@warlock.js/cascade 4.0.92 → 4.0.93

package/esm/relations/pivot-operations.js

@@ -0,0 +1,293 @@
+/**
+ * @fileoverview Pivot table operations for many-to-many relationships.
+ *
+ * This module provides methods for managing the pivot table in
+ * belongsToMany relationships: attach, detach, sync, and toggle.
+ *
+ * @module @warlock.js/cascade/relations/pivot-operations
+ */
+// ============================================================================
+// PIVOT OPERATIONS CLASS
+// ============================================================================
+/**
+ * Manages pivot table operations for many-to-many relationships.
+ *
+ * Provides attach, detach, sync, and toggle operations for managing
+ * the connections between two models through a pivot table.
+ *
+ * @example
+ * ```typescript
+ * const pivotOps = new PivotOperations(post, "tags", tagsDefinition);
+ *
+ * // Attach tags
+ * await pivotOps.attach([1, 2, 3]);
+ *
+ * // Attach with pivot data
+ * await pivotOps.attach([4], { addedBy: userId });
+ *
+ * // Detach specific tags
+ * await pivotOps.detach([2]);
+ *
+ * // Sync (replace all)
+ * await pivotOps.sync([1, 5, 6]);
+ *
+ * // Toggle (attach if missing, detach if present)
+ * await pivotOps.toggle([1, 7]);
+ * ```
+ */
+class PivotOperations {
+    // ==========================================================================
+    // PRIVATE PROPERTIES
+    // ==========================================================================
+    /**
+     * The model instance performing the pivot operation.
+     */
+    model;
+    /**
+     * The name of the relation.
+     */
+    relationName;
+    /**
+     * The relation definition with pivot table configuration.
+     */
+    definition;
+    /**
+     * The model class of the source model.
+     */
+    modelClass;
+    // ==========================================================================
+    // CONSTRUCTOR
+    // ==========================================================================
+    /**
+     * Creates a new PivotOperations instance.
+     *
+     * @param model - The model instance performing the operation
+     * @param relationName - The name of the belongsToMany relation
+     * @param definition - The relation definition
+     * @param modelClass - The model class constructor
+     */
+    constructor(model, relationName, definition, modelClass) {
+        if (definition.type !== "belongsToMany") {
+            throw new Error(`Pivot operations are only available for belongsToMany relations. ` +
+                `Relation "${relationName}" is of type "${definition.type}".`);
+        }
+        if (!definition.pivot) {
+            throw new Error(`Relation "${relationName}" is missing the pivot table configuration.`);
+        }
+        this.model = model;
+        this.relationName = relationName;
+        this.definition = definition;
+        this.modelClass = modelClass;
+    }
+    // ==========================================================================
+    // PUBLIC METHODS
+    // ==========================================================================
+    /**
+     * Attaches one or more related models via the pivot table.
+     *
+     * Creates new records in the pivot table linking this model to the
+     * specified related model IDs. Existing attachments are not duplicated.
+     *
+     * @param ids - The IDs of the related models to attach
+     * @param pivotData - Optional additional data to store in the pivot record
+     *
+     * @example
+     * ```typescript
+     * // Attach tags to a post
+     * await post.attach("tags", [1, 2, 3]);
+     *
+     * // Attach with additional pivot data
+     * await post.attach("tags", [4], { addedBy: currentUserId });
+     * ```
+     */
+    async attach(ids, pivotData) {
+        if (ids.length === 0)
+            return;
+        const { pivotTable, localKeyValue, pivotLocalKey, pivotForeignKey } = this.getPivotConfig();
+        // Get existing attachments to avoid duplicates
+        const existingIds = await this.getExistingPivotIds();
+        const newIds = ids.filter((id) => !existingIds.has(id));
+        if (newIds.length === 0)
+            return;
+        // Create pivot records
+        const records = newIds.map((id) => ({
+            [pivotLocalKey]: localKeyValue,
+            [pivotForeignKey]: id,
+            ...pivotData,
+        }));
+        const dataSource = this.modelClass.getDataSource();
+        await dataSource.driver.insertMany(pivotTable, records);
+    }
+    /**
+     * Detaches one or more related models from the pivot table.
+     *
+     * Removes records from the pivot table. If no IDs are specified,
+     * all attachments for this model are removed.
+     *
+     * @param ids - Optional IDs to detach. If omitted, detaches all.
+     *
+     * @example
+     * ```typescript
+     * // Detach specific tags
+     * await post.detach("tags", [2, 3]);
+     *
+     * // Detach all tags
+     * await post.detach("tags");
+     * ```
+     */
+    async detach(ids) {
+        const { pivotTable, localKeyValue, pivotLocalKey, pivotForeignKey } = this.getPivotConfig();
+        const dataSource = this.modelClass.getDataSource();
+        // Build filter based on local key and optionally foreign keys
+        const filter = { [pivotLocalKey]: localKeyValue };
+        if (ids && ids.length > 0) {
+            // Use $in operator style for filtering by multiple IDs
+            filter[pivotForeignKey] = { $in: ids };
+        }
+        await dataSource.driver.deleteMany(pivotTable, filter);
+    }
+    /**
+     * Synchronizes the pivot table to match the specified IDs.
+     *
+     * Attaches any new IDs and detaches any IDs not in the list.
+     * After sync, the pivot table will contain exactly the specified IDs.
+     *
+     * @param ids - The IDs that should be attached after sync
+     * @param pivotData - Optional data for newly attached records
+     *
+     * @example
+     * ```typescript
+     * // Set tags to exactly [1, 3, 5], removing any others
+     * await post.sync("tags", [1, 3, 5]);
+     * ```
+     */
+    async sync(ids, pivotData) {
+        const existingIds = await this.getExistingPivotIds();
+        const newIdSet = new Set(ids);
+        // Find IDs to detach (in existing but not in new)
+        const toDetach = [];
+        for (const existingId of existingIds) {
+            if (!newIdSet.has(existingId)) {
+                toDetach.push(existingId);
+            }
+        }
+        // Find IDs to attach (in new but not in existing)
+        const toAttach = ids.filter((id) => !existingIds.has(id));
+        // Perform operations
+        if (toDetach.length > 0) {
+            await this.detach(toDetach);
+        }
+        if (toAttach.length > 0) {
+            await this.attach(toAttach, pivotData);
+        }
+    }
+    /**
+     * Toggles the attachment status of the specified IDs.
+     *
+     * For each ID: if attached, detaches it; if not attached, attaches it.
+     *
+     * @param ids - The IDs to toggle
+     * @param pivotData - Optional data for newly attached records
+     *
+     * @example
+     * ```typescript
+     * // Toggle tags - attached become detached, detached become attached
+     * await post.toggle("tags", [1, 4]);
+     * ```
+     */
+    async toggle(ids, pivotData) {
+        if (ids.length === 0)
+            return;
+        const existingIds = await this.getExistingPivotIds();
+        const toAttach = [];
+        const toDetach = [];
+        for (const id of ids) {
+            if (existingIds.has(id)) {
+                toDetach.push(id);
+            }
+            else {
+                toAttach.push(id);
+            }
+        }
+        if (toDetach.length > 0) {
+            await this.detach(toDetach);
+        }
+        if (toAttach.length > 0) {
+            await this.attach(toAttach, pivotData);
+        }
+    }
+    // ==========================================================================
+    // PRIVATE METHODS
+    // ==========================================================================
+    /**
+     * Gets the pivot table configuration.
+     *
+     * @returns The pivot configuration object
+     */
+    getPivotConfig() {
+        const pivotTable = this.definition.pivot;
+        const localKey = this.definition.pivotLocalKey ?? "id";
+        const pivotLocalKey = this.definition.localKey ?? this.inferForeignKey(this.modelClass.name);
+        const pivotForeignKey = this.definition.foreignKey ?? this.inferForeignKey(this.definition.model);
+        const relatedKey = this.definition.pivotForeignKey ?? "id";
+        const localKeyValue = this.model.get(localKey);
+        return {
+            pivotTable,
+            localKeyValue,
+            pivotLocalKey,
+            pivotForeignKey,
+            relatedKey,
+        };
+    }
+    /**
+     * Gets all currently attached IDs from the pivot table.
+     *
+     * @returns A set of attached foreign key values
+     */
+    async getExistingPivotIds() {
+        const { pivotTable, localKeyValue, pivotLocalKey, pivotForeignKey } = this.getPivotConfig();
+        const dataSource = this.modelClass.getDataSource();
+        const records = await dataSource.driver
+            .queryBuilder(pivotTable)
+            .select([pivotForeignKey])
+            .where(pivotLocalKey, localKeyValue)
+            .get();
+        const ids = new Set();
+        for (const record of records) {
+            const id = record[pivotForeignKey];
+            if (id !== undefined && id !== null) {
+                ids.add(id);
+            }
+        }
+        return ids;
+    }
+    /**
+     * Infers a foreign key name from a model name.
+     *
+     * @param modelName - The model class name
+     * @returns The inferred foreign key (e.g., "User" -> "userId")
+     */
+    inferForeignKey(modelName) {
+        return `${modelName.charAt(0).toLowerCase()}${modelName.slice(1)}Id`;
+    }
+}
+// ============================================================================
+// FACTORY FUNCTION
+// ============================================================================
+/**
+ * Creates a PivotOperations instance for a model and relation.
+ *
+ * @param model - The model instance
+ * @param relationName - The name of the belongsToMany relation
+ * @returns A PivotOperations instance
+ * @throws Error if the relation is not a belongsToMany or not defined
+ */
+function createPivotOperations(model, relationName) {
+    const ModelClass = model.constructor;
+    const relations = ModelClass
+        .relations;
+    if (!relations || !relations[relationName]) {
+        throw new Error(`Relation "${relationName}" is not defined on model "${ModelClass.name}".`);
+    }
+    return new PivotOperations(model, relationName, relations[relationName], ModelClass);
+}export{PivotOperations,createPivotOperations};//# sourceMappingURL=pivot-operations.js.map

package/esm/relations/pivot-operations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pivot-operations.js","sources":["../../src/relations/pivot-operations.ts"],"sourcesContent":[null],"names":[],"mappings":"AAAA;;;;;;;AAOG;AAKH;AACA;AACA;AAEA;;;;;;;;;;;;;;;;;;;;;;;;;AAyBG;MACU,eAAe,CAAA;;;;AAK1B;;AAEG;AACc,IAAA,KAAK,CAAQ;AAE9B;;AAEG;AACc,IAAA,YAAY,CAAS;AAEtC;;AAEG;AACc,IAAA,UAAU,CAAqB;AAEhD;;AAEG;AACc,IAAA,UAAU,CAAoB;;;;AAM/C;;;;;;;AAOG;AACH,IAAA,WAAA,CACE,KAAY,EACZ,YAAoB,EACpB,UAA8B,EAC9B,UAA6B,EAAA;AAE7B,QAAA,IAAI,UAAU,CAAC,IAAI,KAAK,eAAe,EAAE;YACvC,MAAM,IAAI,KAAK,CACb,CAAmE,iEAAA,CAAA;AACjE,gBAAA,CAAA,UAAA,EAAa,YAAY,CAAiB,cAAA,EAAA,UAAU,CAAC,IAAI,CAAA,EAAA,CAAI,CAChE,CAAC;AACH,SAAA;AAED,QAAA,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE;AACrB,YAAA,MAAM,IAAI,KAAK,CAAC,aAAa,YAAY,CAAA,2CAAA,CAA6C,CAAC,CAAC;AACzF,SAAA;AAED,QAAA,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;AACnB,QAAA,IAAI,CAAC,YAAY,GAAG,YAAY,CAAC;AACjC,QAAA,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;AAC7B,QAAA,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;KAC9B;;;;AAMD;;;;;;;;;;;;;;;;;AAiBG;AACI,IAAA,MAAM,MAAM,CAAC,GAAa,EAAE,SAAqB,EAAA;AACtD,QAAA,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO;AAE7B,QAAA,MAAM,EAAE,UAAU,EAAE,aAAa,EAAE,aAAa,EAAE,eAAe,EAAE,GAAG,IAAI,CAAC,cAAc,EAAE,CAAC;;AAG5F,QAAA,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC,mBAAmB,EAAE,CAAC;AACrD,QAAA,MAAM,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC,EAAE,KAAK,CAAC,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;AAExD,QAAA,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO;;QAGhC,MAAM,OAAO,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM;YAClC,CAAC,aAAa,GAAG,aAAa;YAC9B,CAAC,eAAe,GAAG,EAAE;AACrB,YAAA,GAAG,SAAS;AACb,SAAA,CAAC,CAAC,CAAC;QAEJ,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC,aAAa,EAAE,CAAC;QACnD,MAAM,UAAU,CAAC,MAAM,CAAC,UAAU,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;KACzD;AAED;;;;;;;;;;;;;;;;AAgBG;IACI,MAAM,MAAM,CAAC,GAAc,EAAA;AAChC,QAAA,MAAM,EAAE,UAAU,EAAE,aAAa,EAAE,aAAa,EAAE,eAAe,EAAE,GAAG,IAAI,CAAC,cAAc,EAAE,CAAC;QAE5F,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC,aAAa,EAAE,CAAC;;QAGnD,MAAM,MAAM,GAA4B,EAAE,CAAC,aAAa,GAAG,aAAa,EAAE,CAAC;AAE3E,QAAA,IAAI,GAAG,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,EAAE;;YAEzB,MAAM,CAAC,eAAe,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC;AACxC,SAAA;QAED,MAAM,UAAU,CAAC,MAAM,CAAC,UAAU,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;KACxD;AAED;;;;;;;;;;;;;;AAcG;AACI,IAAA,MAAM,IAAI,CAAC,GAAa,EAAE,SAAqB,EAAA;AACpD,QAAA,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC,mBAAmB,EAAE,CAAC;AACrD,QAAA,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;;QAG9B,MAAM,QAAQ,GAAa,EAAE,CAAC;AAC9B,QAAA,KAAK,MAAM,UAAU,IAAI,WAAW,EAAE;AACpC,YAAA,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE;AAC7B,gBAAA,QAAQ,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;AAC3B,aAAA;AACF,SAAA;;AAGD,QAAA,MAAM,QAAQ,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC,EAAE,KAAK,CAAC,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;;AAG1D,QAAA,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE;AACvB,YAAA,MAAM,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;AAC7B,SAAA;AAED,QAAA,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE;YACvB,MAAM,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;AACxC,SAAA;KACF;AAED;;;;;;;;;;;;;AAaG;AACI,IAAA,MAAM,MAAM,CAAC,GAAa,EAAE,SAAqB,EAAA;AACtD,QAAA,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO;AAE7B,QAAA,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC,mBAAmB,EAAE,CAAC;QAErD,MAAM,QAAQ,GAAa,EAAE,CAAC;QAC9B,MAAM,QAAQ,GAAa,EAAE,CAAC;AAE9B,QAAA,KAAK,MAAM,EAAE,IAAI,GAAG,EAAE;AACpB,YAAA,IAAI,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE;AACvB,gBAAA,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AACnB,aAAA;AAAM,iBAAA;AACL,gBAAA,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AACnB,aAAA;AACF,SAAA;AAED,QAAA,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE;AACvB,YAAA,MAAM,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;AAC7B,SAAA;AAED,QAAA,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE;YACvB,MAAM,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;AACxC,SAAA;KACF;;;;AAMD;;;;AAIG;IACK,cAAc,GAAA;AAOpB,QAAA,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC,KAAM,CAAC;QAC1C,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,CAAC,aAAa,IAAI,IAAI,CAAC;AACvD,QAAA,MAAM,aAAa,GAAG,IAAI,CAAC,UAAU,CAAC,QAAQ,IAAI,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;AAC7F,QAAA,MAAM,eAAe,GACnB,IAAI,CAAC,UAAU,CAAC,UAAU,IAAI,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;QAC5E,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC,eAAe,IAAI,IAAI,CAAC;QAC3D,MAAM,aAAa,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAE/C,OAAO;YACL,UAAU;YACV,aAAa;YACb,aAAa;YACb,eAAe;YACf,UAAU;SACX,CAAC;KACH;AAED;;;;AAIG;AACK,IAAA,MAAM,mBAAmB,GAAA;AAC/B,QAAA,MAAM,EAAE,UAAU,EAAE,aAAa,EAAE,aAAa,EAAE,eAAe,EAAE,GAAG,IAAI,CAAC,cAAc,EAAE,CAAC;QAE5F,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC,aAAa,EAAE,CAAC;AACnD,QAAA,MAAM,OAAO,GAAG,MAAM,UAAU,CAAC,MAAM;aACpC,YAAY,CAAC,UAAU,CAAC;AACxB,aAAA,MAAM,CAAC,CAAC,eAAe,CAAC,CAAC;AACzB,aAAA,KAAK,CAAC,aAAa,EAAE,aAAa,CAAC;AACnC,aAAA,GAAG,EAAE,CAAC;AAET,QAAA,MAAM,GAAG,GAAG,IAAI,GAAG,EAAmB,CAAC;AACvC,QAAA,KAAK,MAAM,MAAM,IAAI,OAAoC,EAAE;AACzD,YAAA,MAAM,EAAE,GAAG,MAAM,CAAC,eAAe,CAAC,CAAC;AACnC,YAAA,IAAI,EAAE,KAAK,SAAS,IAAI,EAAE,KAAK,IAAI,EAAE;AACnC,gBAAA,GAAG,CAAC,GAAG,CAAC,EAAqB,CAAC,CAAC;AAChC,aAAA;AACF,SAAA;AAED,QAAA,OAAO,GAAG,CAAC;KACZ;AAED;;;;;AAKG;AACK,IAAA,eAAe,CAAC,SAAiB,EAAA;AACvC,QAAA,OAAO,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAA,EAAG,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;KACtE;AACF,CAAA;AAED;AACA;AACA;AAEA;;;;;;;AAOG;AACa,SAAA,qBAAqB,CAAC,KAAY,EAAE,YAAoB,EAAA;AACtE,IAAA,MAAM,UAAU,GAAG,KAAK,CAAC,WAAgC,CAAC;IAC1D,MAAM,SAAS,GAAI,UAA4E;AAC5F,SAAA,SAAS,CAAC;IAEb,IAAI,CAAC,SAAS,IAAI,CAAC,SAAS,CAAC,YAAY,CAAC,EAAE;QAC1C,MAAM,IAAI,KAAK,CAAC,CAAa,UAAA,EAAA,YAAY,CAA8B,2BAAA,EAAA,UAAU,CAAC,IAAI,CAAI,EAAA,CAAA,CAAC,CAAC;AAC7F,KAAA;AAED,IAAA,OAAO,IAAI,eAAe,CAAC,KAAK,EAAE,YAAY,EAAE,SAAS,CAAC,YAAY,CAAC,EAAE,UAAU,CAAC,CAAC;AACvF"}

package/esm/relations/relation-loader.d.ts

@@ -0,0 +1,194 @@
+/**
+ * @fileoverview Core relation loading logic for the Cascade ORM.
+ *
+ * The RelationLoader is responsible for efficiently loading related models
+ * while preventing N+1 query problems through batch loading strategies.
+ *
+ * @module @warlock.js/cascade/relations/relation-loader
+ */
+import type { ChildModel, Model } from "../model/model";
+import type { RelationConstraints } from "./types";
+/**
+ * Efficiently loads relationships for one or more model instances.
+ *
+ * The RelationLoader handles:
+ * - Batch loading to prevent N+1 query problems
+ * - Nested relation loading via dot notation
+ * - Constrained loading with query callbacks
+ * - All relation types (hasOne, hasMany, belongsTo, belongsToMany)
+ *
+ * @template TModel - The type of model being loaded
+ *
+ * @example
+ * ```typescript
+ * const users = await User.query().get();
+ * const loader = new RelationLoader(users, User);
+ *
+ * // Load single relation
+ * await loader.load("posts");
+ *
+ * // Load multiple relations
+ * await loader.load(["posts", "organization"]);
+ *
+ * // Load nested relations
+ * await loader.load("posts.comments.author");
+ *
+ * // Load with constraints
+ * await loader.load("posts", {
+ *   posts: (query) => query.where("isPublished", true),
+ * });
+ * ```
+ */
+export declare class RelationLoader<TModel extends Model = Model> {
+    /**
+     * The model instances to load relations for.
+     */
+    private readonly models;
+    /**
+     * The model class constructor.
+     */
+    private readonly modelClass;
+    /**
+     * Creates a new RelationLoader instance.
+     *
+     * @param models - The model instances to load relations for
+     * @param modelClass - The model class constructor
+     */
+    constructor(models: TModel[], modelClass: ChildModel<TModel>);
+    /**
+     * Loads one or more relations for all model instances.
+     *
+     * @param relations - A single relation name, array of names, or constraints object
+     * @param constraints - Optional constraints to apply to the loading query
+     *
+     * @example
+     * ```typescript
+     * // Single relation
+     * await loader.load("posts");
+     *
+     * // Multiple relations
+     * await loader.load(["posts", "organization"]);
+     *
+     * // With constraints
+     * await loader.load("posts", {
+     *   posts: (query) => query.where("status", "active"),
+     * });
+     * ```
+     */
+    load(relations: string | string[], constraints?: RelationConstraints): Promise<void>;
+    /**
+     * Loads a single relation, handling nested relations via dot notation.
+     *
+     * @param name - The relation name, possibly with dot notation for nesting
+     * @param constraint - Optional constraint callback
+     */
+    private loadRelation;
+    /**
+     * Loads a hasMany relation for all models.
+     *
+     * @param name - The relation name
+     * @param definition - The relation definition
+     * @param constraint - Optional constraint callback
+     */
+    private loadHasMany;
+    /**
+     * Loads a hasOne relation for all models.
+     *
+     * @param name - The relation name
+     * @param definition - The relation definition
+     * @param constraint - Optional constraint callback
+     */
+    private loadHasOne;
+    /**
+     * Loads a belongsTo relation for all models.
+     *
+     * @param name - The relation name
+     * @param definition - The relation definition
+     * @param constraint - Optional constraint callback
+     */
+    private loadBelongsTo;
+    /**
+     * Loads a belongsToMany relation for all models.
+     *
+     * @param name - The relation name
+     * @param definition - The relation definition
+     * @param constraint - Optional constraint callback
+     */
+    private loadBelongsToMany;
+    /**
+     * Loads nested relations recursively.
+     *
+     * @param parentRelation - The name of the parent relation
+     * @param remainingPath - The remaining path segments to load
+     * @param constraint - Optional constraint callback
+     */
+    private loadNestedRelations;
+    /**
+     * Parses a dot-notation relation path into segments.
+     *
+     * @param path - The relation path (e.g., "posts.comments.author")
+     * @returns An array of relation names
+     */
+    private parseNestedRelation;
+    /**
+     * Resolves a model class from the registry by name.
+     *
+     * @param name - The registered model name
+     * @returns The model class constructor
+     * @throws Error if the model is not found in the registry
+     */
+    private resolveModelClass;
+    /**
+     * Gets the relation definition from the model class.
+     *
+     * @param name - The relation name
+     * @returns The relation definition or undefined
+     */
+    private getRelationDefinition;
+    /**
+     * Collects unique key values from all models.
+     *
+     * @param key - The key to collect values for
+     * @returns An array of unique key values
+     */
+    private collectKeyValues;
+    /**
+     * Groups records by a key value.
+     *
+     * @param records - The records to group
+     * @param key - The key to group by
+     * @returns A map of key values to records
+     */
+    private groupBy;
+    /**
+     * Infers a foreign key name from a model name.
+     *
+     * @param modelName - The model class name
+     * @returns The inferred foreign key (e.g., "User" -> "userId")
+     */
+    private inferForeignKey;
+    /**
+     * Sets a relation value on all models using a getter function.
+     *
+     * @param name - The relation name
+     * @param getter - Function that returns the relation value for each model
+     */
+    private setRelationOnModels;
+    /**
+     * Gets a loaded relation from a model instance.
+     *
+     * @param model - The model instance
+     * @param name - The relation name
+     * @returns The loaded relation value or undefined
+     */
+    private getLoadedRelation;
+    /**
+     * Sets a loaded relation on a model instance.
+     *
+     * @param model - The model instance
+     * @param name - The relation name
+     * @param value - The relation value
+     */
+    private setLoadedRelation;
+}
+//# sourceMappingURL=relation-loader.d.ts.map

package/esm/relations/relation-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relation-loader.d.ts","sourceRoot":"","sources":["../../src/relations/relation-loader.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAExD,OAAO,KAAK,EAGV,mBAAmB,EAEpB,MAAM,SAAS,CAAC;AAMjB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,qBAAa,cAAc,CAAC,MAAM,SAAS,KAAK,GAAG,KAAK;IAKtD;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAW;IAElC;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAqB;IAMhD;;;;;OAKG;gBACgB,MAAM,EAAE,MAAM,EAAE,EAAE,UAAU,EAAE,UAAU,CAAC,MAAM,CAAC;IASnE;;;;;;;;;;;;;;;;;;;OAmBG;IACU,IAAI,CACf,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,EAC5B,WAAW,CAAC,EAAE,mBAAmB,GAChC,OAAO,CAAC,IAAI,CAAC;IAsBhB;;;;;OAKG;YACW,YAAY;IAuC1B;;;;;;OAMG;YACW,WAAW;IAoCzB;;;;;;OAMG;YACW,UAAU;IA0CxB;;;;;;OAMG;YACW,aAAa;IAuC3B;;;;;;OAMG;YACW,iBAAiB;IAoF/B;;;;;;OAMG;YACW,mBAAmB;IAwCjC;;;;;OAKG;IACH,OAAO,CAAC,mBAAmB;IAI3B;;;;;;OAMG;IACH,OAAO,CAAC,iBAAiB;IAazB;;;;;OAKG;IACH,OAAO,CAAC,qBAAqB;IAO7B;;;;;OAKG;IACH,OAAO,CAAC,gBAAgB;IAaxB;;;;;;OAMG;IACH,OAAO,CAAC,OAAO;IAgBf;;;;;OAKG;IACH,OAAO,CAAC,eAAe;IAIvB;;;;;OAKG;IACH,OAAO,CAAC,mBAAmB;IAO3B;;;;;;OAMG;IACH,OAAO,CAAC,iBAAiB;IAOzB;;;;;;OAMG;IACH,OAAO,CAAC,iBAAiB;CAe1B"}