@relations-dil/relations 0.1.0

package/dist/dynamic.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Models from data.
+ *
+ * `identity.define()` turns a model class into a plain, backend-neutral object. This
+ * module goes the other way: it turns that object back into a working model class. The
+ * round trip means a set of models can be written as data - JSON, YAML, a database row,
+ * a form in a UI - saved, shipped, and loaded somewhere that has never seen the code.
+ *
+ * ```ts
+ * import { modelsFrom } from '@relations-dil/relations'
+ * import { parse } from 'yaml'          // any YAML parser; relations has no opinion
+ *
+ * const app = parse(await readFile('app.yaml', 'utf8'))
+ * const { Unit, Test } = modelsFrom(app.models, { relations: app.relations })
+ *
+ * await new Unit('yep').create()
+ * ```
+ *
+ * The YAML for that looks like:
+ *
+ * ```yaml
+ * models:
+ *   unit:
+ *     source: example
+ *     name: unit
+ *     fields:
+ *       - {kind: int,  name: id,   store: id,   auto: true}
+ *       - {kind: str,  name: name, store: name, none: false}
+ *   test:
+ *     source: example
+ *     name: test
+ *     fields:
+ *       - {kind: int, name: id,      store: id, auto: true}
+ *       - {kind: int, name: unit_id, store: unit_id}
+ *       - {kind: str, name: name,    store: name, none: false}
+ * relations:
+ *   - {kind: OneToMany, parent: unit, child: test}
+ * ```
+ */
+import { type ModelClass } from './model.js';
+import { type ManyToManyOptions, type OneToOptions } from './relation.js';
+/** A model definition, as `identity.define()` emits it. */
+export interface Definition {
+    /** Name of the source the model lives in. */
+    source?: string;
+    /** Name of the model in the source. */
+    name: string;
+    /** Human-facing title. */
+    title?: string;
+    /** Whether this model is a many-to-many tie table. */
+    tie?: boolean;
+    /** Field definitions, in order. */
+    fields: globalThis.Record<string, any>[];
+    /** Which field is the id. */
+    id?: string | null;
+    /** Which fields make up a title. Optional; derived when absent. */
+    titles?: string | string[];
+    /** Which fields to show in a listing. Optional; derived when absent. */
+    list?: string | string[];
+    /** Unique indexes. */
+    unique?: globalThis.Record<string, string[]>;
+    /** Regular indexes. */
+    index?: globalThis.Record<string, string[]>;
+    /** Default sort order. */
+    order?: string | string[];
+    /** Default chunk size. */
+    chunk?: number;
+}
+/** A relation between two definitions, by model name. */
+export interface RelationDefinition {
+    /** Which kind of relation. */
+    kind: 'OneToMany' | 'OneToOne' | 'ManyToMany';
+    /** The one side, for a one-to-* relation. */
+    parent?: string;
+    /** The many side, for a one-to-* relation. */
+    child?: string;
+    /** The first side of a many-to-many. */
+    sister?: string;
+    /** The second side of a many-to-many. */
+    brother?: string;
+    /** The joining model of a many-to-many. */
+    tie?: string;
+    /** Anything the relation lets you spell out instead of inferring. */
+    options?: OneToOptions & ManyToManyOptions;
+}
+/** What `modelsFrom` gives you back. */
+export type Built = globalThis.Record<string, ModelClass>;
+/**
+ * A model class built from a definition. Extend the result, or use it as it is.
+ *
+ * ```ts
+ * const Unit = modelFrom({
+ *   source: 'example',
+ *   name: 'unit',
+ *   fields: [
+ *     { kind: 'int', name: 'id', store: 'id', auto: true },
+ *     { kind: 'str', name: 'name', store: 'name', none: false }
+ *   ],
+ *   id: 'id',
+ *   unique: { name: ['name'] }
+ * })
+ * ```
+ */
+export declare function modelFrom(definition: Definition, base?: ModelClass): ModelClass;
+/**
+ * Every model in a set of definitions, wired up. Pass `relations` to connect them; the
+ * names in each relation refer to the keys of `definitions`, or to a definition's `name`.
+ *
+ * ```ts
+ * const { unit, test } = modelsFrom(
+ *   { unit: unitDefinition, test: testDefinition },
+ *   { relations: [{ kind: 'OneToMany', parent: 'unit', child: 'test' }] }
+ * )
+ * ```
+ */
+export declare function modelsFrom(definitions: globalThis.Record<string, Definition> | Definition[], options?: {
+    relations?: RelationDefinition[];
+    base?: ModelClass;
+}): Built;
+/** The definitions for a set of model classes, keyed by model name - the way back out. */
+export declare function definitionsOf(models: ModelClass[]): globalThis.Record<string, Definition>;
+//# sourceMappingURL=dynamic.d.ts.map

package/dist/dynamic.js

@@ -0,0 +1,164 @@
+/**
+ * Models from data.
+ *
+ * `identity.define()` turns a model class into a plain, backend-neutral object. This
+ * module goes the other way: it turns that object back into a working model class. The
+ * round trip means a set of models can be written as data - JSON, YAML, a database row,
+ * a form in a UI - saved, shipped, and loaded somewhere that has never seen the code.
+ *
+ * ```ts
+ * import { modelsFrom } from '@relations-dil/relations'
+ * import { parse } from 'yaml'          // any YAML parser; relations has no opinion
+ *
+ * const app = parse(await readFile('app.yaml', 'utf8'))
+ * const { Unit, Test } = modelsFrom(app.models, { relations: app.relations })
+ *
+ * await new Unit('yep').create()
+ * ```
+ *
+ * The YAML for that looks like:
+ *
+ * ```yaml
+ * models:
+ *   unit:
+ *     source: example
+ *     name: unit
+ *     fields:
+ *       - {kind: int,  name: id,   store: id,   auto: true}
+ *       - {kind: str,  name: name, store: name, none: false}
+ *   test:
+ *     source: example
+ *     name: test
+ *     fields:
+ *       - {kind: int, name: id,      store: id, auto: true}
+ *       - {kind: int, name: unit_id, store: unit_id}
+ *       - {kind: str, name: name,    store: name, none: false}
+ * relations:
+ *   - {kind: OneToMany, parent: unit, child: test}
+ * ```
+ */
+import { ModelError } from './errors.js';
+import { kindOf, str } from './kinds.js';
+import { Model } from './model.js';
+import { ManyToMany, OneToMany, OneToOne } from './relation.js';
+function fieldFrom(definition) {
+    const { kind: kindName, name, ...options } = definition;
+    const kind = kindOf(kindName);
+    if (kind === undefined) {
+        throw new ModelError(null, `unknown kind '${kindName}' for field '${name}' - expected one of bool, int, float, str, set, list, dict`);
+    }
+    if (options.extract) {
+        options.extract = Object.fromEntries(Object.entries(options.extract).map(([path, each]) => [
+            path,
+            kindOf(each) ?? str
+        ]));
+    }
+    return [name, { kind, ...options }];
+}
+/**
+ * A model class built from a definition. Extend the result, or use it as it is.
+ *
+ * ```ts
+ * const Unit = modelFrom({
+ *   source: 'example',
+ *   name: 'unit',
+ *   fields: [
+ *     { kind: 'int', name: 'id', store: 'id', auto: true },
+ *     { kind: 'str', name: 'name', store: 'name', none: false }
+ *   ],
+ *   id: 'id',
+ *   unique: { name: ['name'] }
+ * })
+ * ```
+ */
+export function modelFrom(definition, base = Model) {
+    const spec = {};
+    for (const field of definition.fields ?? []) {
+        const [name, made] = fieldFrom(field);
+        spec[name] = made;
+    }
+    class Defined extends base {
+        static fields = spec;
+    }
+    const cls = Defined;
+    cls.store = definition.name;
+    cls.source = definition.source ?? base.source;
+    cls.id = definition.id ?? null;
+    if (definition.title !== undefined) {
+        cls.title = definition.title;
+    }
+    if (definition.titles !== undefined) {
+        cls.titles = definition.titles;
+    }
+    if (definition.list !== undefined) {
+        cls.list = definition.list;
+    }
+    if (definition.unique !== undefined) {
+        cls.unique = definition.unique;
+    }
+    if (definition.index !== undefined) {
+        cls.index = definition.index;
+    }
+    if (definition.order !== undefined) {
+        cls.order = definition.order;
+    }
+    if (definition.chunk !== undefined) {
+        cls.chunk = definition.chunk;
+    }
+    if (definition.tie !== undefined) {
+        cls.TIE = definition.tie;
+    }
+    Object.defineProperty(cls, 'name', { value: definition.title ?? definition.name, configurable: true });
+    return cls;
+}
+/**
+ * Every model in a set of definitions, wired up. Pass `relations` to connect them; the
+ * names in each relation refer to the keys of `definitions`, or to a definition's `name`.
+ *
+ * ```ts
+ * const { unit, test } = modelsFrom(
+ *   { unit: unitDefinition, test: testDefinition },
+ *   { relations: [{ kind: 'OneToMany', parent: 'unit', child: 'test' }] }
+ * )
+ * ```
+ */
+export function modelsFrom(definitions, options = {}) {
+    const entries = Array.isArray(definitions)
+        ? definitions.map((definition) => [definition.name, definition])
+        : Object.entries(definitions).map(([key, definition]) => [definition.name ?? key, definition]);
+    const built = {};
+    for (const [name, definition] of entries) {
+        built[name] = modelFrom({ ...definition, name: definition.name ?? name }, options.base);
+    }
+    const need = (name, relation) => {
+        if (name === undefined || built[name] === undefined) {
+            throw new ModelError(null, `relation ${relation.kind} refers to unknown model '${name}'`);
+        }
+        return built[name];
+    };
+    for (const relation of options.relations ?? []) {
+        if (relation.kind === 'OneToMany') {
+            new OneToMany(need(relation.parent, relation), need(relation.child, relation), relation.options);
+        }
+        else if (relation.kind === 'OneToOne') {
+            new OneToOne(need(relation.parent, relation), need(relation.child, relation), relation.options);
+        }
+        else if (relation.kind === 'ManyToMany') {
+            new ManyToMany(need(relation.sister, relation), need(relation.brother, relation), need(relation.tie, relation), relation.options);
+        }
+        else {
+            throw new ModelError(null, `unknown relation kind '${relation.kind}'`);
+        }
+    }
+    return built;
+}
+/** The definitions for a set of model classes, keyed by model name - the way back out. */
+export function definitionsOf(models) {
+    const definitions = {};
+    for (const model of models) {
+        const definition = model.thy().define();
+        definitions[definition.name] = definition;
+    }
+    return definitions;
+}
+//# sourceMappingURL=dynamic.js.map

package/dist/errors.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Error classes. Each one carries the thing that went wrong, not just a message,
+ * so callers can branch on the field or model involved.
+ */
+/** Something invalid about a field's definition, value, or criteria. */
+export declare class FieldError extends Error {
+    field: any;
+    constructor(field: any, message: string);
+}
+/** Something invalid about a record - usually an unknown field name. */
+export declare class RecordError extends Error {
+    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 {
+    /** The model the error is about. */
+    model: any;
+    /** The message on its own, without the model name in front. */
+    detail: string;
+    constructor(model: any, message: string);
+}
+/** A unique index was violated. Sources throw this and roll back. */
+export declare class UniqueError extends ModelError {
+    constructor(model: any, message: string);
+}
+/** Something went wrong diffing or applying migrations. */
+export declare class MigrationsError extends Error {
+    constructor(message: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.js

@@ -0,0 +1,50 @@
+/**
+ * Error classes. Each one carries the thing that went wrong, not just a message,
+ * so callers can branch on the field or model involved.
+ */
+/** Something invalid about a field's definition, value, or criteria. */
+export class FieldError extends Error {
+    field;
+    constructor(field, message) {
+        super(message);
+        this.name = 'FieldError';
+        this.field = field;
+    }
+}
+/** Something invalid about a record - usually an unknown field name. */
+export class RecordError extends Error {
+    record;
+    constructor(record, message) {
+        super(message);
+        this.name = 'RecordError';
+        this.record = record;
+    }
+}
+/** Something invalid about a model, its identity, or the action being attempted. */
+export class ModelError extends Error {
+    /** The model the error is about. */
+    model;
+    /** The message on its own, without the model name in front. */
+    detail;
+    constructor(model, message) {
+        super(`${model?.NAME ?? 'model'}: ${message}`);
+        this.name = 'ModelError';
+        this.model = model;
+        this.detail = message;
+    }
+}
+/** A unique index was violated. Sources throw this and roll back. */
+export class UniqueError extends ModelError {
+    constructor(model, message) {
+        super(model, message);
+        this.name = 'UniqueError';
+    }
+}
+/** Something went wrong diffing or applying migrations. */
+export class MigrationsError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'MigrationsError';
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/field.d.ts

@@ -0,0 +1,157 @@
+/**
+ * Fields: the typed, validating, filterable units a record is made of.
+ */
+import * as overscore from './overscore.js';
+import { type FieldKind, type Kind } from './kinds.js';
+/** How values map onto a class kind's properties, or a function that writes them. */
+export type Attr = string | string[] | Record<string, string> | ((values: Record<string, any>, value: any) => void);
+/** How a stored value maps back onto a class kind's constructor. */
+export type Init = string | string[] | Record<string, string> | ((value: any) => any);
+/** How a value is checked beyond its kind: a regular expression or a predicate. */
+export type Validation = string | RegExp | ((value: any) => boolean);
+/** Everything you can say about a field beyond its kind. */
+export interface FieldOptions {
+    /** Name in the model. Set for you from the key in `static fields`. */
+    name?: string;
+    /** Name used when reading and writing to the source. Defaults to `name`. Set `false` to never store. */
+    store?: string | false;
+    /** Whether this field carries a many-to-many tie. Managed by relations. */
+    tied?: boolean;
+    /** How to flatten a class-kind value into storable values. Required for class kinds. */
+    attr?: Attr;
+    /** How to build a class-kind value back from stored values. Defaults to `attr`. */
+    init?: Init;
+    /** Which attributes make up this field's titles. Defaults to `attr`. */
+    titles?: string | string[];
+    /** Interior values to pull out into their own stored columns, keyed by path. */
+    extract?: string | string[] | Record<string, Kind>;
+    /** Store this field inside another list or dict field, at the given path. */
+    inject?: string;
+    /** Default value, or a function returning one. */
+    default?: any;
+    /** Whether null is allowed. Inferred when not set. */
+    none?: boolean;
+    /** The complete set of allowed values. */
+    options?: any[];
+    /** A regular expression or predicate the value must satisfy. */
+    validation?: Validation;
+    /** Length of the value, for sources that need it. */
+    length?: number;
+    /** How to format the value, one entry per title. */
+    format?: any;
+    /** Whether the field can't be written by the caller. */
+    readonly?: boolean;
+    /** Whether the source generates this value (an auto increment id, say). */
+    auto?: boolean;
+    /** Whether to reset to the default on update when untouched. */
+    refresh?: boolean;
+    /** Anything else a source wants to hang off the field. */
+    [option: string]: any;
+}
+/** Which comparison operators exist, and whether each takes multiple values. */
+export declare const OPERATORS: Record<string, boolean>;
+/**
+ * Names a field can't have, because the model already uses them. Use `store` when the
+ * source column really is called one of these.
+ */
+export declare const RESERVED: string[];
+/**
+ * A single typed value on a model, with everything needed to validate it, filter on it,
+ * and move it in and out of a source.
+ */
+export declare class Field {
+    /** Extra attributes a source hung off this field. */
+    [option: string]: any;
+    /** Data kind to cast values as, or validate against. */
+    kind: FieldKind;
+    /** Name used in models. */
+    private _name;
+    /** Name used when reading and writing. `false` means never stored. */
+    store: string | false | null;
+    /** Whether this field is used for a many-to-many tie. */
+    tied: boolean | null;
+    /** Attributes to store, for class kinds. */
+    attr: Record<string, string> | ((values: Record<string, any>, value: any) => void) | null;
+    /** Attributes to construct with, for class kinds. */
+    init: Record<string, string> | ((value: any) => any) | null;
+    /** Attributes that make up the titles. */
+    titles: string[] | null;
+    /** Interior values to pull out into their own stored columns. */
+    extract: Record<string, Kind> | null;
+    /** Path in another field to store this value at. */
+    inject: string | null;
+    /** Default value, or a factory for one. */
+    default: any;
+    /** Whether null is allowed. */
+    none: boolean;
+    /** What `none` was before it got inferred. */
+    _none: boolean | null;
+    /** The complete set of allowed values. */
+    options: any[] | null;
+    /** A regular expression or predicate. */
+    validation: Validation | null;
+    /** Length of the value. */
+    length: number | null;
+    /** Formatting instructions, one per title. */
+    format: any[] | null;
+    /** Whether the caller may write this field. */
+    readonly: boolean | null;
+    /** Whether the source generates the value. */
+    auto: boolean | null;
+    /** Whether to reset to the default on an untouched update. */
+    refresh: boolean | null;
+    /** Current value. */
+    private _value;
+    /** Value as last read from or written to the source, in exported form. */
+    original: any;
+    /** Criteria to search by, keyed by criterion. */
+    criteria: Record<string, any> | null;
+    /** Whether the value has been set since the record was built. */
+    changed: boolean | null;
+    constructor(kind: FieldKind, options?: FieldOptions | boolean | null);
+    /** Name used in models. Setting it validates the name and fills in `store`. */
+    get name(): string | null;
+    set name(value: string | null);
+    /** Current value. Setting it validates and casts, and marks the field changed. */
+    get value(): any;
+    set value(value: any);
+    /** Set the value without marking the field changed. */
+    load(value: any): void;
+    /** Whether a value is already of this field's kind. */
+    private check;
+    /** An independent copy, used when a model builds a record from its fields. */
+    copy(): Field;
+    /** The definition of this field, for schemas and migrations. */
+    define(): Record<string, any>;
+    /** The valid form of a value, throwing when it can't be made valid. */
+    valid(value: any): any;
+    /** Add a criterion to this field's criteria. */
+    filter(value: any, criterion?: string): void;
+    /** The storable form of this field's value. */
+    export(): any;
+    /** Store a value at a path inside this field. */
+    apply(path: overscore.Path, value: any): void;
+    /** Read the value at a path inside this field. */
+    access(path: overscore.Path): any;
+    /** Whether the value differs from what was last read or written. */
+    delta(): boolean;
+    /** Write this field's value into a values object for storage. */
+    write(values: Record<string, any>): void;
+    /** Write this field's value for a create. */
+    create(values: Record<string, any>): void;
+    /** Whether a stored record satisfies this field's criteria. */
+    retrieve(values: Record<string, any>): boolean;
+    /** Whether a stored record matches a fuzzy `like`, or is one of a parent's matches. */
+    like(values: Record<string, any>, like: any, parents: Record<string, any[]>, path?: overscore.Path): boolean;
+    /** Load this field's value from a stored record. */
+    read(values: Record<string, any>): void;
+    /** The title values for this field, optionally at a path. */
+    title(path?: overscore.Path): any[];
+    /** Write this field's value for an update, if it changed. */
+    update(values: Record<string, any>): void;
+    /** Write this field's value for a mass update, if it was set. */
+    mass(values: Record<string, any>): void;
+    /** Write this field's value for a many-to-many tie update, if it was set. */
+    tie(values: Record<string, any>): void;
+}
+//# sourceMappingURL=field.d.ts.map