@relations-dil/relations 0.1.0

package/dist/relation.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Relations between models.
+ *
+ * Relations are declared outside the models, not inside them, so a model stays a plain
+ * description of its own shape and can be reused in a service that doesn't know about
+ * the other side.
+ *
+ * ```ts
+ * new OneToMany(Unit, Test)          // unit.test, test.unit
+ * new OneToOne(Unit, Detail)         // unit.detail, detail.unit
+ * new ManyToMany(Sister, Brother, Tie)
+ * ```
+ */
+import type { ModelClass, ModelIdentity } from './model.js';
+/** Base for every relation, holding the convention used to find the joining field. */
+export declare class Relation {
+    /** Whether the two sides can share an id field name. */
+    static SAME: boolean | null;
+    /**
+     * Work out which field on `relative` points at `model`, by convention:
+     * `<model>_id`, then `<model>_<model id field>`, then the model's own id field name.
+     */
+    static relativeField(model: ModelIdentity, relative: ModelIdentity, same: boolean | null): string;
+}
+/** What you can spell out about a one-to-* relation instead of letting it be inferred. */
+export interface OneToOptions {
+    /** Attribute on the parent that reaches the children. Defaults to the child's name. */
+    parentChildAttr?: string;
+    /** Attribute on the child that reaches the parent. Defaults to the parent's name. */
+    childParentAttr?: string;
+    /** Field on the parent the child points at. Defaults to the parent's id. */
+    parentId?: string | number;
+    /** Field on the child that points at the parent. Inferred by convention. */
+    childParentRef?: string | number;
+}
+/** One parent record to one or many child records. */
+export declare class OneTo extends Relation {
+    /** Whether the child side holds one record or many. */
+    static MODE: 'one' | 'many';
+    /** The model with one record. */
+    Parent: ModelClass;
+    /** Field on the parent the child points at. */
+    parentId: string;
+    /** Attribute on the parent that reaches the children. */
+    parentChildAttr: string;
+    /** The model with the other record or records. */
+    Child: ModelClass;
+    /** Field on the child that points at the parent. */
+    childParentRef: string;
+    /** Attribute on the child that reaches the parent. */
+    childParentAttr: string;
+    /** Whether the child side holds one record or many. */
+    MODE: 'one' | 'many';
+    constructor(Parent: ModelClass, Child: ModelClass, options?: OneToOptions);
+}
+/** One parent record to many child records. */
+export declare class OneToMany extends OneTo {
+    static MODE: "many";
+    static SAME: boolean;
+}
+/** One parent record to one child record. */
+export declare class OneToOne extends OneTo {
+    static MODE: "one";
+    static SAME: boolean;
+}
+/** What you can spell out about a many-to-many relation instead of letting it be inferred. */
+export interface ManyToManyOptions {
+    /** Attribute on the sister that reaches the brothers. Defaults to the brother's name. */
+    sisterBrotherAttr?: string;
+    /** Attribute on the brother that reaches the sisters. Defaults to the sister's name. */
+    brotherSisterAttr?: string;
+    /** Field on the sister listing brother ids. Inferred by convention. */
+    sisterBrotherRef?: string | number;
+    /** Field on the brother listing sister ids. Inferred by convention. */
+    brotherSisterRef?: string | number;
+    /** Field on the sister the tie points at. Defaults to the sister's id. */
+    sisterId?: string | number;
+    /** Field on the brother the tie points at. Defaults to the brother's id. */
+    brotherId?: string | number;
+    /** Field on the tie pointing at the sister. Inferred by convention. */
+    tieSisterRef?: string | number;
+    /** Field on the tie pointing at the brother. Inferred by convention. */
+    tieBrotherRef?: string | number;
+}
+/**
+ * Many records on each side, joined through a tie model. The tie is a real model, so it
+ * lives in the same source and migrates like anything else.
+ */
+export declare class ManyToMany extends Relation {
+    /** The model with fewer records, by convention. */
+    Sister: ModelClass;
+    /** Field on the sister the tie points at. */
+    sisterId: string;
+    /** Field on the sister listing brother ids. */
+    sisterBrotherRef: string;
+    /** Attribute on the sister that reaches the brothers. */
+    sisterBrotherAttr: string;
+    /** The model with more records, by convention. */
+    Brother: ModelClass;
+    /** Field on the brother the tie points at. */
+    brotherId: string;
+    /** Field on the brother listing sister ids. */
+    brotherSisterRef: string;
+    /** Attribute on the brother that reaches the sisters. */
+    brotherSisterAttr: string;
+    /** The joining model. */
+    Tie: ModelClass;
+    /** Field on the tie pointing at the sister. */
+    tieSisterRef: string;
+    /** Field on the tie pointing at the brother. */
+    tieBrotherRef: string;
+    constructor(Sister: ModelClass, Brother: ModelClass, Tie: ModelClass, options?: ManyToManyOptions);
+}
+//# sourceMappingURL=relation.d.ts.map

package/dist/relation.js

@@ -0,0 +1,145 @@
+/**
+ * Relations between models.
+ *
+ * Relations are declared outside the models, not inside them, so a model stays a plain
+ * description of its own shape and can be reused in a service that doesn't know about
+ * the other side.
+ *
+ * ```ts
+ * new OneToMany(Unit, Test)          // unit.test, test.unit
+ * new OneToOne(Unit, Detail)         // unit.detail, detail.unit
+ * new ManyToMany(Sister, Brother, Tie)
+ * ```
+ */
+import { ModelError } from './errors.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. */
+    static SAME = null;
+    /**
+     * Work out which field on `relative` points at `model`, by convention:
+     * `<model>_id`, then `<model>_<model id field>`, then the model's own id field name.
+     */
+    static relativeField(model, relative, same) {
+        // The standard convention: unit_id on the test.
+        const standard = `${model.NAME}_id`;
+        if (relative._fields.has(standard)) {
+            return standard;
+        }
+        // The id field isn't called id: unit_uuid on the test.
+        const modelId = model._fieldName(model._id);
+        const simple = `${model.NAME}_${modelId}`;
+        if (relative._fields.has(simple)) {
+            return simple;
+        }
+        // Both sides use the same name for the field: unit_id on both.
+        if (relative._fields.has(modelId) && (same || modelId !== relative._fieldName(relative._id))) {
+            return modelId;
+        }
+        throw new ModelError(model, `cannot determine field for ${model.NAME} in ${relative.NAME}`);
+    }
+}
+/** One parent record to one or many child records. */
+export class OneTo extends Relation {
+    /** Whether the child side holds one record or many. */
+    static MODE = 'many';
+    /** The model with one record. */
+    Parent;
+    /** Field on the parent the child points at. */
+    parentId;
+    /** Attribute on the parent that reaches the children. */
+    parentChildAttr;
+    /** The model with the other record or records. */
+    Child;
+    /** Field on the child that points at the parent. */
+    childParentRef;
+    /** Attribute on the child that reaches the parent. */
+    childParentAttr;
+    /** Whether the child side holds one record or many. */
+    MODE;
+    constructor(Parent, Child, options = {}) {
+        super();
+        const kind = this.constructor;
+        this.Parent = Parent;
+        this.Child = Child;
+        this.MODE = kind.MODE;
+        const parent = Parent.thy();
+        const child = Child.thy();
+        this.parentId = parent._fieldName(options.parentId ?? parent._id);
+        this.parentChildAttr = options.parentChildAttr ?? child.NAME;
+        this.childParentAttr = options.childParentAttr ?? parent.NAME;
+        this.childParentRef =
+            options.childParentRef !== undefined
+                ? child._fieldName(options.childParentRef)
+                : Relation.relativeField(parent, child, kind.SAME);
+        this.Parent._child(this);
+        this.Child._parent(this);
+    }
+}
+/** One parent record to many child records. */
+export class OneToMany extends OneTo {
+    static MODE = 'many';
+    static SAME = false;
+}
+/** One parent record to one child record. */
+export class OneToOne extends OneTo {
+    static MODE = 'one';
+    static SAME = true;
+}
+/**
+ * Many records on each side, joined through a tie model. The tie is a real model, so it
+ * lives in the same source and migrates like anything else.
+ */
+export class ManyToMany extends Relation {
+    /** The model with fewer records, by convention. */
+    Sister;
+    /** Field on the sister the tie points at. */
+    sisterId;
+    /** Field on the sister listing brother ids. */
+    sisterBrotherRef;
+    /** Attribute on the sister that reaches the brothers. */
+    sisterBrotherAttr;
+    /** The model with more records, by convention. */
+    Brother;
+    /** Field on the brother the tie points at. */
+    brotherId;
+    /** Field on the brother listing sister ids. */
+    brotherSisterRef;
+    /** Attribute on the brother that reaches the sisters. */
+    brotherSisterAttr;
+    /** The joining model. */
+    Tie;
+    /** Field on the tie pointing at the sister. */
+    tieSisterRef;
+    /** Field on the tie pointing at the brother. */
+    tieBrotherRef;
+    constructor(Sister, Brother, Tie, options = {}) {
+        super();
+        this.Sister = Sister;
+        this.Brother = Brother;
+        this.Tie = Tie;
+        if (Tie.TIE === undefined || Tie.TIE === null) {
+            Tie.TIE = true;
+        }
+        const sister = Sister.thy();
+        const brother = Brother.thy();
+        const tie = Tie.thy();
+        this.sisterId = sister._fieldName(options.sisterId ?? sister._id);
+        this.sisterBrotherRef =
+            options.sisterBrotherRef !== undefined
+                ? sister._fieldName(options.sisterBrotherRef)
+                : Relation.relativeField(brother, sister, null);
+        this.sisterBrotherAttr = options.sisterBrotherAttr ?? brother.NAME;
+        this.brotherId = brother._fieldName(options.brotherId ?? brother._id);
+        this.brotherSisterRef =
+            options.brotherSisterRef !== undefined
+                ? brother._fieldName(options.brotherSisterRef)
+                : Relation.relativeField(sister, brother, null);
+        this.brotherSisterAttr = options.brotherSisterAttr ?? sister.NAME;
+        this.tieSisterRef = tie._fieldName(options.tieSisterRef ?? Relation.relativeField(sister, tie, null));
+        this.tieBrotherRef = tie._fieldName(options.tieBrotherRef ?? Relation.relativeField(brother, tie, null));
+        this.Sister._brother(this);
+        this.Brother._sister(this);
+    }
+}
+//# sourceMappingURL=relation.js.map

package/dist/source.d.ts

@@ -0,0 +1,147 @@
+/**
+ * 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 type { Field } from './field.js';
+import type { Record as FieldRecord } from './record.js';
+import type { ManyToMany } from './relation.js';
+import type { Model, ModelClass, ModelIdentity } from './model.js';
+/** A query a source built but hasn't run. */
+export interface Query {
+    bind(model: Model): Query;
+    [member: string]: any;
+}
+/**
+ * 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 declare class Source {
+    /** Anything the subclass was constructed with. */
+    [option: string]: any;
+    /** What kind of source this is, used to namespace migration files. */
+    static KIND: string | null;
+    /** The name models refer to this source by. */
+    name: string;
+    constructor(name: string, options?: globalThis.Record<string, any>);
+    /** What kind of source this is. */
+    get KIND(): string | null;
+    /** Give an object an attribute if it hasn't got one. */
+    ensureAttribute(item: any, attribute: string, value?: any): void;
+    /** Prepare a field for this source. */
+    fieldInit(field: Field): void;
+    /** Prepare every field in a record. */
+    recordInit(record: FieldRecord): void;
+    /** Prepare a model. Called once per model identity. */
+    init(model: ModelIdentity): void;
+    /** Turn a field definition into whatever this source needs. */
+    fieldDefine(field: globalThis.Record<string, any>, ...args: any[]): void;
+    /** Turn every field definition in a record. */
+    recordDefine(record: globalThis.Record<string, any>[], ...args: any[]): void;
+    /** Turn a model definition into whatever this source needs. */
+    define(model: globalThis.Record<string, any>, ...args: any[]): any;
+    /** Add a field. */
+    fieldAdd(migration: globalThis.Record<string, any>, ...args: any[]): void;
+    /** Remove a field. */
+    fieldRemove(definition: globalThis.Record<string, any>, ...args: any[]): void;
+    /** Change a field. */
+    fieldChange(definition: globalThis.Record<string, any>, migration: globalThis.Record<string, any>, ...args: any[]): void;
+    /** Apply a record's worth of field changes. */
+    recordChange(definition: globalThis.Record<string, any>[], migration: globalThis.Record<string, any>, ...args: any[]): void;
+    /** Add a model. */
+    modelAdd(migration: globalThis.Record<string, any>): any;
+    /** Remove a model. */
+    modelRemove(definition: globalThis.Record<string, any>): any;
+    /** Change a model. */
+    modelChange(definition: globalThis.Record<string, any>, migration: globalThis.Record<string, any>): any;
+    /** Prepare a field for a create. */
+    createField(field: Field, ...args: any[]): void;
+    /** Prepare every field in a record for a create. */
+    createRecord(record: FieldRecord, ...args: any[]): void;
+    /** The query that would create these records. */
+    createQuery(model: Model, ...args: any[]): Query | undefined;
+    /** Whether any tie records need writing. */
+    static hasTies(model: Model, data?: any): boolean;
+    /** Write the tie records for a many-to-many. */
+    static createTies(model: Model, data?: any, ids?: any): Promise<void>;
+    /** Write records. Subclasses do the actual storing and call this first. */
+    create(model: Model, ...args: any[]): Promise<any>;
+    /** Prepare a field for a retrieve. */
+    retrieveField(field: Field, ...args: any[]): void;
+    /** Prepare every field in a record for a retrieve. */
+    retrieveRecord(record: FieldRecord, ...args: any[]): void;
+    /** The ids on one side of a tie that match a set operator on the other. */
+    static tieIds(Tie: ModelClass, queryRef: string, resultRef: string, operator: string, values: any): Promise<Set<any>>;
+    /**
+     * 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 attrIds(relation: ManyToMany, side: 'sister' | 'brother', criteria: globalThis.Record<string, any>): Promise<Set<any>>;
+    /**
+     * 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 collateTies(model: Model): Promise<void>;
+    /** Fill in the tie fields on retrieved records. */
+    static retrieveTies(model: Model): Promise<void>;
+    /** The query that would count matching records. */
+    countQuery(model: Model, ...args: any[]): Query | undefined;
+    /** Count matching records. Subclasses do the counting and call this first. */
+    count(model: Model, ...args: any[]): Promise<any>;
+    /** The query that would retrieve matching records. */
+    retrieveQuery(model: Model, ...args: any[]): Query | undefined;
+    /** Read records. Subclasses do the reading and call this first. */
+    retrieve(model: Model, verify?: boolean, ...args: any[]): Promise<any>;
+    /** The query that would retrieve titles. */
+    titlesQuery(model: Model, ...args: any[]): Query | undefined;
+    /** Titles for matching records. Subclasses build them and call this first. */
+    titles(model: Model, ...args: any[]): Promise<any>;
+    /** Prepare a field for an update. */
+    updateField(field: Field, ...args: any[]): void;
+    /** Prepare every field in a record for an update. */
+    updateRecord(record: FieldRecord, ...args: any[]): void;
+    /** Prepare a field for a mass update. */
+    fieldMass(field: Field, ...args: any[]): void;
+    /** Prepare every field in a record for a mass update. */
+    recordMass(record: FieldRecord, ...args: any[]): void;
+    /** The query that would update records. */
+    updateQuery(model: Model, ...args: any[]): Query | undefined;
+    /** Write changes. Resolves to how many records changed. */
+    update(model: Model, ...args: any[]): Promise<number>;
+    /** Prepare a field for a delete. */
+    deleteField(field: Field, ...args: any[]): void;
+    /** Prepare every field in a record for a delete. */
+    deleteRecord(record: FieldRecord, ...args: any[]): void;
+    /** The query that would delete records. */
+    deleteQuery(model: Model, ...args: any[]): Query | undefined;
+    /** Remove the tie records for a many-to-many. */
+    static deleteTies(model: Model, ids?: any): Promise<void>;
+    /** Remove records. Resolves to how many were removed. */
+    delete(model: Model, ...args: any[]): Promise<number>;
+    /** Convert a general definition file into a source-specific one. */
+    definition(filePath: string, sourcePath: string): Promise<void>;
+    /** Convert a general migration file into a source-specific one. */
+    migration(filePath: string, sourcePath: string): Promise<void>;
+    /** Run a command or commands against the source. */
+    execute(commands: any): Promise<void>;
+    /** The migration pairs available for this source. */
+    list(sourcePath: string): Promise<globalThis.Record<string, any>>;
+    /** Load a definition or migration file into the source. */
+    load(filePath: string): Promise<void>;
+    /** Bring the source up to date with everything in a migration directory. */
+    migrate(sourcePath: string): Promise<boolean>;
+}
+/** A field definition by name. */
+export declare function lookup(name: string, fields: globalThis.Record<string, any>[]): globalThis.Record<string, any> | null;
+//# sourceMappingURL=source.d.ts.map