img-upload-kit 1.1.1 → 2.0.1

package/dist/server.d.ts

@@ -1,44 +1,7 @@
-import { b as ImageOutputFormat, I as ImageDimensions, E as ExplicitOutputFormat, c as ImageUploadOptions, r as UploadedImageData, p as UploadPresetConfig, g as StandardPresetName, h as StorageAdapter, t as UploadRecordHook, n as StorageUploadResult } from './types-CiLY0DwB.js';
-
-interface OptimizedImageResult {
-    buffer: Buffer;
-    width: number;
-    height: number;
-    format: ImageOutputFormat;
-    size: number;
-}
-interface BlurHashResult {
-    dataURL: string;
-    color: string;
-    blurHash?: string;
-}
-interface OptimizeImageOptions {
-    /** Max bounding box dimensions (fit: 'inside', withoutEnlargement: true). Defaults to 1920x1080. */
-    maxDimensions?: ImageDimensions;
-    /** Explicit output format; omit for smart size-guarded AVIF/WebP selection */
-    outputFormat?: ExplicitOutputFormat;
-    /** 1–100 compression quality. Defaults to smart photo/graphic heuristic (85–88). */
-    quality?: number;
-}
-interface GenerateBlurOptions {
-    width?: number;
-    fallbackWidth?: number;
-    quality?: number;
-    maxDataUrlChars?: number;
-    includeBlurHash?: boolean;
-}
-type ColorSamplingMode = 'balanced' | 'edge';
-type EdgeKey = 'top' | 'right' | 'bottom' | 'left';
-type EdgeColorSet = Record<EdgeKey, string>;
-declare const PRIMARY_AVIF_EFFORT = 6;
-declare const RETRY_AVIF_EFFORT = 5;
-declare const BLUR_PLACEHOLDER_WIDTH = 128;
-declare const BLUR_PLACEHOLDER_FALLBACK_WIDTH = 96;
-declare const BLUR_PLACEHOLDER_QUALITY = 80;
-declare const BLUR_PLACEHOLDER_MAX_CHARS = 8000;
-declare const EDGE_COLOR_FALLBACK = "#6B7280";
-declare const EDGE_WHITE_FALLBACK = "#F9FAFB";
-declare const WHITE_DOMINANCE_RATIO = 1.35;
+import { O as OptimizeImageOptions, a as OptimizedImageResult, G as GenerateBlurOptions, B as BlurHashResult, E as EdgeColorSet, C as ColorSamplingMode, P as ProcessImageBufferOptions, b as ProcessedImageBufferResult, I as ImageUploaderOptions, c as ImageUploader, d as InferredPresetKey, S as StoragePathGenerator, e as StoragePathContext, f as GeneratedStorageTarget } from './index-BIdnqtW8.js';
+export { A as AllowClientOverrides, g as AuthorizeContext, h as BLUR_PLACEHOLDER_FALLBACK_WIDTH, i as BLUR_PLACEHOLDER_MAX_CHARS, j as BLUR_PLACEHOLDER_QUALITY, k as BLUR_PLACEHOLDER_WIDTH, D as DEFAULT_LIMIT_INPUT_PIXELS, l as EDGE_COLOR_FALLBACK, m as EDGE_WHITE_FALLBACK, n as EdgeKey, o as PRIMARY_AVIF_EFFORT, R as RETRY_AVIF_EFFORT, U as UploadErrorContext, p as UploadHttpHandlerOptions, q as UploadValidationError, W as WHITE_DOMINANCE_RATIO, r as createUploadHandler, s as createUploadHttpHandler, t as isClientValidationError } from './index-BIdnqtW8.js';
+import { k as UploadPresetConfig, c as ImageOutputFormat, e as ImageVariant } from './upload-C5Trd6Dh.js';
+import { S as StorageAdapter, h as StorageUploadResult } from './types-sZ3KoFQY.js';
 
 declare function optimizeImage(buffer: Buffer, options?: OptimizeImageOptions): Promise<OptimizedImageResult>;
 
@@ -47,90 +10,11 @@ declare function generateBlurPlaceholder(buffer: Buffer, options?: GenerateBlurO
 declare const generateBlurHash: typeof generateBlurPlaceholder;
 
 declare function extractEdgeColorsFromBuffer(buffer: Buffer): Promise<EdgeColorSet>;
+declare function computeEdgeColorSet(data: Buffer, width: number, height: number): EdgeColorSet;
 declare function blendEdgeColors(edgeColors: EdgeColorSet): string;
 
 declare function extractEnhancedColorFromBuffer(buffer: Buffer, mode?: ColorSamplingMode): Promise<string>;
 
-interface ProcessedImageBufferResult {
-    optimized: OptimizedImageResult;
-    blurData: BlurHashResult;
-    contentHash: string;
-    originalSize: number;
-}
-interface ProcessImageBufferOptions {
-    maxDimensions?: ImageDimensions;
-    outputFormat?: ExplicitOutputFormat;
-    quality?: number;
-    includeBlurHash?: boolean;
-    optimizationTimeoutMs?: number;
-    blurTimeoutMs?: number;
-}
-interface StoragePathContext {
-    bucket: string;
-    folder?: string;
-    preset?: string;
-    format: ImageOutputFormat;
-    extension: string;
-    customFilename?: string;
-    contentHash: string;
-    originalName?: string;
-    metadata?: Record<string, string>;
-}
-interface GeneratedStorageTarget {
-    bucket: string;
-    path: string;
-    filename: string;
-}
-type StoragePathGenerator = (context: StoragePathContext) => GeneratedStorageTarget;
-interface ImageUploaderOptions<TPresets extends Record<string, UploadPresetConfig> = Record<StandardPresetName, UploadPresetConfig>> {
-    /** Pluggable storage backend (Supabase, S3, R2, Local FS, Memory, or custom) */
-    storage: StorageAdapter;
-    /** Default bucket name when neither `options.bucket` nor `preset.bucket` is provided (defaults to `'images'`) */
-    defaultBucket?: string;
-    /** Default folder prefix within the bucket (defaults to `''` or preset folder) */
-    defaultFolder?: string;
-    /** Default max input size in MB (defaults to `10`) */
-    defaultMaxSizeMB?: number;
-    /** Default allowed MIME formats */
-    defaultAllowedFormats?: string[];
-    /** Default max bounding box dimensions (defaults to `1920x1080`) */
-    defaultMaxDimensions?: ImageDimensions;
-    /**
-     * Project-specific named presets (merged over universal `STANDARD_PRESETS` unless `includeStandardPresets: false`).
-     * Preset names are automatically inferred in `uploader.uploadImage(file, { preset })`.
-     */
-    presets?: TPresets;
-    /** Include universal visual role presets (`thumbnail`, `avatar`, `card`, `cover`, `hero`, `logo`, `original`). Defaults to `true`. */
-    includeStandardPresets?: boolean;
-    /** Custom storage path generator for full control over bucket/folder/filename layout */
-    pathGenerator?: StoragePathGenerator;
-    /** Optional database/analytics hook invoked after each successful upload */
-    onUploadRecord?: UploadRecordHook;
-    /** Wait for `onUploadRecord` before returning (defaults to `false` best-effort) */
-    awaitRecordHook?: boolean;
-    /** Max concurrent Sharp + LQIP image processing pipelines (defaults to `2`) */
-    concurrency?: number;
-    /** Timeout per Sharp optimization job in ms (defaults to `60000`) */
-    optimizationTimeoutMs?: number;
-    /** Timeout per LQIP/blur generation job in ms (defaults to `30000`) */
-    blurTimeoutMs?: number;
-    /** Generate compact BlurHash strings by default on every upload */
-    includeBlurHash?: boolean;
-}
-type InferredPresetKey<TPresets extends Record<string, UploadPresetConfig>, TIncludeStandard extends boolean = true> = (keyof TPresets & string) | (TIncludeStandard extends false ? never : StandardPresetName) | (string & {});
-interface ImageUploader<TPreset extends string = string> {
-    uploadImage(file: File | {
-        buffer: Buffer;
-        name?: string;
-        type: string;
-        size?: number;
-    }, options?: ImageUploadOptions<TPreset>): Promise<UploadedImageData>;
-    processBuffer(buffer: Buffer, options?: ProcessImageBufferOptions): Promise<ProcessedImageBufferResult>;
-    deleteImage(path: string, bucket?: string): Promise<void>;
-    deleteByUrl(url: string): Promise<boolean>;
-    resolvePreset(presetName?: string): UploadPresetConfig | undefined;
-}
-
 declare function processImageBuffer(originalBuffer: Buffer, options?: ProcessImageBufferOptions): Promise<ProcessedImageBufferResult>;
 
 declare function createImageUploader<TPresets extends Record<string, UploadPresetConfig> = Record<string, UploadPresetConfig>>(options: ImageUploaderOptions<TPresets>): ImageUploader<InferredPresetKey<TPresets>>;
@@ -153,67 +37,106 @@ interface UploadWithCollisionRetryResult {
 }
 /**
  * Determines whether a storage error represents a filename or object collision.
- * Matches `already exists` or `EEXIST`, while strictly excluding `does not exist`
- * (e.g. non-existent buckets, directories, or missing keys).
+ * Matches `already exists`, `EEXIST`, or HTTP 412 Precondition Failed, while strictly
+ * excluding `does not exist` (e.g. non-existent buckets, directories, or missing keys).
  */
 declare function isCollisionError(e: unknown): boolean;
 /**
  * Uploads optimized image bytes to the storage backend with automatic filename
- * collision retries (or immediate `upsert: true` fallback when `customFilename` is set).
+ * collision retries. Server-side `customFilename` uses `upsert: true`, while
+ * client-supplied `customFilename` (`isClientFilename: true`) never upserts and
+ * appends a unique suffix on collision.
  */
 declare function uploadWithCollisionRetry(params: UploadWithCollisionRetryParams): Promise<UploadWithCollisionRetryResult>;
 interface MirrorBufferLocallyOptions {
     buffer: Buffer | Uint8Array;
     filename: string;
+    storagePath?: string;
     fallbackUrl: string;
     mirrorDir?: string;
     publicUrlBase?: string;
 }
 /**
  * Mirrors an uploaded image buffer to a local directory when `mirrorDir` is configured.
- * Safely swallows read-only filesystem errors on serverless runtimes and resolves
- * `publicUrlBase` when local mirroring succeeds.
+ * Uses non-blocking `fs/promises` I/O, safely swallows read-only filesystem errors on
+ * serverless runtimes, and resolves `publicUrlBase` when local mirroring succeeds.
  */
-declare function mirrorBufferLocally(options: MirrorBufferLocallyOptions): string;
+declare function mirrorBufferLocally(options: MirrorBufferLocallyOptions): Promise<string>;
 
-interface UploadHttpHandlerOptions<TPreset extends string = string> {
-    uploader: ImageUploader<TPreset>;
-    /**
-     * Optional authorization check. Return `false` or throw to reject with 401.
-     */
-    authorize?: (request: Request) => boolean | Promise<boolean>;
-    /**
-     * Optional whitelist of allowed preset names.
-     */
-    allowedPresets?: string[];
-    /**
-     * Allow clients to override `bucket` via FormData. Defaults to `false` for security.
-     */
-    allowClientBucketOverride?: boolean;
+interface GenerateImageVariantsParams {
+    sourceBuffer: Buffer;
+    format: ImageOutputFormat;
+    quality?: number;
+    effort?: number;
+    limitInputPixels?: number;
+    mainWidth: number;
+    mainHeight: number;
+    mainUrl: string;
+    baseStoragePath: string;
+    baseFilename: string;
+    bucket: string;
+    storage: StorageAdapter;
+    variantWidths?: number[];
+    upsert?: boolean;
+    contentHash?: string;
+    metadata?: Record<string, string>;
+    mirrorDir?: string;
+    publicUrlBase?: string;
 }
-declare class UploadValidationError extends Error {
-    readonly status = 400;
-    constructor(message: string);
+interface GeneratedVariantsResult {
+    variants: ImageVariant[];
+    srcSet?: string;
+}
+declare function buildVariantStoragePath(basePath: string, width: number): string;
+declare function generateImageVariants(params: GenerateImageVariantsParams): Promise<GeneratedVariantsResult>;
+
+type SniffedImageFormat = 'jpeg' | 'png' | 'gif' | 'webp' | 'avif' | 'heif' | 'tiff' | 'bmp' | 'ico' | 'svg';
+interface SniffedFormatResult {
+    format: SniffedImageFormat;
+    mime: string;
 }
-declare function isClientValidationError(error: unknown): boolean;
 /**
- * Standard Web Fetch (`Request` -> `Response`) upload & delete route handlers.
- * Works across Next.js App Router, Remix, React Router, SvelteKit, Astro, Hono, and Node Fetch servers.
+ * Inspects magic bytes of a buffer to determine its true image format,
+ * independent of any client-supplied MIME type or file extension.
  */
-declare function createUploadHttpHandler<TPreset extends string = string>(options: UploadHttpHandlerOptions<TPreset>): {
-    POST: (request: Request) => Promise<Response>;
-    DELETE: (request: Request) => Promise<Response>;
-};
+declare function sniffImageFormat(input: Buffer | Uint8Array): SniffedFormatResult | null;
+declare function assertMagicBytesAllowed(buffer: Buffer | Uint8Array, allowedFormats: string[], allowSvg?: boolean): SniffedFormatResult;
 
+declare const DEFAULT_MAX_SVG_BYTES: number;
+interface SanitizeSvgOptions {
+    maxBytes?: number;
+}
+/**
+ * Dependency-free SVG sanitizer.
+ * Strips `<script>`, `<foreignObject>`, `<iframe|embed|object>`, `<!DOCTYPE>`/`<!ENTITY>`,
+ * custom XML entities, `on*` event attributes, and non-fragment / non-raster-data `href`s.
+ */
+declare function sanitizeSvg(input: Buffer | string, options?: SanitizeSvgOptions): Buffer;
+
+declare class SemaphoreQueueFullError extends Error {
+    readonly status = 503;
+    constructor(message?: string);
+}
+interface SemaphoreOptions {
+    maxQueue?: number;
+}
+interface SemaphoreRunOptions {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+    label?: string;
+}
 declare class AsyncSemaphore {
     private readonly concurrency;
     private activeCount;
+    private readonly maxQueue?;
     private readonly queue;
-    constructor(concurrency: number);
-    run<T>(task: () => Promise<T>): Promise<T>;
+    constructor(concurrency: number, options?: SemaphoreOptions | number);
+    get active(): number;
+    get pending(): number;
+    run<T>(task: () => Promise<T>, options?: SemaphoreRunOptions): Promise<T>;
     private acquire;
     private release;
 }
 declare function withTimeout<T>(task: Promise<T>, timeoutMs: number, label: string): Promise<T>;
 
-export { AsyncSemaphore, BLUR_PLACEHOLDER_FALLBACK_WIDTH, BLUR_PLACEHOLDER_MAX_CHARS, BLUR_PLACEHOLDER_QUALITY, BLUR_PLACEHOLDER_WIDTH, type BlurHashResult, type ColorSamplingMode, EDGE_COLOR_FALLBACK, EDGE_WHITE_FALLBACK, type EdgeColorSet, type EdgeKey, type GenerateBlurOptions, type GeneratedStorageTarget, type ImageUploader, type ImageUploaderOptions, type InferredPresetKey, type MirrorBufferLocallyOptions, type OptimizeImageOptions, type OptimizedImageResult, PRIMARY_AVIF_EFFORT, type ProcessImageBufferOptions, type ProcessedImageBufferResult, RETRY_AVIF_EFFORT, type StoragePathContext, type StoragePathGenerator, type UploadHttpHandlerOptions, UploadValidationError, type UploadWithCollisionRetryParams, type UploadWithCollisionRetryResult, WHITE_DOMINANCE_RATIO, blendEdgeColors, createDefaultPathGenerator, createImageUploader, createUploadHttpHandler, encodeBlurHashString, extractEdgeColorsFromBuffer, extractEnhancedColorFromBuffer, formatToExtension, generateBlurHash, generateBlurPlaceholder, isClientValidationError, isCollisionError, mirrorBufferLocally, optimizeImage, processImageBuffer, sanitizeSegment, uploadWithCollisionRetry, withTimeout };
+export { AsyncSemaphore, BlurHashResult, ColorSamplingMode, DEFAULT_MAX_SVG_BYTES, EdgeColorSet, GenerateBlurOptions, type GenerateImageVariantsParams, GeneratedStorageTarget, type GeneratedVariantsResult, ImageUploader, ImageUploaderOptions, InferredPresetKey, type MirrorBufferLocallyOptions, OptimizeImageOptions, OptimizedImageResult, ProcessImageBufferOptions, ProcessedImageBufferResult, type SanitizeSvgOptions, type SemaphoreOptions, SemaphoreQueueFullError, type SemaphoreRunOptions, type SniffedFormatResult, type SniffedImageFormat, StoragePathContext, StoragePathGenerator, type UploadWithCollisionRetryParams, type UploadWithCollisionRetryResult, assertMagicBytesAllowed, blendEdgeColors, buildVariantStoragePath, computeEdgeColorSet, createDefaultPathGenerator, createImageUploader, encodeBlurHashString, extractEdgeColorsFromBuffer, extractEnhancedColorFromBuffer, formatToExtension, generateBlurHash, generateBlurPlaceholder, generateImageVariants, isCollisionError, mirrorBufferLocally, optimizeImage, processImageBuffer, sanitizeSegment, sanitizeSvg, sniffImageFormat, uploadWithCollisionRetry, withTimeout };