@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
• 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

▸ 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

| Name | Type | Description | | ----- | ------ | ------------------------- | | url | string | URL to get path name from |

Returns: string

Defined in src/paths.ts:159

License

MIT-licensed. See LICENSE.