Reusable utility functions for dealing with image and file assets in Sanity
$ npm install @sanity/asset-utils
// ESM / TypeScript
import {someUtilityFunction} from '@sanity/asset-utils'
// CommonJS
const {someUtilityFunction} = require('@sanity/asset-utils')
An HTML version is also available, which also includes interface definitions, constants and more.
- buildFilePath
- buildFileUrl
- buildImagePath
- buildImageUrl
- getAssetDocumentId
- getDefaultCrop
- getDefaultHotspot
- getExtension
- getFile
- getFileAsset
- getIdFromString
- getImage
- getImageAsset
- getImageDimensions
- getProject
- getUrlFilename
- getUrlPath
- getVanityStub
- hasPath
- idFromUrl
- 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(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(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(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(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(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(): SanityImageCrop
Returns cloned version of the default crop (prevents accidental mutations)
Name | Type |
---|
Returns: SanityImageCrop
Defined in src/hotspotCrop.ts:28
▸ getDefaultHotspot(): SanityImageHotspot
Returns cloned version of the default hotspot (prevents accidental mutations)
Name | Type |
---|
Returns: SanityImageHotspot
Defined in src/hotspotCrop.ts:35
▸ 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(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(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(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(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(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(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(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(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(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(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(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(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(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(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(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(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(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(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(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(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(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(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(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(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(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(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(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(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(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(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(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(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(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(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(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(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(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(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(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(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(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(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(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(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(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(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(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(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(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(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(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(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(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:159
MIT-licensed. See LICENSE.