@relations-dil/relations 0.2.0 → 0.2.1

package/README.md

@@ -781,7 +781,7 @@ Instance: `filter()`, `sort()`, `limit()`, `set()`, `add()`, `queue()`, `export(
 ### Sources
 
 `Source` (subclass this), `MockSource` (in-memory, complete), `LocalSource` (the same, kept in the
-browser's `localStorage`), `register()`, `source()`, `unregister()`, `clear()`, `SOURCES`.
+browser's `localStorage`), `RestSource` (a relations-restx API as the backend), `register()`, `source()`, `unregister()`, `clear()`, `SOURCES`.
 
 #### LocalSource
 
@@ -800,6 +800,46 @@ open on the same key don't see each other's changes; whichever saves last wins,
 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
 
 `Migrations`, `models(module)`, `modelFrom()`, `modelsFrom()`, `definitionsOf()`.

package/dist/index.d.ts

@@ -43,6 +43,7 @@ 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

@@ -43,6 +43,7 @@ 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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@relations-dil/relations",
-  "version": "0.2.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": {
@@ -35,6 +35,10 @@
       "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"
@@ -66,6 +70,7 @@
     "@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"