@relations-dil/relations 0.1.0

package/dist/source.js

@@ -0,0 +1,409 @@
+/**
+ * Sources: the abstract backend.
+ *
+ * Everything that actually stores data implements this. The methods that touch storage
+ * are async, because in JavaScript anything that talks to a database, a socket, or a
+ * file has to be. Everything else - definitions, migrations, query building - is plain
+ * synchronous work on structures already in memory.
+ */
+import { ModelError } from './errors.js';
+import { register } from './registry.js';
+/**
+ * Base source. Subclass it, give it a name, and register happens for you.
+ *
+ * ```ts
+ * class MySource extends Source {
+ *   async create(model) { ... }
+ * }
+ *
+ * new MySource('example')   // models with `static source = 'example'` now use it
+ * ```
+ */
+export class Source {
+    /** What kind of source this is, used to namespace migration files. */
+    static KIND = null;
+    /** The name models refer to this source by. */
+    name;
+    constructor(name, options = {}) {
+        this.name = name;
+        for (const [option, value] of Object.entries(options)) {
+            this[option] = value;
+        }
+        register(this);
+    }
+    /** What kind of source this is. */
+    get KIND() {
+        return this.constructor.KIND;
+    }
+    /** Give an object an attribute if it hasn't got one. */
+    ensureAttribute(item, attribute, value = null) {
+        if (attribute in item) {
+            return;
+        }
+        item[attribute] = value;
+    }
+    // ------------------------------------------------------------------ init
+    /** Prepare a field for this source. */
+    fieldInit(field) { }
+    /** Prepare every field in a record. */
+    recordInit(record) {
+        for (const field of record._order) {
+            this.fieldInit(field);
+        }
+    }
+    /** Prepare a model. Called once per model identity. */
+    init(model) {
+        this.recordInit(model._fields);
+    }
+    // ------------------------------------------------------------------ definitions
+    /** Turn a field definition into whatever this source needs. */
+    fieldDefine(field, ...args) { }
+    /** Turn every field definition in a record. */
+    recordDefine(record, ...args) {
+        for (const field of record) {
+            this.fieldDefine(field, ...args);
+        }
+    }
+    /** Turn a model definition into whatever this source needs. */
+    define(model, ...args) { }
+    // ------------------------------------------------------------------ migrations
+    /** Add a field. */
+    fieldAdd(migration, ...args) { }
+    /** Remove a field. */
+    fieldRemove(definition, ...args) { }
+    /** Change a field. */
+    fieldChange(definition, migration, ...args) { }
+    /** Apply a record's worth of field changes. */
+    recordChange(definition, migration, ...args) {
+        for (const add of migration.add ?? []) {
+            this.fieldAdd(add, ...args);
+        }
+        for (const remove of migration.remove ?? []) {
+            this.fieldRemove(lookup(remove, definition), ...args);
+        }
+        for (const field of definition) {
+            if (field.name in (migration.change ?? {})) {
+                this.fieldChange(field, migration.change[field.name], ...args);
+            }
+        }
+    }
+    /** Add a model. */
+    modelAdd(migration) { }
+    /** Remove a model. */
+    modelRemove(definition) { }
+    /** Change a model. */
+    modelChange(definition, migration) { }
+    // ------------------------------------------------------------------ create
+    /** Prepare a field for a create. */
+    createField(field, ...args) { }
+    /** Prepare every field in a record for a create. */
+    createRecord(record, ...args) {
+        for (const field of record._order) {
+            this.createField(field, ...args);
+        }
+    }
+    /** The query that would create these records. */
+    createQuery(model, ...args) {
+        return undefined;
+    }
+    /** Whether any tie records need writing. */
+    static hasTies(model, data) {
+        const values = data ?? model;
+        for (const relation of Object.values(model.SISTERS)) {
+            if (relation.brotherSisterRef in values && filled(values[relation.brotherSisterRef])) {
+                return true;
+            }
+        }
+        for (const relation of Object.values(model.BROTHERS)) {
+            if (relation.sisterBrotherRef in values && filled(values[relation.sisterBrotherRef])) {
+                return true;
+            }
+        }
+        return false;
+    }
+    /** Write the tie records for a many-to-many. */
+    static async createTies(model, data, ids) {
+        const values = data ?? model;
+        let keys = ids ?? values[model._id];
+        if (!Array.isArray(keys)) {
+            keys = [keys];
+        }
+        const write = async (relation, ref, keyRef, valueRef) => {
+            if (!(ref in values)) {
+                return;
+            }
+            const holder = values;
+            const records = [];
+            for (const key of keys) {
+                for (const value of holder[ref] ?? []) {
+                    records.push({ [keyRef]: key, [valueRef]: value });
+                }
+            }
+            if (records.length) {
+                await new relation.Tie(records).create();
+            }
+        };
+        for (const relation of Object.values(model.SISTERS)) {
+            await write(relation, relation.brotherSisterRef, relation.tieBrotherRef, relation.tieSisterRef);
+        }
+        for (const relation of Object.values(model.BROTHERS)) {
+            await write(relation, relation.sisterBrotherRef, relation.tieSisterRef, relation.tieBrotherRef);
+        }
+    }
+    /** Write records. Subclasses do the actual storing and call this first. */
+    async create(model, ...args) {
+        if (model._bulk && Source.hasTies(model)) {
+            throw new ModelError(model, 'cannot create ties in bulk mode');
+        }
+    }
+    // ------------------------------------------------------------------ retrieve
+    /** Prepare a field for a retrieve. */
+    retrieveField(field, ...args) { }
+    /** Prepare every field in a record for a retrieve. */
+    retrieveRecord(record, ...args) {
+        for (const field of record._order) {
+            this.retrieveField(field, ...args);
+        }
+    }
+    /** The ids on one side of a tie that match a set operator on the other. */
+    static async tieIds(Tie, queryRef, resultRef, operator, values) {
+        const wanted = new Set(values instanceof Set ? values : Array.isArray(values) ? values : [values]);
+        const ties = await Tie.many({ [`${queryRef}__in`]: [...wanted] }).retrieve();
+        const results = ties[resultRef];
+        const queries = ties[queryRef];
+        // "all" wants every requested value present, so group by the model side and
+        // require the distinct match count to equal the de-duplicated request size.
+        if (operator === 'all') {
+            const matched = new Map();
+            results.forEach((result, index) => {
+                if (!matched.has(result)) {
+                    matched.set(result, new Set());
+                }
+                matched.get(result)?.add(queries[index]);
+            });
+            const found = new Set();
+            for (const [result, seen] of matched) {
+                if (seen.size === wanted.size) {
+                    found.add(result);
+                }
+            }
+            return found;
+        }
+        // has, any, eq: tied to at least one of the requested values.
+        return new Set(results);
+    }
+    /**
+     * The ids tied to a sibling matching field criteria, for filters like
+     * `{brother__name: 'Tom'}`. A model matches when it's tied to any such sibling.
+     */
+    static async attrIds(relation, side, criteria) {
+        const Sibling = side === 'sister' ? relation.Sister : relation.Brother;
+        const siblingId = side === 'sister' ? relation.sisterId : relation.brotherId;
+        const queryRef = side === 'sister' ? relation.tieSisterRef : relation.tieBrotherRef;
+        const resultRef = side === 'sister' ? relation.tieBrotherRef : relation.tieSisterRef;
+        const siblings = await Sibling.many(criteria).retrieve();
+        const siblingIds = siblings[siblingId];
+        if (!siblingIds.length) {
+            return new Set();
+        }
+        return Source.tieIds(relation.Tie, queryRef, resultRef, 'any', siblingIds);
+    }
+    /**
+     * Resolve tie criteria into plain id filters by walking the tie model. Handles both
+     * tie-id criteria (`{brother_id__has: [...]}`) and sibling-attribute criteria
+     * (`{brother__name: 'Tom'}`).
+     */
+    static async collateTies(model) {
+        if (!Object.keys(model.SISTERS).length && !Object.keys(model.BROTHERS).length) {
+            return;
+        }
+        let include = null;
+        const exclude = new Set();
+        let any = false;
+        const sides = [
+            ...Object.values(model.SISTERS).map((relation) => [relation, relation.brotherSisterRef, relation.tieSisterRef, relation.tieBrotherRef]),
+            ...Object.values(model.BROTHERS).map((relation) => [relation, relation.sisterBrotherRef, relation.tieBrotherRef, relation.tieSisterRef])
+        ];
+        for (const [relation, fieldRef, queryRef, resultRef] of sides) {
+            const field = model._record?.field(fieldRef);
+            if (!field?.criteria) {
+                continue;
+            }
+            any = true;
+            for (const [criterion, values] of Object.entries(field.criteria)) {
+                const negate = criterion.startsWith('not_');
+                const operator = negate ? criterion.slice(4) : criterion;
+                const matched = await Source.tieIds(relation.Tie, queryRef, resultRef, operator, values);
+                if (negate) {
+                    for (const id of matched) {
+                        exclude.add(id);
+                    }
+                }
+                else {
+                    include = include === null ? matched : intersect(include, matched);
+                }
+            }
+            field.criteria = {};
+        }
+        for (const [name, criteria] of Object.entries(model._ties)) {
+            any = true;
+            const relation = name in model.SISTERS ? model.SISTERS[name] : model.BROTHERS[name];
+            const side = name in model.SISTERS ? 'sister' : 'brother';
+            const matched = await Source.attrIds(relation, side, criteria);
+            include = include === null ? matched : intersect(include, matched);
+        }
+        model._ties = {};
+        if (!any) {
+            return;
+        }
+        if (include !== null) {
+            model._record?.filter(`${model._id}__in`, [...include]);
+        }
+        if (exclude.size) {
+            model._record?.filter(`${model._id}__not_in`, [...exclude]);
+        }
+    }
+    /** Fill in the tie fields on retrieved records. */
+    static async retrieveTies(model) {
+        for (const retrieved of model._each()) {
+            const holder = retrieved;
+            for (const relation of Object.values(model.SISTERS)) {
+                const ties = await relation.Tie
+                    .many({ [relation.tieBrotherRef]: holder[relation.brotherId] })
+                    .retrieve();
+                holder[relation.brotherSisterRef] = ties[relation.tieSisterRef];
+            }
+            for (const relation of Object.values(model.BROTHERS)) {
+                const ties = await relation.Tie
+                    .many({ [relation.tieSisterRef]: holder[relation.sisterId] })
+                    .retrieve();
+                holder[relation.sisterBrotherRef] = ties[relation.tieBrotherRef];
+            }
+        }
+    }
+    /** The query that would count matching records. */
+    countQuery(model, ...args) {
+        return undefined;
+    }
+    /** Count matching records. Subclasses do the counting and call this first. */
+    async count(model, ...args) {
+        await Source.collateTies(model);
+    }
+    /** The query that would retrieve matching records. */
+    retrieveQuery(model, ...args) {
+        return undefined;
+    }
+    /** Read records. Subclasses do the reading and call this first. */
+    async retrieve(model, verify = true, ...args) {
+        await Source.collateTies(model);
+    }
+    // ------------------------------------------------------------------ titles
+    /** The query that would retrieve titles. */
+    titlesQuery(model, ...args) {
+        return undefined;
+    }
+    /** Titles for matching records. Subclasses build them and call this first. */
+    async titles(model, ...args) {
+        if (model._action === 'retrieve') {
+            await Source.collateTies(model);
+        }
+    }
+    // ------------------------------------------------------------------ update
+    /** Prepare a field for an update. */
+    updateField(field, ...args) { }
+    /** Prepare every field in a record for an update. */
+    updateRecord(record, ...args) {
+        for (const field of record._order) {
+            this.updateField(field, ...args);
+        }
+    }
+    /** Prepare a field for a mass update. */
+    fieldMass(field, ...args) { }
+    /** Prepare every field in a record for a mass update. */
+    recordMass(record, ...args) {
+        for (const field of record._order) {
+            this.fieldMass(field, ...args);
+        }
+    }
+    /** The query that would update records. */
+    updateQuery(model, ...args) {
+        return undefined;
+    }
+    /** Write changes. Resolves to how many records changed. */
+    async update(model, ...args) {
+        return 0;
+    }
+    // ------------------------------------------------------------------ delete
+    /** Prepare a field for a delete. */
+    deleteField(field, ...args) { }
+    /** Prepare every field in a record for a delete. */
+    deleteRecord(record, ...args) {
+        for (const field of record._order) {
+            this.deleteField(field, ...args);
+        }
+    }
+    /** The query that would delete records. */
+    deleteQuery(model, ...args) {
+        return undefined;
+    }
+    /** Remove the tie records for a many-to-many. */
+    static async deleteTies(model, ids) {
+        let keys = ids ?? model[model._id];
+        if (!Array.isArray(keys)) {
+            keys = [keys];
+        }
+        for (const relation of Object.values(model.SISTERS)) {
+            await relation.Tie.many({ [`${relation.tieBrotherRef}__in`]: keys }).delete();
+        }
+        for (const relation of Object.values(model.BROTHERS)) {
+            await relation.Tie.many({ [`${relation.tieSisterRef}__in`]: keys }).delete();
+        }
+    }
+    /** Remove records. Resolves to how many were removed. */
+    async delete(model, ...args) {
+        return 0;
+    }
+    // ------------------------------------------------------------------ files
+    /** Convert a general definition file into a source-specific one. */
+    async definition(filePath, sourcePath) { }
+    /** Convert a general migration file into a source-specific one. */
+    async migration(filePath, sourcePath) { }
+    /** Run a command or commands against the source. */
+    async execute(commands) { }
+    /** The migration pairs available for this source. */
+    async list(sourcePath) {
+        return {};
+    }
+    /** Load a definition or migration file into the source. */
+    async load(filePath) { }
+    /** Bring the source up to date with everything in a migration directory. */
+    async migrate(sourcePath) {
+        return false;
+    }
+}
+/** A field definition by name. */
+export function lookup(name, fields) {
+    for (const field of fields) {
+        if (name === field.name) {
+            return field;
+        }
+    }
+    return null;
+}
+/** Truthy the way Python is: an empty Set, array or object counts as nothing. */
+function filled(value) {
+    if (value instanceof Set || value instanceof Map) {
+        return value.size > 0;
+    }
+    if (Array.isArray(value)) {
+        return value.length > 0;
+    }
+    if (value && typeof value === 'object') {
+        return Object.keys(value).length > 0;
+    }
+    return Boolean(value);
+}
+function intersect(first, second) {
+    return new Set([...first].filter((item) => second.has(item)));
+}
+//# sourceMappingURL=source.js.map

package/dist/titles.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Titles: the human-readable label for a record, assembled from its title fields and,
+ * where a title field points at a parent, from that parent's titles too.
+ */
+import type { Model } from './model.js';
+/** Titles for a set of records, keyed by id, with the ids kept in retrieval order. */
+export declare class Titles {
+    /** Name of the id field the titles are keyed by. */
+    id: string;
+    /** Fields that make up a title. */
+    fields: string[];
+    /** Ids, in order. */
+    ids: any[];
+    /** Title values, keyed by id. */
+    titles: Map<any, any[]>;
+    /** Format instructions, one per title value. */
+    format: any[];
+    /** Parent titles, for title fields that point at another model. */
+    parents: globalThis.Record<string, Titles>;
+    private constructor();
+    /**
+     * Build titles for a model. Async because a title field pointing at a parent has to
+     * fetch that parent's titles first.
+     */
+    static build(model: Model): Promise<Titles>;
+    /** How many titles there are. */
+    get size(): number;
+    /** Whether there's a title for an id. */
+    has(id: any): boolean;
+    /** The title values for an id. */
+    get(id: any): any[] | undefined;
+    /** Set the title values for an id. */
+    set(id: any, value: any[]): void;
+    /** Forget an id. */
+    delete(id: any): void;
+    /** Ids, in order. */
+    [Symbol.iterator](): IterableIterator<any>;
+    /** Add a record's title. */
+    add(model: Model): void;
+    /** Plain object form, for serialising. */
+    toJSON(): globalThis.Record<string, any>;
+}
+//# sourceMappingURL=titles.d.ts.map

package/dist/titles.js

@@ -0,0 +1,115 @@
+/**
+ * Titles: the human-readable label for a record, assembled from its title fields and,
+ * where a title field points at a parent, from that parent's titles too.
+ */
+import * as overscore from './overscore.js';
+/** Titles for a set of records, keyed by id, with the ids kept in retrieval order. */
+export class Titles {
+    /** Name of the id field the titles are keyed by. */
+    id;
+    /** Fields that make up a title. */
+    fields;
+    /** Ids, in order. */
+    ids = [];
+    /** Title values, keyed by id. */
+    titles = new Map();
+    /** Format instructions, one per title value. */
+    format = [];
+    /** Parent titles, for title fields that point at another model. */
+    parents = {};
+    constructor(model) {
+        this.id = model._id;
+        this.fields = model._titles;
+    }
+    /**
+     * Build titles for a model. Async because a title field pointing at a parent has to
+     * fetch that parent's titles first.
+     */
+    static async build(model) {
+        const titles = new Titles(model);
+        for (const field of titles.fields) {
+            const relation = model._ancestor(field);
+            if (relation !== null) {
+                const parent = await relation.Parent
+                    .many({ [`${relation.parentId}__in`]: model[field] })
+                    .titles();
+                titles.parents[field] = parent;
+                titles.format.push(...parent.format);
+            }
+            else {
+                const own = model._fields.field(field);
+                if (own && own.format !== null) {
+                    titles.format.push(...own.format);
+                }
+                else {
+                    titles.format.push(null);
+                }
+            }
+        }
+        return titles;
+    }
+    /** How many titles there are. */
+    get size() {
+        return this.ids.length;
+    }
+    /** Whether there's a title for an id. */
+    has(id) {
+        return this.ids.includes(id);
+    }
+    /** The title values for an id. */
+    get(id) {
+        return this.titles.get(id);
+    }
+    /** Set the title values for an id. */
+    set(id, value) {
+        if (!this.ids.includes(id)) {
+            this.ids.push(id);
+        }
+        this.titles.set(id, value);
+    }
+    /** Forget an id. */
+    delete(id) {
+        const at = this.ids.indexOf(id);
+        if (at !== -1) {
+            this.ids.splice(at, 1);
+        }
+        this.titles.delete(id);
+    }
+    /** Ids, in order. */
+    *[Symbol.iterator]() {
+        yield* this.ids;
+    }
+    /** Add a record's title. */
+    add(model) {
+        const title = [];
+        for (const name of this.fields) {
+            if (name in this.parents) {
+                const parent = this.parents[name];
+                const key = model[name];
+                if (parent.has(key)) {
+                    title.push(...parent.get(key));
+                }
+                else {
+                    title.push(...parent.format.map(() => null));
+                }
+            }
+            else {
+                const path = overscore.parse(name);
+                const field = String(path.shift());
+                title.push(...(model._record?.field(field)?.title(path) ?? []));
+            }
+        }
+        this.set(model[this.id], title);
+    }
+    /** Plain object form, for serialising. */
+    toJSON() {
+        return {
+            id: this.id,
+            fields: this.fields,
+            ids: this.ids,
+            titles: Object.fromEntries(this.titles),
+            format: this.format
+        };
+    }
+}
+//# sourceMappingURL=titles.js.map

package/dist/typed.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Typed models.
+ *
+ * Field values are reached through a Proxy at runtime, which TypeScript can't see into
+ * on its own. `fields()` closes that gap: it declares the fields once and hands back a
+ * base class that already knows their types.
+ *
+ * ```ts
+ * import { fields, int, str, list } from '@relations-dil/relations'
+ *
+ * class Unit extends fields({ id: int, name: str, tags: list }) {
+ *   static source = 'example'
+ * }
+ *
+ * const unit = await Unit.one({ name: 'yep' }).retrieve()
+ *
+ * unit.name.toUpperCase()   // string, checked
+ * unit.nmae                 // error: no such field
+ * unit.name = 5             // error: not a string
+ * ```
+ *
+ * Relations are declared separately from the model, so add them with `declare` when you
+ * want them typed too. `declare` is erased at compile time and costs nothing to run:
+ *
+ * ```ts
+ * class Unit extends fields({ id: int, name: str }) {
+ *   static source = 'example'
+ *   declare test: Test
+ * }
+ * ```
+ */
+import { Field } from './field.js';
+import { Model, type FieldSpec, type ModelClass, type ModelIdentity } from './model.js';
+import type { bool, dict, float, int, list, set, str } from './kinds.js';
+/** The value type behind a kind sentinel. */
+export type ValueOfKind<K> = K extends typeof bool ? boolean : K extends typeof int ? number : K extends typeof float ? number : K extends typeof str ? string : K extends typeof set ? Set<any> : K extends typeof list ? any[] : K extends typeof dict ? globalThis.Record<string, any> : K extends abstract new (...args: any[]) => infer T ? T : any;
+/** The value type behind a field declaration. */
+export type ValueOfSpec<S> = S extends Field ? any : S extends readonly (infer T)[] ? T : S extends Set<infer T> ? Set<T> : S extends (...args: any[]) => infer T ? T : S extends {
+    kind: infer K;
+} ? ValueOfKind<K> : ValueOfKind<S>;
+/** Every field of a declaration, as the values they hold. */
+export type Values<F> = {
+    [Name in keyof F]: ValueOfSpec<F[Name]>;
+};
+/** A model instance with its fields typed. */
+export type Typed<F> = Model & Values<F>;
+/**
+ * A model in many mode: every field reads back as an array of its values, and indexing
+ * gives you one model.
+ */
+export type Listed<I> = Model & {
+    [Name in keyof Omit<I, keyof Model>]: I[Name][];
+} & {
+    [index: number]: I;
+};
+/** The class of a model with its fields typed. */
+export interface TypedClass<F> {
+    [member: string]: any;
+    new (...args: any[]): Typed<F>;
+    /** The field declaration this class was built from. */
+    fields: F;
+    /** Name of the source this model lives in. */
+    source?: string;
+    /** Name of the model in the source. Defaults to the underscored class name. */
+    store?: string;
+    /** Human-facing title. Defaults to the class name. */
+    title?: string;
+    /** Which field is the id, by name or position. `null` for no id. */
+    id?: string | number | null;
+    /** Which fields make up a title. */
+    titles?: string | string[];
+    /** Which fields to show in a listing. */
+    list?: string | string[];
+    /** Unique indexes. */
+    unique?: string | string[] | globalThis.Record<string, string[]> | false;
+    /** Regular indexes. */
+    index?: string | string[] | globalThis.Record<string, string[]>;
+    /** Default sort order. */
+    order?: string | string[];
+    /** Default chunk size. */
+    chunk?: number;
+    /** Everything knowable about this model without an instance. */
+    thy(target?: ModelIdentity): ModelIdentity;
+    /** The definition of this model, as the source wants it. */
+    define(...args: any[]): any;
+    /** A model that will retrieve exactly one record. */
+    one<T extends abstract new (...args: any[]) => any>(this: T, ...args: any[]): InstanceType<T>;
+    /** A model that will retrieve any number of records. */
+    many<T extends abstract new (...args: any[]) => any>(this: T, ...args: any[]): Listed<InstanceType<T>>;
+    /** A model set up to insert many records without reading their ids back. */
+    bulk<T extends abstract new (...args: any[]) => any>(this: T, size?: number): Listed<InstanceType<T>>;
+}
+/**
+ * A base class with these fields, typed. Extend it instead of `Model` and every field
+ * is checked at the point you touch it. Pass a base to share configuration, the way a
+ * `Base` class shares a source across models.
+ */
+export declare function fields<F extends globalThis.Record<string, FieldSpec>>(spec: F, base?: ModelClass | TypedClass<any>): TypedClass<F>;
+//# sourceMappingURL=typed.d.ts.map