@sanity/asset-utils NPM

@sanity/asset-utils

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

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

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

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

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

Returns: string

Defined in src/paths.ts:61

buildFileUrl

▸ buildFileUrl(asset: FileUrlBuilderOptions, project: 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
`project`	PathBuilderOptions

Returns: string

Defined in src/paths.ts:85

buildImagePath

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

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

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

Returns: string

Defined in src/paths.ts:20

buildImageUrl

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

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

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

Returns: string

Defined in src/paths.ts:47

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:261

getDefaultCrop

▸ getDefaultCrop(): SanityImageCrop

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

Name	Type

Returns: SanityImageCrop

Defined in src/hotspotCrop.ts:28

getDefaultHotspot

▸ getDefaultHotspot(): SanityImageHotspot

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

Name	Type

Returns: SanityImageHotspot

Defined in src/hotspotCrop.ts:35

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:78

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	Project ID and dataset the file belongs to

Returns: ResolvedSanityFile

Defined in src/resolve.ts:192

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	Project ID and dataset the file belongs to, along with other options

Returns: SanityFileAsset

Defined in src/resolve.ts:217

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:303

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	Project ID and dataset the image belongs to

Returns: ResolvedSanityImage

Defined in src/resolve.ts:103

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	Project ID and dataset the image belongs to

Returns: SanityImageAsset

Defined in src/resolve.ts:137

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:54

getProject

▸ getProject(src: SanityImageSource): SanityProjectDetails

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

Name	Type
`src`	SanityImageSource

Returns: SanityProjectDetails

Defined in src/resolve.ts:361

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:170

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:138

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
`originalFilename`	string \| undefined
`vanityFilename`	string \| undefined
`options`	PathBuilderOptions

Returns: string

Defined in src/paths.ts:201

hasPath

▸ hasPath(urlOrPath: string): boolean

Checks whether or not the given URL contains an asset path

Name	Type
`urlOrPath`	string

Returns: boolean

Defined in src/paths.ts:95

idFromUrl

▸ idFromUrl(url: string): string

Converts from a full asset URL to just the asset document ID

Name	Type	Description
`url`	string	A full asset URL to convert

Returns: string

Defined in src/resolve.ts:346

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:409

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:104

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:30

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:114

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:41

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:52

isDefaultCrop

▸ isDefaultCrop(crop: SanityImageCrop): boolean

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

Name	Type
`crop`	SanityImageCrop

Returns: boolean

Defined in src/hotspotCrop.ts:43

isDefaultHotspot

▸ isDefaultHotspot(hotspot: SanityImageHotspot): boolean

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

Name	Type
`hotspot`	SanityImageHotspot

Returns: boolean

Defined in src/hotspotCrop.ts:63

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:399

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:94

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:419

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:389

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:84

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:430

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:19

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:9

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:63

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:29

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:74

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:19

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/utils.ts:36

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:194

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:90

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:35

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:113

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:54

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:160

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:72

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:143

tryGetAssetDocumentId

▸ tryGetAssetDocumentId(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:291

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:105

tryGetExtension

▸ tryGetExtension(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:90

tryGetFile

▸ tryGetFile(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	Project ID and dataset the file belongs to

Returns: ResolvedSanityFile

Defined in src/resolve.ts:204

tryGetFileAsset

▸ tryGetFileAsset(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	Project ID and dataset the file belongs to, along with other options

Returns: SanityFileAsset

Defined in src/resolve.ts:250

tryGetIdFromString

▸ tryGetIdFromString(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:338

tryGetImage

▸ tryGetImage(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	Project ID and dataset the image belongs to

Returns: ResolvedSanityImage

Defined in src/resolve.ts:124

tryGetImageAsset

▸ tryGetImageAsset(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	Project ID and dataset the image belongs to

Returns: SanityImageAsset

Defined in src/resolve.ts:179

tryGetImageDimensions

▸ tryGetImageDimensions(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:67

tryGetProject

▸ tryGetProject(src: SanityImageSource): SanityProjectDetails

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

Name	Type
`src`	SanityImageSource

Returns: SanityProjectDetails

Defined in src/resolve.ts:381

tryGetUrlFilename

▸ tryGetUrlFilename(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:186

tryGetUrlPath

▸ tryGetUrlPath(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