@warlock.js/cascade 4.0.171 → 4.1.1

package/esm/relations/pivot-operations.mjs

@@ -0,0 +1,232 @@
+import { resolveModelClass, resolveModelName } from "../model/register-model.mjs";
+import { inferPivotKey, inferPivotTable } from "./key-conventions.mjs";
+
+//#region ../../@warlock.js/cascade/src/relations/pivot-operations.ts
+/**
+* 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]);
+* ```
+*/
+var PivotOperations = class {
+	/**
+	* 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;
+	/**
+	* 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}".`);
+		this.model = model;
+		this.relationName = relationName;
+		this.definition = definition;
+		this.modelClass = modelClass;
+	}
+	/**
+	* Read the configured relation conventions from this pivot's owning
+	* data source. Returns `undefined` when no overrides are set.
+	*/
+	get relationDefaults() {
+		try {
+			return this.modelClass.getDataSource()?.relationDefaults;
+		} catch {
+			return;
+		}
+	}
+	/**
+	* 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();
+		const existingIds = await this.getExistingPivotIds();
+		const newIds = ids.filter((id) => !existingIds.has(id));
+		if (newIds.length === 0) return;
+		const records = newIds.map((id) => ({
+			[pivotLocalKey]: localKeyValue,
+			[pivotForeignKey]: id,
+			...pivotData
+		}));
+		await this.modelClass.getDataSource().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();
+		const filter = { [pivotLocalKey]: localKeyValue };
+		if (ids && ids.length > 0) 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);
+		const toDetach = [];
+		for (const existingId of existingIds) if (!newIdSet.has(existingId)) toDetach.push(existingId);
+		const toAttach = ids.filter((id) => !existingIds.has(id));
+		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);
+	}
+	/**
+	* Gets the pivot table configuration.
+	*
+	* @returns The pivot configuration object
+	*/
+	getPivotConfig() {
+		const conventions = this.relationDefaults;
+		const relatedModelName = resolveModelName(this.definition.model);
+		const pivotTable = this.definition.pivot ?? inferPivotTable(this.modelClass.name, relatedModelName, conventions);
+		const RelatedModel = resolveModelClass(this.definition.model);
+		const localKey = this.definition.pivotLocalKey ?? this.modelClass.primaryKey ?? "id";
+		const pivotLocalKey = this.definition.localKey ?? inferPivotKey(this.modelClass.name, conventions);
+		const pivotForeignKey = this.definition.foreignKey ?? inferPivotKey(relatedModelName, conventions);
+		const relatedKey = this.definition.pivotForeignKey ?? RelatedModel?.primaryKey ?? "id";
+		return {
+			pivotTable,
+			localKeyValue: this.model.get(localKey),
+			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 records = await this.modelClass.getDataSource().driver.queryBuilder(pivotTable).select([pivotForeignKey]).where(pivotLocalKey, localKeyValue).get();
+		const ids = /* @__PURE__ */ new Set();
+		for (const record of records) {
+			const id = record[pivotForeignKey];
+			if (id !== void 0 && id !== null) ids.add(id);
+		}
+		return ids;
+	}
+};
+/**
+* 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);
+}
+
+//#endregion
+export { PivotOperations, createPivotOperations };
+//# sourceMappingURL=pivot-operations.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pivot-operations.mjs","names":[],"sources":["../../../../../../@warlock.js/cascade/src/relations/pivot-operations.ts"],"sourcesContent":["/**\n * @fileoverview Pivot table operations for many-to-many relationships.\n *\n * This module provides methods for managing the pivot table in\n * belongsToMany relationships: attach, detach, sync, and toggle.\n *\n * @module @warlock.js/cascade/relations/pivot-operations\n */\n\nimport type { ChildModel, Model } from \"../model/model\";\nimport { resolveModelClass, resolveModelName } from \"../model/register-model\";\nimport { inferPivotKey, inferPivotTable } from \"./key-conventions\";\nimport type { PivotData, PivotIds, RelationDefinition } from \"./types\";\n\n// ============================================================================\n// PIVOT OPERATIONS CLASS\n// ============================================================================\n\n/**\n * Manages pivot table operations for many-to-many relationships.\n *\n * Provides attach, detach, sync, and toggle operations for managing\n * the connections between two models through a pivot table.\n *\n * @example\n * ```typescript\n * const pivotOps = new PivotOperations(post, \"tags\", tagsDefinition);\n *\n * // Attach tags\n * await pivotOps.attach([1, 2, 3]);\n *\n * // Attach with pivot data\n * await pivotOps.attach([4], { addedBy: userId });\n *\n * // Detach specific tags\n * await pivotOps.detach([2]);\n *\n * // Sync (replace all)\n * await pivotOps.sync([1, 5, 6]);\n *\n * // Toggle (attach if missing, detach if present)\n * await pivotOps.toggle([1, 7]);\n * ```\n */\nexport class PivotOperations {\n  // ==========================================================================\n  // PRIVATE PROPERTIES\n  // ==========================================================================\n\n  /**\n   * The model instance performing the pivot operation.\n   */\n  private readonly model: Model;\n\n  /**\n   * The name of the relation.\n   */\n  private readonly relationName: string;\n\n  /**\n   * The relation definition with pivot table configuration.\n   */\n  private readonly definition: RelationDefinition;\n\n  /**\n   * The model class of the source model.\n   */\n  private readonly modelClass: ChildModel<Model>;\n\n  // ==========================================================================\n  // CONSTRUCTOR\n  // ==========================================================================\n\n  /**\n   * Creates a new PivotOperations instance.\n   *\n   * @param model - The model instance performing the operation\n   * @param relationName - The name of the belongsToMany relation\n   * @param definition - The relation definition\n   * @param modelClass - The model class constructor\n   */\n  public constructor(\n    model: Model,\n    relationName: string,\n    definition: RelationDefinition,\n    modelClass: ChildModel<Model>,\n  ) {\n    if (definition.type !== \"belongsToMany\") {\n      throw new Error(\n        `Pivot operations are only available for belongsToMany relations. ` +\n          `Relation \"${relationName}\" is of type \"${definition.type}\".`,\n      );\n    }\n\n    this.model = model;\n    this.relationName = relationName;\n    this.definition = definition;\n    this.modelClass = modelClass;\n  }\n\n  /**\n   * Read the configured relation conventions from this pivot's owning\n   * data source. Returns `undefined` when no overrides are set.\n   */\n  private get relationDefaults() {\n    try {\n      return this.modelClass.getDataSource()?.relationDefaults;\n    } catch {\n      return undefined;\n    }\n  }\n\n  // ==========================================================================\n  // PUBLIC METHODS\n  // ==========================================================================\n\n  /**\n   * Attaches one or more related models via the pivot table.\n   *\n   * Creates new records in the pivot table linking this model to the\n   * specified related model IDs. Existing attachments are not duplicated.\n   *\n   * @param ids - The IDs of the related models to attach\n   * @param pivotData - Optional additional data to store in the pivot record\n   *\n   * @example\n   * ```typescript\n   * // Attach tags to a post\n   * await post.attach(\"tags\", [1, 2, 3]);\n   *\n   * // Attach with additional pivot data\n   * await post.attach(\"tags\", [4], { addedBy: currentUserId });\n   * ```\n   */\n  public async attach(ids: PivotIds, pivotData?: PivotData): Promise<void> {\n    if (ids.length === 0) return;\n\n    const { pivotTable, localKeyValue, pivotLocalKey, pivotForeignKey } = this.getPivotConfig();\n\n    // Get existing attachments to avoid duplicates\n    const existingIds = await this.getExistingPivotIds();\n    const newIds = ids.filter((id) => !existingIds.has(id));\n\n    if (newIds.length === 0) return;\n\n    // Create pivot records\n    const records = newIds.map((id) => ({\n      [pivotLocalKey]: localKeyValue,\n      [pivotForeignKey]: id,\n      ...pivotData,\n    }));\n\n    const dataSource = this.modelClass.getDataSource();\n    await dataSource.driver.insertMany(pivotTable, records);\n  }\n\n  /**\n   * Detaches one or more related models from the pivot table.\n   *\n   * Removes records from the pivot table. If no IDs are specified,\n   * all attachments for this model are removed.\n   *\n   * @param ids - Optional IDs to detach. If omitted, detaches all.\n   *\n   * @example\n   * ```typescript\n   * // Detach specific tags\n   * await post.detach(\"tags\", [2, 3]);\n   *\n   * // Detach all tags\n   * await post.detach(\"tags\");\n   * ```\n   */\n  public async detach(ids?: PivotIds): Promise<void> {\n    const { pivotTable, localKeyValue, pivotLocalKey, pivotForeignKey } = this.getPivotConfig();\n\n    const dataSource = this.modelClass.getDataSource();\n\n    // Build filter based on local key and optionally foreign keys\n    const filter: Record<string, unknown> = { [pivotLocalKey]: localKeyValue };\n\n    if (ids && ids.length > 0) {\n      // Use $in operator style for filtering by multiple IDs\n      filter[pivotForeignKey] = { $in: ids };\n    }\n\n    await dataSource.driver.deleteMany(pivotTable, filter);\n  }\n\n  /**\n   * Synchronizes the pivot table to match the specified IDs.\n   *\n   * Attaches any new IDs and detaches any IDs not in the list.\n   * After sync, the pivot table will contain exactly the specified IDs.\n   *\n   * @param ids - The IDs that should be attached after sync\n   * @param pivotData - Optional data for newly attached records\n   *\n   * @example\n   * ```typescript\n   * // Set tags to exactly [1, 3, 5], removing any others\n   * await post.sync(\"tags\", [1, 3, 5]);\n   * ```\n   */\n  public async sync(ids: PivotIds, pivotData?: PivotData): Promise<void> {\n    const existingIds = await this.getExistingPivotIds();\n    const newIdSet = new Set(ids);\n\n    // Find IDs to detach (in existing but not in new)\n    const toDetach: PivotIds = [];\n    for (const existingId of existingIds) {\n      if (!newIdSet.has(existingId)) {\n        toDetach.push(existingId);\n      }\n    }\n\n    // Find IDs to attach (in new but not in existing)\n    const toAttach = ids.filter((id) => !existingIds.has(id));\n\n    // Perform operations\n    if (toDetach.length > 0) {\n      await this.detach(toDetach);\n    }\n\n    if (toAttach.length > 0) {\n      await this.attach(toAttach, pivotData);\n    }\n  }\n\n  /**\n   * Toggles the attachment status of the specified IDs.\n   *\n   * For each ID: if attached, detaches it; if not attached, attaches it.\n   *\n   * @param ids - The IDs to toggle\n   * @param pivotData - Optional data for newly attached records\n   *\n   * @example\n   * ```typescript\n   * // Toggle tags - attached become detached, detached become attached\n   * await post.toggle(\"tags\", [1, 4]);\n   * ```\n   */\n  public async toggle(ids: PivotIds, pivotData?: PivotData): Promise<void> {\n    if (ids.length === 0) return;\n\n    const existingIds = await this.getExistingPivotIds();\n\n    const toAttach: PivotIds = [];\n    const toDetach: PivotIds = [];\n\n    for (const id of ids) {\n      if (existingIds.has(id)) {\n        toDetach.push(id);\n      } else {\n        toAttach.push(id);\n      }\n    }\n\n    if (toDetach.length > 0) {\n      await this.detach(toDetach);\n    }\n\n    if (toAttach.length > 0) {\n      await this.attach(toAttach, pivotData);\n    }\n  }\n\n  // ==========================================================================\n  // PRIVATE METHODS\n  // ==========================================================================\n\n  /**\n   * Gets the pivot table configuration.\n   *\n   * @returns The pivot configuration object\n   */\n  private getPivotConfig(): {\n    pivotTable: string;\n    localKeyValue: unknown;\n    pivotLocalKey: string;\n    pivotForeignKey: string;\n    relatedKey: string;\n  } {\n    const conventions = this.relationDefaults;\n    const relatedModelName = resolveModelName(this.definition.model);\n    const pivotTable =\n      this.definition.pivot ??\n      inferPivotTable(this.modelClass.name, relatedModelName, conventions);\n    const RelatedModel = resolveModelClass(this.definition.model);\n    const localKey = this.definition.pivotLocalKey ?? this.modelClass.primaryKey ?? \"id\";\n    const pivotLocalKey =\n      this.definition.localKey ?? inferPivotKey(this.modelClass.name, conventions);\n    const pivotForeignKey =\n      this.definition.foreignKey ?? inferPivotKey(relatedModelName, conventions);\n    const relatedKey = this.definition.pivotForeignKey ?? RelatedModel?.primaryKey ?? \"id\";\n    const localKeyValue = this.model.get(localKey);\n\n    return {\n      pivotTable,\n      localKeyValue,\n      pivotLocalKey,\n      pivotForeignKey,\n      relatedKey,\n    };\n  }\n\n  /**\n   * Gets all currently attached IDs from the pivot table.\n   *\n   * @returns A set of attached foreign key values\n   */\n  private async getExistingPivotIds(): Promise<Set<number | string>> {\n    const { pivotTable, localKeyValue, pivotLocalKey, pivotForeignKey } = this.getPivotConfig();\n\n    const dataSource = this.modelClass.getDataSource();\n    const records = await dataSource.driver\n      .queryBuilder(pivotTable)\n      .select([pivotForeignKey])\n      .where(pivotLocalKey, localKeyValue)\n      .get();\n\n    const ids = new Set<number | string>();\n    for (const record of records as Record<string, unknown>[]) {\n      const id = record[pivotForeignKey];\n      if (id !== undefined && id !== null) {\n        ids.add(id as number | string);\n      }\n    }\n\n    return ids;\n  }\n\n}\n\n// ============================================================================\n// FACTORY FUNCTION\n// ============================================================================\n\n/**\n * Creates a PivotOperations instance for a model and relation.\n *\n * @param model - The model instance\n * @param relationName - The name of the belongsToMany relation\n * @returns A PivotOperations instance\n * @throws Error if the relation is not a belongsToMany or not defined\n */\nexport function createPivotOperations(model: Model, relationName: string): PivotOperations {\n  const ModelClass = model.constructor as ChildModel<Model>;\n  const relations = (ModelClass as unknown as { relations?: Record<string, RelationDefinition> })\n    .relations;\n\n  if (!relations || !relations[relationName]) {\n    throw new Error(`Relation \"${relationName}\" is not defined on model \"${ModelClass.name}\".`);\n  }\n\n  return new PivotOperations(model, relationName, relations[relationName], ModelClass);\n}\n"],"mappings":"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"}

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

@@ -0,0 +1,55 @@
+import { RelationDefinition } from "./types.mjs";
+import { Model } from "../model/model.mjs";
+
+//#region ../../@warlock.js/cascade/src/relations/relation-hydrator.d.ts
+/**
+ * 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
+ */
+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.
+ */
+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);
+ * ```
+ */
+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;
+}
+//#endregion
+export { ModelSnapshot, RelationHydrator, SerializedRelation };
+//# sourceMappingURL=relation-hydrator.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"relation-hydrator.d.mts","names":[],"sources":["../../../../../../@warlock.js/cascade/src/relations/relation-hydrator.ts"],"mappings":";;;;;;;;AA0C8C;AAoB9C;;KA7BY,kBAAA,UAA4B,aAAA,GAAgB,aAAa;;;;;;KAOzD,aAAA;EACV,IAAA,EAAM,MAAA;EACN,SAAA,EAAW,MAAA,SAAe,kBAAA;AAAA;;;;;;;;;AAuCyC;;;;;cAnBxD,gBAAA;;;;;;;;;;;;;;;;SAgBG,OAAA,CACZ,KAAA,EAAO,KAAA,EACP,YAAA,EAAc,MAAA,SAAe,kBAAA,GAC7B,iBAAA,EAAmB,MAAA,SAAe,kBAAA;AAAA"}

package/esm/relations/relation-hydrator.mjs

@@ -0,0 +1,52 @@
+import { resolveModelClass } from "../model/register-model.mjs";
+
+//#region ../../@warlock.js/cascade/src/relations/relation-hydrator.ts
+/**
+* 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);
+* ```
+*/
+var RelationHydrator = class {
+	/**
+	* 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];
+			if (!def) continue;
+			const RelModel = resolveModelClass(def.model);
+			if (!RelModel) continue;
+			let hydrated;
+			if (snapshot === null) hydrated = null;
+			else if (Array.isArray(snapshot)) hydrated = snapshot.map((item) => RelModel.fromSnapshot(item));
+			else hydrated = RelModel.fromSnapshot(snapshot);
+			model.loadedRelations.set(name, hydrated);
+			model[name] = hydrated;
+		}
+	}
+};
+
+//#endregion
+export { RelationHydrator };
+//# sourceMappingURL=relation-hydrator.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"relation-hydrator.mjs","names":[],"sources":["../../../../../../@warlock.js/cascade/src/relations/relation-hydrator.ts"],"sourcesContent":["/**\n * @fileoverview Restores relation data onto model instances from a plain object snapshot.\n *\n * This is the cache-restoration counterpart to RelationLoader (which loads from the DB).\n * It is intentionally decoupled from query execution — it only deals with instantiating\n * related models from already-serialized data.\n *\n * @module @warlock.js/cascade/relations/relation-hydrator\n *\n * @example\n * ```typescript\n * // Restoring a model + its relations from a cache snapshot:\n * const snapshot = await cache.get(key);\n * const chat = Chat.fromSnapshot(snapshot);\n * // chat.unit, chat.organization etc. are fully hydrated Model instances.\n * ```\n */\n\nimport type { ChildModel, Model } from \"../model/model\";\nimport { resolveModelClass } from \"../model/register-model\";\nimport type { RelationDefinition } from \"./types\";\n\n// ============================================================================\n// TYPES\n// ============================================================================\n\n/**\n * The serialized shape of a single relation entry inside a model snapshot.\n * Each value is either:\n * - `null`  — the relation was loaded and resolved to nothing (e.g. belongsTo with no match)\n * - A nested snapshot object `{ data, relations }` — a single related model\n * - An array of nested snapshot objects — a collection relation\n */\nexport type SerializedRelation = null | ModelSnapshot | ModelSnapshot[];\n\n/**\n * The plain-object shape produced by `model.toSnapshot()` and consumed by\n * `Model.fromSnapshot()`. The `relations` map uses the same relation names\n * defined in the model's static `relations` property.\n */\nexport type ModelSnapshot = {\n  data: Record<string, unknown>;\n  relations: Record<string, SerializedRelation>;\n};\n\n// ============================================================================\n// RELATION HYDRATOR CLASS\n// ============================================================================\n\n/**\n * Restores eager-loaded relations from a plain snapshot onto a model instance.\n *\n * Mirrors the interface of RelationLoader but instead of issuing DB queries,\n * it recursively instantiates related models from serialized snapshot data.\n *\n * @example\n * ```typescript\n * // Used internally by Model.fromSnapshot():\n * const model = new Chat(snapshot.data);\n * RelationHydrator.hydrate(model, Chat.relations, snapshot.relations);\n * ```\n */\nexport class RelationHydrator {\n  /**\n   * Hydrate all relations from a snapshot onto `model`.\n   *\n   * - Looks up each relation name in `relationDefs` to find the target model class.\n   * - Recursively calls `fromSnapshot` on nested snapshots so deeply nested\n   *   relations are fully hydrated as well.\n   * - Sets each relation on both `model.loadedRelations` (Map) and as a direct\n   *   property (`model[name]`) to match the behaviour of RelationLoader.\n   * - Intentionally preserves `null` entries — a null relation was explicitly\n   *   loaded and resolved to nothing; this is different from a missing relation.\n   *\n   * @param model - The model instance to attach relations to\n   * @param relationDefs - The static `relations` map from the model class\n   * @param relationsSnapshot - The `relations` portion of a `ModelSnapshot`\n   */\n  public static hydrate(\n    model: Model,\n    relationDefs: Record<string, RelationDefinition>,\n    relationsSnapshot: Record<string, SerializedRelation> | undefined,\n  ): void {\n    if (!relationsSnapshot) return;\n\n    for (const [name, snapshot] of Object.entries(relationsSnapshot)) {\n      const def = relationDefs[name];\n\n      // Relation name not in definition — skip gracefully rather than throwing,\n      // since the snapshot could be from an older schema version.\n      if (!def) continue;\n\n      const RelModel = resolveModelClass(def.model) as ChildModel<Model> | undefined;\n      if (!RelModel) continue;\n\n      let hydrated: Model | Model[] | null;\n\n      if (snapshot === null) {\n        // Explicitly loaded relation that resolved to nothing — keep as null.\n        hydrated = null;\n      } else if (Array.isArray(snapshot)) {\n        // Collection relation (hasMany / belongsToMany)\n        hydrated = snapshot.map((item) => RelModel.fromSnapshot(item));\n      } else {\n        // Single relation (belongsTo / hasOne)\n        hydrated = RelModel.fromSnapshot(snapshot);\n      }\n\n      // Set on the Map for getRelation() / isLoaded() API\n      model.loadedRelations.set(name, hydrated);\n\n      // Set as direct property for convenient access (model.unit, model.posts, …)\n      (model as unknown as Record<string, unknown>)[name] = hydrated;\n    }\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;AA8DA,IAAa,mBAAb,MAA8B;;;;;;;;;;;;;;;;CAgB5B,OAAc,QACZ,OACA,cACA,mBACM;EACN,IAAI,CAAC,mBAAmB;EAExB,KAAK,MAAM,CAAC,MAAM,aAAa,OAAO,QAAQ,iBAAiB,GAAG;GAChE,MAAM,MAAM,aAAa;GAIzB,IAAI,CAAC,KAAK;GAEV,MAAM,WAAW,kBAAkB,IAAI,KAAK;GAC5C,IAAI,CAAC,UAAU;GAEf,IAAI;GAEJ,IAAI,aAAa,MAEf,WAAW;QACN,IAAI,MAAM,QAAQ,QAAQ,GAE/B,WAAW,SAAS,KAAK,SAAS,SAAS,aAAa,IAAI,CAAC;QAG7D,WAAW,SAAS,aAAa,QAAQ;GAI3C,MAAM,gBAAgB,IAAI,MAAM,QAAQ;GAGxC,AAAC,MAA6C,QAAQ;EACxD;CACF;AACF"}

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

@@ -0,0 +1,190 @@
+import { ChildModel } from "../model/model.types.mjs";
+import { RelationConstraints } from "./types.mjs";
+import { Model } from "../model/model.mjs";
+
+//#region ../../@warlock.js/cascade/src/relations/relation-loader.d.ts
+/**
+ * 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),
+ * });
+ * ```
+ */
+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>);
+  /**
+   * Read the configured relation conventions from this model's data
+   * source. Returns `undefined` when no overrides are set — the inference
+   * helpers fall back to framework defaults in that case.
+   */
+  private get relationDefaults();
+  /**
+   * 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;
+  /**
+   * 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;
+}
+//#endregion
+export { RelationLoader };
+//# sourceMappingURL=relation-loader.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"relation-loader.d.mts","names":[],"sources":["../../../../../../@warlock.js/cascade/src/relations/relation-loader.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;AAkpB2B;;;;;;;;;;cAjiBd,cAAA,gBAA8B,KAAA,GAAQ,KAAA;;;;mBAQhC,MAAA;;;;mBAKA,UAAA;;;;;;;cAYE,MAAA,EAAQ,MAAA,IAAU,UAAA,EAAY,UAAA,CAAW,MAAA;;;;;;cAUhD,gBAAA,CAAA;;;;;;;;;;;;;;;;;;;;;EAgCC,IAAA,CACX,SAAA,qBACA,WAAA,GAAc,mBAAA,GACb,OAAA;;;;;;;UA4BW,YAAA;;;;;;;;UA8CA,WAAA;;;;;;;;UA2CA,UAAA;;;;;;;;UAiDA,aAAA;;;;;;;;UA8CA,iBAAA;;;;;;;;UAyFA,mBAAA;;;;;;;UA8CN,mBAAA;;;;;;;;UAWA,iBAAA;;;;;;;UAkCA,qBAAA;;;;;;;UAaA,gBAAA;;;;;;;;UAoBA,OAAA;;;;;;;UAsBA,mBAAA;;;;;;;;UAcA,iBAAA;;;;;;;;UAcA,iBAAA;AAAA"}