@warlock.js/cascade 4.0.157 → 4.0.158

package/esm/relations/pivot-operations.js

@@ -1,293 +0,0 @@
-/**
- * @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

@@ -1 +0,0 @@
-{"version":3,"file":"pivot-operations.js","sources":["../../src/relations/pivot-operations.ts"],"sourcesContent":[null],"names":[],"mappings":"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"}

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

@@ -1,68 +0,0 @@
-/**
- * @fileoverview Restores relation data onto model instances from a plain object snapshot.
- *
- * This is the cache-restoration counterpart to RelationLoader (which loads from the DB).
- * It is intentionally decoupled from query execution — it only deals with instantiating
- * related models from already-serialized data.
- *
- * @module @warlock.js/cascade/relations/relation-hydrator
- *
- * @example
- * ```typescript
- * // Restoring a model + its relations from a cache snapshot:
- * const snapshot = await cache.get(key);
- * const chat = Chat.fromSnapshot(snapshot);
- * // chat.unit, chat.organization etc. are fully hydrated Model instances.
- * ```
- */
-import type { Model } from "../model/model";
-import type { RelationDefinition } from "./types";
-/**
- * The serialized shape of a single relation entry inside a model snapshot.
- * Each value is either:
- * - `null`  — the relation was loaded and resolved to nothing (e.g. belongsTo with no match)
- * - A nested snapshot object `{ data, relations }` — a single related model
- * - An array of nested snapshot objects — a collection relation
- */
-export type SerializedRelation = null | ModelSnapshot | ModelSnapshot[];
-/**
- * The plain-object shape produced by `model.toSnapshot()` and consumed by
- * `Model.fromSnapshot()`. The `relations` map uses the same relation names
- * defined in the model's static `relations` property.
- */
-export type ModelSnapshot = {
-    data: Record<string, unknown>;
-    relations: Record<string, SerializedRelation>;
-};
-/**
- * Restores eager-loaded relations from a plain snapshot onto a model instance.
- *
- * Mirrors the interface of RelationLoader but instead of issuing DB queries,
- * it recursively instantiates related models from serialized snapshot data.
- *
- * @example
- * ```typescript
- * // Used internally by Model.fromSnapshot():
- * const model = new Chat(snapshot.data);
- * RelationHydrator.hydrate(model, Chat.relations, snapshot.relations);
- * ```
- */
-export declare class RelationHydrator {
-    /**
-     * Hydrate all relations from a snapshot onto `model`.
-     *
-     * - Looks up each relation name in `relationDefs` to find the target model class.
-     * - Recursively calls `fromSnapshot` on nested snapshots so deeply nested
-     *   relations are fully hydrated as well.
-     * - Sets each relation on both `model.loadedRelations` (Map) and as a direct
-     *   property (`model[name]`) to match the behaviour of RelationLoader.
-     * - Intentionally preserves `null` entries — a null relation was explicitly
-     *   loaded and resolved to nothing; this is different from a missing relation.
-     *
-     * @param model - The model instance to attach relations to
-     * @param relationDefs - The static `relations` map from the model class
-     * @param relationsSnapshot - The `relations` portion of a `ModelSnapshot`
-     */
-    static hydrate(model: Model, relationDefs: Record<string, RelationDefinition>, relationsSnapshot: Record<string, SerializedRelation> | undefined): void;
-}
-//# sourceMappingURL=relation-hydrator.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"relation-hydrator.d.ts","sourceRoot":"","sources":["../../src/relations/relation-hydrator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAc,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAExD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAMlD;;;;;;GAMG;AACH,MAAM,MAAM,kBAAkB,GAAG,IAAI,GAAG,aAAa,GAAG,aAAa,EAAE,CAAC;AAExE;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;CAC/C,CAAC;AAMF;;;;;;;;;;;;GAYG;AACH,qBAAa,gBAAgB;IAC3B;;;;;;;;;;;;;;OAcG;WACW,OAAO,CACnB,KAAK,EAAE,KAAK,EACZ,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,EAChD,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,GAAG,SAAS,GAChE,IAAI;CAiCR"}

package/esm/relations/relation-hydrator.js

@@ -1,81 +0,0 @@
-import {getModelFromRegistry}from'../model/register-model.js';/**
- * @fileoverview Restores relation data onto model instances from a plain object snapshot.
- *
- * This is the cache-restoration counterpart to RelationLoader (which loads from the DB).
- * It is intentionally decoupled from query execution — it only deals with instantiating
- * related models from already-serialized data.
- *
- * @module @warlock.js/cascade/relations/relation-hydrator
- *
- * @example
- * ```typescript
- * // Restoring a model + its relations from a cache snapshot:
- * const snapshot = await cache.get(key);
- * const chat = Chat.fromSnapshot(snapshot);
- * // chat.unit, chat.organization etc. are fully hydrated Model instances.
- * ```
- */
-// ============================================================================
-// RELATION HYDRATOR CLASS
-// ============================================================================
-/**
- * Restores eager-loaded relations from a plain snapshot onto a model instance.
- *
- * Mirrors the interface of RelationLoader but instead of issuing DB queries,
- * it recursively instantiates related models from serialized snapshot data.
- *
- * @example
- * ```typescript
- * // Used internally by Model.fromSnapshot():
- * const model = new Chat(snapshot.data);
- * RelationHydrator.hydrate(model, Chat.relations, snapshot.relations);
- * ```
- */
-class RelationHydrator {
-    /**
-     * Hydrate all relations from a snapshot onto `model`.
-     *
-     * - Looks up each relation name in `relationDefs` to find the target model class.
-     * - Recursively calls `fromSnapshot` on nested snapshots so deeply nested
-     *   relations are fully hydrated as well.
-     * - Sets each relation on both `model.loadedRelations` (Map) and as a direct
-     *   property (`model[name]`) to match the behaviour of RelationLoader.
-     * - Intentionally preserves `null` entries — a null relation was explicitly
-     *   loaded and resolved to nothing; this is different from a missing relation.
-     *
-     * @param model - The model instance to attach relations to
-     * @param relationDefs - The static `relations` map from the model class
-     * @param relationsSnapshot - The `relations` portion of a `ModelSnapshot`
-     */
-    static hydrate(model, relationDefs, relationsSnapshot) {
-        if (!relationsSnapshot)
-            return;
-        for (const [name, snapshot] of Object.entries(relationsSnapshot)) {
-            const def = relationDefs[name];
-            // Relation name not in definition — skip gracefully rather than throwing,
-            // since the snapshot could be from an older schema version.
-            if (!def)
-                continue;
-            const RelModel = getModelFromRegistry(def.model);
-            if (!RelModel)
-                continue;
-            let hydrated;
-            if (snapshot === null) {
-                // Explicitly loaded relation that resolved to nothing — keep as null.
-                hydrated = null;
-            }
-            else if (Array.isArray(snapshot)) {
-                // Collection relation (hasMany / belongsToMany)
-                hydrated = snapshot.map((item) => RelModel.fromSnapshot(item));
-            }
-            else {
-                // Single relation (belongsTo / hasOne)
-                hydrated = RelModel.fromSnapshot(snapshot);
-            }
-            // Set on the Map for getRelation() / isLoaded() API
-            model.loadedRelations.set(name, hydrated);
-            // Set as direct property for convenient access (model.unit, model.posts, …)
-            model[name] = hydrated;
-        }
-    }
-}export{RelationHydrator};//# sourceMappingURL=relation-hydrator.js.map

package/esm/relations/relation-hydrator.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"relation-hydrator.js","sources":["../../src/relations/relation-hydrator.ts"],"sourcesContent":[null],"names":[],"mappings":"8DAAA;;;;;;;;;;;;;;;;AAgBG;AA6BH;AACA;AACA;AAEA;;;;;;;;;;;;AAYG;MACU,gBAAgB,CAAA;AAC3B;;;;;;;;;;;;;;AAcG;AACI,IAAA,OAAO,OAAO,CACnB,KAAY,EACZ,YAAgD,EAChD,iBAAiE,EAAA;AAEjE,QAAA,IAAI,CAAC,iBAAiB;YAAE,OAAO;AAE/B,QAAA,KAAK,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,iBAAiB,CAAC,EAAE;AAChE,YAAA,MAAM,GAAG,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;;;AAI/B,YAAA,IAAI,CAAC,GAAG;gBAAE,SAAS;YAEnB,MAAM,QAAQ,GAAG,oBAAoB,CAAC,GAAG,CAAC,KAAK,CAAkC,CAAC;AAClF,YAAA,IAAI,CAAC,QAAQ;gBAAE,SAAS;AAExB,YAAA,IAAI,QAAgC,CAAC;YAErC,IAAI,QAAQ,KAAK,IAAI,EAAE;;gBAErB,QAAQ,GAAG,IAAI,CAAC;AACjB,aAAA;AAAM,iBAAA,IAAI,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE;;AAElC,gBAAA,QAAQ,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC;AAChE,aAAA;AAAM,iBAAA;;AAEL,gBAAA,QAAQ,GAAG,QAAQ,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC;AAC5C,aAAA;;YAGD,KAAK,CAAC,eAAe,CAAC,GAAG,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;;AAGzC,YAAA,KAA4C,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC;AAChE,SAAA;KACF;AACF"}

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

@@ -1,194 +0,0 @@
-/**
- * @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

@@ -1 +0,0 @@
-{"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"}