@relations-dil/relations 0.2.1 → 0.2.3

package/CHANGELOG.md

@@ -0,0 +1,86 @@
+# Changelog
+
+All notable changes to this project are recorded here, newest first. Format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow [SemVer](https://semver.org/).
+
+## [Unreleased]
+
+## [0.2.3] - 2026-10-18
+
+Parity with python-relations 0.6.20, the four releases since 0.6.16, and the release tooling the Python repos have.
+
+### Added
+- `Model.pre(action, ...args)` and `Model.post(action, result, ...args)`, empty hooks run around every source action (`create`, `count`, `retrieve`, `titles`, `update`, `delete`). Override `pre` to deny (throw) or rewrite (`this.filter(...)`), bulk calls included; override `post` to transform the result, it must return it. Both can be `async` and chain through `super`. (python-relations 0.6.17)
+- String ids (slugs): an id that isn't an `int` is supplied by the caller instead of generated by the source. Such an id is not `auto`, can't be null and is `readonly`, and unless set otherwise it is the model's only title, has no extra unique index (it is the key) and is the default order. `MockSource` (and so `LocalSource`) keys its data by the supplied id and throws a `UniqueError` for a missing or repeated one. (0.6.18)
+- `readonly` is enforced, it was declared and never read: a readonly field is written on create, skipped by `update` and mass updates, and an edited value snaps back to what is stored so `WHERE` clauses still find the record. (0.6.18)
+- `RelationsError`, the base of every error relations throws, so one `catch` gets them all. `FieldError`, `ModelError`, `RecordError`, `MigrationsError` and `SourceError` extend it. (0.6.19)
+- `NotFoundError` ("none retrieved") and `MultipleError` ("more than one retrieved"), both `ModelError`s with the same messages as before, thrown by `MockSource` and `RestSource` in place of a plain `ModelError`. `UniqueError` was already there. (0.6.19)
+- Release tooling, as in the Python repos: one script in `scripts/` per make target. `make new` (next version, branch, `VERSION`, `package.json`, changelog section), `make release-check` (where the release is up to and what would stop it), `make release` (from `main`: the checks, npm, a clean install from the registry, the tag; it does only what's left, so it can be run again), `make verify` (the clean install), and `make test-release`, which tests the scripts against a throwaway repo and a fake registry (109 assertions).
+- A `release` stage in the `Jenkinsfile`, on `main` only: a merged `VERSION` that isn't released yet is published and tagged. It needs `~/.npmrc` with a publish token on the Jenkins host; a `VERSION` that is already out is a no-op.
+- `make` on its own lists the targets (`make help`), each has a description, and `make sync` does what `make version` used to.
+
+### Changed
+- A model whose name has a `.` in it throws a `ModelError`: ids built from a model's name (relations-unifist's `seq.model.source.unum`) use the dot to separate their parts. (0.6.20)
+- Models whose id field isn't an `int` get the string id defaults above, so their default titles, unique index and order change; set `titles` and `unique` to keep the old ones.
+- `make version` sets `VERSION` and syncs `package.json` and the lockfile (`V=+0.0.1|+0.1|+1|x.y.z`, `+0.0.1` by default), like the Python repos. What it did before is `make sync`.
+- `make tag` skips a tag that exists instead of hiding every failure, and every `docker run` in the Makefile uses `--rm`.
+- `make pack` and `make publish` build from a copy, with only what the package needs mounted read-only, so nothing is written into the working tree.
+
+### Fixed
+- `CHANGELOG.md` is in the published package, `files` listed it but the build never had it (39 files in 0.2.2, 40 now).
+
+## [0.2.2] - 2026-10-06
+
+Parity with python-relations 0.6.16: an optional parent whose id is stored in a dict field of the child.
+
+### Added
+- `childInject` on `OneTo` (and so `OneToMany` and `OneToOne`): `new OneToMany(Unum, Entity, { childInject: 'what' })` adds a nullable key field to the child, `unum_id`, stored inside the child's `what` dict at `what__relations__unum__id`, so a model that's shared between apps can take on a parent without being edited or getting a column. The dict field has to be named, it isn't touched (no `extract`), and several parents can use the same one. It throws a `ModelError` if the key field already exists, the named field is missing, or it isn't a dict.
+- The key is named `<model>_<id>` when the parent and child share a source, else `<parent source>_<model>_<id>` (the source lowercased, `-` as `_`), like `bucket_app_pet_id`. `childParentRef` still overrides it.
+- `DNS` and `SourceError`: source names have to be dns labels (letters, digits and hyphens, 1 to 63 characters, no leading or trailing hyphen), so they're safe to use in field names. `register` throws a `SourceError` for any other name, and `OneTo` checks the parent's source when the two sources differ.
+
+### Changed
+- An empty key means no parent: `_relate` returns `null` for a parent when its key is `null`, instead of a placeholder parent that matches nothing. Setting the key later still loads the parent.
+- `Record.retrieve` checks an injected field where it's stored, in the field it lives inside, so filtering by an injected key works.
+- `Field.write` doesn't store a `null` for an injected field whose path is only dict keys, it leaves the key out (or removes it), since a missing key reads back as `null` and storage has no JSON nulls to trip over. Paths through a list still set the `null`.
+
+## [0.2.1] - 2026-10-02
+
+### Added
+- The example is laid out as a list of apps: `app.js` lists them (name, title, models file, source, seed), `models/<app>.js` holds each app's models and relations (source-agnostic; the source is named for the app), and `js/unum.js` is the host that builds the apps, makes their sources, seeds an empty one and starts the screens. Screens are routed by app, `/<app>/<model>` (`#/example/unit`), with an app page at `/<app>`, a nav of apps with their models in dropdowns and a home page listing the apps, so two apps can each have a model of the same name; the access function addresses models as `api/<app>/<model>`, and routes, route names and controllers are keyed `<app>_<model>`. `make dotroute` loads the models file with a script tag; `make single` inlines `app.js` and every `models/*.js`.
+- Single-file pages keep **every app's data** in one file next to the page: `app.html` loads `data.js` (a plain `<script src>`, which works from `file://`) on open, and **Save to data.js** (or Cmd/Ctrl-S) writes it back, in place after one pick in Chromium (File System Access API) or as a download elsewhere. `localStorage` stays the working copy, one key per app (`relations:<app>`); one revision covers the whole file and decides whether the file or the browser is newer, and the page asks when both changed. Apps in the file that aren't running here are kept on save. A chip shows saved or unsaved, and leaving with unsaved changes asks first. Code in `example/dotroute/www/js/persist.js`; `make check-single` runs 14 jsdom checks of the rules.
+- `RestSource` (`@relations-dil/relations/rest`, also exported from the index): a source that uses a relations-restx API as its backend, a port of python-relations-rest. It takes `url`, and optionally `fetch`, `headers`, `credentials` and `request`, and works in the browser or in Node. Reads go as `POST /<endpoint>` with a `{"filter": ...}` body (which restx treats as a GET), since browsers can't send a body with a GET. Errors from the API throw a `ModelError` with its message.
+- `test/restx-fake.ts`: an in-process relations-restx API (a `fetch` over MockSource-backed models) the `RestSource` tests run against, with no network.
+
+## [0.2.0] - 2026-10-02
+
+### Added
+- A `VERSION` file as the one place the version is set. The Makefile reads it, and `make version`, `make pack` and `make publish` sync `package.json` and the lockfile to it, so what's published always matches.
+- `LocalSource` (`@relations-dil/relations/local`, also exported from the index): a source that keeps its data in `localStorage` (or any `storage` you pass), loading when it's made and saving after every successful write. `MockSource` stays purely in memory.
+- `make local`: builds the single file and opens it in your browser (`open`, or `xdg-open` where there's no `open`).
+- `example/single/` and `make single`: builds the doTRoute app into one self-contained `app.html` (library, UIkit, jQuery, doT, doTRoute, templates and app all inlined) that opens from disk with no server and keeps its data in `localStorage`. The example app picks `LocalSource` when the page sets `STORAGE_KEY`, and only seeds an empty store; `DRApp.load` reads templates embedded in the page when there are any.
+- `make shell` mounts `~/.npmrc` too, so npm commands run as you, but only when the file exists.
+
+### Changed
+- File access in `MockSource` and `Migrations` is loaded lazily and `node:path` is no longer used (a small `joinPath` replaces it), so the library bundles for the browser with no stub and no Node polyfills; only the file-based features need Node when called. `make dotroute` no longer needs a stub file, and `esbuild` is now a dev dependency.
+
+## [0.1.0] - 2026-10-02
+
+### Added
+- Package metadata for npm: `repository`, `homepage` and `bugs`.
+- Initial TypeScript port (usable from plain JavaScript) of python-relations (npm package `@relations-dil/relations`): Model, Field, Record, Relation, Source, Migrations, Titles, MockSource, overscore, and models-from-data.
+- Docker-based workflow (`Dockerfile`, `Makefile`, `Jenkinsfile`) mirroring the Python repos: `make build|test|lint|setup|shell|debug|example|pack|publish|tag`. Nothing needs installing locally beyond Docker and make.
+- `package.json` scripts (`build`, `test`, `coverage`, `lint`, `typecheck`, `example`) as the canonical commands; the Makefile wraps them, so `npm` works too for anyone with Node.
+- ESLint (flat config, 140-column limit) and TypeScript typecheck as `lint`.
+- Coverage tests (`test/coverage.test.ts`, `test/coverage-isolated.test.ts`) covering the edge cases and error paths the ported suites missed, bringing `make test` to 100% line, branch and function coverage. The isolated file runs in its own process so it can see `MigrationsRef` before `migrations.ts` replaces its stub.
+- `example/dotroute/`: a playable doTRoute app that follows the layout of the other apps' `gui/www`: an empty `index.html`, one `.html` file per view (header, footer, home, form, fields, list, create, retrieve, update), the generic `js/relations.js` (Base and Model controllers, the same as the other apps' apart from `await`), and a small `js/service.js` for the app's routes. Every data call goes through one access function, `DRApp.rest(type, url, data)`, in `js/api.js`: `DRApp.http` is the other apps' request to a relations-restx API, and `DRApp.local` answers the same API from relations models running in the page, with the restx endpoints, request bodies, response shapes (`api/model`, `OPTIONS` fields with a parent's `options` and `titles`, list `formats` and `overflow`, `{updated}`/`{deleted}`) and status codes, including the alert on failure. Moving to a real backend is `DRApp.rest = DRApp.http` in `service.js`. Foreign keys render as a select of the parent's titles and display as the parent's title in lists. `make dotroute` bundles the library for the browser with esbuild (an IIFE exposing global `Relations`, with the `node:` file imports stubbed out) and serves it on http://localhost:8483 (`make dotroute PORT=9000` to change it; 8483 is ASCII T and S).
+
+### Changed
+- The published package no longer includes `.map` files (source maps and declaration maps): `src/` isn't shipped, so they pointed at nothing. They're still built locally.
+- `example/dotroute/` uses the published `@unum-pillars/uikit` theme (UIkit 3 with the `uu-*` palette) instead of a vendored UIkit 2. It's a dev dependency, and `make dotroute` copies `dist/` into `example/dotroute/www/vendor/` (gitignored). The ported views use UIkit 3 classes (`uk-navbar-container`, `uk-input`, `uk-alert-danger`, ...), with the navbar built the UIkit 3 way (a full-width bar with a container inside it) and UIkit 3's own centered container width; the other apps' wide-container override in `relations.css` was UIkit 2 CSS and isn't carried over.
+- Removed provably unreachable code found while reaching 100% coverage, with no behaviour change: the `UNDEFINE` filter in `Field.define()` (no definable attribute was ever in it), the unreachable `return 0` in `count()` in `field.ts`, a duplicated no-records check in `Model._item`, and `this._proxy ?? this` / `?.` / `?? 0` fallbacks in `model.ts` and `mock.ts` that could never fire.
+- Tests run directly from `.ts` via `tsx` (no compiled `dist-test/` step).
+- Repo is named `typescript-relations` (Docker image too); the npm package is `@relations-dil/relations`, under the `relations-dil` npm org.
+- `files` in `package.json` references `LICENSE` (repo copy) instead of `LICENSE.txt`.
+
+### Fixed
+- Four lint violations in the ported source: a long line in `field.ts`, a `Function` type in `model.ts`, and two bare expressions in `ported-model.test.ts`.

package/README.md

@@ -24,6 +24,8 @@ npm install @relations-dil/relations
 - [Querying](#querying)
 - [Relations](#relations)
 - [Titles](#titles)
+- [Ids you supply](#ids-you-supply)
+- [Hooks](#hooks)
 - [Migrations](#migrations)
 - [Models from data (YAML, JSON, anywhere)](#models-from-data-yaml-json-anywhere)
 - [Writing your own source](#writing-your-own-source)
@@ -286,7 +288,7 @@ class Thing extends Model {
 | `options`    | The complete set of allowed values.                                           |
 | `validation` | A regular expression, a pattern string, or a predicate.                       |
 | `length`     | Length of the value, for sources that care.                                   |
-| `readonly`   | Whether the caller may write it.                                              |
+| `readonly`   | Written on create, never on update. An edited value snaps back to what's stored. |
 | `auto`       | Whether the source generates it — an auto-increment id, say.                  |
 | `refresh`    | Reset to the default on update when untouched. Good for `updated_at`.         |
 | `inject`     | Store this value inside another `list` or `dict` field, at a path.            |
@@ -335,6 +337,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
@@ -538,6 +551,51 @@ class Item extends Base {
 
 ---
 
+## Ids you supply
+
+Only an `int` id is generated by the source. An id of any other kind, a `str` slug, is supplied by
+the caller: it's not `auto`, can't be null, and is `readonly`, so it's written when the record is
+created and never changed. Unless you say otherwise it's the model's only title, there's no extra
+unique index (it is the key), and it's the default order.
+
+```ts
+class Tag extends fields({ id: str, label: str }) {
+  static source = 'example'
+}
+
+await new Tag('fine', 'Fine').create()
+
+const tag = await Tag.one('fine').retrieve()
+tag.id = 'renamed'     // snaps back to 'fine' on update
+```
+
+A missing or repeated id throws a `UniqueError`. A model's name can't have a `.` in it, ids built
+from a name (`seq.model.source.unum`) use the dot to separate their parts.
+
+---
+
+## Hooks
+
+`pre(action, ...args)` and `post(action, result, ...args)` run around every source action:
+`create`, `count`, `retrieve`, `titles`, `update` and `delete`. Bulk calls come through too, as a
+model in many mode. Override `pre` to deny (throw) or rewrite (`this.filter(...)`) before the
+source runs, and `post` to transform what it returned. `post` must return the result. Both can be
+`async`, and mixins chain through `super`.
+
+```ts
+class Mine extends fields({ id: int, name: str, owner: str }) {
+  static source = 'example'
+
+  pre(action: string) {
+    if (action !== 'create') {
+      this.filter({ owner: currentUser() })   // every read, update and delete is scoped
+    }
+  }
+}
+```
+
+---
+
 ## Migrations
 
 Definitions are backend-neutral JSON. A source converts them into whatever it needs — DDL
@@ -740,6 +798,7 @@ assertion. Where behaviour differs, it's for a reason:
 | **`add()` on an unread relation** | Retrieves first | Starts a fresh set | The retrieve would have to be awaited |
 | **`bool` casting** | `bool("false")` is `true` | `"false"`, `"no"`, `"0"`, `""` are `false` | Sane for HTTP params; Python's is a wart |
 | **`int` default of `false`** | Allowed (`bool` subclasses `int`) | Rejected | JS has no such relationship |
+| **Overriding `pre` / `post`** | A method in the class body that shadows one of `Model`'s is left alone, not made a field | Fields are declared in `static fields`, so a method is always a method | Nothing to guard against |
 | **`error.message`** | Bare text; name added by `__str__` | Name included; bare text on `.detail` | `assert.throws` and stack traces read `.message` |
 | **Sorting on several keys** | Only the first key was used | All keys, in order | Python bug |
 | **`titles` as a field name** | Allowed (typo in the reserved list) | Reserved | It's a real method |
@@ -767,8 +826,8 @@ Config statics: `source`, `store`, `title`, `id`, `titles`, `list`, `unique`, `i
 `order`, `chunk`.
 
 Instance: `filter()`, `sort()`, `limit()`, `set()`, `add()`, `queue()`, `export()`,
-`toJSON()`, `keys()`, `size`, `models`, `overflow`, `query()`, and the six async methods
-`create()`, `retrieve()`, `count()`, `update()`, `delete()`, `titles()`.
+`toJSON()`, `keys()`, `size`, `models`, `overflow`, `query()`, the hooks `pre()` and `post()`, and
+the six async methods `create()`, `retrieve()`, `count()`, `update()`, `delete()`, `titles()`.
 
 ### Kinds
 
@@ -846,8 +905,11 @@ that many and sets `overflow` when it got that many.
 
 ### Errors
 
-`FieldError`, `RecordError`, `ModelError`, `UniqueError`, `MigrationsError`,
-`OverscoreError`. All carry the thing that went wrong, not just a message.
+`RelationsError` is the base of every error relations throws, so one `catch` gets them all.
+`FieldError`, `RecordError`, `ModelError`, `MigrationsError` and `SourceError` extend it, and
+`UniqueError`, `NotFoundError` ("none retrieved") and `MultipleError` ("more than one retrieved")
+are `ModelError`s, so what caught a `ModelError` still does. `OverscoreError` is its own.
+All carry the thing that went wrong, not just a message.
 
 ### overscore
 
@@ -874,6 +936,25 @@ npm test           # compile and run the full suite
 npm run typecheck  # types only, no output
 ```
 
+Nothing needs installing but Docker and make. `make` on its own lists every target, and the
+usual ones are `make build`, `make test` (100% coverage), `make lint` and `make setup`.
+
+### Releasing
+
+`VERSION` is the one place the version is set. The work is in `scripts/`, one script per target.
+
+```bash
+make new                  # next version: branch gaf3/<version>, VERSION, package.json, changelog
+make new V=+0.1 B=thing   # a bigger bump (+0.0.1, +0.1, +1 or x.y.z) and a branch name
+make release-check        # where the release is up to, and what would stop it
+make release              # from main: the checks, npm, a clean install from it, the tag
+make test-release         # tests the scripts against a throwaway repo and a fake registry
+```
+
+`make release` does only what's left, so it can be run again after a failure, and once the version
+is out and tagged it does nothing. It needs `~/.npmrc` with a token that can publish. The Jenkins
+build runs it on `main`, so merging a pull request with an unreleased `VERSION` releases it.
+
 No runtime dependencies.
 
 ## License

package/dist/errors.d.ts

@@ -2,18 +2,22 @@
  * Error classes. Each one carries the thing that went wrong, not just a message,
  * so callers can branch on the field or model involved.
  */
+/** The base of every error relations throws, so one catch gets them all. */
+export declare class RelationsError extends Error {
+    constructor(message: string);
+}
 /** Something invalid about a field's definition, value, or criteria. */
-export declare class FieldError extends Error {
+export declare class FieldError extends RelationsError {
     field: any;
     constructor(field: any, message: string);
 }
 /** Something invalid about a record - usually an unknown field name. */
-export declare class RecordError extends Error {
+export declare class RecordError extends RelationsError {
     record: any;
     constructor(record: any, message: string);
 }
 /** Something invalid about a model, its identity, or the action being attempted. */
-export declare class ModelError extends Error {
+export declare class ModelError extends RelationsError {
     /** The model the error is about. */
     model: any;
     /** The message on its own, without the model name in front. */
@@ -24,8 +28,20 @@ export declare class ModelError extends Error {
 export declare class UniqueError extends ModelError {
     constructor(model: any, message: string);
 }
+/** A record that was asked for as one, to read, update or delete, isn't there. */
+export declare class NotFoundError extends ModelError {
+    constructor(model: any, message: string);
+}
+/** More than one record where there should be only one. */
+export declare class MultipleError 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 RelationsError {
+    constructor(message: string);
+}
 /** Something went wrong diffing or applying migrations. */
-export declare class MigrationsError extends Error {
+export declare class MigrationsError extends RelationsError {
     constructor(message: string);
 }
 //# sourceMappingURL=errors.d.ts.map

package/dist/errors.js

@@ -2,8 +2,15 @@
  * Error classes. Each one carries the thing that went wrong, not just a message,
  * so callers can branch on the field or model involved.
  */
+/** The base of every error relations throws, so one catch gets them all. */
+export class RelationsError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'RelationsError';
+    }
+}
 /** Something invalid about a field's definition, value, or criteria. */
-export class FieldError extends Error {
+export class FieldError extends RelationsError {
     field;
     constructor(field, message) {
         super(message);
@@ -12,7 +19,7 @@ export class FieldError extends Error {
     }
 }
 /** Something invalid about a record - usually an unknown field name. */
-export class RecordError extends Error {
+export class RecordError extends RelationsError {
     record;
     constructor(record, message) {
         super(message);
@@ -21,7 +28,7 @@ export class RecordError extends Error {
     }
 }
 /** Something invalid about a model, its identity, or the action being attempted. */
-export class ModelError extends Error {
+export class ModelError extends RelationsError {
     /** The model the error is about. */
     model;
     /** The message on its own, without the model name in front. */
@@ -40,8 +47,29 @@ export class UniqueError extends ModelError {
         this.name = 'UniqueError';
     }
 }
+/** A record that was asked for as one, to read, update or delete, isn't there. */
+export class NotFoundError extends ModelError {
+    constructor(model, message) {
+        super(model, message);
+        this.name = 'NotFoundError';
+    }
+}
+/** More than one record where there should be only one. */
+export class MultipleError extends ModelError {
+    constructor(model, message) {
+        super(model, message);
+        this.name = 'MultipleError';
+    }
+}
+/** A source can't be registered, usually because its name isn't a dns label. */
+export class SourceError extends RelationsError {
+    constructor(message) {
+        super(message);
+        this.name = 'SourceError';
+    }
+}
 /** Something went wrong diffing or applying migrations. */
-export class MigrationsError extends Error {
+export class MigrationsError extends RelationsError {
     constructor(message) {
         super(message);
         this.name = 'MigrationsError';

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;
@@ -627,6 +643,14 @@ export class Field {
     }
     /** Write this field's value for an update, if it changed. */
     update(values) {
+        // A readonly field isn't written, and an edit snaps back to what's stored.
+        if (this.readonly) {
+            if (this.original !== null && this.delta()) {
+                this.value = this.original;
+                this.changed = false;
+            }
+            return;
+        }
         if (this.refresh && !this.delta()) {
             this.value = typeof this.default === 'function' ? this.default() : this.default;
         }
@@ -637,6 +661,9 @@ export class Field {
     }
     /** Write this field's value for a mass update, if it was set. */
     mass(values) {
+        if (this.readonly) {
+            return;
+        }
         if (this.refresh && !this.changed) {
             this.value = typeof this.default === 'function' ? this.default() : this.default;
         }

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, MultipleError, NotFoundError, RecordError, RelationsError, 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';
@@ -46,7 +46,7 @@ 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, MultipleError, NotFoundError, RecordError, RelationsError, 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';
@@ -46,7 +46,7 @@ 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/mock.d.ts

@@ -35,9 +35,9 @@ export declare class MockSource extends Source {
     /** Last id handed out, keyed by model name. */
     ids: globalThis.Record<string, number>;
     /** Records keyed by id, keyed by model name. */
-    data: globalThis.Record<string, Map<number, Stored>>;
+    data: globalThis.Record<string, Map<number | string, Stored>>;
     /** Unique index values keyed by id, keyed by index, keyed by model name. */
-    unique: globalThis.Record<string, globalThis.Record<string, Map<number, string>>>;
+    unique: globalThis.Record<string, globalThis.Record<string, Map<number | string, string>>>;
     /** Migrations applied so far, or null when nothing has been loaded. */
     migrations: string[] | null;
     /** Snapshot taken while a write is in flight, so a failure can roll back. */
@@ -56,7 +56,7 @@ export declare class MockSource extends Source {
     /** Copy extracted paths out of container fields into their own stored keys. */
     static extract(model: Model, values: Stored): Stored;
     /** Check every unique index, recording the new value or throwing. */
-    uniques(model: Model, values: Stored, id: number): void;
+    uniques(model: Model, values: Stored, id: number | string): void;
     /** Run a write with a snapshot in place, restoring it if the write fails. */
     private rolling;
     createQuery(model: Model): Query;

package/dist/mock.js

@@ -11,7 +11,7 @@
  * ```
  */
 import * as overscore from './overscore.js';
-import { ModelError, UniqueError } from './errors.js';
+import { ModelError, MultipleError, NotFoundError, UniqueError } from './errors.js';
 import { Source } from './source.js';
 import { Titles } from './titles.js';
 import { clone, joinPath, stable } from './util.js';
@@ -162,12 +162,21 @@ export class MockSource extends Source {
             for (const creating of model._each('create')) {
                 const values = creating._record.create({});
                 this.ids[name] += 1;
-                this.uniques(model, values, this.ids[name]);
-                if (model._id !== null && (values[model._id] ?? null) === null) {
-                    values[model._fields.field(model._id).store] = this.ids[name];
-                    creating[model._id] = this.ids[name];
+                const idField = model._id !== null ? model._fields.field(model._id) : null;
+                let key = this.ids[name];
+                // Ids the caller supplies (slugs) are the keys, else it's the next number.
+                if (idField !== null && !idField.auto) {
+                    key = values[idField.store];
+                    if (key === null || key === undefined || this.data[name].has(key)) {
+                        throw new UniqueError(model, `value ${JSON.stringify(key ?? null)} violates unique ${model._id}`);
+                    }
+                }
+                this.uniques(model, values, key);
+                if (idField !== null && idField.auto && (values[model._id] ?? null) === null) {
+                    values[idField.store] = key;
+                    creating[model._id] = key;
                 }
-                this.data[name].set(this.ids[name], MockSource.extract(creating, values));
+                this.data[name].set(key, MockSource.extract(creating, values));
                 if (!model._bulk) {
                     if (model._id) {
                         await Source.createTies(creating);
@@ -256,12 +265,12 @@ export class MockSource extends Source {
             }
         }
         if (model._mode === 'one' && matches.length > 1) {
-            throw new ModelError(model, 'more than one retrieved');
+            throw new MultipleError(model, 'more than one retrieved');
         }
         if (model._mode === 'one' && model._role !== 'child') {
             if (matches.length < 1) {
                 if (verify) {
-                    throw new ModelError(model, 'none retrieved');
+                    throw new NotFoundError(model, 'none retrieved');
                 }
                 return null;
             }

package/dist/model.d.ts

@@ -253,6 +253,19 @@ export declare class Model extends ModelIdentity {
     toJSON(): any;
     /** The definition of this model, for schemas and migrations. */
     static define(...args: any[]): any;
+    /**
+     * Called before every source action (create, count, retrieve, titles, update, delete).
+     * Override to deny (throw) or rewrite (`this.filter(...)`) before the source runs.
+     * Bulk calls come through here too, as a model in many mode.
+     */
+    pre(action: string, ...args: any[]): void;
+    /**
+     * Called after every source action with what the source returned. Override to
+     * transform the result. Must return the result.
+     */
+    post(action: string, result: any, ...args: any[]): any;
+    /** Runs `pre`, the source action, then `post`. */
+    _hook(action: 'create' | 'count' | 'retrieve' | 'titles' | 'update' | 'delete', ...args: any[]): Promise<any>;
     /** Write this model's records to the source. */
     create(...args: any[]): Promise<this>;
     /** How many records match. */

package/dist/model.js

@@ -356,6 +356,10 @@ export class Model extends ModelIdentity {
         const self = target ?? new ModelIdentity();
         self.TITLE = cls.title ?? cls.name;
         self.NAME = cls.store ?? underscore(self.TITLE);
+        // Ids built from a model's name separate their parts with a dot.
+        if (self.NAME.includes('.')) {
+            throw new ModelError(self, "model name cannot contain '.'");
+        }
         // Build the fields.
         const fields = new Record();
         for (const [name, spec] of Object.entries(cls.fields ?? {})) {
@@ -367,8 +371,29 @@ export class Model extends ModelIdentity {
         // Which field is the id.
         const id = cls.id === undefined ? 0 : cls.id;
         self._id = id === null ? null : self._fieldName(id);
+        // Only int ids are generated by the source (it marks them auto). Any other kind, a slug,
+        // is supplied by the caller, so it's required and written once.
+        let supplied = false;
+        if (self._id !== null) {
+            const field = self._fields.field(self._id);
+            if (field.auto === null && field.kind !== int) {
+                field.auto = false;
+            }
+            supplied = field.auto === false && field.kind !== int;
+            if (supplied) {
+                if (field._none === null) {
+                    field.none = false;
+                }
+                if (field.readonly === null) {
+                    field.readonly = true;
+                }
+            }
+        }
         // Which fields make up a title.
         let titles = cls.titles;
+        if (!titles && supplied) {
+            titles = [self._id];
+        }
         if (!titles) {
             const found = [];
             for (const field of self._fields._order) {
@@ -410,7 +435,10 @@ export class Model extends ModelIdentity {
         }
         // Unique indexes: unset means the titles, explicitly empty means none.
         let unique = cls.unique;
-        if (unique === undefined) {
+        if (unique === undefined && supplied) {
+            unique = {};
+        }
+        else if (unique === undefined) {
             unique = self._titles;
         }
         else if (!unique || (Array.isArray(unique) && !unique.length)) {
@@ -467,6 +495,9 @@ export class Model extends ModelIdentity {
         else if (cls.order === undefined && Object.keys(self._unique).length === 1) {
             self._order = self._ordering(Object.values(self._unique)[0]);
         }
+        else if (cls.order === undefined && supplied) {
+            self._order = self._ordering([self._id]);
+        }
         else {
             self._order = [];
         }
@@ -545,12 +576,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];
         }
@@ -1012,12 +1048,32 @@ export class Model extends ModelIdentity {
         const cls = this;
         return need(cls.source, cls).define(cls.thy().define(), ...args);
     }
+    /**
+     * Called before every source action (create, count, retrieve, titles, update, delete).
+     * Override to deny (throw) or rewrite (`this.filter(...)`) before the source runs.
+     * Bulk calls come through here too, as a model in many mode.
+     */
+    pre(action, ...args) { }
+    /**
+     * Called after every source action with what the source returned. Override to
+     * transform the result. Must return the result.
+     */
+    post(action, result, ...args) {
+        return result;
+    }
+    /** Runs `pre`, the source action, then `post`. */
+    async _hook(action, ...args) {
+        const model = this._proxy;
+        await model.pre(action, ...args);
+        const result = await need(this.SOURCE, this)[action](model, ...args);
+        return model.post(action, result, ...args);
+    }
     /** Write this model's records to the source. */
     async create(...args) {
         if (!['create', 'update'].includes(this._action)) {
             throw new ModelError(this, `cannot create during ${this._action}`);
         }
-        await need(this.SOURCE, this).create(this._proxy, ...args);
+        await this._hook('create', ...args);
         return this;
     }
     /** How many records match. */
@@ -1025,7 +1081,7 @@ export class Model extends ModelIdentity {
         if (!['update', 'retrieve'].includes(this._action)) {
             throw new ModelError(this, `cannot count during ${this._action}`);
         }
-        return need(this.SOURCE, this).count(this._proxy, ...args);
+        return this._hook('count', ...args);
     }
     /**
      * Read this model's records out of the source. Pass `false` to get `null` instead of
@@ -1035,7 +1091,7 @@ export class Model extends ModelIdentity {
         if (this._action !== 'retrieve') {
             throw new ModelError(this, `cannot retrieve during ${this._action}`);
         }
-        const retrieved = await need(this.SOURCE, this).retrieve(this._proxy, verify, ...args);
+        const retrieved = await this._hook('retrieve', verify, ...args);
         return retrieved === null ? null : this;
     }
     /** Titles for the matching records, keyed by id. */
@@ -1043,14 +1099,14 @@ export class Model extends ModelIdentity {
         if (!['update', 'retrieve'].includes(this._action)) {
             throw new ModelError(this, `cannot titles during ${this._action}`);
         }
-        return need(this.SOURCE, this).titles(this._proxy, ...args);
+        return this._hook('titles', ...args);
     }
     /** Write changes back to the source. Resolves to how many records changed. */
     async update(...args) {
         if (!['update', 'retrieve'].includes(this._action)) {
             throw new ModelError(this, `cannot update during ${this._action}`);
         }
-        return need(this.SOURCE, this).update(this._proxy, ...args);
+        return this._hook('update', ...args);
     }
     /** Remove records from the source. Resolves to how many were removed. */
     async delete(...args) {
@@ -1060,7 +1116,7 @@ export class Model extends ModelIdentity {
         if (this._action === 'retrieve' && this._mode === 'one') {
             await this.retrieve();
         }
-        return need(this.SOURCE, this).delete(this._proxy, ...args);
+        return this._hook('delete', ...args);
     }
     /** The query a source would run for an action, without running it. */
     query(action, ...args) {

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.js

@@ -13,7 +13,7 @@
  * 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 { ModelError, MultipleError, NotFoundError } from './errors.js';
 import { Source } from './source.js';
 import { Titles } from './titles.js';
 import { sorted } from './util.js';
@@ -176,12 +176,12 @@ export class RestSource extends Source {
         }
         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');
+            throw new MultipleError(model, 'more than one retrieved');
         }
         if (model._mode === 'one' && model._role !== 'child') {
             if (matches.length < 1) {
                 if (verify) {
-                    throw new ModelError(model, 'none retrieved');
+                    throw new NotFoundError(model, 'none retrieved');
                 }
                 return null;
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@relations-dil/relations",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "A simple, flexible DIL (data interface layer). Define models once, independent of backend; set the source at runtime.",
   "license": "MIT",
   "repository": {