@relations-dil/relations 0.1.0 → 0.2.1

package/README.md

@@ -780,8 +780,65 @@ 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`), `RestSource` (a relations-restx API as the backend), `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.
+
+#### RestSource
+
+For models whose data lives behind a [relations-restx](https://github.com/relations-dil/python-relations-restx)
+API: swap `MockSource` or `LocalSource` for it at runtime and the same models read and write the
+remote service. It's a port of python-relations-rest, and it runs in the browser or in Node.
+
+```ts
+import { RestSource } from '@relations-dil/relations/rest'
+
+new RestSource('example', { url: 'https://api.example.com' })
+
+const unit = await Unit.one({ name: 'yep' }).retrieve()   // POST https://api.example.com/unit
+```
+
+Options:
+
+- `url` (required): where the API lives. `''` is fine for the same origin.
+- `fetch`: anything shaped like `fetch`. Defaults to `globalThis.fetch`, so pass one in on older
+  Node or to stand in for the network in tests.
+- `headers`: sent on every request, e.g. `{ Authorization: 'Bearer ...' }`. Requests have a JSON
+  body and `Content-Type: application/json`; a header of your own wins.
+- `credentials`: passed through to fetch, e.g. `'include'` to send cookies cross-origin.
+- `request`: anything else to hand fetch on every request, like `mode` or `cache`.
+
+A model's `SINGULAR`, `PLURAL` and `ENDPOINT` (defaulting to its name, the name plus `s`, and its
+name) say how it's addressed, just as in the Python client. The endpoint is `/<ENDPOINT>`, and by
+id `/<ENDPOINT>/<id>`.
+
+Reads are sent as `POST /<endpoint>` with a `{"filter": ...}` body, not GET. Browsers can't send a
+body with a GET, and relations-restx treats a POST that carries a `filter` exactly like a GET, so
+`filter`, `sort`, `limit` and `count` all work. Creates are `POST {plural: [...]}`, updates by id
+are `PATCH /<endpoint>/<id>` with `{singular: {...}}`, mass updates are `PATCH /<endpoint>` with
+`{filter, plural: {...}}`, and deletes are `DELETE /<endpoint>` with `{filter}`.
+
+A response of 400 or more throws a `ModelError` carrying the API's `message` (or `API Error`). An
+`overflow` in a response is carried onto the model. Sets go over as sorted lists. Like the Python
+client, it never asks the API for more than the model's `limit()`, but restx always applies one
+itself (the server model's `CHUNK`, 100 unless set), so a retrieve with no `limit()` returns at most
+that many and sets `overflow` when it got that many.
 
 ### Migrations and data
 

package/dist/index.d.ts

@@ -42,6 +42,8 @@ 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 { RestSource, type FetchInit, type FetchLike, type FetchResponse } from './rest.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,8 @@ 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 { RestSource } from './rest.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/rest.d.ts

@@ -0,0 +1,91 @@
+/**
+ * A source whose backend is a relations-restx API.
+ *
+ * The models stay exactly as they were; only the source they name changes. Swap `MockSource`
+ * or `LocalSource` for this one and the same code reads and writes a remote service.
+ *
+ * ```ts
+ * import { RestSource } from '@relations-dil/relations/rest'
+ *
+ * new RestSource('example', { url: 'https://api.example.com' })
+ * ```
+ *
+ * Browsers can't send a body with a GET, so reads are sent as `POST /<endpoint>` with a
+ * `{"filter": ...}` body, which relations-restx treats exactly like a GET.
+ */
+import { Source } from './source.js';
+import { Titles } from './titles.js';
+import { type Model, type ModelIdentity } from './model.js';
+import type { Field } from './field.js';
+/** The part of a fetch response that's used, so anything fetch-shaped can stand in. */
+export interface FetchResponse {
+    status: number;
+    json(): Promise<any>;
+}
+/** The part of fetch's init that's used. */
+export interface FetchInit {
+    method: string;
+    headers: globalThis.Record<string, string>;
+    body?: string;
+    credentials?: string;
+    [option: string]: any;
+}
+/** Anything shaped like `fetch`. */
+export type FetchLike = (url: string, init: FetchInit) => Promise<FetchResponse>;
+type Values = globalThis.Record<string, any>;
+/** A source that uses a relations-restx API as its backend. */
+export declare class RestSource extends Source {
+    /** Where the API lives, without a trailing slash. */
+    url: string;
+    /** The fetch every request goes through. */
+    fetch: FetchLike;
+    /** Headers sent with every request. */
+    headers: globalThis.Record<string, string>;
+    /** Passed to fetch as `credentials`, e.g. `'include'` to send cookies. */
+    credentials: string | undefined;
+    /** Anything else to hand fetch on every request, like `mode` or `cache`. */
+    request: globalThis.Record<string, any>;
+    constructor(name: string, options?: globalThis.Record<string, any>);
+    /** Send a request, always with a JSON body, and hand back the response. */
+    send(method: string, path: string, body: any): Promise<FetchResponse>;
+    /** Checks a response and returns the result. */
+    result(model: Model, key: string, response: FetchResponse): Promise<any>;
+    /** Init the model. */
+    init(model: ModelIdentity): void;
+    /** Updates values with the field's that changed. */
+    createField(field: Field, values: Values): void;
+    /** Executes the create. */
+    create(model: Model): Promise<Model>;
+    /** Adds criteria to the filter. */
+    retrieveField(field: Field, criteria: Values): void;
+    /**
+     * Adds sibling-attribute filters (model._ties, e.g. bro__name: 'Tom') to the filter so the
+     * remote API resolves them through many(); the tie field lives on the model, not the record.
+     */
+    static filterTies(model: Model, criteria: Values): void;
+    /** Everything that narrows the model down, as the API wants it. */
+    filter(model: Model): Promise<Values>;
+    /** Executes the count. */
+    count(model: Model): Promise<number>;
+    /** Executes the retrieve. */
+    retrieve(model: Model, verify?: boolean): Promise<Model | null>;
+    /**
+     * Loads the tie ids the API already resolved onto the model.
+     *
+     * Other sources query the tie table; the API has no tie endpoint but returns the
+     * resolved ids inline, so they're read straight off the response.
+     */
+    retrieveTies(model: Model, read: Values): void;
+    /** Creates the titles structure. */
+    titles(model: Model): Promise<Titles>;
+    /** Updates values with the field's that changed. */
+    updateField(field: Field, values: Values): void;
+    /** Mass values with the field's that changed. */
+    fieldMass(field: Field, values: Values): void;
+    /** Executes the update. */
+    update(model: Model): Promise<number>;
+    /** Executes the delete. */
+    delete(model: Model): Promise<number>;
+}
+export {};
+//# sourceMappingURL=rest.d.ts.map

package/dist/rest.js

@@ -0,0 +1,306 @@
+/**
+ * A source whose backend is a relations-restx API.
+ *
+ * The models stay exactly as they were; only the source they name changes. Swap `MockSource`
+ * or `LocalSource` for this one and the same code reads and writes a remote service.
+ *
+ * ```ts
+ * import { RestSource } from '@relations-dil/relations/rest'
+ *
+ * new RestSource('example', { url: 'https://api.example.com' })
+ * ```
+ *
+ * Browsers can't send a body with a GET, so reads are sent as `POST /<endpoint>` with a
+ * `{"filter": ...}` body, which relations-restx treats exactly like a GET.
+ */
+import { ModelError } from './errors.js';
+import { Source } from './source.js';
+import { Titles } from './titles.js';
+import { sorted } from './util.js';
+import { construct } from './model.js';
+/** A set goes over the wire as a sorted list. */
+function wire(value) {
+    return value instanceof Set ? sorted(value) : value;
+}
+/** A source that uses a relations-restx API as its backend. */
+export class RestSource extends Source {
+    constructor(name, options = {}) {
+        if (typeof options.url !== 'string') {
+            throw new Error(`${name}: no url - pass options.url`);
+        }
+        const fetcher = options.fetch ?? globalThis.fetch;
+        if (typeof fetcher !== 'function') {
+            throw new Error(`${name}: no fetch here - pass options.fetch`);
+        }
+        super(name, options);
+        // Called bare, so a browser's own fetch doesn't complain about what it was called on.
+        this.fetch = (url, init) => fetcher(url, init);
+        this.url = options.url.replace(/\/+$/, '');
+        this.headers = { ...options.headers };
+        this.credentials = options.credentials;
+        this.request = { ...options.request };
+    }
+    /** Send a request, always with a JSON body, and hand back the response. */
+    async send(method, path, body) {
+        const init = {
+            ...this.request,
+            method,
+            headers: { 'Content-Type': 'application/json', ...this.headers },
+            body: JSON.stringify(body)
+        };
+        if (this.credentials !== undefined) {
+            init.credentials = this.credentials;
+        }
+        return this.fetch(`${this.url}/${path}`, init);
+    }
+    /** Checks a response and returns the result. */
+    async result(model, key, response) {
+        let body;
+        try {
+            body = await response.json();
+        }
+        catch {
+            body = null;
+        }
+        if (response.status >= 400) {
+            throw new ModelError(model, body?.message ?? 'API Error');
+        }
+        if (body === null || typeof body !== 'object') {
+            throw new ModelError(model, 'API Error');
+        }
+        if ('overflow' in body) {
+            model.overflow = model.overflow || body.overflow;
+        }
+        return body[key];
+    }
+    /** Init the model. */
+    init(model) {
+        this.recordInit(model._fields);
+        model.SINGULAR = model.SINGULAR ?? model.NAME;
+        model.PLURAL = model.PLURAL ?? `${model.SINGULAR}s`;
+        model.ENDPOINT = model.ENDPOINT ?? model.SINGULAR;
+        if (model._id !== null) {
+            const field = model._fields.field(model._id);
+            if (field.auto === null) {
+                field.auto = true;
+            }
+        }
+    }
+    // ------------------------------------------------------------------ create
+    /** Updates values with the field's that changed. */
+    createField(field, values) {
+        if (!field.auto) {
+            values[field.name] = field.export();
+            field.original = field.export();
+        }
+    }
+    /** Executes the create. */
+    async create(model) {
+        const models = model._each('create');
+        const values = [];
+        for (const creating of models) {
+            const record = {};
+            this.createRecord(creating._record, record);
+            values.push(record);
+        }
+        const records = await this.result(model, model.PLURAL, await this.send('POST', model.ENDPOINT, { [model.PLURAL]: values }));
+        for (const [index, creating] of models.entries()) {
+            if (model._id !== null && model._fields.field(model._id).auto) {
+                ;
+                creating[model._id] = records[index][model._id];
+            }
+            if (!model._bulk) {
+                for (const attr of Object.keys(creating.CHILDREN)) {
+                    const child = creating._children[attr];
+                    if (child) {
+                        await child.create();
+                    }
+                }
+            }
+            creating._action = 'update';
+            creating._record._action = 'update';
+        }
+        if (model._bulk) {
+            model._models = [];
+        }
+        else {
+            model._action = 'update';
+        }
+        return model;
+    }
+    // ------------------------------------------------------------------ retrieve
+    /** Adds criteria to the filter. */
+    retrieveField(field, criteria) {
+        for (const [operator, value] of Object.entries(field.criteria ?? {})) {
+            criteria[`${field.name}__${operator}`] = wire(value);
+        }
+    }
+    /**
+     * Adds sibling-attribute filters (model._ties, e.g. bro__name: 'Tom') to the filter so the
+     * remote API resolves them through many(); the tie field lives on the model, not the record.
+     */
+    static filterTies(model, criteria) {
+        for (const [name, attrs] of Object.entries(model._ties)) {
+            for (const [predicate, value] of Object.entries(attrs)) {
+                criteria[`${name}__${predicate}`] = wire(value);
+            }
+        }
+    }
+    /** Everything that narrows the model down, as the API wants it. */
+    async filter(model) {
+        await model._collate();
+        const criteria = {};
+        this.retrieveRecord(model._record, criteria);
+        RestSource.filterTies(model, criteria);
+        if (model._like !== null) {
+            criteria.like = model._like;
+        }
+        return criteria;
+    }
+    /** Executes the count. */
+    async count(model) {
+        const body = { filter: await this.filter(model), count: true };
+        return this.result(model, model.PLURAL, await this.send('POST', model.ENDPOINT, body));
+    }
+    /** Executes the retrieve. */
+    async retrieve(model, verify = true) {
+        const body = { filter: await this.filter(model) };
+        if (model._sort?.length) {
+            body.sort = model._sort;
+        }
+        if (model._limit !== null) {
+            body.limit = { per_page: model._limit };
+            if (model._offset) {
+                body.limit.start = model._offset;
+            }
+        }
+        const matches = await this.result(model, model.PLURAL, await this.send('POST', model.ENDPOINT, body));
+        if (model._mode === 'one' && matches.length > 1) {
+            throw new ModelError(model, 'more than one retrieved');
+        }
+        if (model._mode === 'one' && model._role !== 'child') {
+            if (matches.length < 1) {
+                if (verify) {
+                    throw new ModelError(model, 'none retrieved');
+                }
+                return null;
+            }
+            model._record = model._build('update', { read: matches[0] });
+            model._action = 'update';
+            this.retrieveTies(model, matches[0]);
+            return model;
+        }
+        model._models = [];
+        for (const match of matches) {
+            const retrieved = construct(model.constructor, { read: match });
+            this.retrieveTies(retrieved, match);
+            model._models.push(retrieved);
+        }
+        model._record = null;
+        model._action = 'update';
+        return model;
+    }
+    /**
+     * Loads the tie ids the API already resolved onto the model.
+     *
+     * Other sources query the tie table; the API has no tie endpoint but returns the
+     * resolved ids inline, so they're read straight off the response.
+     */
+    retrieveTies(model, read) {
+        for (const relation of Object.values(model.SISTERS)) {
+            if (relation.brotherSisterRef in read) {
+                ;
+                model[relation.brotherSisterRef] = read[relation.brotherSisterRef];
+            }
+        }
+        for (const relation of Object.values(model.BROTHERS)) {
+            if (relation.sisterBrotherRef in read) {
+                ;
+                model[relation.sisterBrotherRef] = read[relation.sisterBrotherRef];
+            }
+        }
+    }
+    // ------------------------------------------------------------------ titles
+    /** Creates the titles structure. */
+    async titles(model) {
+        if (model._action === 'retrieve') {
+            await this.retrieve(model);
+        }
+        const titles = await Titles.build(model);
+        for (const titling of model._each()) {
+            titles.add(titling);
+        }
+        return titles;
+    }
+    // ------------------------------------------------------------------ update
+    /** Updates values with the field's that changed. */
+    updateField(field, values) {
+        if (!field.auto && field.delta()) {
+            field.original = field.export();
+            values[field.name] = field.original;
+        }
+    }
+    /** Mass values with the field's that changed. */
+    fieldMass(field, values) {
+        if (!field.auto && field.changed) {
+            values[field.name] = field.export();
+        }
+    }
+    /** Executes the update. */
+    async update(model) {
+        let updated = 0;
+        if (model._action === 'retrieve' && model._record._action === 'update') {
+            // The model is still retrieving but has values set: change everything it matches.
+            const criteria = await this.filter(model);
+            const values = {};
+            this.recordMass(model._record, values);
+            updated += await this.result(model, 'updated', await this.send('PATCH', model.ENDPOINT, { filter: criteria, [model.PLURAL]: values }));
+        }
+        else if (model._id) {
+            for (const updating of model._each('update')) {
+                const values = {};
+                this.updateRecord(updating._record, values);
+                updated += await this.result(updating, 'updated', await this.send('PATCH', `${model.ENDPOINT}/${encodeURIComponent(updating[model._id])}`, {
+                    [model.SINGULAR]: values
+                }));
+                for (const attr of Object.keys(updating.CHILDREN)) {
+                    const child = updating._children[attr];
+                    if (child) {
+                        await child.create();
+                        await child.update();
+                    }
+                }
+            }
+        }
+        else {
+            throw new ModelError(model, 'nothing to update from');
+        }
+        return updated;
+    }
+    // ------------------------------------------------------------------ delete
+    /** Executes the delete. */
+    async delete(model) {
+        let criteria = {};
+        let deleting = [];
+        if (model._action === 'retrieve') {
+            criteria = await this.filter(model);
+        }
+        else if (model._id) {
+            deleting = model._each();
+            criteria[`${model._id}__in`] = deleting.map((each) => each[model._id]);
+        }
+        else {
+            throw new ModelError(model, 'nothing to delete from');
+        }
+        const deleted = await this.result(model, 'deleted', await this.send('DELETE', model.ENDPOINT, { filter: criteria }));
+        for (const each of deleting) {
+            each._action = 'create';
+        }
+        if (model._action !== 'retrieve') {
+            model._action = 'create';
+        }
+        return deleted;
+    }
+}
+RestSource.KIND = 'rest';
+//# sourceMappingURL=rest.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.1",
   "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,14 @@
       "types": "./dist/mock.d.ts",
       "default": "./dist/mock.js"
     },
+    "./local": {
+      "types": "./dist/local.d.ts",
+      "default": "./dist/local.js"
+    },
+    "./rest": {
+      "types": "./dist/rest.d.ts",
+      "default": "./dist/rest.js"
+    },
     "./overscore": {
       "types": "./dist/overscore.d.ts",
       "default": "./dist/overscore.js"
@@ -60,7 +68,9 @@
     "@eslint/js": "^9.39.5",
     "@types/node": "^22.0.0",
     "@unum-pillars/uikit": "^0.1.0",
+    "esbuild": "^0.25.12",
     "eslint": "^9.39.5",
+    "jsdom": "^24.1.3",
     "tsx": "^4.23.15",
     "typescript": "^5.6.0",
     "typescript-eslint": "^8.71.0"