@burojs/file-storage 0.2.0 → 0.5.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { Plugin, AppRuntime } from '@burojs/core';
-
+import { AppRuntime, Plugin } from "@burojs/core";
+//#region src/types.d.ts
 /** How a file's bytes travel relative to the record mutation. */
 type UploadPipeline = 'immediate' | 'fused' | 'handshake' | 'resumable';
 /**
@@ -30,51 +30,51 @@ type OrphanPolicy = 'best-effort' | 'keep';
  * so, rather than leaving the consumer to guess.
  */
 type ResolvedUrl = string | {
-    url: string;
-    expiresAt: number;
+  url: string;
+  expiresAt: number;
 };
 /** The framework's in-memory normal form for one file. */
 interface FileRef {
-    /** Client-side identity. Present from the moment the file is picked. */
-    localId: string;
-    /**
-     * Storage identity — id, key, path or filename, whichever this backend
-     * uses. Absent until the bytes have landed, and always absent for `fused`
-     * until the mutation succeeds.
-     */
-    handle?: string;
-    /** Raw bytes not yet sent. Present for `fused` and for `defer: true`. */
-    pending?: File;
-    name?: string;
-    mime?: string;
-    size?: number;
-    width?: number;
-    height?: number;
-    /**
-     * Metadata that belongs to THIS REFERENCE rather than to the file — a
-     * Sanity-style hotspot/crop, an alt text that differs per usage, a sort
-     * position. Opaque to the framework; carried through to the renderer.
-     */
-    usage?: Record<string, unknown>;
-    /**
-     * The original column entry this ref was read from. Absent for newly added
-     * files.
-     *
-     * ⚠️ `write` MUST merge onto this rather than rebuild the value. A Strapi
-     * media object carries `provider_metadata`, `createdAt`, `caption` and more;
-     * reading four known keys and writing four keys back DELETES the rest.
-     */
-    raw?: unknown;
+  /** Client-side identity. Present from the moment the file is picked. */
+  localId: string;
+  /**
+   * Storage identity — id, key, path or filename, whichever this backend
+   * uses. Absent until the bytes have landed, and always absent for `fused`
+   * until the mutation succeeds.
+   */
+  handle?: string;
+  /** Raw bytes not yet sent. Present for `fused` and for `defer: true`. */
+  pending?: File;
+  name?: string;
+  mime?: string;
+  size?: number;
+  width?: number;
+  height?: number;
+  /**
+   * Metadata that belongs to THIS REFERENCE rather than to the file — a
+   * Sanity-style hotspot/crop, an alt text that differs per usage, a sort
+   * position. Opaque to the framework; carried through to the renderer.
+   */
+  usage?: Record<string, unknown>;
+  /**
+   * The original column entry this ref was read from. Absent for newly added
+   * files.
+   *
+   * ⚠️ `write` MUST merge onto this rather than rebuild the value. A Strapi
+   * media object carries `provider_metadata`, `createdAt`, `caption` and more;
+   * reading four known keys and writing four keys back DELETES the rest.
+   */
+  raw?: unknown;
 }
 interface MapperCtx {
-    /** Registry name of the resource being read or written. */
-    resource: string;
-    /** Field name this column belongs to. */
-    field: string;
-    /** Declared cardinality — a single-value mapper must not emit an array. */
-    multiple: boolean;
-    /** The record the column belongs to. Absent on create. */
-    record?: Record<string, unknown>;
+  /** Registry name of the resource being read or written. */
+  resource: string;
+  /** Field name this column belongs to. */
+  field: string;
+  /** Declared cardinality — a single-value mapper must not emit an array. */
+  multiple: boolean;
+  /** The record the column belongs to. Absent on create. */
+  record?: Record<string, unknown>;
 }
 /**
  * Translates between the record's column and the normalised form.
@@ -87,88 +87,91 @@ interface MapperCtx {
  * only an id.
  */
 interface FileMapper<TRead = unknown, TWrite = TRead> {
-    read(column: TRead, ctx: MapperCtx): FileRef[];
-    /**
-     * `prev` is not decoration: some backends update a multi-value field by
-     * DIFF rather than replacement (PocketBase uses `field+` to add and
-     * `field-` to remove), and a diff cannot be computed without the old value.
-     */
-    write(next: FileRef[], prev: FileRef[], ctx: MapperCtx): TWrite;
-    /**
-     * Declares that `write` carries a `pending`-only ref (no `handle` yet)
-     * forward into its output — typically by embedding the raw `File` itself —
-     * rather than silently omitting it.
-     *
-     * This matters because a ref on a `fused`-pipeline storage NEVER has a
-     * `handle` before the record mutation runs: the bytes ride the mutation
-     * itself, so `pending` is all a freshly-added file ever has until the
-     * backend accepts it. A mapper that only knows how to write a `handle`
-     * (the ordinary case — `richImage`, `junction`) silently drops that file
-     * with no error the moment it is paired with a `fused` adapter.
-     * `assertFileStorageWiring` refuses that pairing at boot rather than
-     * discovering it via a vanished upload.
-     *
-     * Absent/false is the safe default: a mapper written assuming every ref
-     * already has a handle by the time `write` sees it should not claim
-     * otherwise. `scalarHandle` and `pocketbaseDiff` are the two mappers that
-     * set this.
-     */
-    carriesPending?: boolean;
+  read(column: TRead, ctx: MapperCtx): FileRef[];
+  /**
+   * `prev` is not decoration: some backends update a multi-value field by
+   * DIFF rather than replacement (PocketBase uses `field+` to add and
+   * `field-` to remove), and a diff cannot be computed without the old value.
+   */
+  write(next: FileRef[], prev: FileRef[], ctx: MapperCtx): TWrite;
+  /**
+   * Declares that `write` carries a `pending`-only ref (no `handle` yet)
+   * forward into its output — typically by embedding the raw `File` itself —
+   * rather than silently omitting it.
+   *
+   * This matters because a ref on a `fused`-pipeline storage NEVER has a
+   * `handle` before the record mutation runs: the bytes ride the mutation
+   * itself, so `pending` is all a freshly-added file ever has until the
+   * backend accepts it. A mapper that only knows how to write a `handle`
+   * (the ordinary case — `richImage`, `junction`) silently drops that file
+   * with no error the moment it is paired with a `fused` adapter.
+   * `assertFileStorageWiring` refuses that pairing at boot rather than
+   * discovering it via a vanished upload.
+   *
+   * Absent/false is the safe default: a mapper written assuming every ref
+   * already has a handle by the time `write` sees it should not claim
+   * otherwise. `scalarHandle` and `pocketbaseDiff` are the two mappers that
+   * set this.
+   */
+  carriesPending?: boolean;
 }
 interface UploadCtx {
-    signal: AbortSignal;
-    onProgress: (loaded: number, total: number) => void;
+  signal: AbortSignal;
+  onProgress: (loaded: number, total: number) => void;
 }
 interface ResolveCtx {
-    variant?: {
-        width?: number;
-        height?: number;
-    };
-    disposition?: 'inline' | 'attachment';
-    resource?: string;
-    record?: Record<string, unknown>;
+  variant?: {
+    width?: number;
+    height?: number;
+  };
+  disposition?: 'inline' | 'attachment';
+  resource?: string;
+  record?: Record<string, unknown>;
 }
 interface FileStorageAdapter {
-    pipeline: UploadPipeline;
-    /** Used by every field that does not name its own mapper. */
-    defaultMapper: FileMapper;
-    /** Only meaningful when `pipeline === 'fused'`. */
-    encoding?: FusedEncoding;
-    /** Storage-level default; a field may override. */
-    orphans?: OrphanPolicy;
-    /** For a `fused` adapter this is a no-op — the bytes have nowhere to go yet. */
-    upload(file: File, ctx: UploadCtx): Promise<FileRef>;
-    resolveUrl(ref: FileRef, ctx: ResolveCtx): ResolvedUrl | Promise<ResolvedUrl>;
-    /**
-     * Batched metadata read. Implement only when the column holds a bare handle
-     * with no name/mime/size — otherwise the framework never calls it.
-     *
-     * Honesty rule: a field this backend cannot report is left ABSENT on the
-     * returned ref. Never guess, and never substitute a zero.
-     */
-    stat?(refs: FileRef[]): Promise<FileRef[]>;
-    remove?(ref: FileRef): Promise<void>;
+  pipeline: UploadPipeline;
+  /** Used by every field that does not name its own mapper. */
+  defaultMapper: FileMapper;
+  /** Only meaningful when `pipeline === 'fused'`. */
+  encoding?: FusedEncoding;
+  /** Storage-level default; a field may override. */
+  orphans?: OrphanPolicy;
+  /** For a `fused` adapter this is a no-op — the bytes have nowhere to go yet. */
+  upload(file: File, ctx: UploadCtx): Promise<FileRef>;
+  resolveUrl(ref: FileRef, ctx: ResolveCtx): ResolvedUrl | Promise<ResolvedUrl>;
+  /**
+   * Batched metadata read. Implement only when the column holds a bare handle
+   * with no name/mime/size — otherwise the framework never calls it.
+   *
+   * Honesty rule: a field this backend cannot report is left ABSENT on the
+   * returned ref. Never guess, and never substitute a zero.
+   */
+  stat?(refs: FileRef[]): Promise<FileRef[]>;
+  remove?(ref: FileRef): Promise<void>;
 }
 interface FileStorageRegistry {
-    /** `undefined` resolves the `default` entry. Throws on an unknown name. */
-    get(name?: string): FileStorageAdapter;
-    has(name: string): boolean;
-    names(): string[];
-    /** True when any registered adapter carries its bytes inside the mutation. */
-    hasFused(): boolean;
+  /** `undefined` resolves the `default` entry. Throws on an unknown name. */
+  get(name?: string): FileStorageAdapter;
+  has(name: string): boolean;
+  names(): string[];
+  /** True when any registered adapter carries its bytes inside the mutation. */
+  hasFused(): boolean;
 }
-
+//#endregion
+//#region src/registry.d.ts
 /** Service name under which the registry is registered on the app. */
 declare const FILE_STORAGE_SERVICE: "fileStorage";
 declare function createFileStorageRegistry(map: Record<string, FileStorageAdapter>): FileStorageRegistry;
-
+//#endregion
+//#region src/plugin.d.ts
 /**
  * Declare the app's file storages as a named map, mirroring the existing
  * multi-data-provider convention. `default` is required; other keys are free
  * form and are what a field names in `f.file({ fileStorage: '…' })`.
  */
 declare function fileStoragePlugin(map: Record<string, FileStorageAdapter>): Plugin;
-
+//#endregion
+//#region src/mappers/ref.d.ts
 /**
  * Mint a ref with a fresh client-side identity.
  *
@@ -177,7 +180,8 @@ declare function fileStoragePlugin(map: Record<string, FileStorageAdapter>): Plu
  * readable and snapshots stable.
  */
 declare function newRef(init?: Partial<FileRef>): FileRef;
-
+//#endregion
+//#region src/kind.d.ts
 /**
  * Kind by mime; the filename is consulted only when mime is unknown.
  *
@@ -190,7 +194,8 @@ declare function newRef(init?: Partial<FileRef>): FileRef;
  * of the stored string, which can never match a uuid or other opaque handle.
  */
 declare function isImage(ref: FileRef): boolean;
-
+//#endregion
+//#region src/mappers/scalar-handle.d.ts
 type ScalarColumn = string | string[] | null | undefined;
 type ScalarWriteValue = string | File | (string | File)[] | null;
 /**
@@ -200,33 +205,35 @@ type ScalarWriteValue = string | File | (string | File)[] | null;
  * in sync for no behavioural gain.
  */
 declare function scalarHandle(): FileMapper<ScalarColumn, ScalarWriteValue>;
-
+//#endregion
+//#region src/mappers/rich-image.d.ts
 interface RichImageOpts {
-    /**
-     * Who owns the focal point.
-     *
-     *  - `'usage'` — it lives on the reference inside the record, so the same
-     *    asset crops differently in two records (Sanity-shaped).
-     *  - `'file'` — it is a property of the file that the storage owns; the
-     *    mapper leaves it alone (Directus-shaped).
-     *  - `false`  — this column has none.
-     *
-     * There is no default. Guessing wrong silently corrupts a neighbouring
-     * record's crop, which is exactly the failure nobody notices for months.
-     */
-    focus: 'usage' | 'file' | false;
-    /** Dotted path to the handle inside the object. Defaults to `'id'`. */
-    handleKey?: string;
-    /** Keys lifted into `usage` when `focus === 'usage'`. */
-    usageKeys?: string[];
+  /**
+   * Who owns the focal point.
+   *
+   *  - `'usage'` — it lives on the reference inside the record, so the same
+   *    asset crops differently in two records (Sanity-shaped).
+   *  - `'file'` — it is a property of the file that the storage owns; the
+   *    mapper leaves it alone (Directus-shaped).
+   *  - `false`  — this column has none.
+   *
+   * There is no default. Guessing wrong silently corrupts a neighbouring
+   * record's crop, which is exactly the failure nobody notices for months.
+   */
+  focus: 'usage' | 'file' | false;
+  /** Dotted path to the handle inside the object. Defaults to `'id'`. */
+  handleKey?: string;
+  /** Keys lifted into `usage` when `focus === 'usage'`. */
+  usageKeys?: string[];
 }
 declare function richImage(opts: RichImageOpts): FileMapper<unknown, unknown>;
-
+//#endregion
+//#region src/mappers/junction.d.ts
 interface JunctionOpts {
-    /** Column on the junction row holding the file's handle. */
-    fileKey: string;
-    /** Column holding the 1-based position. Omit when the table is unordered. */
-    sortKey?: string;
+  /** Column on the junction row holding the file's handle. */
+  fileKey: string;
+  /** Column holding the 1-based position. Omit when the table is unordered. */
+  sortKey?: string;
 }
 type Row = Record<string, unknown>;
 /**
@@ -235,39 +242,40 @@ type Row = Record<string, unknown>;
  * must survive a reorder: dropping it would delete and recreate every row.
  */
 declare function junction(opts: JunctionOpts): FileMapper<Row[] | null | undefined, Row[]>;
-
+//#endregion
+//#region src/contract/run-contract.d.ts
 interface ContractOpts {
-    /** A FRESH adapter per case — shared state between cases hides bugs. */
-    adapter: () => FileStorageAdapter;
-    mapper: FileMapper;
-    /** Representative column values this mapper reads, for the invariants. */
-    sampleColumn: {
-        single: unknown;
-        multiple: unknown;
-    };
-    /** Skip upload cases for adapters whose bytes ride the mutation. */
-    skipUpload?: boolean;
-    /**
-     * Set for a mapper whose `write` returns a COLUMN PATCH rather than a column
-     * value — `pocketbaseDiff` is the one in this package.
-     *
-     * Round-trip identity is meaningless for such a mapper: it never returns the
-     * value it was given, it returns the keys needed to change it. The patch
-     * invariants below replace the round-trip cases rather than sitting beside
-     * them, because running both would demand two contradictory things of one
-     * `write`.
-     */
-    writesColumnPatch?: boolean;
-    /**
-     * Context every `resolveUrl` case is called with. Defaults to `{}`.
-     *
-     * Supply it for an adapter whose URL cannot be built from a handle alone.
-     * A PocketBase filename is meaningless by itself — the URL is assembled from
-     * collection + record + filename — so that adapter correctly THROWS on an
-     * empty context, and the contract must hand it a real one rather than
-     * treating the throw as a conformance failure.
-     */
-    resolveCtx?: ResolveCtx;
+  /** A FRESH adapter per case — shared state between cases hides bugs. */
+  adapter: () => FileStorageAdapter;
+  mapper: FileMapper;
+  /** Representative column values this mapper reads, for the invariants. */
+  sampleColumn: {
+    single: unknown;
+    multiple: unknown;
+  };
+  /** Skip upload cases for adapters whose bytes ride the mutation. */
+  skipUpload?: boolean;
+  /**
+   * Set for a mapper whose `write` returns a COLUMN PATCH rather than a column
+   * value — `pocketbaseDiff` is the one in this package.
+   *
+   * Round-trip identity is meaningless for such a mapper: it never returns the
+   * value it was given, it returns the keys needed to change it. The patch
+   * invariants below replace the round-trip cases rather than sitting beside
+   * them, because running both would demand two contradictory things of one
+   * `write`.
+   */
+  writesColumnPatch?: boolean;
+  /**
+   * Context every `resolveUrl` case is called with. Defaults to `{}`.
+   *
+   * Supply it for an adapter whose URL cannot be built from a handle alone.
+   * A PocketBase filename is meaningless by itself — the URL is assembled from
+   * collection + record + filename — so that adapter correctly THROWS on an
+   * empty context, and the contract must hand it a real one rather than
+   * treating the throw as a conformance failure.
+   */
+  resolveCtx?: ResolveCtx;
 }
 /**
  * The test runner, injected.
@@ -278,8 +286,8 @@ interface ContractOpts {
  * or node:test run the same contract.
  */
 interface ContractRunner {
-    it: (name: string, fn: () => void | Promise<void>) => void;
-    expect: (actual: never) => unknown;
+  it: (name: string, fn: () => void | Promise<void>) => void;
+  expect: (actual: never) => unknown;
 }
 /**
  * The conformance suite every adapter owes. Call inside a `describe`.
@@ -289,16 +297,17 @@ interface ContractRunner {
  * if it is executable by the person doing the stretching.
  */
 declare function runFileStorageContract(opts: ContractOpts, runner: ContractRunner): void;
-
+//#endregion
+//#region src/contract/fake-adapter.d.ts
 interface FakeAdapterOpts {
-    /** Emit this many progress ticks before resolving. Default 2. */
-    progressTicks?: number;
-    /** Make every upload reject with this message. */
-    failWith?: string;
-    /** Return signed URLs that expire this many ms from resolution. */
-    signedTtlMs?: number;
-    /** Default `'immediate'`. Set `'fused'` to stand in for an inline/PocketBase-shaped storage. */
-    pipeline?: 'immediate' | 'fused';
+  /** Emit this many progress ticks before resolving. Default 2. */
+  progressTicks?: number;
+  /** Make every upload reject with this message. */
+  failWith?: string;
+  /** Return signed URLs that expire this many ms from resolution. */
+  signedTtlMs?: number;
+  /** Default `'immediate'`. Set `'fused'` to stand in for an inline/PocketBase-shaped storage. */
+  pipeline?: 'immediate' | 'fused';
 }
 /**
  * In-memory adapter. Exists so the contract suite can be tested against
@@ -306,23 +315,24 @@ interface FakeAdapterOpts {
  * when their own adapter fails a case.
  */
 declare function createFakeAdapter(opts?: FakeAdapterOpts): FileStorageAdapter & {
-    stored: Map<string, File>;
-    removed: string[];
+  stored: Map<string, File>;
+  removed: string[];
 };
-
+//#endregion
+//#region src/adapters/inline.d.ts
 interface InlineFileStorageOpts {
-    /**
-     * How the data-provider wrapper should encode the bytes into the mutation.
-     * `base64` transforms the value; `multipart` and `graphql-upload` set the
-     * request body and are mutually exclusive with each other.
-     */
-    encoding: FusedEncoding;
-    /**
-     * How a saved file is read back. `ctx.resource` and `ctx.record` are given
-     * because backends of this shape usually address files through the record
-     * that owns them.
-     */
-    resolveUrl: (ref: FileRef, ctx: ResolveCtx) => ResolvedUrl | Promise<ResolvedUrl>;
+  /**
+   * How the data-provider wrapper should encode the bytes into the mutation.
+   * `base64` transforms the value; `multipart` and `graphql-upload` set the
+   * request body and are mutually exclusive with each other.
+   */
+  encoding: FusedEncoding;
+  /**
+   * How a saved file is read back. `ctx.resource` and `ctx.record` are given
+   * because backends of this shape usually address files through the record
+   * that owns them.
+   */
+  resolveUrl: (ref: FileRef, ctx: ResolveCtx) => ResolvedUrl | Promise<ResolvedUrl>;
 }
 /**
  * The storage that is not a storage: the backend takes the file inside the
@@ -334,19 +344,20 @@ interface InlineFileStorageOpts {
  * request path — that can report it.
  */
 declare function inlineFileStorage(opts: InlineFileStorageOpts): FileStorageAdapter;
-
+//#endregion
+//#region src/adapters/nhost.d.ts
 interface NhostFileStorageOpts {
-    /** Storage service base URL, e.g. `https://<project>.storage.<region>.nhost.run`. */
-    baseUrl: string;
-    /**
-     * Access token supplier. Injected rather than read from localStorage: the
-     * v0.2 implementation hardcoded a storage key and a window global, which
-     * meant one app shape was supported and no test could drive it.
-     */
-    getToken: () => string | null | Promise<string | null>;
-    bucketId?: string;
-    orphans?: OrphanPolicy;
-    fetchImpl?: typeof fetch;
+  /** Storage service base URL, e.g. `https://<project>.storage.<region>.nhost.run`. */
+  baseUrl: string;
+  /**
+   * Access token supplier. Injected rather than read from localStorage: the
+   * v0.2 implementation hardcoded a storage key and a window global, which
+   * meant one app shape was supported and no test could drive it.
+   */
+  getToken: () => string | null | Promise<string | null>;
+  bucketId?: string;
+  orphans?: OrphanPolicy;
+  fetchImpl?: typeof fetch;
 }
 /**
  * nhost storage: bytes go up first, the column keeps the file's UUID, and the
@@ -356,90 +367,92 @@ interface NhostFileStorageOpts {
  * as v0.2 did — writes a link with a TTL into the database.
  */
 declare function nhostFileStorage(opts: NhostFileStorageOpts): FileStorageAdapter;
-
+//#endregion
+//#region src/adapters/supabase.d.ts
 /**
  * The slice of `@supabase/supabase-js` this adapter uses, declared
  * structurally so the package keeps zero runtime dependencies and the adapter
  * can be driven by a plain object in tests.
  */
 interface SupabaseStorageLike {
-    storage: {
-        from(bucket: string): {
-            upload(path: string, file: File, opts?: {
-                contentType?: string;
-                upsert?: boolean;
-            }): Promise<{
-                data: {
-                    path: string;
-                } | null;
-                error: {
-                    message: string;
-                } | null;
-            }>;
-            getPublicUrl(path: string): {
-                data: {
-                    publicUrl: string;
-                };
-            };
-            createSignedUrl(path: string, expiresIn: number): Promise<{
-                data: {
-                    signedUrl: string;
-                } | null;
-                error: {
-                    message: string;
-                } | null;
-            }>;
-            remove(paths: string[]): Promise<{
-                data: unknown;
-                error: {
-                    message: string;
-                } | null;
-            }>;
+  storage: {
+    from(bucket: string): {
+      upload(path: string, file: File, opts?: {
+        contentType?: string;
+        upsert?: boolean;
+      }): Promise<{
+        data: {
+          path: string;
+        } | null;
+        error: {
+          message: string;
+        } | null;
+      }>;
+      getPublicUrl(path: string): {
+        data: {
+          publicUrl: string;
         };
+      };
+      createSignedUrl(path: string, expiresIn: number): Promise<{
+        data: {
+          signedUrl: string;
+        } | null;
+        error: {
+          message: string;
+        } | null;
+      }>;
+      remove(paths: string[]): Promise<{
+        data: unknown;
+        error: {
+          message: string;
+        } | null;
+      }>;
     };
+  };
 }
 interface SupabaseFileStorageOpts {
-    client: SupabaseStorageLike;
-    bucket: string;
-    /** Public buckets yield permanent URLs; signed buckets yield expiring ones. */
-    access: 'public' | 'signed';
-    /** Lifetime of a signed URL in seconds. Default 3600. */
-    signedTtlSec?: number;
-    /** Prepended to every generated object path, e.g. `'avatars'`. */
-    pathPrefix?: string;
-    orphans?: OrphanPolicy;
+  client: SupabaseStorageLike;
+  bucket: string;
+  /** Public buckets yield permanent URLs; signed buckets yield expiring ones. */
+  access: 'public' | 'signed';
+  /** Lifetime of a signed URL in seconds. Default 3600. */
+  signedTtlSec?: number;
+  /** Prepended to every generated object path, e.g. `'avatars'`. */
+  pathPrefix?: string;
+  orphans?: OrphanPolicy;
 }
 declare function supabaseFileStorage(opts: SupabaseFileStorageOpts): FileStorageAdapter;
-
+//#endregion
+//#region src/adapters/s3.d.ts
 /** What the adopter's signing endpoint hands back. */
 interface SignedTarget {
-    /**
-     * The object key. **The server chooses it, not the client** — letting the
-     * browser name the object is how buckets get overwritten by whoever asks.
-     */
-    key: string;
-    url: string;
-    method?: 'PUT' | 'POST';
-    /** Headers that were part of the signature. Sent verbatim. */
-    headers?: Record<string, string>;
-    /** POST-policy form fields. Sent before the file part. */
-    fields?: Record<string, string>;
+  /**
+   * The object key. **The server chooses it, not the client** — letting the
+   * browser name the object is how buckets get overwritten by whoever asks.
+   */
+  key: string;
+  url: string;
+  method?: 'PUT' | 'POST';
+  /** Headers that were part of the signature. Sent verbatim. */
+  headers?: Record<string, string>;
+  /** POST-policy form fields. Sent before the file part. */
+  fields?: Record<string, string>;
 }
 interface S3FileStorageOpts {
-    /** Ask your backend to sign. Authorization happens there, not here. */
-    sign: (file: {
-        name: string;
-        type: string;
-        size: number;
-    }) => Promise<SignedTarget>;
-    /** CDN or bucket origin for permanent read URLs. */
-    publicBaseUrl?: string;
-    /** Supply for private buckets; return an expiring URL. */
-    signView?: (key: string, ctx: ResolveCtx) => Promise<ResolvedUrl>;
-    remove?: (key: string) => Promise<void>;
-    orphans?: OrphanPolicy;
-    /** Injected for tests. Defaults to `new XMLHttpRequest()`. */
-    xhrImpl?: () => XMLHttpRequest;
+  /** Ask your backend to sign. Authorization happens there, not here. */
+  sign: (file: {
+    name: string;
+    type: string;
+    size: number;
+  }) => Promise<SignedTarget>;
+  /** CDN or bucket origin for permanent read URLs. */
+  publicBaseUrl?: string;
+  /** Supply for private buckets; return an expiring URL. */
+  signView?: (key: string, ctx: ResolveCtx) => Promise<ResolvedUrl>;
+  remove?: (key: string) => Promise<void>;
+  orphans?: OrphanPolicy;
+  /** Injected for tests. Defaults to `new XMLHttpRequest()`. */
+  xhrImpl?: () => XMLHttpRequest;
 }
 /**
  * Direct-to-bucket upload behind a signed handshake: ask the server to sign,
@@ -450,7 +463,8 @@ interface S3FileStorageOpts {
  * absence to be felt.
  */
 declare function s3FileStorage(opts: S3FileStorageOpts): FileStorageAdapter;
-
+//#endregion
+//#region src/adapters/pocketbase.d.ts
 /**
  * PocketBase stores a filename per file and updates multi-value fields by
  * DIFF: `field+` appends, `field-` removes by name. Single-value fields are
@@ -458,14 +472,14 @@ declare function s3FileStorage(opts: S3FileStorageOpts): FileStorageAdapter;
  */
 declare function pocketbaseDiff(): FileMapper<string | string[] | null | undefined, unknown>;
 interface PocketbaseFileStorageOpts {
-    /** PocketBase origin, e.g. `http://127.0.0.1:8090`. */
-    baseUrl: string;
-    /** Set when the file field is marked Protected in the collection schema. */
-    protectedFiles?: boolean;
-    /** Supplies a short-lived file token — `pb.files.getToken()`. */
-    getFileToken?: () => Promise<string>;
-    /** Lifetime assumed for a file token, in seconds. Default 120. */
-    tokenTtlSec?: number;
+  /** PocketBase origin, e.g. `http://127.0.0.1:8090`. */
+  baseUrl: string;
+  /** Set when the file field is marked Protected in the collection schema. */
+  protectedFiles?: boolean;
+  /** Supplies a short-lived file token — `pb.files.getToken()`. */
+  getFileToken?: () => Promise<string>;
+  /** Lifetime assumed for a file token, in seconds. Default 120. */
+  tokenTtlSec?: number;
 }
 /**
  * PocketBase: bytes ride the record mutation as multipart, the column keeps a
@@ -476,7 +490,8 @@ interface PocketbaseFileStorageOpts {
  * one the example app runs against.
  */
 declare function pocketbaseFileStorage(opts: PocketbaseFileStorageOpts): FileStorageAdapter;
-
+//#endregion
+//#region src/mappers/column-patch.d.ts
 /**
  * A mapper's answer when the change cannot be expressed as "the new value of
  * this column".
@@ -489,12 +504,13 @@ declare function pocketbaseFileStorage(opts: PocketbaseFileStorageOpts): FileSto
  */
 declare const COLUMN_PATCH: unique symbol;
 interface ColumnPatch {
-    [COLUMN_PATCH]: true;
-    keys: Record<string, unknown>;
+  [COLUMN_PATCH]: true;
+  keys: Record<string, unknown>;
 }
 declare function columnPatch(keys: Record<string, unknown>): ColumnPatch;
 declare function isColumnPatch(value: unknown): value is ColumnPatch;
-
+//#endregion
+//#region src/wrapper/with-file-storage.d.ts
 /** Stamped on a wrapped provider so the wiring assertion can see it. */
 declare const FILE_STORAGE_WRAPPED: unique symbol;
 /**
@@ -523,21 +539,22 @@ declare function withFileStorage<T>(provider: T, app: AppRuntime): T;
  * being Files. Only what remains decides the request body.
  */
 interface EncodingPlan {
-    /** Encoding EXPLICITLY declared for a field, via `f.file({ fileStorage })`. Authoritative. */
-    knownEncodings: Map<string, FusedEncoding>;
-    /**
-     * Assumed for a payload key with NO declared field to consult — the
-     * resource isn't registered, or has no `f.file()` for this key. Mirrors
-     * `ui.fileStorage ?? 'default'`, the exact resolution a KNOWN field with no
-     * explicit storage name already gets, extended to "no field info at all".
-     * This is what keeps a single-storage app working without ever having to
-     * declare its fields through `@burojs/field-types`.
-     */
-    defaultEncoding: FusedEncoding;
-    /** Body encoding for whatever Files remain once base64 keys are converted. */
-    bodyEncoding: Exclude<FusedEncoding, 'base64'>;
+  /** Encoding EXPLICITLY declared for a field, via `f.file({ fileStorage })`. Authoritative. */
+  knownEncodings: Map<string, FusedEncoding>;
+  /**
+   * Assumed for a payload key with NO declared field to consult — the
+   * resource isn't registered, or has no `f.file()` for this key. Mirrors
+   * `ui.fileStorage ?? 'default'`, the exact resolution a KNOWN field with no
+   * explicit storage name already gets, extended to "no field info at all".
+   * This is what keeps a single-storage app working without ever having to
+   * declare its fields through `@burojs/field-types`.
+   */
+  defaultEncoding: FusedEncoding;
+  /** Body encoding for whatever Files remain once base64 keys are converted. */
+  bodyEncoding: Exclude<FusedEncoding, 'base64'>;
 }
-
+//#endregion
+//#region src/wrapper/assert-wiring.d.ts
 /**
  * Three checks that must fail at boot rather than at runtime.
  *
@@ -560,7 +577,8 @@ interface EncodingPlan {
  * provider.
  */
 declare function assertFileStorageWiring(app: AppRuntime, provider: unknown): void;
-
+//#endregion
+//#region src/wrapper/encode.d.ts
 /**
  * Splice column patches into the payload; leave everything else alone.
  *
@@ -596,14 +614,17 @@ declare function containsColumnPatch(value: unknown, seen?: WeakSet<object>): bo
  * content-type, because the browser writes the boundary.
  */
 declare function encodePayload(variables: Record<string, unknown>, plan: EncodingPlan): Promise<Record<string, unknown> | FormData>;
-
+//#endregion
+//#region src/baseline-carrier.d.ts
 /**
  * Copy the opaque mapped-file baseline capability from a decoded record to a
  * fresh edit payload. The physical baseline itself remains private to the
  * provider wrapper; this helper can neither inspect nor serialize it.
  */
 declare function inheritFileMapperBaseline<T extends object>(source: object, target: T): T;
-
+//#endregion
+//#region src/index.d.ts
 declare const PACKAGE_NAME: "@burojs/file-storage";
-
+//#endregion
 export { COLUMN_PATCH, type ColumnPatch, type ContractOpts, type ContractRunner, FILE_STORAGE_SERVICE, FILE_STORAGE_WRAPPED, type FakeAdapterOpts, type FileMapper, type FileRef, type FileStorageAdapter, type FileStorageRegistry, type FusedEncoding, type InlineFileStorageOpts, type JunctionOpts, type MapperCtx, type NhostFileStorageOpts, type OrphanPolicy, PACKAGE_NAME, type PocketbaseFileStorageOpts, type ResolveCtx, type ResolvedUrl, type RichImageOpts, type S3FileStorageOpts, type SignedTarget, type SupabaseFileStorageOpts, type SupabaseStorageLike, type UploadCtx, type UploadPipeline, assertFileStorageWiring, columnPatch, containsColumnPatch, containsFile, createFakeAdapter, createFileStorageRegistry, encodePayload, fileStoragePlugin, inheritFileMapperBaseline, inlineFileStorage, isColumnPatch, isImage, junction, newRef, nhostFileStorage, pocketbaseDiff, pocketbaseFileStorage, richImage, runFileStorageContract, s3FileStorage, scalarHandle, splicePatches, supabaseFileStorage, withFileStorage };
+//# sourceMappingURL=index.d.cts.map