JavaScript Helpers

The StudioCMS Storage API provides several JavaScript helpers to facilitate interaction with storage backends. These helpers simplify tasks such as resolving storage identifiers and keys, as well as providing type definitions for better type safety and code completion.

JavaScript helpers

import {
    
function resolveStorageIdentifier(identifier: StorageFileIdentifier, { baseUrl, verbose, timeoutMs }: ResolveUrlOptions): Promise<string>
Resolves a storage-file:// identifier to its actual URL by calling the StudioCMS storage manager API.
@param ― identifier - The storage-file:// identifier to resolve.
@param ― options - Options including the base URL of the StudioCMS instance and verbosity flag.
@returns ― A promise that resolves to the actual URL or the original identifier if resolution fails.
resolveStorageIdentifier,
    
function resolveStorageKey(key: string, options: ResolveUrlOptions): Promise<string>
Resolves a storage key to its actual URL by calling the StudioCMS storage manager API.
@param ― key - The storage key to resolve.
@param ― opts - Options including the base URL of the StudioCMS instance and verbosity flag.
@returns ― A promise that resolves to the actual URL or the original identifier if resolution fails.
resolveStorageKey,
} from 'studiocms/storage-api';

const 
const storageIdentifier: string
storageIdentifier = await 
function resolveStorageIdentifier(identifier: StorageFileIdentifier, { baseUrl, verbose, timeoutMs }: ResolveUrlOptions): Promise<string>
Resolves a storage-file:// identifier to its actual URL by calling the StudioCMS storage manager API.
@param ― identifier - The storage-file:// identifier to resolve.
@param ― options - Options including the base URL of the StudioCMS instance and verbosity flag.
@returns ― A promise that resolves to the actual URL or the original identifier if resolution fails.
resolveStorageIdentifier('storage-file://my-file.txt', {
    
ResolveUrlOptions.baseUrl: string | URL
baseUrl: 'https://example.com/', // Use the value of `site` from "astro:config/server"
});

const 
const storageKey: string
storageKey = await 
function resolveStorageKey(key: string, options: ResolveUrlOptions): Promise<string>
Resolves a storage key to its actual URL by calling the StudioCMS storage manager API.
@param ― key - The storage key to resolve.
@param ― opts - Options including the base URL of the StudioCMS instance and verbosity flag.
@returns ― A promise that resolves to the actual URL or the original identifier if resolution fails.
resolveStorageKey('my-file.txt', {
    
ResolveUrlOptions.baseUrl: string | URL
baseUrl: 'https://example.com/', // Use the value of `site` from "astro:config/server"
});

JavaScript Types

import type {
    
type ContextJsonBody = ContextBodyResolveUrl | ContextBodyPublicUrl | ContextBodyUpload | ContextBodyDelete | ContextBodyRename | ContextBodyCleanup | ContextBodyMappings | ContextBodyTest | ContextBodyList | ContextBodyDownload
Context JSON Body type.
This type defines the possible structures for the JSON body
in the context of storage manager API requests.
ContextJsonBody,
    
type AuthorizationType = "locals" | "headers"
Authorization Type.
This type defines the possible authorization types
that can be used in storage manager API requests.
AuthorizationType,
    
type ParsedContext = {
    getJson: () => Promise<ContextJsonBody>;
    getArrayBuffer: () => Promise<ArrayBuffer>;
    getHeader: (name: string) => string | null;
    isAuthorized: (type?: AuthorizationType) => Promise<boolean>;
}
Parsed Context type.
This type defines the structure of a parsed context,
including methods to retrieve JSON body, array buffer,
get headers, and check authorization.
ParsedContext,
    
(alias) interface UrlMetadata
import UrlMetadata
URL Metadata interface.
This interface defines the structure for URL metadata,
including the URL itself, permanence status, and optional expiration time.
UrlMetadata,
    
(alias) interface UrlMapping
import UrlMapping
URL Mapping interface.
This interface extends UrlMetadata to include additional properties
for identifying and tracking URL mappings.
UrlMapping,
    
type ContextHandler = (context: ParsedContext) => Promise<{
    data: unknown;
    status: number;
}>
Context Handler type.
This type defines a function that takes a ParsedContext
and returns a Promise resolving to an object containing data and status.
ContextHandler,
    
type ContextHandlerFn<C, R> = (context: C) => Promise<R>
Context Handler Function type.
This type defines a function that takes a context of type C
and returns a Promise resolving to a response of type R.
ContextHandlerFn,
    
interface ContextDriverDefinition<C, R>
Context Driver Definition interface.
This interface defines the structure and methods for a context driver,
including parsing the context, building responses, and handling endpoints.
ContextDriverDefinition,
    
type StorageAPIEndpointFn<C, R> = (context: C) => Promise<R>
Storage API Endpoint Function type.
This type defines a function that takes a context of type C
and returns a Promise resolving to a response of type R.
StorageAPIEndpointFn,
    
interface StorageApiBuilderDefinition<C, R>
Storage API Builder Definition interface.
This interface defines the structure and methods for building storage API endpoints,
including handling POST and PUT requests.
StorageApiBuilderDefinition,
    
(alias) interface UrlMappingDatabaseDefinition
import UrlMappingDatabaseDefinition
URL Mapping Database Definition interface.
This interface defines the structure and methods for the URL Mapping Database,
which is responsible for storing and retrieving URL mappings.
UrlMappingDatabaseDefinition,
    
(alias) interface UrlMappingServiceDefinition
import UrlMappingServiceDefinition
URL Mapping Service Definition interface.
This interface defines the structure and methods for the URL Mapping Service,
which manages the mapping between storage file identifiers and their corresponding URLs.
UrlMappingServiceDefinition,
    
interface APICoreDefinition<C, R>
API Core Definition interface.
This interface defines the structure and methods for the core API of the Storage Manager,
including access to the context driver, URL mapping service, and storage API builder.
APICoreDefinition
} from 'studiocms/storage-api';