@warlock.js/cascade 4.0.174 → 4.1.1

package/esm/utils/define-model.d.mts

@@ -0,0 +1,185 @@
+import { DeleteStrategy, StrictMode } from "../types.mjs";
+import { ModelSchema } from "../model/model.types.mjs";
+import { Model } from "../model/model.mjs";
+import { Infer, ObjectValidator } from "@warlock.js/seal";
+
+//#region ../../@warlock.js/cascade/src/utils/define-model.d.ts
+/**
+ * Configuration options for defining a model.
+ */
+type DefineModelOptions<TSchema extends ModelSchema> = {
+  /**
+   * The database table/collection name.
+   */
+  table: string;
+  /**
+   * Model name
+   * If provided, it will be registered in the models registery
+   */
+  name?: string;
+  /**
+   * The validation schema for the model.
+   * Use `v.object()` from @warlock.js/seal to define the schema.
+   */
+  schema: ObjectValidator;
+  /**
+   * Delete strategy for this model. Controls how `destroy()` handles records.
+   *
+   * - `"trash"` — Moves the record to a trash table/collection, then deletes from the source.
+   * - `"permanent"` — Hard delete. The record is removed from the database.
+   * - `"soft"` — Sets a `deletedAt` timestamp; the row stays in place.
+   *
+   * When omitted, the runtime resolves the strategy in this priority order:
+   * `destroy()` call options → this model's static → data source `defaultDeleteStrategy` → `"permanent"`.
+   */
+  deleteStrategy?: DeleteStrategy;
+  /**
+   * Behavior when the model is asked to write a field that is not declared in `schema`.
+   *
+   * - `"strip"` — Drop unknown fields silently (default).
+   * - `"fail"` — Throw a validation error on unknown fields.
+   * - `"allow"` — Pass unknown fields through to the database as-is.
+   */
+  strictMode?: StrictMode;
+  /**
+   * Auto-generate a sequential `id` field on insert (NoSQL only).
+   *
+   * SQL drivers use native AUTO_INCREMENT and ignore this. When omitted, the
+   * MongoDB driver defaults to `true`; the PostgreSQL driver defaults to `false`.
+   */
+  autoGenerateId?: boolean;
+  /**
+   * Use a random increment (1–10) instead of a fixed step when auto-generating IDs.
+   *
+   * When omitted, falls through to the driver/data-source default.
+   */
+  randomIncrement?: boolean;
+  /**
+   * Initial ID value for the first record when auto-generating IDs.
+   *
+   * When omitted, falls through to the driver/data-source default (typically `1`).
+   */
+  initialId?: number;
+  /**
+   * Optional: Custom instance properties (getters/setters/methods).
+   * Define computed properties, custom getters, or instance methods.
+   *
+   * The `this` context will be the Model instance, giving you access to
+   * all Model methods like `get()`, `set()`, `save()`, etc.
+   *
+   * @example
+   * ```typescript
+   * properties: {
+   *   get fullName(this: Model<UserSchema>) {
+   *     return `${this.get("firstName")} ${this.get("lastName")}`;
+   *   },
+   *   get isActive(this: Model<UserSchema>) {
+   *     return this.get("status") === "active";
+   *   },
+   *   async sendEmail(this: Model<UserSchema>, subject: string) {
+   *     // this.get(), this.save(), etc. all work!
+   *   },
+   * }
+   * ```
+   */
+  properties?: ThisType<Model<TSchema>> & Record<string, any>;
+  /**
+   * Optional: Custom static methods.
+   * Define class-level methods like custom finders or utilities.
+   *
+   * @example
+   * ```typescript
+   * statics: {
+   *   async findByEmail(email: string) {
+   *     return this.first({ email });
+   *   },
+   *   async findActive() {
+   *     return this.query().where("status", "active").get();
+   *   },
+   * }
+   * ```
+   */
+  statics?: Record<string, any>;
+};
+/**
+ * Define a model with a clean, concise API.
+ *
+ * This utility function creates a Model class with the specified configuration,
+ * reducing boilerplate and providing a more declarative way to define models.
+ *
+ * @param options - Model configuration options
+ * @returns A Model class with the specified configuration
+ *
+ * @example
+ * ```typescript
+ * import { defineModel } from "@warlock.js/cascade";
+ * import { v } from "@warlock.js/seal";
+ *
+ * export const User = defineModel({
+ *   table: "users",
+ *   schema: v.object({
+ *     name: v.string().required().trim(),
+ *     email: v.string().email().required().lowercase(),
+ *     password: v.string().required().min(6),
+ *     role: v.string().default("user"),
+ *   }),
+ *   deleteStrategy: "soft",
+ * });
+ *
+ * // Usage
+ * const user = await User.create({
+ *   name: "John Doe",
+ *   email: "john@example.com",
+ *   password: "secret123",
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With type inference
+ * export const Post = defineModel({
+ *   table: "posts",
+ *   schema: v.object({
+ *     title: v.string().required(),
+ *     content: v.string().required(),
+ *     authorId: v.number().required(),
+ *     published: v.boolean().default(false),
+ *   }),
+ * });
+ *
+ * // TypeScript knows the exact type!
+ * const post = await Post.create({
+ *   title: "Hello World",
+ *   content: "My first post",
+ *   authorId: 1,
+ * });
+ *
+ * console.log(post.title); // ✅ Type-safe!
+ * ```
+ */
+declare function defineModel<TSchema extends ModelSchema, TSchemaValidator extends ObjectValidator = ObjectValidator, TProperties extends Record<string, any> = {}, TStatics extends Record<string, any> = {}>(options: DefineModelOptions<TSchema> & {
+  schema: TSchemaValidator;
+  properties?: ThisType<Model<Infer.Output<TSchemaValidator>>> & TProperties;
+  statics?: ThisType<typeof Model<Infer.Output<TSchemaValidator>>> & TStatics;
+}): (new (initialData?: Partial<Infer.Output<TSchemaValidator>>) => Model<Infer.Output<TSchemaValidator>> & TProperties) & Omit<typeof Model, "new"> & TStatics;
+/**
+ * Type helper to infer the schema type from a defined model.
+ *
+ * @example
+ * ```typescript
+ * const User = defineModel({
+ *   table: "users",
+ *   schema: v.object({
+ *     name: v.string(),
+ *     email: v.string(),
+ *   }),
+ * });
+ *
+ * type UserType = ModelType<typeof User>;
+ * // { name: string; email: string; }
+ * ```
+ */
+type ModelType<T extends ReturnType<typeof defineModel>> = T extends (new (...args: any[]) => infer R) ? R extends Model<infer S> ? S : never : never;
+//#endregion
+export { DefineModelOptions, ModelType, defineModel };
+//# sourceMappingURL=define-model.d.mts.map

package/esm/utils/define-model.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-model.d.mts","names":[],"sources":["../../../../../../@warlock.js/cascade/src/utils/define-model.ts"],"mappings":";;;;;;;;AASA;KAAY,kBAAA,iBAAmC,WAAA;EAAjB;;;EAI5B,KAAA;EAiCa;;;;EA3Bb,IAAA;EA2FU;;;;EArFV,MAAA,EAAQ,eAAA;EAZR;;;;;;;;;;EAwBA,cAAA,GAAiB,cAAA;EAuDjB;;;;;;;EA9CA,UAAA,GAAa,UAAA;EAgEG;AA2DlB;;;;;EAnHE,cAAA;EAsHoB;;;;;EA/GpB,eAAA;EAoH8B;;;;;EA7G9B,SAAA;EA8G4B;;;;;;;;;;;;;;;;;;;;;;EAtF5B,UAAA,GAAa,QAAA,CAAS,KAAA,CAAM,OAAA,KAAY,MAAA;EAiFvB;;;;;;;;;;;;;;;;EA/DjB,OAAA,GAAU,MAAA;AAAA;;;;;;;;;;;;;;;;;AAgJwE;AAwBpF;;;;;;;;;;;;;;;;;;;;AAIO;;;;;;;;;;;;;;;;;;;iBAjHS,WAAA,iBACE,WAAA,2BACS,eAAA,GAAkB,eAAA,sBACvB,MAAA,qCACH,MAAA,mBAAA,CAEjB,OAAA,EAAS,kBAAA,CAAmB,OAAA;EAC1B,MAAA,EAAQ,gBAAA;EACR,UAAA,GAAa,QAAA,CAAS,KAAA,CAAM,KAAA,CAAM,MAAA,CAAO,gBAAA,MAAsB,WAAA;EAC/D,OAAA,GAAU,QAAA,QAAgB,KAAA,CAAM,KAAA,CAAM,MAAA,CAAO,gBAAA,MAAsB,QAAA;AAAA,UACpE,WAAA,GA2EoB,OAAA,CAAO,KAAA,CAAA,MAAA,CAAA,gBAAA,OAAmB,KAAA,CAAK,KAAA,CAAA,MAAA,CAAA,gBAAA,KAAmB,WAAA,IAAW,IAAA,QAAA,KAAA,WAAA,QAAA;;;;;;;;;;;;;;;;;;KAwBxE,SAAA,WAAoB,UAAA,QAAkB,WAAA,KAAgB,CAAA,kBAC7D,IAAA,uBAED,CAAA,SAAU,KAAA,YACR,CAAA"}

package/esm/utils/define-model.mjs

@@ -0,0 +1,105 @@
+import { registerModelInRegistry } from "../model/register-model.mjs";
+import { Model } from "../model/model.mjs";
+
+//#region ../../@warlock.js/cascade/src/utils/define-model.ts
+/**
+* Define a model with a clean, concise API.
+*
+* This utility function creates a Model class with the specified configuration,
+* reducing boilerplate and providing a more declarative way to define models.
+*
+* @param options - Model configuration options
+* @returns A Model class with the specified configuration
+*
+* @example
+* ```typescript
+* import { defineModel } from "@warlock.js/cascade";
+* import { v } from "@warlock.js/seal";
+*
+* export const User = defineModel({
+*   table: "users",
+*   schema: v.object({
+*     name: v.string().required().trim(),
+*     email: v.string().email().required().lowercase(),
+*     password: v.string().required().min(6),
+*     role: v.string().default("user"),
+*   }),
+*   deleteStrategy: "soft",
+* });
+*
+* // Usage
+* const user = await User.create({
+*   name: "John Doe",
+*   email: "john@example.com",
+*   password: "secret123",
+* });
+* ```
+*
+* @example
+* ```typescript
+* // With type inference
+* export const Post = defineModel({
+*   table: "posts",
+*   schema: v.object({
+*     title: v.string().required(),
+*     content: v.string().required(),
+*     authorId: v.number().required(),
+*     published: v.boolean().default(false),
+*   }),
+* });
+*
+* // TypeScript knows the exact type!
+* const post = await Post.create({
+*   title: "Hello World",
+*   content: "My first post",
+*   authorId: 1,
+* });
+*
+* console.log(post.title); // ✅ Type-safe!
+* ```
+*/
+function defineModel(options) {
+	class DefinedModel extends Model {
+		/**
+		* Table/collection name
+		*/
+		static table = options.table;
+		/**
+		* Validation schema
+		*/
+		static schema = options.schema;
+		/**
+		* Delete strategy. When undefined, the runtime resolves via call options →
+		* data source `defaultDeleteStrategy` → `"permanent"`.
+		*/
+		static deleteStrategy = options.deleteStrategy;
+		/**
+		* Strict mode for unknown fields. Defaults to `"strip"` to match the base
+		* `Model` static default.
+		*/
+		static strictMode = options.strictMode || "strip";
+		/**
+		* Auto-generate sequential IDs (NoSQL only). Defaults to `true` to match
+		* the base `Model` static default.
+		*/
+		static autoGenerateId = options.autoGenerateId ?? true;
+		/**
+		* Random increment for auto-generated IDs. When undefined, falls through
+		* to the data-source default.
+		*/
+		static randomIncrement = options.randomIncrement;
+		/**
+		* Initial ID value for the first record when auto-generating IDs. When
+		* undefined, falls through to the data-source default.
+		*/
+		static initialId = options.initialId;
+	}
+	if (options.properties) Object.defineProperties(DefinedModel.prototype, Object.getOwnPropertyDescriptors(options.properties));
+	if (options.name) registerModelInRegistry(options.name, DefinedModel);
+	if (options.statics) Object.defineProperties(DefinedModel, Object.getOwnPropertyDescriptors(options.statics));
+	return DefinedModel;
+}
+
+//#endregion
+export { defineModel };
+//# sourceMappingURL=define-model.mjs.map

package/esm/utils/define-model.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-model.mjs","names":[],"sources":["../../../../../../@warlock.js/cascade/src/utils/define-model.ts"],"sourcesContent":["import type { Infer, ObjectValidator } from \"@warlock.js/seal\";\nimport type { ModelSchema } from \"../model/model\";\nimport { Model } from \"../model/model\";\nimport { registerModelInRegistry } from \"../model/register-model\";\nimport type { DeleteStrategy, StrictMode } from \"../types\";\n\n/**\n * Configuration options for defining a model.\n */\nexport type DefineModelOptions<TSchema extends ModelSchema> = {\n  /**\n   * The database table/collection name.\n   */\n  table: string;\n\n  /**\n   * Model name\n   * If provided, it will be registered in the models registery\n   */\n  name?: string;\n\n  /**\n   * The validation schema for the model.\n   * Use `v.object()` from @warlock.js/seal to define the schema.\n   */\n  schema: ObjectValidator;\n\n  /**\n   * Delete strategy for this model. Controls how `destroy()` handles records.\n   *\n   * - `\"trash\"` — Moves the record to a trash table/collection, then deletes from the source.\n   * - `\"permanent\"` — Hard delete. The record is removed from the database.\n   * - `\"soft\"` — Sets a `deletedAt` timestamp; the row stays in place.\n   *\n   * When omitted, the runtime resolves the strategy in this priority order:\n   * `destroy()` call options → this model's static → data source `defaultDeleteStrategy` → `\"permanent\"`.\n   */\n  deleteStrategy?: DeleteStrategy;\n\n  /**\n   * Behavior when the model is asked to write a field that is not declared in `schema`.\n   *\n   * - `\"strip\"` — Drop unknown fields silently (default).\n   * - `\"fail\"` — Throw a validation error on unknown fields.\n   * - `\"allow\"` — Pass unknown fields through to the database as-is.\n   */\n  strictMode?: StrictMode;\n\n  /**\n   * Auto-generate a sequential `id` field on insert (NoSQL only).\n   *\n   * SQL drivers use native AUTO_INCREMENT and ignore this. When omitted, the\n   * MongoDB driver defaults to `true`; the PostgreSQL driver defaults to `false`.\n   */\n  autoGenerateId?: boolean;\n\n  /**\n   * Use a random increment (1–10) instead of a fixed step when auto-generating IDs.\n   *\n   * When omitted, falls through to the driver/data-source default.\n   */\n  randomIncrement?: boolean;\n\n  /**\n   * Initial ID value for the first record when auto-generating IDs.\n   *\n   * When omitted, falls through to the driver/data-source default (typically `1`).\n   */\n  initialId?: number;\n\n  /**\n   * Optional: Custom instance properties (getters/setters/methods).\n   * Define computed properties, custom getters, or instance methods.\n   *\n   * The `this` context will be the Model instance, giving you access to\n   * all Model methods like `get()`, `set()`, `save()`, etc.\n   *\n   * @example\n   * ```typescript\n   * properties: {\n   *   get fullName(this: Model<UserSchema>) {\n   *     return `${this.get(\"firstName\")} ${this.get(\"lastName\")}`;\n   *   },\n   *   get isActive(this: Model<UserSchema>) {\n   *     return this.get(\"status\") === \"active\";\n   *   },\n   *   async sendEmail(this: Model<UserSchema>, subject: string) {\n   *     // this.get(), this.save(), etc. all work!\n   *   },\n   * }\n   * ```\n   */\n  properties?: ThisType<Model<TSchema>> & Record<string, any>;\n\n  /**\n   * Optional: Custom static methods.\n   * Define class-level methods like custom finders or utilities.\n   *\n   * @example\n   * ```typescript\n   * statics: {\n   *   async findByEmail(email: string) {\n   *     return this.first({ email });\n   *   },\n   *   async findActive() {\n   *     return this.query().where(\"status\", \"active\").get();\n   *   },\n   * }\n   * ```\n   */\n  statics?: Record<string, any>;\n};\n\n/**\n * Define a model with a clean, concise API.\n *\n * This utility function creates a Model class with the specified configuration,\n * reducing boilerplate and providing a more declarative way to define models.\n *\n * @param options - Model configuration options\n * @returns A Model class with the specified configuration\n *\n * @example\n * ```typescript\n * import { defineModel } from \"@warlock.js/cascade\";\n * import { v } from \"@warlock.js/seal\";\n *\n * export const User = defineModel({\n *   table: \"users\",\n *   schema: v.object({\n *     name: v.string().required().trim(),\n *     email: v.string().email().required().lowercase(),\n *     password: v.string().required().min(6),\n *     role: v.string().default(\"user\"),\n *   }),\n *   deleteStrategy: \"soft\",\n * });\n *\n * // Usage\n * const user = await User.create({\n *   name: \"John Doe\",\n *   email: \"john@example.com\",\n *   password: \"secret123\",\n * });\n * ```\n *\n * @example\n * ```typescript\n * // With type inference\n * export const Post = defineModel({\n *   table: \"posts\",\n *   schema: v.object({\n *     title: v.string().required(),\n *     content: v.string().required(),\n *     authorId: v.number().required(),\n *     published: v.boolean().default(false),\n *   }),\n * });\n *\n * // TypeScript knows the exact type!\n * const post = await Post.create({\n *   title: \"Hello World\",\n *   content: \"My first post\",\n *   authorId: 1,\n * });\n *\n * console.log(post.title); // ✅ Type-safe!\n * ```\n */\nexport function defineModel<\n  TSchema extends ModelSchema,\n  TSchemaValidator extends ObjectValidator = ObjectValidator,\n  TProperties extends Record<string, any> = {},\n  TStatics extends Record<string, any> = {},\n>(\n  options: DefineModelOptions<TSchema> & {\n    schema: TSchemaValidator;\n    properties?: ThisType<Model<Infer.Output<TSchemaValidator>>> & TProperties;\n    statics?: ThisType<typeof Model<Infer.Output<TSchemaValidator>>> & TStatics;\n  },\n) {\n  type InferredSchema = Infer.Output<TSchemaValidator>;\n\n  class DefinedModel extends Model<InferredSchema> {\n    /**\n     * Table/collection name\n     */\n    public static table = options.table;\n\n    /**\n     * Validation schema\n     */\n    public static schema = options.schema;\n\n    /**\n     * Delete strategy. When undefined, the runtime resolves via call options →\n     * data source `defaultDeleteStrategy` → `\"permanent\"`.\n     */\n    public static deleteStrategy: DeleteStrategy | undefined = options.deleteStrategy;\n\n    /**\n     * Strict mode for unknown fields. Defaults to `\"strip\"` to match the base\n     * `Model` static default.\n     */\n    public static strictMode: StrictMode = options.strictMode || \"strip\";\n\n    /**\n     * Auto-generate sequential IDs (NoSQL only). Defaults to `true` to match\n     * the base `Model` static default.\n     */\n    public static autoGenerateId: boolean = options.autoGenerateId ?? true;\n\n    /**\n     * Random increment for auto-generated IDs. When undefined, falls through\n     * to the data-source default.\n     */\n    public static randomIncrement: boolean | undefined = options.randomIncrement;\n\n    /**\n     * Initial ID value for the first record when auto-generating IDs. When\n     * undefined, falls through to the data-source default.\n     */\n    public static initialId: number | undefined = options.initialId;\n  }\n\n  // Apply custom instance properties (getters/setters/methods)\n  if (options.properties) {\n    Object.defineProperties(\n      DefinedModel.prototype,\n      Object.getOwnPropertyDescriptors(options.properties),\n    );\n  }\n\n  if (options.name) {\n    registerModelInRegistry(options.name, DefinedModel);\n  }\n\n  // Apply custom static methods\n  if (options.statics) {\n    Object.defineProperties(DefinedModel, Object.getOwnPropertyDescriptors(options.statics));\n  }\n\n  // Return with proper type inference.\n  //\n  // The constructed type references the EXPORTED `Model` (instance + statics)\n  // rather than the local `DefinedModel` class. `DefinedModel` is declared\n  // inside this function, so emitting it into the public `.d.ts` would force the\n  // declaration emitter to inline it as an anonymous class type — which fails\n  // with TS4094 (\"anonymous class type may not be private or protected\", from\n  // Model's `protected isActiveColumn`) and crashes the dts bundler on Model's\n  // getters. `DefinedModel` adds no instance members over `Model<InferredSchema>`\n  // and no statics beyond those already declared on `Model`, so this is a\n  // faithful, emittable equivalent of the previously-inferred return type.\n  type DefinedModelClass = {\n    new (initialData?: Partial<InferredSchema>): Model<InferredSchema> & TProperties;\n  } & Omit<typeof Model, \"new\"> &\n    TStatics;\n\n  return DefinedModel as unknown as DefinedModelClass;\n}\n\n/**\n * Type helper to infer the schema type from a defined model.\n *\n * @example\n * ```typescript\n * const User = defineModel({\n *   table: \"users\",\n *   schema: v.object({\n *     name: v.string(),\n *     email: v.string(),\n *   }),\n * });\n *\n * type UserType = ModelType<typeof User>;\n * // { name: string; email: string; }\n * ```\n */\nexport type ModelType<T extends ReturnType<typeof defineModel>> = T extends new (\n  ...args: any[]\n) => infer R\n  ? R extends Model<infer S>\n    ? S\n    : never\n  : never;\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyKA,SAAgB,YAMd,SAKA;CAGA,MAAM,qBAAqB,MAAsB;;;;EAI/C,OAAc,QAAQ,QAAQ;;;;EAK9B,OAAc,SAAS,QAAQ;;;;;EAM/B,OAAc,iBAA6C,QAAQ;;;;;EAMnE,OAAc,aAAyB,QAAQ,cAAc;;;;;EAM7D,OAAc,iBAA0B,QAAQ,kBAAkB;;;;;EAMlE,OAAc,kBAAuC,QAAQ;;;;;EAM7D,OAAc,YAAgC,QAAQ;CACxD;CAGA,IAAI,QAAQ,YACV,OAAO,iBACL,aAAa,WACb,OAAO,0BAA0B,QAAQ,UAAU,CACrD;CAGF,IAAI,QAAQ,MACV,wBAAwB,QAAQ,MAAM,YAAY;CAIpD,IAAI,QAAQ,SACV,OAAO,iBAAiB,cAAc,OAAO,0BAA0B,QAAQ,OAAO,CAAC;CAmBzF,OAAO;AACT"}

package/esm/utils/is-valid-date-value.mjs

@@ -0,0 +1,22 @@
+//#region ../../@warlock.js/cascade/src/utils/is-valid-date-value.ts
+const isoRegex = /^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d{3})?Z?)?$/;
+/**
+* Check if the given value is a valid date value
+*/
+function isValidDateValue(value) {
+	if (typeof value === "number") {
+		if (!Number.isFinite(value)) return false;
+		const date = new Date(value);
+		return !Number.isNaN(date.getTime());
+	}
+	if (typeof value !== "string") return false;
+	if (!isoRegex.test(value)) return false;
+	const date = new Date(value);
+	if (Number.isNaN(date.getTime())) return false;
+	const [y, m, d] = value.split("T")[0].split("-").map(Number);
+	return date.getUTCFullYear() === y && date.getUTCMonth() + 1 === m && date.getUTCDate() === d;
+}
+
+//#endregion
+export { isValidDateValue };
+//# sourceMappingURL=is-valid-date-value.mjs.map

package/esm/utils/is-valid-date-value.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"is-valid-date-value.mjs","names":[],"sources":["../../../../../../@warlock.js/cascade/src/utils/is-valid-date-value.ts"],"sourcesContent":["const isoRegex = /^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$/;\n\n/**\n * Check if the given value is a valid date value\n */\nexport function isValidDateValue(value: unknown): boolean {\n  // ✅ Handle timestamps\n  if (typeof value === \"number\") {\n    if (!Number.isFinite(value)) return false;\n\n    const date = new Date(value);\n    return !Number.isNaN(date.getTime());\n  }\n\n  // ❌ Only allow strict ISO strings\n  if (typeof value !== \"string\") return false;\n\n  if (!isoRegex.test(value)) return false;\n\n  const date = new Date(value);\n  if (Number.isNaN(date.getTime())) return false;\n\n  // 🔥 Critical step: prevent JS auto-correction\n  // Example: \"2023-02-31\" → March 3 (WRONG but \"valid\")\n  const [y, m, d] = value.split(\"T\")[0].split(\"-\").map(Number);\n\n  return date.getUTCFullYear() === y && date.getUTCMonth() + 1 === m && date.getUTCDate() === d;\n}\n"],"mappings":";AAAA,MAAM,WAAW;;;;AAKjB,SAAgB,iBAAiB,OAAyB;CAExD,IAAI,OAAO,UAAU,UAAU;EAC7B,IAAI,CAAC,OAAO,SAAS,KAAK,GAAG,OAAO;EAEpC,MAAM,OAAO,IAAI,KAAK,KAAK;EAC3B,OAAO,CAAC,OAAO,MAAM,KAAK,QAAQ,CAAC;CACrC;CAGA,IAAI,OAAO,UAAU,UAAU,OAAO;CAEtC,IAAI,CAAC,SAAS,KAAK,KAAK,GAAG,OAAO;CAElC,MAAM,OAAO,IAAI,KAAK,KAAK;CAC3B,IAAI,OAAO,MAAM,KAAK,QAAQ,CAAC,GAAG,OAAO;CAIzC,MAAM,CAAC,GAAG,GAAG,KAAK,MAAM,MAAM,GAAG,EAAE,GAAG,MAAM,GAAG,EAAE,IAAI,MAAM;CAE3D,OAAO,KAAK,eAAe,MAAM,KAAK,KAAK,YAAY,IAAI,MAAM,KAAK,KAAK,WAAW,MAAM;AAC9F"}

package/esm/utils/once-connected.d.mts

@@ -0,0 +1,150 @@
+import { DataSource } from "../data-source/data-source.mjs";
+
+//#region ../../@warlock.js/cascade/src/utils/once-connected.d.ts
+/**
+ * Execute a callback once the driver is connected.
+ *
+ * If the driver is already connected, the callback is executed immediately.
+ * Otherwise, it waits for the "connected" event.
+ *
+ * **Use Case:**
+ * Useful for ensuring database-dependent operations only run after connection
+ * is established, especially in small to medium projects with a single data source.
+ *
+ * @param dataSourceOrNameOrCallback - Data source instance, name, or callback function
+ * @param callback - Function to execute once connected (optional if first param is callback)
+ *
+ * @example
+ * ```typescript
+ * // With default data source (just callback)
+ * await connectToDatabase({ database: "myapp" });
+ *
+ * onceConnected((ds) => {
+ *   console.log("Database is ready!");
+ *   console.log("Connected to:", ds.name);
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With data source name
+ * onceConnected("primary", (ds) => {
+ *   console.log("Primary database is ready!");
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With data source instance
+ * const dataSource = await connectToDatabase({ database: "myapp" });
+ *
+ * onceConnected(dataSource, (ds) => {
+ *   console.log("Database is ready!");
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With driver instance
+ * const driver = new MongoDbDriver(config);
+ * const dataSource = new DataSource({ name: "primary", driver });
+ *
+ * onceConnected(dataSource, () => {
+ *   // Start application server
+ *   app.listen(3000);
+ * });
+ *
+ * // Connect after setting up the callback
+ * await driver.connect();
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Chaining operations
+ * onceConnected(async (ds) => {
+ *   // Seed database
+ *   await seedDatabase();
+ *
+ *   // Run migrations
+ *   await runMigrations();
+ *
+ *   console.log("Database ready!");
+ * });
+ * ```
+ */
+declare function onceConnected(dataSourceOrNameOrCallback: DataSource | string | ((dataSource: DataSource) => void), callback?: (dataSource: DataSource) => void): void;
+/**
+ * Execute a callback once the driver is disconnected.
+ *
+ * If the driver is already disconnected, the callback is executed immediately.
+ * Otherwise, it waits for the "disconnected" event.
+ *
+ * **Use Case:**
+ * Useful for cleanup operations, graceful shutdown, or reconnection logic.
+ *
+ * @param dataSourceOrNameOrCallback - Data source instance, name, or callback function
+ * @param callback - Function to execute once disconnected (optional if first param is callback)
+ *
+ * @example
+ * ```typescript
+ * // With default data source (just callback)
+ * await connectToDatabase({ database: "myapp" });
+ *
+ * onceDisconnected((ds) => {
+ *   console.log("Database disconnected!");
+ *   console.log("Attempting reconnection...");
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With data source name
+ * onceDisconnected("primary", (ds) => {
+ *   console.log("Primary database disconnected!");
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With data source instance
+ * const dataSource = await connectToDatabase({ database: "myapp" });
+ *
+ * onceDisconnected(dataSource, (ds) => {
+ *   console.log("Database disconnected!");
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Graceful shutdown with default data source
+ * process.on("SIGTERM", async () => {
+ *   console.log("Shutting down...");
+ *
+ *   onceDisconnected(() => {
+ *     console.log("Database closed, exiting process");
+ *     process.exit(0);
+ *   });
+ *
+ *   const dataSource = DataSourceRegistry.getDefault();
+ *   await dataSource?.driver.disconnect();
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Cleanup resources on disconnect
+ * onceDisconnected(async (ds) => {
+ *   // Close file handles
+ *   await closeFileHandles();
+ *
+ *   // Clear caches
+ *   clearCaches();
+ *
+ *   console.log("Cleanup complete");
+ * });
+ * ```
+ */
+declare function onceDisconnected(dataSourceOrNameOrCallback: DataSource | string | ((dataSource: DataSource) => void), callback?: (dataSource: DataSource) => void): void;
+//#endregion
+export { onceConnected, onceDisconnected };
+//# sourceMappingURL=once-connected.d.mts.map

package/esm/utils/once-connected.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"once-connected.d.mts","names":[],"sources":["../../../../../../@warlock.js/cascade/src/utils/once-connected.ts"],"mappings":";;;;;AA0EA;;;;;;;;;;;;;;;;AAE6C;AAmI7C;;;;;;;;;;;;;;;;AAE6C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAvI7B,aAAA,CACd,0BAAA,EAA4B,UAAA,cAAwB,UAAA,EAAY,UAAA,YAChE,QAAA,IAAY,UAAA,EAAY,UAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAmIV,gBAAA,CACd,0BAAA,EAA4B,UAAA,cAAwB,UAAA,EAAY,UAAA,YAChE,QAAA,IAAY,UAAA,EAAY,UAAA"}