@burojs/file-storage 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,609 @@
+import { Plugin, AppRuntime } from '@burojs/core';
+
+/** How a file's bytes travel relative to the record mutation. */
+type UploadPipeline = 'immediate' | 'fused' | 'handshake' | 'resumable';
+/**
+ * How a `fused` adapter wants its bytes encoded into the mutation.
+ *
+ * `base64` is a VALUE transform — the File becomes a string before the body is
+ * assembled — so it composes with anything. `multipart` and `graphql-upload`
+ * are REQUEST-BODY encodings and are mutually exclusive: one request has one
+ * body.
+ */
+type FusedEncoding = 'multipart' | 'base64' | 'graphql-upload';
+/** What to do with bytes that landed but whose form was never saved. */
+type OrphanPolicy = 'best-effort' | 'keep';
+/**
+ * A resolved display URL.
+ *
+ * A plain string means the URL is permanent — cache it, render it on the
+ * server. The object form means it is signed: the cache re-resolves on expiry,
+ * and the URL must never reach the database or an SSR payload.
+ *
+ * ⚠️ `expiresAt` (epoch ms) is deliberately REQUIRED on the object arm. An
+ * omitted expiry is an accident, not a decision — the same rule the data
+ * provider already applies to `getCount`'s `total`
+ * (`docs/data-provider-guide.md:92`). Without it, an adapter that signs a URL
+ * but stays silent about the deadline gets that URL cached FOREVER, which is
+ * precisely the rotting-link failure this port exists to prevent. An adapter
+ * that genuinely cannot learn the expiry must pick a conservative one and say
+ * so, rather than leaving the consumer to guess.
+ */
+type ResolvedUrl = string | {
+    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;
+}
+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>;
+}
+/**
+ * Translates between the record's column and the normalised form.
+ *
+ * Pure — no I/O, no React, no network. This is what makes "any API can be
+ * stretched onto this" a testable claim rather than an aspiration.
+ *
+ * `TRead` and `TWrite` are separate because read and write shapes genuinely
+ * differ on real backends: Strapi returns a rich media object and accepts back
+ * 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;
+}
+interface UploadCtx {
+    signal: AbortSignal;
+    onProgress: (loaded: number, total: number) => void;
+}
+interface ResolveCtx {
+    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>;
+}
+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;
+}
+
+/** 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;
+
+/**
+ * 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;
+
+/**
+ * Mint a ref with a fresh client-side identity.
+ *
+ * Deliberately a counter rather than `crypto.randomUUID()`: ids are
+ * process-local and never persisted, and a counter keeps test output
+ * readable and snapshots stable.
+ */
+declare function newRef(init?: Partial<FileRef>): FileRef;
+
+/**
+ * Kind by mime; the filename is consulted only when mime is unknown.
+ *
+ * A pure predicate over `FileRef`, not a UI concern — it lives next to the
+ * type it describes so any renderer, in `@burojs/ui-shadcn` or a future UI
+ * kit, answers "is this an image?" the same way. Two independently
+ * maintained copies (one per renderer) drift the moment one gains a mime
+ * type or extension the other lacks — which is exactly the bug this
+ * function replaces: the deleted `isLikelyImageUrl` regexed an extension out
+ * of the stored string, which can never match a uuid or other opaque handle.
+ */
+declare function isImage(ref: FileRef): boolean;
+
+type ScalarColumn = string | string[] | null | undefined;
+type ScalarWriteValue = string | File | (string | File)[] | null;
+/**
+ * The column IS the handle: a URL, an id, a key, a path, a filename. One
+ * mapper covers all four because the difference between them is meaning, not
+ * structure — and three names for one function would be three things to keep
+ * in sync for no behavioural gain.
+ */
+declare function scalarHandle(): FileMapper<ScalarColumn, ScalarWriteValue>;
+
+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[];
+}
+declare function richImage(opts: RichImageOpts): FileMapper<unknown, unknown>;
+
+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;
+}
+type Row = Record<string, unknown>;
+/**
+ * A column that is an array of junction ROWS rather than of files — Directus
+ * M2M being the canonical case. Each row carries its own primary key, which
+ * must survive a reorder: dropping it would delete and recreate every row.
+ */
+declare function junction(opts: JunctionOpts): FileMapper<Row[] | null | undefined, Row[]>;
+
+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;
+}
+/**
+ * The test runner, injected.
+ *
+ * `src/` may not import vitest: this package promises zero runtime
+ * dependencies, and a module under `src/` importing a test framework ships
+ * that import in the published bundle. Injection also lets an adopter on jest
+ * or node:test run the same contract.
+ */
+interface ContractRunner {
+    it: (name: string, fn: () => void | Promise<void>) => void;
+    expect: (actual: never) => unknown;
+}
+/**
+ * The conformance suite every adapter owes. Call inside a `describe`.
+ *
+ * Exported from the package so adopters can point it at their own adapter —
+ * the claim "any API can be stretched onto this port" is only worth something
+ * if it is executable by the person doing the stretching.
+ */
+declare function runFileStorageContract(opts: ContractOpts, runner: ContractRunner): void;
+
+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';
+}
+/**
+ * In-memory adapter. Exists so the contract suite can be tested against
+ * something known-correct, and so adopters have a baseline to diff against
+ * when their own adapter fails a case.
+ */
+declare function createFakeAdapter(opts?: FakeAdapterOpts): FileStorageAdapter & {
+    stored: Map<string, File>;
+    removed: string[];
+};
+
+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>;
+}
+/**
+ * The storage that is not a storage: the backend takes the file inside the
+ * record mutation, so there is no upload endpoint and no handle until the
+ * mutation succeeds.
+ *
+ * `upload` deliberately does nothing but wrap the File in a ref. Progress here
+ * belongs to the mutation, and it is `withFileStorage` — the only code on the
+ * request path — that can report it.
+ */
+declare function inlineFileStorage(opts: InlineFileStorageOpts): FileStorageAdapter;
+
+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;
+}
+/**
+ * nhost storage: bytes go up first, the column keeps the file's UUID, and the
+ * display URL is signed and short-lived.
+ *
+ * ⚠️ The handle is the id, NOT the presigned URL. Storing the presigned URL —
+ * as v0.2 did — writes a link with a TTL into the database.
+ */
+declare function nhostFileStorage(opts: NhostFileStorageOpts): FileStorageAdapter;
+
+/**
+ * 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;
+            }>;
+        };
+    };
+}
+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;
+}
+declare function supabaseFileStorage(opts: SupabaseFileStorageOpts): FileStorageAdapter;
+
+/** 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>;
+}
+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;
+}
+/**
+ * Direct-to-bucket upload behind a signed handshake: ask the server to sign,
+ * send the bytes straight to storage, keep the key.
+ *
+ * Uses XHR rather than fetch on purpose — browsers expose no upload progress
+ * on fetch, and this is the pipeline whose files are large enough for the
+ * absence to be felt.
+ */
+declare function s3FileStorage(opts: S3FileStorageOpts): FileStorageAdapter;
+
+/**
+ * PocketBase stores a filename per file and updates multi-value fields by
+ * DIFF: `field+` appends, `field-` removes by name. Single-value fields are
+ * replaced outright, and cleared with an empty string.
+ */
+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: bytes ride the record mutation as multipart, the column keeps a
+ * filename that only means anything alongside its record, images get thumbs
+ * from a query parameter, and protected files need a short-lived token.
+ *
+ * It is the hardest of the four reference pipelines, which is why it is the
+ * one the example app runs against.
+ */
+declare function pocketbaseFileStorage(opts: PocketbaseFileStorageOpts): FileStorageAdapter;
+
+/**
+ * A mapper's answer when the change cannot be expressed as "the new value of
+ * this column".
+ *
+ * PocketBase updates a multi-value file field through SIBLING keys — `docs+`
+ * to append, `docs-` to remove named files — so there is no single value to
+ * return. Rather than special-casing one backend inside the write path, a
+ * mapper may return this marker and `withFileStorage` splices its keys into
+ * the payload instead of assigning to the field's own key.
+ */
+declare const COLUMN_PATCH: unique symbol;
+interface ColumnPatch {
+    [COLUMN_PATCH]: true;
+    keys: Record<string, unknown>;
+}
+declare function columnPatch(keys: Record<string, unknown>): ColumnPatch;
+declare function isColumnPatch(value: unknown): value is ColumnPatch;
+
+/** Stamped on a wrapped provider so the wiring assertion can see it. */
+declare const FILE_STORAGE_WRAPPED: unique symbol;
+/**
+ * Rewrite outgoing mutations that actually carry bytes.
+ *
+ * The decision is PER REQUEST, from the payload — never global. Mixing
+ * pipelines is the ordinary case (a storage service for most fields, two
+ * places that take the file inline), so a payload with no File is handed to
+ * the underlying provider untouched, by reference: no FormData, no
+ * re-encoding, no surprise.
+ */
+declare function withFileStorage<T>(provider: T, app: AppRuntime): T;
+/**
+ * Which encoding each payload key needs, and which body encoding the rest
+ * fall back to — for ONE resource.
+ *
+ * ⚠️ This must be resolved per resource, not once per provider. An earlier
+ * version picked a single encoding from the whole registry, so an app with a
+ * multipart storage anywhere and a base64 storage anywhere else sent the
+ * base64 field's File into FormData as raw binary — never encoded, no boot
+ * error, no runtime error, silently wrong data. It also contradicted the
+ * type's own promise that base64 "composes with anything", which is exactly
+ * why `assertFileStorageWiring` permits that combination.
+ *
+ * `base64` is a VALUE transform: those fields are converted first and stop
+ * 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'>;
+}
+
+/**
+ * Three checks that must fail at boot rather than at runtime.
+ *
+ * 1. A fused storage with an unwrapped provider. Files in `variables` reach
+ *    `JSON.stringify` and become `{}` — the upload silently does nothing, the
+ *    request succeeds, and nobody finds out until someone opens the record.
+ * 2. A fused storage paired with a mapper that cannot carry a `pending` file
+ *    forward (`mapper.carriesPending` is not set). A ref on a fused pipeline
+ *    never has a `handle` before the mutation runs — only `pending` — so a
+ *    mapper that writes nothing for a handle-less ref (the ordinary case:
+ *    `richImage`, `junction`) silently drops every file added through that
+ *    field. This is the same class of failure as #1 — a fused storage whose
+ *    mapper cannot carry the file forward is exactly as broken as one with no
+ *    wrapper — so it gets the same treatment: fail loudly before any user
+ *    touches the form, not discover it when a saved record turns out empty.
+ * 3. Two incompatible body encodings on one resource. One request has one
+ *    body; discovering that during a save is discovering it too late.
+ *
+ * Called by the host composition layer that owns both the app and its data
+ * provider.
+ */
+declare function assertFileStorageWiring(app: AppRuntime, provider: unknown): void;
+
+/**
+ * Splice column patches into the payload; leave everything else alone.
+ *
+ * Reference identity is preserved ONLY when the payload carries no column
+ * patch at all. The moment even an EMPTY patch (`{ keys: {} }` — "nothing
+ * changed for this field") is present, the field's own key must still be
+ * dropped: forwarding the raw patch marker as the field's value would
+ * overwrite the column with `{ keys: {} }` instead of leaving it alone. So a
+ * fresh object is built whenever any patch is present, empty or not — this
+ * function does not claim otherwise.
+ */
+declare function splicePatches(variables: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Does this payload actually carry bytes? Everything downstream hinges on it.
+ *
+ * ⚠️ No depth cap. An earlier version stopped at four levels, which meant a
+ * File nested deeper was silently declared absent — the payload then took the
+ * untouched fast path and the File reached `JSON.stringify` and became `{}`.
+ * Today's mappers never nest a File below the first level, so the cap was
+ * unreachable; a future rich-content mapper would have made it a silent
+ * data-loss bug. Cycles are handled by tracking visited objects rather than by
+ * limiting depth.
+ */
+declare function containsFile(value: unknown, seen?: WeakSet<object>): boolean;
+/** Getter-safe recursive check used to reject unsupported bulk column patches. */
+declare function containsColumnPatch(value: unknown, seen?: WeakSet<object>): boolean;
+/**
+ * Turn a payload carrying Files into something the provider can send.
+ *
+ * `base64` is a VALUE transform, so the payload stays a plain object and
+ * composes with anything. `multipart` and `graphql-upload` produce a FormData
+ * — the provider must send it as the body verbatim and must NOT set a
+ * content-type, because the browser writes the boundary.
+ */
+declare function encodePayload(variables: Record<string, unknown>, plan: EncodingPlan): Promise<Record<string, unknown> | FormData>;
+
+/**
+ * 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;
+
+declare const PACKAGE_NAME: "@burojs/file-storage";
+
+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 };