@burojs/file-storage 0.2.0

package/dist/index.js

@@ -0,0 +1,878 @@
+// src/registry.ts
+var FILE_STORAGE_SERVICE = "fileStorage";
+function createFileStorageRegistry(map) {
+  if (!map.default) {
+    throw new Error(
+      "fileStoragePlugin requires a 'default' entry \u2014 every file field that does not name a storage resolves to it."
+    );
+  }
+  const entries = new Map(Object.entries(map));
+  return {
+    get(name = "default") {
+      const found = entries.get(name);
+      if (!found) {
+        throw new Error(
+          `Unknown file storage '${name}'. Registered: ${[...entries.keys()].join(", ")}.`
+        );
+      }
+      return found;
+    },
+    has: (name) => entries.has(name),
+    names: () => [...entries.keys()],
+    hasFused: () => [...entries.values()].some((a) => a.pipeline === "fused")
+  };
+}
+
+// src/plugin.ts
+function fileStoragePlugin(map) {
+  const adapters = Object.freeze({ ...map });
+  return {
+    name: "@burojs/file-storage",
+    enforce: "pre",
+    setup: (api) => {
+      api.runtime.registerService(FILE_STORAGE_SERVICE, () => createFileStorageRegistry(adapters));
+    }
+  };
+}
+
+// src/mappers/ref.ts
+var seq = 0;
+function newRef(init = {}) {
+  seq += 1;
+  return { localId: `ref-${seq}`, ...init };
+}
+
+// src/kind.ts
+function isImage(ref) {
+  if (ref.mime) return ref.mime.startsWith("image/");
+  const name = ref.name ?? "";
+  return /\.(png|jpe?g|gif|webp|svg|avif)$/i.test(name);
+}
+
+// src/mappers/scalar-handle.ts
+function scalarHandle() {
+  return {
+    carriesPending: true,
+    read(column) {
+      if (column == null) return [];
+      const list = Array.isArray(column) ? column : [column];
+      return list.filter((entry) => entry !== "" && entry != null).map((entry) => newRef({ handle: entry, raw: entry, name: tail(entry) }));
+    },
+    write(next, _prev, ctx) {
+      const values = next.map((r) => r.handle ?? r.pending).filter((v) => v != null);
+      if (ctx.multiple) return values;
+      return values[0] ?? null;
+    }
+  };
+}
+function tail(value) {
+  const seg = value.split("/").pop();
+  return seg && seg !== value ? seg : value || void 0;
+}
+
+// src/mappers/rich-image.ts
+var DEFAULT_USAGE_KEYS = ["hotspot", "crop"];
+function richImage(opts) {
+  const handleKey = opts.handleKey ?? "id";
+  const usageKeys = opts.usageKeys ?? DEFAULT_USAGE_KEYS;
+  function readOne(entry) {
+    const usage = opts.focus === "usage" ? pick(
+      entry,
+      usageKeys.filter((k) => entry[k] !== void 0)
+    ) : void 0;
+    return newRef({
+      handle: asString(getPath(entry, handleKey)),
+      raw: entry,
+      name: asString(entry.name ?? entry.filename_download),
+      mime: asString(entry.mime ?? entry.type),
+      size: asNumber(entry.size ?? entry.filesize),
+      width: asNumber(entry.width),
+      height: asNumber(entry.height),
+      ...usage && Object.keys(usage).length > 0 ? { usage } : {}
+    });
+  }
+  return {
+    read(column, ctx) {
+      if (column == null) return [];
+      const list = Array.isArray(column) ? column : [column];
+      return list.filter((e) => e && typeof e === "object").map(readOne);
+    },
+    write(next, _prev, ctx) {
+      const out = next.filter((r) => r.handle != null).map((r) => {
+        const base = isObj(r.raw) ? { ...r.raw } : {};
+        setPath(base, handleKey, r.handle);
+        if (opts.focus === "usage" && r.usage) Object.assign(base, r.usage);
+        return base;
+      });
+      if (ctx.multiple) return out;
+      return out[0] ?? null;
+    }
+  };
+}
+function isObj(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function asString(v) {
+  return typeof v === "string" ? v : void 0;
+}
+function asNumber(v) {
+  return typeof v === "number" && Number.isFinite(v) ? v : void 0;
+}
+function pick(src, keys) {
+  const out = {};
+  for (const k of keys) out[k] = src[k];
+  return out;
+}
+function getPath(src, path) {
+  return path.split(".").reduce((acc, k) => isObj(acc) ? acc[k] : void 0, src);
+}
+function setPath(target, path, value) {
+  const keys = path.split(".");
+  const last = keys.pop();
+  let cursor = target;
+  for (const k of keys) {
+    const nextLevel = cursor[k];
+    cursor[k] = isObj(nextLevel) ? { ...nextLevel } : {};
+    cursor = cursor[k];
+  }
+  cursor[last] = value;
+}
+
+// src/mappers/junction.ts
+function junction(opts) {
+  return {
+    read(column, _ctx) {
+      if (!Array.isArray(column)) return [];
+      return column.filter((row) => row && typeof row === "object").map((row) => newRef({ handle: asString2(row[opts.fileKey]), raw: row }));
+    },
+    write(next, _prev, _ctx) {
+      return next.filter((r) => r.handle != null).map((r, i) => {
+        const base = r.raw && typeof r.raw === "object" ? { ...r.raw } : {};
+        base[opts.fileKey] = r.handle;
+        if (opts.sortKey) base[opts.sortKey] = i + 1;
+        return base;
+      });
+    }
+  };
+}
+function asString2(v) {
+  return typeof v === "string" ? v : void 0;
+}
+
+// src/contract/run-contract.ts
+var single = { resource: "demo", field: "file", multiple: false };
+var many = { resource: "demo", field: "files", multiple: true };
+function runFileStorageContract(opts, runner) {
+  const { mapper } = opts;
+  const it = runner.it;
+  const expect = runner.expect;
+  it("declares a pipeline", () => {
+    expect(["immediate", "fused", "handshake", "resumable"]).toContain(opts.adapter().pipeline);
+  });
+  it("ships a default mapper", () => {
+    const m = opts.adapter().defaultMapper;
+    expect(typeof m.read).toBe("function");
+    expect(typeof m.write).toBe("function");
+  });
+  if (opts.writesColumnPatch) {
+    it("emits an empty patch when nothing changed", () => {
+      const refs = mapper.read(opts.sampleColumn.multiple, many);
+      const out = mapper.write(refs, refs, many);
+      expect(Object.keys(out.keys ?? {}).length).toBe(0);
+    });
+    it("emits only patch keys, never the raw column value", () => {
+      const refs = mapper.read(opts.sampleColumn.multiple, many);
+      const out = mapper.write(refs, refs, many);
+      expect(typeof out.keys).toBe("object");
+    });
+  } else {
+    it("round-trips an untouched single value unchanged", () => {
+      const refs = mapper.read(opts.sampleColumn.single, single);
+      expect(mapper.write(refs, refs, single)).toEqual(opts.sampleColumn.single);
+    });
+    it("round-trips an untouched multiple value unchanged", () => {
+      const refs = mapper.read(opts.sampleColumn.multiple, many);
+      expect(mapper.write(refs, refs, many)).toEqual(opts.sampleColumn.multiple);
+    });
+  }
+  it("reads null as no files", () => {
+    expect(mapper.read(null, single)).toEqual([]);
+  });
+  it("gives every ref a distinct localId", () => {
+    const refs = mapper.read(opts.sampleColumn.multiple, many);
+    expect(new Set(refs.map((r) => r.localId)).size).toBe(refs.length);
+  });
+  if (!opts.skipUpload) {
+    it("reports progress and resolves to a ref carrying a handle", async () => {
+      const adapter = opts.adapter();
+      const seen = [];
+      const ref = await adapter.upload(new File(["hello"], "a.txt", { type: "text/plain" }), {
+        signal: new AbortController().signal,
+        onProgress: (loaded) => seen.push(loaded)
+      });
+      expect(ref.handle).toBeTruthy();
+      expect(seen.length).toBeGreaterThan(0);
+      expect(seen.at(-1)).toBe(5);
+    });
+    it("rejects with an AbortError when the signal is already aborted", async () => {
+      const adapter = opts.adapter();
+      const ac = new AbortController();
+      ac.abort();
+      await expect(
+        adapter.upload(new File(["x"], "x.txt"), {
+          signal: ac.signal,
+          onProgress: () => {
+          }
+        })
+      ).rejects.toThrow(/abort/i);
+    });
+    it("accepts a retry after a failure", async () => {
+      const adapter = opts.adapter();
+      const file = new File(["x"], "x.txt");
+      const aborted = new AbortController();
+      aborted.abort();
+      await expect(
+        adapter.upload(file, { signal: aborted.signal, onProgress: () => {
+        } })
+      ).rejects.toThrow();
+      const second = await adapter.upload(file, {
+        signal: new AbortController().signal,
+        onProgress: () => {
+        }
+      });
+      expect(second.handle).toBeTruthy();
+    });
+  }
+  it("resolves a URL for a ref", async () => {
+    const adapter = opts.adapter();
+    const resolved = await adapter.resolveUrl({ localId: "x", handle: "h" }, opts.resolveCtx ?? {});
+    const url = typeof resolved === "string" ? resolved : resolved.url;
+    expect(url).toMatch(/^https?:\/\//);
+  });
+  it("either returns a permanent string or states a future expiry \u2014 never neither", async () => {
+    const adapter = opts.adapter();
+    const resolved = await adapter.resolveUrl({ localId: "x", handle: "h" }, opts.resolveCtx ?? {});
+    if (typeof resolved === "string") return;
+    expect(typeof resolved.expiresAt).toBe("number");
+    expect(resolved.expiresAt).toBeGreaterThan(Date.now());
+  });
+  it("leaves unreportable metadata absent rather than guessing", async () => {
+    const adapter = opts.adapter();
+    if (!adapter.stat) return;
+    const [out] = await adapter.stat([{ localId: "x", handle: "definitely-not-stored" }]);
+    expect(out?.size).not.toBe(0);
+  });
+}
+
+// src/contract/fake-adapter.ts
+function createFakeAdapter(opts = {}) {
+  const stored = /* @__PURE__ */ new Map();
+  const removed = [];
+  let seq2 = 0;
+  return {
+    stored,
+    removed,
+    pipeline: opts.pipeline ?? "immediate",
+    defaultMapper: scalarHandle(),
+    async upload(file, ctx) {
+      const ticks = opts.progressTicks ?? 2;
+      for (let i = 1; i <= ticks; i += 1) {
+        if (ctx.signal.aborted) throw new DOMException("Aborted", "AbortError");
+        await Promise.resolve();
+        ctx.onProgress(Math.round(file.size * i / ticks), file.size);
+      }
+      if (ctx.signal.aborted) throw new DOMException("Aborted", "AbortError");
+      if (opts.failWith) throw new Error(opts.failWith);
+      seq2 += 1;
+      const handle = `fake-${seq2}-${file.name}`;
+      stored.set(handle, file);
+      return newRef({ handle, name: file.name, mime: file.type || void 0, size: file.size });
+    },
+    resolveUrl(ref, ctx) {
+      const q = ctx.variant?.width ? `?w=${ctx.variant.width}` : "";
+      const url = `https://fake.test/${ref.handle}${q}`;
+      if (opts.signedTtlMs == null) return url;
+      return Promise.resolve({ url, expiresAt: Date.now() + opts.signedTtlMs });
+    },
+    async stat(refs) {
+      return refs.map((r) => {
+        const f = r.handle ? stored.get(r.handle) : void 0;
+        return f ? { ...r, name: f.name, size: f.size, mime: f.type || void 0 } : r;
+      });
+    },
+    async remove(ref) {
+      if (ref.handle) {
+        stored.delete(ref.handle);
+        removed.push(ref.handle);
+      }
+    }
+  };
+}
+
+// src/adapters/inline.ts
+function inlineFileStorage(opts) {
+  return {
+    pipeline: "fused",
+    encoding: opts.encoding,
+    defaultMapper: scalarHandle(),
+    // Nothing was uploaded ahead of the save, so nothing can be orphaned.
+    orphans: "keep",
+    async upload(file, _ctx) {
+      return newRef({
+        pending: file,
+        name: file.name,
+        mime: file.type || void 0,
+        size: file.size
+      });
+    },
+    resolveUrl(ref, ctx) {
+      return opts.resolveUrl(ref, ctx);
+    }
+  };
+}
+
+// src/adapters/nhost.ts
+function nhostFileStorage(opts) {
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const base = opts.baseUrl.replace(/\/+$/, "");
+  async function authHeaders() {
+    const token = await opts.getToken();
+    if (!token) throw new Error("nhostFileStorage: no access token \u2014 the user is not signed in");
+    return { Authorization: `Bearer ${token}` };
+  }
+  return {
+    pipeline: "immediate",
+    defaultMapper: scalarHandle(),
+    orphans: opts.orphans ?? "best-effort",
+    async upload(file, ctx) {
+      if (ctx.signal.aborted) throw new DOMException("Aborted", "AbortError");
+      const headers = await authHeaders();
+      const fd = new FormData();
+      fd.append("file[]", file);
+      if (opts.bucketId) fd.append("bucket-id", opts.bucketId);
+      ctx.onProgress(0, file.size);
+      const res = await fetchImpl(`${base}/v1/files`, {
+        method: "POST",
+        headers,
+        body: fd,
+        signal: ctx.signal
+      });
+      if (!res.ok) {
+        const body = await res.text().catch(() => "");
+        throw new Error(`nhost upload failed: ${res.status} ${body}`.trim());
+      }
+      const json = await res.json();
+      const meta = "processedFiles" in json ? json.processedFiles?.[0] : json;
+      if (!meta?.id) throw new Error("nhost upload returned no file id");
+      ctx.onProgress(file.size, file.size);
+      return newRef({
+        handle: meta.id,
+        name: meta.name ?? file.name,
+        mime: meta.mimeType ?? file.type ?? void 0,
+        size: meta.size ?? file.size
+      });
+    },
+    async resolveUrl(ref, ctx) {
+      const headers = await authHeaders();
+      const params = new URLSearchParams();
+      if (ctx.variant?.width) params.set("w", String(ctx.variant.width));
+      if (ctx.variant?.height) params.set("h", String(ctx.variant.height));
+      const qs = params.toString();
+      const res = await fetchImpl(
+        `${base}/v1/files/${ref.handle}/presignedurl${qs ? `?${qs}` : ""}`,
+        { headers }
+      );
+      if (!res.ok) throw new Error(`nhost presign failed: ${res.status}`);
+      const json = await res.json();
+      if (!json.url) throw new Error("nhost presign returned no url");
+      return {
+        url: json.url,
+        // `expiration` is a lifetime in seconds; the cache wants an instant.
+        expiresAt: Date.now() + (json.expiration ?? 1800) * 1e3
+      };
+    },
+    async stat(refs) {
+      const headers = await authHeaders();
+      return Promise.all(
+        refs.map(async (ref) => {
+          const res = await fetchImpl(`${base}/v1/files/${ref.handle}`, {
+            method: "HEAD",
+            headers
+          });
+          if (!res.ok) return ref;
+          const rawSize = res.headers.get("content-length");
+          const size = rawSize == null ? Number.NaN : Number(rawSize);
+          const mime = res.headers.get("content-type") ?? void 0;
+          return {
+            ...ref,
+            ...Number.isFinite(size) ? { size } : {},
+            ...mime ? { mime } : {}
+          };
+        })
+      );
+    },
+    async remove(ref) {
+      const headers = await authHeaders();
+      const res = await fetchImpl(`${base}/v1/files/${ref.handle}`, {
+        method: "DELETE",
+        headers
+      });
+      if (!res.ok && res.status !== 404) {
+        throw new Error(`nhost delete failed: ${res.status}`);
+      }
+    }
+  };
+}
+
+// src/adapters/supabase.ts
+function pathStamp() {
+  if (typeof crypto !== "undefined" && "randomUUID" in crypto) {
+    return crypto.randomUUID().slice(0, 8);
+  }
+  return Math.random().toString(36).slice(2, 10).padEnd(8, "0");
+}
+function supabaseFileStorage(opts) {
+  const bucket = () => opts.client.storage.from(opts.bucket);
+  const ttl = opts.signedTtlSec ?? 3600;
+  return {
+    pipeline: "immediate",
+    defaultMapper: scalarHandle(),
+    orphans: opts.orphans ?? "best-effort",
+    async upload(file, ctx) {
+      if (ctx.signal.aborted) throw new DOMException("Aborted", "AbortError");
+      const stamp = `${pathStamp()}-${file.name}`;
+      const path = opts.pathPrefix ? `${opts.pathPrefix}/${stamp}` : stamp;
+      ctx.onProgress(0, file.size);
+      const { data, error } = await bucket().upload(path, file, {
+        contentType: file.type || void 0
+      });
+      if (error) throw new Error(`Supabase upload failed: ${error.message}`);
+      if (!data) throw new Error("Supabase upload returned no path");
+      ctx.onProgress(file.size, file.size);
+      return newRef({
+        handle: data.path,
+        name: file.name,
+        mime: file.type || void 0,
+        size: file.size
+      });
+    },
+    async resolveUrl(ref, _ctx) {
+      const path = ref.handle;
+      if (opts.access === "public") {
+        return bucket().getPublicUrl(path).data.publicUrl;
+      }
+      const { data, error } = await bucket().createSignedUrl(path, ttl);
+      if (error) throw new Error(`Supabase sign failed: ${error.message}`);
+      if (!data) throw new Error("Supabase sign returned no url");
+      return { url: data.signedUrl, expiresAt: Date.now() + ttl * 1e3 };
+    },
+    async remove(ref) {
+      const { error } = await bucket().remove([ref.handle]);
+      if (error) throw new Error(`Supabase remove failed: ${error.message}`);
+    }
+  };
+}
+
+// src/adapters/s3.ts
+function s3FileStorage(opts) {
+  return {
+    pipeline: "handshake",
+    defaultMapper: scalarHandle(),
+    orphans: opts.orphans ?? "best-effort",
+    async upload(file, ctx) {
+      if (ctx.signal.aborted) throw new DOMException("Aborted", "AbortError");
+      const target = await opts.sign({ name: file.name, type: file.type, size: file.size });
+      if (ctx.signal.aborted) throw new DOMException("Aborted", "AbortError");
+      const xhr = (opts.xhrImpl ?? (() => new XMLHttpRequest()))();
+      const method = target.method ?? "PUT";
+      await new Promise((resolve, reject) => {
+        const onAbort = () => xhr.abort();
+        ctx.signal.addEventListener("abort", onAbort, { once: true });
+        xhr.upload.addEventListener("progress", (e) => {
+          const ev = e;
+          ctx.onProgress(ev.loaded, ev.total || file.size);
+        });
+        xhr.addEventListener("load", () => {
+          ctx.signal.removeEventListener("abort", onAbort);
+          if (xhr.status >= 200 && xhr.status < 300) {
+            ctx.onProgress(file.size, file.size);
+            resolve();
+          } else reject(new Error(`S3 upload failed: ${xhr.status}`));
+        });
+        xhr.addEventListener("error", () => {
+          ctx.signal.removeEventListener("abort", onAbort);
+          reject(new Error("S3 upload failed: network error"));
+        });
+        xhr.addEventListener("abort", () => {
+          reject(new DOMException("Aborted", "AbortError"));
+        });
+        xhr.open(method, target.url);
+        for (const [k, v] of Object.entries(target.headers ?? {})) {
+          xhr.setRequestHeader(k, v);
+        }
+        if (method === "POST") {
+          const fd = new FormData();
+          for (const [k, v] of Object.entries(target.fields ?? {})) fd.append(k, v);
+          fd.append("file", file);
+          xhr.send(fd);
+        } else {
+          xhr.send(file);
+        }
+      });
+      return newRef({
+        handle: target.key,
+        name: file.name,
+        mime: file.type || void 0,
+        size: file.size
+      });
+    },
+    resolveUrl(ref, ctx) {
+      const key = ref.handle;
+      if (opts.signView) return opts.signView(key, ctx);
+      if (opts.publicBaseUrl) return `${opts.publicBaseUrl.replace(/\/+$/, "")}/${key}`;
+      throw new Error(
+        "s3FileStorage: pass publicBaseUrl for a public bucket or signView for a private one"
+      );
+    },
+    ...opts.remove ? {
+      async remove(ref) {
+        await opts.remove?.(ref.handle);
+      }
+    } : {}
+  };
+}
+
+// src/mappers/column-patch.ts
+var COLUMN_PATCH = /* @__PURE__ */ Symbol.for("buro.fileStorage.columnPatch");
+function columnPatch(keys) {
+  return { [COLUMN_PATCH]: true, keys };
+}
+function isColumnPatch(value) {
+  return typeof value === "object" && value !== null && COLUMN_PATCH in value;
+}
+
+// src/adapters/pocketbase.ts
+function pocketbaseDiff() {
+  return {
+    carriesPending: true,
+    read(column) {
+      if (column == null) return [];
+      const list = Array.isArray(column) ? column : [column];
+      return list.filter((n) => typeof n === "string" && n !== "").map((name) => newRef({ handle: name, raw: name, name }));
+    },
+    write(next, prev, ctx) {
+      const added = next.filter((r) => r.pending).map((r) => r.pending);
+      if (!ctx.multiple) {
+        if (added.length > 0) return columnPatch({ [ctx.field]: added[0] });
+        const kept = next.find((r) => r.handle);
+        if (kept) return columnPatch({});
+        return prev.length > 0 ? columnPatch({ [ctx.field]: "" }) : columnPatch({});
+      }
+      const keptHandles = new Set(next.filter((r) => r.handle).map((r) => r.handle));
+      const removed = prev.map((r) => r.handle).filter((h) => h != null && !keptHandles.has(h));
+      const keys = {};
+      if (added.length > 0) keys[`${ctx.field}+`] = added;
+      if (removed.length > 0) keys[`${ctx.field}-`] = removed;
+      return columnPatch(keys);
+    }
+  };
+}
+function pocketbaseFileStorage(opts) {
+  const base = opts.baseUrl.replace(/\/+$/, "");
+  const ttl = opts.tokenTtlSec ?? 120;
+  return {
+    pipeline: "fused",
+    encoding: "multipart",
+    defaultMapper: pocketbaseDiff(),
+    orphans: "keep",
+    async upload(file, _ctx) {
+      return newRef({
+        pending: file,
+        name: file.name,
+        mime: file.type || void 0,
+        size: file.size
+      });
+    },
+    async resolveUrl(ref, ctx) {
+      const recordId = ctx.record?.id;
+      if (!ctx.resource || !recordId) {
+        throw new Error(
+          "pocketbaseFileStorage: a file URL needs its collection and record id \u2014 the filename alone does not identify a file in PocketBase."
+        );
+      }
+      const params = new URLSearchParams();
+      if (ctx.variant?.width || ctx.variant?.height) {
+        const w = ctx.variant.width ?? 0;
+        const h = ctx.variant.height ?? 0;
+        params.set("thumb", `${w}x${h}f`);
+      }
+      if (ctx.disposition === "attachment") params.set("download", "1");
+      if (opts.protectedFiles) {
+        if (!opts.getFileToken) {
+          throw new Error(
+            "pocketbaseFileStorage: protectedFiles is set but getFileToken was not supplied"
+          );
+        }
+        const token = await opts.getFileToken();
+        params.set("token", token);
+        const qs2 = params.toString();
+        return {
+          url: `${base}/api/files/${ctx.resource}/${recordId}/${ref.handle}${qs2 ? `?${qs2}` : ""}`,
+          expiresAt: Date.now() + ttl * 1e3
+        };
+      }
+      const qs = params.toString();
+      return `${base}/api/files/${ctx.resource}/${recordId}/${ref.handle}${qs ? `?${qs}` : ""}`;
+    }
+  };
+}
+
+// src/wrapper/encode.ts
+function splicePatches(variables) {
+  let touched = false;
+  const out = {};
+  for (const [key, value] of Object.entries(variables)) {
+    if (isColumnPatch(value)) {
+      touched = true;
+      Object.assign(out, value.keys);
+      continue;
+    }
+    out[key] = value;
+  }
+  return touched ? out : variables;
+}
+function containsFile(value, seen = /* @__PURE__ */ new WeakSet()) {
+  if (typeof File !== "undefined" && value instanceof File) return true;
+  if (!value || typeof value !== "object") return false;
+  if (seen.has(value)) return false;
+  seen.add(value);
+  if (Array.isArray(value)) return value.some((v) => containsFile(v, seen));
+  return Object.values(value).some((v) => containsFile(v, seen));
+}
+function containsColumnPatch(value, seen = /* @__PURE__ */ new WeakSet()) {
+  if (!value || typeof value !== "object") return false;
+  try {
+    if (isColumnPatch(value)) return true;
+    if (seen.has(value)) return false;
+    seen.add(value);
+    const descriptors = Object.getOwnPropertyDescriptors(value);
+    return Object.entries(descriptors).some(
+      ([key, descriptor]) => key !== "length" && "value" in descriptor && containsColumnPatch(descriptor.value, seen)
+    );
+  } catch {
+    return false;
+  }
+}
+async function toDataUrl(file) {
+  const buf = await file.arrayBuffer();
+  const bytes = new Uint8Array(buf);
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  const b64 = typeof btoa === "function" ? btoa(binary) : Buffer.from(bytes).toString("base64");
+  return `data:${file.type || "application/octet-stream"};base64,${b64}`;
+}
+async function encodePayload(variables, plan) {
+  const staged = {};
+  for (const [key, value] of Object.entries(variables)) {
+    if (encodingFor(key, plan) !== "base64") {
+      staged[key] = value;
+      continue;
+    }
+    if (value instanceof File) staged[key] = await toDataUrl(value);
+    else if (Array.isArray(value)) {
+      staged[key] = await Promise.all(
+        value.map((v) => v instanceof File ? toDataUrl(v) : Promise.resolve(v))
+      );
+    } else staged[key] = value;
+  }
+  if (!containsFile(staged)) return staged;
+  const encoding = plan.bodyEncoding;
+  const fd = new FormData();
+  if (encoding === "graphql-upload") {
+    const files = [];
+    const map = {};
+    const scrubbed = {};
+    for (const [key, value] of Object.entries(staged)) {
+      if (value instanceof File) {
+        map[String(files.length)] = [`variables.${key}`];
+        files.push(value);
+        scrubbed[key] = null;
+      } else scrubbed[key] = value;
+    }
+    fd.append("operations", JSON.stringify({ variables: scrubbed }));
+    fd.append("map", JSON.stringify(map));
+    files.forEach((f, i) => fd.append(String(i), f));
+    return fd;
+  }
+  for (const [key, value] of Object.entries(staged)) {
+    if (value instanceof File) fd.append(key, value);
+    else if (Array.isArray(value)) {
+      for (const item of value) {
+        fd.append(key, item instanceof File ? item : String(item));
+      }
+    } else if (value == null) fd.append(key, "");
+    else if (typeof value === "object") fd.append(key, JSON.stringify(value));
+    else fd.append(key, String(value));
+  }
+  return fd;
+}
+
+// src/wrapper/with-file-storage.ts
+var FILE_STORAGE_WRAPPED = /* @__PURE__ */ Symbol.for("buro.fileStorage.wrapped");
+var MUTATING = /* @__PURE__ */ new Set(["create", "update", "createMany", "updateMany"]);
+function isProviderMap(value) {
+  if (!value || typeof value !== "object") return false;
+  const entries = Object.values(value);
+  return entries.length > 0 && entries.every((v) => v && typeof v === "object" && !("then" in v));
+}
+function withFileStorage(provider, app) {
+  const registry = app.getService(FILE_STORAGE_SERVICE);
+  if (!registry) {
+    throw new Error(
+      "withFileStorage: no file storage registered \u2014 add fileStoragePlugin({...}) to defineApp"
+    );
+  }
+  if (isProviderMap(provider) && !provider.getList) {
+    const out = {};
+    for (const [name, entry] of Object.entries(provider)) {
+      out[name] = withFileStorage(entry, app);
+    }
+    Object.defineProperty(out, FILE_STORAGE_WRAPPED, { value: true, enumerable: false });
+    return out;
+  }
+  const source = provider;
+  const wrapped = Object.create(
+    Object.getPrototypeOf(source)
+  );
+  for (const key of allKeys(source)) {
+    const value = source[key];
+    if (typeof value !== "function" || !MUTATING.has(key)) {
+      wrapped[key] = value;
+      continue;
+    }
+    wrapped[key] = async (args) => {
+      const variables = args?.variables;
+      if (!variables || typeof variables !== "object" || variables instanceof FormData) {
+        return value(args);
+      }
+      if ((key === "createMany" || key === "updateMany") && (containsFile(variables) || containsColumnPatch(variables))) {
+        throw new Error(
+          `withFileStorage: bulk file mutations are not supported for ${key}; submit one record at a time so FileMapper patches and request-body encoding stay unambiguous.`
+        );
+      }
+      if (Array.isArray(variables)) return value(args);
+      const spliced = splicePatches(variables);
+      if (!containsFile(spliced)) {
+        const passthrough = spliced === variables ? args : { ...args, variables: spliced };
+        return value(passthrough);
+      }
+      const encoded = await encodePayload(spliced, planFor(app, registry, String(args.resource)));
+      return value({ ...args, variables: encoded });
+    };
+  }
+  Object.defineProperty(wrapped, FILE_STORAGE_WRAPPED, { value: true, enumerable: false });
+  return wrapped;
+}
+function allKeys(source) {
+  const keys = new Set(Object.keys(source));
+  const proto = Object.getPrototypeOf(source);
+  if (proto && proto !== Object.prototype) {
+    for (const k of Object.getOwnPropertyNames(proto)) if (k !== "constructor") keys.add(k);
+  }
+  return [...keys];
+}
+function fieldOfKey(key) {
+  return key.endsWith("+") || key.endsWith("-") ? key.slice(0, -1) : key;
+}
+function encodingFor(key, plan) {
+  return plan.knownEncodings.get(fieldOfKey(key)) ?? plan.defaultEncoding;
+}
+function planFor(app, registry, resource) {
+  const knownEncodings = /* @__PURE__ */ new Map();
+  const defaultAdapter = registry.has("default") ? registry.get("default") : void 0;
+  const defaultEncoding = defaultAdapter?.pipeline === "fused" && defaultAdapter.encoding ? defaultAdapter.encoding : "multipart";
+  let bodyEncoding = defaultEncoding === "base64" ? "multipart" : defaultEncoding;
+  const def = app.registry.get(resource);
+  for (const [fieldName, field] of Object.entries(def?.fields ?? {})) {
+    const ui = field.ui;
+    if (ui?.component !== "file") continue;
+    if (!registry.has(ui.fileStorage ?? "default")) continue;
+    const adapter = registry.get(ui.fileStorage);
+    if (adapter.pipeline !== "fused" || !adapter.encoding) continue;
+    knownEncodings.set(fieldName, adapter.encoding);
+    if (adapter.encoding !== "base64") bodyEncoding = adapter.encoding;
+  }
+  return { knownEncodings, defaultEncoding, bodyEncoding };
+}
+
+// src/wrapper/assert-wiring.ts
+var BODY_ENCODINGS = ["multipart", "graphql-upload"];
+function assertFileStorageWiring(app, provider) {
+  const registry = app.getService(FILE_STORAGE_SERVICE);
+  if (!registry) return;
+  if (registry.hasFused()) {
+    const stamped = provider != null && (typeof provider === "object" || typeof provider === "function") && FILE_STORAGE_WRAPPED in provider;
+    if (!stamped) {
+      throw new Error(
+        "A fused file storage is registered, but the data provider is not wrapped. Files ride inside the record mutation for this pipeline, so an unwrapped provider will JSON.stringify them into `{}` and lose them silently. Wrap it once: dataProvider: withFileStorage(myDataProvider, app)"
+      );
+    }
+  }
+  for (const def of app.registry.list()) {
+    const seen = /* @__PURE__ */ new Map();
+    for (const [fieldName, field] of Object.entries(def.fields ?? {})) {
+      const ui = field.ui;
+      if (ui?.component !== "file") continue;
+      if (!registry.has(ui.fileStorage ?? "default")) continue;
+      const adapter = registry.get(ui.fileStorage);
+      if (adapter.pipeline === "fused") {
+        const mapper = ui.mapper ?? adapter.defaultMapper;
+        if (!mapper.carriesPending) {
+          throw new Error(
+            `Resource '${def.name}' field '${fieldName}' pairs a fused file storage with a mapper that cannot carry a pending file forward. A ref on a fused pipeline never has a \`handle\` before the record mutation runs \u2014 only \`pending\` \u2014 and this mapper's \`write\` has no \`carriesPending\` marker, meaning it drops any ref with no handle. That silently discards every file added through this field, with no error. Use a mapper built for this pipeline (scalarHandle, pocketbaseDiff), or give this field one that sets \`carriesPending: true\` via \`f.file({ mapper })\`.`
+          );
+        }
+      }
+      if (adapter.pipeline !== "fused" || !adapter.encoding) continue;
+      if (!BODY_ENCODINGS.includes(adapter.encoding)) continue;
+      const previous = seen.get(adapter.encoding);
+      if (previous == null) seen.set(adapter.encoding, fieldName);
+      if (seen.size > 1) {
+        const entries = [...seen.entries()];
+        const [encA, fieldA] = entries[0];
+        const [encB, fieldB] = entries[1];
+        throw new Error(
+          `Resource '${def.name}' mixes two request-body encodings: field '${fieldA}' wants ${encA} and field '${fieldB}' wants ${encB}. One request has one body \u2014 move one of these fields to a storage using the same encoding, or to base64, which transforms values rather than claiming the body.`
+        );
+      }
+    }
+  }
+}
+
+// src/baseline-carrier.ts
+var FILE_MAPPER_BASELINE_CARRIER = /* @__PURE__ */ Symbol.for("buro.fileMapper.baselineCarrier");
+function inheritFileMapperBaseline(source, target) {
+  let descriptor;
+  try {
+    descriptor = Object.getOwnPropertyDescriptor(source, FILE_MAPPER_BASELINE_CARRIER);
+  } catch {
+    return target;
+  }
+  if (descriptor === void 0 || !("value" in descriptor) || descriptor.value === null || typeof descriptor.value !== "object") {
+    return target;
+  }
+  Object.defineProperty(target, FILE_MAPPER_BASELINE_CARRIER, {
+    value: descriptor.value,
+    enumerable: false,
+    configurable: true,
+    writable: false
+  });
+  return target;
+}
+
+// src/index.ts
+var PACKAGE_NAME = "@burojs/file-storage";
+
+export { COLUMN_PATCH, FILE_STORAGE_SERVICE, FILE_STORAGE_WRAPPED, PACKAGE_NAME, 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.js.map
+//# sourceMappingURL=index.js.map