@sanity/asset-utils
Options
All
  • Public
  • Public/Protected
  • All
Menu

@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')

License

MIT-licensed. See LICENSE.

Index

Classes

Interfaces

Type aliases

Variables

Functions

Type aliases

SanityAssetIdParts

SanityAssetIdParts: SanityFileAssetIdParts | SanityImageAssetIdParts

SanityAssetObjectStub

SanityAssetObjectStub: SanityFileObjectStub | SanityImageObjectStub

SanityAssetSource

SanityAssetSource: SanityFileSource | SanityImageSource

SanityAssetUrlParts

SanityAssetUrlParts: SanityFileUrlParts | SanityImageUrlParts

SanityFileAsset

SanityFileAsset: SanityAsset & { _type: "sanity.fileAsset"; metadata: {} }

SanityFileSource

SanityFileSource: string | SanityReference | SanityFileAsset | SanityAssetIdStub | SanityAssetUrlStub | SanityAssetPathStub | SanityFileObjectStub

SanityImageAsset

SanityImageAsset: SanityAsset & { _type: "sanity.imageAsset"; metadata: SanityImageMetadata }

SanityImageDimensions

SanityImageDimensions: SanityImageSize & { aspectRatio: number }

SanityImageSource

SanityImageSource: string | SanityReference | SanityImageAsset | SanityAssetIdStub | SanityAssetUrlStub | SanityAssetPathStub | SanityImageObjectStub

SanitySwatchName

SanitySwatchName: "darkMuted" | "darkVibrant" | "dominant" | "lightMuted" | "lightVibrant" | "muted" | "vibrant"

Variables

Const DEFAULT_CROP

DEFAULT_CROP: Readonly<SanityImageCrop> = Object.freeze({left: 0,top: 0,bottom: 0,right: 0,})

Default crop (equals to "whole image")

Const DEFAULT_HOTSPOT

DEFAULT_HOTSPOT: Readonly<SanityImageHotspot> = Object.freeze({x: 0.5,y: 0.5,height: 1,width: 1,})

Default hotspot (equals to horizontal/vertical center, full size of image)

Const tryGetAssetDocumentId

tryGetAssetDocumentId: (Anonymous function) = getForgivingResolver(getAssetDocumentId)

See getAssetDocumentId

inheritfrom

getAssetDocumentId

returns

Returns undefined instead of throwing if a value cannot be resolved

Const tryGetExtension

tryGetExtension: (Anonymous function) = getForgivingResolver(getExtension)

See getExtension

inheritfrom

getExtension

returns

Returns undefined instead of throwing if a value cannot be resolved

Const tryGetFile

tryGetFile: (Anonymous function) = getForgivingResolver(getFile)

See getFile

inheritfrom

getFile

returns

Returns undefined instead of throwing if a value cannot be resolved

Const tryGetFileAsset

tryGetFileAsset: (Anonymous function) = getForgivingResolver(getFileAsset)

See getFileAsset

inheritfrom

getFileAsset

returns

Returns undefined instead of throwing if a value cannot be resolved

Const tryGetIdFromString

tryGetIdFromString: (Anonymous function) = getForgivingResolver(getIdFromString)

See getIdFromString

inheritfrom

getIdFromString

returns

Returns undefined instead of throwing if a value cannot be resolved

Const tryGetImage

tryGetImage: (Anonymous function) = getForgivingResolver(getImage)

See getImage

inheritfrom

getImage

returns

Returns undefined instead of throwing if a value cannot be resolved

Const tryGetImageAsset

tryGetImageAsset: (Anonymous function) = getForgivingResolver(getImageAsset)

See getImageAsset

inheritfrom

getImageAsset

returns

Returns undefined instead of throwing if a value cannot be resolved

Const tryGetImageDimensions

tryGetImageDimensions: (Anonymous function) = getForgivingResolver(getImageDimensions)

See getImageDimensions

inheritfrom

getImageDimensions

returns

Returns undefined instead of throwing if a value cannot be resolved

Const tryGetProject

tryGetProject: (Anonymous function) = getForgivingResolver(getProject)

See getProject

inheritfrom

getProject

returns

Returns undefined instead of throwing if a value cannot be resolved

Const tryGetUrlFilename

tryGetUrlFilename: (Anonymous function) = getForgivingResolver(getUrlFilename)

See getUrlFilename

inheritfrom

getUrlFilename

returns

Returns undefined instead of throwing if a value cannot be resolved

Const tryGetUrlPath

tryGetUrlPath: (Anonymous function) = getForgivingResolver(getUrlPath)

See getUrlPath

inheritfrom

getUrlPath

returns

Returns undefined instead of throwing if a value cannot be resolved

Functions

buildFilePath

buildFileUrl

buildImagePath

buildImageUrl

getAssetDocumentId

  • getAssetDocumentId(src: unknown): string

  • Tries to resolve the asset document ID from any inferrable structure

    throws

    UnresolvableError Throws if passed asset source could not be resolved to an asset document ID

    Parameters

    • src: unknown

      Input source (image/file object, asset, reference, id, url, path)

    Returns string

    The asset document ID

Const getDefaultCrop

Const getDefaultHotspot

getExtension

  • Returns the file extension for a given asset

    throws

    UnresolvableError Throws if passed asset source could not be resolved to an asset ID

    Parameters

    • src: SanityAssetSource

      Input source (file/image object, asset, reference, id, url, path)

    Returns string

    The file extension, if resolvable (no . included)

getFile

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

    throws

    UnresolvableError Throws if passed file source could not be resolved to an asset ID

    Parameters

    Returns ResolvedSanityFile

    File object

getFileAsset

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

    throws

    UnresolvableError Throws if passed file source could not be resolved to an asset ID

    Parameters

    • src: SanityFileSource

      Input source (file object, asset, reference, id, url, path)

    • Optional options: PathBuilderOptions

      Project ID and dataset the file belongs to, along with other options

    Returns SanityFileAsset

    File asset document

getIdFromString

  • getIdFromString(str: string): string

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

    throws

    UnresolvableError Throws if passed image source could not be resolved to an asset ID

    Parameters

    • str: string

      Input string (ID, URL or path)

    Returns string

    string

getImage

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

    throws

    UnresolvableError Throws if passed image source could not be resolved to an asset ID

    Parameters

    Returns ResolvedSanityImage

    Image object

getImageAsset

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

    throws

    UnresolvableError Throws if passed image source could not be resolved to an asset ID

    Parameters

    Returns SanityImageAsset

    Image asset document

getImageDimensions

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

    throws

    UnresolvableError Throws if passed image source could not be resolved to an asset ID

    Parameters

    • src: SanityImageSource

      Input source (image object, asset, reference, id, url, path)

    Returns SanityImageDimensions

    Object with width, height and aspect ratio properties

getProject

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

    throws

    If URL is not a valid Sanity asset URL

    Parameters

    • url: string

      URL to get filename from

    Returns string

    The filename of an URL, if URL matches the CDN URL

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

    throws

    If URL is not a valid Sanity asset URL

    Parameters

    • url: string

      URL to get path name from

    Returns string

    The path of a CDN URL

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

    Parameters

    • originalFilename: string | undefined
    • vanityFilename: string | undefined
    • Optional options: PathBuilderOptions

    Returns string

hasPath

  • hasPath(urlOrPath: string): boolean

  • Checks whether or not the given URL contains an asset path

    Parameters

    • urlOrPath: string

    Returns boolean

    Whether or not it contained an asset path

idFromUrl

  • idFromUrl(url: string): string

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

    Parameters

    • url: string

      A full asset URL to convert

    Returns string

    string

isAssetFilename

  • isAssetFilename(filename: string): boolean

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

    Parameters

    • filename: string

      Filename to validate

    Returns boolean

    Whether or not the filename is an asset filename

isAssetId

  • isAssetId(documentId: string): boolean

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

    Parameters

    • documentId: string

      Document ID to check

    Returns boolean

    Whether or not the given document ID is a Sanity asset document ID (file or image)

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)

    Parameters

    • stub: unknown

      Possible asset id stub

    Returns stub is SanityAssetIdStub

    Whether or not the passed object is an object id stub

isAssetObjectStub

  • isAssetObjectStub(stub: unknown): stub is SanityAssetObjectStub

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

    Parameters

    • stub: unknown

      Possible asset object stub

    Returns stub is SanityAssetObjectStub

    Whether or not the passed object is an object stub

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)

    Parameters

    • stub: unknown

      Possible asset path stub

    Returns stub is SanityAssetPathStub

    Whether or not the passed object is an object path stub

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)

    Parameters

    • stub: unknown

      Possible asset url stub

    Returns stub is SanityAssetUrlStub

    Whether or not the passed object is an object url stub

Const isDefaultCrop

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

    Parameters

    • crop: SanityImageCrop

      The crop to return whether or not is the default crop

    Returns boolean

    True if passed crop matches default, false otherwise

Const isDefaultHotspot

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

    Parameters

    Returns boolean

    True if passed hotspot matches default, false otherwise

isFileAssetFilename

  • isFileAssetFilename(filename: string): boolean

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

    Parameters

    • filename: string

      Filename to validate

    Returns boolean

    Whether or not the filename is a file asset filename

isFileAssetId

  • isFileAssetId(documentId: string): boolean

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

    Parameters

    • documentId: string

      Document ID to check

    Returns boolean

    Whether or not the given document ID is a Sanity file asset document ID

isFileSource

  • isFileSource(src: unknown): src is SanityFileSource

  • Return whether or not the passed source is a file source

    Parameters

    • src: unknown

      Source to check

    Returns src is SanityFileSource

    Whether or not the given source is a file source

isImageAssetFilename

  • isImageAssetFilename(filename: string): boolean

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

    Parameters

    • filename: string

      Filename to validate

    Returns boolean

    Whether or not the filename is an image asset filename

isImageAssetId

  • isImageAssetId(documentId: string): boolean

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

    Parameters

    • documentId: string

      Document ID to check

    Returns boolean

    Whether or not the given document ID is a Sanity image asset document ID

isImageSource

  • isImageSource(src: unknown): src is SanityImageSource

  • Return whether or not the passed source is an image source

    Parameters

    • src: unknown

      Source to check

    Returns src is SanityImageSource

    Whether or not the given source is an image source

isReference

  • isReference(ref: unknown): ref is SanityReference

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

    Parameters

    • ref: unknown

      Possible reference

    Returns ref is SanityReference

    Whether or not the passed object is a reference

isSanityAssetUrl

  • isSanityAssetUrl(url: string): boolean

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

    Parameters

    • url: string

      URL to test

    Returns boolean

    True if url is a valid Sanity asset URL, false otherwise

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

    Parameters

    • src: unknown

      Source to check

    Returns src is SanityFileAsset

    Whether or not the given source is a file asset

isSanityFileUrl

  • isSanityFileUrl(url: string): boolean

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

    Parameters

    • url: string

      URL to test

    Returns boolean

    True if url is a valid Sanity file asset URL, false otherwise

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

    Parameters

    • src: unknown

      Source to check

    Returns src is SanityImageAsset

    Whether or not the given source is a file asset

isSanityImageUrl

  • isSanityImageUrl(url: string): boolean

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

    Parameters

    • url: string

      URL to test

    Returns boolean

    True if url is a valid Sanity image asset URL, false otherwise

isUnresolvableError

  • isUnresolvableError(err: unknown): err is UnresolvableError

  • Checks whether or not an error instance is of type UnresolvableError

    Parameters

    • err: unknown

      Error to check for unresolvable error type

    Returns err is UnresolvableError

    True if the passed error instance appears to be an unresolveable error

isValidFilename

  • isValidFilename(filename: string): boolean

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

    Parameters

    • filename: string

      Filename to check for validity

    Returns boolean

    Whether or not the specified filename is valid

parseAssetFilename

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

    throws

    If image/filename is invalid

    Parameters

    • filename: string

      Filename to parse into named parts

    Returns SanityAssetIdParts

    Object of named properties

parseAssetId

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

    throws

    If document ID is invalid

    Parameters

    • documentId: string

      Document ID to parse into named parts

    Returns SanityAssetIdParts

    Object of named properties

parseAssetUrl

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

    throws

    If URL is invalid or not a Sanity asset URL

    Parameters

    • url: string

      Full URL to parse into named parts

    Returns SanityAssetUrlParts

    Object of named properties

parseFileAssetId

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

    throws

    If document ID invalid

    Parameters

    • documentId: string

      File asset document ID to parse into named parts

    Returns SanityFileAssetIdParts

    Object of named properties

parseFileAssetUrl

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

    throws

    If URL is invalid or not a Sanity file asset URL

    Parameters

    • url: string

      Full URL to parse into named parts

    Returns SanityFileUrlParts

    Object of named properties

parseImageAssetId

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

    throws

    If document ID invalid

    Parameters

    • documentId: string

      Image asset document ID to parse into named parts

    Returns SanityImageAssetIdParts

    Object of named properties

parseImageAssetUrl

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

    throws

    If URL is invalid or not a Sanity image asset URL

    Parameters

    • url: string

      Full URL to parse into named parts

    Returns SanityImageUrlParts

    Object of named properties

tryGetAssetPath

  • Tries to get the asset path from a given asset source

    Parameters

    Returns string | undefined

    A path if resolvable, undefined otherwise