@bunyad/orm 0.1.0-alpha.0

package/dist/orm-collection.d.ts

@@ -0,0 +1,37 @@
+import { Collection } from "@bunyad/common";
+import type { Model } from "./model.js";
+/**
+ * ORM model collection (`get()` / relation `get()`).
+ */
+export declare class OrmCollection<T extends Model = Model> extends Collection<T> {
+    #private;
+    constructor(items?: T[] | Collection<T> | Iterable<T> | null | undefined, options?: {
+        owned?: boolean;
+    });
+    /** Fresh `items` array — no copy. */
+    protected make(items: T[]): OrmCollection<T>;
+    /**
+     * Eager-load relations onto every model (`load('posts')` / constrained maps).
+     */
+    load(...relations: Array<string | Record<string, unknown>>): Promise<this>;
+    /**
+     * Load only relations that are not already present (`loadMissing`).
+     */
+    loadMissing(...relations: Array<string | Record<string, unknown>>): Promise<this>;
+    /** Laravel `$collection->loadCount(...)` — batched GROUP BY per relation. */
+    loadCount(...relations: string[]): Promise<this>;
+    loadSum(relation: string, column: string): Promise<this>;
+    loadAvg(relation: string, column: string): Promise<this>;
+    loadMin(relation: string, column: string): Promise<this>;
+    loadMax(relation: string, column: string): Promise<this>;
+    loadExists(...relations: string[]): Promise<this>;
+    /** Primary keys of all models. */
+    modelKeys(): Collection<unknown>;
+    /**
+     * Find model(s) by primary key (`$collection->find($id)`).
+     * Pass an array of keys to return a filtered OrmCollection.
+     */
+    find(key: string | number | bigint): T | null;
+    find(keys: Array<string | number | bigint>): OrmCollection<T>;
+    findOrFail(key: string | number | bigint): T;
+}

package/dist/orm-collection.js

@@ -0,0 +1,150 @@
+import { Collection } from "@bunyad/common";
+function relationLoaded(model, name) {
+    return Object.prototype.hasOwnProperty.call(model, name);
+}
+function parseRelationAlias(raw) {
+    const m = raw.match(/^(.+?)\s+as\s+(.+)$/i);
+    if (!m)
+        return { relation: raw.trim() };
+    return { relation: m[1].trim(), alias: m[2].trim() };
+}
+/**
+ * ORM model collection (`get()` / relation `get()`).
+ */
+export class OrmCollection extends Collection {
+    constructor(items = [], options) {
+        super(items, options);
+    }
+    /** Fresh `items` array — no copy. */
+    make(items) {
+        return new OrmCollection(items, { owned: true });
+    }
+    /**
+     * Eager-load relations onto every model (`load('posts')` / constrained maps).
+     */
+    async load(...relations) {
+        if (relations.length === 0 || this.isEmpty())
+            return this;
+        const { eagerLoadModels } = await import("./model.js");
+        const { normalizeWithRelations } = await import("./model-helpers.js");
+        await eagerLoadModels(this.all(), normalizeWithRelations(relations));
+        return this;
+    }
+    /**
+     * Load only relations that are not already present (`loadMissing`).
+     */
+    async loadMissing(...relations) {
+        const { normalizeWithRelations } = await import("./model-helpers.js");
+        const normalized = normalizeWithRelations(relations);
+        const missing = normalized.filter((entry) => this.items.some((model) => !relationLoaded(model, entry.name)));
+        if (missing.length === 0)
+            return this;
+        if (this.isEmpty())
+            return this;
+        const { eagerLoadModels } = await import("./model.js");
+        await eagerLoadModels(this.all(), missing);
+        return this;
+    }
+    /** Laravel `$collection->loadCount(...)` — batched GROUP BY per relation. */
+    async loadCount(...relations) {
+        return this.#loadAggregates(relations.flat().map((raw) => {
+            const parsed = parseRelationAlias(raw);
+            return {
+                relation: parsed.relation,
+                alias: parsed.alias ?? `${parsed.relation}_count`,
+                fn: "count",
+            };
+        }));
+    }
+    async loadSum(relation, column) {
+        const parsed = parseRelationAlias(relation);
+        return this.#loadAggregates([
+            {
+                relation: parsed.relation,
+                alias: parsed.alias ?? `${parsed.relation}_sum_${column}`,
+                fn: "sum",
+                column,
+            },
+        ]);
+    }
+    async loadAvg(relation, column) {
+        const parsed = parseRelationAlias(relation);
+        return this.#loadAggregates([
+            {
+                relation: parsed.relation,
+                alias: parsed.alias ?? `${parsed.relation}_avg_${column}`,
+                fn: "avg",
+                column,
+            },
+        ]);
+    }
+    async loadMin(relation, column) {
+        const parsed = parseRelationAlias(relation);
+        return this.#loadAggregates([
+            {
+                relation: parsed.relation,
+                alias: parsed.alias ?? `${parsed.relation}_min_${column}`,
+                fn: "min",
+                column,
+            },
+        ]);
+    }
+    async loadMax(relation, column) {
+        const parsed = parseRelationAlias(relation);
+        return this.#loadAggregates([
+            {
+                relation: parsed.relation,
+                alias: parsed.alias ?? `${parsed.relation}_max_${column}`,
+                fn: "max",
+                column,
+            },
+        ]);
+    }
+    async loadExists(...relations) {
+        return this.#loadAggregates(relations.flat().map((raw) => {
+            const parsed = parseRelationAlias(raw);
+            return {
+                relation: parsed.relation,
+                alias: parsed.alias ?? `${parsed.relation}_exists`,
+                fn: "exists",
+            };
+        }));
+    }
+    async #loadAggregates(specs) {
+        if (specs.length === 0 || this.isEmpty())
+            return this;
+        const { eagerLoadAggregates } = await import("./model.js");
+        await eagerLoadAggregates(this.all(), specs);
+        return this;
+    }
+    /** Primary keys of all models. */
+    modelKeys() {
+        return this.map((model) => {
+            const ctor = model.constructor;
+            return model[ctor.primaryKey];
+        });
+    }
+    find(key) {
+        if (Array.isArray(key)) {
+            const want = new Set(key.map(String));
+            return this.make(this.items.filter((model) => {
+                const ctor = model.constructor;
+                const id = model[ctor.primaryKey];
+                return want.has(String(id));
+            }));
+        }
+        const want = String(key);
+        return (this.items.find((model) => {
+            const ctor = model.constructor;
+            const id = model[ctor.primaryKey];
+            return String(id) === want;
+        }) ?? null);
+    }
+    findOrFail(key) {
+        const model = this.find(key);
+        if (!model) {
+            throw new Error(`No query results for model [${String(key)}].`);
+        }
+        return model;
+    }
+}

package/dist/pivot.d.ts

@@ -0,0 +1,9 @@
+import { Model } from "./model.js";
+/**
+ * Intermediate table model (`product_categories`, `model_has_roles`, …).
+ * Composite / non-incrementing keys — `create()` inserts without `RETURNING id`.
+ */
+export declare class Pivot extends Model {
+    static incrementing: boolean;
+    static timestamps: boolean;
+}

package/dist/pivot.js

@@ -0,0 +1,9 @@
+import { Model } from "./model.js";
+/**
+ * Intermediate table model (`product_categories`, `model_has_roles`, …).
+ * Composite / non-incrementing keys — `create()` inserts without `RETURNING id`.
+ */
+export class Pivot extends Model {
+    static incrementing = false;
+    static timestamps = false;
+}

package/dist/relations.d.ts

@@ -0,0 +1,335 @@
+import { OrmCollection } from "./orm-collection.js";
+import { Model, type ModelClass } from "./model.js";
+import type { ModelQuery } from "./model-query.js";
+/** ModelQuery methods that mutate the builder and return it — forwarded onto relations. */
+declare const RELATION_QUERY_CHAIN: readonly ["where", "orWhere", "whereIn", "whereNotIn", "whereNull", "whereNotNull", "whereBetween", "whereNotBetween", "whereColumn", "whereRaw", "orWhereRaw", "whereLike", "whereDate", "orderBy", "orderByDesc", "orderByRaw", "latest", "oldest", "limit", "offset", "take", "skip", "forPage", "select", "addSelect", "selectRaw", "groupBy", "having", "havingRaw", "when", "unless", "tap"];
+/** ModelQuery methods that return a value — forwarded onto relations. */
+declare const RELATION_QUERY_TERMINAL: readonly ["count", "exists", "sum", "avg", "min", "max", "toSql", "toRawSql", "getBindings"];
+/** Write terminals, forwarded only onto relations that filter one table by a foreign key. */
+declare const RELATION_QUERY_WRITE: readonly ["update", "delete", "forceDelete"];
+type RelationQueryKey = (typeof RELATION_QUERY_CHAIN)[number] | (typeof RELATION_QUERY_TERMINAL)[number];
+type RelationWriteKey = (typeof RELATION_QUERY_WRITE)[number];
+/** Types for the methods `installRelationQueryForwarders` adds to every relation. */
+type RelationQuery<T extends Model> = Pick<ModelQuery<T>, RelationQueryKey>;
+type RelationWrite<T extends Model> = Pick<ModelQuery<T>, RelationWriteKey>;
+/** Strip `__pivot_*` columns onto `model.pivot`. */
+export declare function applyPivotAttributes(model: Model, attrs: Record<string, unknown>, pivotKeys: string[]): Model;
+export declare function morphMap(map: Record<string, ModelClass>): void;
+export declare function clearMorphMap(): void;
+export declare function morphTypeFor(model: ModelClass): string;
+export declare function resolveMorphType(type: string): ModelClass;
+/** MorphMany relation. */
+export declare class MorphMany<T extends Model = Model> {
+    #private;
+    private parent;
+    private related;
+    private typeColumn;
+    private idColumn;
+    private morphType;
+    private localKey?;
+    constructor(parent: Model, related: ModelClass, typeColumn: string, idColumn: string, morphType: string, localKey?: string | undefined);
+    getRelated(): ModelClass;
+    getTypeColumn(): string;
+    getIdColumn(): string;
+    getMorphType(): string;
+    getLocalKeyName(): string;
+    /** Constrained related query (`morphMany().where(…).get()`). */
+    getQuery(): ModelQuery<T>;
+    get(): Promise<OrmCollection<T>>;
+    first(): Promise<T | null>;
+    create(attributes: Record<string, unknown>): Promise<T>;
+}
+/** MorphOne relation. */
+export declare class MorphOne<T extends Model = Model> {
+    #private;
+    private parent;
+    private related;
+    private typeColumn;
+    private idColumn;
+    private morphType;
+    private localKey?;
+    constructor(parent: Model, related: ModelClass, typeColumn: string, idColumn: string, morphType: string, localKey?: string | undefined);
+    getRelated(): ModelClass;
+    getTypeColumn(): string;
+    getIdColumn(): string;
+    getMorphType(): string;
+    getLocalKeyName(): string;
+    isOfMany(): boolean;
+    getOfManyColumn(): string | undefined;
+    getOfManyAggregate(): "min" | "max" | undefined;
+    latestOfMany(column?: string): this;
+    oldestOfMany(column?: string): this;
+    ofMany(column: string, aggregate: "min" | "max"): this;
+    getQuery(): ModelQuery<T>;
+    get(): Promise<T | null>;
+    first(): Promise<T | null>;
+    create(attributes: Record<string, unknown>): Promise<T>;
+}
+/** Laravel MorphTo relation. */
+export declare class MorphTo {
+    private parent;
+    private typeColumn;
+    private idColumn;
+    private ownerKey?;
+    constructor(parent: Model, typeColumn: string, idColumn: string, ownerKey?: string | undefined);
+    getTypeColumn(): string;
+    getIdColumn(): string;
+    getOwnerKeyName(): string | undefined;
+    get(): Promise<Model | null>;
+    first(): Promise<Model | null>;
+    /** Laravel `associate` for morphTo. */
+    associate(model: Model): this;
+    /** Laravel `dissociate` for morphTo. */
+    dissociate(): this;
+}
+/** HasMany relation. */
+export declare class HasMany<T extends Model = Model> {
+    #private;
+    private parent;
+    private related;
+    private foreignKey;
+    private localKey?;
+    constructor(parent: Model, related: ModelClass, foreignKey: string, localKey?: string | undefined);
+    getRelated(): ModelClass;
+    getForeignKeyName(): string;
+    getLocalKeyName(): string;
+    /** Constrained related query (`hasMany().where(…).orderBy(…).get()`). */
+    getQuery(): ModelQuery<T>;
+    get(): Promise<OrmCollection<T>>;
+    first(): Promise<T | null>;
+    create(attributes: Record<string, unknown>): Promise<T>;
+    /** Bump `updated_at` on matching related rows. */
+    touch(): Promise<boolean>;
+}
+/** HasOne relation. */
+export declare class HasOne<T extends Model = Model> {
+    #private;
+    private parent;
+    private related;
+    private foreignKey;
+    private localKey?;
+    constructor(parent: Model, related: ModelClass, foreignKey: string, localKey?: string | undefined);
+    getRelated(): ModelClass;
+    getForeignKeyName(): string;
+    getLocalKeyName(): string;
+    isOfMany(): boolean;
+    getOfManyColumn(): string | undefined;
+    getOfManyAggregate(): "min" | "max" | undefined;
+    /** Latest related row by column (default primary key). */
+    latestOfMany(column?: string): this;
+    /** Oldest related row by column (default primary key). */
+    oldestOfMany(column?: string): this;
+    /** Constrain to the related row with min/max of `column`. */
+    ofMany(column: string, aggregate: "min" | "max"): this;
+    getQuery(): ModelQuery<T>;
+    get(): Promise<T | null>;
+    first(): Promise<T | null>;
+    create(attributes: Record<string, unknown>): Promise<T>;
+    /** Bump `updated_at` on matching related rows. */
+    touch(): Promise<boolean>;
+}
+/** HasManyThrough relation (Parent → Through → Related). */
+export declare class HasManyThrough<T extends Model = Model> {
+    #private;
+    private parent;
+    private related;
+    private through;
+    private firstKey;
+    private secondKey;
+    private localKey;
+    private secondLocalKey;
+    constructor(parent: Model, related: ModelClass, through: ModelClass, firstKey: string, secondKey: string, localKey: string, secondLocalKey: string);
+    getRelated(): ModelClass;
+    getThrough(): ModelClass;
+    getFirstKeyName(): string;
+    getSecondKeyName(): string;
+    getLocalKeyName(): string;
+    getSecondLocalKeyName(): string;
+    getQuery(): ModelQuery<T>;
+    get(): Promise<OrmCollection<T>>;
+    first(): Promise<T | null>;
+}
+/**
+ * HasOneThrough — same join as HasManyThrough, returns a single related model.
+ */
+export declare class HasOneThrough<T extends Model = Model> {
+    #private;
+    constructor(parent: Model, related: ModelClass, through: ModelClass, firstKey: string, secondKey: string, localKey: string, secondLocalKey: string);
+    getRelated(): ModelClass;
+    getThrough(): ModelClass;
+    getFirstKeyName(): string;
+    getSecondKeyName(): string;
+    getLocalKeyName(): string;
+    getSecondLocalKeyName(): string;
+    /** Underlying many-through relation (for eager load reuse). */
+    asHasManyThrough(): HasManyThrough<T>;
+    getQuery(): ModelQuery<T>;
+    get(): Promise<T | null>;
+    first(): Promise<T | null>;
+}
+/** BelongsTo relation. */
+export declare class BelongsTo<T extends Model = Model> {
+    #private;
+    private child;
+    private related;
+    private foreignKey;
+    private ownerKey?;
+    constructor(child: Model, related: ModelClass, foreignKey: string, ownerKey?: string | undefined);
+    getRelated(): ModelClass;
+    getForeignKeyName(): string;
+    getOwnerKeyName(): string;
+    getQuery(): ModelQuery<T>;
+    get(): Promise<T | null>;
+    first(): Promise<T | null>;
+    /** Set the foreign key from a related model (or null). */
+    associate(model: T | null): this;
+    /** Clear the foreign key. */
+    dissociate(): this;
+    /**
+     * Bump related parent's `updated_at` (query update).
+     * Honors `Model.withoutTouching` / `isIgnoringTouch` on the related class.
+     */
+    touch(): Promise<boolean>;
+    /** Sync variant for Model sync-persist path. */
+    touchSync(): boolean;
+}
+/** BelongsToMany relation. */
+export declare class BelongsToMany<T extends Model = Model> {
+    #private;
+    private parent;
+    private related;
+    private pivotTable;
+    private foreignPivotKey;
+    private relatedPivotKey;
+    constructor(parent: Model, related: ModelClass, pivotTable: string, foreignPivotKey: string, relatedPivotKey: string);
+    getRelated(): ModelClass;
+    getPivotTable(): string;
+    getForeignPivotKeyName(): string;
+    getRelatedPivotKeyName(): string;
+    getPivotColumns(): string[];
+    /** Include extra pivot table columns on related models as `model.pivot`. */
+    withPivot(...columns: Array<string | string[]>): this;
+    getQuery(): ModelQuery<T>;
+    get(): Promise<OrmCollection<T>>;
+    first(): Promise<T | null>;
+    attach(ids: Array<string | number> | string | number): Promise<void>;
+    detach(ids?: Array<string | number> | string | number): Promise<void>;
+    sync(ids: Array<string | number>): Promise<void>;
+    /** Attach missing ids only. */
+    syncWithoutDetaching(ids: Array<string | number>): Promise<void>;
+    /** Attach missing, detach present. */
+    toggle(ids: Array<string | number> | string | number): Promise<void>;
+}
+/** Options for `morphToMany` beyond the Laravel positional args. */
+export type MorphToManyOptions = {
+    table?: string;
+    foreignPivotKey?: string;
+    relatedPivotKey?: string;
+    morphTypeColumn?: string;
+    /** Pivot `model_type` values matched (includes legacy aliases). */
+    morphTypes?: string[];
+    /** Tenant column on the pivot table (when set, rows are tenant-scoped). */
+    pivotTenantKey?: string;
+    /**
+     * Tenant column on the parent model.
+     * Defaults to `pivotTenantKey` when omitted.
+     */
+    parentTenantKey?: string;
+};
+/** Polymorphic many-to-many (e.g. Contact → Role via `model_has_roles`). */
+export declare class MorphToMany<T extends Model = Model> {
+    #private;
+    private parent;
+    private related;
+    private pivotTable;
+    private foreignPivotKey;
+    private relatedPivotKey;
+    private morphTypeColumn;
+    private morphTypes;
+    private pivotTenantKey?;
+    private parentTenantKey?;
+    constructor(parent: Model, related: ModelClass, pivotTable: string, foreignPivotKey: string, relatedPivotKey: string, morphTypeColumn: string, morphTypes: string[], pivotTenantKey?: string | undefined, parentTenantKey?: string | undefined);
+    getRelated(): ModelClass;
+    getPivotTable(): string;
+    getForeignPivotKeyName(): string;
+    getRelatedPivotKeyName(): string;
+    getMorphTypeColumn(): string;
+    getMorphTypes(): string[];
+    getPivotTenantKey(): string | undefined;
+    getParentTenantKey(): string | undefined;
+    /** Primary morph type written on attach (first configured type). */
+    getMorphType(): string;
+    get(): Promise<OrmCollection<T>>;
+    attach(ids: Array<string | number> | string | number): Promise<void>;
+    detach(ids?: Array<string | number> | string | number): Promise<void>;
+    sync(ids: Array<string | number>): Promise<void>;
+    syncWithoutDetaching(ids: Array<string | number>): Promise<void>;
+    toggle(ids: Array<string | number> | string | number): Promise<void>;
+}
+export type RelationMeta = {
+    kind: "has";
+    related: ModelClass;
+    foreignKey: string;
+    localKey: string;
+} | {
+    kind: "belongsTo";
+    related: ModelClass;
+    foreignKey: string;
+    ownerKey: string;
+} | {
+    kind: "belongsToMany";
+    related: ModelClass;
+    pivotTable: string;
+    foreignPivotKey: string;
+    relatedPivotKey: string;
+    localKey: string;
+    pivotColumns: string[];
+} | {
+    kind: "morphToMany";
+    related: ModelClass;
+    pivotTable: string;
+    foreignPivotKey: string;
+    relatedPivotKey: string;
+    localKey: string;
+    morphTypeColumn: string;
+    morphTypes: string[];
+    pivotTenantKey?: string;
+    parentTenantKey?: string;
+} | {
+    kind: "hasManyThrough";
+    related: ModelClass;
+    through: ModelClass;
+    firstKey: string;
+    secondKey: string;
+    localKey: string;
+    secondLocalKey: string;
+} | {
+    kind: "hasOneThrough";
+    related: ModelClass;
+    through: ModelClass;
+    firstKey: string;
+    secondKey: string;
+    localKey: string;
+    secondLocalKey: string;
+};
+export declare function resolveRelation(model: ModelClass, relation: string): RelationMeta | null;
+export declare function countRelation(model: Model, relation: string): Promise<number>;
+/** Run COUNT/SUM/AVG/MIN/MAX/EXISTS for a relation on one model instance. */
+export declare function aggregateRelation(model: Model, relation: string, fn: "count" | "sum" | "avg" | "min" | "max" | "exists", column?: string): Promise<unknown>;
+export interface HasMany<T extends Model = Model> extends RelationQuery<T>, RelationWrite<T> {
+}
+export interface HasOne<T extends Model = Model> extends RelationQuery<T>, RelationWrite<T> {
+}
+export interface MorphMany<T extends Model = Model> extends RelationQuery<T>, RelationWrite<T> {
+}
+export interface MorphOne<T extends Model = Model> extends RelationQuery<T>, RelationWrite<T> {
+}
+export interface HasManyThrough<T extends Model = Model> extends RelationQuery<T> {
+}
+export interface HasOneThrough<T extends Model = Model> extends RelationQuery<T> {
+}
+export interface BelongsTo<T extends Model = Model> extends RelationQuery<T> {
+}
+export interface BelongsToMany<T extends Model = Model> extends RelationQuery<T> {
+}
+export {};