@remix-run/assets 0.2.0 → 0.4.0

package/dist/lib/files/compiler.js

@@ -0,0 +1,552 @@
+import * as fs from 'node:fs';
+import * as fsp from 'node:fs/promises';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { IfNoneMatch } from '@remix-run/headers';
+import { detectContentType } from '@remix-run/mime';
+import { createAssetServerCompilationError, isAssetServerCompilationError, } from "../compilation-error.js";
+import { formatFingerprintedPathname, generateFingerprint, hashContent } from "../fingerprint.js";
+import { normalizeFilePath, resolveFilePath } from "../paths.js";
+import { parseAssetTransformInvocations } from "./config.js";
+import { createSourceFileStore } from "./store.js";
+export function createFileCompiler(options) {
+    let resolvedOptions = {
+        ...options,
+        extensionSet: new Set(options.extensions),
+    };
+    let sourceFileStore = createSourceFileStore();
+    let sourceFileInFlightByCacheKey = new Map();
+    let transformedAssetMetadataByCacheKey = new Map();
+    let transformedCacheKeysByIdentityPath = new Map();
+    let transformedEmitInFlightByCacheKey = new Map();
+    let cacheEpoch = resolvedOptions.buildId ?? crypto.randomUUID();
+    let resolveArgs = {
+        extensions: resolvedOptions.extensionSet,
+        isAllowed: resolvedOptions.isAllowed,
+        routes: resolvedOptions.routes,
+    };
+    return {
+        async getFile(filePath, getOptions) {
+            let resolvedFile = resolveServedFileOrThrow(resolveInputFilePath(filePath), resolveArgs);
+            let record = getFreshSourceFileRecord(resolvedFile.identityPath);
+            if (shouldUseTransformPipeline(getOptions.transform)) {
+                let cacheKey = getTransformedRecordCacheKey(cacheEpoch, record, getOptions.transform);
+                let notModified = getNotModifiedFile(transformedAssetMetadataByCacheKey.get(cacheKey), getOptions);
+                if (notModified)
+                    return notModified;
+                let transformedFile = await getOrCreateTransformedFile(record, getOptions.transform);
+                notModified = getNotModifiedFile(toEmittedFileMetadata(transformedFile), getOptions);
+                if (notModified)
+                    return notModified;
+                return {
+                    file: transformedFile,
+                    type: 'file',
+                };
+            }
+            let notModified = getNotModifiedFile(record.metadata, getOptions);
+            if (notModified)
+                return notModified;
+            if (record.staleMetadata &&
+                record.staleMetadataSnapshot &&
+                isFileSnapshotFresh(record.staleMetadataSnapshot)) {
+                let staleNotModified = getNotModifiedFile(record.staleMetadata, getOptions);
+                if (staleNotModified)
+                    return staleNotModified;
+            }
+            let file = await getOrCreateSourceFile(record);
+            return {
+                file,
+                type: 'file',
+            };
+        },
+        async getHref(filePath, hrefOptions) {
+            let resolvedFile = resolveServedFileOrThrow(resolveInputFilePath(filePath), resolveArgs);
+            let record = getFreshSourceFileRecord(resolvedFile.identityPath);
+            let href = resolvedOptions.fingerprintAssets
+                ? formatFingerprintedPathname(resolvedFile.stableUrlPathname, (await getOrCreateSourceFileMetadata(record)).fingerprint)
+                : resolvedFile.stableUrlPathname;
+            if (shouldUseTransformPipeline(hrefOptions.transform)) {
+                return appendTransformQuery(href, hrefOptions.transform);
+            }
+            return href;
+        },
+        async handleFileEvent(filePath, event) {
+            if (!isServedFilePath(filePath, resolvedOptions.extensionSet))
+                return;
+            sourceFileStore.invalidateForFileEvent(filePath, event);
+            clearTransformedCacheIndex(filePath);
+        },
+        isServedFilePath(filePath) {
+            return isServedFilePath(filePath, resolvedOptions.extensionSet);
+        },
+        validateTransformQuery(transformQuery) {
+            parseRequestTransforms(transformQuery, resolvedOptions.transforms, resolvedOptions.maxRequestTransforms);
+        },
+    };
+    function resolveInputFilePath(filePath) {
+        if (filePath.startsWith('file://')) {
+            return normalizeFilePath(fileURLToPath(new URL(filePath)));
+        }
+        if (filePath.includes('://')) {
+            throw new TypeError(`Expected a file path or file:// URL, received "${filePath}"`);
+        }
+        return resolveFilePath(resolvedOptions.rootDir, filePath);
+    }
+    function shouldUseTransformPipeline(transformQuery) {
+        return ((transformQuery !== null && transformQuery.length > 0) ||
+            resolvedOptions.globalTransforms.length > 0);
+    }
+    function getFreshSourceFileRecord(identityPath) {
+        let record = sourceFileStore.get(identityPath);
+        if (record.metadataSnapshot && !isFileSnapshotFresh(record.metadataSnapshot)) {
+            sourceFileStore.invalidate(identityPath);
+            clearTransformedCacheIndex(identityPath);
+            record = sourceFileStore.get(identityPath);
+        }
+        return record;
+    }
+    async function getOrCreateSourceFile(record) {
+        let cacheKey = getRecordCacheKey(record);
+        let existing = sourceFileInFlightByCacheKey.get(cacheKey);
+        if (existing)
+            return existing;
+        let promise = (async () => {
+            let startedVersion = record.invalidationVersion;
+            let body = await readFileContents(record.identityPath);
+            let sourceFile = record.metadata
+                ? createEmittedFileFromMetadata(body, record.metadata)
+                : await createSourceFile(body, record.identityPath);
+            if (record.invalidationVersion === startedVersion && !record.metadata) {
+                sourceFileStore.set(record.identityPath, toEmittedFileMetadata(sourceFile), getFileSnapshot(record.identityPath));
+            }
+            return sourceFile;
+        })();
+        sourceFileInFlightByCacheKey.set(cacheKey, promise);
+        try {
+            return await promise;
+        }
+        finally {
+            if (sourceFileInFlightByCacheKey.get(cacheKey) === promise) {
+                sourceFileInFlightByCacheKey.delete(cacheKey);
+            }
+        }
+    }
+    async function getOrCreateSourceFileMetadata(record) {
+        if (record.metadata)
+            return record.metadata;
+        return toEmittedFileMetadata(await getOrCreateSourceFile(record));
+    }
+    async function getOrCreateTransformedFile(record, transformQuery) {
+        let parsedTransforms = parseRequestTransforms(transformQuery, resolvedOptions.transforms, resolvedOptions.maxRequestTransforms);
+        let cacheKey = getTransformedRecordCacheKey(cacheEpoch, record, transformQuery);
+        let existing = transformedEmitInFlightByCacheKey.get(cacheKey);
+        if (existing)
+            return existing;
+        let promise = (async () => {
+            let sourceFile = await getOrCreateSourceFile(record);
+            let cachedFile = await getCachedTransformedFile(cacheKey, record.identityPath, sourceFile.fingerprint);
+            if (cachedFile)
+                return cachedFile;
+            let transformedFile = await applyTransforms(record.identityPath, sourceFile, parsedTransforms);
+            if (transformedFile === null) {
+                return sourceFile;
+            }
+            let emittedFile = await createEmittedFile(transformedFile.body, {
+                extension: transformedFile.extension,
+                filePath: record.identityPath,
+                fingerprint: sourceFile.fingerprint,
+            });
+            rememberTransformedAssetMetadata(cacheKey, record.identityPath, toEmittedFileMetadata(emittedFile));
+            await setCachedTransformedFile(cacheKey, record.identityPath, emittedFile);
+            return emittedFile;
+        })();
+        transformedEmitInFlightByCacheKey.set(cacheKey, promise);
+        try {
+            return await promise;
+        }
+        finally {
+            if (transformedEmitInFlightByCacheKey.get(cacheKey) === promise) {
+                transformedEmitInFlightByCacheKey.delete(cacheKey);
+            }
+        }
+    }
+    async function createSourceFile(body, identityPath) {
+        return createEmittedFile(body, {
+            extension: path.extname(identityPath).toLowerCase(),
+            filePath: identityPath,
+            fingerprint: resolvedOptions.fingerprintAssets && resolvedOptions.buildId
+                ? await generateFingerprint({
+                    buildId: resolvedOptions.buildId,
+                    content: body,
+                })
+                : null,
+        });
+    }
+    function createEmittedFileFromMetadata(body, metadata) {
+        return {
+            body,
+            ...metadata,
+        };
+    }
+    async function applyTransforms(filePath, source, transforms) {
+        let currentBody = source.body;
+        let currentExtension = source.extension;
+        let appliedTransform = false;
+        for (let requestTransform of transforms) {
+            let transform = resolvedOptions.transforms.get(requestTransform.name);
+            if (transform === undefined) {
+                throw createAssetServerCompilationError(`Unknown file transform "${requestTransform.name}" requested for ${filePath}`, { code: 'FILE_TRANSFORM_QUERY_INVALID' });
+            }
+            if (!supportsTransformExtension(transform.extensions, currentExtension)) {
+                throw createAssetServerCompilationError(`File transform "${requestTransform.name}" does not support ${currentExtension} inputs for ${filePath}`, { code: 'FILE_TRANSFORM_NOT_SUPPORTED' });
+            }
+            let result;
+            let transformSubject = {
+                kind: 'request',
+                name: requestTransform.name,
+            };
+            try {
+                result = await transform.transform(currentBody, {
+                    extension: currentExtension,
+                    filePath,
+                    param: requestTransform.param,
+                });
+            }
+            catch (error) {
+                throw toFileTransformFailedError(error, filePath, transformSubject);
+            }
+            let normalizedResult = normalizeTransformResult(result, {
+                currentExtension,
+                filePath,
+                transformSubject,
+            });
+            currentBody = normalizedResult.content;
+            currentExtension = normalizedResult.extension;
+            appliedTransform = true;
+        }
+        for (let [index, globalTransform] of resolvedOptions.globalTransforms.entries()) {
+            if (!supportsTransformExtension(globalTransform.extensions, currentExtension))
+                continue;
+            let result;
+            let transformSubject = getGlobalFileTransformSubject(globalTransform, index);
+            try {
+                result = await globalTransform.transform(currentBody, {
+                    extension: currentExtension,
+                    filePath,
+                });
+            }
+            catch (error) {
+                throw toFileTransformFailedError(error, filePath, transformSubject);
+            }
+            if (result === null)
+                continue;
+            let normalizedResult = normalizeTransformResult(result, {
+                currentExtension,
+                filePath,
+                transformSubject,
+            });
+            currentBody = normalizedResult.content;
+            currentExtension = normalizedResult.extension;
+            appliedTransform = true;
+        }
+        if (!appliedTransform)
+            return null;
+        return { body: currentBody, extension: currentExtension };
+    }
+    async function getCachedTransformedFile(cacheKey, identityPath, fingerprint) {
+        if (!resolvedOptions.cache)
+            return null;
+        let file = await resolvedOptions.cache.get(cacheKey);
+        if (!file)
+            return null;
+        let body = new Uint8Array(await file.arrayBuffer());
+        let metadata = transformedAssetMetadataByCacheKey.get(cacheKey) ??
+            (await createEmittedFileMetadata(body, {
+                extension: path.extname(file.name).toLowerCase(),
+                filePath: identityPath,
+                fingerprint,
+            }));
+        rememberTransformedAssetMetadata(cacheKey, identityPath, metadata);
+        return {
+            body,
+            ...metadata,
+        };
+    }
+    async function setCachedTransformedFile(cacheKey, filePath, emittedFile) {
+        if (!resolvedOptions.cache)
+            return;
+        let basename = path.basename(filePath, path.extname(filePath));
+        await resolvedOptions.cache.set(cacheKey, new File([Buffer.from(emittedFile.body)], `${basename}${emittedFile.extension}`, {
+            type: emittedFile.contentType,
+        }));
+    }
+    async function createEmittedFile(body, options) {
+        let metadata = await createEmittedFileMetadata(body, options);
+        return {
+            body,
+            ...metadata,
+        };
+    }
+    function clearTransformedCacheIndex(identityPath) {
+        let cacheKeys = transformedCacheKeysByIdentityPath.get(identityPath);
+        if (!cacheKeys)
+            return;
+        for (let cacheKey of cacheKeys) {
+            transformedAssetMetadataByCacheKey.delete(cacheKey);
+        }
+        transformedCacheKeysByIdentityPath.delete(identityPath);
+    }
+    function rememberTransformedAssetMetadata(cacheKey, identityPath, metadata) {
+        transformedAssetMetadataByCacheKey.set(cacheKey, metadata);
+        let cacheKeys = transformedCacheKeysByIdentityPath.get(identityPath) ?? new Set();
+        cacheKeys.add(cacheKey);
+        transformedCacheKeysByIdentityPath.set(identityPath, cacheKeys);
+    }
+    async function createEmittedFileMetadata(body, options) {
+        let contentType = detectContentType(`file${options.extension}`) ??
+            detectContentType(options.filePath) ??
+            'application/octet-stream';
+        return {
+            contentType,
+            etag: `W/"${await hashContent(body)}"`,
+            extension: options.extension,
+            fingerprint: options.fingerprint,
+        };
+    }
+}
+export function resolveServedFileOrThrow(filePath, args) {
+    let identityPath = resolveExistingFilePath(filePath);
+    if (!identityPath) {
+        throw createAssetServerCompilationError(`File not found: ${filePath}`, {
+            code: 'FILE_NOT_FOUND',
+        });
+    }
+    if (!isServedFilePath(identityPath, args.extensions)) {
+        throw createAssetServerCompilationError(`File type is not supported: ${identityPath}`, {
+            code: 'FILE_NOT_SUPPORTED',
+        });
+    }
+    if (!args.isAllowed(identityPath)) {
+        throw createAssetServerCompilationError(`File is not allowed: ${identityPath}`, {
+            code: 'FILE_NOT_ALLOWED',
+        });
+    }
+    let stableUrlPathname = args.routes.toUrlPathname(identityPath);
+    if (!stableUrlPathname) {
+        throw createAssetServerCompilationError(`File ${identityPath} is outside all configured fileMap entries.`, {
+            code: 'FILE_OUTSIDE_FILE_MAP',
+        });
+    }
+    return {
+        identityPath,
+        stableUrlPathname,
+    };
+}
+export function createResponseForFile(result, options) {
+    if (IfNoneMatch.from(options.ifNoneMatch).matches(result.etag)) {
+        return new Response(null, { status: 304, headers: { ETag: result.etag } });
+    }
+    return new Response(options.method === 'HEAD' ? null : Buffer.from(result.body), {
+        headers: {
+            'Cache-Control': options.cacheControl,
+            'Content-Type': result.contentType,
+            ETag: result.etag,
+        },
+    });
+}
+export function isServedFilePath(filePath, extensions) {
+    return extensions.has(path.extname(filePath).toLowerCase());
+}
+function getRecordCacheKey(record) {
+    return `${record.identityPath}\0${record.invalidationVersion}`;
+}
+function getTransformedRecordCacheKey(cacheEpoch, record, transformQuery) {
+    return [
+        encodeCacheKeyPart(cacheEpoch),
+        encodeCacheKeyPart(record.identityPath),
+        String(record.invalidationVersion),
+        encodeCacheKeyPart(JSON.stringify(transformQuery ?? [])),
+    ].join('/');
+}
+function getFileSnapshot(filePath) {
+    try {
+        let stats = fs.statSync(filePath, { bigint: true });
+        if (!stats.isFile())
+            return null;
+        return {
+            filePath,
+            mtimeNs: stats.mtimeNs,
+            size: stats.size,
+        };
+    }
+    catch (error) {
+        if (isNoEntityError(error))
+            return null;
+        throw error;
+    }
+}
+function getNotModifiedFile(emittedFile, options) {
+    if (!emittedFile || options.ifNoneMatch === null)
+        return null;
+    if (options.requestedFingerprint !== null &&
+        emittedFile.fingerprint !== options.requestedFingerprint) {
+        return null;
+    }
+    if (!IfNoneMatch.from(options.ifNoneMatch).matches(emittedFile.etag))
+        return null;
+    return { etag: emittedFile.etag, type: 'not-modified' };
+}
+function toEmittedFileMetadata(emittedFile) {
+    return {
+        contentType: emittedFile.contentType,
+        etag: emittedFile.etag,
+        extension: emittedFile.extension,
+        fingerprint: emittedFile.fingerprint,
+    };
+}
+function isFileSnapshotFresh(snapshot) {
+    let current = getFileSnapshot(snapshot.filePath);
+    return current != null && current.mtimeNs === snapshot.mtimeNs && current.size === snapshot.size;
+}
+function appendTransformQuery(href, transformQuery) {
+    if (transformQuery === null)
+        return href;
+    let searchParams = new URLSearchParams();
+    for (let transform of transformQuery) {
+        searchParams.append('transform', transform);
+    }
+    let search = searchParams.toString();
+    return search.length > 0 ? `${href}?${search}` : href;
+}
+function encodeCacheKeyPart(value) {
+    return Buffer.from(value).toString('base64url');
+}
+function normalizeTransformResult(result, options) {
+    if (typeof result === 'string') {
+        return {
+            content: new TextEncoder().encode(result),
+            extension: options.currentExtension,
+        };
+    }
+    if (result instanceof Uint8Array) {
+        return {
+            content: result,
+            extension: options.currentExtension,
+        };
+    }
+    if (result === null || typeof result !== 'object') {
+        throw createAssetServerCompilationError(`${formatFileTransformSubject(options.transformSubject)} must return a string, Uint8Array, or object for ${options.filePath}`, { code: 'FILE_TRANSFORM_RESULT_INVALID' });
+    }
+    if (!('content' in result) ||
+        (typeof result.content !== 'string' && !(result.content instanceof Uint8Array))) {
+        throw createAssetServerCompilationError(`${formatFileTransformSubject(options.transformSubject)} must return a string or Uint8Array content value for ${options.filePath}`, { code: 'FILE_TRANSFORM_RESULT_INVALID' });
+    }
+    let extension = options.currentExtension;
+    if ('extension' in result && result.extension !== undefined) {
+        if (typeof result.extension !== 'string') {
+            throw createAssetServerCompilationError(`${formatFileTransformSubject(options.transformSubject)} must return a string extension for ${options.filePath}`, { code: 'FILE_TRANSFORM_RESULT_INVALID' });
+        }
+        extension = normalizeTransformExtension(result.extension, options.filePath, options.transformSubject);
+    }
+    return {
+        content: typeof result.content === 'string'
+            ? new TextEncoder().encode(result.content)
+            : result.content,
+        extension,
+    };
+}
+function normalizeTransformExtension(extension, filePath, transformSubject) {
+    let normalizedExtension = extension.trim().toLowerCase();
+    if (!/^\.[A-Za-z0-9_-]+$/.test(normalizedExtension)) {
+        throw createAssetServerCompilationError(`${formatFileTransformSubject(transformSubject)} returned an invalid extension "${extension}" for ${filePath}`, { code: 'FILE_TRANSFORM_RESULT_INVALID' });
+    }
+    return normalizedExtension;
+}
+function toFileTransformFailedError(error, filePath, transformSubject) {
+    if (isAssetServerCompilationError(error))
+        return error;
+    return createAssetServerCompilationError(`${formatFileTransformSubject(transformSubject)} failed for ${filePath}. ${formatUnknownError(error)}`, {
+        cause: error,
+        code: 'FILE_TRANSFORM_FAILED',
+    });
+}
+function getGlobalFileTransformSubject(globalTransform, index) {
+    let functionName = globalTransform.transform.name;
+    return {
+        index,
+        kind: 'global',
+        name: globalTransform.name ?? (functionName.length > 0 ? functionName : undefined),
+    };
+}
+function formatFileTransformSubject(transformSubject) {
+    if (transformSubject.kind === 'request') {
+        return `File transform "${transformSubject.name}"`;
+    }
+    return transformSubject.name === undefined
+        ? `Global file transform at index ${transformSubject.index}`
+        : `Global file transform "${transformSubject.name}"`;
+}
+function formatUnknownError(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function supportsTransformExtension(extensions, currentExtension) {
+    return extensions === undefined || extensions.includes(currentExtension);
+}
+function parseRequestTransforms(transformQuery, transforms, maxRequestTransforms) {
+    if (transformQuery === null)
+        return [];
+    try {
+        return parseAssetTransformInvocations(transformQuery, transforms, maxRequestTransforms).map((transformInvocation) => typeof transformInvocation === 'string'
+            ? {
+                name: transformInvocation,
+                param: undefined,
+            }
+            : {
+                name: transformInvocation[0],
+                param: transformInvocation[1],
+            });
+    }
+    catch (error) {
+        throw createAssetServerCompilationError(error instanceof Error ? error.message : 'Invalid file transforms', {
+            code: 'FILE_TRANSFORM_QUERY_INVALID',
+        });
+    }
+}
+function resolveExistingFilePath(filePath) {
+    try {
+        return normalizeFilePath(fs.realpathSync(filePath));
+    }
+    catch (error) {
+        if (isNoEntityError(error))
+            return null;
+        throw error;
+    }
+}
+function isNoEntityError(error) {
+    return (error instanceof Error &&
+        'code' in error &&
+        (error.code === 'ENOENT' ||
+            error.code === 'ENOTDIR'));
+}
+async function readFileContents(identityPath) {
+    try {
+        return new Uint8Array(await fsp.readFile(identityPath));
+    }
+    catch (error) {
+        if (isNoEntityError(error)) {
+            throw createAssetServerCompilationError(`File not found: ${identityPath}`, {
+                cause: error,
+                code: 'FILE_NOT_FOUND',
+            });
+        }
+        throw toEmitError(error, identityPath);
+    }
+}
+function toEmitError(error, identityPath) {
+    if (isAssetServerCompilationError(error))
+        return error;
+    return createAssetServerCompilationError(`Failed to read file ${identityPath}. ${error instanceof Error ? error.message : String(error)}`, {
+        cause: error,
+        code: 'EMIT_FAILED',
+    });
+}

package/dist/lib/files/config.d.ts

@@ -0,0 +1,101 @@
+import type { FileStorage } from '@remix-run/file-storage';
+export interface AssetFileTransformResult {
+    content: string | Uint8Array;
+    extension?: string;
+}
+type AssetRequestTransformParamMode = true | 'optional' | undefined;
+declare const assetRequestTransformTypes: unique symbol;
+type AssetRequestTransformTypes<param extends string, mode extends AssetRequestTransformParamMode> = {
+    input: param;
+    mode: mode;
+};
+export interface AssetTransformContext {
+    extension: string;
+    filePath: string;
+}
+type AssetRequestTransformRuntimeParam<mode extends AssetRequestTransformParamMode> = mode extends true ? string : mode extends 'optional' ? string | undefined : undefined;
+export interface AssetRequestTransformContext<mode extends AssetRequestTransformParamMode = undefined> extends AssetTransformContext {
+    param: AssetRequestTransformRuntimeParam<mode>;
+}
+export interface AssetGlobalTransformContext extends AssetTransformContext {
+}
+export type AssetRequestTransform<param extends string = string, mode extends AssetRequestTransformParamMode = undefined> = {
+    readonly [assetRequestTransformTypes]?: AssetRequestTransformTypes<param, mode>;
+    /**
+     * Optional list of file extensions this transform accepts. Values must use `.ext` format.
+     * Matching is evaluated against the current extension at this point in the transform pipeline.
+     */
+    extensions?: readonly string[];
+    transform(bytes: Uint8Array, context: AssetRequestTransformContext<mode>): string | Uint8Array | AssetFileTransformResult | Promise<string | Uint8Array | AssetFileTransformResult>;
+} & (mode extends undefined ? {
+    param?: undefined;
+} : {
+    param: mode;
+});
+type AssetGlobalTransformHandler = (bytes: Uint8Array, context: AssetGlobalTransformContext) => string | Uint8Array | AssetFileTransformResult | null | Promise<string | Uint8Array | AssetFileTransformResult | null>;
+export type AssetGlobalTransform = AssetGlobalTransformHandler | {
+    /**
+     * Optional list of file extensions this transform accepts. Values must use `.ext` format.
+     * Non-matching files are skipped automatically.
+     */
+    extensions?: readonly string[];
+    name?: string;
+    transform: AssetGlobalTransformHandler;
+};
+interface ResolvedAssetGlobalTransform {
+    extensions?: readonly string[];
+    name?: string;
+    transform: AssetGlobalTransformHandler;
+}
+export type AssetRequestTransformMap = Readonly<Record<string, AssetRequestTransform<string, AssetRequestTransformParamMode>>>;
+export type ResolvedAssetRequestTransformMap = ReadonlyMap<string, AssetRequestTransform<string, AssetRequestTransformParamMode>>;
+export interface AssetServerFilesOptions<transforms extends AssetRequestTransformMap = {}> {
+    /**
+     * File extensions to expose as leaf assets. Values must include the leading dot,
+     * for example `['.png', '.svg', '.woff2']`.
+     */
+    extensions: readonly string[];
+    /**
+     * Named transforms that can be requested from asset URLs.
+     */
+    transforms?: transforms;
+    /**
+     * Maximum number of request transforms allowed in a single asset URL.
+     * Defaults to `5`.
+     */
+    maxRequestTransforms?: number;
+    /**
+     * Ordered transforms that run for every served file asset and may return `null`
+     * to skip themselves for a given input.
+     */
+    globalTransforms?: readonly AssetGlobalTransform[];
+    /**
+     * Optional backing store for cached transformed file outputs.
+     */
+    cache?: FileStorage;
+}
+export interface ResolvedAssetServerFilesOptions {
+    cache?: FileStorage;
+    extensions: readonly string[];
+    globalTransforms: readonly ResolvedAssetGlobalTransform[];
+    hasTransforms: boolean;
+    maxRequestTransforms: number;
+    transforms: ResolvedAssetRequestTransformMap;
+}
+type AssetTransformStep<name extends string, param extends string, mode extends AssetRequestTransformParamMode> = mode extends true ? readonly [name, param] : mode extends 'optional' ? name | readonly [name] | readonly [name, param] : name | readonly [name];
+export type AssetTransformInvocation<transforms extends AssetRequestTransformMap> = {
+    [name in keyof transforms & string]: transforms[name] extends {
+        readonly [assetRequestTransformTypes]?: infer types;
+    } ? types extends {
+        input: infer param extends string;
+        mode: infer mode extends AssetRequestTransformParamMode;
+    } ? AssetTransformStep<name, param, mode> : never : never;
+}[keyof transforms & string];
+export declare function defineFileTransform(transform: AssetRequestTransform<string, undefined>): AssetRequestTransform<string, undefined>;
+export declare function defineFileTransform<const param extends string = string>(transform: AssetRequestTransform<param, true>): AssetRequestTransform<param, true>;
+export declare function defineFileTransform<const param extends string = string>(transform: AssetRequestTransform<param, 'optional'>): AssetRequestTransform<param, 'optional'>;
+export declare function normalizeFilesOptions<transforms extends AssetRequestTransformMap>(files: AssetServerFilesOptions<transforms> | undefined): ResolvedAssetServerFilesOptions;
+export declare function serializeAssetTransformInvocations<transforms extends AssetRequestTransformMap>(transforms: readonly AssetTransformInvocation<transforms>[], transformsByName: ResolvedAssetRequestTransformMap, maxTransforms?: number): string[];
+export declare function parseAssetTransformInvocations(transformsQuery: readonly string[], transformsByName: ResolvedAssetRequestTransformMap, maxTransforms?: number): readonly (string | readonly [string, string])[];
+export {};
+//# sourceMappingURL=config.d.ts.map

package/dist/lib/files/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../src/lib/files/config.ts"],"names":[],"mappings":"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"}