@relations-dil/relations 0.1.0 → 0.2.0

package/README.md

@@ -780,8 +780,25 @@ Instance: `filter()`, `sort()`, `limit()`, `set()`, `add()`, `queue()`, `export(
 
 ### Sources
 
-`Source` (subclass this), `MockSource` (in-memory, complete), `register()`, `source()`,
-`unregister()`, `clear()`, `SOURCES`.
+`Source` (subclass this), `MockSource` (in-memory, complete), `LocalSource` (the same, kept in the
+browser's `localStorage`), `register()`, `source()`, `unregister()`, `clear()`, `SOURCES`.
+
+#### LocalSource
+
+For pages that need to remember things with no server: it behaves like any other source, but the
+data survives a reload.
+
+```ts
+import { LocalSource } from '@relations-dil/relations/local'
+
+new LocalSource('example', { key: 'my-app' })
+```
+
+It loads once when it's made and saves after every write that succeeds, as plain JSON under `key`
+(default `relations:<name>`). Pass `storage` to use something other than `localStorage`. Two tabs
+open on the same key don't see each other's changes; whichever saves last wins, and `reset()`
+forgets everything. If what's in storage isn't valid JSON it refuses to start, rather than
+overwrite it.
 
 ### Migrations and data
 

package/dist/index.d.ts

@@ -42,6 +42,7 @@ export { Source, lookup, type Query } from './source.js';
 export { Titles } from './titles.js';
 export { Migrations, pretty, type Renamer } from './migrations.js';
 export { MockQuery, MockSource } from './mock.js';
+export { LocalSource, type StorageLike } from './local.js';
 export { fields, type Listed, type Typed, type TypedClass, type ValueOfKind, type ValueOfSpec, type Values } from './typed.js';
 export { definitionsOf, modelFrom, modelsFrom, type Built, type Definition, type RelationDefinition } from './dynamic.js';
 export { SOURCES, clear, register, source, unregister, type Registered } from './registry.js';

package/dist/index.js

@@ -42,6 +42,7 @@ export { Source, lookup } from './source.js';
 export { Titles } from './titles.js';
 export { Migrations, pretty } from './migrations.js';
 export { MockQuery, MockSource } from './mock.js';
+export { LocalSource } from './local.js';
 export { fields } from './typed.js';
 export { definitionsOf, modelFrom, modelsFrom } from './dynamic.js';
 export { SOURCES, clear, register, source, unregister } from './registry.js';

package/dist/local.d.ts

@@ -0,0 +1,42 @@
+/**
+ * A source that keeps everything in the browser's localStorage.
+ *
+ * Same behaviour as every other source - unique indexes, auto ids, relations, titles - but the
+ * data survives a page reload, with no server and nothing to install. Reach for it for apps that
+ * are a single file you open from disk, or any page that just needs to remember things.
+ *
+ * ```ts
+ * import { LocalSource } from '@relations-dil/relations/local'
+ *
+ * new LocalSource('example', { key: 'my-app' })
+ * ```
+ *
+ * It loads once, when it's made, and saves after every write that succeeds. Two tabs open on the
+ * same key don't see each other's changes: whichever saves last wins.
+ */
+import { MockSource } from './mock.js';
+import type { Model } from './model.js';
+/** The slice of the Web Storage API that's used, so tests (and other stores) can stand in. */
+export interface StorageLike {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+/** A source whose data lives in localStorage. */
+export declare class LocalSource extends MockSource {
+    /** The localStorage key everything is kept under. */
+    key: string;
+    /** Where it's kept. Defaults to the page's localStorage. */
+    storage: StorageLike;
+    constructor(name: string, options?: globalThis.Record<string, any>);
+    /** Read what was saved last time, if anything. */
+    restore(): void;
+    /** Write everything out. Maps become lists of [id, value] pairs. */
+    save(): void;
+    /** Forget everything, here and in storage. The models stay registered. */
+    reset(): void;
+    create(model: Model): Promise<Model>;
+    update(model: Model): Promise<number>;
+    delete(model: Model): Promise<number>;
+}
+//# sourceMappingURL=local.d.ts.map

package/dist/local.js

@@ -0,0 +1,89 @@
+/**
+ * A source that keeps everything in the browser's localStorage.
+ *
+ * Same behaviour as every other source - unique indexes, auto ids, relations, titles - but the
+ * data survives a page reload, with no server and nothing to install. Reach for it for apps that
+ * are a single file you open from disk, or any page that just needs to remember things.
+ *
+ * ```ts
+ * import { LocalSource } from '@relations-dil/relations/local'
+ *
+ * new LocalSource('example', { key: 'my-app' })
+ * ```
+ *
+ * It loads once, when it's made, and saves after every write that succeeds. Two tabs open on the
+ * same key don't see each other's changes: whichever saves last wins.
+ */
+import { MockSource } from './mock.js';
+/** A source whose data lives in localStorage. */
+export class LocalSource extends MockSource {
+    constructor(name, options = {}) {
+        super(name, options);
+        const storage = options.storage ?? globalThis.localStorage;
+        if (storage === undefined) {
+            throw new Error(`${name}: no localStorage here - pass options.storage`);
+        }
+        this.key = options.key ?? `relations:${name}`;
+        this.storage = storage;
+        this.restore();
+    }
+    /** Read what was saved last time, if anything. */
+    restore() {
+        const saved = this.storage.getItem(this.key);
+        if (saved === null) {
+            return;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(saved);
+        }
+        catch {
+            // Carrying on would overwrite whatever's there at the next save.
+            throw new Error(`${this.name}: ${this.key} in storage isn't valid JSON`);
+        }
+        this.ids = parsed.ids;
+        this.data = Object.fromEntries(Object.entries(parsed.data).map(([name, rows]) => [name, new Map(rows)]));
+        this.unique = Object.fromEntries(Object.entries(parsed.unique).map(([name, indexes]) => [
+            name,
+            Object.fromEntries(Object.entries(indexes).map(([index, rows]) => [index, new Map(rows)]))
+        ]));
+    }
+    /** Write everything out. Maps become lists of [id, value] pairs. */
+    save() {
+        this.storage.setItem(this.key, JSON.stringify({
+            ids: this.ids,
+            data: Object.fromEntries(Object.entries(this.data).map(([name, records]) => [name, [...records]])),
+            unique: Object.fromEntries(Object.entries(this.unique).map(([name, indexes]) => [
+                name,
+                Object.fromEntries(Object.entries(indexes).map(([index, values]) => [index, [...values]]))
+            ]))
+        }));
+    }
+    /** Forget everything, here and in storage. The models stay registered. */
+    reset() {
+        this.storage.removeItem(this.key);
+        this.ids = Object.fromEntries(Object.keys(this.ids).map((name) => [name, 0]));
+        this.data = Object.fromEntries(Object.keys(this.data).map((name) => [name, new Map()]));
+        this.unique = Object.fromEntries(Object.entries(this.unique).map(([name, indexes]) => [
+            name,
+            Object.fromEntries(Object.keys(indexes).map((index) => [index, new Map()]))
+        ]));
+    }
+    async create(model) {
+        const created = await super.create(model);
+        this.save();
+        return created;
+    }
+    async update(model) {
+        const updated = await super.update(model);
+        this.save();
+        return updated;
+    }
+    async delete(model) {
+        const deleted = await super.delete(model);
+        this.save();
+        return deleted;
+    }
+}
+LocalSource.KIND = 'local';
+//# sourceMappingURL=local.js.map

package/dist/migrations.js

@@ -5,11 +5,9 @@
  * DDL for a database, nothing at all for an API - so the same migration history drives
  * every backend a set of models is used with.
  */
-import { mkdir, readdir, readFile, rename as renameFile, writeFile } from 'node:fs/promises';
-import { join } from 'node:path';
 import { MigrationsError } from './errors.js';
 import { source as registered } from './registry.js';
-import { equal } from './util.js';
+import { equal, joinPath } from './util.js';
 import { MigrationsRef } from './model.js';
 const noRenames = () => ({});
 /** Diffs model definitions and drives a source through the resulting changes. */
@@ -24,8 +22,9 @@ export class Migrations {
     }
     /** The definition as of the last generate, or an empty one. */
     async current() {
+        const { readFile } = await import('node:fs/promises');
         try {
-            return JSON.parse(await readFile(join(this.directory, 'definition.json'), 'utf8'));
+            return JSON.parse(await readFile(joinPath(this.directory, 'definition.json'), 'utf8'));
         }
         catch (error) {
             if (error.code === 'ENOENT') {
@@ -191,6 +190,7 @@ export class Migrations {
      * Resolves to whether anything was written.
      */
     async generate(models, stamp) {
+        const { mkdir, rename: renameFile, writeFile } = await import('node:fs/promises');
         await mkdir(this.directory, { recursive: true });
         const current = await this.current();
         const define = Migrations.define(models);
@@ -200,10 +200,10 @@ export class Migrations {
             }
             const migration = Migrations.models(current, define, this.renamer);
             const at = stamp ?? stamped();
-            await renameFile(join(this.directory, 'definition.json'), join(this.directory, `definition-${at}.json`));
-            await writeFile(join(this.directory, `migration-${at}.json`), pretty(migration));
+            await renameFile(joinPath(this.directory, 'definition.json'), joinPath(this.directory, `definition-${at}.json`));
+            await writeFile(joinPath(this.directory, `migration-${at}.json`), pretty(migration));
         }
-        await writeFile(join(this.directory, 'definition.json'), pretty(define));
+        await writeFile(joinPath(this.directory, 'definition.json'), pretty(define));
         return true;
     }
     /** Where a source's converted files live. */
@@ -212,7 +212,7 @@ export class Migrations {
         if (source === undefined) {
             throw new MigrationsError(`no source registered as '${name}'`);
         }
-        return join(this.directory, source.name, String(source.KIND));
+        return joinPath(this.directory, source.name, String(source.KIND));
     }
     /** Convert every definition and migration into a source's own form. */
     async convert(name) {
@@ -220,6 +220,7 @@ export class Migrations {
         if (source === undefined) {
             throw new MigrationsError(`no source registered as '${name}'`);
         }
+        const { mkdir, readdir } = await import('node:fs/promises');
         const path = this.sourcePath(name);
         await mkdir(path, { recursive: true });
         for (const file of (await readdir(this.directory)).sort()) {
@@ -227,10 +228,10 @@ export class Migrations {
                 continue;
             }
             if (file.startsWith('definition')) {
-                await source.definition(join(this.directory, file), path);
+                await source.definition(joinPath(this.directory, file), path);
             }
             else if (file.startsWith('migration')) {
-                await source.migration(join(this.directory, file), path);
+                await source.migration(joinPath(this.directory, file), path);
             }
         }
     }
@@ -248,7 +249,7 @@ export class Migrations {
         if (source === undefined) {
             throw new MigrationsError(`no source registered as '${name}'`);
         }
-        return source.load(join(this.sourcePath(name), fileName));
+        return source.load(joinPath(this.sourcePath(name), fileName));
     }
     /** Bring a source up to date. Resolves to whether anything was applied. */
     async apply(name) {

package/dist/mock.js

@@ -10,13 +10,11 @@
  * new MockSource('example')
  * ```
  */
-import { readdir, readFile } from 'node:fs/promises';
-import { join } from 'node:path';
 import * as overscore from './overscore.js';
 import { ModelError, UniqueError } from './errors.js';
 import { Source } from './source.js';
 import { Titles } from './titles.js';
-import { clone, stable } from './util.js';
+import { clone, joinPath, stable } from './util.js';
 import { construct } from './model.js';
 /** A stand-in for a real source's query object. */
 export class MockQuery {
@@ -379,6 +377,7 @@ export class MockSource extends Source {
     }
     // ------------------------------------------------------------------ files
     async definition(filePath, sourcePath) {
+        const { readFile } = await import('node:fs/promises');
         const definitions = [];
         const definition = JSON.parse(await readFile(filePath, 'utf8'));
         for (const name of Object.keys(definition).sort()) {
@@ -391,6 +390,7 @@ export class MockSource extends Source {
         }
     }
     async migration(filePath, sourcePath) {
+        const { readFile } = await import('node:fs/promises');
         const migrations = [];
         const migration = JSON.parse(await readFile(filePath, 'utf8'));
         for (const add of Object.keys(migration.add ?? {}).sort()) {
@@ -456,9 +456,11 @@ export class MockSource extends Source {
         }
     }
     async load(loadPath) {
+        const { readFile } = await import('node:fs/promises');
         await this.execute(JSON.parse(await readFile(loadPath, 'utf8')));
     }
     async list(sourcePath) {
+        const { readdir } = await import('node:fs/promises');
         const migrations = {};
         for (const fileName of await readdir(sourcePath)) {
             if (!fileName.endsWith('.json') || !fileName.includes('-')) {
@@ -474,19 +476,20 @@ export class MockSource extends Source {
         return migrations;
     }
     async migrate(sourcePath) {
+        const { readdir } = await import('node:fs/promises');
         let migrated = false;
         const paths = (await readdir(sourcePath))
             .filter((file) => file.startsWith('migration-') && file.endsWith('.json'))
             .sort();
         if (this.migrations === null) {
             this.migrations = [];
-            await this.load(join(sourcePath, 'definition.json'));
+            await this.load(joinPath(sourcePath, 'definition.json'));
             migrated = true;
         }
         else {
             for (const path of paths) {
                 if (!this.migrations.includes(stampOf(path))) {
-                    await this.load(join(sourcePath, path));
+                    await this.load(joinPath(sourcePath, path));
                     migrated = true;
                 }
             }
@@ -506,6 +509,6 @@ function stampOf(path) {
 async function write(sourcePath, filePath, contents) {
     const { writeFile } = await import('node:fs/promises');
     const fileName = filePath.split('/').pop().split('.')[0];
-    await writeFile(join(sourcePath, `${fileName}.json`), `${JSON.stringify(contents)}\n`);
+    await writeFile(joinPath(sourcePath, `${fileName}.json`), `${JSON.stringify(contents)}\n`);
 }
 //# sourceMappingURL=mock.js.map

package/dist/util.d.ts

@@ -13,4 +13,6 @@ export declare function sorted<T>(values: Iterable<T>): T[];
 export declare function compare(first: any, second: any): number;
 /** Turn CamelCase into under_scored. */
 export declare function underscore(name: string): string;
+/** Join path pieces with `/`, collapsing repeats. All the file paths here need, without `node:path`. */
+export declare function joinPath(...parts: string[]): string;
 //# sourceMappingURL=util.d.ts.map

package/dist/util.js

@@ -114,4 +114,8 @@ export function underscore(name) {
     }
     return parts.join('');
 }
+/** Join path pieces with `/`, collapsing repeats. All the file paths here need, without `node:path`. */
+export function joinPath(...parts) {
+    return parts.join('/').replace(/\/{2,}/g, '/');
+}
 //# sourceMappingURL=util.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@relations-dil/relations",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "A simple, flexible DIL (data interface layer). Define models once, independent of backend; set the source at runtime.",
   "license": "MIT",
   "repository": {
@@ -31,6 +31,10 @@
       "types": "./dist/mock.d.ts",
       "default": "./dist/mock.js"
     },
+    "./local": {
+      "types": "./dist/local.d.ts",
+      "default": "./dist/local.js"
+    },
     "./overscore": {
       "types": "./dist/overscore.d.ts",
       "default": "./dist/overscore.js"
@@ -60,6 +64,7 @@
     "@eslint/js": "^9.39.5",
     "@types/node": "^22.0.0",
     "@unum-pillars/uikit": "^0.1.0",
+    "esbuild": "^0.25.12",
     "eslint": "^9.39.5",
     "tsx": "^4.23.15",
     "typescript": "^5.6.0",