@vryzel/file-next 0.4.0 → 0.4.2

package/README.md

@@ -1,12 +1,20 @@
 # @vryzel/file-next
 
-S3/R2 filesystem for Next.js: object adapter, metadata index, server actions, write-through.
+S3/R2 filesystem for Next.js. Bytes in your bucket. The folder tree in **your** SQLite or Postgres. Tenant comes from the server, never from the client.
 
 ```bash
 pnpm add @vryzel/file-next
+# optional, depending on the store:
+pnpm add better-sqlite3   # SQLite
+pnpm add pg               # Postgres
 ```
 
+Peer deps `better-sqlite3` and `pg` are optional. Install only the one you use.
+
+## Quick path
+
 ```ts
+// app/lib/file-next.ts
 import {
   asTenantId,
   asUserId,
@@ -29,6 +37,7 @@ const fs = createFileSystem(
   },
   { store },
 );
+
 export const actions = createServerActions({
   store,
   fs,
@@ -40,6 +49,177 @@ export const actions = createServerActions({
 });
 ```
 
-Tenant never comes from the client. Replace `getAuth` with your session.
+```ts
+// app/lib/actions.ts
+"use server";
+import { actions } from "./file-next";
+
+export const listFiles = (input: { parentId: string | null; cursor?: string; limit?: number }) =>
+  actions.listFiles(input);
+```
+
+Replace `getAuth` with Clerk / Auth.js / your session. Import `@vryzel/file-next/server` only from server modules.
+
+## Use cases
+
+### 1. SQLite (one process)
+
+Default for a single Next.js server.
+
+```ts
+import { createSqliteStore } from "@vryzel/file-next";
+const store = createSqliteStore({ path: ".data/metadata.db" });
+```
+
+Schema is created on first call. Path is relative to `process.cwd()`.
+
+### 2. Postgres (multi-instance + RLS)
+
+```ts
+import { createPostgresStore } from "@vryzel/file-next";
+const store = createPostgresStore({
+  connectionString: process.env.DATABASE_URL!,
+});
+```
+
+Install `pg`. Tenant isolation uses `SET LOCAL app.current_tenant` + row-level security.
+
+### 3. In-memory (tests / Storybook)
+
+```ts
+import { createMemoryStore, createMemoryFileSystem } from "@vryzel/file-next";
+
+const store = createMemoryStore();
+const fs = createMemoryFileSystem({ store });
+```
+
+No AWS. Data dies with the process.
+
+### 4. Cloudflare R2
+
+```ts
+const fs = createFileSystem(
+  {
+    provider: "r2",
+    bucket: process.env.FILE_NEXT_BUCKET!,
+    endpoint: process.env.FILE_NEXT_ENDPOINT!, // https://<accountid>.r2.cloudflarestorage.com
+    credentials: {
+      accessKeyId: process.env.FILE_NEXT_ACCESS_KEY_ID!,
+      secretAccessKey: process.env.FILE_NEXT_SECRET_ACCESS_KEY!,
+    },
+  },
+  { store },
+);
+```
+
+R2 is S3-compatible. Set bucket CORS for `PUT`/`GET` from your origin.
+
+### 5. Env singleton
+
+```ts
+import { getFileSystem } from "@vryzel/file-next";
+const fs = getFileSystem(); // memoized for the process
+```
+
+Reads:
+
+| Var | Required |
+|---|---|
+| `FILE_NEXT_PROVIDER` | `s3` or `r2` |
+| `FILE_NEXT_BUCKET` | yes |
+| `FILE_NEXT_REGION` | S3 |
+| `FILE_NEXT_ENDPOINT` | R2 |
+| `FILE_NEXT_ACCESS_KEY_ID` | yes |
+| `FILE_NEXT_SECRET_ACCESS_KEY` | yes |
+| `FILE_NEXT_FORCE_PATH_STYLE` | optional |
+
+Missing config throws `FileSystemError` (not retryable).
+
+### 6. Multi-tenant keys
+
+```ts
+const scoped = fs.forTenant("acme");
+// object keys are prefixed t/acme/{nodeId} unless prefixTenantKeys: false
+```
+
+Every store method also takes `tenantId`. Do not take tenant from the request body.
+
+### 7. Server actions
+
+`createServerActions` returns:
+
+`listFiles`, `searchFiles`, `listTrash`, `createFolder`, `deleteFile`, `moveFile`, `copyFile`, `setMetadata`, `prepareUpload`, `confirmUpload`, `restoreNode`, `createShare`, `resolveShare`, `revokeShare`.
+
+All return `Result<T, FileSystemError>`: `{ ok: true, value }` or `{ ok: false, error }`.
+
+```ts
+const listed = await actions.listFiles({ parentId: null, limit: 50 });
+if (!listed.ok) throw listed.error;
+```
+
+`listFiles` / `listTrash` accept `cursor` + `limit`.
+
+### 8. Route handlers (upload / download)
+
+```ts
+// app/api/upload/route.ts
+import { createUploadRouteHandler } from "@vryzel/file-next/server";
+import { getFileSystem } from "@vryzel/file-next";
+
+export const PUT = createUploadRouteHandler({
+  fs: getFileSystem(),
+  maxBytes: 25 * 1024 * 1024,
+  allowedContentTypes: ["image/*", "application/pdf"],
+});
+```
+
+Many apps skip this and PUT to a signed URL / a thin `writeThroughFile` route (see the test app). Use whichever matches your upload flow.
+
+### 9. Write-through (object first, then the tree)
+
+```ts
+import { createWriteThrough } from "@vryzel/file-next/sync";
+
+const writeThrough = createWriteThrough(fs, store);
+await writeThrough.writeThroughFile({
+  tenantId,
+  parentId: null,
+  name: "photo.png",
+  body,
+  contentType: "image/png",
+  ownerId,
+});
+```
+
+If the metadata insert fails after the object is written, the key lands in `pending_orphans`. `reconcile()` drains them.
+
+### 10. Result + errors
+
+```ts
+import { ok, err, unwrap, type Result } from "@vryzel/file-next";
+import { FileSystemError } from "@vryzel/file-next/errors";
+
+if (!result.ok) {
+  if (result.error.code === "Conflict") { /* duplicate name */ }
+  if (result.error.retryable) { /* backoff */ }
+}
+```
+
+`@vryzel/file-next/errors` is the client-safe entry (no Node builtins).
+
+## Imports
+
+| Entry | Use from |
+|---|---|
+| `@vryzel/file-next` | server or shared types |
+| `@vryzel/file-next/server` | Server Actions / Route Handlers only (`server-only`) |
+| `@vryzel/file-next/sync` | server |
+| `@vryzel/file-next/errors` | client or server |
+
+## Not this package
+
+- React hooks → `@vryzel/file-next-headless`
+- Ready-made explorer → `@vryzel/file-next-ui`
+- CLI → `@vryzel/file-next-cli`
 
-Public on npmjs. See the repository README.
+Bucket CORS and IAM: [provider-setup](https://github.com/Vryzel/file-next/blob/main/docs/provider-setup.md), [security](https://github.com/Vryzel/file-next/blob/main/docs/security.md).

package/dist/{filesystem-D1Jjx3md.d.ts → filesystem-B0bJh8bW.d.ts}

@@ -724,6 +724,17 @@ interface MetadataStore {
      * tombstones the entire subtree in one call.
      */
     deleteNode(input: DeleteNodeInput): Promise<Result<void, FileSystemError>>;
+    /**
+     * Hard-delete a trashed node and its trashed descendants.
+     * Live nodes return NotFound. Returns S3 keys of files removed
+     * so the caller can delete objects.
+     */
+    purgeNode(input: {
+        tenantId: TenantId;
+        id: string;
+    }): Promise<Result<{
+        s3Keys: ReadonlyArray<string>;
+    }, FileSystemError>>;
     /** Update user metadata (merge or replace). */
     updateMetadata(input: UpdateMetadataInput): Promise<Result<FileNode, FileSystemError>>;
     /** Case-insensitive name search within an optional folder scope. */

package/dist/{filesystem-BbZJLy4A.d.cts → filesystem-CewcaWEl.d.cts}

@@ -724,6 +724,17 @@ interface MetadataStore {
      * tombstones the entire subtree in one call.
      */
     deleteNode(input: DeleteNodeInput): Promise<Result<void, FileSystemError>>;
+    /**
+     * Hard-delete a trashed node and its trashed descendants.
+     * Live nodes return NotFound. Returns S3 keys of files removed
+     * so the caller can delete objects.
+     */
+    purgeNode(input: {
+        tenantId: TenantId;
+        id: string;
+    }): Promise<Result<{
+        s3Keys: ReadonlyArray<string>;
+    }, FileSystemError>>;
     /** Update user metadata (merge or replace). */
     updateMetadata(input: UpdateMetadataInput): Promise<Result<FileNode, FileSystemError>>;
     /** Case-insensitive name search within an optional folder scope. */

package/dist/index.cjs

@@ -3976,6 +3976,36 @@ var createMemoryStore = () => {
       }
       return ok(void 0);
     },
+    async purgeNode(input) {
+      const n = nodes.get(input.id);
+      if (!n || n.tenantId !== input.tenantId || n.deletedAt === null) {
+        return err(
+          new FileSystemError({
+            code: "NotFound",
+            message: `Trashed node ${input.id} not found`,
+            retryable: false
+          })
+        );
+      }
+      const prefix = `${n.path}/`;
+      const s3Keys = [];
+      const ids = [];
+      for (const node of nodes.values()) {
+        if (node.tenantId !== input.tenantId || node.deletedAt === null) continue;
+        if (node.id !== n.id && !node.path.startsWith(prefix)) continue;
+        ids.push(node.id);
+        if (node.kind === "file" && node.s3Key) s3Keys.push(node.s3Key);
+      }
+      for (const id of ids) {
+        const node = nodes.get(id);
+        if (node) removeFromChildrenIndex(node);
+        nodes.delete(id);
+      }
+      for (const [token, share] of shares) {
+        if (ids.includes(share.nodeId)) shares.delete(token);
+      }
+      return ok({ s3Keys });
+    },
     async updateMetadata(input) {
       const n = nodes.get(input.id);
       if (!n || n.tenantId !== input.tenantId || n.deletedAt !== null) {
@@ -4206,7 +4236,7 @@ var rowToFileNode = (row) => ({
   updatedAt: new Date(row.updated_at),
   deletedAt: row.deleted_at === null ? null : new Date(row.deleted_at)
 });
-var SCHEMA_VERSION = 3;
+var SCHEMA_VERSION = 4;
 var MIGRATION_SQL = `
 CREATE TABLE IF NOT EXISTS schema_meta (
   key   TEXT PRIMARY KEY,
@@ -4290,7 +4320,8 @@ WHEN new.deleted_at IS NULL BEGIN
   INSERT INTO nodes_fts(rowid, name) VALUES (new.rowid, new.name);
 END;
 
-CREATE TRIGGER IF NOT EXISTS nodes_fts_ad AFTER DELETE ON nodes BEGIN
+CREATE TRIGGER IF NOT EXISTS nodes_fts_ad AFTER DELETE ON nodes
+WHEN old.deleted_at IS NULL BEGIN
   INSERT INTO nodes_fts(nodes_fts, rowid, name) VALUES('delete', old.rowid, old.name);
 END;
 
@@ -4300,8 +4331,39 @@ CREATE TRIGGER IF NOT EXISTS nodes_fts_au AFTER UPDATE ON nodes BEGIN
     SELECT new.rowid, new.name WHERE new.deleted_at IS NULL;
 END;
 `;
+var FTS_REBUILD_SQL = `
+DROP TRIGGER IF EXISTS nodes_fts_ai;
+DROP TRIGGER IF EXISTS nodes_fts_ad;
+DROP TRIGGER IF EXISTS nodes_fts_au;
+DROP TABLE IF EXISTS nodes_fts;
+CREATE VIRTUAL TABLE nodes_fts USING fts5(
+  name,
+  content='nodes',
+  content_rowid='rowid',
+  tokenize='unicode61 remove_diacritics 2'
+);
+CREATE TRIGGER nodes_fts_ai AFTER INSERT ON nodes
+WHEN new.deleted_at IS NULL BEGIN
+  INSERT INTO nodes_fts(rowid, name) VALUES (new.rowid, new.name);
+END;
+CREATE TRIGGER nodes_fts_ad AFTER DELETE ON nodes
+WHEN old.deleted_at IS NULL BEGIN
+  INSERT INTO nodes_fts(nodes_fts, rowid, name) VALUES('delete', old.rowid, old.name);
+END;
+CREATE TRIGGER nodes_fts_au AFTER UPDATE ON nodes BEGIN
+  INSERT INTO nodes_fts(nodes_fts, rowid, name) VALUES('delete', old.rowid, old.name);
+  INSERT INTO nodes_fts(rowid, name)
+    SELECT new.rowid, new.name WHERE new.deleted_at IS NULL;
+END;
+INSERT INTO nodes_fts(rowid, name) SELECT rowid, name FROM nodes WHERE deleted_at IS NULL;
+`;
 var runMigrations = (db) => {
   db.exec(MIGRATION_SQL);
+  const row = db.prepare("SELECT value FROM schema_meta WHERE key = 'version'").get();
+  const version = row ? Number(row.value) : 0;
+  if (!Number.isFinite(version) || version < 4) {
+    db.exec(FTS_REBUILD_SQL);
+  }
   db.prepare(
     "INSERT OR REPLACE INTO schema_meta (key, value) VALUES ('version', ?)"
   ).run(String(SCHEMA_VERSION));
@@ -4346,6 +4408,7 @@ var createSqliteStore = (options) => {
     listChildren: wrap((s, i) => s.listChildren(i)),
     moveNode: wrap((s, i) => s.moveNode(i)),
     deleteNode: wrap((s, i) => s.deleteNode(i)),
+    purgeNode: wrap((s, i) => s.purgeNode(i)),
     updateMetadata: wrap((s, i) => s.updateMetadata(i)),
     search: wrap((s, i) => s.search(i)),
     getPath: wrap((s, i) => s.getPath(i)),
@@ -4685,6 +4748,35 @@ var buildInner = (Database, options) => {
       }
       return ok(void 0);
     },
+    async purgeNode(input) {
+      const node = db.prepare(
+        `SELECT id, path FROM nodes WHERE id = ? AND tenant_id = ? AND deleted_at IS NOT NULL`
+      ).get(input.id, input.tenantId);
+      if (!node) {
+        return err(
+          new FileSystemError({
+            code: "NotFound",
+            message: `Trashed node ${input.id} not found`,
+            retryable: false
+          })
+        );
+      }
+      const like = `${node.path}/%`;
+      const files = db.prepare(
+        `SELECT s3_key FROM nodes
+           WHERE tenant_id = ? AND deleted_at IS NOT NULL AND kind = 'file' AND s3_key != ''
+             AND (id = ? OR path LIKE ?)`
+      ).all(input.tenantId, input.id, like);
+      db.prepare(
+        `DELETE FROM shares WHERE tenant_id = ? AND node_id IN (
+           SELECT id FROM nodes WHERE tenant_id = ? AND deleted_at IS NOT NULL AND (id = ? OR path LIKE ?)
+         )`
+      ).run(input.tenantId, input.tenantId, input.id, like);
+      db.prepare(
+        `DELETE FROM nodes WHERE tenant_id = ? AND deleted_at IS NOT NULL AND (id = ? OR path LIKE ?)`
+      ).run(input.tenantId, input.id, like);
+      return ok({ s3Keys: files.map((row) => row.s3_key) });
+    },
     async updateMetadata(input) {
       const node = stmtGetById.get(input.id, input.tenantId);
       if (!node) return notFound(input.id);
@@ -5065,6 +5157,7 @@ var createPostgresStore = (options) => {
     listChildren: wrap((s, i) => s.listChildren(i)),
     moveNode: wrap((s, i) => s.moveNode(i)),
     deleteNode: wrap((s, i) => s.deleteNode(i)),
+    purgeNode: wrap((s, i) => s.purgeNode(i)),
     updateMetadata: wrap((s, i) => s.updateMetadata(i)),
     search: wrap((s, i) => s.search(i)),
     getPath: wrap((s, i) => s.getPath(i)),
@@ -5405,6 +5498,48 @@ var buildInner2 = (pg, options) => {
       }
       return ok(void 0);
     },
+    async purgeNode(input) {
+      await ensureInitialized();
+      const nodeRes = await q(
+        input.tenantId,
+        `SELECT id, path FROM "${schema}".nodes
+         WHERE id = $1 AND tenant_id = $2 AND deleted_at IS NOT NULL`,
+        [input.id, input.tenantId]
+      );
+      const node = nodeRes.rows[0];
+      if (!node) {
+        return err(
+          new FileSystemError({
+            code: "NotFound",
+            message: `Trashed node ${input.id} not found`,
+            retryable: false
+          })
+        );
+      }
+      const like = `${node.path}/%`;
+      const files = await q(
+        input.tenantId,
+        `SELECT s3_key FROM "${schema}".nodes
+         WHERE tenant_id = $1 AND deleted_at IS NOT NULL AND kind = 'file' AND s3_key <> ''
+           AND (id = $2 OR path LIKE $3)`,
+        [input.tenantId, input.id, like]
+      );
+      await q(
+        input.tenantId,
+        `DELETE FROM "${schema}".shares WHERE tenant_id = $1 AND node_id IN (
+           SELECT id FROM "${schema}".nodes
+           WHERE tenant_id = $1 AND deleted_at IS NOT NULL AND (id = $2 OR path LIKE $3)
+         )`,
+        [input.tenantId, input.id, like]
+      );
+      await q(
+        input.tenantId,
+        `DELETE FROM "${schema}".nodes
+         WHERE tenant_id = $1 AND deleted_at IS NOT NULL AND (id = $2 OR path LIKE $3)`,
+        [input.tenantId, input.id, like]
+      );
+      return ok({ s3Keys: files.rows.map((row) => row.s3_key) });
+    },
     async updateMetadata(input) {
       await ensureInitialized();
       const exists = await q(