@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

Functions

buildFilePath

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

    Parameters

    Returns string

    string

buildFileUrl

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

    Parameters

    Returns string

    string

buildImagePath

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

    Parameters

    Returns string

    string

buildImageUrl

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

    Parameters

    Returns string

    string

getAssetDocumentId

  • 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: SanityAssetSource

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

    Returns string

    The asset document ID

getDefaultCrop

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

    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

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

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

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

isFileSource

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

    Parameters

    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

isImageSource

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

    Parameters

    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

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

isUnresolvableError

  • isUnresolvableError(err: Error): err is UnresolvableError
  • Checks whether or not an error instance is of type UnresolvableError

    Parameters

    • err: Error

      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

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

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

tryGetAssetPath

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

    Parameters

    Returns string | undefined

    A path if resolvable, undefined otherwise

tryGetAssetDocumentId

inheritfrom

getAssetDocumentId

returns

Returns undefined instead of throwing if a value cannot be resolved

tryGetExtension

inheritfrom

getExtension

returns

Returns undefined instead of throwing if a value cannot be resolved

tryGetFile

See getFile

inheritfrom

getFile

returns

Returns undefined instead of throwing if a value cannot be resolved

tryGetFileAsset

inheritfrom

getFileAsset

returns

Returns undefined instead of throwing if a value cannot be resolved

tryGetIdFromString

  • getIdFromString(str: string): string | undefined
inheritfrom

getIdFromString

returns

Returns undefined instead of throwing if a value cannot be resolved

tryGetImage

See getImage

inheritfrom

getImage

returns

Returns undefined instead of throwing if a value cannot be resolved

tryGetImageAsset

inheritfrom

getImageAsset

returns

Returns undefined instead of throwing if a value cannot be resolved

tryGetImageDimensions

inheritfrom

getImageDimensions

returns

Returns undefined instead of throwing if a value cannot be resolved

tryGetProject

inheritfrom

getProject

returns

Returns undefined instead of throwing if a value cannot be resolved

tryGetUrlFilename

  • getUrlFilename(url: string): string | undefined
inheritfrom

getUrlFilename

returns

Returns undefined instead of throwing if a value cannot be resolved

tryGetUrlPath

  • getUrlPath(url: string): string | undefined
inheritfrom

getUrlPath

returns

Returns undefined instead of throwing if a value cannot be resolved

Type aliases

SanityAssetIdParts

SanityAssetObjectStub

SanityAssetSource

SanityAssetSource: SanityFileSource | SanityImageSource

SanityFileAsset

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

SanityFileSource

SanityImageAsset

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

SanityImageAssetIdParts

SanityImageAssetIdParts: { assetId: string; extension: string; height: number; type: "image"; width: number }

Type declaration

  • assetId: string
  • extension: string
  • height: number
  • type: "image"
  • width: number

SanityImageDimensions

SanityImageDimensions: SanityImageSize & { aspectRatio: number }

SanityImageSource

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)