@relations-dil/relations 0.1.0

package/dist/overscore.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Double underscore access notation.
+ *
+ * Port of the Python `overscore` library. Lets you retrieve (and store) values in
+ * multi-dimensional data using a single string, so the access path survives being
+ * passed as a function argument, a URL parameter, or a filter key.
+ *
+ * ```ts
+ * import * as overscore from '@relations-dil/relations/overscore'
+ *
+ * const data = { things: { a: { b: [{ '1': 'yep' }] } } }
+ *
+ * overscore.get(data, 'things__a__b__0____1')  // 'yep'
+ * ```
+ *
+ * All places are separated by double underscores. Extra underscores say how to read
+ * the place that follows:
+ *
+ * | Underscores | Following | Meaning              | Example  | Equivalent     |
+ * | ----------- | --------- | -------------------- | -------- | -------------- |
+ * | 2           | word      | key                  | `a__b`   | `['a']['b']`   |
+ * | 2           | number    | index                | `a__1`   | `['a'][1]`     |
+ * | 3           | number    | negative index       | `a___2`  | `['a'][-2]`    |
+ * | 4           | number    | numerical key        | `a____3` | `['a']['3']`   |
+ * | 5           | number    | negative numeric key | `a_____4`| `['a']['-4']`  |
+ */
+export declare class OverscoreError extends Error {
+    constructor(message: string);
+}
+/** A single step in a path: a string key or a numeric (possibly negative) index. */
+export type Place = string | number;
+/** A resolved path, or the double-underscored string form of one. */
+export type Path = Place[] | string;
+/**
+ * Parse double-underscored text into a list of keys and indexes.
+ *
+ * ```ts
+ * parse('a-b__0___1____2_____3')  // ['a-b', 0, -1, '2', '-3']
+ * ```
+ */
+export declare function parse(text: string): Place[];
+/**
+ * Compile a list of keys and indexes back into double-underscored text.
+ *
+ * ```ts
+ * compile(['a-b', 0, -1, '2', '-3'])  // 'a-b__0___1____2_____3'
+ * ```
+ */
+export declare function compile(path: Place[]): string;
+/** True when `data` is a plain object (the JS stand-in for a Python dict). */
+export declare function isDict(data: unknown): data is Record<string, unknown>;
+/** Whether `path` exists in `data`. */
+export declare function has(data: unknown, path: Path): boolean;
+/** The value in `data` at `path`, or `null` when it isn't there. */
+export declare function get(data: unknown, path: Path): any;
+/**
+ * Store `value` in `data` at `path`, creating the objects and arrays along the way.
+ *
+ * ```ts
+ * const data = {}
+ * set(data, 'things__a__b___2____1', 'yep')
+ * // { things: { a: { b: [{ '1': 'yep' }, null] } } }
+ * ```
+ */
+export declare function set(data: unknown, path: Path, value: unknown): void;
+//# sourceMappingURL=overscore.d.ts.map

package/dist/overscore.js

@@ -0,0 +1,226 @@
+/**
+ * Double underscore access notation.
+ *
+ * Port of the Python `overscore` library. Lets you retrieve (and store) values in
+ * multi-dimensional data using a single string, so the access path survives being
+ * passed as a function argument, a URL parameter, or a filter key.
+ *
+ * ```ts
+ * import * as overscore from '@relations-dil/relations/overscore'
+ *
+ * const data = { things: { a: { b: [{ '1': 'yep' }] } } }
+ *
+ * overscore.get(data, 'things__a__b__0____1')  // 'yep'
+ * ```
+ *
+ * All places are separated by double underscores. Extra underscores say how to read
+ * the place that follows:
+ *
+ * | Underscores | Following | Meaning              | Example  | Equivalent     |
+ * | ----------- | --------- | -------------------- | -------- | -------------- |
+ * | 2           | word      | key                  | `a__b`   | `['a']['b']`   |
+ * | 2           | number    | index                | `a__1`   | `['a'][1]`     |
+ * | 3           | number    | negative index       | `a___2`  | `['a'][-2]`    |
+ * | 4           | number    | numerical key        | `a____3` | `['a']['3']`   |
+ * | 5           | number    | negative numeric key | `a_____4`| `['a']['-4']`  |
+ */
+export class OverscoreError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'OverscoreError';
+    }
+}
+const NUMBER = /^\d+$/;
+const WORD = /^[\w-]+$/;
+function isDigit(letter) {
+    return letter >= '0' && letter <= '9';
+}
+/**
+ * Parse double-underscored text into a list of keys and indexes.
+ *
+ * ```ts
+ * parse('a-b__0___1____2_____3')  // ['a-b', 0, -1, '2', '-3']
+ * ```
+ */
+export function parse(text) {
+    let count = 0;
+    let place = [];
+    const places = [];
+    let state = 'place';
+    for (const letter of text) {
+        if (state === 'place') {
+            place.push(letter);
+            if (letter !== '_') {
+                state = 'placing';
+            }
+        }
+        else {
+            count = letter === '_' ? count + 1 : 0;
+            if (count === 2 && letter === '_') {
+                places.push(place.slice(0, -1).join(''));
+                place = [];
+                count = 0;
+                state = 'place';
+            }
+            else {
+                place.push(letter);
+            }
+        }
+    }
+    if (place.length) {
+        places.push(place.join(''));
+    }
+    const path = [];
+    for (const found of places) {
+        if (isDigit(found[0])) {
+            path.push(parseInt(found, 10));
+        }
+        else if (found[0] === '_' && found[1] !== undefined && isDigit(found[1]) && found.slice(0, 2) !== '__') {
+            path.push(-parseInt(found.slice(1), 10));
+        }
+        else if (found.slice(0, 2) === '__' && found[2] !== undefined && isDigit(found[2]) && found.slice(0, 3) !== '___') {
+            path.push(found.slice(2));
+        }
+        else if (found.slice(0, 3) === '___' && found[3] !== undefined && isDigit(found[3])) {
+            path.push(String(-parseInt(found.slice(3), 10)));
+        }
+        else {
+            path.push(found);
+        }
+    }
+    return path;
+}
+/**
+ * Compile a list of keys and indexes back into double-underscored text.
+ *
+ * ```ts
+ * compile(['a-b', 0, -1, '2', '-3'])  // 'a-b__0___1____2_____3'
+ * ```
+ */
+export function compile(path) {
+    const places = [];
+    for (const place of path) {
+        if (typeof place === 'number' && Number.isInteger(place) && place > -1) {
+            places.push(String(place));
+        }
+        else if (typeof place === 'number' && Number.isInteger(place)) {
+            places.push(`_${Math.abs(place)}`);
+        }
+        else if (typeof place === 'string' && place.length && place[0] === '-' && NUMBER.test(place.slice(1))) {
+            places.push(`___${place.slice(1)}`);
+        }
+        else if (typeof place === 'string' && NUMBER.test(place)) {
+            places.push(`__${place}`);
+        }
+        else if (typeof place === 'string' && WORD.test(place)) {
+            places.push(place);
+        }
+        else {
+            throw new OverscoreError(`cannot compile ${String(place)}`);
+        }
+    }
+    return places.join('__');
+}
+/** True when `data` is a plain object (the JS stand-in for a Python dict). */
+export function isDict(data) {
+    if (data === null || typeof data !== 'object' || Array.isArray(data)) {
+        return false;
+    }
+    const proto = Object.getPrototypeOf(data);
+    return proto === Object.prototype || proto === null;
+}
+function resolve(path) {
+    return typeof path === 'string' ? parse(path) : path;
+}
+/** Whether `path` exists in `data`. */
+export function has(data, path) {
+    let current = data;
+    for (const place of resolve(path)) {
+        if (typeof place === 'number') {
+            if (!Array.isArray(current) ||
+                (place >= 0 && current.length < place + 1) ||
+                (place < 0 && current.length < Math.abs(place))) {
+                return false;
+            }
+            current = current.at(place);
+        }
+        else {
+            if (!isDict(current) || !Object.prototype.hasOwnProperty.call(current, place)) {
+                return false;
+            }
+            current = current[place];
+        }
+    }
+    return true;
+}
+/** The value in `data` at `path`, or `null` when it isn't there. */
+export function get(data, path) {
+    let current = data;
+    for (const place of resolve(path)) {
+        if (typeof place === 'number') {
+            if (!Array.isArray(current) ||
+                (place >= 0 && current.length < place + 1) ||
+                (place < 0 && current.length < Math.abs(place))) {
+                return null;
+            }
+            current = current.at(place);
+        }
+        else {
+            if (!isDict(current) || !Object.prototype.hasOwnProperty.call(current, place)) {
+                return null;
+            }
+            current = current[place];
+        }
+    }
+    return current === undefined ? null : current;
+}
+/**
+ * Store `value` in `data` at `path`, creating the objects and arrays along the way.
+ *
+ * ```ts
+ * const data = {}
+ * set(data, 'things__a__b___2____1', 'yep')
+ * // { things: { a: { b: [{ '1': 'yep' }, null] } } }
+ * ```
+ */
+export function set(data, path, value) {
+    const places = resolve(path);
+    let current = data;
+    for (let index = 0; index < places.length; index++) {
+        const place = places[index];
+        const last = index === places.length - 1;
+        const fallback = last ? value : typeof places[index + 1] === 'string' ? {} : [];
+        if (isDict(current)) {
+            if (typeof place === 'number') {
+                throw new OverscoreError(`index ${place} invalid for object ${JSON.stringify(current)}`);
+            }
+            if (!Object.prototype.hasOwnProperty.call(current, place)) {
+                current[place] = fallback;
+            }
+        }
+        else if (Array.isArray(current)) {
+            if (typeof place === 'string') {
+                throw new OverscoreError(`key ${place} invalid for array ${JSON.stringify(current)}`);
+            }
+            while ((place >= 0 && current.length < place + 1) || (place < 0 && current.length < Math.abs(place))) {
+                current.push(null);
+            }
+            const at = place < 0 ? current.length + place : place;
+            if (current[at] === null || current[at] === undefined) {
+                current[at] = fallback;
+            }
+        }
+        else {
+            throw new OverscoreError(`cannot set ${String(place)} on ${JSON.stringify(current)}`);
+        }
+        const at = Array.isArray(current) && typeof place === 'number' && place < 0 ? current.length + place : place;
+        const holder = current;
+        if (!last) {
+            current = holder[at];
+        }
+        else {
+            holder[at] = value;
+        }
+    }
+}
+//# sourceMappingURL=overscore.js.map

package/dist/record.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Records: an ordered set of fields, and the marshalling between them and a source.
+ */
+import { Field } from './field.js';
+/** What a record is currently for. */
+export type Action = 'create' | 'retrieve' | 'update' | 'delete';
+/** An ordered, name-addressable set of fields. */
+export declare class Record {
+    /** Fields in order. */
+    _order: Field[];
+    /** Fields by name. */
+    _names: Map<string, Field>;
+    /** What's being done with this record. */
+    _action: Action | null;
+    /** Add a field at a specific position. */
+    insert(index: number, field: Field): void;
+    /** Add a field at the end. */
+    append(field: Field): void;
+    /** Number of fields. */
+    get size(): number;
+    /** Field names, in order. */
+    [Symbol.iterator](): IterableIterator<string>;
+    /** Field names, in order. */
+    keys(): string[];
+    /** The field itself, by name or position. */
+    field(key: string | number): Field | undefined;
+    /** Whether a field exists, by name or position. */
+    has(key: string | number): boolean;
+    /** An independent copy of this record and every field in it. */
+    copy(): Record;
+    /** A value, by field name, position, or double-underscored path into a field. */
+    get(key: string | number): any;
+    /** Set a value, by field name, position, or double-underscored path into a field. */
+    set(key: string | number, value: any): void;
+    /** Definitions for every field, in order. */
+    define(): globalThis.Record<string, any>[];
+    /** Set a criterion on a field, by name, position, or `name__operator`. */
+    filter(criterion: string | number, value: any): void;
+    /** Every field's value, keyed by field name. */
+    export(): globalThis.Record<string, any>;
+    /** The store name of the field an injected field lives inside. */
+    private injected;
+    /** Write every field's value for a create. */
+    create(values: globalThis.Record<string, any>): globalThis.Record<string, any>;
+    /** Whether a stored record satisfies every field's criteria. */
+    retrieve(values: globalThis.Record<string, any>): boolean;
+    /** Whether a stored record fuzzy-matches on any of the title fields. */
+    like(values: globalThis.Record<string, any>, titles: string[], like: any, parents: globalThis.Record<string, any[]>): boolean;
+    /** Load every field's value from a stored record. */
+    read(values: globalThis.Record<string, any>): void;
+    /** Write every changed field's value for an update. */
+    update(values: globalThis.Record<string, any>): globalThis.Record<string, any>;
+    /** Write every set field's value for a mass update. */
+    mass(values: globalThis.Record<string, any>): globalThis.Record<string, any>;
+    /** Write every set tie field's value for a many-to-many update. */
+    tie(values: globalThis.Record<string, any>): globalThis.Record<string, any>;
+}
+//# sourceMappingURL=record.d.ts.map

package/dist/record.js

@@ -0,0 +1,246 @@
+/**
+ * Records: an ordered set of fields, and the marshalling between them and a source.
+ */
+import * as overscore from './overscore.js';
+import { RecordError } from './errors.js';
+/** An ordered, name-addressable set of fields. */
+export class Record {
+    /** Fields in order. */
+    _order = [];
+    /** Fields by name. */
+    _names = new Map();
+    /** What's being done with this record. */
+    _action = null;
+    /** Add a field at a specific position. */
+    insert(index, field) {
+        this._order.splice(index, 0, field);
+        this._names.set(field.name, field);
+    }
+    /** Add a field at the end. */
+    append(field) {
+        this.insert(this._order.length, field);
+    }
+    /** Number of fields. */
+    get size() {
+        return this._order.length;
+    }
+    /** Field names, in order. */
+    *[Symbol.iterator]() {
+        for (const field of this._order) {
+            yield field.name;
+        }
+    }
+    /** Field names, in order. */
+    keys() {
+        return this._order.map((field) => field.name);
+    }
+    /** The field itself, by name or position. */
+    field(key) {
+        if (typeof key === 'number') {
+            return this._order[key < 0 ? this._order.length + key : key];
+        }
+        return this._names.get(key);
+    }
+    /** Whether a field exists, by name or position. */
+    has(key) {
+        if (typeof key === 'number') {
+            return key < this._order.length;
+        }
+        return this._names.has(key);
+    }
+    /** An independent copy of this record and every field in it. */
+    copy() {
+        const record = new Record();
+        record._action = this._action;
+        for (const field of this._order) {
+            record.append(field.copy());
+        }
+        return record;
+    }
+    /** A value, by field name, position, or double-underscored path into a field. */
+    get(key) {
+        if (typeof key === 'number') {
+            if (key < this._order.length) {
+                return this._order[key].value;
+            }
+            throw new RecordError(this, `unknown field '${key}'`);
+        }
+        const field = this._names.get(key);
+        if (field !== undefined) {
+            return field.value;
+        }
+        const access = overscore.parse(key);
+        const root = this._names.get(String(access[0]));
+        if (root !== undefined) {
+            return root.access(access.slice(1));
+        }
+        throw new RecordError(this, `unknown field '${key}'`);
+    }
+    /** Set a value, by field name, position, or double-underscored path into a field. */
+    set(key, value) {
+        if (typeof key === 'number') {
+            if (key < this._order.length) {
+                this._order[key].value = value;
+                return;
+            }
+            throw new RecordError(this, `unknown field '${key}'`);
+        }
+        const field = this._names.get(key);
+        if (field !== undefined) {
+            field.value = value;
+            return;
+        }
+        const apply = overscore.parse(key);
+        const root = this._names.get(String(apply[0]));
+        if (root !== undefined) {
+            root.apply(apply.slice(1), value);
+            return;
+        }
+        throw new RecordError(this, `unknown field '${key}'`);
+    }
+    /** Definitions for every field, in order. */
+    define() {
+        return this._order.map((field) => field.define());
+    }
+    /** Set a criterion on a field, by name, position, or `name__operator`. */
+    filter(criterion, value) {
+        if (typeof criterion === 'number') {
+            if (criterion < this._order.length) {
+                this._order[criterion].filter(value);
+                return;
+            }
+        }
+        else {
+            if (criterion.includes('__')) {
+                const index = criterion.indexOf('__');
+                const name = criterion.slice(0, index);
+                const operator = criterion.slice(index + 2);
+                const field = this._names.get(name);
+                if (field !== undefined) {
+                    field.filter(value, operator);
+                    return;
+                }
+            }
+            const field = this._names.get(criterion);
+            if (field !== undefined) {
+                field.filter(value);
+                return;
+            }
+        }
+        throw new RecordError(this, `unknown criterion '${criterion}'`);
+    }
+    /** Every field's value, keyed by field name. */
+    export() {
+        const values = {};
+        for (const field of this._order) {
+            values[field.name] = field.export();
+        }
+        return values;
+    }
+    /** The store name of the field an injected field lives inside. */
+    injected(field) {
+        const root = String(field.inject).split('__')[0];
+        return this._names.get(root)?.store;
+    }
+    /** Write every field's value for a create. */
+    create(values) {
+        const inject = [];
+        for (const field of this._order) {
+            if (field.inject) {
+                inject.push(field);
+            }
+            else {
+                field.create(values);
+            }
+        }
+        for (const field of inject) {
+            field.create(values[this.injected(field)]);
+        }
+        return values;
+    }
+    /** Whether a stored record satisfies every field's criteria. */
+    retrieve(values) {
+        for (const field of this._order) {
+            if (!field.retrieve(values)) {
+                return false;
+            }
+        }
+        return true;
+    }
+    /** Whether a stored record fuzzy-matches on any of the title fields. */
+    like(values, titles, like, parents) {
+        for (const title of titles) {
+            const path = overscore.parse(title);
+            const field = this._names.get(String(path[0]));
+            if (field !== undefined && field.like(values, like, parents, path.slice(1))) {
+                return true;
+            }
+        }
+        return false;
+    }
+    /** Load every field's value from a stored record. */
+    read(values) {
+        for (const field of this._order) {
+            if (field.inject) {
+                field.read(values[this.injected(field)] ?? {});
+            }
+            else {
+                field.read(values);
+            }
+        }
+    }
+    /** Write every changed field's value for an update. */
+    update(values) {
+        const inject = [];
+        for (const field of this._order) {
+            if (field.inject) {
+                inject.push(field);
+            }
+            else {
+                field.update(values);
+            }
+        }
+        for (const field of inject) {
+            if (field.delta() || field.refresh) {
+                const root = String(field.inject).split('__')[0];
+                const store = this._names.get(root)?.store;
+                if (!(store in values)) {
+                    this._names.get(root)?.write(values);
+                }
+                field.update(values[store]);
+            }
+        }
+        return values;
+    }
+    /** Write every set field's value for a mass update. */
+    mass(values) {
+        const inject = [];
+        for (const field of this._order) {
+            if (field.inject) {
+                inject.push(field);
+            }
+            else {
+                field.mass(values);
+            }
+        }
+        for (const field of inject) {
+            if (field.changed || field.refresh) {
+                const root = String(field.inject).split('__')[0];
+                const store = this._names.get(root)?.store;
+                if (!(store in values)) {
+                    this._names.get(root)?.write(values);
+                }
+                field.mass(values[store]);
+            }
+        }
+        return values;
+    }
+    /** Write every set tie field's value for a many-to-many update. */
+    tie(values) {
+        for (const field of this._order) {
+            field.tie(values);
+        }
+        return values;
+    }
+}
+//# sourceMappingURL=record.js.map

package/dist/registry.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The global source registry.
+ *
+ * A model names its source with a string. Which actual source that string refers to is
+ * decided at runtime, by whatever registers itself under that name. That indirection is
+ * the whole point of relations: the same model runs against a database in one service
+ * and against a REST API in another.
+ */
+/** Anything registered as a source. Kept loose to avoid a circular import. */
+export interface Registered {
+    name: string;
+    [member: string]: any;
+}
+/** Every registered source, keyed by name. */
+export declare const SOURCES: Map<string, Registered>;
+/** Register a source under its name, replacing any source already there. */
+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;
+/** Forget a source. Mostly useful between tests. */
+export declare function unregister(name: string): boolean;
+/** Forget every source. Mostly useful between tests. */
+export declare function clear(): void;
+//# sourceMappingURL=registry.d.ts.map

package/dist/registry.js

@@ -0,0 +1,27 @@
+/**
+ * The global source registry.
+ *
+ * A model names its source with a string. Which actual source that string refers to is
+ * decided at runtime, by whatever registers itself under that name. That indirection is
+ * the whole point of relations: the same model runs against a database in one service
+ * and against a REST API in another.
+ */
+/** Every registered source, keyed by name. */
+export const SOURCES = new Map();
+/** Register a source under its name, replacing any source already there. */
+export function register(source) {
+    SOURCES.set(source.name, source);
+}
+/** The source registered under a name, or `undefined`. */
+export function source(name) {
+    return name === null || name === undefined ? undefined : SOURCES.get(name);
+}
+/** Forget a source. Mostly useful between tests. */
+export function unregister(name) {
+    return SOURCES.delete(name);
+}
+/** Forget every source. Mostly useful between tests. */
+export function clear() {
+    SOURCES.clear();
+}
+//# sourceMappingURL=registry.js.map