visionary-url/dist/visionary-url.d.ts

A lightweight library for generating image URLs with baked-in blurhash placeholders.

export declare const formatToContentType: (format: ImageFormatToken) => {
    contentType: string;
    extension: string;
};

export declare interface GenerateUrlOptions extends VisionaryImageOptions {
    /**
     * Specifies a filename for the image URL. Defaults to `image.jpg`.
     * @NOTE It's highly recommended to specify a descriptive filename as this helps improve discoverability of images by search engines.
     */
    filename?: string;
}

/**
 * Generates a Visionary image code
 */
export declare const generateVisionaryCode: (fields: VisionaryImageFields) => string | Error;

export declare const generateVisionaryUrl: (fields: VisionaryImageFields, options?: GenerateUrlOptions) => string | null;

export declare enum ImageFormatToken {
    AUTO = "auto",
    AVIF = "avif",
    JPEG = "jpeg",
    WEBP = "webp"
}

export declare enum ImageSizeToken {
    xs = "xs",
    sm = "sm",
    md = "md",
    lg = "lg",
    xl = "xl",
    xxl = "xxl",
    "4k" = "4k",
    "5k" = "5k",
    /**
     * `full` is image dependent and represents the source image's longest edge
     */
    full = "full"
}

export declare const isBase64UrlEncoded: (str?: string) => boolean;

export declare const isDebugToken: (token: string) => token is UrlOptionToken.DEBUG;

export declare const isDownloadToken: (token: string) => token is UrlOptionToken.DOWNLOAD;

export declare const isFollowToken: (token: string) => token is UrlOptionToken.FOLLOW;

export declare const isImageFormatToken: (format: string) => format is ImageFormatToken;

export declare const isImageSizeToken: (token: string) => token is ImageSizeToken;

export declare const parseOptionsString: (options?: string) => VisionaryImageOptions;

export declare const parseVisionaryCode: (code: string) => VisionaryImageFields | null;

/**
 * Parses input string for Visionary data contained within
 * @param visionaryCodeOrUrl string which represents a Visionary Code or Visionary URL
 */
export declare const parseVisionaryString: (visionaryCodeOrUrl: string) => VisionaryImage | null;

export declare const parseVisionaryUrl: (url: string) => VisionaryImage | null;

/**
 * This is purposely kept simple as sometimes cranking these values up results in a good image, other times not.
 * Defaults to 4x4 (or 4x3 for landscape images).
 */
export declare const suggestedBlurhashComponentDimensions: (width: number, height: number) => [x: number, y: number];

export declare enum UrlOptionToken {
    DEBUG = "debug",
    DOWNLOAD = "download",
    FOLLOW = "follow"
}

export declare interface VisionaryImage {
    fields: VisionaryImageFields;
    options: VisionaryImageOptions;
}

/**
 * Image metadata fields encoded in a Visionary URL
 */
export declare interface VisionaryImageFields {
    /**
     * Alt text
     */
    altText?: string;
    /**
     * Background color code
     */
    bcc?: string;
    /**
     * Blurhash string
     */
    blurhash?: string;
    /**
     * Number of _x_ components the blurhash string represents
     */
    blurhashX?: number;
    /**
     * Number of _y_ components the blurhash string represents
     */
    blurhashY?: number;
    /**
     * Height of original upload image (also max height)
     */
    sourceHeight: number;
    /**
     * Width of original upload image (also max width)
     */
    sourceWidth: number;
    /**
     * Image URL or internal image identifier
     */
    url: string;
}

/**
 * Options are encoded in the second segment of a Visionary URL
 */
export declare interface VisionaryImageOptions {
    debug?: boolean;
    /**
     * Specifies that server should send the file as an attachment download
     * (e.g. content-disposition: attachment)
     */
    download?: boolean;
    /** Specifies a custom endpoint when `generateVisionaryUrl()` is used */
    endpoint?: string;
    follow?: boolean;
    format?: ImageFormatToken;
    size?: ImageSizeToken;
}

export { }