@warlock.js/cascade 4.8.2 → 4.9.1

package/esm/validation/rules/exists-rule.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"exists-rule.mjs","names":[],"sources":["../../../../../../../../@warlock.js/cascade/src/validation/rules/exists-rule.ts"],"sourcesContent":["import { invalidRule, VALID_RULE, type SchemaRule } from \"@warlock.js/seal\";\nimport { resolveModelClass } from \"../../model/register-model\";\nimport type { ExistsRuleOptions } from \"../types\";\n\n/**\n * Validates that a record exists in the database for the given column/value.\n *\n * @example\n * v.string().exists(Organization, { column: \"id\" });\n */\nexport const existsRule: SchemaRule<ExistsRuleOptions> = {\n  name: \"exists\",\n  defaultErrorMessage: \"The :input must exist\",\n  async validate(value: any, context) {\n    const { Model, query, column = context.key } = this.context.options;\n\n    const ResolvedModelClass = resolveModelClass(Model);\n\n    const dbQuery = ResolvedModelClass.query();\n\n    dbQuery.where(column, value);\n\n    if (query) {\n      await query({\n        query: dbQuery,\n        value,\n        allValues: context.allValues,\n      });\n    }\n\n    const document = await dbQuery.first();\n\n    return document ? VALID_RULE : invalidRule(this, context);\n  },\n};\n"],"mappings":";;;;;;;;;;AAUA,MAAa,aAA4C;CACvD,MAAM;CACN,qBAAqB;CACrB,MAAM,SAAS,OAAY,SAAS;EAClC,MAAM,EAAE,OAAO,OAAO,SAAS,QAAQ,QAAQ,KAAK,QAAQ;EAI5D,MAAM,UAFqB,kBAAkB,KAEZ,CAAC,CAAC,MAAM;EAEzC,QAAQ,MAAM,QAAQ,KAAK;EAE3B,IAAI,OACF,MAAM,MAAM;GACV,OAAO;GACP;GACA,WAAW,QAAQ;EACrB,CAAC;EAKH,OAAO,MAFgB,QAAQ,MAAM,IAEnB,aAAa,YAAY,MAAM,OAAO;CAC1D;AACF"}
+{"version":3,"file":"exists-rule.mjs","names":[],"sources":["../../../../../../../../cascade/src/validation/rules/exists-rule.ts"],"sourcesContent":["import { invalidRule, VALID_RULE, type SchemaRule } from \"@warlock.js/seal\";\nimport { resolveModelClass } from \"../../model/register-model\";\nimport type { ExistsRuleOptions } from \"../types\";\n\n/**\n * Validates that a record exists in the database for the given column/value.\n *\n * @example\n * v.string().exists(Organization, { column: \"id\" });\n */\nexport const existsRule: SchemaRule<ExistsRuleOptions> = {\n  name: \"exists\",\n  defaultErrorMessage: \"The :input must exist\",\n  async validate(value: any, context) {\n    const { Model, query, column = context.key } = this.context.options;\n\n    const ResolvedModelClass = resolveModelClass(Model);\n\n    const dbQuery = ResolvedModelClass.query();\n\n    dbQuery.where(column, value);\n\n    if (query) {\n      await query({\n        query: dbQuery,\n        value,\n        allValues: context.allValues,\n      });\n    }\n\n    const document = await dbQuery.first();\n\n    return document ? VALID_RULE : invalidRule(this, context);\n  },\n};\n"],"mappings":";;;;;;;;;;AAUA,MAAa,aAA4C;CACvD,MAAM;CACN,qBAAqB;CACrB,MAAM,SAAS,OAAY,SAAS;EAClC,MAAM,EAAE,OAAO,OAAO,SAAS,QAAQ,QAAQ,KAAK,QAAQ;EAI5D,MAAM,UAFqB,kBAAkB,KAEZ,CAAC,CAAC,MAAM;EAEzC,QAAQ,MAAM,QAAQ,KAAK;EAE3B,IAAI,OACF,MAAM,MAAM;GACV,OAAO;GACP;GACA,WAAW,QAAQ;EACrB,CAAC;EAKH,OAAO,MAFgB,QAAQ,MAAM,IAEnB,aAAa,YAAY,MAAM,OAAO;CAC1D;AACF"}

package/esm/validation/rules/unique-rule.mjs

@@ -2,7 +2,7 @@ import { resolveModelClass } from "../../model/register-model.mjs";
 import { get } from "@mongez/reinforcements";
 import { VALID_RULE, invalidRule } from "@warlock.js/seal";
 
-//#region ../@warlock.js/cascade/src/validation/rules/unique-rule.ts
+//#region ../cascade/src/validation/rules/unique-rule.ts
 /**
 * Validates that a value is unique against a database column.
 *

package/esm/validation/rules/unique-rule.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"unique-rule.mjs","names":[],"sources":["../../../../../../../../@warlock.js/cascade/src/validation/rules/unique-rule.ts"],"sourcesContent":["import { get } from \"@mongez/reinforcements\";\nimport { invalidRule, VALID_RULE, type SchemaRule } from \"@warlock.js/seal\";\nimport { resolveModelClass } from \"../../model/register-model\";\nimport type { UniqueRuleOptions } from \"../types\";\n\n/**\n * Validates that a value is unique against a database column.\n *\n * Supports three exclusion modes:\n * - `except`: read a sibling input's value and exclude rows where that\n *   column equals the sibling's value\n * - `exceptColumnName` + `exceptValue`: exclude rows where the named\n *   column equals the supplied value (used by request-aware wrappers)\n * - Custom `query` callback for anything more involved\n *\n * @example\n * v.email().unique(\"User\");\n * v.string().unique(\"User\", { except: \"id\" });\n */\nexport const uniqueRule: SchemaRule<UniqueRuleOptions> = {\n  name: \"unique\",\n  defaultErrorMessage: \"The :input must be unique\",\n  async validate(value: any, context) {\n    const {\n      Model,\n      except,\n      column = context.key,\n      exceptColumnName,\n      exceptValue,\n      query,\n    } = this.context.options;\n\n    const ResolvedModelClass = resolveModelClass(Model);\n\n    const dbQuery = ResolvedModelClass.query();\n\n    dbQuery.where(column, value);\n\n    if (except) {\n      const exceptVal = get(context.allValues, except);\n\n      if (exceptVal !== undefined) {\n        dbQuery.where(except, \"!=\", exceptVal);\n      }\n    }\n\n    if (exceptColumnName !== undefined) {\n      dbQuery.where(exceptColumnName, \"!=\", exceptValue);\n    }\n\n    if (query) {\n      await query({\n        query: dbQuery,\n        value,\n        allValues: context.allValues,\n      });\n    }\n\n    const document = await dbQuery.first();\n\n    return document ? invalidRule(this, context) : VALID_RULE;\n  },\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;AAmBA,MAAa,aAA4C;CACvD,MAAM;CACN,qBAAqB;CACrB,MAAM,SAAS,OAAY,SAAS;EAClC,MAAM,EACJ,OACA,QACA,SAAS,QAAQ,KACjB,kBACA,aACA,UACE,KAAK,QAAQ;EAIjB,MAAM,UAFqB,kBAAkB,KAEZ,CAAC,CAAC,MAAM;EAEzC,QAAQ,MAAM,QAAQ,KAAK;EAE3B,IAAI,QAAQ;GACV,MAAM,YAAY,IAAI,QAAQ,WAAW,MAAM;GAE/C,IAAI,cAAc,QAChB,QAAQ,MAAM,QAAQ,MAAM,SAAS;EAEzC;EAEA,IAAI,qBAAqB,QACvB,QAAQ,MAAM,kBAAkB,MAAM,WAAW;EAGnD,IAAI,OACF,MAAM,MAAM;GACV,OAAO;GACP;GACA,WAAW,QAAQ;EACrB,CAAC;EAKH,OAAO,MAFgB,QAAQ,MAAM,IAEnB,YAAY,MAAM,OAAO,IAAI;CACjD;AACF"}
+{"version":3,"file":"unique-rule.mjs","names":[],"sources":["../../../../../../../../cascade/src/validation/rules/unique-rule.ts"],"sourcesContent":["import { get } from \"@mongez/reinforcements\";\nimport { invalidRule, VALID_RULE, type SchemaRule } from \"@warlock.js/seal\";\nimport { resolveModelClass } from \"../../model/register-model\";\nimport type { UniqueRuleOptions } from \"../types\";\n\n/**\n * Validates that a value is unique against a database column.\n *\n * Supports three exclusion modes:\n * - `except`: read a sibling input's value and exclude rows where that\n *   column equals the sibling's value\n * - `exceptColumnName` + `exceptValue`: exclude rows where the named\n *   column equals the supplied value (used by request-aware wrappers)\n * - Custom `query` callback for anything more involved\n *\n * @example\n * v.email().unique(\"User\");\n * v.string().unique(\"User\", { except: \"id\" });\n */\nexport const uniqueRule: SchemaRule<UniqueRuleOptions> = {\n  name: \"unique\",\n  defaultErrorMessage: \"The :input must be unique\",\n  async validate(value: any, context) {\n    const {\n      Model,\n      except,\n      column = context.key,\n      exceptColumnName,\n      exceptValue,\n      query,\n    } = this.context.options;\n\n    const ResolvedModelClass = resolveModelClass(Model);\n\n    const dbQuery = ResolvedModelClass.query();\n\n    dbQuery.where(column, value);\n\n    if (except) {\n      const exceptVal = get(context.allValues, except);\n\n      if (exceptVal !== undefined) {\n        dbQuery.where(except, \"!=\", exceptVal);\n      }\n    }\n\n    if (exceptColumnName !== undefined) {\n      dbQuery.where(exceptColumnName, \"!=\", exceptValue);\n    }\n\n    if (query) {\n      await query({\n        query: dbQuery,\n        value,\n        allValues: context.allValues,\n      });\n    }\n\n    const document = await dbQuery.first();\n\n    return document ? invalidRule(this, context) : VALID_RULE;\n  },\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;AAmBA,MAAa,aAA4C;CACvD,MAAM;CACN,qBAAqB;CACrB,MAAM,SAAS,OAAY,SAAS;EAClC,MAAM,EACJ,OACA,QACA,SAAS,QAAQ,KACjB,kBACA,aACA,UACE,KAAK,QAAQ;EAIjB,MAAM,UAFqB,kBAAkB,KAEZ,CAAC,CAAC,MAAM;EAEzC,QAAQ,MAAM,QAAQ,KAAK;EAE3B,IAAI,QAAQ;GACV,MAAM,YAAY,IAAI,QAAQ,WAAW,MAAM;GAE/C,IAAI,cAAc,QAChB,QAAQ,MAAM,QAAQ,MAAM,SAAS;EAEzC;EAEA,IAAI,qBAAqB,QACvB,QAAQ,MAAM,kBAAkB,MAAM,WAAW;EAGnD,IAAI,OACF,MAAM,MAAM;GACV,OAAO;GACP;GACA,WAAW,QAAQ;EACrB,CAAC;EAKH,OAAO,MAFgB,QAAQ,MAAM,IAEnB,YAAY,MAAM,OAAO,IAAI;CACjD;AACF"}

package/esm/validation/transformers/embed-model-transformer.mjs

@@ -1,6 +1,6 @@
 import { Model } from "../../model/model.mjs";
 
-//#region ../@warlock.js/cascade/src/validation/transformers/embed-model-transformer.ts
+//#region ../cascade/src/validation/transformers/embed-model-transformer.ts
 const databaseModelTransformer = (value, context) => {
 	const embed = context.options.embed ?? "embedData";
 	if (value instanceof Model === false && !Array.isArray(value)) return value;

package/esm/validation/transformers/embed-model-transformer.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"embed-model-transformer.mjs","names":[],"sources":["../../../../../../../../@warlock.js/cascade/src/validation/transformers/embed-model-transformer.ts"],"sourcesContent":["import { type TransformerCallback } from \"@warlock.js/seal\";\nimport { Model } from \"../../model/model\";\n\nexport const databaseModelTransformer: TransformerCallback = (value, context) => {\n  const embed = context.options.embed ?? \"embedData\";\n\n  if (value instanceof Model === false && !Array.isArray(value)) {\n    return value;\n  }\n\n  if (Array.isArray(value)) {\n    return value.map((item) => {\n      if (typeof embed === \"string\") {\n        return item[embed];\n      }\n\n      return item.only(embed);\n    });\n  }\n\n  if (typeof embed === \"string\") {\n    return (value as any)[embed];\n  }\n\n  return value.only(embed);\n};\n"],"mappings":";;;AAGA,MAAa,4BAAiD,OAAO,YAAY;CAC/E,MAAM,QAAQ,QAAQ,QAAQ,SAAS;CAEvC,IAAI,iBAAiB,UAAU,SAAS,CAAC,MAAM,QAAQ,KAAK,GAC1D,OAAO;CAGT,IAAI,MAAM,QAAQ,KAAK,GACrB,OAAO,MAAM,KAAK,SAAS;EACzB,IAAI,OAAO,UAAU,UACnB,OAAO,KAAK;EAGd,OAAO,KAAK,KAAK,KAAK;CACxB,CAAC;CAGH,IAAI,OAAO,UAAU,UACnB,OAAQ,MAAc;CAGxB,OAAO,MAAM,KAAK,KAAK;AACzB"}
+{"version":3,"file":"embed-model-transformer.mjs","names":[],"sources":["../../../../../../../../cascade/src/validation/transformers/embed-model-transformer.ts"],"sourcesContent":["import { type TransformerCallback } from \"@warlock.js/seal\";\nimport { Model } from \"../../model/model\";\n\nexport const databaseModelTransformer: TransformerCallback = (value, context) => {\n  const embed = context.options.embed ?? \"embedData\";\n\n  if (value instanceof Model === false && !Array.isArray(value)) {\n    return value;\n  }\n\n  if (Array.isArray(value)) {\n    return value.map((item) => {\n      if (typeof embed === \"string\") {\n        return item[embed];\n      }\n\n      return item.only(embed);\n    });\n  }\n\n  if (typeof embed === \"string\") {\n    return (value as any)[embed];\n  }\n\n  return value.only(embed);\n};\n"],"mappings":";;;AAGA,MAAa,4BAAiD,OAAO,YAAY;CAC/E,MAAM,QAAQ,QAAQ,QAAQ,SAAS;CAEvC,IAAI,iBAAiB,UAAU,SAAS,CAAC,MAAM,QAAQ,KAAK,GAC1D,OAAO;CAGT,IAAI,MAAM,QAAQ,KAAK,GACrB,OAAO,MAAM,KAAK,SAAS;EACzB,IAAI,OAAO,UAAU,UACnB,OAAO,KAAK;EAGd,OAAO,KAAK,KAAK,KAAK;CACxB,CAAC;CAGH,IAAI,OAAO,UAAU,UACnB,OAAQ,MAAc;CAGxB,OAAO,MAAM,KAAK,KAAK;AACzB"}

package/esm/validation/types.d.mts

@@ -2,7 +2,7 @@ import { ChildModel } from "../model/model.types.mjs";
 import { Model } from "../model/model.mjs";
 import { QueryBuilderContract } from "../contracts/query-builder.contract.mjs";
 
-//#region ../@warlock.js/cascade/src/validation/types.d.ts
+//#region ../cascade/src/validation/types.d.ts
 /**
  * Base options shared by all database-backed validation rules.
  *

package/esm/validation/types.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.mts","names":[],"sources":["../../../../../../../@warlock.js/cascade/src/validation/types.ts"],"mappings":";;;;;;;;AASA;;;KAAY,oBAAA;EAEH,iCAAP,KAAA,EAAO,UAAA,CAAW,KAAA,YAML;EAJb,KAAA,IAAS,OAAA;IACP,KAAA,EAAO,oBAAA;IACP,KAAA;IACA,SAAA;EAAA,aACW,OAAA,QAJb;EAMA,MAAA;AAAA;;;;KAMU,qBAAA,GAAwB,oBAAoB;;;AANhD;AAMR;;;;KASY,iBAAA,GAAoB,qBAAqB;EAAzC,6DAEV,MAAA;EAEA,gBAAA,WAJ8B;EAM9B,WAAA;AAAA;;;AAAW;KAMD,iBAAA,GAAoB,oBAAoB"}
+{"version":3,"file":"types.d.mts","names":[],"sources":["../../../../../../../cascade/src/validation/types.ts"],"mappings":";;;;;;;;AASA;;;KAAY,oBAAA;EAEH,iCAAP,KAAA,EAAO,UAAA,CAAW,KAAA,YAML;EAJb,KAAA,IAAS,OAAA;IACP,KAAA,EAAO,oBAAA;IACP,KAAA;IACA,SAAA;EAAA,aACW,OAAA,QAJb;EAMA,MAAA;AAAA;;;;KAMU,qBAAA,GAAwB,oBAAoB;;;AANhD;AAMR;;;;KASY,iBAAA,GAAoB,qBAAqB;EAAzC,6DAEV,MAAA;EAEA,gBAAA,WAJ8B;EAM9B,WAAA;AAAA;;;AAAW;KAMD,iBAAA,GAAoB,oBAAoB"}

package/esm/validation/validators/embed-validator.d.mts

@@ -1,7 +1,7 @@
 import { ChildModel } from "../../model/model.types.mjs";
 import { BaseValidator } from "@warlock.js/seal";
 
-//#region ../@warlock.js/cascade/src/validation/validators/embed-validator.d.ts
+//#region ../cascade/src/validation/validators/embed-validator.d.ts
 declare class EmbedModelValidator extends BaseValidator {
   /**
    * Check if value is a string type

package/esm/validation/validators/embed-validator.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"embed-validator.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/cascade/src/validation/validators/embed-validator.ts"],"mappings":";;;;cAMa,mBAAA,SAA4B,aAAA;;;AAAzC;EAIS,WAAA,CAAY,KAAA;;;;EAWZ,KAAA,CAAM,KAAA,EAAO,UAAA,gBAA0B,YAAA,YAAwB,mBAAA;EAaC;;;EAAhE,MAAA,CAAO,KAAA,EAAO,UAAA,gBAA0B,YAAA,YAAwB,mBAAA;EA5BnB;;;EA6C7C,KAAA,CAAM,KAAA,uBAA4B,mBAAA;AAAA"}
+{"version":3,"file":"embed-validator.d.mts","names":[],"sources":["../../../../../../../../cascade/src/validation/validators/embed-validator.ts"],"mappings":";;;;cAMa,mBAAA,SAA4B,aAAA;;;AAAzC;EAIS,WAAA,CAAY,KAAA;;;;EAWZ,KAAA,CAAM,KAAA,EAAO,UAAA,gBAA0B,YAAA,YAAwB,mBAAA;EAaC;;;EAAhE,MAAA,CAAO,KAAA,EAAO,UAAA,gBAA0B,YAAA,YAAwB,mBAAA;EA5BnB;;;EA6C7C,KAAA,CAAM,KAAA,uBAA4B,mBAAA;AAAA"}

package/esm/validation/validators/embed-validator.mjs

@@ -4,7 +4,7 @@ import { databaseModelTransformer } from "../transformers/embed-model-transforme
 import { Model } from "../../model/model.mjs";
 import { BaseValidator, arrayRule } from "@warlock.js/seal";
 
-//#region ../@warlock.js/cascade/src/validation/validators/embed-validator.ts
+//#region ../cascade/src/validation/validators/embed-validator.ts
 var EmbedModelValidator = class extends BaseValidator {
 	/**
 	* Check if value is a string type

package/esm/validation/validators/embed-validator.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"embed-validator.mjs","names":[],"sources":["../../../../../../../../@warlock.js/cascade/src/validation/validators/embed-validator.ts"],"sourcesContent":["import { arrayRule, BaseValidator } from \"@warlock.js/seal\";\nimport { Model, type ChildModel } from \"../../model/model\";\nimport { databaseModelMutator, databaseModelsMutator } from \"../mutators/embed-mutator\";\nimport { databaseModelRule, databaseModelsRule } from \"../rules/database-model-rule\";\nimport { databaseModelTransformer } from \"../transformers/embed-model-transformer\";\n\nexport class EmbedModelValidator extends BaseValidator {\n  /**\n   * Check if value is a string type\n   */\n  public matchesType(value: any): boolean {\n    return (\n      value instanceof Model ||\n      typeof value === \"number\" ||\n      (Array.isArray(value) && value.every((item) => item instanceof Model))\n    );\n  }\n\n  /**\n   * Mutate the value to be a model, also fail if the mutated value is not a valid model\n   */\n  public model(model: ChildModel<any> | string, errorMessage?: string): EmbedModelValidator {\n    this.addMutator(databaseModelMutator, {\n      model,\n    });\n\n    return this.addRule(databaseModelRule, errorMessage, {\n      model,\n    });\n  }\n\n  /**\n   * Validate the value is a list of models\n   */\n  public models(model: ChildModel<any> | string, errorMessage?: string): EmbedModelValidator {\n    const instance = this.instance;\n    instance.addMutator(databaseModelsMutator, {\n      model,\n    });\n\n    instance.addMutableRule(arrayRule);\n    instance.addMutableRule(databaseModelsRule, errorMessage, {\n      model,\n    });\n\n    return instance;\n  }\n\n  /**\n   * Determine how the data will be stored as an embedded document\n   */\n  public embed(embed?: string | string[]): EmbedModelValidator {\n    return this.addTransformer(databaseModelTransformer, {\n      embed,\n    });\n  }\n}\n"],"mappings":";;;;;;;AAMA,IAAa,sBAAb,cAAyC,cAAc;;;;CAIrD,AAAO,YAAY,OAAqB;EACtC,OACE,iBAAiB,SACjB,OAAO,UAAU,YAChB,MAAM,QAAQ,KAAK,KAAK,MAAM,OAAO,SAAS,gBAAgB,KAAK;CAExE;;;;CAKA,AAAO,MAAM,OAAiC,cAA4C;EACxF,KAAK,WAAW,sBAAsB,EACpC,MACF,CAAC;EAED,OAAO,KAAK,QAAQ,mBAAmB,cAAc,EACnD,MACF,CAAC;CACH;;;;CAKA,AAAO,OAAO,OAAiC,cAA4C;EACzF,MAAM,WAAW,KAAK;EACtB,SAAS,WAAW,uBAAuB,EACzC,MACF,CAAC;EAED,SAAS,eAAe,SAAS;EACjC,SAAS,eAAe,oBAAoB,cAAc,EACxD,MACF,CAAC;EAED,OAAO;CACT;;;;CAKA,AAAO,MAAM,OAAgD;EAC3D,OAAO,KAAK,eAAe,0BAA0B,EACnD,MACF,CAAC;CACH;AACF"}
+{"version":3,"file":"embed-validator.mjs","names":[],"sources":["../../../../../../../../cascade/src/validation/validators/embed-validator.ts"],"sourcesContent":["import { arrayRule, BaseValidator } from \"@warlock.js/seal\";\nimport { Model, type ChildModel } from \"../../model/model\";\nimport { databaseModelMutator, databaseModelsMutator } from \"../mutators/embed-mutator\";\nimport { databaseModelRule, databaseModelsRule } from \"../rules/database-model-rule\";\nimport { databaseModelTransformer } from \"../transformers/embed-model-transformer\";\n\nexport class EmbedModelValidator extends BaseValidator {\n  /**\n   * Check if value is a string type\n   */\n  public matchesType(value: any): boolean {\n    return (\n      value instanceof Model ||\n      typeof value === \"number\" ||\n      (Array.isArray(value) && value.every((item) => item instanceof Model))\n    );\n  }\n\n  /**\n   * Mutate the value to be a model, also fail if the mutated value is not a valid model\n   */\n  public model(model: ChildModel<any> | string, errorMessage?: string): EmbedModelValidator {\n    this.addMutator(databaseModelMutator, {\n      model,\n    });\n\n    return this.addRule(databaseModelRule, errorMessage, {\n      model,\n    });\n  }\n\n  /**\n   * Validate the value is a list of models\n   */\n  public models(model: ChildModel<any> | string, errorMessage?: string): EmbedModelValidator {\n    const instance = this.instance;\n    instance.addMutator(databaseModelsMutator, {\n      model,\n    });\n\n    instance.addMutableRule(arrayRule);\n    instance.addMutableRule(databaseModelsRule, errorMessage, {\n      model,\n    });\n\n    return instance;\n  }\n\n  /**\n   * Determine how the data will be stored as an embedded document\n   */\n  public embed(embed?: string | string[]): EmbedModelValidator {\n    return this.addTransformer(databaseModelTransformer, {\n      embed,\n    });\n  }\n}\n"],"mappings":";;;;;;;AAMA,IAAa,sBAAb,cAAyC,cAAc;;;;CAIrD,AAAO,YAAY,OAAqB;EACtC,OACE,iBAAiB,SACjB,OAAO,UAAU,YAChB,MAAM,QAAQ,KAAK,KAAK,MAAM,OAAO,SAAS,gBAAgB,KAAK;CAExE;;;;CAKA,AAAO,MAAM,OAAiC,cAA4C;EACxF,KAAK,WAAW,sBAAsB,EACpC,MACF,CAAC;EAED,OAAO,KAAK,QAAQ,mBAAmB,cAAc,EACnD,MACF,CAAC;CACH;;;;CAKA,AAAO,OAAO,OAAiC,cAA4C;EACzF,MAAM,WAAW,KAAK;EACtB,SAAS,WAAW,uBAAuB,EACzC,MACF,CAAC;EAED,SAAS,eAAe,SAAS;EACjC,SAAS,eAAe,oBAAoB,cAAc,EACxD,MACF,CAAC;EAED,OAAO;CACT;;;;CAKA,AAAO,MAAM,OAAgD;EAC3D,OAAO,KAAK,eAAe,0BAA0B,EACnD,MACF,CAAC;CACH;AACF"}

package/esm/writer/database-writer.d.mts

@@ -1,7 +1,7 @@
 import { Model } from "../model/model.mjs";
 import { WriterContract, WriterOptions, WriterResult } from "../contracts/database-writer.contract.mjs";
 
-//#region ../@warlock.js/cascade/src/writer/database-writer.d.ts
+//#region ../cascade/src/writer/database-writer.d.ts
 /**
  * Database writer service that orchestrates model persistence.
  *

package/esm/writer/database-writer.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"database-writer.d.mts","names":[],"sources":["../../../../../../../@warlock.js/cascade/src/writer/database-writer.ts"],"mappings":";;;;;;AAsDA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAAa,cAAA,YAA0B,cAAA;EAwW7B;EAAA,iBAtWS,KAAA;EAsaT;EAAA,iBAnaS,IAAA;EAscH;EAAA,iBAncG,UAAA;EAmcQ;EAAA,iBAhcR,MAAA;;mBAGA,KAAA;;mBAGA,UAAA;;mBAGA,MAAA;;mBAGA,UAAA;;;;;;;;;;;;;cAcE,KAAA,EAAO,KAAA;;;;;;;;EAkBb,IAAA,CAAK,OAAA,GAAS,aAAA,GAAqB,OAAA,CAAQ,YAAA;;;;;;;;;;;UAsE1C,eAAA;;;;;;;;UA8FA,aAAA;;;;;;;;UAqDA,aAAA;;;;;;EA2CD,cAAA,IAAkB,OAAA;;;;;;;;;;;;;;;;;;;;;;UA6CvB,qBAAA;;;;;;;;;;;;UAuCA,gBAAA;;;;;;;;;;;;UAyBA,kBAAA;;;;;;;;;UAsBA,SAAA;;;;;;;;;;UAaM,WAAA;AAAA"}
+{"version":3,"file":"database-writer.d.mts","names":[],"sources":["../../../../../../../cascade/src/writer/database-writer.ts"],"mappings":";;;;;;AAsDA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAAa,cAAA,YAA0B,cAAA;EAwW7B;EAAA,iBAtWS,KAAA;EAsaT;EAAA,iBAnaS,IAAA;EAscH;EAAA,iBAncG,UAAA;EAmcQ;EAAA,iBAhcR,MAAA;;mBAGA,KAAA;;mBAGA,UAAA;;mBAGA,MAAA;;mBAGA,UAAA;;;;;;;;;;;;;cAcE,KAAA,EAAO,KAAA;;;;;;;;EAkBb,IAAA,CAAK,OAAA,GAAS,aAAA,GAAqB,OAAA,CAAQ,YAAA;;;;;;;;;;;UAsE1C,eAAA;;;;;;;;UA8FA,aAAA;;;;;;;;UAqDA,aAAA;;;;;;EA2CD,cAAA,IAAkB,OAAA;;;;;;;;;;;;;;;;;;;;;;UA6CvB,qBAAA;;;;;;;;;;;;UAuCA,gBAAA;;;;;;;;;;;;UAyBA,kBAAA;;;;;;;;;UAsBA,SAAA;;;;;;;;;;UAaM,WAAA;AAAA"}

package/esm/writer/database-writer.mjs

@@ -5,7 +5,7 @@ import { when } from "@mongez/reinforcements";
 import events from "@mongez/events";
 import { getSealConfig, v } from "@warlock.js/seal";
 
-//#region ../@warlock.js/cascade/src/writer/database-writer.ts
+//#region ../cascade/src/writer/database-writer.ts
 /**
 * Database writer service that orchestrates model persistence.
 *

package/esm/writer/database-writer.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"database-writer.mjs","names":[],"sources":["../../../../../../../@warlock.js/cascade/src/writer/database-writer.ts"],"sourcesContent":["import events from \"@mongez/events\";\nimport { when } from \"@mongez/reinforcements\";\nimport { getSealConfig, v, type ObjectValidator } from \"@warlock.js/seal\";\nimport type {\n  DriverContract,\n  InsertResult,\n  UpdateOperations,\n  UpdateResult,\n} from \"../contracts/database-driver.contract\";\nimport type {\n  WriterContract,\n  WriterOptions,\n  WriterResult,\n} from \"../contracts/database-writer.contract\";\nimport type { ChildModel, Model } from \"../model/model\";\nimport { getModelUpdatedEvent } from \"../sync/model-events\";\nimport type { StrictMode } from \"../types\";\nimport { DatabaseWriterValidationError } from \"../validation\";\nimport type { DataSource } from \"./../data-source/data-source\";\n\n/**\n * Database writer service that orchestrates model persistence.\n *\n * Handles the complete save pipeline:\n * 1. Check for changes (skip if no changes and not new)\n * 2. Emit `saving` event (for data enrichment)\n * 3. Emit `validating` event\n * 4. Validate and cast data via @warlock.js/seal schema\n * 5. Emit `validated` event\n * 6. Generate ID (for new NoSQL records)\n * 7. Emit `creating`/`updating` events\n * 8. Execute insert or update via driver\n * 9. Merge returned data into model\n * 10. Reset dirty tracker and update `isNew` flag\n * 11. Emit `saved` and `created`/`updated` events\n *\n * @example\n * ```typescript\n * const user = new User({ name: \"Alice\", email: \"alice@example.com\" });\n * const writer = new DatabaseWriter(user);\n * await writer.save();\n *\n * console.log(user.get(\"id\")); // 1 (auto-generated)\n * console.log(user.get(\"_id\")); // ObjectId(\"...\")\n *\n * // Update existing record\n * user.set(\"name\", \"Alice Smith\");\n * await writer.save();\n * // Only updates the \"name\" field (partial update)\n *\n * // Silent save (no events)\n * await writer.save({ skipEvents: true });\n * ```\n */\nexport class DatabaseWriter implements WriterContract {\n  /** The model instance being persisted */\n  private readonly model: Model;\n\n  /** Model constructor reference */\n  private readonly ctor: ChildModel<Model>;\n\n  /** Data source containing driver and ID generator */\n  private readonly dataSource: DataSource;\n\n  /** Database driver for executing queries */\n  private readonly driver: DriverContract;\n\n  /** Table/collection name */\n  private readonly table: string;\n\n  /** Primary key field name */\n  private readonly primaryKey: string;\n\n  /** Validation schema (if defined) */\n  private readonly schema?: ObjectValidator;\n\n  /** Strict mode configuration */\n  private readonly strictMode: StrictMode;\n\n  /**\n   * Create a new writer instance for a model.\n   *\n   * @param model - The model instance to persist\n   *\n   * @example\n   * ```typescript\n   * const user = new User({ name: \"Alice\" });\n   * const writer = new DatabaseWriter(user);\n   * await writer.save();\n   * ```\n   */\n  public constructor(model: Model) {\n    this.model = model;\n    this.ctor = model.constructor as ChildModel<Model>;\n    this.dataSource = this.ctor.getDataSource();\n    this.driver = this.dataSource.driver;\n    this.table = this.ctor.table;\n    this.primaryKey = this.ctor.primaryKey;\n    this.schema = this.ctor.schema;\n    this.strictMode = this.ctor.strictMode;\n  }\n\n  /**\n   * Save the model instance to the database.\n   *\n   * @param options - Save options\n   * @returns Result with success status, document, and metadata\n   * @throws {ValidationError} If validation fails\n   */\n  public async save(options: WriterOptions = {}): Promise<WriterResult> {\n    const isInsert = this.model.isNew;\n\n    // 1. Check if model has changes (skip if no changes and not new)\n    if (!isInsert && !this.model.hasChanges()) {\n      return {\n        success: true,\n        document: this.model.data,\n        isNew: false,\n        modifiedCount: 0,\n      };\n    }\n\n    // 2. Emit saving event (before validation for data enrichment)\n    if (!options.skipEvents) {\n      await this.model.emitEvent(\"saving\", {\n        isInsert,\n        options,\n        mode: isInsert ? \"insert\" : \"update\",\n      });\n    }\n\n    // 3. Validate and cast data\n    await this.validateAndCast(isInsert, options);\n\n    // 4. Execute insert or update\n    let result: InsertResult | UpdateResult;\n\n    if (isInsert) {\n      result = await this.performInsert(options);\n    } else {\n      result = await this.performUpdate(options);\n    }\n\n    // 5. Reset dirty tracker and update isNew flag\n    const changedFields = isInsert ? [] : this.model.getDirtyColumns();\n    this.model.dirtyTracker.reset();\n    this.model.isNew = false;\n\n    // 6. Emit post-save events\n    if (!options.skipEvents) {\n      await this.model.emitEvent(\"saved\");\n      await this.model.emitEvent(isInsert ? \"created\" : \"updated\");\n    }\n\n    // 7. Trigger sync operations (fire-and-forget, non-blocking)\n    if (!options.skipSync && !isInsert) {\n      void this.triggerSync(changedFields);\n    }\n\n    return {\n      success: true,\n      document: this.model.data,\n      isNew: isInsert,\n      modifiedCount: isInsert\n        ? undefined\n        : (result as UpdateResult).modifiedCount,\n    };\n  }\n\n  /**\n   * Validate and cast model data using the schema.\n   *\n   * Updates the model's data in-place with validated/casted values.\n   *\n   * @param isInsert - Whether this is an insert operation\n   * @param options - Save options\n   * @throws {ValidationError} If validation fails\n   * @private\n   */\n  private async validateAndCast(\n    isInsert: boolean,\n    options: WriterOptions,\n  ): Promise<void> {\n    // Emit validating event\n    if (!options.skipEvents) {\n      await this.model.emitEvent(\"validating\", {\n        isInsert,\n        options,\n        mode: isInsert ? \"insert\" : \"update\",\n      });\n    }\n\n    // Skip validation if requested or no schema defined\n    if (options.skipValidation || !this.schema) {\n      return;\n    }\n\n    // Whitelist the framework-managed system columns so a model carrying them\n    // (id / _id / timestamps / soft-delete deletedAt) validates cleanly instead\n    // of being stripped (strictMode \"strip\") or rejected (strictMode \"fail\").\n    // `when(...)` adds each timestamp/soft-delete column only when configured\n    // (truthy) — the lazy factory means a disabled column (`false`) never even\n    // builds a bogus schema key.\n    //\n    // The whitelist must apply to BOTH insert and update: on insert a caller may\n    // supply a backdated createdAt (e.g. data migrations / imports), and without\n    // the whitelist strictMode \"strip\" silently drops it before it reaches the\n    // writer, while \"fail\" rejects the whole insert.\n    const systemColumns = {\n      id: v.scalar().optional(),\n      _id: v.any().optional(),\n      ...when(this.ctor.createdAtColumn, () => ({\n        [this.ctor.createdAtColumn as string]: v.date().optional(),\n      })),\n      ...when(this.ctor.updatedAtColumn, () => ({\n        [this.ctor.updatedAtColumn as string]: v.date().optional(),\n      })),\n      ...when(this.ctor.deletedAtColumn, () => ({\n        [this.ctor.deletedAtColumn as string]: v.date().optional(),\n      })),\n    };\n\n    // Clone full schema for insert, partial (dirty keys only) for updates.\n    const validationSchema = isInsert\n      ? this.schema.clone().extend(systemColumns)\n      : this.schema.clone(Object.keys(this.model.data)).extend(systemColumns);\n\n    // Apply strict mode\n    if (this.strictMode === \"strip\") {\n      validationSchema.stripUnknown();\n    } else if (this.strictMode === \"fail\") {\n      validationSchema.allowUnknown(false);\n    } else if (this.strictMode === \"allow\") {\n      validationSchema.allowUnknown(true);\n    }\n\n    // Run validation\n    const result = await v.validate(validationSchema, this.model.data, {\n      context: {\n        model: this.model,\n      },\n      ...getSealConfig(),\n    });\n\n    if (!result.isValid) {\n      console.trace(result.errors);\n\n      const error = new DatabaseWriterValidationError(\n        `[${this.model.constructor.name} Model] ${isInsert ? \"Insert\" : \"Update\"} Validation failed`,\n        result.errors,\n      );\n      if (!options.skipEvents) {\n        await this.model.emitEvent(\"validated\", { result, error });\n      }\n      throw error;\n    }\n\n    // Update model data with validated/casted data\n    this.model.replaceData(result.data);\n\n    // Emit validated event\n    if (!options.skipEvents) {\n      await this.model.emitEvent(\"validated\", { result });\n    }\n  }\n\n  /**\n   * Perform an insert operation.\n   *\n   * @param options - Save options\n   * @returns Insert result\n   * @private\n   */\n  private async performInsert(options: WriterOptions): Promise<InsertResult> {\n    // Generate ID if needed (NoSQL only)\n    await this.generateNextId();\n\n    // Get data to insert (already validated and casted)\n    const dataToInsert = this.model.data;\n\n    // Add createdAt and updatedAt to the data (using resolved column names)\n    // The column names are already resolved through the hierarchy:\n    // Model static property > Database config > Driver defaults > undefined\n    //\n    // Only stamp createdAt when the caller did NOT supply one, so a backdated\n    // value (e.g. data migrations / imports) is honored instead of overwritten.\n    // This mirrors the upsert path's guard. updatedAt is always stamped to\n    // reflect the moment the record is persisted.\n    const createdAtColumn = this.ctor.createdAtColumn;\n\n    if (createdAtColumn && dataToInsert[createdAtColumn] == null) {\n      dataToInsert[createdAtColumn] = new Date();\n    }\n\n    const updatedAtColumn = this.ctor.updatedAtColumn;\n    if (updatedAtColumn) {\n      dataToInsert[updatedAtColumn] = new Date();\n    }\n\n    // Emit creating event\n    if (!options.skipEvents) {\n      await this.model.emitEvent(\"creating\");\n    }\n\n    // INSERT: use full validated data\n    const result = await this.driver.insert(this.table, dataToInsert);\n\n    // Merge returned data (e.g., generated _id, timestamps)\n    // Note: We use merge here because the result might not include all fields\n    // (e.g., our generated 'id' field), and we don't want to lose them\n    this.model.merge(result.document as Record<string, unknown>);\n\n    // Reset dirty tracker immediately after merge to prevent\n    // database-generated fields (like _id) from being marked as dirty\n    this.model.dirtyTracker.reset();\n\n    return result;\n  }\n\n  /**\n   * Perform an update operation.\n   *\n   * @param options - Save options\n   * @returns Update result\n   * @private\n   */\n  private async performUpdate(options: WriterOptions): Promise<UpdateResult> {\n    // Emit updating event\n    if (!options.skipEvents) {\n      await this.model.emitEvent(\"updating\");\n    }\n\n    // Update the updatedAt timestamp (using resolved column name)\n    const updatedAtColumn = this.ctor.updatedAtColumn;\n    if (updatedAtColumn) {\n      this.model.set(updatedAtColumn, new Date());\n    }\n\n    if (options.replace) {\n      const document = await this.driver.replace(\n        this.table,\n        {\n          [this.primaryKey]: this.model.get(this.primaryKey),\n        },\n        this.model.data,\n      );\n\n      if (document) {\n        this.model.replaceData(document as Record<string, unknown>);\n      }\n\n      return { modifiedCount: document ? 1 : 0 };\n    }\n\n    // Build operations from dirty tracker\n    const operations = this.buildUpdateOperations();\n\n    // Build filter using primary key\n    const filter = { [this.primaryKey]: this.model.get(this.primaryKey) };\n\n    // Execute update with operations\n    return await this.driver.update(this.table, filter, operations);\n  }\n\n  /**\n   * Generate ID for the model if auto-generation is enabled.\n   *\n   * @private\n   */\n  public async generateNextId(): Promise<void> {\n    if (!this.ctor.autoGenerateId || this.model.get(\"id\")) {\n      return;\n    }\n\n    const idGenerator = this.dataSource.idGenerator;\n    if (!idGenerator) {\n      return;\n    }\n\n    // Resolve ID generation options from model configuration\n    const initialId = this.resolveInitialId();\n\n    const incrementIdBy = this.resolveIncrementBy();\n\n    const id = await idGenerator.generateNextId({\n      table: this.table,\n      initialId,\n      incrementIdBy,\n    });\n\n    this.model.set(\"id\", id);\n  }\n\n  /**\n   * Build update operations from the model's dirty tracker.\n   *\n   * Handles both modified fields ($set) and removed fields ($unset).\n   *\n   * @returns Update operations for the driver\n   * @private\n   *\n   * @example\n   * ```typescript\n   * // Model with changes\n   * user.set(\"name\", \"Alice\");\n   * user.unset(\"tempField\");\n   *\n   * const operations = this.buildUpdateOperations();\n   * // {\n   * //   $set: { name: \"Alice\" },\n   * //   $unset: { tempField: 1 }\n   * // }\n   * ```\n   */\n  private buildUpdateOperations(): UpdateOperations {\n    const operations: UpdateOperations = {};\n\n    // Get dirty columns (modified fields)\n    const dirtyColumns = this.model.getDirtyColumns();\n\n    if (dirtyColumns.length > 0) {\n      operations.$set = {};\n      for (const column of dirtyColumns) {\n        const value = this.model.get(column);\n        if (value === undefined) continue;\n\n        operations.$set[column] = this.model.get(column);\n      }\n    }\n\n    // Get removed columns\n    const removedColumns = this.model.getRemovedColumns();\n    if (removedColumns.length > 0) {\n      operations.$unset = {};\n      for (const column of removedColumns) {\n        operations.$unset[column] = 1;\n      }\n    }\n\n    return operations;\n  }\n\n  /**\n   * Resolve the initial ID from model configuration.\n   *\n   * Priority:\n   * 1. Model.initialId (explicit value)\n   * 2. Model.randomInitialId (random or function)\n   * 3. Default: 1\n   *\n   * @returns The initial ID value\n   * @private\n   */\n  private resolveInitialId(): number {\n    if (this.ctor.initialId) {\n      return this.ctor.initialId;\n    }\n\n    if (this.ctor.randomInitialId) {\n      return typeof this.ctor.randomInitialId === \"function\"\n        ? this.ctor.randomInitialId()\n        : this.randomInt(10000, 499999);\n    }\n\n    return 1; // Default initial ID\n  }\n\n  /**\n   * Resolve the increment value from model configuration.\n   *\n   * Priority:\n   * 1. Model.incrementIdBy (explicit value)\n   * 2. Model.randomIncrement (random or function)\n   * 3. Default: 1\n   *\n   * @returns The increment value\n   * @private\n   */\n  private resolveIncrementBy(): number {\n    if (this.ctor.incrementIdBy) {\n      return this.ctor.incrementIdBy;\n    }\n\n    if (this.ctor.randomIncrement) {\n      return typeof this.ctor.randomIncrement === \"function\"\n        ? this.ctor.randomIncrement()\n        : this.randomInt(1, 10);\n    }\n\n    return 1; // Default increment\n  }\n\n  /**\n   * Generate a random integer between min and max (inclusive).\n   *\n   * @param min - Minimum value\n   * @param max - Maximum value\n   * @returns Random integer\n   * @private\n   */\n  private randomInt(min: number, max: number): number {\n    return Math.floor(Math.random() * (max - min + 1)) + min;\n  }\n\n  /**\n   * Trigger sync operations after successful save.\n   *\n   * Emits a model.updated event that ModelSyncOperation listens to.\n   * The sync is handled by registered sync operations, not directly here.\n   *\n   * @param changedFields - Fields that were changed (for filtering)\n   * @private\n   */\n  private async triggerSync(changedFields: string[]): Promise<void> {\n    // Emit model.updated event - ModelSyncOperation listens to these\n    await events.triggerAll(\n      getModelUpdatedEvent(this.ctor),\n      this.model,\n      changedFields,\n    );\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"database-writer.mjs","names":[],"sources":["../../../../../../../cascade/src/writer/database-writer.ts"],"sourcesContent":["import events from \"@mongez/events\";\nimport { when } from \"@mongez/reinforcements\";\nimport { getSealConfig, v, type ObjectValidator } from \"@warlock.js/seal\";\nimport type {\n  DriverContract,\n  InsertResult,\n  UpdateOperations,\n  UpdateResult,\n} from \"../contracts/database-driver.contract\";\nimport type {\n  WriterContract,\n  WriterOptions,\n  WriterResult,\n} from \"../contracts/database-writer.contract\";\nimport type { ChildModel, Model } from \"../model/model\";\nimport { getModelUpdatedEvent } from \"../sync/model-events\";\nimport type { StrictMode } from \"../types\";\nimport { DatabaseWriterValidationError } from \"../validation\";\nimport type { DataSource } from \"./../data-source/data-source\";\n\n/**\n * Database writer service that orchestrates model persistence.\n *\n * Handles the complete save pipeline:\n * 1. Check for changes (skip if no changes and not new)\n * 2. Emit `saving` event (for data enrichment)\n * 3. Emit `validating` event\n * 4. Validate and cast data via @warlock.js/seal schema\n * 5. Emit `validated` event\n * 6. Generate ID (for new NoSQL records)\n * 7. Emit `creating`/`updating` events\n * 8. Execute insert or update via driver\n * 9. Merge returned data into model\n * 10. Reset dirty tracker and update `isNew` flag\n * 11. Emit `saved` and `created`/`updated` events\n *\n * @example\n * ```typescript\n * const user = new User({ name: \"Alice\", email: \"alice@example.com\" });\n * const writer = new DatabaseWriter(user);\n * await writer.save();\n *\n * console.log(user.get(\"id\")); // 1 (auto-generated)\n * console.log(user.get(\"_id\")); // ObjectId(\"...\")\n *\n * // Update existing record\n * user.set(\"name\", \"Alice Smith\");\n * await writer.save();\n * // Only updates the \"name\" field (partial update)\n *\n * // Silent save (no events)\n * await writer.save({ skipEvents: true });\n * ```\n */\nexport class DatabaseWriter implements WriterContract {\n  /** The model instance being persisted */\n  private readonly model: Model;\n\n  /** Model constructor reference */\n  private readonly ctor: ChildModel<Model>;\n\n  /** Data source containing driver and ID generator */\n  private readonly dataSource: DataSource;\n\n  /** Database driver for executing queries */\n  private readonly driver: DriverContract;\n\n  /** Table/collection name */\n  private readonly table: string;\n\n  /** Primary key field name */\n  private readonly primaryKey: string;\n\n  /** Validation schema (if defined) */\n  private readonly schema?: ObjectValidator;\n\n  /** Strict mode configuration */\n  private readonly strictMode: StrictMode;\n\n  /**\n   * Create a new writer instance for a model.\n   *\n   * @param model - The model instance to persist\n   *\n   * @example\n   * ```typescript\n   * const user = new User({ name: \"Alice\" });\n   * const writer = new DatabaseWriter(user);\n   * await writer.save();\n   * ```\n   */\n  public constructor(model: Model) {\n    this.model = model;\n    this.ctor = model.constructor as ChildModel<Model>;\n    this.dataSource = this.ctor.getDataSource();\n    this.driver = this.dataSource.driver;\n    this.table = this.ctor.table;\n    this.primaryKey = this.ctor.primaryKey;\n    this.schema = this.ctor.schema;\n    this.strictMode = this.ctor.strictMode;\n  }\n\n  /**\n   * Save the model instance to the database.\n   *\n   * @param options - Save options\n   * @returns Result with success status, document, and metadata\n   * @throws {ValidationError} If validation fails\n   */\n  public async save(options: WriterOptions = {}): Promise<WriterResult> {\n    const isInsert = this.model.isNew;\n\n    // 1. Check if model has changes (skip if no changes and not new)\n    if (!isInsert && !this.model.hasChanges()) {\n      return {\n        success: true,\n        document: this.model.data,\n        isNew: false,\n        modifiedCount: 0,\n      };\n    }\n\n    // 2. Emit saving event (before validation for data enrichment)\n    if (!options.skipEvents) {\n      await this.model.emitEvent(\"saving\", {\n        isInsert,\n        options,\n        mode: isInsert ? \"insert\" : \"update\",\n      });\n    }\n\n    // 3. Validate and cast data\n    await this.validateAndCast(isInsert, options);\n\n    // 4. Execute insert or update\n    let result: InsertResult | UpdateResult;\n\n    if (isInsert) {\n      result = await this.performInsert(options);\n    } else {\n      result = await this.performUpdate(options);\n    }\n\n    // 5. Reset dirty tracker and update isNew flag\n    const changedFields = isInsert ? [] : this.model.getDirtyColumns();\n    this.model.dirtyTracker.reset();\n    this.model.isNew = false;\n\n    // 6. Emit post-save events\n    if (!options.skipEvents) {\n      await this.model.emitEvent(\"saved\");\n      await this.model.emitEvent(isInsert ? \"created\" : \"updated\");\n    }\n\n    // 7. Trigger sync operations (fire-and-forget, non-blocking)\n    if (!options.skipSync && !isInsert) {\n      void this.triggerSync(changedFields);\n    }\n\n    return {\n      success: true,\n      document: this.model.data,\n      isNew: isInsert,\n      modifiedCount: isInsert\n        ? undefined\n        : (result as UpdateResult).modifiedCount,\n    };\n  }\n\n  /**\n   * Validate and cast model data using the schema.\n   *\n   * Updates the model's data in-place with validated/casted values.\n   *\n   * @param isInsert - Whether this is an insert operation\n   * @param options - Save options\n   * @throws {ValidationError} If validation fails\n   * @private\n   */\n  private async validateAndCast(\n    isInsert: boolean,\n    options: WriterOptions,\n  ): Promise<void> {\n    // Emit validating event\n    if (!options.skipEvents) {\n      await this.model.emitEvent(\"validating\", {\n        isInsert,\n        options,\n        mode: isInsert ? \"insert\" : \"update\",\n      });\n    }\n\n    // Skip validation if requested or no schema defined\n    if (options.skipValidation || !this.schema) {\n      return;\n    }\n\n    // Whitelist the framework-managed system columns so a model carrying them\n    // (id / _id / timestamps / soft-delete deletedAt) validates cleanly instead\n    // of being stripped (strictMode \"strip\") or rejected (strictMode \"fail\").\n    // `when(...)` adds each timestamp/soft-delete column only when configured\n    // (truthy) — the lazy factory means a disabled column (`false`) never even\n    // builds a bogus schema key.\n    //\n    // The whitelist must apply to BOTH insert and update: on insert a caller may\n    // supply a backdated createdAt (e.g. data migrations / imports), and without\n    // the whitelist strictMode \"strip\" silently drops it before it reaches the\n    // writer, while \"fail\" rejects the whole insert.\n    const systemColumns = {\n      id: v.scalar().optional(),\n      _id: v.any().optional(),\n      ...when(this.ctor.createdAtColumn, () => ({\n        [this.ctor.createdAtColumn as string]: v.date().optional(),\n      })),\n      ...when(this.ctor.updatedAtColumn, () => ({\n        [this.ctor.updatedAtColumn as string]: v.date().optional(),\n      })),\n      ...when(this.ctor.deletedAtColumn, () => ({\n        [this.ctor.deletedAtColumn as string]: v.date().optional(),\n      })),\n    };\n\n    // Clone full schema for insert, partial (dirty keys only) for updates.\n    const validationSchema = isInsert\n      ? this.schema.clone().extend(systemColumns)\n      : this.schema.clone(Object.keys(this.model.data)).extend(systemColumns);\n\n    // Apply strict mode\n    if (this.strictMode === \"strip\") {\n      validationSchema.stripUnknown();\n    } else if (this.strictMode === \"fail\") {\n      validationSchema.allowUnknown(false);\n    } else if (this.strictMode === \"allow\") {\n      validationSchema.allowUnknown(true);\n    }\n\n    // Run validation\n    const result = await v.validate(validationSchema, this.model.data, {\n      context: {\n        model: this.model,\n      },\n      ...getSealConfig(),\n    });\n\n    if (!result.isValid) {\n      console.trace(result.errors);\n\n      const error = new DatabaseWriterValidationError(\n        `[${this.model.constructor.name} Model] ${isInsert ? \"Insert\" : \"Update\"} Validation failed`,\n        result.errors,\n      );\n      if (!options.skipEvents) {\n        await this.model.emitEvent(\"validated\", { result, error });\n      }\n      throw error;\n    }\n\n    // Update model data with validated/casted data\n    this.model.replaceData(result.data);\n\n    // Emit validated event\n    if (!options.skipEvents) {\n      await this.model.emitEvent(\"validated\", { result });\n    }\n  }\n\n  /**\n   * Perform an insert operation.\n   *\n   * @param options - Save options\n   * @returns Insert result\n   * @private\n   */\n  private async performInsert(options: WriterOptions): Promise<InsertResult> {\n    // Generate ID if needed (NoSQL only)\n    await this.generateNextId();\n\n    // Get data to insert (already validated and casted)\n    const dataToInsert = this.model.data;\n\n    // Add createdAt and updatedAt to the data (using resolved column names)\n    // The column names are already resolved through the hierarchy:\n    // Model static property > Database config > Driver defaults > undefined\n    //\n    // Only stamp createdAt when the caller did NOT supply one, so a backdated\n    // value (e.g. data migrations / imports) is honored instead of overwritten.\n    // This mirrors the upsert path's guard. updatedAt is always stamped to\n    // reflect the moment the record is persisted.\n    const createdAtColumn = this.ctor.createdAtColumn;\n\n    if (createdAtColumn && dataToInsert[createdAtColumn] == null) {\n      dataToInsert[createdAtColumn] = new Date();\n    }\n\n    const updatedAtColumn = this.ctor.updatedAtColumn;\n    if (updatedAtColumn) {\n      dataToInsert[updatedAtColumn] = new Date();\n    }\n\n    // Emit creating event\n    if (!options.skipEvents) {\n      await this.model.emitEvent(\"creating\");\n    }\n\n    // INSERT: use full validated data\n    const result = await this.driver.insert(this.table, dataToInsert);\n\n    // Merge returned data (e.g., generated _id, timestamps)\n    // Note: We use merge here because the result might not include all fields\n    // (e.g., our generated 'id' field), and we don't want to lose them\n    this.model.merge(result.document as Record<string, unknown>);\n\n    // Reset dirty tracker immediately after merge to prevent\n    // database-generated fields (like _id) from being marked as dirty\n    this.model.dirtyTracker.reset();\n\n    return result;\n  }\n\n  /**\n   * Perform an update operation.\n   *\n   * @param options - Save options\n   * @returns Update result\n   * @private\n   */\n  private async performUpdate(options: WriterOptions): Promise<UpdateResult> {\n    // Emit updating event\n    if (!options.skipEvents) {\n      await this.model.emitEvent(\"updating\");\n    }\n\n    // Update the updatedAt timestamp (using resolved column name)\n    const updatedAtColumn = this.ctor.updatedAtColumn;\n    if (updatedAtColumn) {\n      this.model.set(updatedAtColumn, new Date());\n    }\n\n    if (options.replace) {\n      const document = await this.driver.replace(\n        this.table,\n        {\n          [this.primaryKey]: this.model.get(this.primaryKey),\n        },\n        this.model.data,\n      );\n\n      if (document) {\n        this.model.replaceData(document as Record<string, unknown>);\n      }\n\n      return { modifiedCount: document ? 1 : 0 };\n    }\n\n    // Build operations from dirty tracker\n    const operations = this.buildUpdateOperations();\n\n    // Build filter using primary key\n    const filter = { [this.primaryKey]: this.model.get(this.primaryKey) };\n\n    // Execute update with operations\n    return await this.driver.update(this.table, filter, operations);\n  }\n\n  /**\n   * Generate ID for the model if auto-generation is enabled.\n   *\n   * @private\n   */\n  public async generateNextId(): Promise<void> {\n    if (!this.ctor.autoGenerateId || this.model.get(\"id\")) {\n      return;\n    }\n\n    const idGenerator = this.dataSource.idGenerator;\n    if (!idGenerator) {\n      return;\n    }\n\n    // Resolve ID generation options from model configuration\n    const initialId = this.resolveInitialId();\n\n    const incrementIdBy = this.resolveIncrementBy();\n\n    const id = await idGenerator.generateNextId({\n      table: this.table,\n      initialId,\n      incrementIdBy,\n    });\n\n    this.model.set(\"id\", id);\n  }\n\n  /**\n   * Build update operations from the model's dirty tracker.\n   *\n   * Handles both modified fields ($set) and removed fields ($unset).\n   *\n   * @returns Update operations for the driver\n   * @private\n   *\n   * @example\n   * ```typescript\n   * // Model with changes\n   * user.set(\"name\", \"Alice\");\n   * user.unset(\"tempField\");\n   *\n   * const operations = this.buildUpdateOperations();\n   * // {\n   * //   $set: { name: \"Alice\" },\n   * //   $unset: { tempField: 1 }\n   * // }\n   * ```\n   */\n  private buildUpdateOperations(): UpdateOperations {\n    const operations: UpdateOperations = {};\n\n    // Get dirty columns (modified fields)\n    const dirtyColumns = this.model.getDirtyColumns();\n\n    if (dirtyColumns.length > 0) {\n      operations.$set = {};\n      for (const column of dirtyColumns) {\n        const value = this.model.get(column);\n        if (value === undefined) continue;\n\n        operations.$set[column] = this.model.get(column);\n      }\n    }\n\n    // Get removed columns\n    const removedColumns = this.model.getRemovedColumns();\n    if (removedColumns.length > 0) {\n      operations.$unset = {};\n      for (const column of removedColumns) {\n        operations.$unset[column] = 1;\n      }\n    }\n\n    return operations;\n  }\n\n  /**\n   * Resolve the initial ID from model configuration.\n   *\n   * Priority:\n   * 1. Model.initialId (explicit value)\n   * 2. Model.randomInitialId (random or function)\n   * 3. Default: 1\n   *\n   * @returns The initial ID value\n   * @private\n   */\n  private resolveInitialId(): number {\n    if (this.ctor.initialId) {\n      return this.ctor.initialId;\n    }\n\n    if (this.ctor.randomInitialId) {\n      return typeof this.ctor.randomInitialId === \"function\"\n        ? this.ctor.randomInitialId()\n        : this.randomInt(10000, 499999);\n    }\n\n    return 1; // Default initial ID\n  }\n\n  /**\n   * Resolve the increment value from model configuration.\n   *\n   * Priority:\n   * 1. Model.incrementIdBy (explicit value)\n   * 2. Model.randomIncrement (random or function)\n   * 3. Default: 1\n   *\n   * @returns The increment value\n   * @private\n   */\n  private resolveIncrementBy(): number {\n    if (this.ctor.incrementIdBy) {\n      return this.ctor.incrementIdBy;\n    }\n\n    if (this.ctor.randomIncrement) {\n      return typeof this.ctor.randomIncrement === \"function\"\n        ? this.ctor.randomIncrement()\n        : this.randomInt(1, 10);\n    }\n\n    return 1; // Default increment\n  }\n\n  /**\n   * Generate a random integer between min and max (inclusive).\n   *\n   * @param min - Minimum value\n   * @param max - Maximum value\n   * @returns Random integer\n   * @private\n   */\n  private randomInt(min: number, max: number): number {\n    return Math.floor(Math.random() * (max - min + 1)) + min;\n  }\n\n  /**\n   * Trigger sync operations after successful save.\n   *\n   * Emits a model.updated event that ModelSyncOperation listens to.\n   * The sync is handled by registered sync operations, not directly here.\n   *\n   * @param changedFields - Fields that were changed (for filtering)\n   * @private\n   */\n  private async triggerSync(changedFields: string[]): Promise<void> {\n    // Emit model.updated event - ModelSyncOperation listens to these\n    await events.triggerAll(\n      getModelUpdatedEvent(this.ctor),\n      this.model,\n      changedFields,\n    );\n  }\n}\n"],"mappings":"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"}

package/llms-full.txt

@@ -2556,6 +2556,24 @@ for (const [field, { oldValue, newValue }] of Object.entries(dirty)) {
 }
 ```
 
+## How a merge decides what changed
+
+`.merge()` deep-merges **plain objects only**. Every other value — primitives, arrays, and class instances such as `Date`, `Map`, `Set`, `RegExp` — **replaces** the target outright.
+
+```ts
+// plain object → merged key-by-key, siblings survive
+user.merge({ profile: { age: 26 } });     // profile.city untouched
+user.getDirtyColumns();                    // ["profile.age"]
+
+// Date → replaced, not merged
+conversation.merge({ lastOutboundAt: new Date() });
+conversation.getDirtyColumns();            // ["lastOutboundAt"]
+```
+
+:::note[Fixed in 4.9.1]
+Before 4.9.1 a `Date` merged over a column that **already held a `Date`** was silently dropped: the merge treated it as a mergeable container and recursed into it, and a `Date` has no own enumerable properties, so nothing was copied. The column never went dirty and `save()` returned `{ success: true, modifiedCount: 0 }` with no `UPDATE` issued. Writing into an empty column always worked, so only overwrites were affected. If you are on 4.9.0 or earlier, upgrade.
+:::
+
 ## Things NOT to do
 
 - Don't use `hasChanges()` / `isDirty()` after `save()` to verify the save persisted. The tracker resets to clean on save — these become false regardless. Read back from the DB if you need verification.
@@ -2636,6 +2654,20 @@ yarn cascade migrate:export-sql # write .up.sql / .down.sql instead of executing
 
 Name files with a timestamp prefix (`MM-DD-YYYY_HH-MM-SS-<name>.migration.ts`) so Cascade orders runs deterministically and infers the migration name from the filename. A timestamp prefix prevents the "two devs picked the same number" merge conflict.
 
+### How ordering actually works
+
+Every pending migration's SQL is pooled and sorted **globally**, by three keys in order:
+
+1. **Phase** — the dependency-safe DDL order, derived from the statement itself: extensions/types (1), `CREATE TABLE` (2), `ADD COLUMN` (3), foreign keys (4), drops/alters (5). A `CREATE TABLE` from a newer migration therefore still runs before an older migration's `ALTER`.
+2. **`createdAt`** — parsed from the filename prefix.
+3. **Migration name** — alphabetical, only when the timestamps can't decide.
+
+Because phase wins, cross-migration ordering matters most for statements that share a phase — two migrations both altering the same table, for instance.
+
+:::caution[`MM-DD` vs `DD-MM` is a guess]
+The parser tells the two apart by whether the first field is greater than 12 — a month can't be. When both fields are ≤ 12 the stamp is genuinely ambiguous and it assumes `MM-DD`. Two migrations generated on `01-08` and `08-01` of the same year sort by that assumption rather than by fact. If exact ordering between two such files matters, make it unambiguous — a differing hour is enough.
+:::
+
 ## Column helpers — the building blocks
 
 Every column in a `Migration.create` / `Migration.alter` map starts with a helper imported from `@warlock.js/cascade`; each returns a builder you chain modifiers onto (`.notNullable()`, `.nullable()`, `.unique()`, `.default(value)`, `.index()`, `.primary()`, `.references(table)`):

package/package.json

@@ -27,9 +27,9 @@
     "@mongez/events": "^2.2.6",
     "@mongez/reinforcements": "^3.3.0",
     "@mongez/supportive-is": "^2.1.3",
-    "@warlock.js/context": "4.8.2",
-    "@warlock.js/logger": "4.8.2",
-    "@warlock.js/seal": "4.8.2",
+    "@warlock.js/context": "4.9.1",
+    "@warlock.js/logger": "4.9.1",
+    "@warlock.js/seal": "4.9.1",
     "citty": "^0.2.2",
     "fast-glob": "^3.3.3"
   },
@@ -40,7 +40,7 @@
   "bin": {
     "cascade": "bin/cascade.js"
   },
-  "version": "4.8.2",
+  "version": "4.9.1",
   "main": "./cjs/index.cjs",
   "module": "./esm/index.mjs",
   "types": "./esm/index.d.mts",

package/skills/track-changes/SKILL.md

@@ -97,6 +97,24 @@ for (const [field, { oldValue, newValue }] of Object.entries(dirty)) {
 }
 ```
 
+## How a merge decides what changed
+
+`.merge()` deep-merges **plain objects only**. Every other value — primitives, arrays, and class instances such as `Date`, `Map`, `Set`, `RegExp` — **replaces** the target outright.
+
+```ts
+// plain object → merged key-by-key, siblings survive
+user.merge({ profile: { age: 26 } });     // profile.city untouched
+user.getDirtyColumns();                    // ["profile.age"]
+
+// Date → replaced, not merged
+conversation.merge({ lastOutboundAt: new Date() });
+conversation.getDirtyColumns();            // ["lastOutboundAt"]
+```
+
+:::note[Fixed in 4.9.1]
+Before 4.9.1 a `Date` merged over a column that **already held a `Date`** was silently dropped: the merge treated it as a mergeable container and recursed into it, and a `Date` has no own enumerable properties, so nothing was copied. The column never went dirty and `save()` returned `{ success: true, modifiedCount: 0 }` with no `UPDATE` issued. Writing into an empty column always worked, so only overwrites were affected. If you are on 4.9.0 or earlier, upgrade.
+:::
+
 ## Things NOT to do
 
 - Don't use `hasChanges()` / `isDirty()` after `save()` to verify the save persisted. The tracker resets to clean on save — these become false regardless. Read back from the DB if you need verification.

package/skills/write-migration/SKILL.md

@@ -64,6 +64,20 @@ yarn cascade migrate:export-sql # write .up.sql / .down.sql instead of executing
 
 Name files with a timestamp prefix (`MM-DD-YYYY_HH-MM-SS-<name>.migration.ts`) so Cascade orders runs deterministically and infers the migration name from the filename. A timestamp prefix prevents the "two devs picked the same number" merge conflict.
 
+### How ordering actually works
+
+Every pending migration's SQL is pooled and sorted **globally**, by three keys in order:
+
+1. **Phase** — the dependency-safe DDL order, derived from the statement itself: extensions/types (1), `CREATE TABLE` (2), `ADD COLUMN` (3), foreign keys (4), drops/alters (5). A `CREATE TABLE` from a newer migration therefore still runs before an older migration's `ALTER`.
+2. **`createdAt`** — parsed from the filename prefix.
+3. **Migration name** — alphabetical, only when the timestamps can't decide.
+
+Because phase wins, cross-migration ordering matters most for statements that share a phase — two migrations both altering the same table, for instance.
+
+:::caution[`MM-DD` vs `DD-MM` is a guess]
+The parser tells the two apart by whether the first field is greater than 12 — a month can't be. When both fields are ≤ 12 the stamp is genuinely ambiguous and it assumes `MM-DD`. Two migrations generated on `01-08` and `08-01` of the same year sort by that assumption rather than by fact. If exact ordering between two such files matters, make it unambiguous — a differing hour is enough.
+:::
+
 ## Column helpers — the building blocks
 
 Every column in a `Migration.create` / `Migration.alter` map starts with a helper imported from `@warlock.js/cascade`; each returns a builder you chain modifiers onto (`.notNullable()`, `.nullable()`, `.unique()`, `.default(value)`, `.index()`, `.primary()`, `.references(table)`):