@relations-dil/relations 0.2.0 → 0.2.2

package/README.md

@@ -335,6 +335,17 @@ static fields = {
 }
 ```
 
+A relation can do the injecting for you, so a shared model can take on an optional parent
+without being edited or getting a column of its own. Name the dict field to store it in:
+
+```ts
+new OneToMany(Unum, Entity, { childInject: 'what' })
+// adds entity.unum_id, stored at what.relations.unum.id; entity.unum is null when there isn't one
+```
+
+The key is named `<model>_<id>`, or `<parent source>_<model>_<id>` when the parent lives in a
+different source, which has to be a dns label (letters, digits and hyphens).
+
 ---
 
 ## Querying
@@ -781,7 +792,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 +811,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/errors.d.ts

@@ -24,6 +24,10 @@ export declare class ModelError extends Error {
 export declare class UniqueError extends ModelError {
     constructor(model: any, message: string);
 }
+/** A source can't be registered, usually because its name isn't a dns label. */
+export declare class SourceError extends Error {
+    constructor(message: string);
+}
 /** Something went wrong diffing or applying migrations. */
 export declare class MigrationsError extends Error {
     constructor(message: string);

package/dist/errors.js

@@ -40,6 +40,13 @@ export class UniqueError extends ModelError {
         this.name = 'UniqueError';
     }
 }
+/** A source can't be registered, usually because its name isn't a dns label. */
+export class SourceError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'SourceError';
+    }
+}
 /** Something went wrong diffing or applying migrations. */
 export class MigrationsError extends Error {
     constructor(message) {

package/dist/field.js

@@ -491,7 +491,23 @@ export class Field {
     write(values) {
         const value = this.export();
         if (this.inject) {
-            overscore.set(values, this.inject.split('__').slice(1).join('__'), value);
+            const path = this.inject.split('__').slice(1).join('__');
+            if (value === null || value === undefined) {
+                // A null isn't stored when it's only dict keys: a missing key reads back as null,
+                // and storage has no nulls to trip over.
+                const keys = overscore.parse(path);
+                let container = values;
+                for (const key of keys.slice(0, -1)) {
+                    container =
+                        overscore.isDict(container) && typeof key === 'string' ? (key in container ? container[key] : {}) : null;
+                }
+                const last = keys[keys.length - 1];
+                if (overscore.isDict(container) && typeof last === 'string') {
+                    delete container[last];
+                    return;
+                }
+            }
+            overscore.set(values, path, value);
         }
         else if (this.store) {
             values[this.store] = value;

package/dist/index.d.ts

@@ -31,7 +31,7 @@
  */
 import * as overscore from './overscore.js';
 export { overscore };
-export { FieldError, MigrationsError, ModelError, RecordError, UniqueError } from './errors.js';
+export { FieldError, MigrationsError, ModelError, RecordError, SourceError, UniqueError } from './errors.js';
 export { OverscoreError } from './overscore.js';
 export { bool, builtin, container, dict, float, int, kindName, kindOf, list, scalar, set, str, CONTAINERS, KINDS, SCALARS, type FieldKind, type Kind, type KindClass } from './kinds.js';
 export { Field, OPERATORS, RESERVED, type Attr, type FieldOptions, type Init, type Validation } from './field.js';
@@ -43,9 +43,10 @@ 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';
+export { DNS, SOURCES, clear, register, source, unregister, type Registered } from './registry.js';
 import type { ModelClass } from './model.js';
 /**
  * Every model class exported by a module, for handing to migrations.

package/dist/index.js

@@ -31,7 +31,7 @@
  */
 import * as overscore from './overscore.js';
 export { overscore };
-export { FieldError, MigrationsError, ModelError, RecordError, UniqueError } from './errors.js';
+export { FieldError, MigrationsError, ModelError, RecordError, SourceError, UniqueError } from './errors.js';
 export { OverscoreError } from './overscore.js';
 export { bool, builtin, container, dict, float, int, kindName, kindOf, list, scalar, set, str, CONTAINERS, KINDS, SCALARS } from './kinds.js';
 export { Field, OPERATORS, RESERVED } from './field.js';
@@ -43,9 +43,10 @@ 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';
+export { DNS, SOURCES, clear, register, source, unregister } from './registry.js';
 import { Model as ModelBase } from './model.js';
 /**
  * Every model class exported by a module, for handing to migrations.

package/dist/model.js

@@ -545,12 +545,17 @@ export class Model extends ModelIdentity {
         if (name in this.PARENTS) {
             const relation = this.PARENTS[name];
             if (!this._parents[name]) {
-                this._parents[name] =
-                    this._action === 'retrieve'
-                        ? relation.Parent.many().limit(this._chunk)
-                        : construct(relation.Parent, {
-                            child: { [relation.parentId]: this._item(relation.childParentRef) }
-                        });
+                if (this._action === 'retrieve') {
+                    this._parents[name] = relation.Parent.many().limit(this._chunk);
+                }
+                else if (this._item(relation.childParentRef) === null) {
+                    return null; // No key means no parent, nothing to cache
+                }
+                else {
+                    this._parents[name] = construct(relation.Parent, {
+                        child: { [relation.parentId]: this._item(relation.childParentRef) }
+                    });
+                }
             }
             return this._parents[name];
         }

package/dist/record.js

@@ -161,7 +161,14 @@ export class Record {
     /** Whether a stored record satisfies every field's criteria. */
     retrieve(values) {
         for (const field of this._order) {
-            if (!field.retrieve(values)) {
+            if (field.inject) {
+                // An injected field is checked where it's stored, in the field it lives inside.
+                const injected = overscore.get(values[this.injected(field)] ?? {}, field.inject.split('__').slice(1).join('__'));
+                if (!field.retrieve({ [field.store]: injected })) {
+                    return false;
+                }
+            }
+            else if (!field.retrieve(values)) {
                 return false;
             }
         }

package/dist/registry.d.ts

@@ -6,6 +6,11 @@
  * the whole point of relations: the same model runs against a database in one service
  * and against a REST API in another.
  */
+/**
+ * A dns label, which is what a source's name has to be so it's safe to use in other names:
+ * letters, digits and hyphens, 1 to 63 characters, no leading or trailing hyphen.
+ */
+export declare const DNS: RegExp;
 /** Anything registered as a source. Kept loose to avoid a circular import. */
 export interface Registered {
     name: string;
@@ -13,7 +18,7 @@ export interface Registered {
 }
 /** Every registered source, keyed by name. */
 export declare const SOURCES: Map<string, Registered>;
-/** Register a source under its name, replacing any source already there. */
+/** Register a source under its name, replacing any source already there. The name has to be a dns label. */
 export declare function register(source: Registered): void;
 /** The source registered under a name, or `undefined`. */
 export declare function source(name: string | null | undefined): Registered | undefined;

package/dist/registry.js

@@ -6,10 +6,19 @@
  * the whole point of relations: the same model runs against a database in one service
  * and against a REST API in another.
  */
+import { SourceError } from './errors.js';
+/**
+ * A dns label, which is what a source's name has to be so it's safe to use in other names:
+ * letters, digits and hyphens, 1 to 63 characters, no leading or trailing hyphen.
+ */
+export const DNS = /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$/i;
 /** Every registered source, keyed by name. */
 export const SOURCES = new Map();
-/** Register a source under its name, replacing any source already there. */
+/** Register a source under its name, replacing any source already there. The name has to be a dns label. */
 export function register(source) {
+    if (typeof source.name !== 'string' || !DNS.test(source.name)) {
+        throw new SourceError(`source ${source.name} is not dns compliant`);
+    }
     SOURCES.set(source.name, source);
 }
 /** The source registered under a name, or `undefined`. */

package/dist/relation.d.ts

@@ -32,6 +32,11 @@ export interface OneToOptions {
     parentId?: string | number;
     /** Field on the child that points at the parent. Inferred by convention. */
     childParentRef?: string | number;
+    /**
+     * A dict field on the child to store the parent id in, so the child needs no field of its own
+     * for it. The relation adds that field, at `<childInject>__relations__<parent>__<id>`.
+     */
+    childInject?: string;
 }
 /** One parent record to one or many child records. */
 export declare class OneTo extends Relation {
@@ -49,6 +54,8 @@ export declare class OneTo extends Relation {
     childParentRef: string;
     /** Attribute on the child that reaches the parent. */
     childParentAttr: string;
+    /** The dict field in the child the parent id is stored in, if it's not a field of its own. */
+    childInject: string | null;
     /** Whether the child side holds one record or many. */
     MODE: 'one' | 'many';
     constructor(Parent: ModelClass, Child: ModelClass, options?: OneToOptions);

package/dist/relation.js

@@ -12,6 +12,9 @@
  * ```
  */
 import { ModelError } from './errors.js';
+import { Field } from './field.js';
+import { dict } from './kinds.js';
+import { DNS } from './registry.js';
 /** Base for every relation, holding the convention used to find the joining field. */
 export class Relation {
     /** Whether the two sides can share an id field name. */
@@ -55,6 +58,8 @@ export class OneTo extends Relation {
     childParentRef;
     /** Attribute on the child that reaches the parent. */
     childParentAttr;
+    /** The dict field in the child the parent id is stored in, if it's not a field of its own. */
+    childInject;
     /** Whether the child side holds one record or many. */
     MODE;
     constructor(Parent, Child, options = {}) {
@@ -63,14 +68,48 @@ export class OneTo extends Relation {
         this.Parent = Parent;
         this.Child = Child;
         this.MODE = kind.MODE;
+        this.childInject = options.childInject ?? null;
         const parent = Parent.thy();
-        const child = Child.thy();
+        let child = Child.thy();
         this.parentId = parent._fieldName(options.parentId ?? parent._id);
         this.parentChildAttr = options.parentChildAttr ?? child.NAME;
+        let childParentRef = options.childParentRef;
+        // If asked, add the child field for the parent id, stored in a dict field of the child.
+        if (this.childInject !== null) {
+            const stored = child._fields._names.get(this.childInject);
+            if (stored === undefined) {
+                throw new ModelError(child, `cannot find field ${this.childInject} in ${child.NAME}`);
+            }
+            if (stored.kind !== dict) {
+                throw new ModelError(child, `field ${this.childInject} not a dict in ${child.NAME}`);
+            }
+            // Same source is just the model name, else prefix the source of the parent (a dns label).
+            let named = parent.NAME;
+            if (parent.SOURCE !== child.SOURCE) {
+                if (typeof parent.SOURCE !== 'string' || !DNS.test(parent.SOURCE)) {
+                    throw new ModelError(parent, `source ${parent.SOURCE} is not dns compliant`);
+                }
+                named = `${parent.SOURCE.toLowerCase().replace(/-/g, '_')}_${parent.NAME}`;
+            }
+            const ref = childParentRef !== undefined ? String(childParentRef) : `${named}_${this.parentId}`;
+            if (child._fields.has(ref)) {
+                throw new ModelError(child, `field ${ref} already exists in ${child.NAME}`);
+            }
+            const kindOfParent = parent._fields._names.get(this.parentId).kind;
+            Child.fields = {
+                ...Child.fields,
+                [ref]: new Field(kindOfParent, {
+                    inject: `${this.childInject}__relations__${named}__${this.parentId}`,
+                    none: true
+                })
+            };
+            childParentRef = ref;
+            child = Child.thy();
+        }
         this.childParentAttr = options.childParentAttr ?? parent.NAME;
         this.childParentRef =
-            options.childParentRef !== undefined
-                ? child._fieldName(options.childParentRef)
+            childParentRef !== undefined
+                ? child._fieldName(childParentRef)
                 : Relation.relativeField(parent, child, kind.SAME);
         this.Parent._child(this);
         this.Child._parent(this);

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.2",
   "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"