@warlock.js/core 5.29.0 → 5.31.0

package/esm/http/types.d.mts

@@ -1,13 +1,19 @@
 import { HttpRateLimitConfig } from "./build-rate-limit-options.mjs";
+import { StreamQueueOptions } from "./bounded-stream-queue.mjs";
+import { HttpLoggingConfig } from "./request-log-snapshot.mjs";
 import { Response } from "./response.mjs";
 import { CspConfig } from "./csp.mjs";
+import { HttpErrorMapper } from "./error-mapper.mjs";
 import { HttpTracingConfig } from "./tracing/tracing.type.mjs";
 import { Middleware } from "../router/types.mjs";
+import { FastifyHttpOptions } from "fastify";
 import { CookieSerializeOptions } from "@fastify/cookie";
 import { FastifyCorsOptions } from "@fastify/cors";
+import { Server } from "node:http";
+import { SecureServerOptions } from "node:http2";
 import React from "react";
 
-//#region ../core/src/http/types.d.ts
+//#region ../../packages/core/src/http/types.d.ts
 type RequestEvent = "executingMiddleware" | "executedMiddleware" | "executingAction" | "executedAction";
 /**
  * Private, server-only, per-request data bag — `request.locals`.
@@ -175,10 +181,43 @@ interface PartialMiddleware {
    */
   middleware: Middleware[];
 }
+/**
+ * Options for the underlying Fastify server, passed through by
+ * `http.serverOptions`. Includes `http`, the options Node's
+ * `http.createServer()` receives (for example `maxHeaderSize`).
+ *
+ * Framework-owned settings (`trustProxy`, `bodyLimit`,
+ * `gracefulShutdown.forceCloseConnections`) have their own `http.*` keys;
+ * setting them here as well overrides those keys.
+ */
+type HttpServerOptions = Omit<FastifyHttpOptions<Server>, "http2"> & {
+  /** Enable HTTP/2 while retaining the framework's HTTP-compatible reply API. */http2?: boolean;
+  https?: SecureServerOptions;
+  http2SessionTimeout?: number;
+};
 /**
  * Http Configurations list
  */
 interface HttpConfigurations {
+  /**
+   * Options for the underlying Fastify server, applied when it is created.
+   *
+   * Node's own HTTP server options go under `http`. The request header size
+   * limit, for example, is `serverOptions.http.maxHeaderSize` (Node's default
+   * is 16KB); a top-level `maxHeaderSize` is not a Fastify option and is
+   * ignored.
+   *
+   * @example
+   * ```ts
+   * const httpConfigurations: HttpConfigurations = {
+   *   serverOptions: {
+   *     http: { maxHeaderSize: 32 * 1024 },
+   *     keepAliveTimeout: 10_000,
+   *   },
+   * };
+   * ```
+   */
+  serverOptions?: HttpServerOptions;
   /**
    * Status used when a Cascade model fails validation during a database write.
    * The default is 500 because request input has already been validated before
@@ -188,6 +227,21 @@ interface HttpConfigurations {
    * @default 500
    */
   modelValidationErrorStatus?: number;
+  /**
+   * Map errors that are not an `HttpError` to an HTTP status (and optional
+   * message/payload), so domain errors shared with non-HTTP processes need not
+   * extend Core's error classes. Return `undefined` to keep the default
+   * handling. See {@link HttpErrorMapper}.
+   */
+  errorMapper?: HttpErrorMapper;
+  /**
+   * In `warlock dev`, warn once per route about POST/PUT/PATCH/DELETE routes
+   * that have no auth middleware and no `public: true`. Development only;
+   * production never checks. Set `false` to silence the warning entirely.
+   *
+   * @default true
+   */
+  warnUnguardedRoutes?: boolean;
   /**
    * Server port
    */
@@ -196,6 +250,13 @@ interface HttpConfigurations {
    * Log requests
    */
   log?: boolean;
+  /**
+   * What request log entries carry of each request's input. Entries carry a
+   * bounded `RequestLogSnapshot`, never the `Request`/`Response`
+   * instances; credential-bearing query values are masked in its URL.
+   * A route's own `logging` option overrides these defaults.
+   */
+  logging?: HttpLoggingConfig;
   /**
    * Cors configurations
    */
@@ -406,6 +467,13 @@ interface HttpConfigurations {
      * @default "/ready"
      */
     readinessPath?: string;
+    /**
+     * Include built-in liveness/readiness probes in the global rate-limit policy.
+     * Leave false so client traffic cannot exhaust infrastructure probe quotas.
+     *
+     * @default false
+     */
+    rateLimit?: boolean;
   };
   /**
    * Host
@@ -435,32 +503,122 @@ interface HttpConfigurations {
    */
   tracing?: HttpTracingConfig;
 }
+/**
+ * Options for `response.stream()`.
+ */
+type ResponseStreamOptions = StreamQueueOptions & {
+  /** Application/cache headers override defaults before flushing; framing and connection headers are ignored. */headers?: Record<string, string>;
+  /**
+   * How many of the most recent chunks (from `send()`, `write()` and
+   * `render()`) to keep on `response.body` after `end()`, for logging and
+   * debugging. Written chunks are otherwise not kept, so a long-lived stream
+   * does not grow with its own history.
+   *
+   * @default 0
+   */
+  retainChunks?: number;
+};
 type ResponseStreamController = {
   /**
-   * Send data to the client
+   * Send data to the client. Does not wait for the client; for long-lived or
+   * high-volume streams use `write()` (or `drain()`) so the producer slows
+   * down to the client's pace instead of buffering. A silent no-op after the
+   * client disconnected; throws after `end()`.
+   */
+  send: (data: string | Uint8Array) => void; /** Bounded synchronous write; false when closed or overflow rejects this chunk. */
+  enqueue: (data: string | Uint8Array) => boolean;
+  /**
+   * Send data and wait until the transport can take more. Resolves `true`
+   * when it can, `false` when the stream ended or the client disconnected —
+   * stop producing then. In drop mode, true means the stream is ready to continue;
+   * inspect dropped to detect rejected output and schedule a resync.
    */
-  send: (data: string) => void;
+  write: (data: string | Uint8Array) => Promise<boolean>;
   /**
    * Render a view and send it to the client
    */
   render: (view: React.ReactNode) => void;
+  /**
+   * Wait until output buffered for the client has been flushed. Resolves
+   * `true` immediately when nothing is backed up, `false` when the stream
+   * ended or the client disconnected.
+   */
+  drain: () => Promise<boolean>;
   /**
    * End the stream
    */
   end: () => void;
   /**
-   * Detect whether stream is ended
+   * Register a handler to be called when the client disconnects
+   */
+  onDisconnect: (handler: () => void) => ResponseStreamController;
+  /**
+   * Aborted when the client disconnects (not when `end()` is called). Pass it
+   * to the work feeding the stream.
+   */
+  signal: AbortSignal;
+  /**
+   * Whether the transport is currently holding more than its high-water mark.
+   */
+  backpressured: boolean; /** Chunks/events/comments rejected by onOverflow: "drop", including send/write/render paths. */
+  readonly dropped: number;
+  /**
+   * Detect whether stream is ended (by `end()` or a client disconnect)
    */
   ended: boolean;
 };
+/**
+ * Options for `response.sse()`.
+ */
+type ResponseSSEOptions = StreamQueueOptions & {
+  /** Application/cache headers override defaults before flushing; framing and connection headers are ignored. */headers?: Record<string, string>;
+  /**
+   * How many of the most recent events to keep on `response.body` after
+   * `end()`, for logging and debugging. Sent events are otherwise not kept,
+   * so a long-lived stream does not grow with its own history.
+   *
+   * @default 0
+   */
+  retainEvents?: number;
+};
+/** Wire serialization for one SSE event. Raw strings are split into safe data lines. */
+type ResponseSSEMessageOptions = {
+  raw?: boolean;
+};
 type ResponseSSEController = {
   /**
-   * Send an SSE event to the client
+   * Send an SSE event to the client. Does not wait for the client; for
+   * long-lived or high-volume streams use `write()` (or `drain()`) so the
+   * producer slows down to the client's pace instead of buffering.
    * @param event - Event name
    * @param data - Event data (will be JSON stringified)
    * @param id - Optional event ID for client-side Last-Event-ID tracking
    */
-  send: (event: string, data: any, id?: string) => ResponseSSEController;
+  send: (event: string | undefined, data: any, id?: string, options?: ResponseSSEMessageOptions) => ResponseSSEController; /** Bounded synchronous event; undefined event omits the event field. */
+  enqueue: (event: string | undefined, data: unknown, id?: string, options?: ResponseSSEMessageOptions) => boolean;
+  /**
+   * Send an SSE event and wait until the transport can take more.
+   * Resolves `true` when it can, `false` when the stream ended or the client
+   * disconnected — stop producing then. In drop mode, true means ready to continue;
+   * inspect dropped to detect rejected output and schedule a resync.
+   */
+  write: (event: string | undefined, data: any, id?: string, options?: ResponseSSEMessageOptions) => Promise<boolean>;
+  /**
+   * Wait until output buffered for the client has been flushed. Resolves
+   * `true` immediately when nothing is backed up, `false` when the stream
+   * ended or the client disconnected.
+   */
+  drain: () => Promise<boolean>;
+  /**
+   * Aborted when the client disconnects (not when `end()` is called). Pass it
+   * to the work feeding the stream.
+   */
+  signal: AbortSignal;
+  /**
+   * Whether the transport is currently holding more than its high-water mark.
+   */
+  backpressured: boolean; /** Chunks/events/comments rejected by onOverflow: "drop", including send/write/render paths. */
+  readonly dropped: number;
   /**
    * Send a comment to keep the connection alive (invisible to client)
    */
@@ -480,5 +638,5 @@ type ResponseSSEController = {
   ended: boolean;
 };
 //#endregion
-export { DecodedAccessToken, HttpConfigurations, PartialMiddleware, RequestEvent, RequestLocals, ResponseEvent, ResponseSSEController, ResponseStreamController, ReturnedResponse };
+export { DecodedAccessToken, HttpConfigurations, HttpServerOptions, PartialMiddleware, RequestEvent, RequestLocals, ResponseEvent, ResponseSSEController, ResponseSSEMessageOptions, ResponseSSEOptions, ResponseStreamController, ResponseStreamOptions, ReturnedResponse };
 //# sourceMappingURL=types.d.mts.map

package/esm/http/types.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.mts","names":[],"sources":["../../../../../../../core/src/http/types.ts"],"mappings":";;;;;;;;;;KASY,YAAA;;;AAAZ;;;;AAAwB;AA0BxB;;;;AAca;AAeb;;;;AACU;AAMV;;;;;;UApCiB,aAAA;EAoDL;;;;;;;;;;;;;EAtCV,WAAW;AAAA;;;;AAmDY;AAiEzB;;;;;;;;KArGY,kBAAA;EACV,QAAQ;AAAA;;;;KAME,gBAAA;;;;AAIR;;;;EAIA,OAAA,CAAQ,QAAA;;;;EAIR,MAAA;;;;EAIA,OAAA,CAAQ,MAAA;;;;;;;;EAQR,OAAA;;;;KAKQ,aAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqViB;AAG7B;;;;;;;;;;;;;;AAmBA;;;AAAA;;;;;;;;;;;;UA1SiB,iBAAA;EAqTe;;;;EAhT9B,MAAA;EAyTuC;;;AAIlC;;EAvTL,WAAA;;;;EAIA,UAAA,EAAY,UAAU;AAAA;;;;UAMP,kBAAA;;;;;;;;;EASf,0BAAA;;;;EAIA,IAAA;;;;EAIA,GAAA;;;;EAIA,IAAA,GAAO,kBAAA;;;;;;EAMP,eAAA;;;;;EAKA,SAAA;;;;;;IAME,KAAA;;;;;;IAMA,MAAA;;;;;;IAMA,SAAA;EAAA;;;;;;;;;;EAWF,SAAA;;;;;;;;;;;;;;;;;;;;EAoBA,UAAA,mCAA6C,OAAA,UAAiB,GAAA;EAC9D,OAAA;;;;IAIE,MAAA;;;;IAIA,OAAA,GAAU,sBAAA;EAAA;;;;;;;;;;EAWZ,GAAA,GAAM,SAAA;;;;EAIN,SAAA,GAAY,mBAAA;;;;;;;;EAQZ,SAAA;;;;;;IAME,MAAA;;;;IAIA,SAAA;;;;;;;IAOA,OAAA;EAAA;;;;EAKF,WAAA;;;;;;IAME,GAAA;;;;;;IAMA,UAAA;;;;;;;IAOA,OAAA;;;;IAIA,MAAA;EAAA;;;;EAKF,WAAA;;;;;;;IAOE,OAAA;;;;;;IAMA,SAAA;;;;;;IAMA,UAAA;EAAA;;;;EAKF,gBAAA;;;;;;;IAOE,OAAA;;;;;;;;IAQA,qBAAA;EAAA;;;;EAKF,MAAA;;;;;;IAME,OAAA;;;;;;;IAOA,IAAA;;;;;;;IAOA,aAAA;EAAA;;;;EAKF,IAAA;;;;EAIA,UAAA;;;;IAIE,GAAA,GAAM,UAAA;;;;IAIN,IAAA,GAAO,iBAAA;;;;IAIP,MAAA,GAAS,iBAAA;EAAA;;;;;;EAOX,OAAA,GAAU,iBAAA;AAAA;AAAA,KAGA,wBAAA;;;;EAIV,IAAA,GAAO,IAAA;;;;EAIP,MAAA,GAAS,IAAA,EAAM,KAAA,CAAM,SAAS;;;;EAI9B,GAAA;;;;EAIA,KAAA;AAAA;AAAA,KAGU,qBAAA;;;;;;;EAOV,IAAA,GAAO,KAAA,UAAe,IAAA,OAAW,EAAA,cAAgB,qBAAA;;;;EAIjD,OAAA,GAAU,OAAA,aAAoB,qBAAA;;;;EAI9B,GAAA,QAAW,qBAAA;;;;;EAKX,YAAA,GAAe,OAAA,iBAAwB,qBAAA;;;;EAIvC,KAAA;AAAA"}
+{"version":3,"file":"types.d.mts","names":[],"sources":["../../../../../../../../packages/core/src/http/types.ts"],"mappings":"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"}

package/esm/http/uploaded-file.d.mts

@@ -1,12 +1,12 @@
 import { StorageFile } from "../storage/storage-file.mjs";
-import { StorageDriverName } from "../storage/types.mjs";
 import { ScopedStorage } from "../storage/scoped-storage.mjs";
+import { StorageDriverName } from "../storage/types.mjs";
 import { storage } from "../storage/storage.mjs";
 import { Image, ImageFormat, ImageTransformOptions } from "../image/image.mjs";
 import { ImageTransformCallback, PrefixConfig, SaveAsOptions, SaveOptions, UploadedFileImageOptions } from "./uploads-types.mjs";
 import { MultipartFile } from "@fastify/multipart";
 
-//#region ../core/src/http/uploaded-file.d.ts
+//#region ../../packages/core/src/http/uploaded-file.d.ts
 type UploadedFileMetadata = {
   name: string;
   mimeType: string;

package/esm/http/uploaded-file.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"uploaded-file.d.mts","names":[],"sources":["../../../../../../../core/src/http/uploaded-file.ts"],"mappings":"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"}
+{"version":3,"file":"uploaded-file.d.mts","names":[],"sources":["../../../../../../../../packages/core/src/http/uploaded-file.ts"],"mappings":";;;;;;;;;KAiBK,oBAAA;EACH,IAAA;EACA,QAAA;EACA,SAAA;EACA,IAAA;EACA,KAAA;EACA,MAAA;AAAA;;;;;;;;;KAWU,gBAAA;EACV,IAAA;EACA,QAAA;EACA,SAAA;EACA,OAAA;EACA,OAAA;EACA,OAAA;EACA,IAAA;AAAA;;;;KAMU,qBAAA;EANV;;AAAI;AAMN;;EAME,gBAAA;EAN+B;;;;;EAa/B,iBAAA;EAsCW;;;;;EA/BX,OAAA;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cA+BW,YAAA;EAAA,mBA4C2B,QAAA,EAAU,aAAA;EA4ff;;;;EAAA,UAniBvB,mBAAA,GAAsB,MAAA;EAylBI;;;;;EAllB7B,IAAA;EAgC+B;;;;EAAA,UA1B5B,QAAA,EAAU,aAAA;EAAV;;;;EAAA,UAMA,YAAA,GAAe,WAAA;EAMA;;;;EAAA,UAAf,aAAA,EAAe,wBAAA;EAcuB;;;;EAAA,UARtC,gBAAA,GAAmB,qBAAA,GAAwB,sBAAA;EAgDxC;;;;;;cAxCyB,QAAA,EAAU,aAAA;EAwEjB;;;;;EAAA,IAzDpB,IAAA;EA8GA;;;;;EAAA,IArGA,QAAA;EAsKJ;;;;;EAAA,IA7JI,SAAA;EA6LC;;;EAtLC,QAAA,IAAY,OAAA,CAAQ,oBAAA;EA2OgB;;;;;EArNpC,IAAA,IAAQ,OAAA;EAwPM;;;;;EA9Od,MAAA,IAAU,OAAA,CAAQ,MAAA;EAwQwB;;;EAAA,IAxP5C,OAAA;EAmT0B;;;EAAA,IA5S1B,OAAA;EA0US;;;EAAA,IAnUT,OAAA;EAmU6D;;;;;;;;;;;;;;;EA5SjE,GAAA,CAAI,MAAA,EAAQ,iBAAA;EAiaT;;;;;;;;;;;;;;;EAzYH,MAAA,CAAO,KAAA,UAAe,MAAA;EA+eR;;;;;;;;;;;;;;EA5dd,OAAA,CAAQ,KAAA;;;;;;;;;;;;;;;EAsBR,MAAA,CAAO,MAAA,EAAQ,WAAA;;;;;;;;;;;;EAgBf,MAAA,CAAO,OAAA;;;;;;;;;;;;EAgBP,IAAA,CAAK,KAAA;;;;;;;;;;;EAkBL,SAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;EAmCA,SAAA,CAAU,MAAA,EAAQ,qBAAA,GAAwB,sBAAA;;;;;;;;;;;;;;;;;;EAsBpC,OAAA,IAAW,OAAA,CAAQ,KAAA;;;;;;EAanB,UAAA,IAAc,OAAA;IAAU,KAAA;IAAgB,MAAA;EAAA;;;;;;;;;;;;;;;EA0BxC,QAAA,CAAS,OAAA,EAAS,qBAAA,GAAwB,OAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA2D1C,IAAA,CAAK,SAAA,UAAmB,OAAA,GAAU,WAAA,GAAc,OAAA,CAAQ,WAAA;;;;;;;;;;;;;;;;;EA8BxD,MAAA,CAAO,QAAA,UAAkB,OAAA,GAAU,aAAA,GAAgB,OAAA,CAAQ,WAAA;;;;;;MAc7D,WAAA,IAAe,WAAA;;;;;YAYV,cAAA,CACd,QAAA,UACA,MAAA,GAAS,iBAAA,GACR,OAAA,CAAQ,WAAA;;;;;YA0BK,mBAAA,IAAuB,OAAA,CAAQ,MAAA;;;;;YA4BrC,iBAAA,CAAkB,GAAA,EAAK,KAAA,GAAQ,KAAA;;;;;YAkC/B,aAAA;;;;;YAQA,cAAA,CAAe,MAAA,GAAS,iBAAA,GAAoB,aAAA,UAAuB,OAAA;;;;;YAYnE,eAAA,CAAgB,OAAA,GAAU,WAAA;;;;;YAwB1B,aAAA,CAAc,MAAA,GAAS,YAAA;;;;;YAiDvB,gBAAA,CAAiB,MAAA,UAAgB,EAAA;;;;;YASjC,UAAA,CAAW,MAAA;;;;;YAQX,aAAA,CAAc,SAAA,UAAmB,MAAA,UAAgB,QAAA;;;;;YAiBjD,iBAAA;;;;;YAiBA,gBAAA;;;;;YAgBA,uBAAA,CAAwB,QAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;EA6C3B,MAAA,IAAU,gBAAA;;;;;;;EAkBJ,QAAA,IAAY,OAAA;AAAA"}

package/esm/http/uploaded-file.mjs

@@ -1,14 +1,14 @@
 import { sanitizePath } from "../utils/paths.mjs";
+import { uploadsConfig } from "./uploads-config.mjs";
 import { storage } from "../storage/storage.mjs";
 import "../storage/index.mjs";
 import { Image } from "../image/image.mjs";
 import "../image/index.mjs";
-import { uploadsConfig } from "./uploads-config.mjs";
 import path from "path";
 import { Random } from "@mongez/reinforcements";
 import dayjs from "dayjs";
 
-//#region ../core/src/http/uploaded-file.ts
+//#region ../../packages/core/src/http/uploaded-file.ts
 /**
 * UploadedFile - Handles multipart file uploads with storage and image integration
 *

package/esm/http/uploaded-file.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"uploaded-file.mjs","names":[],"sources":["../../../../../../../core/src/http/uploaded-file.ts"],"sourcesContent":["import type { MultipartFile } from \"@fastify/multipart\";\nimport { Random } from \"@mongez/reinforcements\";\nimport dayjs from \"dayjs\";\nimport path from \"path\";\nimport { Image, type ImageFormat, type ImageTransformOptions } from \"../image\";\nimport { storage, type ScopedStorage, type StorageDriverName, type StorageFile } from \"../storage\";\nimport { sanitizePath } from \"../utils/paths\";\nimport { uploadsConfig } from \"./uploads-config\";\nimport type {\n  FileNamingStrategy,\n  ImageTransformCallback,\n  PrefixConfig,\n  SaveAsOptions,\n  SaveOptions,\n  UploadedFileImageOptions,\n} from \"./uploads-types\";\n\ntype UploadedFileMetadata = {\n  name: string;\n  mimeType: string;\n  extension: string;\n  size: number;\n  width?: number;\n  height?: number;\n};\n\n/**\n * What an `UploadedFile` looks like on the wire.\n *\n * Every member is knowable **without reading the file**, which is what lets\n * {@link UploadedFile.toJSON} be synchronous — see the note there. `size` is\n * the one exception and it is optional for exactly that reason: present when\n * the file has already been buffered, absent otherwise, never guessed.\n */\nexport type UploadedFileJson = {\n  name: string;\n  mimeType: string;\n  extension: string;\n  isImage: boolean;\n  isVideo: boolean;\n  isAudio: boolean;\n  size?: number;\n};\n\n/**\n * Options for validating file before saving\n */\nexport type FileValidationOptions = {\n  /**\n   * List of allowed MIME types\n   *\n   * @example [\"image/jpeg\", \"image/png\", \"image/webp\"]\n   */\n  allowedMimeTypes?: string[];\n\n  /**\n   * List of allowed file extensions (without dot)\n   *\n   * @example [\"jpg\", \"jpeg\", \"png\", \"webp\"]\n   */\n  allowedExtensions?: string[];\n\n  /**\n   * Maximum file size in bytes\n   *\n   * @example 5 * 1024 * 1024 // 5MB\n   */\n  maxSize?: number;\n};\n\n/**\n * UploadedFile - Handles multipart file uploads with storage and image integration\n *\n * Provides a fluent API for validating, transforming, and saving uploaded files\n * to various storage drivers (local, S3, R2, etc.).\n *\n * @example\n * ```typescript\n * // Simple save with random name\n * const file = await uploadedFile.save(\"avatars\");\n *\n * // Original name with date prefix\n * const file = await uploadedFile.save(\"avatars\", {\n *   name: \"original\",\n *   prefix: { format: \"yyyy/mm/dd\", as: \"directory\" }\n * });\n *\n * // With image transformations\n * const file = await uploadedFile\n *   .resize(800, 600)\n *   .quality(85)\n *   .format(\"webp\")\n *   .save(\"avatars\");\n *\n * // Different storage driver\n * const file = await uploadedFile.use(\"s3\").save(\"avatars\");\n * ```\n */\nexport class UploadedFile {\n  /**\n   * File buffered content\n   * @internal\n   */\n  protected bufferedFileContent?: Buffer;\n\n  /**\n   * Upload file hash (SHA-256)\n   *\n   * Populated after file is saved.\n   */\n  public hash = \"\";\n\n  /**\n   * Selected storage driver\n   * @internal\n   */\n  protected _storage: ScopedStorage = storage;\n\n  /**\n   * Saved StorageFile reference\n   * @internal\n   */\n  protected _storageFile?: StorageFile;\n\n  /**\n   * Queued image options (high-level API)\n   * @internal\n   */\n  protected _imageOptions: UploadedFileImageOptions = {};\n\n  /**\n   * Full transform options or callback\n   * @internal\n   */\n  protected _transformConfig?: ImageTransformOptions | ImageTransformCallback;\n\n  /**\n   * Create a new UploadedFile instance\n   *\n   * @param fileData - Multipart file data from Fastify\n   * @throws Error if file data is invalid\n   */\n  public constructor(protected readonly fileData: MultipartFile) {\n    if (!fileData?.filename) {\n      throw new Error(\"Invalid file data: filename is required\");\n    }\n  }\n\n  // ============================================================\n  // File Properties\n  // ============================================================\n\n  /**\n   * Get file name (sanitized)\n   *\n   * Returns the original filename with special characters removed/replaced.\n   */\n  public get name(): string {\n    return sanitizePath(this.fileData.filename);\n  }\n\n  /**\n   * Get file MIME type\n   *\n   * @example \"image/jpeg\", \"application/pdf\"\n   */\n  public get mimeType(): string {\n    return this.fileData.mimetype;\n  }\n\n  /**\n   * Get file extension (lowercase, without dot)\n   *\n   * @example \"jpg\", \"png\", \"pdf\"\n   */\n  public get extension(): string {\n    return path.extname(this.fileData.filename).replace(\".\", \"\").toLowerCase();\n  }\n\n  /**\n   * Get file metadata\n   */\n  public async metadata(): Promise<UploadedFileMetadata> {\n    const data: UploadedFileMetadata = {\n      name: this.name,\n      mimeType: this.mimeType,\n      extension: this.extension,\n      size: await this.size(),\n    };\n\n    if (this.isImage) {\n      const dimensions = await this.dimensions();\n      data.width = dimensions.width;\n      data.height = dimensions.height;\n    }\n\n    return data;\n  }\n\n  /**\n   * Get file size in bytes\n   *\n   * Buffers the file content if not already buffered.\n   */\n  public async size(): Promise<number> {\n    const file = await this.buffer();\n    return file.length;\n  }\n\n  /**\n   * Get file buffer\n   *\n   * Caches the buffer after first call for efficiency.\n   */\n  public async buffer(): Promise<Buffer> {\n    if (this.bufferedFileContent) {\n      return this.bufferedFileContent;\n    }\n\n    this.bufferedFileContent = await this.fileData.toBuffer();\n    return this.bufferedFileContent;\n  }\n\n  // ============================================================\n  // File Type Checks\n  // ============================================================\n\n  /**\n   * Check if file is an image based on MIME type\n   */\n  public get isImage(): boolean {\n    return this.mimeType.startsWith(\"image\");\n  }\n\n  /**\n   * Check if file is a video based on MIME type\n   */\n  public get isVideo(): boolean {\n    return this.mimeType.startsWith(\"video\");\n  }\n\n  /**\n   * Check if file is an audio based on MIME type\n   */\n  public get isAudio(): boolean {\n    return this.mimeType.startsWith(\"audio\");\n  }\n\n  // ============================================================\n  // Storage Driver Selection\n  // ============================================================\n\n  /**\n   * Select a specific storage driver for this upload\n   *\n   * Returns this instance for chaining. The driver is used\n   * when `save()` or `saveAs()` is called.\n   *\n   * @param driver - Driver name from storage configuration\n   * @returns This instance for chaining\n   *\n   * @example\n   * ```typescript\n   * await file.use(\"s3\").save(\"avatars\");\n   * await file.use(\"r2\").save(\"cdn/images\");\n   * ```\n   */\n  public use(driver: StorageDriverName): this {\n    this._storage = storage.use(driver) as ScopedStorage;\n    return this;\n  }\n\n  // ============================================================\n  // High-Level Image Transform API\n  // ============================================================\n\n  /**\n   * Resize the image before saving\n   *\n   * Only applies to image files. Non-image files ignore this.\n   *\n   * @param width - Target width in pixels\n   * @param height - Optional target height (maintains aspect ratio if omitted)\n   * @returns This instance for chaining\n   *\n   * @example\n   * ```typescript\n   * await file.resize(800).save(\"thumbnails\");\n   * await file.resize(400, 400).save(\"avatars\");\n   * ```\n   */\n  public resize(width: number, height?: number): this {\n    this._imageOptions.resize = { width, height };\n    return this;\n  }\n\n  /**\n   * Set image output quality\n   *\n   * Quality affects file size and visual fidelity.\n   * Only applies to formats that support quality (JPEG, WebP, AVIF).\n   *\n   * @param value - Quality value (1-100)\n   * @returns This instance for chaining\n   *\n   * @example\n   * ```typescript\n   * await file.quality(85).save(\"images\");\n   * ```\n   */\n  public quality(value: number): this {\n    if (value < 1 || value > 100) {\n      throw new Error(\"Quality must be between 1 and 100\");\n    }\n    this._imageOptions.quality = value;\n    return this;\n  }\n\n  /**\n   * Convert image to a specific format\n   *\n   * Changes the output format and updates the file extension accordingly.\n   *\n   * @param format - Target image format (jpeg, png, webp, avif, etc.)\n   * @returns This instance for chaining\n   *\n   * @example\n   * ```typescript\n   * await file.format(\"webp\").save(\"images\");\n   * await file.resize(800).format(\"avif\").quality(80).save(\"optimized\");\n   * ```\n   */\n  public format(format: ImageFormat): this {\n    this._imageOptions.format = format;\n    return this;\n  }\n\n  /**\n   * Rotate the image\n   *\n   * @param degrees - Rotation angle in degrees (positive = clockwise)\n   * @returns This instance for chaining\n   *\n   * @example\n   * ```typescript\n   * await file.rotate(90).save(\"rotated\");\n   * ```\n   */\n  public rotate(degrees: number): this {\n    this._imageOptions.rotate = degrees;\n    return this;\n  }\n\n  /**\n   * Apply blur effect to the image\n   *\n   * @param sigma - Blur intensity (default: 3, minimum: 0.3)\n   * @returns This instance for chaining\n   *\n   * @example\n   * ```typescript\n   * await file.blur(5).save(\"blurred\");\n   * ```\n   */\n  public blur(sigma = 3): this {\n    if (sigma < 0.3) {\n      throw new Error(\"Blur sigma must be at least 0.3\");\n    }\n    this._imageOptions.blur = sigma;\n    return this;\n  }\n\n  /**\n   * Convert image to grayscale (black and white)\n   *\n   * @returns This instance for chaining\n   *\n   * @example\n   * ```typescript\n   * await file.grayscale().save(\"bw-images\");\n   * ```\n   */\n  public grayscale(): this {\n    this._imageOptions.grayscale = true;\n    return this;\n  }\n\n  // ============================================================\n  // Full Transform Control\n  // ============================================================\n\n  /**\n   * Apply full image transformations\n   *\n   * Provides complete control over image processing. Can be used with:\n   * - An options object for predefined transforms\n   * - A callback function for chained operations\n   *\n   * @param config - Transform options or callback function\n   * @returns This instance for chaining\n   *\n   * @example\n   * ```typescript\n   * // Using options object\n   * await file.transform({\n   *   resize: { width: 800, fit: \"inside\" },\n   *   quality: 85\n   * }).save(\"images\");\n   *\n   * // Using callback for full control\n   * await file.transform(img =>\n   *   img.resize({ width: 800 })\n   *      .watermark(\"logo.png\", { gravity: \"southeast\" })\n   *      .sharpen()\n   * ).save(\"products\");\n   * ```\n   */\n  public transform(config: ImageTransformOptions | ImageTransformCallback): this {\n    this._transformConfig = config;\n    return this;\n  }\n\n  /**\n   * Get an Image instance for advanced manipulation\n   *\n   * Returns an Image instance from the file buffer for manual processing.\n   * Use this when you need operations not covered by the fluent API.\n   *\n   * @returns Promise resolving to Image instance\n   *\n   * @example\n   * ```typescript\n   * const img = await file.toImage();\n   * await img\n   *   .resize({ width: 800 })\n   *   .watermark(\"logo.png\", { gravity: \"southeast\" })\n   *   .save(\"path/to/output.jpg\");\n   * ```\n   */\n  public async toImage(): Promise<Image> {\n    return new Image(await this.buffer());\n  }\n\n  // ============================================================\n  // Image Metadata\n  // ============================================================\n\n  /**\n   * Get file width and height (only for images)\n   *\n   * @returns Dimensions object, or empty object if not an image\n   */\n  public async dimensions(): Promise<{ width?: number; height?: number }> {\n    if (!this.isImage) {\n      return {};\n    }\n\n    return new Image(await this.buffer()).dimensions();\n  }\n\n  // ============================================================\n  // Validation\n  // ============================================================\n\n  /**\n   * Validate file against the given options\n   *\n   * @param options - Validation rules\n   * @throws Error if validation fails\n   *\n   * @example\n   * ```typescript\n   * await file.validate({\n   *   allowedMimeTypes: [\"image/jpeg\", \"image/png\"],\n   *   maxSize: 5 * 1024 * 1024 // 5MB\n   * });\n   * ```\n   */\n  public async validate(options: FileValidationOptions): Promise<void> {\n    const { allowedMimeTypes, allowedExtensions, maxSize } = options;\n\n    if (allowedMimeTypes && !allowedMimeTypes.includes(this.mimeType)) {\n      throw new Error(\n        `Invalid file type: ${this.mimeType}. Allowed types: ${allowedMimeTypes.join(\", \")}`,\n      );\n    }\n\n    if (allowedExtensions && !allowedExtensions.includes(this.extension)) {\n      throw new Error(\n        `Invalid file extension: ${this.extension}. Allowed extensions: ${allowedExtensions.join(\", \")}`,\n      );\n    }\n\n    if (maxSize) {\n      const fileSize = await this.size();\n      if (fileSize > maxSize) {\n        throw new Error(`File too large: ${fileSize} bytes. Maximum allowed: ${maxSize} bytes`);\n      }\n    }\n  }\n\n  // ============================================================\n  // Save Operations\n  // ============================================================\n\n  /**\n   * Save the file to a directory with automatic naming\n   * Keep in mind to use only relative path to the root of storage\n   * If you are using local driver\n   * Uses the configured naming strategy and prefix options to generate\n   * the final path. Returns a StorageFile for accessing file metadata.\n   *\n   * @param directory - Target directory path\n   * @param options - Save options (name, prefix, driver, validate)\n   * @returns StorageFile instance with file metadata and operations\n   *\n   * @example\n   * ```typescript\n   * // Random name (default)\n   * await file.save(\"avatars\");\n   * // → avatars/x7k9m2p4.jpg\n   *\n   * // Original name\n   * await file.save(\"avatars\", { name: \"original\" });\n   * // → avatars/photo.jpg\n   *\n   * // With date directory\n   * await file.save(\"avatars\", {\n   *   prefix: { format: \"yyyy/mm/dd\", as: \"directory\" }\n   * });\n   * // → avatars/2025/12/21/x7k9m2p4.jpg\n   *\n   * // Original name with datetime prefix\n   * await file.save(\"avatars\", { name: \"original\", prefix: true });\n   * // → avatars/21-12-2025-16-45-30-photo.jpg\n   * ```\n   */\n  public async save(directory: string, options?: SaveOptions): Promise<StorageFile> {\n    // Validate if requested\n    if (options?.validate) {\n      await this.validate(options.validate);\n    }\n\n    // Resolve filename and prefix\n    const filename = this.resolveFilename(options);\n    const prefix = this.resolvePrefix(options?.prefix);\n    const location = this.buildLocation(directory, prefix, filename);\n\n    return this.saveToLocation(location, options?.driver);\n  }\n\n  /**\n   * Save the file to an explicit path\n   *\n   * Unlike `save()`, this method uses the exact path you provide.\n   * No automatic naming or prefix is applied.\n   *\n   * @param location - Full file path (directory + filename)\n   * @param options - Save options (driver, validate)\n   * @returns StorageFile instance with file metadata\n   *\n   * @example\n   * ```typescript\n   * await file.saveAs(\"avatars/profile-123.png\");\n   * await file.saveAs(\"products/2025/featured-image.webp\");\n   * ```\n   */\n  public async saveAs(location: string, options?: SaveAsOptions): Promise<StorageFile> {\n    // Validate if requested\n    if (options?.validate) {\n      await this.validate(options.validate);\n    }\n\n    return this.saveToLocation(location, options?.driver);\n  }\n\n  /**\n   * Get the StorageFile reference if file has been saved\n   *\n   * Returns undefined if file hasn't been saved yet.\n   */\n  public get storageFile(): StorageFile | undefined {\n    return this._storageFile;\n  }\n\n  // ============================================================\n  // Internal Helpers\n  // ============================================================\n\n  /**\n   * Execute save to the specified location\n   * @internal\n   */\n  protected async saveToLocation(\n    location: string,\n    driver?: StorageDriverName,\n  ): Promise<StorageFile> {\n    // Get file content (apply transforms if image)\n    const content = await this.getProcessedContent();\n\n    // Select storage\n    const storageInstance = this.resolveStorage(driver);\n\n    // Determine final location (adjust extension if format changed)\n    const finalLocation = this.adjustLocationForFormat(location);\n\n    // Save to storage\n    this._storageFile = await storageInstance.put(content, finalLocation, {\n      mimeType: this.getFinalMimeType(),\n    });\n\n    // Store hash from StorageFile\n    const info = await this._storageFile.data();\n    this.hash = info.hash || \"\";\n\n    return this._storageFile;\n  }\n\n  /**\n   * Get processed content (with transforms applied if applicable)\n   * @internal\n   */\n  protected async getProcessedContent(): Promise<Buffer> {\n    const content = await this.buffer();\n\n    // If not an image or no transforms, return as-is\n    if (!this.isImage || !this.hasTransforms()) {\n      return content;\n    }\n\n    // Create Image and apply transforms\n    let img = new Image(content);\n\n    // Apply transform callback or options\n    if (typeof this._transformConfig === \"function\") {\n      img = this._transformConfig(img);\n    } else if (this._transformConfig) {\n      img = img.apply(this._transformConfig);\n    }\n\n    // Apply high-level options on top\n    img = this.applyImageOptions(img);\n\n    return img.toBuffer();\n  }\n\n  /**\n   * Apply high-level image options\n   * @internal\n   */\n  protected applyImageOptions(img: Image): Image {\n    const opts = this._imageOptions;\n\n    if (opts.resize) {\n      img = img.resize({ width: opts.resize.width, height: opts.resize.height });\n    }\n\n    if (opts.rotate !== undefined) {\n      img = img.rotate(opts.rotate);\n    }\n\n    if (opts.blur !== undefined) {\n      img = img.blur(opts.blur);\n    }\n\n    if (opts.grayscale) {\n      img = img.grayscale();\n    }\n\n    if (opts.quality !== undefined) {\n      img = img.quality(opts.quality);\n    }\n\n    if (opts.format) {\n      img = img.format(opts.format);\n    }\n\n    return img;\n  }\n\n  /**\n   * Check if any transforms are queued\n   * @internal\n   */\n  protected hasTransforms(): boolean {\n    return this._transformConfig !== undefined || Object.keys(this._imageOptions).length > 0;\n  }\n\n  /**\n   * Resolve storage instance to use\n   * @internal\n   */\n  protected resolveStorage(driver?: StorageDriverName): ScopedStorage | typeof storage {\n    if (driver) {\n      return storage.use(driver) as ScopedStorage;\n    }\n\n    return this._storage || storage;\n  }\n\n  /**\n   * Resolve the filename based on options and config\n   * @internal\n   */\n  protected resolveFilename(options?: SaveOptions): string {\n    const namingStrategy: FileNamingStrategy = options?.name ?? uploadsConfig(\"name\") ?? \"random\";\n    let baseName: string;\n\n    if (namingStrategy === \"original\") {\n      baseName = path.basename(this.name, path.extname(this.name));\n    } else if (namingStrategy === \"random\") {\n      const length = uploadsConfig(\"randomLength\");\n      baseName = Random.string(length);\n    } else {\n      // Custom name - strip extension if provided, we'll add it\n      baseName = path.basename(namingStrategy, path.extname(namingStrategy));\n    }\n\n    // Get extension (may be changed by format transform)\n    const ext = this.getFinalExtension();\n\n    return `${baseName}.${ext}`;\n  }\n\n  /**\n   * Resolve prefix based on options and config\n   * @internal\n   */\n  protected resolvePrefix(prefix?: PrefixConfig): string {\n    // No prefix\n    if (prefix === false || prefix === undefined) {\n      const configPrefix = uploadsConfig(\"prefix\");\n      if (!configPrefix) {\n        return \"\";\n      }\n      // Use config prefix if no explicit prefix provided\n      prefix = configPrefix;\n    }\n\n    // Boolean true = use default format\n    if (prefix === true) {\n      const format = uploadsConfig(\"defaultPrefixFormat\")!;\n      return this.formatDatePrefix(format, \"file\");\n    }\n\n    // String = static prefix\n    if (typeof prefix === \"string\") {\n      return prefix;\n    }\n\n    // PrefixOptions object\n    const parts: string[] = [];\n\n    // Add date format if specified\n    if (prefix.format) {\n      parts.push(this.formatDate(prefix.format));\n    }\n\n    // Add random string if specified\n    if (prefix.randomLength) {\n      parts.push(Random.string(prefix.randomLength));\n    }\n\n    const combined = parts.join(\"-\");\n    const as = prefix.as ?? \"file\";\n\n    if (as === \"directory\") {\n      return combined ? `${combined}/` : \"\";\n    }\n\n    return combined ? `${combined}-` : \"\";\n  }\n\n  /**\n   * Format a date prefix with the given format\n   * @internal\n   */\n  protected formatDatePrefix(format: string, as: \"file\" | \"directory\"): string {\n    const formatted = this.formatDate(format);\n    return as === \"directory\" ? `${formatted}/` : `${formatted}-`;\n  }\n\n  /**\n   * Format current date using token-based format string\n   * @internal\n   */\n  protected formatDate(format: string): string {\n    return dayjs().format(format);\n  }\n\n  /**\n   * Build final location from directory, prefix, and filename\n   * @internal\n   */\n  protected buildLocation(directory: string, prefix: string, filename: string): string {\n    // Clean up directory (remove trailing slash)\n    const dir = directory.replace(/\\/$/, \"\");\n\n    // If prefix ends with /, it's a directory\n    if (prefix.endsWith(\"/\")) {\n      return `${dir}/${prefix}${filename}`;\n    }\n\n    // Otherwise prefix is part of filename\n    return `${dir}/${prefix}${filename}`;\n  }\n\n  /**\n   * Get final extension (accounting for format changes)\n   * @internal\n   */\n  protected getFinalExtension(): string {\n    if (this._imageOptions.format) {\n      // Map formats to extensions\n      const format = this._imageOptions.format;\n\n      if (format === \"jpeg\") return \"jpg\";\n\n      return format;\n    }\n\n    return this.extension;\n  }\n\n  /**\n   * Get final MIME type (accounting for format changes)\n   * @internal\n   */\n  protected getFinalMimeType(): string {\n    if (this._imageOptions.format) {\n      const format = this._imageOptions.format;\n\n      if (format === \"jpeg\" || format === \"jpg\") return \"image/jpeg\";\n\n      return `image/${format}`;\n    }\n\n    return this.mimeType;\n  }\n\n  /**\n   * Adjust location to use correct extension if format changed\n   * @internal\n   */\n  protected adjustLocationForFormat(location: string): string {\n    if (!this._imageOptions.format) {\n      return location;\n    }\n\n    const ext = this.getFinalExtension();\n    const currentExt = path.extname(location);\n\n    if (currentExt) {\n      return location.replace(currentExt, `.${ext}`);\n    }\n\n    return `${location}.${ext}`;\n  }\n\n  // ============================================================\n  // Serialization\n  // ============================================================\n\n  /**\n   * Convert to JSON representation.\n   *\n   * **Synchronous, and that is the whole point.** `toJSON` is not an ordinary\n   * method name — it is the hook `JSON.stringify` calls, and `JSON.stringify`\n   * does not await. While this was `async`, every implicit serialization of an\n   * upload produced `{}`: no base64, no size, not even the filename.\n   *\n   * Two call sites in core awaited it and worked (`http/response.ts:304`,\n   * `utils/to-json.ts:9`). The ones that could not were the ones that mattered:\n   * `cascade`'s model serializer calls `toJSON()` without awaiting, and\n   * `Resource.toJSON()` is itself synchronous. Those paths were silently\n   * broken. See canon `cd60b894`.\n   *\n   * **What is NOT here, and why.** `base64` forced the async — `buffer()` is\n   * async — and it also put the entire file, inflated by a third, into any\n   * response that happened to carry an upload. It is opt-in now via\n   * {@link UploadedFile.toBase64}. `dimensions` costs an image decode; ask for\n   * it with {@link UploadedFile.dimensions} when you want it.\n   *\n   * `size` is reported **only when the file has already been read**. Reading it\n   * here would make the method async again, and guessing would be worse than\n   * omitting: a wrong number is believed, an absent one is asked about. In\n   * practice validation or `save()` has usually buffered the file long before\n   * anything serializes it.\n   */\n  public toJSON(): UploadedFileJson {\n    return {\n      name: this.name,\n      mimeType: this.mimeType,\n      extension: this.extension,\n      isImage: this.isImage,\n      isVideo: this.isVideo,\n      isAudio: this.isAudio,\n      size: this.bufferedFileContent?.length,\n    };\n  }\n\n  /**\n   * The file's contents as base64.\n   *\n   * Explicit because it is expensive: it reads the whole file into memory and\n   * grows it by a third. This used to happen on every serialization.\n   */\n  public async toBase64(): Promise<string> {\n    return (await this.buffer()).toString(\"base64\");\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"uploaded-file.mjs","names":[],"sources":["../../../../../../../../packages/core/src/http/uploaded-file.ts"],"sourcesContent":["import type { MultipartFile } from \"@fastify/multipart\";\nimport { Random } from \"@mongez/reinforcements\";\nimport dayjs from \"dayjs\";\nimport path from \"path\";\nimport { Image, type ImageFormat, type ImageTransformOptions } from \"../image\";\nimport { storage, type ScopedStorage, type StorageDriverName, type StorageFile } from \"../storage\";\nimport { sanitizePath } from \"../utils/paths\";\nimport { uploadsConfig } from \"./uploads-config\";\nimport type {\n  FileNamingStrategy,\n  ImageTransformCallback,\n  PrefixConfig,\n  SaveAsOptions,\n  SaveOptions,\n  UploadedFileImageOptions,\n} from \"./uploads-types\";\n\ntype UploadedFileMetadata = {\n  name: string;\n  mimeType: string;\n  extension: string;\n  size: number;\n  width?: number;\n  height?: number;\n};\n\n/**\n * What an `UploadedFile` looks like on the wire.\n *\n * Every member is knowable **without reading the file**, which is what lets\n * {@link UploadedFile.toJSON} be synchronous — see the note there. `size` is\n * the one exception and it is optional for exactly that reason: present when\n * the file has already been buffered, absent otherwise, never guessed.\n */\nexport type UploadedFileJson = {\n  name: string;\n  mimeType: string;\n  extension: string;\n  isImage: boolean;\n  isVideo: boolean;\n  isAudio: boolean;\n  size?: number;\n};\n\n/**\n * Options for validating file before saving\n */\nexport type FileValidationOptions = {\n  /**\n   * List of allowed MIME types\n   *\n   * @example [\"image/jpeg\", \"image/png\", \"image/webp\"]\n   */\n  allowedMimeTypes?: string[];\n\n  /**\n   * List of allowed file extensions (without dot)\n   *\n   * @example [\"jpg\", \"jpeg\", \"png\", \"webp\"]\n   */\n  allowedExtensions?: string[];\n\n  /**\n   * Maximum file size in bytes\n   *\n   * @example 5 * 1024 * 1024 // 5MB\n   */\n  maxSize?: number;\n};\n\n/**\n * UploadedFile - Handles multipart file uploads with storage and image integration\n *\n * Provides a fluent API for validating, transforming, and saving uploaded files\n * to various storage drivers (local, S3, R2, etc.).\n *\n * @example\n * ```typescript\n * // Simple save with random name\n * const file = await uploadedFile.save(\"avatars\");\n *\n * // Original name with date prefix\n * const file = await uploadedFile.save(\"avatars\", {\n *   name: \"original\",\n *   prefix: { format: \"yyyy/mm/dd\", as: \"directory\" }\n * });\n *\n * // With image transformations\n * const file = await uploadedFile\n *   .resize(800, 600)\n *   .quality(85)\n *   .format(\"webp\")\n *   .save(\"avatars\");\n *\n * // Different storage driver\n * const file = await uploadedFile.use(\"s3\").save(\"avatars\");\n * ```\n */\nexport class UploadedFile {\n  /**\n   * File buffered content\n   * @internal\n   */\n  protected bufferedFileContent?: Buffer;\n\n  /**\n   * Upload file hash (SHA-256)\n   *\n   * Populated after file is saved.\n   */\n  public hash = \"\";\n\n  /**\n   * Selected storage driver\n   * @internal\n   */\n  protected _storage: ScopedStorage = storage;\n\n  /**\n   * Saved StorageFile reference\n   * @internal\n   */\n  protected _storageFile?: StorageFile;\n\n  /**\n   * Queued image options (high-level API)\n   * @internal\n   */\n  protected _imageOptions: UploadedFileImageOptions = {};\n\n  /**\n   * Full transform options or callback\n   * @internal\n   */\n  protected _transformConfig?: ImageTransformOptions | ImageTransformCallback;\n\n  /**\n   * Create a new UploadedFile instance\n   *\n   * @param fileData - Multipart file data from Fastify\n   * @throws Error if file data is invalid\n   */\n  public constructor(protected readonly fileData: MultipartFile) {\n    if (!fileData?.filename) {\n      throw new Error(\"Invalid file data: filename is required\");\n    }\n  }\n\n  // ============================================================\n  // File Properties\n  // ============================================================\n\n  /**\n   * Get file name (sanitized)\n   *\n   * Returns the original filename with special characters removed/replaced.\n   */\n  public get name(): string {\n    return sanitizePath(this.fileData.filename);\n  }\n\n  /**\n   * Get file MIME type\n   *\n   * @example \"image/jpeg\", \"application/pdf\"\n   */\n  public get mimeType(): string {\n    return this.fileData.mimetype;\n  }\n\n  /**\n   * Get file extension (lowercase, without dot)\n   *\n   * @example \"jpg\", \"png\", \"pdf\"\n   */\n  public get extension(): string {\n    return path.extname(this.fileData.filename).replace(\".\", \"\").toLowerCase();\n  }\n\n  /**\n   * Get file metadata\n   */\n  public async metadata(): Promise<UploadedFileMetadata> {\n    const data: UploadedFileMetadata = {\n      name: this.name,\n      mimeType: this.mimeType,\n      extension: this.extension,\n      size: await this.size(),\n    };\n\n    if (this.isImage) {\n      const dimensions = await this.dimensions();\n      data.width = dimensions.width;\n      data.height = dimensions.height;\n    }\n\n    return data;\n  }\n\n  /**\n   * Get file size in bytes\n   *\n   * Buffers the file content if not already buffered.\n   */\n  public async size(): Promise<number> {\n    const file = await this.buffer();\n    return file.length;\n  }\n\n  /**\n   * Get file buffer\n   *\n   * Caches the buffer after first call for efficiency.\n   */\n  public async buffer(): Promise<Buffer> {\n    if (this.bufferedFileContent) {\n      return this.bufferedFileContent;\n    }\n\n    this.bufferedFileContent = await this.fileData.toBuffer();\n    return this.bufferedFileContent;\n  }\n\n  // ============================================================\n  // File Type Checks\n  // ============================================================\n\n  /**\n   * Check if file is an image based on MIME type\n   */\n  public get isImage(): boolean {\n    return this.mimeType.startsWith(\"image\");\n  }\n\n  /**\n   * Check if file is a video based on MIME type\n   */\n  public get isVideo(): boolean {\n    return this.mimeType.startsWith(\"video\");\n  }\n\n  /**\n   * Check if file is an audio based on MIME type\n   */\n  public get isAudio(): boolean {\n    return this.mimeType.startsWith(\"audio\");\n  }\n\n  // ============================================================\n  // Storage Driver Selection\n  // ============================================================\n\n  /**\n   * Select a specific storage driver for this upload\n   *\n   * Returns this instance for chaining. The driver is used\n   * when `save()` or `saveAs()` is called.\n   *\n   * @param driver - Driver name from storage configuration\n   * @returns This instance for chaining\n   *\n   * @example\n   * ```typescript\n   * await file.use(\"s3\").save(\"avatars\");\n   * await file.use(\"r2\").save(\"cdn/images\");\n   * ```\n   */\n  public use(driver: StorageDriverName): this {\n    this._storage = storage.use(driver) as ScopedStorage;\n    return this;\n  }\n\n  // ============================================================\n  // High-Level Image Transform API\n  // ============================================================\n\n  /**\n   * Resize the image before saving\n   *\n   * Only applies to image files. Non-image files ignore this.\n   *\n   * @param width - Target width in pixels\n   * @param height - Optional target height (maintains aspect ratio if omitted)\n   * @returns This instance for chaining\n   *\n   * @example\n   * ```typescript\n   * await file.resize(800).save(\"thumbnails\");\n   * await file.resize(400, 400).save(\"avatars\");\n   * ```\n   */\n  public resize(width: number, height?: number): this {\n    this._imageOptions.resize = { width, height };\n    return this;\n  }\n\n  /**\n   * Set image output quality\n   *\n   * Quality affects file size and visual fidelity.\n   * Only applies to formats that support quality (JPEG, WebP, AVIF).\n   *\n   * @param value - Quality value (1-100)\n   * @returns This instance for chaining\n   *\n   * @example\n   * ```typescript\n   * await file.quality(85).save(\"images\");\n   * ```\n   */\n  public quality(value: number): this {\n    if (value < 1 || value > 100) {\n      throw new Error(\"Quality must be between 1 and 100\");\n    }\n    this._imageOptions.quality = value;\n    return this;\n  }\n\n  /**\n   * Convert image to a specific format\n   *\n   * Changes the output format and updates the file extension accordingly.\n   *\n   * @param format - Target image format (jpeg, png, webp, avif, etc.)\n   * @returns This instance for chaining\n   *\n   * @example\n   * ```typescript\n   * await file.format(\"webp\").save(\"images\");\n   * await file.resize(800).format(\"avif\").quality(80).save(\"optimized\");\n   * ```\n   */\n  public format(format: ImageFormat): this {\n    this._imageOptions.format = format;\n    return this;\n  }\n\n  /**\n   * Rotate the image\n   *\n   * @param degrees - Rotation angle in degrees (positive = clockwise)\n   * @returns This instance for chaining\n   *\n   * @example\n   * ```typescript\n   * await file.rotate(90).save(\"rotated\");\n   * ```\n   */\n  public rotate(degrees: number): this {\n    this._imageOptions.rotate = degrees;\n    return this;\n  }\n\n  /**\n   * Apply blur effect to the image\n   *\n   * @param sigma - Blur intensity (default: 3, minimum: 0.3)\n   * @returns This instance for chaining\n   *\n   * @example\n   * ```typescript\n   * await file.blur(5).save(\"blurred\");\n   * ```\n   */\n  public blur(sigma = 3): this {\n    if (sigma < 0.3) {\n      throw new Error(\"Blur sigma must be at least 0.3\");\n    }\n    this._imageOptions.blur = sigma;\n    return this;\n  }\n\n  /**\n   * Convert image to grayscale (black and white)\n   *\n   * @returns This instance for chaining\n   *\n   * @example\n   * ```typescript\n   * await file.grayscale().save(\"bw-images\");\n   * ```\n   */\n  public grayscale(): this {\n    this._imageOptions.grayscale = true;\n    return this;\n  }\n\n  // ============================================================\n  // Full Transform Control\n  // ============================================================\n\n  /**\n   * Apply full image transformations\n   *\n   * Provides complete control over image processing. Can be used with:\n   * - An options object for predefined transforms\n   * - A callback function for chained operations\n   *\n   * @param config - Transform options or callback function\n   * @returns This instance for chaining\n   *\n   * @example\n   * ```typescript\n   * // Using options object\n   * await file.transform({\n   *   resize: { width: 800, fit: \"inside\" },\n   *   quality: 85\n   * }).save(\"images\");\n   *\n   * // Using callback for full control\n   * await file.transform(img =>\n   *   img.resize({ width: 800 })\n   *      .watermark(\"logo.png\", { gravity: \"southeast\" })\n   *      .sharpen()\n   * ).save(\"products\");\n   * ```\n   */\n  public transform(config: ImageTransformOptions | ImageTransformCallback): this {\n    this._transformConfig = config;\n    return this;\n  }\n\n  /**\n   * Get an Image instance for advanced manipulation\n   *\n   * Returns an Image instance from the file buffer for manual processing.\n   * Use this when you need operations not covered by the fluent API.\n   *\n   * @returns Promise resolving to Image instance\n   *\n   * @example\n   * ```typescript\n   * const img = await file.toImage();\n   * await img\n   *   .resize({ width: 800 })\n   *   .watermark(\"logo.png\", { gravity: \"southeast\" })\n   *   .save(\"path/to/output.jpg\");\n   * ```\n   */\n  public async toImage(): Promise<Image> {\n    return new Image(await this.buffer());\n  }\n\n  // ============================================================\n  // Image Metadata\n  // ============================================================\n\n  /**\n   * Get file width and height (only for images)\n   *\n   * @returns Dimensions object, or empty object if not an image\n   */\n  public async dimensions(): Promise<{ width?: number; height?: number }> {\n    if (!this.isImage) {\n      return {};\n    }\n\n    return new Image(await this.buffer()).dimensions();\n  }\n\n  // ============================================================\n  // Validation\n  // ============================================================\n\n  /**\n   * Validate file against the given options\n   *\n   * @param options - Validation rules\n   * @throws Error if validation fails\n   *\n   * @example\n   * ```typescript\n   * await file.validate({\n   *   allowedMimeTypes: [\"image/jpeg\", \"image/png\"],\n   *   maxSize: 5 * 1024 * 1024 // 5MB\n   * });\n   * ```\n   */\n  public async validate(options: FileValidationOptions): Promise<void> {\n    const { allowedMimeTypes, allowedExtensions, maxSize } = options;\n\n    if (allowedMimeTypes && !allowedMimeTypes.includes(this.mimeType)) {\n      throw new Error(\n        `Invalid file type: ${this.mimeType}. Allowed types: ${allowedMimeTypes.join(\", \")}`,\n      );\n    }\n\n    if (allowedExtensions && !allowedExtensions.includes(this.extension)) {\n      throw new Error(\n        `Invalid file extension: ${this.extension}. Allowed extensions: ${allowedExtensions.join(\", \")}`,\n      );\n    }\n\n    if (maxSize) {\n      const fileSize = await this.size();\n      if (fileSize > maxSize) {\n        throw new Error(`File too large: ${fileSize} bytes. Maximum allowed: ${maxSize} bytes`);\n      }\n    }\n  }\n\n  // ============================================================\n  // Save Operations\n  // ============================================================\n\n  /**\n   * Save the file to a directory with automatic naming\n   * Keep in mind to use only relative path to the root of storage\n   * If you are using local driver\n   * Uses the configured naming strategy and prefix options to generate\n   * the final path. Returns a StorageFile for accessing file metadata.\n   *\n   * @param directory - Target directory path\n   * @param options - Save options (name, prefix, driver, validate)\n   * @returns StorageFile instance with file metadata and operations\n   *\n   * @example\n   * ```typescript\n   * // Random name (default)\n   * await file.save(\"avatars\");\n   * // → avatars/x7k9m2p4.jpg\n   *\n   * // Original name\n   * await file.save(\"avatars\", { name: \"original\" });\n   * // → avatars/photo.jpg\n   *\n   * // With date directory\n   * await file.save(\"avatars\", {\n   *   prefix: { format: \"yyyy/mm/dd\", as: \"directory\" }\n   * });\n   * // → avatars/2025/12/21/x7k9m2p4.jpg\n   *\n   * // Original name with datetime prefix\n   * await file.save(\"avatars\", { name: \"original\", prefix: true });\n   * // → avatars/21-12-2025-16-45-30-photo.jpg\n   * ```\n   */\n  public async save(directory: string, options?: SaveOptions): Promise<StorageFile> {\n    // Validate if requested\n    if (options?.validate) {\n      await this.validate(options.validate);\n    }\n\n    // Resolve filename and prefix\n    const filename = this.resolveFilename(options);\n    const prefix = this.resolvePrefix(options?.prefix);\n    const location = this.buildLocation(directory, prefix, filename);\n\n    return this.saveToLocation(location, options?.driver);\n  }\n\n  /**\n   * Save the file to an explicit path\n   *\n   * Unlike `save()`, this method uses the exact path you provide.\n   * No automatic naming or prefix is applied.\n   *\n   * @param location - Full file path (directory + filename)\n   * @param options - Save options (driver, validate)\n   * @returns StorageFile instance with file metadata\n   *\n   * @example\n   * ```typescript\n   * await file.saveAs(\"avatars/profile-123.png\");\n   * await file.saveAs(\"products/2025/featured-image.webp\");\n   * ```\n   */\n  public async saveAs(location: string, options?: SaveAsOptions): Promise<StorageFile> {\n    // Validate if requested\n    if (options?.validate) {\n      await this.validate(options.validate);\n    }\n\n    return this.saveToLocation(location, options?.driver);\n  }\n\n  /**\n   * Get the StorageFile reference if file has been saved\n   *\n   * Returns undefined if file hasn't been saved yet.\n   */\n  public get storageFile(): StorageFile | undefined {\n    return this._storageFile;\n  }\n\n  // ============================================================\n  // Internal Helpers\n  // ============================================================\n\n  /**\n   * Execute save to the specified location\n   * @internal\n   */\n  protected async saveToLocation(\n    location: string,\n    driver?: StorageDriverName,\n  ): Promise<StorageFile> {\n    // Get file content (apply transforms if image)\n    const content = await this.getProcessedContent();\n\n    // Select storage\n    const storageInstance = this.resolveStorage(driver);\n\n    // Determine final location (adjust extension if format changed)\n    const finalLocation = this.adjustLocationForFormat(location);\n\n    // Save to storage\n    this._storageFile = await storageInstance.put(content, finalLocation, {\n      mimeType: this.getFinalMimeType(),\n    });\n\n    // Store hash from StorageFile\n    const info = await this._storageFile.data();\n    this.hash = info.hash || \"\";\n\n    return this._storageFile;\n  }\n\n  /**\n   * Get processed content (with transforms applied if applicable)\n   * @internal\n   */\n  protected async getProcessedContent(): Promise<Buffer> {\n    const content = await this.buffer();\n\n    // If not an image or no transforms, return as-is\n    if (!this.isImage || !this.hasTransforms()) {\n      return content;\n    }\n\n    // Create Image and apply transforms\n    let img = new Image(content);\n\n    // Apply transform callback or options\n    if (typeof this._transformConfig === \"function\") {\n      img = this._transformConfig(img);\n    } else if (this._transformConfig) {\n      img = img.apply(this._transformConfig);\n    }\n\n    // Apply high-level options on top\n    img = this.applyImageOptions(img);\n\n    return img.toBuffer();\n  }\n\n  /**\n   * Apply high-level image options\n   * @internal\n   */\n  protected applyImageOptions(img: Image): Image {\n    const opts = this._imageOptions;\n\n    if (opts.resize) {\n      img = img.resize({ width: opts.resize.width, height: opts.resize.height });\n    }\n\n    if (opts.rotate !== undefined) {\n      img = img.rotate(opts.rotate);\n    }\n\n    if (opts.blur !== undefined) {\n      img = img.blur(opts.blur);\n    }\n\n    if (opts.grayscale) {\n      img = img.grayscale();\n    }\n\n    if (opts.quality !== undefined) {\n      img = img.quality(opts.quality);\n    }\n\n    if (opts.format) {\n      img = img.format(opts.format);\n    }\n\n    return img;\n  }\n\n  /**\n   * Check if any transforms are queued\n   * @internal\n   */\n  protected hasTransforms(): boolean {\n    return this._transformConfig !== undefined || Object.keys(this._imageOptions).length > 0;\n  }\n\n  /**\n   * Resolve storage instance to use\n   * @internal\n   */\n  protected resolveStorage(driver?: StorageDriverName): ScopedStorage | typeof storage {\n    if (driver) {\n      return storage.use(driver) as ScopedStorage;\n    }\n\n    return this._storage || storage;\n  }\n\n  /**\n   * Resolve the filename based on options and config\n   * @internal\n   */\n  protected resolveFilename(options?: SaveOptions): string {\n    const namingStrategy: FileNamingStrategy = options?.name ?? uploadsConfig(\"name\") ?? \"random\";\n    let baseName: string;\n\n    if (namingStrategy === \"original\") {\n      baseName = path.basename(this.name, path.extname(this.name));\n    } else if (namingStrategy === \"random\") {\n      const length = uploadsConfig(\"randomLength\");\n      baseName = Random.string(length);\n    } else {\n      // Custom name - strip extension if provided, we'll add it\n      baseName = path.basename(namingStrategy, path.extname(namingStrategy));\n    }\n\n    // Get extension (may be changed by format transform)\n    const ext = this.getFinalExtension();\n\n    return `${baseName}.${ext}`;\n  }\n\n  /**\n   * Resolve prefix based on options and config\n   * @internal\n   */\n  protected resolvePrefix(prefix?: PrefixConfig): string {\n    // No prefix\n    if (prefix === false || prefix === undefined) {\n      const configPrefix = uploadsConfig(\"prefix\");\n      if (!configPrefix) {\n        return \"\";\n      }\n      // Use config prefix if no explicit prefix provided\n      prefix = configPrefix;\n    }\n\n    // Boolean true = use default format\n    if (prefix === true) {\n      const format = uploadsConfig(\"defaultPrefixFormat\")!;\n      return this.formatDatePrefix(format, \"file\");\n    }\n\n    // String = static prefix\n    if (typeof prefix === \"string\") {\n      return prefix;\n    }\n\n    // PrefixOptions object\n    const parts: string[] = [];\n\n    // Add date format if specified\n    if (prefix.format) {\n      parts.push(this.formatDate(prefix.format));\n    }\n\n    // Add random string if specified\n    if (prefix.randomLength) {\n      parts.push(Random.string(prefix.randomLength));\n    }\n\n    const combined = parts.join(\"-\");\n    const as = prefix.as ?? \"file\";\n\n    if (as === \"directory\") {\n      return combined ? `${combined}/` : \"\";\n    }\n\n    return combined ? `${combined}-` : \"\";\n  }\n\n  /**\n   * Format a date prefix with the given format\n   * @internal\n   */\n  protected formatDatePrefix(format: string, as: \"file\" | \"directory\"): string {\n    const formatted = this.formatDate(format);\n    return as === \"directory\" ? `${formatted}/` : `${formatted}-`;\n  }\n\n  /**\n   * Format current date using token-based format string\n   * @internal\n   */\n  protected formatDate(format: string): string {\n    return dayjs().format(format);\n  }\n\n  /**\n   * Build final location from directory, prefix, and filename\n   * @internal\n   */\n  protected buildLocation(directory: string, prefix: string, filename: string): string {\n    // Clean up directory (remove trailing slash)\n    const dir = directory.replace(/\\/$/, \"\");\n\n    // If prefix ends with /, it's a directory\n    if (prefix.endsWith(\"/\")) {\n      return `${dir}/${prefix}${filename}`;\n    }\n\n    // Otherwise prefix is part of filename\n    return `${dir}/${prefix}${filename}`;\n  }\n\n  /**\n   * Get final extension (accounting for format changes)\n   * @internal\n   */\n  protected getFinalExtension(): string {\n    if (this._imageOptions.format) {\n      // Map formats to extensions\n      const format = this._imageOptions.format;\n\n      if (format === \"jpeg\") return \"jpg\";\n\n      return format;\n    }\n\n    return this.extension;\n  }\n\n  /**\n   * Get final MIME type (accounting for format changes)\n   * @internal\n   */\n  protected getFinalMimeType(): string {\n    if (this._imageOptions.format) {\n      const format = this._imageOptions.format;\n\n      if (format === \"jpeg\" || format === \"jpg\") return \"image/jpeg\";\n\n      return `image/${format}`;\n    }\n\n    return this.mimeType;\n  }\n\n  /**\n   * Adjust location to use correct extension if format changed\n   * @internal\n   */\n  protected adjustLocationForFormat(location: string): string {\n    if (!this._imageOptions.format) {\n      return location;\n    }\n\n    const ext = this.getFinalExtension();\n    const currentExt = path.extname(location);\n\n    if (currentExt) {\n      return location.replace(currentExt, `.${ext}`);\n    }\n\n    return `${location}.${ext}`;\n  }\n\n  // ============================================================\n  // Serialization\n  // ============================================================\n\n  /**\n   * Convert to JSON representation.\n   *\n   * **Synchronous, and that is the whole point.** `toJSON` is not an ordinary\n   * method name — it is the hook `JSON.stringify` calls, and `JSON.stringify`\n   * does not await. While this was `async`, every implicit serialization of an\n   * upload produced `{}`: no base64, no size, not even the filename.\n   *\n   * Two call sites in core awaited it and worked (`http/response.ts:304`,\n   * `utils/to-json.ts:9`). The ones that could not were the ones that mattered:\n   * `cascade`'s model serializer calls `toJSON()` without awaiting, and\n   * `Resource.toJSON()` is itself synchronous. Those paths were silently\n   * broken. See canon `cd60b894`.\n   *\n   * **What is NOT here, and why.** `base64` forced the async — `buffer()` is\n   * async — and it also put the entire file, inflated by a third, into any\n   * response that happened to carry an upload. It is opt-in now via\n   * {@link UploadedFile.toBase64}. `dimensions` costs an image decode; ask for\n   * it with {@link UploadedFile.dimensions} when you want it.\n   *\n   * `size` is reported **only when the file has already been read**. Reading it\n   * here would make the method async again, and guessing would be worse than\n   * omitting: a wrong number is believed, an absent one is asked about. In\n   * practice validation or `save()` has usually buffered the file long before\n   * anything serializes it.\n   */\n  public toJSON(): UploadedFileJson {\n    return {\n      name: this.name,\n      mimeType: this.mimeType,\n      extension: this.extension,\n      isImage: this.isImage,\n      isVideo: this.isVideo,\n      isAudio: this.isAudio,\n      size: this.bufferedFileContent?.length,\n    };\n  }\n\n  /**\n   * The file's contents as base64.\n   *\n   * Explicit because it is expensive: it reads the whole file into memory and\n   * grows it by a third. This used to happen on every serialization.\n   */\n  public async toBase64(): Promise<string> {\n    return (await this.buffer()).toString(\"base64\");\n  }\n}\n"],"mappings":"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"}

package/esm/http/uploads/detect-image-format.mjs

@@ -1,4 +1,4 @@
-//#region ../core/src/http/uploads/detect-image-format.ts
+//#region ../../packages/core/src/http/uploads/detect-image-format.ts
 /**
 * Bytes `detectImageFormat` needs to see
 */

package/esm/http/uploads/detect-image-format.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"detect-image-format.mjs","names":[],"sources":["../../../../../../../../core/src/http/uploads/detect-image-format.ts"],"sourcesContent":["import type { DetectedImageFormat, VariantSourceFormat } from \"./image-variant-types\";\n\n/**\n * Bytes `detectImageFormat` needs to see\n */\nexport const IMAGE_SIGNATURE_BYTES = 512;\n\nfunction startsWith(buffer: Buffer, signature: number[], offset = 0): boolean {\n  return signature.every((byte, index) => buffer[offset + index] === byte);\n}\n\nfunction ascii(buffer: Buffer, start: number, end: number): string {\n  return buffer.subarray(start, end).toString(\"latin1\");\n}\n\n/**\n * Detect an image format from its magic bytes, never from the file name.\n *\n * Recognises the variant sources (jpeg, png, webp, still avif) and the formats\n * that are refused but worth naming (gif, svg). An animated avif sequence\n * (`avis` brand) is not reported as avif.\n *\n * @returns the format, or `undefined` for anything else\n */\nexport function detectImageFormat(buffer: Buffer): DetectedImageFormat | undefined {\n  if (startsWith(buffer, [0xff, 0xd8, 0xff])) return \"jpeg\";\n\n  if (startsWith(buffer, [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])) return \"png\";\n\n  if (ascii(buffer, 0, 4) === \"RIFF\" && ascii(buffer, 8, 12) === \"WEBP\") return \"webp\";\n\n  if (ascii(buffer, 0, 6) === \"GIF87a\" || ascii(buffer, 0, 6) === \"GIF89a\") return \"gif\";\n\n  if (ascii(buffer, 4, 8) === \"ftyp\" && ascii(buffer, 8, 12) === \"avif\") return \"avif\";\n\n  const head = buffer\n    .subarray(0, IMAGE_SIGNATURE_BYTES)\n    .toString(\"utf8\")\n    .replace(/^/, \"\")\n    .trimStart()\n    .toLowerCase();\n\n  if (head.startsWith(\"<svg\") || (head.startsWith(\"<?xml\") && head.includes(\"<svg\"))) return \"svg\";\n\n  return undefined;\n}\n\nconst VARIANT_SOURCE_FORMATS: readonly DetectedImageFormat[] = [\"jpeg\", \"png\", \"webp\", \"avif\"];\n\n/**\n * Whether a detected format can be the source of a variant. gif is refused\n * (animation is ambiguous) and svg is refused (not a raster).\n */\nexport function isVariantSourceFormat(\n  format: DetectedImageFormat | undefined,\n): format is VariantSourceFormat {\n  return format !== undefined && VARIANT_SOURCE_FORMATS.includes(format);\n}\n"],"mappings":";;;;AAKA,MAAa,wBAAwB;AAErC,SAAS,WAAW,QAAgB,WAAqB,SAAS,GAAY;CAC5E,OAAO,UAAU,OAAO,MAAM,UAAU,OAAO,SAAS,WAAW,IAAI;AACzE;AAEA,SAAS,MAAM,QAAgB,OAAe,KAAqB;CACjE,OAAO,OAAO,SAAS,OAAO,GAAG,CAAC,CAAC,SAAS,QAAQ;AACtD;;;;;;;;;;AAWA,SAAgB,kBAAkB,QAAiD;CACjF,IAAI,WAAW,QAAQ;EAAC;EAAM;EAAM;CAAI,CAAC,GAAG,OAAO;CAEnD,IAAI,WAAW,QAAQ;EAAC;EAAM;EAAM;EAAM;EAAM;EAAM;EAAM;EAAM;CAAI,CAAC,GAAG,OAAO;CAEjF,IAAI,MAAM,QAAQ,GAAG,CAAC,MAAM,UAAU,MAAM,QAAQ,GAAG,EAAE,MAAM,QAAQ,OAAO;CAE9E,IAAI,MAAM,QAAQ,GAAG,CAAC,MAAM,YAAY,MAAM,QAAQ,GAAG,CAAC,MAAM,UAAU,OAAO;CAEjF,IAAI,MAAM,QAAQ,GAAG,CAAC,MAAM,UAAU,MAAM,QAAQ,GAAG,EAAE,MAAM,QAAQ,OAAO;CAE9E,MAAM,OAAO,OACV,SAAS,MAAwB,CAAC,CAClC,SAAS,MAAM,CAAC,CAChB,QAAQ,MAAM,EAAE,CAAC,CACjB,UAAU,CAAC,CACX,YAAY;CAEf,IAAI,KAAK,WAAW,MAAM,KAAM,KAAK,WAAW,OAAO,KAAK,KAAK,SAAS,MAAM,GAAI,OAAO;AAG7F;AAEA,MAAM,yBAAyD;CAAC;CAAQ;CAAO;CAAQ;AAAM;;;;;AAM7F,SAAgB,sBACd,QAC+B;CAC/B,OAAO,WAAW,UAAa,uBAAuB,SAAS,MAAM;AACvE"}
+{"version":3,"file":"detect-image-format.mjs","names":[],"sources":["../../../../../../../../../packages/core/src/http/uploads/detect-image-format.ts"],"sourcesContent":["import type { DetectedImageFormat, VariantSourceFormat } from \"./image-variant-types\";\n\n/**\n * Bytes `detectImageFormat` needs to see\n */\nexport const IMAGE_SIGNATURE_BYTES = 512;\n\nfunction startsWith(buffer: Buffer, signature: number[], offset = 0): boolean {\n  return signature.every((byte, index) => buffer[offset + index] === byte);\n}\n\nfunction ascii(buffer: Buffer, start: number, end: number): string {\n  return buffer.subarray(start, end).toString(\"latin1\");\n}\n\n/**\n * Detect an image format from its magic bytes, never from the file name.\n *\n * Recognises the variant sources (jpeg, png, webp, still avif) and the formats\n * that are refused but worth naming (gif, svg). An animated avif sequence\n * (`avis` brand) is not reported as avif.\n *\n * @returns the format, or `undefined` for anything else\n */\nexport function detectImageFormat(buffer: Buffer): DetectedImageFormat | undefined {\n  if (startsWith(buffer, [0xff, 0xd8, 0xff])) return \"jpeg\";\n\n  if (startsWith(buffer, [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])) return \"png\";\n\n  if (ascii(buffer, 0, 4) === \"RIFF\" && ascii(buffer, 8, 12) === \"WEBP\") return \"webp\";\n\n  if (ascii(buffer, 0, 6) === \"GIF87a\" || ascii(buffer, 0, 6) === \"GIF89a\") return \"gif\";\n\n  if (ascii(buffer, 4, 8) === \"ftyp\" && ascii(buffer, 8, 12) === \"avif\") return \"avif\";\n\n  const head = buffer\n    .subarray(0, IMAGE_SIGNATURE_BYTES)\n    .toString(\"utf8\")\n    .replace(/^/, \"\")\n    .trimStart()\n    .toLowerCase();\n\n  if (head.startsWith(\"<svg\") || (head.startsWith(\"<?xml\") && head.includes(\"<svg\"))) return \"svg\";\n\n  return undefined;\n}\n\nconst VARIANT_SOURCE_FORMATS: readonly DetectedImageFormat[] = [\"jpeg\", \"png\", \"webp\", \"avif\"];\n\n/**\n * Whether a detected format can be the source of a variant. gif is refused\n * (animation is ambiguous) and svg is refused (not a raster).\n */\nexport function isVariantSourceFormat(\n  format: DetectedImageFormat | undefined,\n): format is VariantSourceFormat {\n  return format !== undefined && VARIANT_SOURCE_FORMATS.includes(format);\n}\n"],"mappings":";;;;AAKA,MAAa,wBAAwB;AAErC,SAAS,WAAW,QAAgB,WAAqB,SAAS,GAAY;CAC5E,OAAO,UAAU,OAAO,MAAM,UAAU,OAAO,SAAS,WAAW,IAAI;AACzE;AAEA,SAAS,MAAM,QAAgB,OAAe,KAAqB;CACjE,OAAO,OAAO,SAAS,OAAO,GAAG,CAAC,CAAC,SAAS,QAAQ;AACtD;;;;;;;;;;AAWA,SAAgB,kBAAkB,QAAiD;CACjF,IAAI,WAAW,QAAQ;EAAC;EAAM;EAAM;CAAI,CAAC,GAAG,OAAO;CAEnD,IAAI,WAAW,QAAQ;EAAC;EAAM;EAAM;EAAM;EAAM;EAAM;EAAM;EAAM;CAAI,CAAC,GAAG,OAAO;CAEjF,IAAI,MAAM,QAAQ,GAAG,CAAC,MAAM,UAAU,MAAM,QAAQ,GAAG,EAAE,MAAM,QAAQ,OAAO;CAE9E,IAAI,MAAM,QAAQ,GAAG,CAAC,MAAM,YAAY,MAAM,QAAQ,GAAG,CAAC,MAAM,UAAU,OAAO;CAEjF,IAAI,MAAM,QAAQ,GAAG,CAAC,MAAM,UAAU,MAAM,QAAQ,GAAG,EAAE,MAAM,QAAQ,OAAO;CAE9E,MAAM,OAAO,OACV,SAAS,MAAwB,CAAC,CAClC,SAAS,MAAM,CAAC,CAChB,QAAQ,MAAM,EAAE,CAAC,CACjB,UAAU,CAAC,CACX,YAAY;CAEf,IAAI,KAAK,WAAW,MAAM,KAAM,KAAK,WAAW,OAAO,KAAK,KAAK,SAAS,MAAM,GAAI,OAAO;AAG7F;AAEA,MAAM,yBAAyD;CAAC;CAAQ;CAAO;CAAQ;AAAM;;;;;AAM7F,SAAgB,sBACd,QAC+B;CAC/B,OAAO,WAAW,UAAa,uBAAuB,SAAS,MAAM;AACvE"}

package/esm/http/uploads/generate-image-variant.mjs

@@ -1,8 +1,8 @@
-import path from "node:path";
 import { randomBytes } from "node:crypto";
+import path from "node:path";
 import fs from "node:fs/promises";
 
-//#region ../core/src/http/uploads/generate-image-variant.ts
+//#region ../../packages/core/src/http/uploads/generate-image-variant.ts
 async function fileExists(target) {
 	try {
 		await fs.access(target);

package/esm/http/uploads/generate-image-variant.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"generate-image-variant.mjs","names":[],"sources":["../../../../../../../../core/src/http/uploads/generate-image-variant.ts"],"sourcesContent":["import { randomBytes } from \"node:crypto\";\nimport fs from \"node:fs/promises\";\nimport path from \"node:path\";\nimport type { Image } from \"../../image\";\nimport type { ImageVariantDefinition } from \"../uploads-types\";\nimport type { VariantOutputFormat } from \"./image-variant-types\";\n\n/**\n * Inputs of one derivative generation\n */\nexport type GenerateImageVariantOptions = {\n  image: Image;\n  variant: ImageVariantDefinition;\n  format: VariantOutputFormat;\n  targetPath: string;\n};\n\nasync function fileExists(target: string): Promise<boolean> {\n  try {\n    await fs.access(target);\n\n    return true;\n  } catch {\n    return false;\n  }\n}\n\n/**\n * Render a derivative and write it atomically.\n *\n * The image is written to `<target>.tmp-<random>` and then renamed onto the\n * target, so a reader sees no file or a complete one, never a partial one. On\n * any failure the temp file is removed before the error is rethrown.\n */\nexport async function generateImageVariant({\n  image,\n  variant,\n  format,\n  targetPath,\n}: GenerateImageVariantOptions): Promise<void> {\n  image.resize({\n    width: variant.width,\n    height: variant.height,\n    fit: variant.fit,\n    withoutEnlargement: variant.enlarge !== true,\n  });\n  image.format(format);\n\n  if (variant.quality !== undefined) {\n    image.quality(variant.quality);\n  }\n\n  await fs.mkdir(path.dirname(targetPath), { recursive: true });\n\n  const temporaryPath = `${targetPath}.tmp-${randomBytes(8).toString(\"hex\")}`;\n\n  try {\n    await image.save(temporaryPath);\n\n    try {\n      await fs.rename(temporaryPath, targetPath);\n    } catch (error) {\n      // Another process won the race and its file is being read (win32 refuses\n      // to replace an open file). Same key, same bytes: theirs will do.\n      if (!(await fileExists(targetPath))) throw error;\n    }\n  } finally {\n    await fs.rm(temporaryPath, { force: true });\n  }\n}\n"],"mappings":";;;;;AAiBA,eAAe,WAAW,QAAkC;CAC1D,IAAI;EACF,MAAM,GAAG,OAAO,MAAM;EAEtB,OAAO;CACT,QAAQ;EACN,OAAO;CACT;AACF;;;;;;;;AASA,eAAsB,qBAAqB,EACzC,OACA,SACA,QACA,cAC6C;CAC7C,MAAM,OAAO;EACX,OAAO,QAAQ;EACf,QAAQ,QAAQ;EAChB,KAAK,QAAQ;EACb,oBAAoB,QAAQ,YAAY;CAC1C,CAAC;CACD,MAAM,OAAO,MAAM;CAEnB,IAAI,QAAQ,YAAY,QACtB,MAAM,QAAQ,QAAQ,OAAO;CAG/B,MAAM,GAAG,MAAM,KAAK,QAAQ,UAAU,GAAG,EAAE,WAAW,KAAK,CAAC;CAE5D,MAAM,gBAAgB,GAAG,WAAW,OAAO,YAAY,CAAC,CAAC,CAAC,SAAS,KAAK;CAExE,IAAI;EACF,MAAM,MAAM,KAAK,aAAa;EAE9B,IAAI;GACF,MAAM,GAAG,OAAO,eAAe,UAAU;EAC3C,SAAS,OAAO;GAGd,IAAI,CAAE,MAAM,WAAW,UAAU,GAAI,MAAM;EAC7C;CACF,UAAU;EACR,MAAM,GAAG,GAAG,eAAe,EAAE,OAAO,KAAK,CAAC;CAC5C;AACF"}
+{"version":3,"file":"generate-image-variant.mjs","names":[],"sources":["../../../../../../../../../packages/core/src/http/uploads/generate-image-variant.ts"],"sourcesContent":["import { randomBytes } from \"node:crypto\";\nimport fs from \"node:fs/promises\";\nimport path from \"node:path\";\nimport type { Image } from \"../../image\";\nimport type { ImageVariantDefinition } from \"../uploads-types\";\nimport type { VariantOutputFormat } from \"./image-variant-types\";\n\n/**\n * Inputs of one derivative generation\n */\nexport type GenerateImageVariantOptions = {\n  image: Image;\n  variant: ImageVariantDefinition;\n  format: VariantOutputFormat;\n  targetPath: string;\n};\n\nasync function fileExists(target: string): Promise<boolean> {\n  try {\n    await fs.access(target);\n\n    return true;\n  } catch {\n    return false;\n  }\n}\n\n/**\n * Render a derivative and write it atomically.\n *\n * The image is written to `<target>.tmp-<random>` and then renamed onto the\n * target, so a reader sees no file or a complete one, never a partial one. On\n * any failure the temp file is removed before the error is rethrown.\n */\nexport async function generateImageVariant({\n  image,\n  variant,\n  format,\n  targetPath,\n}: GenerateImageVariantOptions): Promise<void> {\n  image.resize({\n    width: variant.width,\n    height: variant.height,\n    fit: variant.fit,\n    withoutEnlargement: variant.enlarge !== true,\n  });\n  image.format(format);\n\n  if (variant.quality !== undefined) {\n    image.quality(variant.quality);\n  }\n\n  await fs.mkdir(path.dirname(targetPath), { recursive: true });\n\n  const temporaryPath = `${targetPath}.tmp-${randomBytes(8).toString(\"hex\")}`;\n\n  try {\n    await image.save(temporaryPath);\n\n    try {\n      await fs.rename(temporaryPath, targetPath);\n    } catch (error) {\n      // Another process won the race and its file is being read (win32 refuses\n      // to replace an open file). Same key, same bytes: theirs will do.\n      if (!(await fileExists(targetPath))) throw error;\n    }\n  } finally {\n    await fs.rm(temporaryPath, { force: true });\n  }\n}\n"],"mappings":";;;;;AAiBA,eAAe,WAAW,QAAkC;CAC1D,IAAI;EACF,MAAM,GAAG,OAAO,MAAM;EAEtB,OAAO;CACT,QAAQ;EACN,OAAO;CACT;AACF;;;;;;;;AASA,eAAsB,qBAAqB,EACzC,OACA,SACA,QACA,cAC6C;CAC7C,MAAM,OAAO;EACX,OAAO,QAAQ;EACf,QAAQ,QAAQ;EAChB,KAAK,QAAQ;EACb,oBAAoB,QAAQ,YAAY;CAC1C,CAAC;CACD,MAAM,OAAO,MAAM;CAEnB,IAAI,QAAQ,YAAY,QACtB,MAAM,QAAQ,QAAQ,OAAO;CAG/B,MAAM,GAAG,MAAM,KAAK,QAAQ,UAAU,GAAG,EAAE,WAAW,KAAK,CAAC;CAE5D,MAAM,gBAAgB,GAAG,WAAW,OAAO,YAAY,CAAC,CAAC,CAAC,SAAS,KAAK;CAExE,IAAI;EACF,MAAM,MAAM,KAAK,aAAa;EAE9B,IAAI;GACF,MAAM,GAAG,OAAO,eAAe,UAAU;EAC3C,SAAS,OAAO;GAGd,IAAI,CAAE,MAAM,WAAW,UAAU,GAAI,MAAM;EAC7C;CACF,UAAU;EACR,MAAM,GAAG,GAAG,eAAe,EAAE,OAAO,KAAK,CAAC;CAC5C;AACF"}

package/esm/http/uploads/generate-image-variants.d.mts

@@ -1,6 +1,7 @@
+import { StorageDriverName } from "../../storage/types.mjs";
 import { GeneratedImageDescriptor } from "./image-variant-types.mjs";
 
-//#region ../core/src/http/uploads/generate-image-variants.d.ts
+//#region ../../packages/core/src/http/uploads/generate-image-variants.d.ts
 /**
  * Options for `generateImageVariants`
  */
@@ -9,7 +10,9 @@ type GenerateImageVariantsOptions = {
    * Limit generation to these variant names, instead of every variant in
    * `uploads.images.variants`.
    */
-  variants?: readonly string[];
+  variants?: readonly string[]; /** Disk holding the source; defaults to the active disk. */
+  disk?: StorageDriverName; /** Route prefix serving variants of this disk (and originals for local disks). Default /uploads. */
+  urlPrefix?: string;
 };
 /**
  * Render every configured variant of one uploaded image, right after it is
@@ -25,15 +28,15 @@ type GenerateImageVariantsOptions = {
  * The returned descriptor is plain JSON, safe to store next to the record
  * that owns the image, or to carry through loader data. On local storage the
  * `url`/`urls` already point at `uploadedFileController`; an app serving
- * uploads from object storage or a CDN should not proxy the remote files
- * through this route at all — store the descriptor once generation runs
- * against the same bucket the CDN serves from, or resolve its URLs through a
- * custom `ImageLoader` on the client instead.
+ * uploads from object storage use the driver URL for the original, and
+ * `options.urlPrefix` for the route serving locally cached derivatives.
+ * Ingest downloads a remote source once for all variants and formats.
+ * On-demand cache hits use ETag metadata; sources without ETags are hashed.
  *
  * @param relativePath - path of the saved upload, relative to the storage root
  * @param options.variants - limit generation to these variant names
- * @throws ImageVariantsConfigError when there is no local storage root, or
- * `uploads.images` is not configured — both are server misconfiguration, not
+ * @throws ImageVariantsConfigError when `uploads.images` is not
+ * configured — this is server misconfiguration, not
  * a bad request
  * @throws HttpError(400) when a name in `options.variants` is not declared in
  * `uploads.images.variants`

package/esm/http/uploads/generate-image-variants.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"generate-image-variants.d.mts","names":[],"sources":["../../../../../../../../core/src/http/uploads/generate-image-variants.ts"],"mappings":";;;;;AAsBA;KAAY,4BAAA;;;AAKF;AA8EV;EA9EE,QAAQ;AAAA;;;;;;;;;;;;AAiFyB;;;;;;;;;;;;;;;;;;;;;iBAHb,qBAAA,CACpB,YAAA,UACA,OAAA,GAAS,4BAAA,GACR,OAAA,CAAQ,wBAAA"}
+{"version":3,"file":"generate-image-variants.d.mts","names":[],"sources":["../../../../../../../../../packages/core/src/http/uploads/generate-image-variants.ts"],"mappings":";;;;;;AAqCA;KAAY,4BAAA;;;;;EAKV,QAAA,sBAMA;EAHA,IAAA,GAAO,iBAAiB,EAGf;EAAT,SAAA;AAAA;;;;;;;;;;;;;AAuEiC;;;;;;;;;;;;;;;;;;;;iBAHb,qBAAA,CACpB,YAAA,UACA,OAAA,GAAS,4BAAA,GACR,OAAA,CAAQ,wBAAA"}