@fougere/adapter-file 0.6.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fougere contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,56 @@
+# @fougere/adapter-file
+
+> One JSON per row, a directory per entity
+
+```ts
+// fougere.config.ts
+export default defineFougere({
+  db: { path: '.data/app.db' },
+  sources: {
+    archive: { source: 'file', path: './rows', entities: ['Snapshot'] },
+  },
+});
+```
+
+`Snapshot` now reads and writes under `./rows/snapshot/<key>.json`; everything else stays in
+`db`. The storage a handler receives is unchanged — where rows live is a fact about the app,
+not about the code that uses them.
+
+## What it costs, before you find out
+
+`all()` reads the whole directory, so `list` with a `where` or an `orderBy` filters in
+memory. That is right for a few thousand rows held for their durability and wrong on a hot
+read path — the same trade `@fougere/adapter-duckdb` documents for a page-sized read.
+
+Two processes over one directory have no lock. SQLite has one; a filesystem does not.
+
+A key becomes a filename, so a key that would leave its directory is refused by name.
+
+## What it does not declare
+
+No `transacted`: a directory has no unit of work. So a
+[frame](https://fougere.dev/docs/business/together) spanning this source and another
+compensates rather than transacting, and the boot says so:
+
+```
+RateCard+Ledger|RateMirrorTogether — compensated: rateCard in 'archive', ledger in 'db' — no isolation
+Account+LedgerTogether            — transaction, source 'db'
+```
+
+Two frames in one app, two guarantees, and the handlers are the same either way.
+
+`migrate` is a `mkdir` per entity, which is the whole shape a directory has. Nothing here
+emits a constraint, so a `ref()` across sources costs nothing.
+
+## Writing your own source
+
+This package is 105 lines, half of them filesystem guards. `storageOver` (`@fougere/core`)
+derives the thirteen gestures of the storage port from four, so a new source supplies where
+rows are and nothing else:
+
+```ts
+Sources.register('redis', (conf): Source => ({
+  storageFactory: storageOver((_entity, name) => redisRows(conf.url, name)),
+  name: conf.url,
+}));
+```

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+import { type Source } from '@fougere/core';
+export interface FileSourceOptions {
+    /** The directory the entity directories sit under. */
+    path: string;
+}
+export declare function setupFile(opts: FileSourceOptions): Source;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAmBA,OAAO,EAEgB,KAAK,MAAM,EACjC,MAAM,eAAe,CAAC;AAsDvB,MAAM,WAAW,iBAAiB;IAChC,sDAAsD;IACtD,IAAI,EAAE,MAAM,CAAC;CACd;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,iBAAiB,GAAG,MAAM,CAczD"}

package/dist/index.js

@@ -0,0 +1,95 @@
+/**
+ * Rows as files — one JSON per row, a directory per entity.
+ *
+ * The reason this package is short: `storageOver` derives the thirteen gestures from four,
+ * so a source that keeps rows somewhere else supplies only where. Nothing about pages,
+ * criteria or lifecycle stamps is written twice.
+ *
+ * What it costs, said here rather than discovered: `all()` reads the whole directory, so
+ * `list` with a `where` or an `orderBy` filters in memory. That is the same trade
+ * `@fougere/adapter-duckdb` documents for a page-sized read — fine for a few thousand rows
+ * held for their durability, wrong on a hot read path. And two processes over one directory
+ * have no lock: SQLite has one, a filesystem does not.
+ *
+ * No `transacted` — a directory has no unit of work, so a frame compensates and says so.
+ * `migrate` is a `mkdir` per entity, which is the whole shape a directory has.
+ */
+import { mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { lowerFirst } from '@fougere/schema';
+import { Sources, storageOver, } from '@fougere/core';
+/** A key becomes a filename, so it may not leave the directory it addresses. */
+function fileOf(dir, key) {
+    if (key.includes('/') || key.includes('\\') || key === '.' || key === '..') {
+        throw new Error(`source 'file': '${key}' cannot be a filename — a key becomes one here.`);
+    }
+    return join(dir, `${encodeURIComponent(key)}.json`);
+}
+/** One entity's rows, one file each, under `<root>/<entity>/`. */
+function dirRows(root, name) {
+    const dir = join(root, name);
+    const read = async (file) => {
+        try {
+            return JSON.parse(await readFile(file, 'utf8'));
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return undefined;
+            throw error;
+        }
+    };
+    return {
+        client: dir,
+        get: (key) => read(fileOf(dir, key)),
+        has: async (key) => (await read(fileOf(dir, key))) !== undefined,
+        set: async (key, row) => {
+            await mkdir(dir, { recursive: true });
+            await writeFile(fileOf(dir, key), JSON.stringify(row, null, 2), 'utf8');
+        },
+        delete: async (key) => {
+            const file = fileOf(dir, key);
+            if ((await read(file)) === undefined)
+                return false;
+            await rm(file);
+            return true;
+        },
+        all: async () => {
+            let names;
+            try {
+                names = await readdir(dir);
+            }
+            catch (error) {
+                if (error.code === 'ENOENT')
+                    return [];
+                throw error;
+            }
+            const rows = await Promise.all(names
+                .filter((file) => file.endsWith('.json'))
+                .map((file) => read(join(dir, file))));
+            return rows.filter((row) => row !== undefined);
+        },
+    };
+}
+export function setupFile(opts) {
+    return {
+        storageFactory: storageOver((_entity, name) => dirRows(opts.path, name)),
+        name: opts.path,
+        // A directory IS the shape, so bringing it up to date is making it exist. `elsewhere`
+        // is not read: nothing here emits a constraint, so a cross-source `ref()` costs nothing.
+        migrate: async (view) => {
+            for (const frond of view.fronds) {
+                for (const entry of frond.entities) {
+                    await mkdir(join(opts.path, lowerFirst(entry.name)), { recursive: true });
+                }
+            }
+        },
+    };
+}
+Sources.register('file', (conf) => {
+    const path = conf.path;
+    if (!path) {
+        throw new Error("source 'file': no `path` — a directory is what it is told to open.");
+    }
+    return setupFile({ path });
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@fougere/adapter-file",
+  "version": "0.6.0-alpha.0",
+  "description": "Rows as files — one JSON per row, in a directory per entity.",
+  "keywords": [
+    "fougere",
+    "typescript",
+    "storage",
+    "filesystem",
+    "json"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chok/fougere.git",
+    "directory": "packages/adapter/file"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "@fougere/core": "0.6.0-alpha.0",
+    "@fougere/schema": "0.6.0-alpha.0",
+    "@fougere/adapter-memory": "0.6.0-alpha.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit -p tsconfig.test.json"
+  }
+}

package/src/index.ts

@@ -0,0 +1,105 @@
+/**
+ * Rows as files — one JSON per row, a directory per entity.
+ *
+ * The reason this package is short: `storageOver` derives the thirteen gestures from four,
+ * so a source that keeps rows somewhere else supplies only where. Nothing about pages,
+ * criteria or lifecycle stamps is written twice.
+ *
+ * What it costs, said here rather than discovered: `all()` reads the whole directory, so
+ * `list` with a `where` or an `orderBy` filters in memory. That is the same trade
+ * `@fougere/adapter-duckdb` documents for a page-sized read — fine for a few thousand rows
+ * held for their durability, wrong on a hot read path. And two processes over one directory
+ * have no lock: SQLite has one, a filesystem does not.
+ *
+ * No `transacted` — a directory has no unit of work, so a frame compensates and says so.
+ * `migrate` is a `mkdir` per entity, which is the whole shape a directory has.
+ */
+import { mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { lowerFirst } from '@fougere/schema';
+import {
+  Sources, storageOver,
+  type Row, type Rows, type Source, type SourceConfig, type SourceView,
+} from '@fougere/core';
+
+/** A key becomes a filename, so it may not leave the directory it addresses. */
+function fileOf(dir: string, key: string): string {
+  if (key.includes('/') || key.includes('\\') || key === '.' || key === '..') {
+    throw new Error(`source 'file': '${key}' cannot be a filename — a key becomes one here.`);
+  }
+
+  return join(dir, `${encodeURIComponent(key)}.json`);
+}
+
+/** One entity's rows, one file each, under `<root>/<entity>/`. */
+function dirRows(root: string, name: string): Rows {
+  const dir = join(root, name);
+  const read = async (file: string): Promise<Row | undefined> => {
+    try {
+      return JSON.parse(await readFile(file, 'utf8')) as Row;
+    } catch (error) {
+      if ((error as { code?: string }).code === 'ENOENT') return undefined;
+      throw error;
+    }
+  };
+
+  return {
+    client: dir,
+    get: (key) => read(fileOf(dir, key)),
+    has: async (key) => (await read(fileOf(dir, key))) !== undefined,
+    set: async (key, row) => {
+      await mkdir(dir, { recursive: true });
+      await writeFile(fileOf(dir, key), JSON.stringify(row, null, 2), 'utf8');
+    },
+    delete: async (key) => {
+      const file = fileOf(dir, key);
+      if ((await read(file)) === undefined) return false;
+      await rm(file);
+      return true;
+    },
+    all: async () => {
+      let names: string[];
+      try {
+        names = await readdir(dir);
+      } catch (error) {
+        if ((error as { code?: string }).code === 'ENOENT') return [];
+        throw error;
+      }
+      const rows = await Promise.all(names
+        .filter((file) => file.endsWith('.json'))
+        .map((file) => read(join(dir, file))));
+
+      return rows.filter((row): row is Row => row !== undefined);
+    },
+  };
+}
+
+export interface FileSourceOptions {
+  /** The directory the entity directories sit under. */
+  path: string;
+}
+
+export function setupFile(opts: FileSourceOptions): Source {
+  return {
+    storageFactory: storageOver((_entity, name) => dirRows(opts.path, name)),
+    name: opts.path,
+    // A directory IS the shape, so bringing it up to date is making it exist. `elsewhere`
+    // is not read: nothing here emits a constraint, so a cross-source `ref()` costs nothing.
+    migrate: async (view: SourceView) => {
+      for (const frond of view.fronds) {
+        for (const entry of frond.entities) {
+          await mkdir(join(opts.path, lowerFirst(entry.name)), { recursive: true });
+        }
+      }
+    },
+  };
+}
+
+Sources.register('file', (conf: SourceConfig): Source => {
+  const path = conf.path as string | undefined;
+  if (!path) {
+    throw new Error("source 'file': no `path` — a directory is what it is told to open.");
+  }
+
+  return setupFile({ path });
+});