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

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

import { YOOT_BRAND } from './store.ts';
export { createYoot as yoot };
export { unwrapInput };
export type { Yoot, YootFactory, YootInput, YootState, PrimeStateInput };
export type { Directives, DirectiveHandler, DirectiveMethods, DirectiveNames, OutputMethods, Horizontal, Vertical };
/**
 * Creates a new Yoot image transformation object.
 *
 * @remarks Entry point for all image transformations. *
 * @public
 * @param init - Optional initial state or image source URL string.
 * @returns A new chainable Yoot object.
 */
declare const createYoot: (init?: YootInput) => Yoot;
/**
 * Normalizes input into a `SomeYootState` object.
 * @remarks Accepts a URL string, JSON string, partial state, or a `Yoot` object.
 * @internal
 */
declare function unwrapInput(input?: YootInput): SomeYootState;
/**
 * Vertical crop options.
 * @public
 */
type Vertical = 'top' | 'bottom';
/**
 * Horizontal crop options.
 * @public
 */
type Horizontal = 'left' | 'right';
/**
 * Object map of image transformation directives.
 * @public
 */
type Directives = {
    aspectRatio?: number;
    crop?: 'center' | Vertical | Horizontal;
    dpr?: number;
    fit?: 'contain' | 'cover';
    format?: 'auto' | 'jpg' | 'png' | 'webp';
    height?: number;
    quality?: number;
    width?: number;
};
/**
 * Keys of the `Directives` object.
 * @public
 */
type DirectiveNames = keyof Directives;
/**
 * Function that applies a directive and returns a new `Yoot` object.
 * @public
 */
type DirectiveHandler<K extends keyof Directives> = (value: NonNullable<Directives[K]> | null) => Yoot;
/**
 * Input for `yoot()`: a source URL string or a partial `YootState` object.
 * @public
 */
type YootInput = string | SomeYootState | Yoot | Record<string, unknown> | null | undefined;
/**
 * The public Yoot API: a callable factory for new states, with chainable methods.
 * @public
 */
interface Yoot extends YootFactory, DirectiveMethods, OutputMethods {
    /**
     * Marks this object as Yoot.
     * @internal
     */
    readonly [YOOT_BRAND]: true;
    /**
     * Sets the image source URL.
     * @param src - The image URL.
     * @throws If `src` is not a valid URL string.
     */
    src(src: string): Yoot;
    /**
     * Sets the image alt text (stored in state).
     * @param alt - The alt text.
     */
    alt(alt: string): Yoot;
    /**
     * Applies custom transformations to the current state.
     *
     * @remarks
     * The callback receives a mutable copy of the current state.
     *
     * @param fn - Function `(state: YootState) => SomeYootState` to modify state.
     *
     * @example
     * ```ts
     * yoot().src('https://cdn.example.com/images/image-1.png').width(100).map((state) => {
     *   state.alt ||= 'Fallback Alt Text';
     *   state.directives.format = 'webp';
     *   return state;
     * }).url;
     * ```
     */
    map(fn: (state: YootState) => YootState): Yoot;
}
/**
 * Callable signature of the Yoot object.
 * @public
 */
interface YootFactory {
    (input?: YootInput): Yoot;
}
/**
 * Image transformation directive methods available on the Yoot object.
 * @public
 */
interface DirectiveMethods {
    /** Sets aspect ratio. */
    aspectRatio: DirectiveHandler<'aspectRatio'>;
    /** Alias for `aspectRatio`. */
    ar: DirectiveHandler<'aspectRatio'>;
    /** Sets crop mode. */
    crop: DirectiveHandler<'crop'>;
    /** Sets device pixel ratio. */
    dpr: DirectiveHandler<'dpr'>;
    /** Sets fit mode. */
    fit: DirectiveHandler<'fit'>;
    /** Sets output format. */
    format: DirectiveHandler<'format'>;
    /** Alias for `format`. */
    fm: DirectiveHandler<'format'>;
    /** Sets target height. */
    height: DirectiveHandler<'height'>;
    /** Alias for `height`. */
    h: DirectiveHandler<'height'>;
    /** Sets quality. */
    quality: DirectiveHandler<'quality'>;
    /** Alias for `quality`. */
    q: DirectiveHandler<'quality'>;
    /** Sets target width. */
    width: DirectiveHandler<'width'>;
    /** Alias for `width`. */
    w: DirectiveHandler<'width'>;
}
/**
 * Output methods available on the Yoot object.
 * @public
 */
interface OutputMethods {
    /**
     * Returns a serializable copy of the current state.
     * @remarks Called by `JSON.stringify()`.
     * @returns A shallow-cloned `YootState` object.
     */
    toJSON: () => YootState;
    /**
     * Returns a serializable copy of the current state with normalized directives.
     * @returns A shallow-cloned `YootState` object.
     */
    toResolvedJSON: () => YootState;
    /**
     * Returns the transformed image URL. Same as `url()`.
     * @throws Error If `state.src` is not a valid string.
     */
    toString: () => string;
    /**
     * Returns true if `src` has been given.
     */
    readonly hasSrc: boolean;
    /**
     * Returns the generated image URL.
     * @throws Error If `state.src` is not a valid string.
     */
    readonly url: string;
    /**
     * Returns the base (normalized) URL.
     * @remarks This is `null` if `src` is empty.
     */
    readonly baseUrl: string | null;
}
/**
 * Represents the state of a Yoot object.
 *
 * @remarks
 * Suitable for `toJSON()` output.
 *
 * @public
 */
type YootState = {
    /** Image source URL. */
    src?: string;
    /** Image alt text. */
    alt?: string;
    /** Intrinsic width of the source image, if known. */
    width?: number;
    /** Intrinsic height of the source image, if known. */
    height?: number;
    /** Object map of transformation directives (e.g., `{ width: 300, format: 'webp' }`). */
    directives: Directives;
};
/**
 * Represents a version of `YootState` that guarantees the presence of `src`
 *
 * @remarks Used as input to adapter `primeState` methods.
 * @public
 */
type PrimeStateInput = {
    src: string;
} & Omit<YootState, 'src'>;
/**
 * A partial `YootState`, used for updates and initial input.
 * @public
 */
type SomeYootState = Partial<YootState>;