@relations-dil/relations 0.1.0

package/dist/model.d.ts

@@ -0,0 +1,277 @@
+/**
+ * Models: what you actually write, and the only thing that knows about relations.
+ */
+import { Field, type FieldOptions } from './field.js';
+import { Record } from './record.js';
+import { type FieldKind, type Kind } from './kinds.js';
+import type { ManyToMany, OneTo } from './relation.js';
+/** What a model is currently doing. */
+export type ModelAction = 'create' | 'retrieve' | 'update';
+/** Whether a model holds one record or many. */
+export type ModelMode = 'one' | 'many';
+/** What a model is to whatever reached it. */
+export type ModelRole = 'model' | 'parent' | 'child';
+/** Everything accepted as a field declaration in `static fields`. */
+export type FieldSpec = Kind | Field | Set<any> | any[] | (() => any) | ({
+    kind: FieldKind;
+} & FieldOptions);
+/** Options relations passes to itself when building related or loaded models. */
+interface Internals {
+    read?: globalThis.Record<string, any>;
+    child?: globalThis.Record<string, any>;
+    parent?: globalThis.Record<string, any>;
+    sibling?: globalThis.Record<string, any>;
+    action?: ModelAction;
+    mode?: ModelMode;
+    chunk?: number;
+    bulk?: boolean;
+    size?: number;
+    related?: globalThis.Record<string, any>;
+    args?: any[];
+}
+/** Turn a `static fields` entry into an actual Field. */
+export declare function toField(spec: FieldSpec): Field;
+/**
+ * What's knowable about a model without having an instance of it: its name, its fields,
+ * its indexes, its relations. Sources and migrations work against this.
+ */
+export declare class ModelIdentity {
+    /** Anything else the model class hung off itself in uppercase. */
+    [attribute: string]: any;
+    /** Name of the source this model lives in. */
+    SOURCE: string | null;
+    /** Human-facing title of the model. */
+    TITLE: string | null;
+    /** Name of the model in the source. */
+    NAME: string | null;
+    /** Whether this model is a many-to-many tie table. */
+    TIE: boolean | null;
+    /** Parent relations, keyed by the attribute on this model. */
+    PARENTS: globalThis.Record<string, OneTo>;
+    /** Child relations, keyed by the attribute on this model. */
+    CHILDREN: globalThis.Record<string, OneTo>;
+    /** Sister relations, keyed by the attribute on this model. */
+    SISTERS: globalThis.Record<string, ManyToMany>;
+    /** Brother relations, keyed by the attribute on this model. */
+    BROTHERS: globalThis.Record<string, ManyToMany>;
+    /** Default chunk size for related lookups and bulk creates. */
+    CHUNK: number;
+    /** The model's fields, in order. Records are built from these. */
+    _fields: Record;
+    /** Name of the id field, if there is one. */
+    _id: string | null;
+    /** Fields that make up a title. */
+    _titles: string[];
+    /** Fields to show in a listing. */
+    _list: string[];
+    /** Unique indexes, keyed by index name. */
+    _unique: globalThis.Record<string, string[]>;
+    /** Regular indexes, keyed by index name. */
+    _index: globalThis.Record<string, string[]>;
+    /** Default sort order, as signed field names. */
+    _order: string[];
+    /** The name of a field, whether given by name or position. */
+    _fieldName(field: string | number): string;
+    /** Turn a sort spec into signed field names, checking each one exists. */
+    _ordering(sort: string | string[]): string[];
+    /** The parent relation a field points at, if any. */
+    _ancestor(field: string): OneTo | null;
+    /** The full definition of this model, for schemas and migrations. */
+    define(): globalThis.Record<string, any>;
+    /** How to get from a previous definition of this model to this one. */
+    migrate(previous: globalThis.Record<string, any>, definition?: globalThis.Record<string, any>): globalThis.Record<string, any>;
+}
+export declare const MigrationsRef: {
+    model: (current: any, define: any) => any;
+};
+/** The static shape of a model class. */
+export interface ModelClass<M extends Model = Model> {
+    new (...args: any[]): M;
+    source?: string;
+    fields?: globalThis.Record<string, FieldSpec>;
+    store?: string;
+    title?: string;
+    id?: string | number | null;
+    titles?: string | string[];
+    list?: string | string[];
+    unique?: string | string[] | globalThis.Record<string, string[]> | false;
+    index?: string | string[] | globalThis.Record<string, string[]>;
+    order?: string | string[];
+    chunk?: number;
+    thy(target?: ModelIdentity): ModelIdentity;
+    [member: string]: any;
+}
+/**
+ * A model. Extend it, declare `static source` and `static fields`, and you have
+ * something you can create, retrieve, update and delete against any source.
+ *
+ * ```ts
+ * class Unit extends Model {
+ *   static source = 'example'
+ *   static fields = { id: int, name: str }
+ * }
+ *
+ * await new Unit('yep').create()
+ * const unit = await Unit.one({ name: 'yep' }).retrieve()
+ * ```
+ */
+export declare class Model extends ModelIdentity {
+    /** The single loaded record, in one mode. */
+    _record: Record | null;
+    /** The loaded models, in many mode. */
+    _models: Model[] | null;
+    /** Loaded parent models, keyed by attribute. */
+    _parents: globalThis.Record<string, Model | null>;
+    /** Loaded child models, keyed by attribute. */
+    _children: globalThis.Record<string, Model | null>;
+    /** Loaded sister models, keyed by attribute. */
+    _sisters: globalThis.Record<string, Model | null>;
+    /** Loaded brother models, keyed by attribute. */
+    _brothers: globalThis.Record<string, Model | null>;
+    /** Pending sibling-attribute criteria, keyed by relation attribute. */
+    _ties: globalThis.Record<string, globalThis.Record<string, any>>;
+    /** What this model is to whatever reached it. */
+    _role: ModelRole;
+    /** Whether this model holds one record or many. */
+    _mode: ModelMode | null;
+    /** Whether this is a bulk insert. */
+    _bulk: boolean;
+    /** Chunk size for this model. */
+    _chunk: number;
+    /** How many to accumulate before a bulk insert flushes. */
+    _size: number;
+    /** The current fuzzy match. */
+    _like: any;
+    /** Sorting to apply on retrieve. */
+    _sort: string[] | null;
+    /** How many records to retrieve. */
+    _limit: number | null;
+    /** Where to start retrieving from. */
+    _offset: number;
+    /** What this model is doing. */
+    _action: ModelAction;
+    /** Fields set automatically because of a relation. */
+    _related: globalThis.Record<string, any>;
+    /** Whether a limit was reached, so there may be more records than were returned. */
+    overflow: boolean;
+    constructor(...args: any[]);
+    /**
+     * Work out everything knowable about this model class. Called for you on every
+     * instance; call it directly when you need a model's shape without an instance.
+     */
+    static thy(target?: ModelIdentity): ModelIdentity;
+    /** Register a parent relation on this class. */
+    static _parent(relation: OneTo): void;
+    /** Register a child relation on this class. */
+    static _child(relation: OneTo): void;
+    /** Register a sister relation on this class. */
+    static _sister(relation: ManyToMany): void;
+    /** Register a brother relation on this class. */
+    static _brother(relation: ManyToMany): void;
+    /** Whether a name is one of this model's relation attributes. */
+    _isRelation(name: string): boolean;
+    /** The related model behind a relation attribute. */
+    _relate(name: string): Model | null;
+    /** Hold on to a sibling-attribute filter until the source can resolve it. */
+    _tie(name: string, remainder: string, value: any): void;
+    /**
+     * Fold criteria gathered on related models into this model's own criteria. Retrieving
+     * the relatives is what makes this async: `Test.many({unit__name: 'x'})` has to find
+     * the matching units before it can filter tests by their ids.
+     */
+    _collate(): Promise<void>;
+    /** Keep relations honest when the field they hang off changes. */
+    _propagate(field: string | number, value: any): void;
+    /** Fill a record in from positional and named values. */
+    _input(record: Record, positional: any[], named: globalThis.Record<string, any>): void;
+    /** Build a fresh record for an action. */
+    _build(action: 'create' | 'retrieve' | 'update', options?: {
+        defaults?: boolean;
+        read?: globalThis.Record<string, any>;
+        positional?: any[];
+        named?: globalThis.Record<string, any>;
+    }): Record;
+    /**
+     * Guard synchronous access. A model that still has to hit the source can't fill
+     * itself in from a property getter, so say so plainly instead of returning nothing.
+     */
+    _ensureSync(): void;
+    /** Retrieve if this model still needs to, then carry on. */
+    _ensure(): Promise<void>;
+    /** Every model this one stands for: itself in one mode, its models in many. */
+    _each(action?: ModelAction): Model[];
+    /** Read a value the way `model[key]` does. */
+    _item(key: string | number): any;
+    /** Write a value the way `model[key] = value` does. */
+    _setItem(key: string | number, value: any): void;
+    /** Whether a field is reachable right now, the way `key in model` asks in Python. */
+    _contains(key: string | number): boolean;
+    /** Walk a double-underscored path that starts at a relation. */
+    _path(name: string): any;
+    /** The proxy wrapping this model, so internals hand back the same object callers hold. */
+    _proxy: Model | null;
+    /** Add criteria. Positional values match fields in order, named ones by `field__operator`. */
+    filter(...args: any[]): this;
+    /** A model set up to insert many records without reading their ids back. */
+    static bulk<M extends Model>(this: ModelClass<M>, size?: number): M;
+    /** A model that will retrieve exactly one record. */
+    static one<M extends Model>(this: ModelClass<M>, ...args: any[]): M;
+    /** A model that will retrieve any number of records. */
+    static many<M extends Model>(this: ModelClass<M>, ...args: any[]): M;
+    /** Sort: on a retrieve it's added to the query, otherwise the loaded models are sorted. */
+    sort(...args: string[]): this;
+    /** How many records to retrieve, and where to start. */
+    limit(limit?: number | {
+        limit?: number;
+        start?: number;
+        page?: number;
+        perPage?: number;
+    }): this;
+    /** Set values on the loaded record, or stage a mass update across many. */
+    set(...args: any[]): this;
+    /**
+     * Add a record. In many mode you can add as many as you like.
+     *
+     * On a relation that hasn't been read yet, adding starts a fresh set to create rather
+     * than quietly going to the source - `await model.relation.retrieve()` first when you
+     * want the existing records loaded alongside the new ones.
+     */
+    add(...args: any[]): this;
+    /** Add a record, flushing to the source when a bulk model fills up. */
+    queue(...args: any[]): Promise<this>;
+    /** Number of records in many mode, or fields in one mode. */
+    get size(): number;
+    /** The loaded models, in many mode. */
+    get models(): Model[];
+    /** Models in many mode, field names in one mode. */
+    [Symbol.iterator](): IterableIterator<any>;
+    /** Field names of the loaded record. */
+    keys(): string[];
+    /** Every value, keyed by field name - or an array of those in many mode. */
+    export(): any;
+    /** So `JSON.stringify(model)` does what you'd hope. */
+    toJSON(): any;
+    /** The definition of this model, for schemas and migrations. */
+    static define(...args: any[]): any;
+    /** Write this model's records to the source. */
+    create(...args: any[]): Promise<this>;
+    /** How many records match. */
+    count(...args: any[]): Promise<number>;
+    /**
+     * Read this model's records out of the source. Pass `false` to get `null` instead of
+     * an error when a one-mode retrieve finds nothing.
+     */
+    retrieve(verify?: boolean, ...args: any[]): Promise<this | null>;
+    /** Titles for the matching records, keyed by id. */
+    titles(...args: any[]): Promise<any>;
+    /** Write changes back to the source. Resolves to how many records changed. */
+    update(...args: any[]): Promise<number>;
+    /** Remove records from the source. Resolves to how many were removed. */
+    delete(...args: any[]): Promise<number>;
+    /** The query a source would run for an action, without running it. */
+    query(action?: 'create' | 'retrieve' | 'count' | 'titles' | 'update' | 'delete', ...args: any[]): any;
+}
+/** Build a model the way relations does internally, bypassing the public constructor. */
+export declare function construct<M extends Model>(cls: ModelClass<M>, internal: Internals): M;
+export {};
+//# sourceMappingURL=model.d.ts.map