Package Exports
- @sanity/asset-utils
This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@sanity/asset-utils) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.
Readme
@sanity/asset-utils
Reusable utility functions for dealing with image and file assets in Sanity
Installing
$ npm install @sanity/asset-utilsUsage
// 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
- hasPath
- idFromUrl
- isAssetFilename
- isAssetIdStub
- isAssetObjectStub
- isAssetPathStub
- isAssetUrlStub
- isDefaultCrop
- isDefaultHotspot
- isFileAssetFilename
- isFileSource
- isImageAssetFilename
- isImageSource
- isReference
- isSanityFileAsset
- isUnresolvableError
- isValidFilename
- parseAssetFilename
- parseAssetId
- parseFileAssetId
- parseImageAssetId
- tryGetAssetDocumentId
- tryGetAssetPath
- tryGetExtension
- tryGetFile
- tryGetFileAsset
- tryGetIdFromString
- tryGetImage
- tryGetImageAsset
- tryGetImageDimensions
- tryGetProject
- tryGetUrlFilename
- tryGetUrlPath
buildFilePath
▸ buildFilePath(asset: FileUrlBuilderOptions, project: SanityProjectDetails): string
Builds the base file path from the minimal set of parts required to assemble it
| Name | Type | Description |
|---|---|---|
asset |
FileUrlBuilderOptions | An asset-like shape defining ID, dimensions and extension |
project |
SanityProjectDetails | Project ID and dataset the file belongs to |
Returns: string
Defined in src/paths.ts:57
buildFileUrl
▸ buildFileUrl(asset: FileUrlBuilderOptions, project: SanityProjectDetails): 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 |
SanityProjectDetails | Project ID and dataset the file belongs to |
Returns: string
Defined in src/paths.ts:78
buildImagePath
▸ buildImagePath(asset: ImageUrlBuilderOptions, project: SanityProjectDetails): string
Builds the base image path from the minimal set of parts required to assemble it
| Name | Type | Description |
|---|---|---|
asset |
ImageUrlBuilderOptions | An asset-like shape defining ID, dimensions and extension |
project |
SanityProjectDetails | Project ID and dataset the image belongs to |
Returns: string
Defined in src/paths.ts:21
buildImageUrl
▸ buildImageUrl(asset: ImageUrlBuilderOptions, project: SanityProjectDetails): string
Builds the base image URL from the minimal set of parts required to assemble it
| Name | Type | Description |
|---|---|---|
asset |
ImageUrlBuilderOptions | An asset-like shape defining ID, dimensions and extension |
project |
SanityProjectDetails | Project ID and dataset the image belongs to |
Returns: string
Defined in src/paths.ts:43
getAssetDocumentId
▸ getAssetDocumentId(src: SanityAssetSource): string
Tries to resolve the asset document ID from any inferrable structure
| Name | Type | Description |
|---|---|---|
src |
SanityAssetSource | Input source (image/file object, asset, reference, id, url, path) |
Returns: string
Defined in src/resolve.ts:256
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:73
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:185
getFileAsset
▸ getFileAsset(src: SanityFileSource, project: SanityProjectDetails): 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) |
project |
SanityProjectDetails | Project ID and dataset the file belongs to |
Returns: SanityFileAsset
Defined in src/resolve.ts:210
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:298
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:98
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:132
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:49
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:356
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:163
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:131
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:88
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:341
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:404
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/types.ts:108
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/types.ts:251
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/types.ts:123
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/types.ts:138
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:394
isFileSource
▸ isFileSource(src: SanityAssetSource): src is SanityFileSource
Return whether or not the passed source is a file source
| Name | Type | Description |
|---|---|---|
src |
SanityAssetSource | Source to check |
Returns: src is SanityFileSource
Defined in src/resolve.ts:414
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:384
isImageSource
▸ isImageSource(src: SanityAssetSource): src is SanityImageSource
Return whether or not the passed source is an image source
| Name | Type | Description |
|---|---|---|
src |
SanityAssetSource | Source to check |
Returns: src is SanityImageSource
Defined in src/resolve.ts:425
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/types.ts:93
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/types.ts:169
isUnresolvableError
▸ isUnresolvableError(err: Error): err is UnresolvableError
Checks whether or not an error instance is of type UnresolvableError
| Name | Type | Description |
|---|---|---|
err |
Error | 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:187
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:77
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:22
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:41
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:59
tryGetAssetDocumentId
▸ tryGetAssetDocumentId(src: SanityAssetSource): string
Tries to resolve the asset document ID from any inferrable structure
| Name | Type | Description |
|---|---|---|
src |
SanityAssetSource | Input source (image/file object, asset, reference, id, url, path) |
Returns: string
Defined in src/resolve.ts:286
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:98
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:85
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:197
tryGetFileAsset
▸ tryGetFileAsset(src: SanityFileSource, project: SanityProjectDetails): 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) |
project |
SanityProjectDetails | Project ID and dataset the file belongs to |
Returns: SanityFileAsset
Defined in src/resolve.ts:245
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:333
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:119
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:172
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:62
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:376
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:179
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:152
License
MIT-licensed. See LICENSE.