@warlock.js/cascade 4.0.174 → 4.1.1

package/esm/model/relation-decorators.d.mts

@@ -0,0 +1,88 @@
+import { ChildModel } from "./model.types.mjs";
+import { BelongsToManyOptions, BelongsToOptions, HasManyOptions, HasOneOptions } from "../relations/types.mjs";
+import { Model } from "./model.mjs";
+import { Lazy } from "@mongez/reinforcements";
+
+//#region ../../@warlock.js/cascade/src/model/relation-decorators.d.ts
+/**
+ * Key used to stash relation definitions on the decorator metadata object.
+ * Exported so `@RegisterModel` (in `register-model.ts`) can read it back.
+ */
+declare const RELATION_METADATA_KEY: unique symbol;
+/**
+ * Declares a `belongsTo` relation on a model field.
+ *
+ * The foreign key lives on **this** model and points at the related
+ * model's primary key. Defaults: FK column inferred as `{relationName}_id`
+ * (snake-cased) — e.g. `organization_id` for `organization?: Organization`.
+ *
+ * @param model - The related model, in any of three forms:
+ *   - `"User"` — registered name (requires `@RegisterModel()` on target).
+ *   - `User` — direct class reference (cleanest for non-cycle relations).
+ *   - `lazy(() => User)` — typed but cycle-safe (use when the two model
+ *     files import each other).
+ * @param options - Inline overrides for FK / owner key / column select
+ *
+ * @example
+ * ```ts
+ * import { lazy } from "@mongez/reinforcements";
+ *
+ * class User extends Model {
+ *   @BelongsTo(Organization) public organization?: Organization;
+ *   @BelongsTo("User", { foreignKey: "manager_id" }) public manager?: User;
+ *   @BelongsTo(lazy(() => Team)) public team?: Team; // cycle case
+ * }
+ * ```
+ */
+declare const BelongsTo: (modelRelation: string | ChildModel<Model> | Lazy<unknown>, options?: string | BelongsToOptions | undefined) => <This>(_value: undefined, context: ClassFieldDecoratorContext<This>) => void;
+/**
+ * Declares a `hasOne` relation on a model field.
+ *
+ * The foreign key lives on the **related** model and points back at this
+ * model's primary key. Defaults: FK column inferred as
+ * `{thisModelSnakeName}_id` (e.g. `user_id` on the `Profile` table).
+ *
+ * @example
+ * ```ts
+ * class User extends Model {
+ *   @HasOne("Profile") profile?: Profile;
+ *   @HasOne("UserSettings", { foreignKey: "owner_id" }) settings?: UserSettings;
+ * }
+ * ```
+ */
+declare const HasOne: (modelRelation: string | ChildModel<Model> | Lazy<unknown>, options?: string | HasOneOptions | undefined) => <This>(_value: undefined, context: ClassFieldDecoratorContext<This>) => void;
+/**
+ * Declares a `hasMany` relation on a model field.
+ *
+ * Same shape as `@HasOne` but loads an array. The foreign key lives on
+ * the related model. Defaults: FK column inferred as
+ * `{thisModelSnakeName}_id`.
+ *
+ * @example
+ * ```ts
+ * class User extends Model {
+ *   @HasMany("Post") posts?: Post[];
+ *   @HasMany("Comment", { foreignKey: "author_id" }) comments?: Comment[];
+ * }
+ * ```
+ */
+declare const HasMany: (modelRelation: string | ChildModel<Model> | Lazy<unknown>, options?: string | HasManyOptions | undefined) => <This>(_value: undefined, context: ClassFieldDecoratorContext<This>) => void;
+/**
+ * Declares a `belongsToMany` relation on a model field.
+ *
+ * Defaults: pivot table inferred as the alphabetical snake-case join of
+ * the two model names (`Post` + `Tag` → `post_tag`); pivot columns
+ * inferred as `{modelSnakeName}_id` on each side.
+ *
+ * @example
+ * ```ts
+ * class Post extends Model {
+ *   @BelongsToMany("Tag") tags?: Tag[];
+ *   @BelongsToMany("User", { pivot: "post_collaborators" }) collaborators?: User[];
+ * }
+ * ```
+ */
+declare const BelongsToMany: (modelRelation: string | ChildModel<Model> | Lazy<unknown>, options?: string | BelongsToManyOptions | undefined) => <This>(_value: undefined, context: ClassFieldDecoratorContext<This>) => void;
+//#endregion
+export { BelongsTo, BelongsToMany, HasMany, HasOne, RELATION_METADATA_KEY };
+//# sourceMappingURL=relation-decorators.d.mts.map

package/esm/model/relation-decorators.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relation-decorators.d.mts","names":[],"sources":["../../../../../../@warlock.js/cascade/src/model/relation-decorators.ts"],"mappings":";;;;;;;;;;cA2Ha,qBAAA;;;AAgB0E;AAqFvF;;;;;;;;;;;;;;;;;;;;;;cAjBa,SAAA,GAAS,aAAA,WAvEM,UAAA,CAAW,KAAA,IAAS,IAAA,WAAa,OAAA,YAAA,gBAAA,wBAGlC,MAAA,aAAmB,OAAA,EAAS,0BAAA,CAA2B,IAAA;AAAK;AAsGvF;;;;;;;;;;;;;;AAtGuF,cAqF1E,MAAA,GAAM,aAAA,WAxFS,UAAA,CAAW,KAAA,IAAS,IAAA,WAAa,OAAA,YAAA,aAAA,wBAGlC,MAAA,aAAmB,OAAA,EAAS,0BAAA,CAA2B,IAAA;;;;;;;;;AAAK;AAuHvF;;;;;;cAjBa,OAAA,GAAO,aAAA,WAzGQ,UAAA,CAAW,KAAA,IAAS,IAAA,WAAa,OAAA,YAAA,cAAA,wBAGlC,MAAA,aAAmB,OAAA,EAAS,0BAAA,CAA2B,IAAA;;;;;;;;;;;;;;;;cAuHrE,aAAA,GAAa,aAAA,WA1HE,UAAA,CAAW,KAAA,IAAS,IAAA,WAAa,OAAA,YAAA,oBAAA,wBAGlC,MAAA,aAAmB,OAAA,EAAS,0BAAA,CAA2B,IAAA"}

package/esm/model/relation-decorators.mjs

@@ -0,0 +1,191 @@
+import { capitalize } from "@mongez/reinforcements";
+
+//#region ../../@warlock.js/cascade/src/model/relation-decorators.ts
+/**
+* @fileoverview TC39 Stage 3 class field decorators for declaring model
+* relations directly on the field.
+*
+* Replaces the legacy `static relations = { name: hasMany("Foo") }` shape
+* with co-located, single-declaration syntax:
+*
+* @example
+* ```ts
+* @RegisterModel()
+* class User extends Model {
+*   @BelongsTo("Organization") organization?: Organization;
+*   @HasOne("Profile") profile?: Profile;
+*   @HasMany("Post") posts?: Post[];
+*   @BelongsToMany("Group") groups?: Group[];
+* }
+* ```
+*
+* Foreign keys, local keys, and pivot tables are inferred from model names
+* via the convention helpers in `relations/key-conventions.ts`. Inline
+* options on the decorator override the conventions per relation.
+*
+* @module @warlock.js/cascade/model/relation-decorators
+*/
+/**
+* Map raw decorator inputs into a `RelationDefinition` of the canonical
+* shape consumed by the relation loader, pivot operations, etc.
+*
+* Note: foreign-key / pivot-table defaults are NOT resolved here — they
+* live on each runtime resolution path (`RelationLoader`, `PivotOperations`,
+* the postgres query builder) and read from `key-conventions.ts`. Recording
+* `undefined` here keeps a single source of truth for the inference logic.
+*/
+function buildRelationDefinition(type, model, options) {
+	const localKey = type === "belongsTo" ? options?.ownerKey : options?.localKey;
+	return {
+		type,
+		model,
+		foreignKey: options?.foreignKey,
+		localKey,
+		pivot: options?.pivot,
+		pivotLocalKey: options?.pivotLocalKey,
+		pivotForeignKey: options?.pivotForeignKey,
+		select: options?.select
+	};
+}
+/**
+* Stash a relation definition into the class-level decorator metadata bag.
+*
+* **Why metadata, not addInitializer?** `context.addInitializer` on a
+* *field* decorator fires per-instance, not per-class — so it only runs
+* when `new ModelClass(...)` is called. Class-level operations like
+* `Organization.withCount("users")` never construct instances, which means
+* an initializer-based registration would leave `Organization.relations`
+* permanently empty.
+*
+* TC39 stage 3 `context.metadata` is the right tool: a shared object across
+* every decorator on the same class declaration. Field decorators write
+* into it during decoration; `@RegisterModel` (a class decorator that runs
+* AFTER all field decorators) reads it back and copies the relations onto
+* the class's static `relations` map.
+*
+* The metadata object also prototype-chains to the parent class's metadata
+* (per spec), so a subclass naturally inherits its parent's relations.
+*/
+function stashRelationInMetadata(metadata, relationName, definition) {
+	let relations = metadata[RELATION_METADATA_KEY];
+	if (!Object.prototype.hasOwnProperty.call(metadata, RELATION_METADATA_KEY)) {
+		relations = { ...relations ?? {} };
+		metadata[RELATION_METADATA_KEY] = relations;
+	}
+	relations[relationName] = definition;
+}
+/**
+* Key used to stash relation definitions on the decorator metadata object.
+* Exported so `@RegisterModel` (in `register-model.ts`) can read it back.
+*/
+const RELATION_METADATA_KEY = Symbol.for("@warlock.js/cascade:relations");
+/**
+* Builds a TC39 stage 3 class-field decorator that registers a relation
+* of the given `type`. Each public decorator (`@BelongsTo`, `@HasMany`,
+* etc.) is a thin specialisation of this factory.
+*/
+function makeRelationDecorator(type) {
+	return function(modelRelation, options) {
+		return function(_value, context) {
+			if (context.kind !== "field") throw new Error(`@${capitalize(type)} can only be applied to class fields — got "${context.kind}".`);
+			const relationName = String(context.name);
+			const definition = buildRelationDefinition(type, modelRelation, resolveOptions(options));
+			stashRelationInMetadata(context.metadata, relationName, definition);
+		};
+	};
+}
+/**
+* Normalise the decorator's second argument.
+*
+* Accepts three shapes:
+* - Omitted (`undefined`): all defaults come from the runtime convention
+*   helpers (`inferBelongsToForeignKey`, `inferHasForeignKey`, …) per
+*   relation type. We must NOT pre-fill `foreignKey` here — the right
+*   convention depends on the relation type AND the *owner* model name,
+*   which the decorator doesn't know.
+* - String: shorthand for `{ foreignKey: <string> }`, matching the legacy
+*   `belongsTo("Foo", "fk_col")` helper.
+* - Object: passed through as-is.
+*/
+function resolveOptions(options) {
+	if (typeof options === "string") return { foreignKey: options };
+	return options;
+}
+/**
+* Declares a `belongsTo` relation on a model field.
+*
+* The foreign key lives on **this** model and points at the related
+* model's primary key. Defaults: FK column inferred as `{relationName}_id`
+* (snake-cased) — e.g. `organization_id` for `organization?: Organization`.
+*
+* @param model - The related model, in any of three forms:
+*   - `"User"` — registered name (requires `@RegisterModel()` on target).
+*   - `User` — direct class reference (cleanest for non-cycle relations).
+*   - `lazy(() => User)` — typed but cycle-safe (use when the two model
+*     files import each other).
+* @param options - Inline overrides for FK / owner key / column select
+*
+* @example
+* ```ts
+* import { lazy } from "@mongez/reinforcements";
+*
+* class User extends Model {
+*   @BelongsTo(Organization) public organization?: Organization;
+*   @BelongsTo("User", { foreignKey: "manager_id" }) public manager?: User;
+*   @BelongsTo(lazy(() => Team)) public team?: Team; // cycle case
+* }
+* ```
+*/
+const BelongsTo = makeRelationDecorator("belongsTo");
+/**
+* Declares a `hasOne` relation on a model field.
+*
+* The foreign key lives on the **related** model and points back at this
+* model's primary key. Defaults: FK column inferred as
+* `{thisModelSnakeName}_id` (e.g. `user_id` on the `Profile` table).
+*
+* @example
+* ```ts
+* class User extends Model {
+*   @HasOne("Profile") profile?: Profile;
+*   @HasOne("UserSettings", { foreignKey: "owner_id" }) settings?: UserSettings;
+* }
+* ```
+*/
+const HasOne = makeRelationDecorator("hasOne");
+/**
+* Declares a `hasMany` relation on a model field.
+*
+* Same shape as `@HasOne` but loads an array. The foreign key lives on
+* the related model. Defaults: FK column inferred as
+* `{thisModelSnakeName}_id`.
+*
+* @example
+* ```ts
+* class User extends Model {
+*   @HasMany("Post") posts?: Post[];
+*   @HasMany("Comment", { foreignKey: "author_id" }) comments?: Comment[];
+* }
+* ```
+*/
+const HasMany = makeRelationDecorator("hasMany");
+/**
+* Declares a `belongsToMany` relation on a model field.
+*
+* Defaults: pivot table inferred as the alphabetical snake-case join of
+* the two model names (`Post` + `Tag` → `post_tag`); pivot columns
+* inferred as `{modelSnakeName}_id` on each side.
+*
+* @example
+* ```ts
+* class Post extends Model {
+*   @BelongsToMany("Tag") tags?: Tag[];
+*   @BelongsToMany("User", { pivot: "post_collaborators" }) collaborators?: User[];
+* }
+* ```
+*/
+const BelongsToMany = makeRelationDecorator("belongsToMany");
+
+//#endregion
+export { BelongsTo, BelongsToMany, HasMany, HasOne, RELATION_METADATA_KEY };
+//# sourceMappingURL=relation-decorators.mjs.map

package/esm/model/relation-decorators.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"relation-decorators.mjs","names":[],"sources":["../../../../../../@warlock.js/cascade/src/model/relation-decorators.ts"],"sourcesContent":["/**\n * @fileoverview TC39 Stage 3 class field decorators for declaring model\n * relations directly on the field.\n *\n * Replaces the legacy `static relations = { name: hasMany(\"Foo\") }` shape\n * with co-located, single-declaration syntax:\n *\n * @example\n * ```ts\n * @RegisterModel()\n * class User extends Model {\n *   @BelongsTo(\"Organization\") organization?: Organization;\n *   @HasOne(\"Profile\") profile?: Profile;\n *   @HasMany(\"Post\") posts?: Post[];\n *   @BelongsToMany(\"Group\") groups?: Group[];\n * }\n * ```\n *\n * Foreign keys, local keys, and pivot tables are inferred from model names\n * via the convention helpers in `relations/key-conventions.ts`. Inline\n * options on the decorator override the conventions per relation.\n *\n * @module @warlock.js/cascade/model/relation-decorators\n */\n\nimport { capitalize, type Lazy } from \"@mongez/reinforcements\";\nimport type {\n  BelongsToManyOptions,\n  BelongsToOptions,\n  HasManyOptions,\n  HasOneOptions,\n  RelationDefinition,\n  RelationType,\n} from \"../relations/types\";\nimport type { ChildModel, Model } from \"./model\";\n\n// ============================================================================\n// INTERNAL — REGISTRATION\n// ============================================================================\n\n/**\n * Type-erased options bag — each relation type accepts a different subset\n * but the registration helper treats them uniformly.\n */\ntype AnyRelationOptions =\n  | (BelongsToOptions & { localKey?: string; pivot?: string })\n  | HasManyOptions\n  | HasOneOptions\n  | BelongsToManyOptions;\n\n/**\n * Map raw decorator inputs into a `RelationDefinition` of the canonical\n * shape consumed by the relation loader, pivot operations, etc.\n *\n * Note: foreign-key / pivot-table defaults are NOT resolved here — they\n * live on each runtime resolution path (`RelationLoader`, `PivotOperations`,\n * the postgres query builder) and read from `key-conventions.ts`. Recording\n * `undefined` here keeps a single source of truth for the inference logic.\n */\nfunction buildRelationDefinition(\n  type: RelationType,\n  model: string | ChildModel<Model> | Lazy<unknown>,\n  options?: AnyRelationOptions,\n): RelationDefinition {\n  // BelongsTo stores its \"owner key\" in the shared `localKey` slot. Other\n  // types just pass `localKey` through.\n  const localKey =\n    type === \"belongsTo\"\n      ? (options as BelongsToOptions)?.ownerKey\n      : (options as HasManyOptions)?.localKey;\n\n  return {\n    type,\n    model,\n    foreignKey: options?.foreignKey,\n    localKey,\n    pivot: (options as BelongsToManyOptions)?.pivot,\n    pivotLocalKey: (options as BelongsToManyOptions)?.pivotLocalKey,\n    pivotForeignKey: (options as BelongsToManyOptions)?.pivotForeignKey,\n    select: options?.select,\n  };\n}\n\n/**\n * Stash a relation definition into the class-level decorator metadata bag.\n *\n * **Why metadata, not addInitializer?** `context.addInitializer` on a\n * *field* decorator fires per-instance, not per-class — so it only runs\n * when `new ModelClass(...)` is called. Class-level operations like\n * `Organization.withCount(\"users\")` never construct instances, which means\n * an initializer-based registration would leave `Organization.relations`\n * permanently empty.\n *\n * TC39 stage 3 `context.metadata` is the right tool: a shared object across\n * every decorator on the same class declaration. Field decorators write\n * into it during decoration; `@RegisterModel` (a class decorator that runs\n * AFTER all field decorators) reads it back and copies the relations onto\n * the class's static `relations` map.\n *\n * The metadata object also prototype-chains to the parent class's metadata\n * (per spec), so a subclass naturally inherits its parent's relations.\n */\nfunction stashRelationInMetadata(\n  metadata: DecoratorMetadataObject,\n  relationName: string,\n  definition: RelationDefinition,\n): void {\n  let relations = metadata[RELATION_METADATA_KEY] as Record<string, RelationDefinition> | undefined;\n\n  // Promote inherited relations to an own property before mutating, so\n  // writing on the subclass doesn't leak into the parent's bag.\n  if (!Object.prototype.hasOwnProperty.call(metadata, RELATION_METADATA_KEY)) {\n    relations = { ...(relations ?? {}) };\n    metadata[RELATION_METADATA_KEY] = relations;\n  }\n\n  relations![relationName] = definition;\n}\n\n/**\n * Key used to stash relation definitions on the decorator metadata object.\n * Exported so `@RegisterModel` (in `register-model.ts`) can read it back.\n */\nexport const RELATION_METADATA_KEY = Symbol.for(\"@warlock.js/cascade:relations\");\n\n// ============================================================================\n// INTERNAL — DECORATOR FACTORY\n// ============================================================================\n\n/**\n * Builds a TC39 stage 3 class-field decorator that registers a relation\n * of the given `type`. Each public decorator (`@BelongsTo`, `@HasMany`,\n * etc.) is a thin specialisation of this factory.\n */\nfunction makeRelationDecorator<Options extends AnyRelationOptions | undefined>(type: RelationType) {\n  return function (\n    modelRelation: string | ChildModel<Model> | Lazy<unknown>,\n    options?: Options | string,\n  ) {\n    return function <This>(_value: undefined, context: ClassFieldDecoratorContext<This>): void {\n      if (context.kind !== \"field\") {\n        throw new Error(\n          `@${capitalize(type)} can only be applied to class fields — got \"${context.kind}\".`,\n        );\n      }\n\n      const relationName = String(context.name);\n      const resolvedOptions = resolveOptions(options);\n      const definition = buildRelationDefinition(type, modelRelation, resolvedOptions);\n\n      stashRelationInMetadata(context.metadata, relationName, definition);\n    };\n  };\n}\n\n/**\n * Normalise the decorator's second argument.\n *\n * Accepts three shapes:\n * - Omitted (`undefined`): all defaults come from the runtime convention\n *   helpers (`inferBelongsToForeignKey`, `inferHasForeignKey`, …) per\n *   relation type. We must NOT pre-fill `foreignKey` here — the right\n *   convention depends on the relation type AND the *owner* model name,\n *   which the decorator doesn't know.\n * - String: shorthand for `{ foreignKey: <string> }`, matching the legacy\n *   `belongsTo(\"Foo\", \"fk_col\")` helper.\n * - Object: passed through as-is.\n */\nfunction resolveOptions(\n  options: AnyRelationOptions | string | undefined,\n): AnyRelationOptions | undefined {\n  if (typeof options === \"string\") {\n    return { foreignKey: options } as AnyRelationOptions;\n  }\n\n  return options;\n}\n\n// ============================================================================\n// PUBLIC — RELATION DECORATORS\n// ============================================================================\n\n/**\n * Declares a `belongsTo` relation on a model field.\n *\n * The foreign key lives on **this** model and points at the related\n * model's primary key. Defaults: FK column inferred as `{relationName}_id`\n * (snake-cased) — e.g. `organization_id` for `organization?: Organization`.\n *\n * @param model - The related model, in any of three forms:\n *   - `\"User\"` — registered name (requires `@RegisterModel()` on target).\n *   - `User` — direct class reference (cleanest for non-cycle relations).\n *   - `lazy(() => User)` — typed but cycle-safe (use when the two model\n *     files import each other).\n * @param options - Inline overrides for FK / owner key / column select\n *\n * @example\n * ```ts\n * import { lazy } from \"@mongez/reinforcements\";\n *\n * class User extends Model {\n *   @BelongsTo(Organization) public organization?: Organization;\n *   @BelongsTo(\"User\", { foreignKey: \"manager_id\" }) public manager?: User;\n *   @BelongsTo(lazy(() => Team)) public team?: Team; // cycle case\n * }\n * ```\n */\nexport const BelongsTo = makeRelationDecorator<BelongsToOptions>(\"belongsTo\");\n\n/**\n * Declares a `hasOne` relation on a model field.\n *\n * The foreign key lives on the **related** model and points back at this\n * model's primary key. Defaults: FK column inferred as\n * `{thisModelSnakeName}_id` (e.g. `user_id` on the `Profile` table).\n *\n * @example\n * ```ts\n * class User extends Model {\n *   @HasOne(\"Profile\") profile?: Profile;\n *   @HasOne(\"UserSettings\", { foreignKey: \"owner_id\" }) settings?: UserSettings;\n * }\n * ```\n */\nexport const HasOne = makeRelationDecorator<HasOneOptions>(\"hasOne\");\n\n/**\n * Declares a `hasMany` relation on a model field.\n *\n * Same shape as `@HasOne` but loads an array. The foreign key lives on\n * the related model. Defaults: FK column inferred as\n * `{thisModelSnakeName}_id`.\n *\n * @example\n * ```ts\n * class User extends Model {\n *   @HasMany(\"Post\") posts?: Post[];\n *   @HasMany(\"Comment\", { foreignKey: \"author_id\" }) comments?: Comment[];\n * }\n * ```\n */\nexport const HasMany = makeRelationDecorator<HasManyOptions>(\"hasMany\");\n\n/**\n * Declares a `belongsToMany` relation on a model field.\n *\n * Defaults: pivot table inferred as the alphabetical snake-case join of\n * the two model names (`Post` + `Tag` → `post_tag`); pivot columns\n * inferred as `{modelSnakeName}_id` on each side.\n *\n * @example\n * ```ts\n * class Post extends Model {\n *   @BelongsToMany(\"Tag\") tags?: Tag[];\n *   @BelongsToMany(\"User\", { pivot: \"post_collaborators\" }) collaborators?: User[];\n * }\n * ```\n */\nexport const BelongsToMany = makeRelationDecorator<BelongsToManyOptions>(\"belongsToMany\");\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2DA,SAAS,wBACP,MACA,OACA,SACoB;CAGpB,MAAM,WACJ,SAAS,cACJ,SAA8B,WAC9B,SAA4B;CAEnC,OAAO;EACL;EACA;EACA,YAAY,SAAS;EACrB;EACA,OAAQ,SAAkC;EAC1C,eAAgB,SAAkC;EAClD,iBAAkB,SAAkC;EACpD,QAAQ,SAAS;CACnB;AACF;;;;;;;;;;;;;;;;;;;;AAqBA,SAAS,wBACP,UACA,cACA,YACM;CACN,IAAI,YAAY,SAAS;CAIzB,IAAI,CAAC,OAAO,UAAU,eAAe,KAAK,UAAU,qBAAqB,GAAG;EAC1E,YAAY,EAAE,GAAI,aAAa,CAAC,EAAG;EACnC,SAAS,yBAAyB;CACpC;CAEA,UAAW,gBAAgB;AAC7B;;;;;AAMA,MAAa,wBAAwB,OAAO,IAAI,+BAA+B;;;;;;AAW/E,SAAS,sBAAsE,MAAoB;CACjG,OAAO,SACL,eACA,SACA;EACA,OAAO,SAAgB,QAAmB,SAAiD;GACzF,IAAI,QAAQ,SAAS,SACnB,MAAM,IAAI,MACR,IAAI,WAAW,IAAI,EAAE,8CAA8C,QAAQ,KAAK,GAClF;GAGF,MAAM,eAAe,OAAO,QAAQ,IAAI;GAExC,MAAM,aAAa,wBAAwB,MAAM,eADzB,eAAe,OACuC,CAAC;GAE/E,wBAAwB,QAAQ,UAAU,cAAc,UAAU;EACpE;CACF;AACF;;;;;;;;;;;;;;AAeA,SAAS,eACP,SACgC;CAChC,IAAI,OAAO,YAAY,UACrB,OAAO,EAAE,YAAY,QAAQ;CAG/B,OAAO;AACT;;;;;;;;;;;;;;;;;;;;;;;;;;AA+BA,MAAa,YAAY,sBAAwC,WAAW;;;;;;;;;;;;;;;;AAiB5E,MAAa,SAAS,sBAAqC,QAAQ;;;;;;;;;;;;;;;;AAiBnE,MAAa,UAAU,sBAAsC,SAAS;;;;;;;;;;;;;;;;AAiBtE,MAAa,gBAAgB,sBAA4C,eAAe"}

package/esm/operations/database.d.mts

@@ -0,0 +1,46 @@
+//#region ../../@warlock.js/cascade/src/operations/database.d.ts
+/**
+ * Selects which data source the operation runs against. Shared between every
+ * function in this module — kept internal because it carries no semantic
+ * beyond "look up by registry name".
+ */
+type DataSourceSelector = {
+  /** Data source name from the registry. Omit to use the default source. */readonly connection?: string;
+};
+/**
+ * Result of {@link createDatabase}.
+ */
+type CreateDatabaseResult = {
+  /** True if a new database was created; false if it already existed. */readonly created: boolean; /** The database name that was passed to the operation. */
+  readonly name: string;
+};
+/**
+ * Result of {@link dropAllTables}.
+ */
+type DropAllTablesResult = {
+  /** Names of tables that were dropped, in the order returned by the driver. */readonly tables: string[]; /** Count of dropped tables (equal to `tables.length`). */
+  readonly dropped: number;
+};
+/**
+ * Create a database on the configured data source. Returns `created: false`
+ * when the database already exists — drivers are responsible for the
+ * idempotency check.
+ *
+ * @example
+ * await createDatabase("analytics");
+ * await createDatabase("analytics", { connection: "warehouse" });
+ */
+declare function createDatabase(name: string, options?: DataSourceSelector): Promise<CreateDatabaseResult>;
+/**
+ * Drop every table on the configured data source. Lists tables first so the
+ * caller receives the names that were affected — useful for printing,
+ * confirmation prompts, or audit logging at the call site.
+ *
+ * @example
+ * const { tables, dropped } = await dropAllTables();
+ * console.log(`Dropped ${dropped} tables: ${tables.join(", ")}`);
+ */
+declare function dropAllTables(options?: DataSourceSelector): Promise<DropAllTablesResult>;
+//#endregion
+export { CreateDatabaseResult, DropAllTablesResult, createDatabase, dropAllTables };
+//# sourceMappingURL=database.d.mts.map

package/esm/operations/database.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"database.d.mts","names":[],"sources":["../../../../../../@warlock.js/cascade/src/operations/database.ts"],"mappings":";;;;;;KAOK,kBAAA;EAQO,mFAND,UAAU;AAAA;;AAUN;AAMf;KAVY,oBAAA;kFAED,OAAA,WAYO;EAAA,SAVP,IAAI;AAAA;;;;KAMH,mBAAA;EAmBF,uFAjBC,MAAA,YAeT;EAAA,SAbS,OAAO;AAAA;;;;AAea;AAgB/B;;;;;iBAnBsB,cAAA,CACpB,IAAA,UACA,OAAA,GAAS,kBAAA,GACR,OAAA,CAAQ,oBAAA;;;;;;;;AAkBmB;;iBAFR,aAAA,CACpB,OAAA,GAAS,kBAAA,GACR,OAAA,CAAQ,mBAAA"}

package/esm/operations/database.mjs

@@ -0,0 +1,40 @@
+import { dataSourceRegistry } from "../data-source/data-source-registry.mjs";
+
+//#region ../../@warlock.js/cascade/src/operations/database.ts
+/**
+* Create a database on the configured data source. Returns `created: false`
+* when the database already exists — drivers are responsible for the
+* idempotency check.
+*
+* @example
+* await createDatabase("analytics");
+* await createDatabase("analytics", { connection: "warehouse" });
+*/
+async function createDatabase(name, options = {}) {
+	return {
+		created: await dataSourceRegistry.get(options.connection).driver.createDatabase(name),
+		name
+	};
+}
+/**
+* Drop every table on the configured data source. Lists tables first so the
+* caller receives the names that were affected — useful for printing,
+* confirmation prompts, or audit logging at the call site.
+*
+* @example
+* const { tables, dropped } = await dropAllTables();
+* console.log(`Dropped ${dropped} tables: ${tables.join(", ")}`);
+*/
+async function dropAllTables(options = {}) {
+	const driver = dataSourceRegistry.get(options.connection).driver;
+	const tables = await driver.blueprint.listTables();
+	await driver.dropAllTables();
+	return {
+		tables,
+		dropped: tables.length
+	};
+}
+
+//#endregion
+export { createDatabase, dropAllTables };
+//# sourceMappingURL=database.mjs.map

package/esm/operations/database.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"database.mjs","names":[],"sources":["../../../../../../@warlock.js/cascade/src/operations/database.ts"],"sourcesContent":["import { dataSourceRegistry } from \"../data-source/data-source-registry\";\n\n/**\n * Selects which data source the operation runs against. Shared between every\n * function in this module — kept internal because it carries no semantic\n * beyond \"look up by registry name\".\n */\ntype DataSourceSelector = {\n  /** Data source name from the registry. Omit to use the default source. */\n  readonly connection?: string;\n};\n\n/**\n * Result of {@link createDatabase}.\n */\nexport type CreateDatabaseResult = {\n  /** True if a new database was created; false if it already existed. */\n  readonly created: boolean;\n  /** The database name that was passed to the operation. */\n  readonly name: string;\n};\n\n/**\n * Result of {@link dropAllTables}.\n */\nexport type DropAllTablesResult = {\n  /** Names of tables that were dropped, in the order returned by the driver. */\n  readonly tables: string[];\n  /** Count of dropped tables (equal to `tables.length`). */\n  readonly dropped: number;\n};\n\n/**\n * Create a database on the configured data source. Returns `created: false`\n * when the database already exists — drivers are responsible for the\n * idempotency check.\n *\n * @example\n * await createDatabase(\"analytics\");\n * await createDatabase(\"analytics\", { connection: \"warehouse\" });\n */\nexport async function createDatabase(\n  name: string,\n  options: DataSourceSelector = {},\n): Promise<CreateDatabaseResult> {\n  const dataSource = dataSourceRegistry.get(options.connection);\n  const created = await dataSource.driver.createDatabase(name);\n\n  return { created, name };\n}\n\n/**\n * Drop every table on the configured data source. Lists tables first so the\n * caller receives the names that were affected — useful for printing,\n * confirmation prompts, or audit logging at the call site.\n *\n * @example\n * const { tables, dropped } = await dropAllTables();\n * console.log(`Dropped ${dropped} tables: ${tables.join(\", \")}`);\n */\nexport async function dropAllTables(\n  options: DataSourceSelector = {},\n): Promise<DropAllTablesResult> {\n  const dataSource = dataSourceRegistry.get(options.connection);\n  const driver = dataSource.driver;\n\n  const tables = await driver.blueprint.listTables();\n  await driver.dropAllTables();\n\n  return { tables, dropped: tables.length };\n}\n"],"mappings":";;;;;;;;;;;;AAyCA,eAAsB,eACpB,MACA,UAA8B,CAAC,GACA;CAI/B,OAAO;EAAE,eAHU,mBAAmB,IAAI,QAAQ,UACnB,EAAE,OAAO,eAAe,IAAI;EAEzC;CAAK;AACzB;;;;;;;;;;AAWA,eAAsB,cACpB,UAA8B,CAAC,GACD;CAE9B,MAAM,SADa,mBAAmB,IAAI,QAAQ,UAC1B,EAAE;CAE1B,MAAM,SAAS,MAAM,OAAO,UAAU,WAAW;CACjD,MAAM,OAAO,cAAc;CAE3B,OAAO;EAAE;EAAQ,SAAS,OAAO;CAAO;AAC1C"}

package/esm/operations/index.d.mts

@@ -0,0 +1,2 @@
+import { CreateDatabaseResult, DropAllTablesResult, createDatabase, dropAllTables } from "./database.mjs";
+import { ExportMigrationsSQLOptions, RollbackMigrationsOptions, exportMigrationsSQL, freshMigrate, listExecutedMigrations, rollbackMigrations, runMigrations } from "./migrations.mjs";

package/esm/operations/index.mjs

@@ -0,0 +1,4 @@
+import { createDatabase, dropAllTables } from "./database.mjs";
+import { exportMigrationsSQL, freshMigrate, listExecutedMigrations, rollbackMigrations, runMigrations } from "./migrations.mjs";
+
+export {  };

package/esm/operations/migrations.d.mts

@@ -0,0 +1,71 @@
+import { MigrationRecord, MigrationResult } from "../migration/types.mjs";
+
+//#region ../../@warlock.js/cascade/src/operations/migrations.d.ts
+/**
+ * Options for exporting migrations as SQL files.
+ */
+type ExportMigrationsSQLOptions = {
+  /** Export only pending migrations. Default: false (exports all registered). */readonly pendingOnly?: boolean; /** Strip generated block comments and blank lines from the output. */
+  readonly compact?: boolean;
+};
+/**
+ * Options for rolling back migrations.
+ */
+type RollbackMigrationsOptions = {
+  /** Roll back every executed migration. Overrides `batches` when true. */readonly all?: boolean; /** Number of batches to roll back when `all` is not set. Default: 1. */
+  readonly batches?: number;
+};
+/**
+ * Run every pending migration registered on the migration runner.
+ *
+ * Caller is responsible for registering migration classes first via
+ * `migrationRunner.register()` / `migrationRunner.registerMany()`. Returns one
+ * result entry per executed migration.
+ *
+ * @example
+ * migrationRunner.registerMany([CreateUsersTable, AddEmailIndex]);
+ * const results = await runMigrations();
+ */
+declare function runMigrations(): Promise<MigrationResult[]>;
+/**
+ * Roll back executed migrations. By default rolls back the most recent batch;
+ * pass `all: true` to undo every executed migration, or `batches: N` to undo
+ * the last N batches.
+ *
+ * @example
+ * await rollbackMigrations();              // last batch
+ * await rollbackMigrations({ batches: 3 }); // last three batches
+ * await rollbackMigrations({ all: true });  // everything
+ */
+declare function rollbackMigrations(options?: RollbackMigrationsOptions): Promise<MigrationResult[]>;
+/**
+ * Roll back every executed migration, then run every registered migration.
+ * Equivalent to `rollbackMigrations({ all: true })` followed by
+ * `runMigrations()`.
+ *
+ * @example
+ * await freshMigrate();
+ */
+declare function freshMigrate(): Promise<MigrationResult[]>;
+/**
+ * Export registered migrations as phase-ordered `.up.sql` and `.down.sql`
+ * files under `<cwd>/database/sql/`.
+ *
+ * @example
+ * await exportMigrationsSQL();
+ * await exportMigrationsSQL({ pendingOnly: true, compact: true });
+ */
+declare function exportMigrationsSQL(options?: ExportMigrationsSQLOptions): Promise<void>;
+/**
+ * Return the migration records persisted in the migrations table — one entry
+ * per migration that has ever been executed against the configured data
+ * source.
+ *
+ * @example
+ * const executed = await listExecutedMigrations();
+ * console.log(executed.map((record) => record.name));
+ */
+declare function listExecutedMigrations(): Promise<MigrationRecord[]>;
+//#endregion
+export { ExportMigrationsSQLOptions, RollbackMigrationsOptions, exportMigrationsSQL, freshMigrate, listExecutedMigrations, rollbackMigrations, runMigrations };
+//# sourceMappingURL=migrations.d.mts.map

package/esm/operations/migrations.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrations.d.mts","names":[],"sources":["../../../../../../@warlock.js/cascade/src/operations/migrations.ts"],"mappings":";;;;;AAMA;KAAY,0BAAA;0FAED,WAAA,YAEO;EAAA,SAAP,OAAO;AAAA;;;AAUA;KAJN,yBAAA;EAkBuB,kFAhBxB,GAAA,YAgB4B;EAAA,SAd5B,OAAO;AAAA;;;;;;;;;;;;iBAcI,aAAA,CAAA,GAAiB,OAAO,CAAC,eAAA;AAgBrB;AAkB1B;;;;AAA6D;AAY7D;;;;AA9B0B,iBAFJ,kBAAA,CACpB,OAAA,GAAS,yBAAA,GACR,OAAA,CAAQ,eAAA;;;;AAgCD;AAaV;;;;iBA3BsB,YAAA,CAAA,GAAgB,OAAO,CAAC,eAAA;;;;;;;;;iBAYxB,mBAAA,CACpB,OAAA,GAAS,0BAAA,GACR,OAAO;;;;;;;;;;iBAaY,sBAAA,CAAA,GAA0B,OAAO,CAAC,eAAA"}

package/esm/operations/migrations.mjs

@@ -0,0 +1,70 @@
+import { migrationRunner } from "../migration/migration-runner.mjs";
+
+//#region ../../@warlock.js/cascade/src/operations/migrations.ts
+/**
+* Run every pending migration registered on the migration runner.
+*
+* Caller is responsible for registering migration classes first via
+* `migrationRunner.register()` / `migrationRunner.registerMany()`. Returns one
+* result entry per executed migration.
+*
+* @example
+* migrationRunner.registerMany([CreateUsersTable, AddEmailIndex]);
+* const results = await runMigrations();
+*/
+async function runMigrations() {
+	return migrationRunner.runAll();
+}
+/**
+* Roll back executed migrations. By default rolls back the most recent batch;
+* pass `all: true` to undo every executed migration, or `batches: N` to undo
+* the last N batches.
+*
+* @example
+* await rollbackMigrations();              // last batch
+* await rollbackMigrations({ batches: 3 }); // last three batches
+* await rollbackMigrations({ all: true });  // everything
+*/
+async function rollbackMigrations(options = {}) {
+	if (options.all) return migrationRunner.rollbackAll();
+	const batches = options.batches ?? 1;
+	return migrationRunner.rollbackBatches(batches);
+}
+/**
+* Roll back every executed migration, then run every registered migration.
+* Equivalent to `rollbackMigrations({ all: true })` followed by
+* `runMigrations()`.
+*
+* @example
+* await freshMigrate();
+*/
+async function freshMigrate() {
+	return migrationRunner.fresh();
+}
+/**
+* Export registered migrations as phase-ordered `.up.sql` and `.down.sql`
+* files under `<cwd>/database/sql/`.
+*
+* @example
+* await exportMigrationsSQL();
+* await exportMigrationsSQL({ pendingOnly: true, compact: true });
+*/
+async function exportMigrationsSQL(options = {}) {
+	return migrationRunner.exportSQL(options);
+}
+/**
+* Return the migration records persisted in the migrations table — one entry
+* per migration that has ever been executed against the configured data
+* source.
+*
+* @example
+* const executed = await listExecutedMigrations();
+* console.log(executed.map((record) => record.name));
+*/
+async function listExecutedMigrations() {
+	return migrationRunner.getExecutedMigrations();
+}
+
+//#endregion
+export { exportMigrationsSQL, freshMigrate, listExecutedMigrations, rollbackMigrations, runMigrations };
+//# sourceMappingURL=migrations.mjs.map

package/esm/operations/migrations.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrations.mjs","names":[],"sources":["../../../../../../@warlock.js/cascade/src/operations/migrations.ts"],"sourcesContent":["import { migrationRunner } from \"../migration/migration-runner\";\nimport type { MigrationRecord, MigrationResult } from \"../migration/types\";\n\n/**\n * Options for exporting migrations as SQL files.\n */\nexport type ExportMigrationsSQLOptions = {\n  /** Export only pending migrations. Default: false (exports all registered). */\n  readonly pendingOnly?: boolean;\n  /** Strip generated block comments and blank lines from the output. */\n  readonly compact?: boolean;\n};\n\n/**\n * Options for rolling back migrations.\n */\nexport type RollbackMigrationsOptions = {\n  /** Roll back every executed migration. Overrides `batches` when true. */\n  readonly all?: boolean;\n  /** Number of batches to roll back when `all` is not set. Default: 1. */\n  readonly batches?: number;\n};\n\n/**\n * Run every pending migration registered on the migration runner.\n *\n * Caller is responsible for registering migration classes first via\n * `migrationRunner.register()` / `migrationRunner.registerMany()`. Returns one\n * result entry per executed migration.\n *\n * @example\n * migrationRunner.registerMany([CreateUsersTable, AddEmailIndex]);\n * const results = await runMigrations();\n */\nexport async function runMigrations(): Promise<MigrationResult[]> {\n  return migrationRunner.runAll();\n}\n\n/**\n * Roll back executed migrations. By default rolls back the most recent batch;\n * pass `all: true` to undo every executed migration, or `batches: N` to undo\n * the last N batches.\n *\n * @example\n * await rollbackMigrations();              // last batch\n * await rollbackMigrations({ batches: 3 }); // last three batches\n * await rollbackMigrations({ all: true });  // everything\n */\nexport async function rollbackMigrations(\n  options: RollbackMigrationsOptions = {},\n): Promise<MigrationResult[]> {\n  if (options.all) {\n    return migrationRunner.rollbackAll();\n  }\n\n  const batches = options.batches ?? 1;\n\n  return migrationRunner.rollbackBatches(batches);\n}\n\n/**\n * Roll back every executed migration, then run every registered migration.\n * Equivalent to `rollbackMigrations({ all: true })` followed by\n * `runMigrations()`.\n *\n * @example\n * await freshMigrate();\n */\nexport async function freshMigrate(): Promise<MigrationResult[]> {\n  return migrationRunner.fresh();\n}\n\n/**\n * Export registered migrations as phase-ordered `.up.sql` and `.down.sql`\n * files under `<cwd>/database/sql/`.\n *\n * @example\n * await exportMigrationsSQL();\n * await exportMigrationsSQL({ pendingOnly: true, compact: true });\n */\nexport async function exportMigrationsSQL(\n  options: ExportMigrationsSQLOptions = {},\n): Promise<void> {\n  return migrationRunner.exportSQL(options);\n}\n\n/**\n * Return the migration records persisted in the migrations table — one entry\n * per migration that has ever been executed against the configured data\n * source.\n *\n * @example\n * const executed = await listExecutedMigrations();\n * console.log(executed.map((record) => record.name));\n */\nexport async function listExecutedMigrations(): Promise<MigrationRecord[]> {\n  return migrationRunner.getExecutedMigrations();\n}\n"],"mappings":";;;;;;;;;;;;;;AAkCA,eAAsB,gBAA4C;CAChE,OAAO,gBAAgB,OAAO;AAChC;;;;;;;;;;;AAYA,eAAsB,mBACpB,UAAqC,CAAC,GACV;CAC5B,IAAI,QAAQ,KACV,OAAO,gBAAgB,YAAY;CAGrC,MAAM,UAAU,QAAQ,WAAW;CAEnC,OAAO,gBAAgB,gBAAgB,OAAO;AAChD;;;;;;;;;AAUA,eAAsB,eAA2C;CAC/D,OAAO,gBAAgB,MAAM;AAC/B;;;;;;;;;AAUA,eAAsB,oBACpB,UAAsC,CAAC,GACxB;CACf,OAAO,gBAAgB,UAAU,OAAO;AAC1C;;;;;;;;;;AAWA,eAAsB,yBAAqD;CACzE,OAAO,gBAAgB,sBAAsB;AAC/C"}