@zerotal/orm 1.9.0 → 1.10.0

package/api-surface.md

@@ -806,14 +806,14 @@ interface CastField = {
 }
 
 interface ColumnOptions = {
-  cast?: 'boolean' | 'date' | 'datetime' | 'array' | 'integer' | 'json' | 'float' | 'enum' | 'immutable_datetime' | 'encrypted' | 'encrypted:json' | `decimal:${number}` | {    get?: (dbValue: unknown) => unknown;    set?: (jsValue: unknown) => unknown;} | CastContract<unknown>
+  cast?: 'boolean' | 'date' | 'datetime' | 'array' | 'integer' | 'json' | 'float' | 'enum' | 'immutable_datetime' | 'encrypted' | 'encrypted:json' | `decimal:${number}` | {    get?: (dbValue: unknown) => unknown;    set?: (jsValue: unknown) => unknown;} | CastContract<unknown> | undefined
   default?: unknown
-  enumValues?: Record<string, string | number>
-  index?: boolean
-  nullable?: boolean
-  primary?: boolean
-  type?: 'string' | 'number' | 'boolean' | 'text' | 'datetime' | 'json'
-  unique?: boolean
+  enumValues?: Record<string, string | number> | undefined
+  index?: boolean | undefined
+  nullable?: boolean | undefined
+  primary?: boolean | undefined
+  type?: 'string' | 'number' | 'boolean' | 'text' | 'datetime' | 'json' | undefined
+  unique?: boolean | undefined
 }
 
 interface Compose = {
@@ -836,10 +836,10 @@ interface CursorPaginateResult = {
 
 interface DatabaseConfigShape = {
   driver: 'sqlite' | 'postgres' | 'mysql'
-  pool?: {    max?: number;    idleTimeout?: number;}
-  replicas?: string[]
+  pool?: {    max?: number;    idleTimeout?: number;} | undefined
+  replicas?: string[] | undefined
   sqlite: {    path: string;}
-  synchronize?: boolean | {    enabled: boolean;    disruptive?: boolean;}
+  synchronize?: boolean | {    enabled: boolean;    disruptive?: boolean;} | undefined
   url: string
 }
 
@@ -850,9 +850,9 @@ interface HasMany = {
 
 interface HasManyThroughOptions = {
   firstKey: string
-  localKey?: string
+  localKey?: string | undefined
   secondKey: string
-  throughLocalKey?: string
+  throughLocalKey?: string | undefined
 }
 
 interface HasOne = {
@@ -861,10 +861,10 @@ interface HasOne = {
 }
 
 interface KeysetOptions = {
-  column?: string
-  cursor?: string | null
-  direction?: 'asc' | 'desc'
-  limit?: number
+  column?: string | undefined
+  cursor?: string | null | undefined
+  direction?: 'asc' | 'desc' | undefined
+  limit?: number | undefined
 }
 
 interface KeysetPaginateResult = {
@@ -890,13 +890,13 @@ interface ManyToMany = {
 }
 
 interface ManyToManyOptions = {
-  localKey?: string
+  localKey?: string | undefined
   pivotForeignKey: string
   pivotRelatedKey: string
   pivotTable: string
-  relatedKey?: string
-  withPivot?: string[]
-  withTimestamps?: boolean
+  relatedKey?: string | undefined
+  withPivot?: string[] | undefined
+  withTimestamps?: boolean | undefined
 }
 
 interface MigrationEntry = {
@@ -931,9 +931,9 @@ interface ModelObserver = {
 interface MorphedByManyOptions = {
   morphName: string
   parentPivotKey: string
-  pivotTable?: string
-  withPivot?: string[]
-  withTimestamps?: boolean
+  pivotTable?: string | undefined
+  withPivot?: string[] | undefined
+  withTimestamps?: boolean | undefined
 }
 
 interface MorphMany = {
@@ -942,7 +942,7 @@ interface MorphMany = {
 }
 
 interface MorphManyOptions = {
-  localKey?: string
+  localKey?: string | undefined
   morphName: string
 }
 
@@ -952,7 +952,7 @@ interface MorphOne = {
 }
 
 interface MorphOneOptions = {
-  localKey?: string
+  localKey?: string | undefined
   morphName: string
 }
 
@@ -963,21 +963,21 @@ interface MorphTo = {
 
 interface MorphToManyOptions = {
   morphName: string
-  pivotTable?: string
+  pivotTable?: string | undefined
   relatedPivotKey: string
-  withPivot?: string[]
-  withTimestamps?: boolean
+  withPivot?: string[] | undefined
+  withTimestamps?: boolean | undefined
 }
 
 interface MorphToOptions = {
-  morphForeignKey?: string
+  morphForeignKey?: string | undefined
   morphMap: Record<string, () => unknown>
-  morphTypeColumn?: string
+  morphTypeColumn?: string | undefined
 }
 
 interface NPlusOneOptions = {
-  mode?: 'warn' | 'throw'
-  threshold?: number
+  mode?: 'warn' | 'throw' | undefined
+  threshold?: number | undefined
 }
 
 interface PaginateMeta = {
@@ -1067,8 +1067,8 @@ interface TableDecoratorBuilder = {
 }
 
 interface TableOptions = {
-  primaryKey?: string
-  timestamps?: boolean
+  primaryKey?: string | undefined
+  timestamps?: boolean | undefined
 }
 
 interface TransitionContext = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerotal/orm",
-  "version": "1.9.0",
+  "version": "1.10.0",
   "license": "MIT",
   "maturity": "stable",
   "private": false,
@@ -31,8 +31,8 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zerotal/core": "1.9.0",
-    "@zerotal/validator": "1.9.0"
+    "@zerotal/core": "1.10.0",
+    "@zerotal/validator": "1.10.0"
   },
   "devDependencies": {
     "typescript": "^5.8.0"

package/src/commands/_backup.ts

@@ -45,15 +45,15 @@ export interface BackupOptions {
    * it". An empty `bookings` table in a snapshot of a live system is not a small
    * discrepancy, it is the whole failure — and it is invisible in a byte count.
    */
-  requireRows?: string[];
+  requireRows?: string[] | undefined;
   /**
    * Perform the restore, not just a read of the snapshot: copy it to a scratch
    * path, open the copy, and check it there. Exercises the operation an incident
    * actually needs, rather than the one that is convenient to test.
    */
-  rehearse?: boolean;
+  rehearse?: boolean | undefined;
   /** Clock, so the snapshot name is deterministic under test. */
-  now?: Date;
+  now?: Date | undefined;
 }
 
 /** What a completed backup wrote and proved. */

package/src/config.ts

@@ -28,17 +28,19 @@ export interface DatabaseConfigShape {
    *   env('REPLICA_2_URL'),
    * ].filter((url) => url !== undefined)
    */
-  replicas?: string[];
+  replicas?: string[] | undefined;
   /**
    * Connection pool options (PostgreSQL and MySQL only).
    * Bun.sql manages the pool automatically - these tune its behaviour.
    */
-  pool?: {
-    /** Maximum number of connections in the pool. Default: 10 */
-    max?: number;
-    /** Seconds an idle connection is kept before being closed. Default: 30 */
-    idleTimeout?: number;
-  };
+  pool?:
+    | {
+        /** Maximum number of connections in the pool. Default: 10 */
+        max?: number;
+        /** Seconds an idle connection is kept before being closed. Default: 30 */
+        idleTimeout?: number;
+      }
+    | undefined;
   /** SQLite-specific options */
   sqlite: {
     /** Path to the SQLite file. Use ':memory:' for in-memory database. */
@@ -58,7 +60,7 @@ export interface DatabaseConfigShape {
    * synchronize: { enabled: true, disruptive: false }     // explicit, additive
    * synchronize: { enabled: true, disruptive: true }      // also drops removed columns
    */
-  synchronize?: boolean | { enabled: boolean; disruptive?: boolean };
+  synchronize?: boolean | { enabled: boolean; disruptive?: boolean } | undefined;
 }
 
 const defaults: DatabaseConfigShape = {

package/src/db/NPlusOneDetector.ts

@@ -104,12 +104,12 @@ let _forced = false; // true when explicitly configured via preventNPlusOne()
 
 export interface NPlusOneOptions {
   /** How many identical query shapes in one request triggers a violation. Default: 5. */
-  threshold?: number;
+  threshold?: number | undefined;
   /**
    * 'warn'  → console.warn (default — non-breaking, still visible)
    * 'throw' → throws NPlusOneError (good for CI / strict mode)
    */
-  mode?: "warn" | "throw";
+  mode?: "warn" | "throw" | undefined;
 }
 
 /**

package/src/db/types.ts

@@ -159,7 +159,7 @@ function _pageUrl(baseUrl: string, page: number, extra: Record<string, string> =
 /** Options accepted by the pagination helper factories. */
 export interface PaginationHelperOptions {
   /** Base path used by no-argument URL helpers and `meta.path`. Default: `''`. */
-  path?: string;
+  path?: string | undefined;
 }
 
 /** Attach URL helper methods + metadata to a plain paginate result object. */
@@ -276,13 +276,13 @@ export interface KeysetOptions {
    * Opaque cursor string from the previous page's `nextCursor`.
    * `null` or omitted = first page.
    */
-  cursor?: string | null;
+  cursor?: string | null | undefined;
   /** Column used for keyset ordering. Must be a safe SQL identifier. Default: `'id'`. */
-  column?: string;
+  column?: string | undefined;
   /** Sort direction. Default: `'asc'`. */
-  direction?: "asc" | "desc";
+  direction?: "asc" | "desc" | undefined;
   /** Items per page. Default: `15`. */
-  limit?: number;
+  limit?: number | undefined;
 }
 
 /** Result of {@link QueryBuilder.keysetPaginate} — opaque-cursor keyset pagination. */

package/src/model/decorators/belongsTo.ts

@@ -5,9 +5,9 @@ export interface BelongsToOptions {
   /** FK column on this (child) model pointing to the related row (e.g. `user_id`). */
   foreignKey: string;
   /** Key on the related model the FK references. Defaults to `'id'`. */
-  localKey?: string;
+  localKey?: string | undefined;
   /** Return a default (unsaved) related model instead of null when absent. */
-  withDefault?: boolean | Record<string, unknown> | ((model: unknown) => void);
+  withDefault?: boolean | Record<string, unknown> | ((model: unknown) => void) | undefined;
 }
 
 /**

package/src/model/decorators/column.ts

@@ -82,11 +82,11 @@ export interface ColumnOptions {
    *
    * @default "string"
    */
-  type?: "string" | "text" | "number" | "boolean" | "datetime" | "json";
+  type?: "string" | "text" | "number" | "boolean" | "datetime" | "json" | undefined;
   /** Mark this column as the table's primary key. */
-  primary?: boolean;
+  primary?: boolean | undefined;
   /** Allow SQL `NULL` for this column. */
-  nullable?: boolean;
+  nullable?: boolean | undefined;
   /** Default value applied when none is provided. */
   default?: unknown;
   /**
@@ -96,9 +96,9 @@ export interface ColumnOptions {
    * usually a correctness property (a webhook idempotency key, an invoice number),
    * and `migrate:generate` can only emit constraints it can see declared.
    */
-  unique?: boolean;
+  unique?: boolean | undefined;
   /** Add a plain (non-unique) index on this column. */
-  index?: boolean;
+  index?: boolean | undefined;
   /**
    * Shorthand cast types automatically serialize/deserialize the column value.
    * Can also be a custom object with `get`/`set` functions for full control.
@@ -134,9 +134,10 @@ export interface ColumnOptions {
         get?: (dbValue: unknown) => unknown;
         set?: (jsValue: unknown) => unknown;
       }
-    | CastContract<unknown>;
+    | CastContract<unknown>
+    | undefined;
   /** Enum object (e.g. the imported TS enum) used alongside cast: 'enum'. */
-  enumValues?: Record<string, string | number>;
+  enumValues?: Record<string, string | number> | undefined;
 }
 
 /**

package/src/model/decorators/hasMany.ts

@@ -5,7 +5,7 @@ export interface HasManyOptions {
   /** FK column on the related table pointing back to the parent (e.g. `user_id`). */
   foreignKey: string;
   /** Parent local key the FK references. Defaults to `'id'`. */
-  localKey?: string;
+  localKey?: string | undefined;
 }
 
 /**

package/src/model/decorators/hasManyThrough.ts

@@ -6,9 +6,9 @@ export interface HasManyThroughOptions {
   /** FK on the related table referencing the through model (e.g. 'user_id' on posts). */
   secondKey: string;
   /** Parent local key the firstKey references. Default 'id'. */
-  localKey?: string;
+  localKey?: string | undefined;
   /** Through local key the secondKey references. Default 'id'. */
-  throughLocalKey?: string;
+  throughLocalKey?: string | undefined;
 }
 
 /**

package/src/model/decorators/hasOne.ts

@@ -5,7 +5,7 @@ export interface HasOneOptions {
   /** FK column on the related table pointing back to the parent (e.g. `user_id`). */
   foreignKey: string;
   /** Parent local key the FK references. Defaults to `'id'`. */
-  localKey?: string;
+  localKey?: string | undefined;
 }
 
 /**

package/src/model/decorators/manyToMany.ts

@@ -9,13 +9,13 @@ export interface ManyToManyOptions {
   /** Pivot column referencing the related model (e.g. `role_id`). */
   pivotRelatedKey: string;
   /** Parent local key the pivot FK references. Defaults to `'id'`. */
-  localKey?: string;
+  localKey?: string | undefined;
   /** Related local key the pivot relatedKey references. Defaults to `'id'`. */
-  relatedKey?: string;
+  relatedKey?: string | undefined;
   /** Extra pivot columns to hydrate onto each related model's `pivot` bag. */
-  withPivot?: string[];
+  withPivot?: string[] | undefined;
   /** Maintain created_at / updated_at on the pivot table during attach/sync. */
-  withTimestamps?: boolean;
+  withTimestamps?: boolean | undefined;
 }
 
 /**

package/src/model/decorators/morphMany.ts

@@ -7,7 +7,7 @@ export interface MorphManyOptions {
    */
   morphName: string;
   /** Override the local key. Defaults to 'id'. */
-  localKey?: string;
+  localKey?: string | undefined;
 }
 
 /**

package/src/model/decorators/morphOne.ts

@@ -7,7 +7,7 @@ export interface MorphOneOptions {
    */
   morphName: string;
   /** Override the local key. Defaults to 'id'. */
-  localKey?: string;
+  localKey?: string | undefined;
 }
 
 /**

package/src/model/decorators/morphTo.ts

@@ -7,12 +7,12 @@ export interface MorphToOptions {
    * Override the _type column name. Defaults to `<propertyName>_type`.
    * e.g. property `commentable` → `commentable_type`.
    */
-  morphTypeColumn?: string;
+  morphTypeColumn?: string | undefined;
   /**
    * Override the _id column name. Defaults to `<propertyName>_id`.
    * e.g. property `commentable` → `commentable_id`.
    */
-  morphForeignKey?: string;
+  morphForeignKey?: string | undefined;
 }
 
 function _toSnake(s: string): string {

package/src/model/decorators/morphToMany.ts

@@ -6,11 +6,11 @@ export interface MorphToManyOptions {
   /** FK on the pivot table referencing the related model (e.g. 'tag_id'). */
   relatedPivotKey: string;
   /** Pivot table name. Defaults to `{morphName}s`. */
-  pivotTable?: string;
+  pivotTable?: string | undefined;
   /** Extra pivot columns to hydrate. */
-  withPivot?: string[];
+  withPivot?: string[] | undefined;
   /** Maintain pivot timestamps. */
-  withTimestamps?: boolean;
+  withTimestamps?: boolean | undefined;
 }
 
 /**

package/src/model/decorators/morphedByMany.ts

@@ -6,9 +6,9 @@ export interface MorphedByManyOptions {
   /** FK on the pivot referencing the parent model (e.g. 'tag_id'). */
   parentPivotKey: string;
   /** Pivot table name. Defaults to `{morphName}s`. */
-  pivotTable?: string;
-  withPivot?: string[];
-  withTimestamps?: boolean;
+  pivotTable?: string | undefined;
+  withPivot?: string[] | undefined;
+  withTimestamps?: boolean | undefined;
 }
 
 /**

package/src/model/decorators/table.ts

@@ -11,9 +11,9 @@ import type { ClassRef } from "../../support/classRef.ts";
  */
 export interface TableOptions {
   /** Enable / disable automatic timestamp columns. @default true */
-  timestamps?: boolean;
+  timestamps?: boolean | undefined;
   /** Override the primary key column name. @default "id" */
-  primaryKey?: string;
+  primaryKey?: string | undefined;
 }
 
 /**

package/src/schema/autoMigrate.ts

@@ -52,7 +52,7 @@ export interface SynchronizeOptions {
    * declared by any model. Off by default - additive changes are always safe,
    * drops can lose data.
    */
-  disruptive?: boolean;
+  disruptive?: boolean | undefined;
 }
 
 /**