@yoot/yoot/dist/core/adapter.d.ts

The core library for yoot, providing a CDN-agnostic, chainable API for image URL transformations and adapter integration.

import type { Directives, YootState, PrimeStateInput } from './yoot.ts';
export { createAdapter, defineAdapter, passThroughAdapter, registerAdapters };
export type { Adapter, AdapterOptions, GenerateUrlInput };
export { getAdapter as _getAdapter };
/**
 * Registers one or more adapters for image transformation.
 *
 * @remarks This function validates each adapter's options,
 * freezes the adapter objects, and registers them in the adapter store.
 *
 * @public
 * @param adapters - One or more adapters to register.
 * @returns void
 * @throws Will throw if any adapter does not implement the required interface.
 *
 * @example
 * ```ts
 * registerAdapters(adapterOne, adapterTwo);
 * ```
 */
declare const registerAdapters: RegisterAdaptersFunction;
/**
 * Type definition for the function that registers adapters.
 * @public
 */
type RegisterAdaptersFunction = (...adapters: Adapter[]) => void;
/**
 * Defines a new adapter for image URL transformation.
 *
 * @remarks Use this as a helper to satisfy TypeScript typings to create adapter objects before registration.
 *
 * @public
 * @param options - Configuration for the adapter.
 *   - `supports` - A function to determine whether this adapter supports a given URL.
 *   - `generateUrl` - A function to transform the image URL.
 *   - `primeState` - (Optional) A function to modify the input before transformation.
 * @returns An adapter object implementing `supports`, `generateUrl`, and optionally `primeState`.
 *
 * @example
 * ```ts
 * const myAdapter = defineAdapter({
 *   supports: (url) => url.hostname === 'cdn.example.com',
 *   generateUrl: ({src, directives}) => {
 *     const url = new URL(src);
 *     url.searchParams.set('w', String(directives.width));
 *     return url.href;
 *   },
 * });
 * ```
 */
declare const defineAdapter: (options: AdapterOptions) => Adapter;
/**
 * @deprecated Use `defineAdapter` instead.
 * @remarks  This alias exists for backward compatibility.
 */
declare const createAdapter: (options: AdapterOptions) => Adapter;
/**
 * Retrieves the adapter that supports a given URL.
 *
 * @remarks
 * Checks the internal cache first. If none is found, it uses a fallback strategy via config.
 *
 * @internal
 * @param url - A URL to match against registered adapters.
 * @returns The matching adapter.
 * @throws If no adapter supports the given URL and no `onMissingAdapter` is configured.
 */
declare function getAdapter(url: URL): Adapter | never;
/**
 * A ready-to-use adapter object that returns the source URL unmodified.
 *
 * @remarks
 * It can be used as a fallback in `onMissingAdapter`.
 * If used with `registerAdapters()`, it MUST be registered last.
 *
 * @public
 *
 * @example Recommended: Using with `onMissingAdapter`
 * ```ts
 * defineConfig({
 *   onMissingAdapter: (url) => {
 *      if (process.env.NODE_ENV === 'development') {
 *        throw new Error(`Adapter not found for URL: ${url}`);
 *      }
 *      return passThroughAdapter;
 *   },
 * });
 * ```
 *
 * @example Alternative: Using with `registerAdapters` - Ensure correct order
 * ```ts
 * import {registerAdapters, passThroughAdapter} from '@yoot/yoot';
 * import {shopifyAdapter} from '@yoot/shopify';
 *
 * registerAdapters(shopifyAdapter, passThroughAdapter); // passThroughAdapter must be last
 * ```
 */
declare const passThroughAdapter: Adapter;
/**
 * Represents an image adapter.
 * @public
 */
type Adapter = {
    /**
     * Determines whether the adapter supports a given URL.
     * @param url - The image URL to test.
     */
    supports: (url: URL) => boolean;
    /**
     * Generates a transformed image URL.
     * @param input - The transformation input.
     */
    generateUrl: (input: GenerateUrlInput) => string;
    /**
     * Normalizes a URL to its natural URL.
     * @param url - The URL to convert.
     */
    normalizeUrl: (url: URL) => string;
    /**
     * (Optional) Primes the state before transformation.
     * @param input - The state to prime.
     */
    primeState?: (input: PrimeStateInput) => YootState;
};
/**
 * Configuration object used to create an adapter.
 * @public
 */
type AdapterOptions = {
    [Key in keyof Adapter]: Adapter[Key];
};
/**
 * Input used to generate transformed image URLs.
 * @public
 */
type GenerateUrlInput = {
    /** The source image URL. */
    src: string;
    /** Transformation directives like width, height, etc. */
    directives: Directives;
};