@warlock.js/cascade 4.0.174 → 4.1.1

package/esm/sync/types.d.mts

@@ -0,0 +1,215 @@
+import { ChildModel } from "../model/model.types.mjs";
+import { Model } from "../model/model.mjs";
+
+//#region ../../@warlock.js/cascade/src/sync/types.d.ts
+/**
+ * Context information for a sync operation.
+ * Tracks the source, target, chain, and results of a sync operation.
+ */
+type SyncContext = {
+  /** Source model name (e.g., "Category") */sourceModel: string; /** Source model primary key value */
+  sourceId: string | number; /** Current depth in the sync chain (1, 2, 3...) */
+  currentDepth: number; /** Chain of model names in the sync path (e.g., ["Category", "Product"]) */
+  syncChain: string[]; /** Target model name being synced to */
+  targetModel: string; /** Filter to identify documents to update in target */
+  filter: Record<string, unknown>; /** Update operations to apply to matched documents */
+  update: Record<string, unknown>; /** Number of documents affected by this sync operation */
+  affectedCount: number; /** Timestamp when the sync operation was executed */
+  timestamp: Date;
+};
+/**
+ * Result of a sync operation.
+ * Contains success status, counts, and error details.
+ */
+type SyncResult = {
+  /** Whether the overall sync operation succeeded */success: boolean; /** Total number of sync instructions attempted */
+  attempted: number; /** Number of sync instructions that succeeded */
+  succeeded: number; /** Number of sync instructions that failed */
+  failed: number; /** Detailed error information for failed operations */
+  errors: Array<{
+    instruction: SyncInstruction;
+    error: Error;
+  }>; /** Maximum depth reached in the sync chain */
+  depthReached: number; /** All sync contexts created during the operation */
+  contexts: SyncContext[];
+};
+/**
+ * A single sync instruction to be executed.
+ * Contains all information needed to perform a sync update.
+ */
+type SyncInstruction = {
+  /** Target table/collection name */targetTable: string; /** Target model name */
+  targetModel: string; /** Filter to identify documents to update */
+  filter: Record<string, unknown>; /** Update operations to apply */
+  update: Record<string, unknown>; /** Current depth in the sync chain */
+  depth: number; /** Chain of model names leading to this instruction */
+  chain: string[]; /** Source model name */
+  sourceModel: string; /** Source model ID */
+  sourceId: string | number; /** Whether this is an array update (requires positional operator) */
+  isArrayUpdate?: boolean; /** Array field path for positional updates */
+  arrayField?: string; /** Identifier field for array matching */
+  identifierField?: string; /** Identifier value for array matching */
+  identifierValue?: string | number;
+};
+/**
+ * Configuration for a single sync relationship.
+ */
+type SyncConfig = {
+  /** Target field path in the target model (e.g., "category" or "products") */targetField: string; /** Whether this is a many relationship (array of embedded documents) */
+  isMany: boolean; /** Method name to call on source model to get embedded data */
+  embedKey: string; /** Field name to use as identifier in array matching (for isMany) */
+  identifierField: string; /** Maximum sync depth allowed from this relationship */
+  maxSyncDepth: number; /** Whether to prevent circular sync chains */
+  preventCircularSync: boolean; /** Fields to watch for changes (empty = all fields) */
+  watchFields: string[]; /** Whether to unset the field when source is deleted */
+  unsetOnDelete: boolean; /** Target model class (for chaining) */
+  targetModelClass: ChildModel<Model>;
+};
+/**
+ * Options for building sync instructions.
+ */
+type SyncInstructionOptions = {
+  /** Current depth in the sync chain */currentDepth: number; /** Chain of model names leading to this point */
+  syncChain: string[]; /** Maximum allowed depth for this sync operation */
+  maxDepth: number; /** Whether to prevent circular references */
+  preventCircular: boolean;
+};
+/**
+ * Standard embed proeprties names.
+ */
+type EmbedKey = "embedData" | "embedParent" | "embedMinimal";
+/**
+ * Event payload for sync events.
+ */
+type SyncEventPayload = {
+  /** Source model name */sourceModel: string; /** Source model ID */
+  sourceId: string | number; /** Target model name */
+  targetModel: string; /** Filter used to identify target documents */
+  filter: Record<string, unknown>; /** Update operations applied */
+  update: Record<string, unknown>; /** Number of documents affected */
+  affectedCount: number; /** Current depth in sync chain */
+  depth: number; /** Sync chain path */
+  chain: string[];
+};
+/**
+ * Configuration for a model sync operation.
+ *
+ * Holds all settings for how a source model syncs to a target model.
+ */
+type ModelSyncConfig = {
+  /** Source model class that triggers sync on changes */readonly sourceModel: ChildModel<Model>; /** Target model class that receives synced data */
+  readonly targetModel: ChildModel<Model>; /** Field path in target model where data is embedded */
+  readonly targetField: string; /** Whether this syncs to an array field (true) or single field (false) */
+  readonly isMany: boolean; /** Method name on source model to get embedded data */
+  embedKey: string | string[]; /** Field name used as identifier when syncing to arrays */
+  identifierField: string; /** Maximum depth for chained sync operations */
+  maxSyncDepth: number; /** Fields to watch - sync only triggers when these change (empty = all) */
+  watchFields: string[]; /** Whether to unset the target field when source is deleted */
+  unsetOnDelete: boolean; /** Whether to delete target documents when source is deleted */
+  removeOnDelete: boolean;
+};
+/**
+ * Contract for a model sync operation instance.
+ *
+ * Provides fluent configuration methods and lifecycle management.
+ *
+ * @example
+ * ```typescript
+ * Category.sync(Product, "category")
+ *   .embed("embedMinimal")
+ *   .watchFields(["name", "slug"])
+ *   .unsetOnDelete();
+ * ```
+ */
+interface ModelSyncOperationContract {
+  /**
+   * Set the embed method to call on source model.
+   *
+   * @param method - Method name (e.g., "embedData", "embedMinimal") or an array of strings
+   * @returns This operation for chaining
+   */
+  embed(method: string | string[]): this;
+  /**
+   * Set the identifier field for array matching.
+   * Required when syncing to array fields (syncMany).
+   *
+   * @param field - Field name used as identifier (default: "id")
+   * @returns This operation for chaining
+   */
+  identifyBy(field: string): this;
+  /**
+   * Set the maximum sync depth for chained operations.
+   *
+   * @param depth - Maximum depth (default: 3)
+   * @returns This operation for chaining
+   */
+  maxDepth(depth: number): this;
+  /**
+   * Set which fields to watch for changes.
+   * Sync only triggers when these fields change.
+   *
+   * @param fields - Array of field names to watch (empty = all)
+   * @returns This operation for chaining
+   */
+  watchFields(fields: string[]): this;
+  /**
+   * Unset the target field when source is deleted.
+   *
+   * @returns This operation for chaining
+   */
+  unsetOnDelete(): this;
+  /**
+   * Delete target documents when source is deleted.
+   *
+   * @returns This operation for chaining
+   */
+  removeOnDelete(): this;
+  /**
+   * Unsubscribe from all events and cleanup.
+   * Called automatically when using modelSync.register().
+   */
+  unsubscribe(): void;
+}
+/**
+ * Contract for the modelSync facade.
+ *
+ * Provides methods to create and manage sync operations.
+ *
+ * @example
+ * ```typescript
+ * export const cleanup = modelSync.register(() => {
+ *   Category.sync(Product, "category");
+ *   Tag.syncMany(Post, "tags").identifyBy("id");
+ * });
+ * ```
+ */
+interface ModelSyncContract {
+  /**
+   * Create a sync operation for a single embedded document.
+   *
+   * @param source - Source model class that triggers sync
+   * @param target - Target model class that receives data
+   * @param field - Field path in target model
+   * @returns Sync operation for chaining configuration
+   */
+  sync(source: ChildModel<Model>, target: ChildModel<Model>, field: string): ModelSyncOperationContract;
+  /**
+   * Create a sync operation for an array of embedded documents.
+   *
+   * @param source - Source model class that triggers sync
+   * @param target - Target model class that receives data
+   * @param field - Array field path in target model
+   * @returns Sync operation for chaining configuration
+   */
+  syncMany(source: ChildModel<Model>, target: ChildModel<Model>, field: string): ModelSyncOperationContract;
+  /**
+   * Register sync operations with automatic cleanup.
+   *
+   * @param callback - Function that registers sync operations
+   * @returns Cleanup function that unsubscribes all registered operations
+   */
+  register(callback: () => void): () => void;
+}
+//#endregion
+export { EmbedKey, ModelSyncConfig, ModelSyncContract, ModelSyncOperationContract, SyncConfig, SyncContext, SyncEventPayload, SyncInstruction, SyncInstructionOptions, SyncResult };
+//# sourceMappingURL=types.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.mts","names":[],"sources":["../../../../../../@warlock.js/cascade/src/sync/types.ts"],"mappings":";;;;;;;;KAYY,WAAA;EA0BK,2CAxBf,WAAA,UAGA;EAAA,QAAA,mBAMA;EAHA,YAAA,UASA;EANA,SAAA,YASA;EANA,WAAA,UASA;EANA,MAAA,EAAQ,MAAA,mBASG;EANX,MAAA,EAAQ,MAAA,mBAMO;EAHf,aAAA,UAUoB;EAPpB,SAAA,EAAW,IAAA;AAAA;;;;;KAOD,UAAA;EAEV,mDAAA,OAAA,WAMA;EAHA,SAAA,UASA;EANA,SAAA,UAMgB;EAHhB,MAAA,UAG8C;EAA9C,MAAA,EAAQ,KAAA;IAAQ,WAAA,EAAa,eAAA;IAAiB,KAAA,EAAO,KAAA;EAAA,IAMhC;EAHrB,YAAA,UAUU;EAPV,QAAA,EAAU,WAAA;AAAA;;;;;KAOA,eAAA;EAWV,mCATA,WAAA,UAYA;EATA,WAAA,UAeA;EAZA,MAAA,EAAQ,MAAA,mBAkBR;EAfA,MAAA,EAAQ,MAAM,mBAqBd;EAlBA,KAAA,UAqBe;EAlBf,KAAA,YAwBU;EArBV,WAAA;EAGA,QAAA,mBAoBA;EAjBA,aAAA,YAuBA;EApBA,UAAA,WA0BA;EAvBA,eAAA,WA6BA;EA1BA,eAAA;AAAA;;;;KAMU,UAAA;EAgCA,6EA9BV,WAAA;EAGA,MAAA,WA6BA;EA1BA,QAAA,UAgCA;EA7BA,eAAA,UAgCe;EA7Bf,YAAA,UAuDU;EApDV,mBAAA;EAGA,WAAA,YAiDkB;EA9ClB,aAAA,WAmD0B;EAhD1B,gBAAA,EAAkB,UAAU,CAAC,KAAA;AAAA;;;;KAMnB,sBAAA;EAqDF,sCAnDR,YAAA,UAsDQ;EAnDR,SAAA,YAyDA;EAtDA,QAAA,UAyDK;EAtDL,eAAA;AAAA;;;;KA0BU,QAAA;;;;KAKA,gBAAA;EAgEI,wBA9Dd,WAAA,UA8EyC;EA3EzC,QAAA,mBA2EyC;EAxEzC,WAAA,UA+EM;EA5EN,MAAA,EAAQ,MAAA,mBAqFG;EAlFX,MAAA,EAAQ,MAAM,mBA0FL;EAvFT,aAAA,UAgGY;EA7FZ,KAAA,UA2GA;EAxGA,KAAA;AAAA;AA8GW;AAgBb;;;;AAhBa,KAlGD,eAAA;EA6HW,gEA3HZ,WAAA,EAAa,UAAA,CAAW,KAAA,GA6H9B;EAAA,SA1HM,WAAA,EAAa,UAAA,CAAW,KAAA,GAqIvB;EAAA,SAlID,WAAA,UAmIC;EAAA,SAhID,MAAA,WAkIoB;EA/H7B,QAAA,qBA6GA;EA1GA,eAAA,UA2GqB;EAxGrB,YAAA,UAyGU;EAtGV,WAAA,YAsGE;EAnGF,aAAA,WAqGG;EAlGH,cAAA;AAAA;;;;;;;;;;;AAwH6B;;;UAxGd,0BAAA;;;;;;;EAOf,KAAA,CAAM,MAAA;;;;;;;;EASN,UAAA,CAAW,KAAA;;;;;;;EAQX,QAAA,CAAS,KAAA;;;;;;;;EAST,WAAA,CAAY,MAAA;;;;;;EAOZ,aAAA;;;;;;EAOA,cAAA;;;;;EAMA,WAAA;AAAA;;;;;;;;;;;;;;UAgBe,iBAAA;;;;;;;;;EASf,IAAA,CACE,MAAA,EAAQ,UAAA,CAAW,KAAA,GACnB,MAAA,EAAQ,UAAA,CAAW,KAAA,GACnB,KAAA,WACC,0BAAA;;;;;;;;;EAUH,QAAA,CACE,MAAA,EAAQ,UAAA,CAAW,KAAA,GACnB,MAAA,EAAQ,UAAA,CAAW,KAAA,GACnB,KAAA,WACC,0BAAA;;;;;;;EAQH,QAAA,CAAS,QAAA;AAAA"}

package/esm/types.d.mts

@@ -0,0 +1,423 @@
+//#region ../../@warlock.js/cascade/src/types.d.ts
+/**
+ * Strict mode configuration for handling unknown fields during validation.
+ *
+ * Controls how the model behaves when encountering fields not defined in the schema.
+ *
+ * - `"strip"` - Remove unknown fields silently (default, recommended for APIs)
+ * - `"fail"` - Throw validation error on unknown fields (strict validation)
+ * - `"allow"` - Allow unknown fields to pass through (permissive)
+ *
+ * @example
+ * ```typescript
+ * import { Model, type StrictMode } from "@warlock.js/cascade";
+ *
+ * class User extends Model {
+ *   public static strictMode: StrictMode = "fail";
+ * }
+ * ```
+ */
+type StrictMode = "strip" | "fail" | "allow";
+/**
+ * Delete strategy for model destruction.
+ *
+ * Controls how models are deleted from the database:
+ *
+ * - `"trash"` - Moves document to a trash/recycle bin collection, then deletes
+ * - `"permanent"` - Actually deletes the document from the database (hard delete)
+ * - `"soft"` - Sets a `deletedAt` timestamp instead of deleting (soft delete)
+ *
+ * Priority order (highest to lowest):
+ * 1. destroy() method options
+ * 2. Model static property (deleteStrategy)
+ * 3. Data source default configuration
+ *
+ * @example
+ * ```typescript
+ * class User extends Model {
+ *   public static deleteStrategy: DeleteStrategy = "soft";
+ * }
+ *
+ * // Override at call time
+ * await user.destroy({ strategy: "permanent" });
+ * ```
+ */
+type DeleteStrategy = "trash" | "permanent" | "soft";
+/**
+ * Naming convention for database column names.
+ *
+ * Different databases have different naming conventions:
+ * - `"camelCase"` - MongoDB standard (createdAt, updatedAt, deletedAt)
+ * - `"snake_case"` - PostgreSQL/MySQL standard (created_at, updated_at, deleted_at)
+ *
+ * This affects default column names for timestamps and other system columns.
+ *
+ * @example
+ * ```typescript
+ * // PostgreSQL driver defaults
+ * namingConvention: "snake_case"
+ * // Results in: created_at, updated_at, deleted_at
+ *
+ * // MongoDB driver defaults
+ * namingConvention: "camelCase"
+ * // Results in: createdAt, updatedAt, deletedAt
+ * ```
+ */
+type NamingConvention = "camelCase" | "snake_case";
+/**
+ * Unified model default configuration.
+ *
+ * These settings define default behaviors for models. The configuration
+ * follows a 4-tier hierarchy (highest to lowest precedence):
+ *
+ * 1. Model static property (explicit override)
+ * 2. Database config modelDefaults
+ * 3. Driver defaults (SQL vs NoSQL conventions)
+ * 4. Framework defaults (fallback values)
+ *
+ * @example
+ * ```typescript
+ * // PostgreSQL driver provides defaults:
+ * const postgresDefaults: ModelDefaults = {
+ *   namingConvention: "snake_case",
+ *   createdAtColumn: "created_at",
+ *   updatedAtColumn: "updated_at",
+ *   deletedAtColumn: "deleted_at",
+ *   timestamps: true,
+ *   autoGenerateId: false, // SQL handles this
+ * };
+ *
+ * // Override in database config:
+ * {
+ *   modelDefaults: {
+ *     randomIncrement: true,
+ *     initialId: 1000,
+ *     deleteStrategy: "soft",
+ *   }
+ * }
+ *
+ * // Override in specific model:
+ * class User extends Model {
+ *   public static createdAtColumn = "creation_date"; // Highest priority
+ *   public static updatedAtColumn = false; // Disable updatedAt
+ * }
+ * ```
+ */
+type ModelDefaults = {
+  /**
+   * Auto-generate incremental `id` field on insert (NoSQL only).
+   *
+   * When enabled, the ID generator creates a sequential integer ID
+   * separate from the database's native ID (_id for MongoDB).
+   *
+   * **Note:** SQL databases use native AUTO_INCREMENT and don't need this.
+   *
+   * @default true (MongoDB), false (PostgreSQL)
+   */
+  autoGenerateId?: boolean;
+  /**
+   * Initial ID value for the first record.
+   *
+   * @default 1
+   *
+   * @example
+   * ```typescript
+   * initialId: 1000 // Start from 1000
+   * ```
+   */
+  initialId?: number;
+  /**
+   * Randomly generate the initial ID.
+   *
+   * Can be:
+   * - `true`: Generate random ID between 10000-499999
+   * - Function: Custom random ID generator
+   * - `false`: Use `initialId` or default to 1
+   *
+   * @default false
+   *
+   * @example
+   * ```typescript
+   * randomInitialId: true // Random 10000-499999
+   * randomInitialId: () => Math.floor(Math.random() * 1000000)
+   * ```
+   */
+  randomInitialId?: boolean | (() => number);
+  /**
+   * Amount to increment ID by for each new record.
+   *
+   * @default 1
+   *
+   * @example
+   * ```typescript
+   * incrementIdBy: 5 // Increment by 5
+   * ```
+   */
+  incrementIdBy?: number;
+  /**
+   * Randomly generate the increment amount.
+   *
+   * Can be:
+   * - `true`: Generate random increment between 1-10
+   * - Function: Custom random increment generator
+   * - `false`: Use `incrementIdBy` or default to 1
+   *
+   * @default false
+   *
+   * @example
+   * ```typescript
+   * randomIncrement: true // Random 1-10
+   * randomIncrement: () => Math.floor(Math.random() * 100)
+   * ```
+   */
+  randomIncrement?: boolean | (() => number);
+  /**
+   * Enable/disable automatic timestamp management.
+   *
+   * When enabled, createdAt and updatedAt are automatically managed.
+   * When disabled, no timestamps are added.
+   *
+   * @default true
+   */
+  timestamps?: boolean;
+  /**
+   * Column name for creation timestamp.
+   *
+   * Set to `false` to disable createdAt entirely.
+   *
+   * @default "createdAt" (MongoDB), "created_at" (PostgreSQL)
+   *
+   * @example
+   * ```typescript
+   * createdAtColumn: "creation_date"
+   * createdAtColumn: false // Disable
+   * ```
+   */
+  createdAtColumn?: string | false;
+  /**
+   * Column name for update timestamp.
+   *
+   * Set to `false` to disable updatedAt entirely.
+   *
+   * @default "updatedAt" (MongoDB), "updated_at" (PostgreSQL)
+   *
+   * @example
+   * ```typescript
+   * updatedAtColumn: "last_modified"
+   * updatedAtColumn: false // Disable
+   * ```
+   */
+  updatedAtColumn?: string | false;
+  /**
+   * Delete strategy for this model.
+   *
+   * Controls how models are deleted:
+   * - `"trash"` - Moves to trash collection, then deletes
+   * - `"permanent"` - Direct deletion (hard delete)
+   * - `"soft"` - Sets deletedAt timestamp (soft delete)
+   *
+   * @default "permanent"
+   *
+   * @example
+   * ```typescript
+   * deleteStrategy: "soft"
+   * ```
+   */
+  deleteStrategy?: DeleteStrategy;
+  /**
+   * Column name for soft delete timestamp.
+   *
+   * Used when delete strategy is "soft".
+   * Set to `false` to use a different mechanism.
+   *
+   * @default "deletedAt" (MongoDB), "deleted_at" (PostgreSQL)
+   *
+   * @example
+   * ```typescript
+   * deletedAtColumn: "archived_at"
+   * ```
+   */
+  deletedAtColumn?: string | false;
+  /**
+   * Trash table/collection name override.
+   *
+   * Can be:
+   * - String: Fixed name for all models
+   * - Function: Generate trash table name based on model table
+   * - `undefined`: Use default pattern `{table}Trash`
+   *
+   * Used when delete strategy is "trash".
+   *
+   * @default undefined (uses {table}Trash pattern)
+   *
+   * @example
+   * ```typescript
+   * trashTable: "RecycleBin" // All models use same trash
+   * trashTable: (table) => `archive_${table}` // Dynamic naming
+   * ```
+   */
+  trashTable?: string | ((tableName: string) => string);
+  /**
+   * Strict mode behavior for unknown fields.
+   *
+   * - `"strip"`: Remove unknown fields silently (default)
+   * - `"fail"`: Throw validation error on unknown fields
+   * - `"allow"`: Allow unknown fields to pass through
+   *
+   * @default "strip"
+   *
+   * @example
+   * ```typescript
+   * strictMode: "fail" // Strict validation
+   * ```
+   */
+  strictMode?: StrictMode;
+  /**
+   * Naming convention for database column names.
+   *
+   * Affects default names for timestamps and other system columns.
+   *
+   * @default "camelCase" (MongoDB), "snake_case" (PostgreSQL)
+   *
+   * @example
+   * ```typescript
+   * namingConvention: "snake_case"
+   * // Results in: created_at, updated_at, deleted_at
+   * ```
+   */
+  namingConvention?: NamingConvention;
+};
+/**
+ * UUID generation strategy for primary keys.
+ *
+ * Each driver maps this to its native expression:
+ * - `"v4"`: PG → `gen_random_uuid()` (PG 13+), MySQL → `UUID()`
+ * - `"v7"`: PG → `uuid_generate_v7()` (PG 18+)
+ *
+ * @example
+ * ```typescript
+ * // In database config
+ * migrationDefaults: {
+ *   uuidStrategy: "v7", // Use UUID v7 (PG 18+)
+ * }
+ * ```
+ */
+type UuidStrategy = "v4" | "v7";
+/**
+ * Migration-level defaults configurable per data source.
+ *
+ * These settings affect DDL operations (schema changes) and are
+ * separate from runtime model behavior (`ModelDefaults`).
+ *
+ * The configuration follows a 3-tier hierarchy (highest to lowest):
+ * 1. Inline migration call (explicit `.default("...")`)
+ * 2. DataSource `migrationDefaults` (this type)
+ * 3. Driver migration defaults (e.g., PG defaults to v4)
+ *
+ * @example
+ * ```typescript
+ * // Use UUID v7 for all migrations on this data source
+ * migrationDefaults: {
+ *   uuidStrategy: "v7",
+ * }
+ *
+ * // Use a custom UUID extension
+ * migrationDefaults: {
+ *   uuidExpression: "uuid_generate_v1mc()",
+ * }
+ * ```
+ */
+type MigrationDefaults = {
+  /**
+   * UUID generation strategy for `primaryUuid()` migration shortcut.
+   * Each driver maps this to its native SQL/expression.
+   *
+   * @default "v4"
+   */
+  uuidStrategy?: UuidStrategy;
+  /**
+   * Raw SQL/expression override for UUID generation.
+   * Takes precedence over `uuidStrategy` when set.
+   *
+   * Use for custom extensions (e.g., `uuid-ossp`, `pgcrypto`)
+   * or non-standard UUID generation functions.
+   *
+   * @example "uuid_generate_v1mc()"
+   */
+  uuidExpression?: string;
+  /**
+   * Default primary key type for `Migration.create()`.
+   *
+   * Controls which primary key column is automatically added when using
+   * the declarative `Migration.create()` factory. Individual migrations
+   * can still override this by passing `{ primaryKey: false }` in options.
+   *
+   * - `"uuid"` — UUID primary key via `primaryUuid()` (default for PostgreSQL)
+   * - `"int"` — Auto-increment integer via `id()`
+   * - `"bigInt"` — Big auto-increment integer via `bigId()`
+   *
+   * @default "int"
+   *
+   * @example
+   * ```typescript
+   * // src/config/database.ts
+   * migrationOptions: {
+   *   uuidStrategy: "v7",
+   *   primaryKey: "uuid",
+   * }
+   * ```
+   */
+  primaryKey?: "uuid" | "int" | "bigInt";
+};
+/**
+ * Defaults for relation conventions — controls how `@BelongsTo` /
+ * `@HasOne` / `@HasMany` / `@BelongsToMany` infer foreign-key columns
+ * and pivot-table names when none are explicitly configured.
+ *
+ * **Note on column casing.** Foreign-key column casing follows
+ * `modelOptions.namingConvention` (snake_case vs camelCase) and is NOT
+ * a separate knob — exposing one here would let users desync FK casing
+ * from the actual column casing produced by migrations, which always
+ * silently breaks queries.
+ *
+ * @example
+ * ```typescript
+ * // src/config/database.ts
+ * relationOptions: {
+ *   foreignKeySuffix: "_id",                  // default
+ *   pivotTableNamingOrder: "alphabetical",    // default — `post_tag`
+ * }
+ * ```
+ */
+type RelationDefaults = {
+  /**
+   * Suffix appended to the inferred relation name to form the foreign-key
+   * column name.
+   *
+   * Examples (suffix = `"_id"`):
+   * - `@BelongsTo("Organization") organization` → `organization_id`
+   * - `@HasMany("Post") posts` on `User` → `user_id` on the `posts` table
+   *
+   * @default "_id"
+   */
+  foreignKeySuffix?: string;
+  /**
+   * Ordering rule used to derive the default pivot-table name for
+   * `@BelongsToMany` relations when no explicit `pivot` is given.
+   *
+   * - `"alphabetical"` — snake names sorted alphabetically (Laravel/Rails
+   *   default). `Post` + `Tag` → `post_tag`. Same result regardless of
+   *   which side declares the relation.
+   * - `"owner_first"` — owner's snake name first, related's snake name
+   *   second. `Post` declares `@BelongsToMany("Tag")` → `post_tag`;
+   *   `Tag` declares `@BelongsToMany("Post")` → `tag_post`. Less safe
+   *   when both sides declare the relation (the names disagree); only
+   *   pick this if you've standardised on one-side-declares.
+   *
+   * @default "alphabetical"
+   */
+  pivotTableNamingOrder?: "alphabetical" | "owner_first";
+};
+//#endregion
+export { DeleteStrategy, MigrationDefaults, ModelDefaults, NamingConvention, RelationDefaults, StrictMode, UuidStrategy };
+//# sourceMappingURL=types.d.mts.map

package/esm/types.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.mts","names":[],"sources":["../../../../../@warlock.js/cascade/src/types.ts"],"mappings":";;AAkBA;;;;AAAsB;AA0BtB;;;;AAA0B;AAsB1B;;;;AAA4B;AAyC5B;;KAzFY,UAAA;;;;;;;;;;;;;;;;;;;;;;;;AA+SyB;KArRzB,cAAA;;;;AA2SY;AA0BxB;;;;;;;;;AA0CY;AAuBZ;;;;AA4BuB;;KA5YX,gBAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAyCA,aAAA;;;;;;;;;;;EAeV,cAAA;;;;;;;;;;;EAYA,SAAA;;;;;;;;;;;;;;;;;EAkBA,eAAA;;;;;;;;;;;EAYA,aAAA;;;;;;;;;;;;;;;;;EAkBA,eAAA;;;;;;;;;EAcA,UAAA;;;;;;;;;;;;;;EAeA,eAAA;;;;;;;;;;;;;;EAeA,eAAA;;;;;;;;;;;;;;;;EAqBA,cAAA,GAAiB,cAAA;;;;;;;;;;;;;;EAejB,eAAA;;;;;;;;;;;;;;;;;;;EAoBA,UAAA,cAAwB,SAAA;;;;;;;;;;;;;;;EAoBxB,UAAA,GAAa,UAAA;;;;;;;;;;;;;;EAmBb,gBAAA,GAAmB,gBAAA;AAAA;;;;;;;;;;;;;;;;KAsBT,YAAA;;;;;;;;;;;;;;;;;;;;;;;;;KA0BA,iBAAA;;;;;;;EAOV,YAAA,GAAe,YAAY;;;;;;;;;;EAW3B,cAAA;;;;;;;;;;;;;;;;;;;;;;;EAwBA,UAAA;AAAA;;;;;;;;;;;;;;;;;;;;;KAuBU,gBAAA;;;;;;;;;;;EAWV,gBAAA;;;;;;;;;;;;;;;;EAiBA,qBAAqB;AAAA"}