README.md

@sanity/asset-utils

Reusable utility functions for dealing with image and file assets in Sanity.

Important

This package does not resolve any information from the Sanity APIs - it does no asynchronous operations and only has the information that you pass it. You cannot, for instance, get the LQIP, BlurHash, image palette and similar information without requesting it from the Sanity API.

Installing

$ npm install @sanity/asset-utils

Usage

// ESM / TypeScript
import {someUtilityFunction} from '@sanity/asset-utils'

// CommonJS
const {someUtilityFunction} = require('@sanity/asset-utils')

Documentation

An HTML version is also available, which also includes interface definitions, constants and more.

Functions

• buildFilePath
• buildFileUrl
• buildImagePath
• buildImageUrl
• getAssetDocumentId
• getAssetUrlType
• getDefaultCrop
• getDefaultHotspot
• getExtension
• getFile
• getFileAsset
• getIdFromString
• getImage
• getImageAsset
• getImageDimensions
• getProject
• getUrlFilename
• getUrlPath
• getVanityStub
• isAssetFilename
• isAssetId
• isAssetIdStub
• isAssetObjectStub
• isAssetPathStub
• isAssetUrlStub
• isDefaultCrop
• isDefaultHotspot
• isFileAssetFilename
• isFileAssetId
• isFileSource
• isImageAssetFilename
• isImageAssetId
• isImageSource
• isReference
• isSanityAssetUrl
• isSanityFileAsset
• isSanityFileUrl
• isSanityImageAsset
• isSanityImageUrl
• isUnresolvableError
• isValidFilename
• parseAssetFilename
• parseAssetId
• parseAssetUrl
• parseFileAssetId
• parseFileAssetUrl
• parseImageAssetId
• parseImageAssetUrl
• tryGetAssetDocumentId
• tryGetAssetPath
• tryGetExtension
• tryGetFile
• tryGetFileAsset
• tryGetIdFromString
• tryGetImage
• tryGetImageAsset
• tryGetImageDimensions
• tryGetProject
• tryGetUrlFilename
• tryGetUrlPath

buildFilePath

▸ buildFilePath(asset: SanityFileUrlParts | FileUrlBuilderOptions, options?: PathBuilderOptions): string

Builds the base file path from the minimal set of parts required to assemble it

Name	Type	Description
asset	SanityFileUrlParts | FileUrlBuilderOptions	An asset-like shape defining ID, dimensions and extension
options	PathBuilderOptions	(Optional) Project ID and dataset the file belongs to, along with other options

Returns: string

Defined in src/paths.ts:73

buildFileUrl

▸ buildFileUrl(asset: FileUrlBuilderOptions, options?: PathBuilderOptions): string

Builds the base file URL from the minimal set of parts required to assemble it

Name	Type	Description
asset	FileUrlBuilderOptions	An asset-like shape defining ID and extension
options	PathBuilderOptions	(Optional) Project ID and dataset the file belongs to, along with other options

Returns: string

Defined in src/paths.ts:98

buildImagePath

▸ buildImagePath(asset: SanityImageUrlParts | ImageUrlBuilderOptions, options?: PathBuilderOptions): string

Builds the base image path from the minimal set of parts required to assemble it

Name	Type	Description
asset	SanityImageUrlParts | ImageUrlBuilderOptions	An asset-like shape defining ID, dimensions and extension
options	PathBuilderOptions	(Optional) Project ID and dataset the image belongs to, along with other options

Returns: string

Defined in src/paths.ts:29

buildImageUrl

▸ buildImageUrl(asset: SanityImageUrlParts | ImageUrlBuilderOptions, options?: PathBuilderOptions): string

Builds the base image URL from the minimal set of parts required to assemble it

Name	Type	Description
asset	SanityImageUrlParts | ImageUrlBuilderOptions	An asset-like shape defining ID, dimensions and extension
options	PathBuilderOptions	(Optional) Project ID and dataset the image belongs to

Returns: string

Defined in src/paths.ts:57

getAssetDocumentId

▸ getAssetDocumentId(src: unknown): string

Tries to resolve the asset document ID from any inferrable structure

Name	Type	Description
src	unknown	Input source (image/file object, asset, reference, id, url, path)

Returns: string

Defined in src/resolve.ts:264

getAssetUrlType

▸ getAssetUrlType(url: string): "image" | "file" | false

Validates that a given URL is a Sanity asset URL, and returns the asset type if valid.

Name	Type	Description
url	string	URL to extract asset type from

Returns: "image" | "file" | false

Defined in src/parse.ts:184

getDefaultCrop

▸ getDefaultCrop(): SanityImageCrop

Returns cloned version of the default crop (prevents accidental mutations)

Returns: SanityImageCrop

Defined in src/hotspotCrop.ts:33

getDefaultHotspot

▸ getDefaultHotspot(): SanityImageHotspot

Returns cloned version of the default hotspot (prevents accidental mutations)

Returns: SanityImageHotspot

Defined in src/hotspotCrop.ts:41

getExtension

▸ getExtension(src: SanityAssetSource): string

Returns the file extension for a given asset

Name	Type	Description
src	SanityAssetSource	Input source (file/image object, asset, reference, id, url, path)

Returns: string

Defined in src/resolve.ts:81

getFile

▸ getFile(src: SanityFileSource, project?: SanityProjectDetails): ResolvedSanityFile

Tries to resolve an file object with as much information as possible, from any inferrable structure (id, url, path, file object etc)

Name	Type	Description
src	SanityFileSource	Input source (file object, asset, reference, id, url, path)
project	SanityProjectDetails	(Optional) Project ID and dataset the file belongs to

Returns: ResolvedSanityFile

Defined in src/resolve.ts:195

getFileAsset

▸ getFileAsset(src: SanityFileSource, options?: PathBuilderOptions): SanityFileAsset

Tries to resolve a (partial) file asset document with as much information as possible, from any inferrable structure (id, url, path, file object etc)

Name	Type	Description
src	SanityFileSource	Input source (file object, asset, reference, id, url, path)
options	PathBuilderOptions	(Optional) Project ID and dataset the file belongs to, along with other options

Returns: SanityFileAsset

Defined in src/resolve.ts:220

getIdFromString

▸ getIdFromString(str: string): string

Tries to cooerce a string (ID, URL or path) to an image asset ID

Name	Type	Description
str	string	Input string (ID, URL or path)

Returns: string

Defined in src/resolve.ts:306

getImage

▸ getImage(src: SanityImageSource, project?: SanityProjectDetails): ResolvedSanityImage

Tries to resolve an image object with as much information as possible, from any inferrable structure (id, url, path, image object etc)

Name	Type	Description
src	SanityImageSource	Input source (image object, asset, reference, id, url, path)
project	SanityProjectDetails	(Optional) Project ID and dataset the image belongs to

Returns: ResolvedSanityImage

Defined in src/resolve.ts:106

getImageAsset

▸ getImageAsset(src: SanityImageSource, project?: SanityProjectDetails): SanityImageAsset

Tries to resolve a (partial) image asset document with as much information as possible, from any inferrable structure (id, url, path, image object etc)

Name	Type	Description
src	SanityImageSource	Input source (image object, asset, reference, id, url, path)
project	SanityProjectDetails	(Optional) Project ID and dataset the image belongs to

Returns: SanityImageAsset

Defined in src/resolve.ts:140

getImageDimensions

▸ getImageDimensions(src: SanityImageSource): SanityImageDimensions

Returns the width, height and aspect ratio of a passed image asset, from any inferrable structure (id, url, path, asset document, image object etc)

Name	Type	Description
src	SanityImageSource	Input source (image object, asset, reference, id, url, path)

Returns: SanityImageDimensions

Defined in src/resolve.ts:57

getProject

▸ getProject(src: SanityImageSource): SanityProjectDetails

Resolves project ID and dataset the image belongs to, based on full URL or path

Name	Type	Description
src	SanityImageSource	Image URL or path

Returns: SanityProjectDetails

Defined in src/resolve.ts:368

getUrlFilename

▸ getUrlFilename(url: string): string

Strips the CDN URL, path and query params from a URL, eg: https://cdn.sanity.io/images/project/dataset/filename-200x200.jpg?foo=bar → filename-200x200.jpg

Name	Type	Description
url	string	URL to get filename from

Returns: string

Defined in src/paths.ts:185

getUrlPath

▸ getUrlPath(url: string): string

Strips the CDN URL and query params from a URL, eg: https://cdn.sanity.io/images/project/dataset/filename-200x200.jpg?foo=bar → images/project/dataset/filename-200x200.jpg

Name	Type	Description
url	string	URL to get path name from

Returns: string

Defined in src/paths.ts:155

getVanityStub

▸ getVanityStub(originalFilename: string | undefined, vanityFilename: string | undefined, options?: PathBuilderOptions): string

Get the "path stub" at the end of the path, if the user hasn't explicitly opted out of this behavior

Name	Type	Description
originalFilename	string | undefined	The original filename of the asset
vanityFilename	string | undefined	The vanity filename of the asset
options	PathBuilderOptions	(Optional) Options to control the behavior of the path builder

Returns: string

Defined in src/paths.ts:222

isAssetFilename

▸ isAssetFilename(filename: string): boolean

Returns whether or not the passed filename is a valid file or image asset filename

Name	Type	Description
filename	string	Filename to validate

Returns: boolean

Defined in src/resolve.ts:418

isAssetId

▸ isAssetId(documentId: string): boolean

Checks whether or not the given document ID is a valid Sanity asset document ID (file or image)

Name	Type	Description
documentId	string	Document ID to check

Returns: boolean

Defined in src/asserters.ts:114

isAssetIdStub

▸ isAssetIdStub(stub: unknown): stub is SanityAssetIdStub

Checks whether or not the given source is an asset ID stub (an object containing an _id property)

Name	Type	Description
stub	unknown	Possible asset id stub

Returns: stub is SanityAssetIdStub

Defined in src/asserters.ts:33

isAssetObjectStub

▸ isAssetObjectStub(stub: unknown): stub is SanityAssetObjectStub

Checks whether or not the given source is an asset object stub

Name	Type	Description
stub	unknown	Possible asset object stub

Returns: stub is SanityAssetObjectStub

Defined in src/asserters.ts:125

isAssetPathStub

▸ isAssetPathStub(stub: unknown): stub is SanityAssetPathStub

Checks whether or not the given source is an asset path stub (an object containing a path property)

Name	Type	Description
stub	unknown	Possible asset path stub

Returns: stub is SanityAssetPathStub

Defined in src/asserters.ts:45

isAssetUrlStub

▸ isAssetUrlStub(stub: unknown): stub is SanityAssetUrlStub

Checks whether or not the given source is an asset URL stub (an object containing a url property)

Name	Type	Description
stub	unknown	Possible asset url stub

Returns: stub is SanityAssetUrlStub

Defined in src/asserters.ts:57

isDefaultCrop

▸ isDefaultCrop(crop: SanityImageCrop): boolean

Returns whether or not the passed crop has the default values for a crop region

Name	Type	Description
crop	SanityImageCrop	The crop to return whether or not is the default crop

Returns: boolean

Defined in src/hotspotCrop.ts:50

isDefaultHotspot

▸ isDefaultHotspot(hotspot: SanityImageHotspot): boolean

Returns whether or not the passed hotspot has the default values for a hotspot region

Name	Type	Description
hotspot	SanityImageHotspot	The hotspot to return whether or not is the default hotspot

Returns: boolean

Defined in src/hotspotCrop.ts:71

isFileAssetFilename

▸ isFileAssetFilename(filename: string): boolean

Returns whether or not the passed filename is a valid file asset filename

Name	Type	Description
filename	string	Filename to validate

Returns: boolean

Defined in src/resolve.ts:407

isFileAssetId

▸ isFileAssetId(documentId: string): boolean

Checks whether or not the given document ID is a valid Sanity file asset document ID

Name	Type	Description
documentId	string	Document ID to check

Returns: boolean

Defined in src/asserters.ts:103

isFileSource

▸ isFileSource(src: unknown): src is SanityFileSource

Return whether or not the passed source is a file source

Name	Type	Description
src	unknown	Source to check

Returns: src is SanityFileSource

Defined in src/resolve.ts:429

isImageAssetFilename

▸ isImageAssetFilename(filename: string): boolean

Returns whether or not the passed filename is a valid image asset filename

Name	Type	Description
filename	string	Filename to validate

Returns: boolean

Defined in src/resolve.ts:396

isImageAssetId

▸ isImageAssetId(documentId: string): boolean

Checks whether or not the given document ID is a valid Sanity image asset document ID

Name	Type	Description
documentId	string	Document ID to check

Returns: boolean

Defined in src/asserters.ts:92

isImageSource

▸ isImageSource(src: unknown): src is SanityImageSource

Return whether or not the passed source is an image source

Name	Type	Description
src	unknown	Source to check

Returns: src is SanityImageSource

Defined in src/resolve.ts:441

isReference

▸ isReference(ref: unknown): ref is SanityReference

Checks whether or not the given source is a Sanity reference (an object containing _ref string key)

Name	Type	Description
ref	unknown	Possible reference

Returns: ref is SanityReference

Defined in src/asserters.ts:21

isSanityAssetUrl

▸ isSanityAssetUrl(url: string): boolean

Checks whether or not a given URL is a valid Sanity asset URL

Name	Type	Description
url	string	URL to test

Returns: boolean

Defined in src/urls.ts:10

isSanityFileAsset

▸ isSanityFileAsset(src: unknown): src is SanityFileAsset

Checks whether or not the given source is a (partial) sanity file asset document. Only checks the _type property, all other properties may be missing

Name	Type	Description
src	unknown	Source to check

Returns: src is SanityFileAsset

Defined in src/asserters.ts:69

isSanityFileUrl

▸ isSanityFileUrl(url: string): boolean

Checks whether or not a given URL is a valid Sanity file asset URL

Name	Type	Description
url	string	URL to test

Returns: boolean

Defined in src/urls.ts:32

isSanityImageAsset

▸ isSanityImageAsset(src: unknown): src is SanityImageAsset

Checks whether or not the given source is a (partial) sanity image asset document. Only checks the _type property, all other properties may be missing

Name	Type	Description
src	unknown	Source to check

Returns: src is SanityImageAsset

Defined in src/asserters.ts:81

isSanityImageUrl

▸ isSanityImageUrl(url: string): boolean

Checks whether or not a given URL is a valid Sanity image asset URL

Name	Type	Description
url	string	URL to test

Returns: boolean

Defined in src/urls.ts:21

isUnresolvableError

▸ isUnresolvableError(err: unknown): err is UnresolvableError

Checks whether or not an error instance is of type UnresolvableError

Name	Type	Description
err	unknown	Error to check for unresolvable error type

Returns: err is UnresolvableError

Defined in src/errors.ts:29

isValidFilename

▸ isValidFilename(filename: string): boolean

Checks whether or not a given filename matches the expected Sanity asset filename pattern

Name	Type	Description
filename	string	Filename to check for validity

Returns: boolean

Defined in src/paths.ts:209

parseAssetFilename

▸ parseAssetFilename(filename: string): SanityAssetIdParts

Parses a Sanity asset filename into individual parts (type, id, extension, width, height)

Name	Type	Description
filename	string	Filename to parse into named parts

Returns: SanityAssetIdParts

Defined in src/parse.ts:95

parseAssetId

▸ parseAssetId(documentId: string): SanityAssetIdParts

Parses a Sanity asset document ID into individual parts (type, id, extension, width/height etc)

Name	Type	Description
documentId	string	Document ID to parse into named parts

Returns: SanityAssetIdParts

Defined in src/parse.ts:37

parseAssetUrl

▸ parseAssetUrl(url: string): SanityAssetUrlParts

Parses a full Sanity asset URL into individual parts (type, project ID, dataset, id, extension, width, height)

Name	Type	Description
url	string	Full URL to parse into named parts

Returns: SanityAssetUrlParts

Defined in src/parse.ts:119

parseFileAssetId

▸ parseFileAssetId(documentId: string): SanityFileAssetIdParts

Parses a Sanity file asset document ID into individual parts (type, id, extension)

Name	Type	Description
documentId	string	File asset document ID to parse into named parts

Returns: SanityFileAssetIdParts

Defined in src/parse.ts:57

parseFileAssetUrl

▸ parseFileAssetUrl(url: string): SanityFileUrlParts

Parses a full Sanity file asset URL into individual parts (type, project ID, dataset, id, extension, width, height)

Name	Type	Description
url	string	Full URL to parse into named parts

Returns: SanityFileUrlParts

Defined in src/parse.ts:168

parseImageAssetId

▸ parseImageAssetId(documentId: string): SanityImageAssetIdParts

Parses a Sanity image asset document ID into individual parts (type, id, extension, width, height)

Name	Type	Description
documentId	string	Image asset document ID to parse into named parts

Returns: SanityImageAssetIdParts

Defined in src/parse.ts:76

parseImageAssetUrl

▸ parseImageAssetUrl(url: string): SanityImageUrlParts

Parses a full Sanity image asset URL into individual parts (type, project ID, dataset, id, extension, width, height)

Name	Type	Description
url	string	Full URL to parse into named parts

Returns: SanityImageUrlParts

Defined in src/parse.ts:150

tryGetAssetDocumentId

▸ tryGetAssetDocumentId(src: unknown): string | undefined

Tries to resolve the asset document ID from any inferrable structure

Name	Type	Description
src	unknown	Input source (image/file object, asset, reference, id, url, path)

Returns: string | undefined

Defined in src/resolve.ts:293

tryGetAssetPath

▸ tryGetAssetPath(src: SanityAssetSource): string | undefined

Tries to get the asset path from a given asset source

Name	Type	Description
src	SanityAssetSource	The source image to infer an asset path from

Returns: string | undefined

Defined in src/paths.ts:121

tryGetExtension

▸ tryGetExtension(src: SanityAssetSource): string | undefined

Returns the file extension for a given asset

Name	Type	Description
src	SanityAssetSource	Input source (file/image object, asset, reference, id, url, path)

Returns: string | undefined

Defined in src/resolve.ts:92

tryGetFile

▸ tryGetFile(src: SanityFileSource, project?: SanityProjectDetails): ResolvedSanityFile | undefined

Tries to resolve an file object with as much information as possible, from any inferrable structure (id, url, path, file object etc)

Name	Type	Description
src	SanityFileSource	Input source (file object, asset, reference, id, url, path)
project	SanityProjectDetails	(Optional) Project ID and dataset the file belongs to

Returns: ResolvedSanityFile | undefined

Defined in src/resolve.ts:206

tryGetFileAsset

▸ tryGetFileAsset(src: SanityFileSource, options?: PathBuilderOptions): SanityFileAsset | undefined

Tries to resolve a (partial) file asset document with as much information as possible, from any inferrable structure (id, url, path, file object etc)

Name	Type	Description
src	SanityFileSource	Input source (file object, asset, reference, id, url, path)
options	PathBuilderOptions	(Optional) Project ID and dataset the file belongs to, along with other options

Returns: SanityFileAsset | undefined

Defined in src/resolve.ts:252

tryGetIdFromString

▸ tryGetIdFromString(str: string): string | undefined

Tries to cooerce a string (ID, URL or path) to an image asset ID

Name	Type	Description
str	string	Input string (ID, URL or path)

Returns: string | undefined

Defined in src/resolve.ts:343

tryGetImage

▸ tryGetImage(src: SanityImageSource, project?: SanityProjectDetails): ResolvedSanityImage | undefined

Tries to resolve an image object with as much information as possible, from any inferrable structure (id, url, path, image object etc)

Name	Type	Description
src	SanityImageSource	Input source (image object, asset, reference, id, url, path)
project	SanityProjectDetails	(Optional) Project ID and dataset the image belongs to

Returns: ResolvedSanityImage | undefined

Defined in src/resolve.ts:126

tryGetImageAsset

▸ tryGetImageAsset(src: SanityImageSource, project?: SanityProjectDetails): SanityImageAsset | undefined

Tries to resolve a (partial) image asset document with as much information as possible, from any inferrable structure (id, url, path, image object etc)

Name	Type	Description
src	SanityImageSource	Input source (image object, asset, reference, id, url, path)
project	SanityProjectDetails	(Optional) Project ID and dataset the image belongs to

Returns: SanityImageAsset | undefined

Defined in src/resolve.ts:181

tryGetImageDimensions

▸ tryGetImageDimensions(src: SanityImageSource): SanityImageDimensions | undefined

Returns the width, height and aspect ratio of a passed image asset, from any inferrable structure (id, url, path, asset document, image object etc)

Name	Type	Description
src	SanityImageSource	Input source (image object, asset, reference, id, url, path)

Returns: SanityImageDimensions | undefined

Defined in src/resolve.ts:69

tryGetProject

▸ tryGetProject(src: SanityImageSource): SanityProjectDetails | undefined

Resolves project ID and dataset the image belongs to, based on full URL or path

Name	Type	Description
src	SanityImageSource	Image URL or path

Returns: SanityProjectDetails | undefined

Defined in src/resolve.ts:387

tryGetUrlFilename

▸ tryGetUrlFilename(url: string): string | undefined

Strips the CDN URL, path and query params from a URL, eg: https://cdn.sanity.io/images/project/dataset/filename-200x200.jpg?foo=bar → filename-200x200.jpg

Name	Type	Description
url	string	URL to get filename from

Returns: string | undefined

Defined in src/paths.ts:200

tryGetUrlPath

▸ tryGetUrlPath(url: string): string | undefined

Strips the CDN URL and query params from a URL, eg: https://cdn.sanity.io/images/project/dataset/filename-200x200.jpg?foo=bar → images/project/dataset/filename-200x200.jpg

Name	Type	Description
url	string	URL to get path name from

Returns: string | undefined

Defined in src/paths.ts:173

License

MIT-licensed. See LICENSE.