@fonderie/storage 0.1.0 → 0.1.1

package/dist/index.cjs

@@ -26,6 +26,7 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/providers/db-blob.ts
+var UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 var DbBlobProvider = class {
   constructor(store) {
     this.store = store;
@@ -40,6 +41,7 @@ var DbBlobProvider = class {
     return { ref: rows[0].id };
   }
   async get(ref) {
+    if (!UUID_RE.test(ref)) return null;
     const rows = await this.store.query(
       "SELECT bytes FROM fonderie_storage_blobs WHERE id = $1",
       [ref]
@@ -48,6 +50,7 @@ var DbBlobProvider = class {
     return row ? { kind: "bytes", bytes: row.bytes } : null;
   }
   async delete(ref) {
+    if (!UUID_RE.test(ref)) return;
     await this.store.query("DELETE FROM fonderie_storage_blobs WHERE id = $1", [ref]);
   }
 };
@@ -64,7 +67,12 @@ var LocalFsProvider = class {
     this.dir = (0, import_node_path.resolve)(dir);
   }
   ensureDir() {
-    if (!this.ready) this.ready = (0, import_promises.mkdir)(this.dir, { recursive: true }).then(() => void 0);
+    if (!this.ready) {
+      this.ready = (0, import_promises.mkdir)(this.dir, { recursive: true }).then(() => void 0).catch((err) => {
+        this.ready = null;
+        throw err;
+      });
+    }
     return this.ready;
   }
   // Reject any ref that isn't a bare id, so a ref can never escape `dir`

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts","../src/providers/db-blob.ts","../src/providers/local-fs.ts"],"sourcesContent":["// @fonderie/storage — content-agnostic, provider-abstracted object storage.\n// The low-dependency foundation other bricks build on (media uploads, DB\n// archives). Store any bytes; swap DbBlob → S3/MinIO with one config line.\n//\n// S3Provider is intentionally NOT exported here — import it from\n// '@fonderie/storage/s3' so the AWS SDK is pulled in only when you use it.\nexport type { IStorageProvider, IFetched, IStoredRef } from './providers/types';\nexport { DbBlobProvider } from './providers/db-blob';\nexport { LocalFsProvider } from './providers/local-fs';\n","import type { IStoreAdapter } from '@fonderie/store';\n\nimport type { IFetched, IStorageProvider, IStoredRef } from './types';\n\n/**\n * Zero-infra provider: bytes live in Postgres (`fonderie_storage_blobs`, created\n * by this package's migration). Great for getting started and self-hosting — the\n * whole app is one Node process + one database, and a `pg_dump` captures the\n * objects atomically with the rows that reference them. Swap to `S3Provider`\n * when bandwidth or table size make object storage worth the extra moving part;\n * no consumer code changes, only the provider passed in config.\n */\nexport class DbBlobProvider implements IStorageProvider {\n\treadonly name = 'db-blob';\n\n\tconstructor(private readonly store: IStoreAdapter) {}\n\n\tasync put({ bytes }: { bytes: Uint8Array; contentType: string }): Promise<IStoredRef> {\n\t\tconst rows = await this.store.query<{ id: string }>(\n\t\t\t'INSERT INTO fonderie_storage_blobs (bytes) VALUES ($1) RETURNING id',\n\t\t\t[Buffer.from(bytes)],\n\t\t);\n\t\treturn { ref: rows[0]!.id };\n\t}\n\n\tasync get(ref: string): Promise<IFetched | null> {\n\t\tconst rows = await this.store.query<{ bytes: Buffer }>(\n\t\t\t'SELECT bytes FROM fonderie_storage_blobs WHERE id = $1',\n\t\t\t[ref],\n\t\t);\n\t\tconst row = rows[0];\n\t\treturn row ? { kind: 'bytes', bytes: row.bytes } : null;\n\t}\n\n\tasync delete(ref: string): Promise<void> {\n\t\tawait this.store.query('DELETE FROM fonderie_storage_blobs WHERE id = $1', [ref]);\n\t}\n}\n","import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';\nimport { randomUUID } from 'node:crypto';\nimport { join, resolve } from 'node:path';\n\nimport type { IFetched, IStorageProvider, IStoredRef } from './types';\n\n/**\n * Zero-infra provider: bytes live on the server's filesystem under `dir`. Useful\n * for a single-box deployment that wants objects off the database without\n * standing up object storage. The `ref` is an opaque filename; content type is\n * the consumer's concern, so nothing about the bytes-on-disk needs to encode it.\n *\n * Serves inline through the app like `DbBlobProvider` (no CDN in front), so at\n * real scale prefer `S3Provider` — same interface, one config line.\n */\nexport class LocalFsProvider implements IStorageProvider {\n\treadonly name = 'local-fs';\n\tprivate readonly dir: string;\n\tprivate ready: Promise<void> | null = null;\n\n\tconstructor(dir: string) {\n\t\tthis.dir = resolve(dir);\n\t}\n\n\tprivate ensureDir(): Promise<void> {\n\t\tif (!this.ready) this.ready = mkdir(this.dir, { recursive: true }).then(() => undefined);\n\t\treturn this.ready;\n\t}\n\n\t// Reject any ref that isn't a bare id, so a ref can never escape `dir`\n\t// (path traversal). Ids we mint are UUIDs.\n\tprivate pathFor(ref: string): string {\n\t\tif (!/^[A-Za-z0-9_-]+$/.test(ref)) throw new Error('invalid storage ref');\n\t\treturn join(this.dir, ref);\n\t}\n\n\tasync put({ bytes }: { bytes: Uint8Array; contentType: string }): Promise<IStoredRef> {\n\t\tawait this.ensureDir();\n\t\tconst ref = randomUUID();\n\t\tawait writeFile(this.pathFor(ref), bytes);\n\t\treturn { ref };\n\t}\n\n\tasync get(ref: string): Promise<IFetched | null> {\n\t\ttry {\n\t\t\tconst bytes = await readFile(this.pathFor(ref));\n\t\t\treturn { kind: 'bytes', bytes };\n\t\t} catch {\n\t\t\treturn null; // ENOENT (or an invalid ref) → treated as not found\n\t\t}\n\t}\n\n\tasync delete(ref: string): Promise<void> {\n\t\tawait rm(this.pathFor(ref), { force: true }); // force → no throw when already gone\n\t}\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACYO,IAAM,iBAAN,MAAiD;AAAA,EAGvD,YAA6B,OAAsB;AAAtB;AAAA,EAAuB;AAAA,EAAvB;AAAA,EAFpB,OAAO;AAAA,EAIhB,MAAM,IAAI,EAAE,MAAM,GAAoE;AACrF,UAAM,OAAO,MAAM,KAAK,MAAM;AAAA,MAC7B;AAAA,MACA,CAAC,OAAO,KAAK,KAAK,CAAC;AAAA,IACpB;AACA,WAAO,EAAE,KAAK,KAAK,CAAC,EAAG,GAAG;AAAA,EAC3B;AAAA,EAEA,MAAM,IAAI,KAAuC;AAChD,UAAM,OAAO,MAAM,KAAK,MAAM;AAAA,MAC7B;AAAA,MACA,CAAC,GAAG;AAAA,IACL;AACA,UAAM,MAAM,KAAK,CAAC;AAClB,WAAO,MAAM,EAAE,MAAM,SAAS,OAAO,IAAI,MAAM,IAAI;AAAA,EACpD;AAAA,EAEA,MAAM,OAAO,KAA4B;AACxC,UAAM,KAAK,MAAM,MAAM,oDAAoD,CAAC,GAAG,CAAC;AAAA,EACjF;AACD;;;ACrCA,sBAA+C;AAC/C,yBAA2B;AAC3B,uBAA8B;AAavB,IAAM,kBAAN,MAAkD;AAAA,EAC/C,OAAO;AAAA,EACC;AAAA,EACT,QAA8B;AAAA,EAEtC,YAAY,KAAa;AACxB,SAAK,UAAM,0BAAQ,GAAG;AAAA,EACvB;AAAA,EAEQ,YAA2B;AAClC,QAAI,CAAC,KAAK,MAAO,MAAK,YAAQ,uBAAM,KAAK,KAAK,EAAE,WAAW,KAAK,CAAC,EAAE,KAAK,MAAM,MAAS;AACvF,WAAO,KAAK;AAAA,EACb;AAAA;AAAA;AAAA,EAIQ,QAAQ,KAAqB;AACpC,QAAI,CAAC,mBAAmB,KAAK,GAAG,EAAG,OAAM,IAAI,MAAM,qBAAqB;AACxE,eAAO,uBAAK,KAAK,KAAK,GAAG;AAAA,EAC1B;AAAA,EAEA,MAAM,IAAI,EAAE,MAAM,GAAoE;AACrF,UAAM,KAAK,UAAU;AACrB,UAAM,UAAM,+BAAW;AACvB,cAAM,2BAAU,KAAK,QAAQ,GAAG,GAAG,KAAK;AACxC,WAAO,EAAE,IAAI;AAAA,EACd;AAAA,EAEA,MAAM,IAAI,KAAuC;AAChD,QAAI;AACH,YAAM,QAAQ,UAAM,0BAAS,KAAK,QAAQ,GAAG,CAAC;AAC9C,aAAO,EAAE,MAAM,SAAS,MAAM;AAAA,IAC/B,QAAQ;AACP,aAAO;AAAA,IACR;AAAA,EACD;AAAA,EAEA,MAAM,OAAO,KAA4B;AACxC,cAAM,oBAAG,KAAK,QAAQ,GAAG,GAAG,EAAE,OAAO,KAAK,CAAC;AAAA,EAC5C;AACD;","names":[]}
+{"version":3,"sources":["../src/index.ts","../src/providers/db-blob.ts","../src/providers/local-fs.ts"],"sourcesContent":["// @fonderie/storage — content-agnostic, provider-abstracted object storage.\n// The low-dependency foundation other bricks build on (media uploads, DB\n// archives). Store any bytes; swap DbBlob → S3/MinIO with one config line.\n//\n// S3Provider is intentionally NOT exported here — import it from\n// '@fonderie/storage/s3' so the AWS SDK is pulled in only when you use it.\nexport type { IStorageProvider, IFetched, IStoredRef } from './providers/types';\nexport { DbBlobProvider } from './providers/db-blob';\nexport { LocalFsProvider } from './providers/local-fs';\n","import type { IStoreAdapter } from '@fonderie/store';\n\nimport type { IFetched, IStorageProvider, IStoredRef } from './types';\n\n// Refs we mint are UUIDs. Guard reads/deletes so a foreign or malformed ref\n// resolves to \"not found\" (null / no-op) instead of a Postgres\n// \"invalid input syntax for type uuid\" error — the interface contract is\n// null-on-missing, and a foundation provider shouldn't throw on a bad ref.\nconst UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;\n\n/**\n * Zero-infra provider: bytes live in Postgres (`fonderie_storage_blobs`, created\n * by this package's migration). Great for getting started and self-hosting — the\n * whole app is one Node process + one database, and a `pg_dump` captures the\n * objects atomically with the rows that reference them. Swap to `S3Provider`\n * when bandwidth or table size make object storage worth the extra moving part;\n * no consumer code changes, only the provider passed in config.\n */\nexport class DbBlobProvider implements IStorageProvider {\n\treadonly name = 'db-blob';\n\n\tconstructor(private readonly store: IStoreAdapter) {}\n\n\tasync put({ bytes }: { bytes: Uint8Array; contentType: string }): Promise<IStoredRef> {\n\t\tconst rows = await this.store.query<{ id: string }>(\n\t\t\t'INSERT INTO fonderie_storage_blobs (bytes) VALUES ($1) RETURNING id',\n\t\t\t[Buffer.from(bytes)],\n\t\t);\n\t\treturn { ref: rows[0]!.id };\n\t}\n\n\tasync get(ref: string): Promise<IFetched | null> {\n\t\tif (!UUID_RE.test(ref)) return null;\n\t\tconst rows = await this.store.query<{ bytes: Buffer }>(\n\t\t\t'SELECT bytes FROM fonderie_storage_blobs WHERE id = $1',\n\t\t\t[ref],\n\t\t);\n\t\tconst row = rows[0];\n\t\treturn row ? { kind: 'bytes', bytes: row.bytes } : null;\n\t}\n\n\tasync delete(ref: string): Promise<void> {\n\t\tif (!UUID_RE.test(ref)) return; // nothing to delete for a ref we never minted\n\t\tawait this.store.query('DELETE FROM fonderie_storage_blobs WHERE id = $1', [ref]);\n\t}\n}\n","import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';\nimport { randomUUID } from 'node:crypto';\nimport { join, resolve } from 'node:path';\n\nimport type { IFetched, IStorageProvider, IStoredRef } from './types';\n\n/**\n * Zero-infra provider: bytes live on the server's filesystem under `dir`. Useful\n * for a single-box deployment that wants objects off the database without\n * standing up object storage. The `ref` is an opaque filename; content type is\n * the consumer's concern, so nothing about the bytes-on-disk needs to encode it.\n *\n * Serves inline through the app like `DbBlobProvider` (no CDN in front), so at\n * real scale prefer `S3Provider` — same interface, one config line.\n */\nexport class LocalFsProvider implements IStorageProvider {\n\treadonly name = 'local-fs';\n\tprivate readonly dir: string;\n\tprivate ready: Promise<void> | null = null;\n\n\tconstructor(dir: string) {\n\t\tthis.dir = resolve(dir);\n\t}\n\n\tprivate ensureDir(): Promise<void> {\n\t\t// Clear the cached promise on failure so a transient mkdir error (e.g. a\n\t\t// briefly-unmounted volume) doesn't stick a rejected promise that fails\n\t\t// every later put; the next call retries.\n\t\tif (!this.ready) {\n\t\t\tthis.ready = mkdir(this.dir, { recursive: true })\n\t\t\t\t.then(() => undefined)\n\t\t\t\t.catch((err) => {\n\t\t\t\t\tthis.ready = null;\n\t\t\t\t\tthrow err;\n\t\t\t\t});\n\t\t}\n\t\treturn this.ready;\n\t}\n\n\t// Reject any ref that isn't a bare id, so a ref can never escape `dir`\n\t// (path traversal). Ids we mint are UUIDs.\n\tprivate pathFor(ref: string): string {\n\t\tif (!/^[A-Za-z0-9_-]+$/.test(ref)) throw new Error('invalid storage ref');\n\t\treturn join(this.dir, ref);\n\t}\n\n\tasync put({ bytes }: { bytes: Uint8Array; contentType: string }): Promise<IStoredRef> {\n\t\tawait this.ensureDir();\n\t\tconst ref = randomUUID();\n\t\tawait writeFile(this.pathFor(ref), bytes);\n\t\treturn { ref };\n\t}\n\n\tasync get(ref: string): Promise<IFetched | null> {\n\t\ttry {\n\t\t\tconst bytes = await readFile(this.pathFor(ref));\n\t\t\treturn { kind: 'bytes', bytes };\n\t\t} catch {\n\t\t\treturn null; // ENOENT (or an invalid ref) → treated as not found\n\t\t}\n\t}\n\n\tasync delete(ref: string): Promise<void> {\n\t\tawait rm(this.pathFor(ref), { force: true }); // force → no throw when already gone\n\t}\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACQA,IAAM,UAAU;AAUT,IAAM,iBAAN,MAAiD;AAAA,EAGvD,YAA6B,OAAsB;AAAtB;AAAA,EAAuB;AAAA,EAAvB;AAAA,EAFpB,OAAO;AAAA,EAIhB,MAAM,IAAI,EAAE,MAAM,GAAoE;AACrF,UAAM,OAAO,MAAM,KAAK,MAAM;AAAA,MAC7B;AAAA,MACA,CAAC,OAAO,KAAK,KAAK,CAAC;AAAA,IACpB;AACA,WAAO,EAAE,KAAK,KAAK,CAAC,EAAG,GAAG;AAAA,EAC3B;AAAA,EAEA,MAAM,IAAI,KAAuC;AAChD,QAAI,CAAC,QAAQ,KAAK,GAAG,EAAG,QAAO;AAC/B,UAAM,OAAO,MAAM,KAAK,MAAM;AAAA,MAC7B;AAAA,MACA,CAAC,GAAG;AAAA,IACL;AACA,UAAM,MAAM,KAAK,CAAC;AAClB,WAAO,MAAM,EAAE,MAAM,SAAS,OAAO,IAAI,MAAM,IAAI;AAAA,EACpD;AAAA,EAEA,MAAM,OAAO,KAA4B;AACxC,QAAI,CAAC,QAAQ,KAAK,GAAG,EAAG;AACxB,UAAM,KAAK,MAAM,MAAM,oDAAoD,CAAC,GAAG,CAAC;AAAA,EACjF;AACD;;;AC7CA,sBAA+C;AAC/C,yBAA2B;AAC3B,uBAA8B;AAavB,IAAM,kBAAN,MAAkD;AAAA,EAC/C,OAAO;AAAA,EACC;AAAA,EACT,QAA8B;AAAA,EAEtC,YAAY,KAAa;AACxB,SAAK,UAAM,0BAAQ,GAAG;AAAA,EACvB;AAAA,EAEQ,YAA2B;AAIlC,QAAI,CAAC,KAAK,OAAO;AAChB,WAAK,YAAQ,uBAAM,KAAK,KAAK,EAAE,WAAW,KAAK,CAAC,EAC9C,KAAK,MAAM,MAAS,EACpB,MAAM,CAAC,QAAQ;AACf,aAAK,QAAQ;AACb,cAAM;AAAA,MACP,CAAC;AAAA,IACH;AACA,WAAO,KAAK;AAAA,EACb;AAAA;AAAA;AAAA,EAIQ,QAAQ,KAAqB;AACpC,QAAI,CAAC,mBAAmB,KAAK,GAAG,EAAG,OAAM,IAAI,MAAM,qBAAqB;AACxE,eAAO,uBAAK,KAAK,KAAK,GAAG;AAAA,EAC1B;AAAA,EAEA,MAAM,IAAI,EAAE,MAAM,GAAoE;AACrF,UAAM,KAAK,UAAU;AACrB,UAAM,UAAM,+BAAW;AACvB,cAAM,2BAAU,KAAK,QAAQ,GAAG,GAAG,KAAK;AACxC,WAAO,EAAE,IAAI;AAAA,EACd;AAAA,EAEA,MAAM,IAAI,KAAuC;AAChD,QAAI;AACH,YAAM,QAAQ,UAAM,0BAAS,KAAK,QAAQ,GAAG,CAAC;AAC9C,aAAO,EAAE,MAAM,SAAS,MAAM;AAAA,IAC/B,QAAQ;AACP,aAAO;AAAA,IACR;AAAA,EACD;AAAA,EAEA,MAAM,OAAO,KAA4B;AACxC,cAAM,oBAAG,KAAK,QAAQ,GAAG,GAAG,EAAE,OAAO,KAAK,CAAC;AAAA,EAC5C;AACD;","names":[]}

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { I as IStorageProvider, a as IStoredRef, b as IFetched } from './types-Cb480R4u.cjs';
+import { I as IStorageProvider, a as IStoredRef, b as IFetched } from './types-CR0cffCy.cjs';
 import { IStoreAdapter } from '@fonderie/store';
 
 /**

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { I as IStorageProvider, a as IStoredRef, b as IFetched } from './types-Cb480R4u.js';
+import { I as IStorageProvider, a as IStoredRef, b as IFetched } from './types-CR0cffCy.js';
 import { IStoreAdapter } from '@fonderie/store';
 
 /**

package/dist/index.js

@@ -1,4 +1,5 @@
 // src/providers/db-blob.ts
+var UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 var DbBlobProvider = class {
   constructor(store) {
     this.store = store;
@@ -13,6 +14,7 @@ var DbBlobProvider = class {
     return { ref: rows[0].id };
   }
   async get(ref) {
+    if (!UUID_RE.test(ref)) return null;
     const rows = await this.store.query(
       "SELECT bytes FROM fonderie_storage_blobs WHERE id = $1",
       [ref]
@@ -21,6 +23,7 @@ var DbBlobProvider = class {
     return row ? { kind: "bytes", bytes: row.bytes } : null;
   }
   async delete(ref) {
+    if (!UUID_RE.test(ref)) return;
     await this.store.query("DELETE FROM fonderie_storage_blobs WHERE id = $1", [ref]);
   }
 };
@@ -37,7 +40,12 @@ var LocalFsProvider = class {
     this.dir = resolve(dir);
   }
   ensureDir() {
-    if (!this.ready) this.ready = mkdir(this.dir, { recursive: true }).then(() => void 0);
+    if (!this.ready) {
+      this.ready = mkdir(this.dir, { recursive: true }).then(() => void 0).catch((err) => {
+        this.ready = null;
+        throw err;
+      });
+    }
     return this.ready;
   }
   // Reject any ref that isn't a bare id, so a ref can never escape `dir`

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/providers/db-blob.ts","../src/providers/local-fs.ts"],"sourcesContent":["import type { IStoreAdapter } from '@fonderie/store';\n\nimport type { IFetched, IStorageProvider, IStoredRef } from './types';\n\n/**\n * Zero-infra provider: bytes live in Postgres (`fonderie_storage_blobs`, created\n * by this package's migration). Great for getting started and self-hosting — the\n * whole app is one Node process + one database, and a `pg_dump` captures the\n * objects atomically with the rows that reference them. Swap to `S3Provider`\n * when bandwidth or table size make object storage worth the extra moving part;\n * no consumer code changes, only the provider passed in config.\n */\nexport class DbBlobProvider implements IStorageProvider {\n\treadonly name = 'db-blob';\n\n\tconstructor(private readonly store: IStoreAdapter) {}\n\n\tasync put({ bytes }: { bytes: Uint8Array; contentType: string }): Promise<IStoredRef> {\n\t\tconst rows = await this.store.query<{ id: string }>(\n\t\t\t'INSERT INTO fonderie_storage_blobs (bytes) VALUES ($1) RETURNING id',\n\t\t\t[Buffer.from(bytes)],\n\t\t);\n\t\treturn { ref: rows[0]!.id };\n\t}\n\n\tasync get(ref: string): Promise<IFetched | null> {\n\t\tconst rows = await this.store.query<{ bytes: Buffer }>(\n\t\t\t'SELECT bytes FROM fonderie_storage_blobs WHERE id = $1',\n\t\t\t[ref],\n\t\t);\n\t\tconst row = rows[0];\n\t\treturn row ? { kind: 'bytes', bytes: row.bytes } : null;\n\t}\n\n\tasync delete(ref: string): Promise<void> {\n\t\tawait this.store.query('DELETE FROM fonderie_storage_blobs WHERE id = $1', [ref]);\n\t}\n}\n","import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';\nimport { randomUUID } from 'node:crypto';\nimport { join, resolve } from 'node:path';\n\nimport type { IFetched, IStorageProvider, IStoredRef } from './types';\n\n/**\n * Zero-infra provider: bytes live on the server's filesystem under `dir`. Useful\n * for a single-box deployment that wants objects off the database without\n * standing up object storage. The `ref` is an opaque filename; content type is\n * the consumer's concern, so nothing about the bytes-on-disk needs to encode it.\n *\n * Serves inline through the app like `DbBlobProvider` (no CDN in front), so at\n * real scale prefer `S3Provider` — same interface, one config line.\n */\nexport class LocalFsProvider implements IStorageProvider {\n\treadonly name = 'local-fs';\n\tprivate readonly dir: string;\n\tprivate ready: Promise<void> | null = null;\n\n\tconstructor(dir: string) {\n\t\tthis.dir = resolve(dir);\n\t}\n\n\tprivate ensureDir(): Promise<void> {\n\t\tif (!this.ready) this.ready = mkdir(this.dir, { recursive: true }).then(() => undefined);\n\t\treturn this.ready;\n\t}\n\n\t// Reject any ref that isn't a bare id, so a ref can never escape `dir`\n\t// (path traversal). Ids we mint are UUIDs.\n\tprivate pathFor(ref: string): string {\n\t\tif (!/^[A-Za-z0-9_-]+$/.test(ref)) throw new Error('invalid storage ref');\n\t\treturn join(this.dir, ref);\n\t}\n\n\tasync put({ bytes }: { bytes: Uint8Array; contentType: string }): Promise<IStoredRef> {\n\t\tawait this.ensureDir();\n\t\tconst ref = randomUUID();\n\t\tawait writeFile(this.pathFor(ref), bytes);\n\t\treturn { ref };\n\t}\n\n\tasync get(ref: string): Promise<IFetched | null> {\n\t\ttry {\n\t\t\tconst bytes = await readFile(this.pathFor(ref));\n\t\t\treturn { kind: 'bytes', bytes };\n\t\t} catch {\n\t\t\treturn null; // ENOENT (or an invalid ref) → treated as not found\n\t\t}\n\t}\n\n\tasync delete(ref: string): Promise<void> {\n\t\tawait rm(this.pathFor(ref), { force: true }); // force → no throw when already gone\n\t}\n}\n"],"mappings":";AAYO,IAAM,iBAAN,MAAiD;AAAA,EAGvD,YAA6B,OAAsB;AAAtB;AAAA,EAAuB;AAAA,EAAvB;AAAA,EAFpB,OAAO;AAAA,EAIhB,MAAM,IAAI,EAAE,MAAM,GAAoE;AACrF,UAAM,OAAO,MAAM,KAAK,MAAM;AAAA,MAC7B;AAAA,MACA,CAAC,OAAO,KAAK,KAAK,CAAC;AAAA,IACpB;AACA,WAAO,EAAE,KAAK,KAAK,CAAC,EAAG,GAAG;AAAA,EAC3B;AAAA,EAEA,MAAM,IAAI,KAAuC;AAChD,UAAM,OAAO,MAAM,KAAK,MAAM;AAAA,MAC7B;AAAA,MACA,CAAC,GAAG;AAAA,IACL;AACA,UAAM,MAAM,KAAK,CAAC;AAClB,WAAO,MAAM,EAAE,MAAM,SAAS,OAAO,IAAI,MAAM,IAAI;AAAA,EACpD;AAAA,EAEA,MAAM,OAAO,KAA4B;AACxC,UAAM,KAAK,MAAM,MAAM,oDAAoD,CAAC,GAAG,CAAC;AAAA,EACjF;AACD;;;ACrCA,SAAS,OAAO,UAAU,IAAI,iBAAiB;AAC/C,SAAS,kBAAkB;AAC3B,SAAS,MAAM,eAAe;AAavB,IAAM,kBAAN,MAAkD;AAAA,EAC/C,OAAO;AAAA,EACC;AAAA,EACT,QAA8B;AAAA,EAEtC,YAAY,KAAa;AACxB,SAAK,MAAM,QAAQ,GAAG;AAAA,EACvB;AAAA,EAEQ,YAA2B;AAClC,QAAI,CAAC,KAAK,MAAO,MAAK,QAAQ,MAAM,KAAK,KAAK,EAAE,WAAW,KAAK,CAAC,EAAE,KAAK,MAAM,MAAS;AACvF,WAAO,KAAK;AAAA,EACb;AAAA;AAAA;AAAA,EAIQ,QAAQ,KAAqB;AACpC,QAAI,CAAC,mBAAmB,KAAK,GAAG,EAAG,OAAM,IAAI,MAAM,qBAAqB;AACxE,WAAO,KAAK,KAAK,KAAK,GAAG;AAAA,EAC1B;AAAA,EAEA,MAAM,IAAI,EAAE,MAAM,GAAoE;AACrF,UAAM,KAAK,UAAU;AACrB,UAAM,MAAM,WAAW;AACvB,UAAM,UAAU,KAAK,QAAQ,GAAG,GAAG,KAAK;AACxC,WAAO,EAAE,IAAI;AAAA,EACd;AAAA,EAEA,MAAM,IAAI,KAAuC;AAChD,QAAI;AACH,YAAM,QAAQ,MAAM,SAAS,KAAK,QAAQ,GAAG,CAAC;AAC9C,aAAO,EAAE,MAAM,SAAS,MAAM;AAAA,IAC/B,QAAQ;AACP,aAAO;AAAA,IACR;AAAA,EACD;AAAA,EAEA,MAAM,OAAO,KAA4B;AACxC,UAAM,GAAG,KAAK,QAAQ,GAAG,GAAG,EAAE,OAAO,KAAK,CAAC;AAAA,EAC5C;AACD;","names":[]}
+{"version":3,"sources":["../src/providers/db-blob.ts","../src/providers/local-fs.ts"],"sourcesContent":["import type { IStoreAdapter } from '@fonderie/store';\n\nimport type { IFetched, IStorageProvider, IStoredRef } from './types';\n\n// Refs we mint are UUIDs. Guard reads/deletes so a foreign or malformed ref\n// resolves to \"not found\" (null / no-op) instead of a Postgres\n// \"invalid input syntax for type uuid\" error — the interface contract is\n// null-on-missing, and a foundation provider shouldn't throw on a bad ref.\nconst UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;\n\n/**\n * Zero-infra provider: bytes live in Postgres (`fonderie_storage_blobs`, created\n * by this package's migration). Great for getting started and self-hosting — the\n * whole app is one Node process + one database, and a `pg_dump` captures the\n * objects atomically with the rows that reference them. Swap to `S3Provider`\n * when bandwidth or table size make object storage worth the extra moving part;\n * no consumer code changes, only the provider passed in config.\n */\nexport class DbBlobProvider implements IStorageProvider {\n\treadonly name = 'db-blob';\n\n\tconstructor(private readonly store: IStoreAdapter) {}\n\n\tasync put({ bytes }: { bytes: Uint8Array; contentType: string }): Promise<IStoredRef> {\n\t\tconst rows = await this.store.query<{ id: string }>(\n\t\t\t'INSERT INTO fonderie_storage_blobs (bytes) VALUES ($1) RETURNING id',\n\t\t\t[Buffer.from(bytes)],\n\t\t);\n\t\treturn { ref: rows[0]!.id };\n\t}\n\n\tasync get(ref: string): Promise<IFetched | null> {\n\t\tif (!UUID_RE.test(ref)) return null;\n\t\tconst rows = await this.store.query<{ bytes: Buffer }>(\n\t\t\t'SELECT bytes FROM fonderie_storage_blobs WHERE id = $1',\n\t\t\t[ref],\n\t\t);\n\t\tconst row = rows[0];\n\t\treturn row ? { kind: 'bytes', bytes: row.bytes } : null;\n\t}\n\n\tasync delete(ref: string): Promise<void> {\n\t\tif (!UUID_RE.test(ref)) return; // nothing to delete for a ref we never minted\n\t\tawait this.store.query('DELETE FROM fonderie_storage_blobs WHERE id = $1', [ref]);\n\t}\n}\n","import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';\nimport { randomUUID } from 'node:crypto';\nimport { join, resolve } from 'node:path';\n\nimport type { IFetched, IStorageProvider, IStoredRef } from './types';\n\n/**\n * Zero-infra provider: bytes live on the server's filesystem under `dir`. Useful\n * for a single-box deployment that wants objects off the database without\n * standing up object storage. The `ref` is an opaque filename; content type is\n * the consumer's concern, so nothing about the bytes-on-disk needs to encode it.\n *\n * Serves inline through the app like `DbBlobProvider` (no CDN in front), so at\n * real scale prefer `S3Provider` — same interface, one config line.\n */\nexport class LocalFsProvider implements IStorageProvider {\n\treadonly name = 'local-fs';\n\tprivate readonly dir: string;\n\tprivate ready: Promise<void> | null = null;\n\n\tconstructor(dir: string) {\n\t\tthis.dir = resolve(dir);\n\t}\n\n\tprivate ensureDir(): Promise<void> {\n\t\t// Clear the cached promise on failure so a transient mkdir error (e.g. a\n\t\t// briefly-unmounted volume) doesn't stick a rejected promise that fails\n\t\t// every later put; the next call retries.\n\t\tif (!this.ready) {\n\t\t\tthis.ready = mkdir(this.dir, { recursive: true })\n\t\t\t\t.then(() => undefined)\n\t\t\t\t.catch((err) => {\n\t\t\t\t\tthis.ready = null;\n\t\t\t\t\tthrow err;\n\t\t\t\t});\n\t\t}\n\t\treturn this.ready;\n\t}\n\n\t// Reject any ref that isn't a bare id, so a ref can never escape `dir`\n\t// (path traversal). Ids we mint are UUIDs.\n\tprivate pathFor(ref: string): string {\n\t\tif (!/^[A-Za-z0-9_-]+$/.test(ref)) throw new Error('invalid storage ref');\n\t\treturn join(this.dir, ref);\n\t}\n\n\tasync put({ bytes }: { bytes: Uint8Array; contentType: string }): Promise<IStoredRef> {\n\t\tawait this.ensureDir();\n\t\tconst ref = randomUUID();\n\t\tawait writeFile(this.pathFor(ref), bytes);\n\t\treturn { ref };\n\t}\n\n\tasync get(ref: string): Promise<IFetched | null> {\n\t\ttry {\n\t\t\tconst bytes = await readFile(this.pathFor(ref));\n\t\t\treturn { kind: 'bytes', bytes };\n\t\t} catch {\n\t\t\treturn null; // ENOENT (or an invalid ref) → treated as not found\n\t\t}\n\t}\n\n\tasync delete(ref: string): Promise<void> {\n\t\tawait rm(this.pathFor(ref), { force: true }); // force → no throw when already gone\n\t}\n}\n"],"mappings":";AAQA,IAAM,UAAU;AAUT,IAAM,iBAAN,MAAiD;AAAA,EAGvD,YAA6B,OAAsB;AAAtB;AAAA,EAAuB;AAAA,EAAvB;AAAA,EAFpB,OAAO;AAAA,EAIhB,MAAM,IAAI,EAAE,MAAM,GAAoE;AACrF,UAAM,OAAO,MAAM,KAAK,MAAM;AAAA,MAC7B;AAAA,MACA,CAAC,OAAO,KAAK,KAAK,CAAC;AAAA,IACpB;AACA,WAAO,EAAE,KAAK,KAAK,CAAC,EAAG,GAAG;AAAA,EAC3B;AAAA,EAEA,MAAM,IAAI,KAAuC;AAChD,QAAI,CAAC,QAAQ,KAAK,GAAG,EAAG,QAAO;AAC/B,UAAM,OAAO,MAAM,KAAK,MAAM;AAAA,MAC7B;AAAA,MACA,CAAC,GAAG;AAAA,IACL;AACA,UAAM,MAAM,KAAK,CAAC;AAClB,WAAO,MAAM,EAAE,MAAM,SAAS,OAAO,IAAI,MAAM,IAAI;AAAA,EACpD;AAAA,EAEA,MAAM,OAAO,KAA4B;AACxC,QAAI,CAAC,QAAQ,KAAK,GAAG,EAAG;AACxB,UAAM,KAAK,MAAM,MAAM,oDAAoD,CAAC,GAAG,CAAC;AAAA,EACjF;AACD;;;AC7CA,SAAS,OAAO,UAAU,IAAI,iBAAiB;AAC/C,SAAS,kBAAkB;AAC3B,SAAS,MAAM,eAAe;AAavB,IAAM,kBAAN,MAAkD;AAAA,EAC/C,OAAO;AAAA,EACC;AAAA,EACT,QAA8B;AAAA,EAEtC,YAAY,KAAa;AACxB,SAAK,MAAM,QAAQ,GAAG;AAAA,EACvB;AAAA,EAEQ,YAA2B;AAIlC,QAAI,CAAC,KAAK,OAAO;AAChB,WAAK,QAAQ,MAAM,KAAK,KAAK,EAAE,WAAW,KAAK,CAAC,EAC9C,KAAK,MAAM,MAAS,EACpB,MAAM,CAAC,QAAQ;AACf,aAAK,QAAQ;AACb,cAAM;AAAA,MACP,CAAC;AAAA,IACH;AACA,WAAO,KAAK;AAAA,EACb;AAAA;AAAA;AAAA,EAIQ,QAAQ,KAAqB;AACpC,QAAI,CAAC,mBAAmB,KAAK,GAAG,EAAG,OAAM,IAAI,MAAM,qBAAqB;AACxE,WAAO,KAAK,KAAK,KAAK,GAAG;AAAA,EAC1B;AAAA,EAEA,MAAM,IAAI,EAAE,MAAM,GAAoE;AACrF,UAAM,KAAK,UAAU;AACrB,UAAM,MAAM,WAAW;AACvB,UAAM,UAAU,KAAK,QAAQ,GAAG,GAAG,KAAK;AACxC,WAAO,EAAE,IAAI;AAAA,EACd;AAAA,EAEA,MAAM,IAAI,KAAuC;AAChD,QAAI;AACH,YAAM,QAAQ,MAAM,SAAS,KAAK,QAAQ,GAAG,CAAC;AAC9C,aAAO,EAAE,MAAM,SAAS,MAAM;AAAA,IAC/B,QAAQ;AACP,aAAO;AAAA,IACR;AAAA,EACD;AAAA,EAEA,MAAM,OAAO,KAA4B;AACxC,UAAM,GAAG,KAAK,QAAQ,GAAG,GAAG,EAAE,OAAO,KAAK,CAAC;AAAA,EAC5C;AACD;","names":[]}

package/dist/s3.d.cts

@@ -1,4 +1,4 @@
-import { I as IStorageProvider, a as IStoredRef, b as IFetched } from './types-Cb480R4u.cjs';
+import { I as IStorageProvider, a as IStoredRef, b as IFetched } from './types-CR0cffCy.cjs';
 
 interface IS3ProviderOptions {
     /** Target bucket. Must already exist. */

package/dist/s3.d.ts

@@ -1,4 +1,4 @@
-import { I as IStorageProvider, a as IStoredRef, b as IFetched } from './types-Cb480R4u.js';
+import { I as IStorageProvider, a as IStoredRef, b as IFetched } from './types-CR0cffCy.js';
 
 interface IS3ProviderOptions {
     /** Target bucket. Must already exist. */

package/dist/{types-Cb480R4u.d.cts → types-CR0cffCy.d.cts}

@@ -37,7 +37,16 @@ interface IStorageProvider {
         bytes: Uint8Array;
         contentType: string;
     }): Promise<IStoredRef>;
-    /** Resolve a ref to bytes or a redirect URL, or null if it's gone. */
+    /**
+     * Resolve a ref to bytes or a redirect URL, or null if it's gone.
+     *
+     * NOTE on `null`: DbBlob/LocalFs verify existence and return `null` for a
+     * missing ref. `S3Provider` returns a presigned `redirect` WITHOUT a
+     * round-trip to check existence, so a missing key yields a redirect URL that
+     * 404s when followed rather than `null`. Consumers that must detect "gone"
+     * without following the URL should keep their own metadata (as
+     * `@fonderie/media` does with its asset row) rather than rely on `null`.
+     */
     get(ref: string): Promise<IFetched | null>;
     /** Remove the stored object. Idempotent — deleting a missing ref must not throw. */
     delete(ref: string): Promise<void>;

package/dist/{types-Cb480R4u.d.ts → types-CR0cffCy.d.ts}

@@ -37,7 +37,16 @@ interface IStorageProvider {
         bytes: Uint8Array;
         contentType: string;
     }): Promise<IStoredRef>;
-    /** Resolve a ref to bytes or a redirect URL, or null if it's gone. */
+    /**
+     * Resolve a ref to bytes or a redirect URL, or null if it's gone.
+     *
+     * NOTE on `null`: DbBlob/LocalFs verify existence and return `null` for a
+     * missing ref. `S3Provider` returns a presigned `redirect` WITHOUT a
+     * round-trip to check existence, so a missing key yields a redirect URL that
+     * 404s when followed rather than `null`. Consumers that must detect "gone"
+     * without following the URL should keep their own metadata (as
+     * `@fonderie/media` does with its asset row) rather than rely on `null`.
+     */
     get(ref: string): Promise<IFetched | null>;
     /** Remove the stored object. Idempotent — deleting a missing ref must not throw. */
     delete(ref: string): Promise<void>;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fonderie/storage",
-	"version": "0.1.0",
+	"version": "0.1.1",
 	"description": "Content-agnostic, provider-abstracted object storage — store any bytes on Postgres, disk, or S3-compatible object storage (S3/MinIO/R2) behind one interface. The low-dependency foundation for media, archives, and more.",
 	"keywords": [
 		"fonderiejs",