@bunyad/orm 0.2.0-beta.1 → 0.2.0-beta.2

package/dist/relations.d.ts

@@ -12,12 +12,34 @@ 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;
+/**
+ * Strip `__pivot_*` columns onto `model.pivot` (or the `as()` accessor). With
+ * `using(PivotModel)` the pivot is an instance of that model, so its casts and
+ * methods apply.
+ */
+export declare function applyPivotAttributes(model: Model, attrs: Record<string, unknown>, pivotKeys: string[], options?: {
+    accessor?: string;
+    pivotClass?: ModelClass;
+}): Model;
+export declare function registerMorphClass(model: ModelClass): void;
+/**
+ * `Relation::morphMap` — register aliases, or read the current map when called
+ * with no arguments. Pass `merge = false` to replace the existing map.
+ */
+export declare function morphMap(): Record<string, ModelClass>;
+export declare function morphMap(map: Record<string, ModelClass>, merge?: boolean): Record<string, ModelClass>;
+/** `Relation::enforceMorphMap` — register the map and refuse unmapped classes. */
+export declare function enforceMorphMap(map: Record<string, ModelClass>, merge?: boolean): Record<string, ModelClass>;
+/** `Relation::requireMorphMap` — throw when a model without an alias is used polymorphically. */
+export declare function requireMorphMap(required?: boolean): void;
+export declare function requiresMorphMap(): boolean;
 export declare function clearMorphMap(): void;
 export declare function morphTypeFor(model: ModelClass): string;
+/** `Relation::getMorphedModel` — class for an alias, or undefined. */
+export declare function getMorphedModel(type: string): ModelClass | undefined;
 export declare function resolveMorphType(type: string): ModelClass;
+/** `withDefault` support shared by the single-result relations (belongsTo, hasOne, morphOne). */
+export type DefaultSpec<T extends Model> = true | Record<string, unknown> | ((model: T, parent: Model) => void);
 /** MorphMany relation. */
 export declare class MorphMany<T extends Model = Model> {
     #private;
@@ -34,6 +56,13 @@ export declare class MorphMany<T extends Model = Model> {
     getMorphType(): string;
     getLocalKeyName(): string;
     /** Constrained related query (`morphMany().where(…).get()`). */
+    /**
+     * `chaperone($inverse)` — set the parent on every loaded child (`post.user` without a query).
+     * The inverse name defaults to the parent class name in camelCase.
+     */
+    chaperone(inverse?: string): this;
+    /** Property the parent is set on, or `undefined` when `chaperone()` was not called. */
+    getInverse(): string | undefined;
     getQuery(): ModelQuery<T>;
     get(): Promise<OrmCollection<T>>;
     first(): Promise<T | null>;
@@ -60,6 +89,11 @@ export declare class MorphOne<T extends Model = Model> {
     latestOfMany(column?: string): this;
     oldestOfMany(column?: string): this;
     ofMany(column: string, aggregate: "min" | "max"): this;
+    /** `withDefault` — return an empty related model instead of `null` when nothing matches. */
+    withDefault(spec?: DefaultSpec<T>): this;
+    hasDefault(): boolean;
+    /** The default model for the owner this relation was built from. */
+    makeDefault(): T;
     getQuery(): ModelQuery<T>;
     get(): Promise<T | null>;
     first(): Promise<T | null>;
@@ -94,6 +128,13 @@ export declare class HasMany<T extends Model = Model> {
     getForeignKeyName(): string;
     getLocalKeyName(): string;
     /** Constrained related query (`hasMany().where(…).orderBy(…).get()`). */
+    /**
+     * `chaperone($inverse)` — set the parent on every loaded child (`post.user` without a query).
+     * The inverse name defaults to the parent class name in camelCase.
+     */
+    chaperone(inverse?: string): this;
+    /** Property the parent is set on, or `undefined` when `chaperone()` was not called. */
+    getInverse(): string | undefined;
     getQuery(): ModelQuery<T>;
     get(): Promise<OrmCollection<T>>;
     first(): Promise<T | null>;
@@ -121,6 +162,18 @@ export declare class HasOne<T extends Model = Model> {
     oldestOfMany(column?: string): this;
     /** Constrain to the related row with min/max of `column`. */
     ofMany(column: string, aggregate: "min" | "max"): this;
+    /** `withDefault` — return an empty related model instead of `null` when nothing matches. */
+    withDefault(spec?: DefaultSpec<T>): this;
+    hasDefault(): boolean;
+    /** The default model for the owner this relation was built from. */
+    makeDefault(): T;
+    /**
+     * `chaperone($inverse)` — set the parent on every loaded child (`post.user` without a query).
+     * The inverse name defaults to the parent class name in camelCase.
+     */
+    chaperone(inverse?: string): this;
+    /** Property the parent is set on, or `undefined` when `chaperone()` was not called. */
+    getInverse(): string | undefined;
     getQuery(): ModelQuery<T>;
     get(): Promise<T | null>;
     first(): Promise<T | null>;
@@ -178,6 +231,11 @@ export declare class BelongsTo<T extends Model = Model> {
     getRelated(): ModelClass;
     getForeignKeyName(): string;
     getOwnerKeyName(): string;
+    /** `withDefault` — return an empty related model instead of `null` when nothing matches. */
+    withDefault(spec?: DefaultSpec<T>): this;
+    hasDefault(): boolean;
+    /** The default model for the owner this relation was built from. */
+    makeDefault(): T;
     getQuery(): ModelQuery<T>;
     get(): Promise<T | null>;
     first(): Promise<T | null>;
@@ -194,6 +252,38 @@ export declare class BelongsTo<T extends Model = Model> {
     touchSync(): boolean;
 }
 /** BelongsToMany relation. */
+/**
+ * Point `child[inverse]` at its parent without making it enumerable: a back-reference
+ * must not be serialized (`toJSON`) or treated as an attribute, or parent → child → parent recurses.
+ */
+export declare function setInverse(child: unknown, inverse: string, parent: Model): void;
+/** `wherePivot*` constraints on a many-to-many pivot table (AND only). */
+export type PivotWhere = {
+    kind: "basic";
+    column: string;
+    op: string;
+    value: unknown;
+} | {
+    kind: "in";
+    column: string;
+    values: unknown[];
+    not: boolean;
+} | {
+    kind: "null";
+    column: string;
+    not: boolean;
+} | {
+    kind: "between";
+    column: string;
+    values: [unknown, unknown];
+    not: boolean;
+};
+export type PivotOrder = {
+    column: string;
+    direction: "asc" | "desc";
+};
+/** Apply pivot wheres to a ModelQuery / QueryBuilder, qualified with the pivot table. */
+export declare function applyPivotWheres(q: unknown, pivotTable: string, wheres: readonly PivotWhere[]): void;
 export declare class BelongsToMany<T extends Model = Model> {
     #private;
     private parent;
@@ -212,13 +302,58 @@ export declare class BelongsToMany<T extends Model = Model> {
     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>;
+    /** `withTimestamps` — stamp `created_at` / `updated_at` on pivot writes. */
+    withTimestamps(): this;
+    /** `as('membership')` — expose the pivot under another property name than `pivot`. */
+    as(accessor: string): this;
+    /**
+     * `using(MembershipPivot)` — hydrate the pivot as a model (casts and methods apply)
+     * and run pivot writes (`attach`, `sync`, `updateExistingPivot`) through its "set" casts.
+     */
+    using(pivotClass: ModelClass): this;
+    getPivotAccessor(): string;
+    getPivotClass(): ModelClass | undefined;
+    getPivotWheres(): PivotWhere[];
+    getPivotOrders(): PivotOrder[];
+    /**
+     * `wherePivot` — constrain the pivot row. Also scopes `attach` defaults, `sync`,
+     * `detach` and `updateExistingPivot`, so two relations on one pivot table with
+     * different `wherePivot` values stay independent.
+     */
+    wherePivot(column: string, value: unknown): this;
+    wherePivot(column: string, op: string, value: unknown): this;
+    wherePivotIn(column: string, values: unknown[]): this;
+    wherePivotNotIn(column: string, values: unknown[]): this;
+    wherePivotNull(column: string): this;
+    wherePivotNotNull(column: string): this;
+    wherePivotBetween(column: string, values: [unknown, unknown]): this;
+    wherePivotNotBetween(column: string, values: [unknown, unknown]): this;
+    /** `orderByPivot` — order related rows by a pivot column. */
+    orderByPivot(column: string, direction?: "asc" | "desc"): this;
+    /** `attach` — one multi-row INSERT per chunk; optional pivot attributes. */
+    attach(ids: PivotIds, attributes?: Record<string, unknown>): Promise<void>;
+    /** `detach` — returns the number of deleted pivot rows. */
+    detach(ids?: PivotIds): Promise<number>;
+    /** `updateExistingPivot` — update pivot columns for one related id. Returns affected rows. */
+    updateExistingPivot(id: string | number | Model, attributes: Record<string, unknown>): Promise<number>;
+    /**
+     * `sync` — diff against existing rows: attach new, detach removed, and update
+     * pivot attributes of kept rows when the map form supplies them.
+     */
+    sync(ids: PivotIds, detaching?: boolean): Promise<PivotSyncResult>;
+    /** `syncWithoutDetaching`. */
+    syncWithoutDetaching(ids: PivotIds): Promise<PivotSyncResult>;
+    /** `toggle` — attach missing, detach present. */
+    toggle(ids: PivotIds): Promise<{
+        attached: Array<string | number>;
+        detached: Array<string | number>;
+    }>;
+}
+export type PivotIds = string | number | Model | Array<string | number | Model> | Record<string | number, Record<string, unknown>>;
+export interface PivotSyncResult {
+    attached: Array<string | number>;
+    detached: Array<string | number>;
+    updated: Array<string | number>;
 }
 /** Options for `morphToMany` beyond the positional args. */
 export type MorphToManyOptions = {
@@ -260,8 +395,42 @@ export declare class MorphToMany<T extends Model = Model> {
     /** Primary morph type written on attach (first configured type). */
     getMorphType(): string;
     get(): Promise<OrmCollection<T>>;
+    /** One multi-row INSERT per chunk (was one INSERT per id). */
+    attach(ids: Array<string | number> | string | number): Promise<void>;
+    /** Returns the number of deleted pivot rows. */
+    detach(ids?: Array<string | number> | string | number): Promise<number>;
+    /** Diff-based: keeps existing rows, attaches new ids, detaches removed ones. */
+    sync(ids: Array<string | number>): Promise<PivotSyncResult>;
+    syncWithoutDetaching(ids: Array<string | number>): Promise<PivotSyncResult>;
+    toggle(ids: Array<string | number> | string | number): Promise<{
+        attached: Array<string | number>;
+        detached: Array<string | number>;
+    }>;
+}
+/**
+ * `morphedByMany` — inverse of a `morphToMany` (`taggables` pivot).
+ * Parent is the "tag" side; the pivot stores the related model's id and morph type.
+ */
+export declare class MorphedByMany<T extends Model = Model> {
+    #private;
+    private parent;
+    private related;
+    private pivotTable;
+    private foreignPivotKey;
+    private relatedPivotKey;
+    private morphTypeColumn;
+    private morphType;
+    constructor(parent: Model, related: ModelClass, pivotTable: string, foreignPivotKey: string, relatedPivotKey: string, morphTypeColumn: string, morphType: string);
+    getRelated(): ModelClass;
+    getPivotTable(): string;
+    getForeignPivotKeyName(): string;
+    getRelatedPivotKeyName(): string;
+    getMorphTypeColumn(): string;
+    getMorphType(): string;
+    get(): Promise<OrmCollection<T>>;
     attach(ids: Array<string | number> | string | number): Promise<void>;
-    detach(ids?: Array<string | number> | string | number): Promise<void>;
+    detach(ids?: Array<string | number> | string | number): Promise<number>;
+    /** Detach missing ids, attach new ones; keeps rows that stay */
     sync(ids: Array<string | number>): Promise<void>;
     syncWithoutDetaching(ids: Array<string | number>): Promise<void>;
     toggle(ids: Array<string | number> | string | number): Promise<void>;
@@ -271,6 +440,9 @@ export type RelationMeta = {
     related: ModelClass;
     foreignKey: string;
     localKey: string;
+    /** morphOne / morphMany: the related rows must also carry this morph type. */
+    typeColumn?: string;
+    morphType?: string;
 } | {
     kind: "belongsTo";
     related: ModelClass;
@@ -284,6 +456,7 @@ export type RelationMeta = {
     relatedPivotKey: string;
     localKey: string;
     pivotColumns: string[];
+    pivotWheres: PivotWhere[];
 } | {
     kind: "morphToMany";
     related: ModelClass;
@@ -313,6 +486,9 @@ export type RelationMeta = {
     secondLocalKey: string;
 };
 export declare function resolveRelation(model: ModelClass, relation: string): RelationMeta | null;
+/** Relation metadata for aggregate subqueries (morphOne / morphMany resolve as `has` + morph type). */
+export type AggregateRelationMeta = RelationMeta;
+export declare function resolveAggregateRelation(model: ModelClass, relation: string): AggregateRelationMeta | 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>;