@zerotal/orm 1.0.4 → 1.3.0

package/CHANGELOG.md

@@ -8,6 +8,77 @@ follows the Zerotal monorepo's unified versioning.
 
 ## [Unreleased]
 
+## [1.3.0] — 2026-08-09
+
+### Changed — BREAKING
+
+- **`BaseModelWith(...)` is replaced by the `Model.using(...)` static.** Mixin composition is now
+  a property of the base class rather than a helper shipped alongside it, so there is one idiom to
+  learn and nothing extra to import.
+
+  ```ts
+  // before
+  import { BaseModelWith } from "@zerotal/orm";
+  class User extends BaseModelWith(Authenticatable, Permissions, Roles) {}
+
+  // after
+  import { Model } from "@zerotal/orm";
+  class User extends Model.using(Authenticatable, Permissions, Roles) {}
+  ```
+
+  Run `bun run scripts/codemod-mixin-composition.ts` to rewrite call sites and imports.
+
+  How mixins are **authored** is unchanged — `<T extends Constructor>(Base: T) => class extends Base`
+  still works exactly as before, and every shipped mixin (`SoftDeletes`, `State`, `Authenticatable`,
+  `Roles`, `Permissions`, `Notifiable`, `Tenantable`, `Auditable`, …) keeps its signature. The
+  `Constructor` and `Mixin` types are still exported; `Compose` (the type of `Model.using`) joins
+  them. Mixin authors declaring columns still call `registerColumn` imperatively.
+
+  `with` was deliberately **not** used for this. It is reserved for the eager-load static
+  (`User.with("posts")`), the one conspicuous gap in the model's existing query-forwarder family
+  (`where`, `whereIn`, `orderBy`, `latest`, `first`, `paginate`, `find`, `all`, `count`, …).
+
+### Changed
+
+- **`Model` is now the canonical name for the base class; `BaseModel` is the alias.** They are the
+  same class object and both remain exported, so no code breaks — but `class User extends Model {}`
+  is the documented form from here, mirroring Flow's `class PostsPage extends Component {}`.
+  `BaseModel` was previously the canonical name and `Model` an unused compat alias added in 1.0.2.
+
+### Added
+
+- **`using` composes onto any class in the chain, not just the root.** An app-level base model can
+  now carry mixins without being flattened out of the prototype chain — `AppModel.using(SoftDeletes)`
+  keeps `AppModel` and its statics in the lineage. `BaseModelWith` hardcoded `BaseModel`, so this
+  previously required hand-nesting.
+- **Composition chains.** The composed class carries `using` itself, so
+  `Model.using(a, b).using(c, d)` works past the 8-mixin overload set — which is why the overload
+  set shrank from 20 hand-written arities to 8 without losing any capability.
+
+## [1.1.0] — 2026-08-08
+
+### Fixed
+
+- **A `json` column returns the type it was given.** Writing skipped `JSON.stringify` for values that were already strings, so a string went into the column as bare characters — `62812345678`, not `"62812345678"` — and the read side's `JSON.parse` turned it back into a number. A `json`-cast setting holding an account number came back as a number, and only for _some_ values, since a string that fails to parse fell through unchanged. Encoding is now symmetric in both directions, and `where()` against a `json` column encodes the same way, so a query finds what a write stores. **Upgrade note:** rows written by an older version hold bare scalars, so a string column may still read back as a number, and a `where()` on a string will not match those older rows — they are stored unquoted. Only affects bare scalars in `json`/`array` columns; objects and arrays were always encoded and are untouched.
+- **`bun zt make:model` generates a file that parses.** The stub emitted `@table('posts').withTimestamps()`, which is not valid decorator syntax — the grammar allows a call at the end of the chain, not in the middle — so every generated model failed with `Expected "class" but found "."`. The stub now emits plain `@table('posts')`; timestamps are on by default and the chained form needs outer parentheses, `@(table("x").withoutTimestamps())`. The same broken form is corrected in the `BaseModel` docblocks, and every generated stub is now parsed by a test rather than checked for substrings.
+- **A column `default` is applied on insert.** A declared field that was never assigned was written as an explicit `NULL`, so the INSERT named the column, the database never applied its own default, and a `NOT NULL` column failed outright — on a model and migration that both declared `default: 0`. `undefined` now means "I didn't say": the declared default is used, or the column is omitted so the database decides. An explicit `null` still stores `NULL`.
+- **A `Date` compared against a timestamp column matches again.** Bound values are serialised through the column's cast metadata, but the framework-managed `created_at` / `updated_at` / `deleted_at` carry no `@column` registration — so a `Date` was bound raw and matched nothing. `where("created_at", ">=", monthStart)` is the commonest reporting query there is, and it silently returned zero rows: a dashboard reading "0 this month" looks like a quiet month, not a broken query.
+
+### Added
+
+- `Schema.alter(...)` as an alias of `Schema.table(...)`, and `table.datetime(...)` as an alias of `table.dateTime(...)`. Both are the names other frameworks use, neither was a type error because the blueprint callback is loosely typed, and both therefore failed as a `TypeError` mid-migration — after earlier statements had already run, leaving the schema half-changed.
+- `@column("string", { nullable: true })` — a two-argument form. The shorthand keeps its type and cast; the options cannot contradict them.
+- `@column({ unique: true })` and `@column({ index: true })`, carried through to both `migrate:generate` and `synchronize`. Uniqueness is usually a correctness property, and it was not expressible at all.
+- Generated migrations index any `*_id` column. The reference cannot always be inferred, but the index can, and an unindexed foreign key is a table scan on every join.
+- `"text"` is its own storage type rather than an alias for `"string"`, so a real `TEXT` column is expressible — the distinction matters on Postgres and MySQL.
+
+### Changed
+
+- **`create()` narrows its payload to the mass-assignable columns** when a model declares `fillable` as a literal tuple (`as const`). A required column deliberately kept out of `fillable` was demanded by `InsertPayload` and refused by `fill()` at runtime: the type required exactly what the runtime forbade, and there was no spelling of `create()` that satisfied both. Models without a literal list are unaffected.
+- `static fillable` / `static guarded` accept `readonly string[]`.
+- A migration that fails with "already exists" now says that `database.synchronize` is the usual cause, since the raw driver error names nothing actionable.
+- `make:model` generates `fillable` as a literal tuple and documents that a nullable column is declared `?: T | undefined` — under the scaffold's `exactOptionalPropertyTypes`, `?: T` cannot be assigned `undefined`, so the field could never be cleared.
+
 ## [1.0.3] — 2026-08-07
 
 ### Changed

package/README.md

@@ -43,11 +43,11 @@ export default DatabaseConfig({
 ### Define a model
 
 ```ts
-import { BaseModel, column, table, belongsTo, hasMany } from "@zerotal/orm";
+import { Model, column, table, belongsTo, hasMany } from "@zerotal/orm";
 import type { Columns } from "@zerotal/orm";
 
 @(table("posts").withTimestamps().withSoftDeletes())
-export class Post extends BaseModel {
+export class Post extends Model {
   static fillable: Columns<Post>[] = ["title", "body", "status", "userId"];
 
   @column("string") title!: string;
@@ -144,7 +144,7 @@ This package exposes two subpath entry points:
 
 Main exports from the default entry point:
 
-- **Models** — `BaseModel` / `Model`, `ModelQueryBuilder`, `DB`, `QueryBuilder`
+- **Models** — `Model` (aka `BaseModel`), `ModelQueryBuilder`, `DB`, `QueryBuilder`
 - **Decorators** — `column`, `table`, `belongsTo`, `hasMany`, `hasOne`, `manyToMany`, `morphTo`, `morphMany`, `morphOne`, `hasManyThrough`, `hasOneThrough`, `morphToMany`, `morphedByMany`
 - **Schema / migrations** — `Schema`, `Blueprint`, `Migration`, `MigrationRunner`, `SchemaInspector`, `ModelInspector`, `SchemaDiffer`, `synchronizeSchema`
 - **Seeding** — `Seeder`

package/package.json

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

package/src/commands/MakeModelCommand.ts

@@ -7,13 +7,23 @@ import { createMigrationFile } from "./MakeMigrationCommand.ts";
 export function modelStub(name: string, tableName: string): string {
   return `import { BaseModel, column, table } from '@zerotal/orm';
 
-@table('${tableName}').withTimestamps()
+@table('${tableName}')
 export class ${name} extends BaseModel {
   // Models guard every attribute by default. List the columns that may be
   // mass-assigned from user input via create() / fill().
-  static override fillable: string[] = ['name'];
+  //
+  // \`as const\` is what lets create() narrow its payload to exactly these columns,
+  // so a column kept out of this list is neither required by the type nor accepted
+  // at runtime — instead of being demanded by one and refused by the other.
+  static override fillable = ['name'] as const;
 
   @column() name!: string;
+
+  // A nullable column is declared \`?: T | undefined\`, not \`?: T\`. The scaffold
+  // enables exactOptionalPropertyTypes, under which \`?: T\` means "may be absent,
+  // but never undefined" — so clearing the field, which is the whole point of a
+  // nullable column, would not typecheck.
+  // @column({ nullable: true }) note?: string | undefined;
 }
 `;
 }

package/src/errors/MigrationError.ts

@@ -9,10 +9,31 @@ import { ZerotalError } from "@zerotal/core";
  */
 export class MigrationError extends ZerotalError {
   constructor(migrationName: string, cause: Error) {
-    super(`Migration '${migrationName}' failed: ${cause.message}`, "E_MIGRATION_FAILED", 500, {
-      migration: migrationName,
-    });
+    super(
+      `Migration '${migrationName}' failed: ${cause.message}` + _syncHint(cause),
+      "E_MIGRATION_FAILED",
+      500,
+      { migration: migrationName },
+    );
     // Preserve the original error so its stack and message survive re-throwing.
     this.cause = cause;
   }
 }
+
+/**
+ * "table X already exists" on a migration that is supposed to create it almost always
+ * means boot-time schema sync got there first: `database.synchronize` built the table
+ * from the model before the migration ran. The two cannot both own a table, and the
+ * raw driver error gives no hint that a config flag is responsible — so name it here,
+ * at the only moment anyone is looking.
+ */
+function _syncHint(cause: Error): string {
+  if (!/already exists/i.test(cause.message)) return "";
+  return (
+    `\n\n  This usually means database.synchronize created the table from your model ` +
+    `before the migration ran.\n` +
+    `  A table can have one owner: set synchronize: false in config/database.ts and let ` +
+    `migrations build the schema,\n` +
+    `  or delete the migration and let synchronize own it.`
+  );
+}

package/src/index.ts

@@ -1,7 +1,7 @@
 /**
  * A Bun-native Active Record ORM built on `Bun.sql`.
  *
- * Models extend {@link BaseModel}: you declare columns with {@link column | `@column`},
+ * Models extend {@link Model}: you declare columns with {@link column | `@column`},
  * relationships with decorators like {@link hasMany | `@hasMany`} and
  * {@link belongsTo | `@belongsTo`}, and then query and persist through the model's
  * static and instance methods. Under the hood a {@link QueryBuilder} routes every
@@ -11,17 +11,17 @@
  * using the {@link Schema} facade and the {@link Blueprint} table builder.
  *
  * Mass assignment is **guarded by default** — a model with neither `fillable` nor
- * `guarded` declared rejects all attributes in {@link BaseModel.fill | `fill()`}.
+ * `guarded` declared rejects all attributes in {@link Model.fill | `fill()`}.
  * Soft deletes and state machines are opt-in mixins composed via
- * {@link BaseModelWith}. The ORM's CLI commands (`migrate`, `make:model`, …) live
+ * `Model.using(...)`. The ORM's CLI commands (`migrate`, `make:model`, …) live
  * under the `@zerotal/orm/commands` subpath.
  *
  * @example Define a model
  * ```ts
- * import { BaseModel, column, hasMany, type HasMany } from "@zerotal/orm";
+ * import { Model, column, hasMany, type HasMany } from "@zerotal/orm";
  * import { Post } from "./Post.ts";
  *
- * export class User extends BaseModel {
+ * export class User extends Model {
  *   @column({ primary: true }) id!: number;
  *   @column() email!: string;
  *   @column() name!: string;
@@ -70,12 +70,14 @@
 
 // @zerotal/orm — public API barrel
 
-export { BaseModel, Model } from "./model/BaseModel.ts";
-export { BaseModelWith } from "./model/mixins.ts";
-export type { Constructor, Mixin } from "./model/mixins.ts";
-// State-machine behaviour is an opt-in mixin — compose with `BaseModelWith(State)`.
+// `Model` is the canonical base class; `BaseModel` is the same class under its original name.
+export { Model, BaseModel } from "./model/BaseModel.ts";
+// Mixin authoring types. Compose them onto a model with the `Model.using(...)` static —
+// `class User extends Model.using(Authenticatable, Roles)`.
+export type { Constructor, Mixin, Compose } from "./model/mixins.ts";
+// State-machine behaviour is an opt-in mixin — compose with `Model.using(State)`.
 export { State } from "./model/State.ts";
-// Soft deletes are opt-in — compose with `BaseModelWith(SoftDeletes)`.
+// Soft deletes are opt-in — compose with `Model.using(SoftDeletes)`.
 export { SoftDeletes } from "./model/SoftDeletes.ts";
 export type {
   StateDefinition,
@@ -143,7 +145,7 @@ export { column, columnRegistry } from "./model/decorators/column.ts";
 export type { ColumnOptions, ColumnShorthand } from "./model/decorators/column.ts";
 export { registerModel, modelByName, modelsByName } from "./model/decorators/_metadata.ts";
 // Imperative column registration — for mixin authors composing model behaviour with
-// BaseModelWith (the @column decorator can't run inside a returned class expression).
+// Model.using (the @column decorator can't run inside a returned class expression).
 export { registerColumn, columnsFor } from "./model/decorators/_metadata.ts";
 export { table } from "./model/decorators/table.ts";
 export type { TableDecoratorBuilder, TableOptions } from "./model/decorators/table.ts";

package/src/model/BaseModel.ts

@@ -33,9 +33,11 @@ import {
 } from "../errors/index.ts";
 import { type ManyToMany } from "./relations/RelationRegistry.ts";
 import { installReactiveAccessors, type ColumnOptions } from "./decorators/column.ts";
+import { _compose } from "./mixins.ts";
+import type { Compose } from "./mixins.ts";
 import { columnsFor, relationsFor } from "./decorators/_metadata.ts";
 import { TransactionContext } from "../db/TransactionContext.ts";
-import type { InsertPayload, UpdatePayload } from "./payload.ts";
+import type { InsertPayload, UpdatePayload, FillablePayload } from "./payload.ts";
 import type { WhereOperator, OrderDirection } from "../db/types.ts";
 
 let _dialect: "sqlite" | "postgres" | "mysql" = "sqlite";
@@ -311,8 +313,13 @@ function applyCastSet(value: unknown, cast: StringCast): unknown {
       return value;
     case "array":
     case "json":
-      if (typeof value !== "string") return JSON.stringify(value);
-      return value;
+      // Encode unconditionally. Skipping strings was meant to avoid double-encoding a
+      // value that was already JSON text, but that is indistinguishable from a string
+      // someone means to store — and guessing wrong changed the value's *type* between
+      // write and read: `"62812345678"` went in as bare characters and came back out of
+      // `JSON.parse` as a number. Encoding both ways symmetrically is the only version
+      // of this that round-trips.
+      return JSON.stringify(value);
     case "date":
       if (value instanceof Carbon) return _serializeDate(value.toDate());
       if (value instanceof Date) return _serializeDate(value);
@@ -366,7 +373,9 @@ function _serializeForWrite(
     serializedVal = applyCastSet(val, castOpt);
   } else if (colType === "boolean" && val !== null && val !== undefined) {
     serializedVal = val ? 1 : 0;
-  } else if (colType === "json" && val !== null && typeof val !== "string") {
+  } else if (colType === "json" && val !== null) {
+    // See applyCastSet: strings are encoded too, so the column always holds valid JSON
+    // and a read returns the type that was written.
     serializedVal = JSON.stringify(val);
   } else {
     serializedVal = val;
@@ -460,7 +469,7 @@ export interface ScopeApplicator {
  * — TypeScript will catch typos and non-existent column references.
  *
  * @example
- * \@table("users").withTimestamps()
+ * \@table("users")
  * export class User extends BaseModel {
  *   static fillable: Columns<User>[] = ["name", "email", "role"];
  *   static hidden:   Columns<User>[] = ["password"];
@@ -516,7 +525,7 @@ export type Columns<T> = {
  * @example
  * Defining a model with `@column`:
  * ```ts
- * @table("users").withTimestamps()
+ * @table("users")
  * export class User extends BaseModel {
  *   static fillable: Columns<User>[] = ["name", "email", "password"];
  *   static hidden: Columns<User>[] = ["password"];
@@ -560,6 +569,37 @@ export class BaseModel {
    */
   declare readonly __isZerotalModel: true;
 
+  /**
+   * Compose one or more model mixins onto this class, folding them left-to-right, so reusable
+   * model behaviour (auth contract, roles, permissions, soft deletes, tenancy, …) stacks flat
+   * instead of nesting.
+   *
+   * @remarks
+   * Each mixin receives the accumulated base and returns an extended class, so this class's full
+   * static surface (`query()`, `find()`, `create()`, scopes, …) and every mixin's instance and
+   * static members flow through to the composed class — fully type-checked. Prefer this over
+   * hand-nesting mixins (`Roles(Permissions(AuthUser))`), which reads inside-out and repeats the
+   * base.
+   *
+   * `using` composes onto whatever class it is called on, so it also works on an intermediate
+   * model base, and the composed class carries `using` itself, so `Model.using(a, b).using(c)`
+   * chains past the 8-mixin overload set.
+   *
+   * Mixin authors declaring columns must call {@link registerColumn} imperatively — the `@column`
+   * decorator cannot run inside a returned class expression.
+   *
+   * @param mixins - Mixin factories applied in order; each receives the class the previous one produced.
+   * @returns A model class extending this one with every mixin applied.
+   *
+   * @example
+   * ```ts
+   * class User extends Model.using(Authenticatable, Permissions, Roles) {}
+   * ```
+   *
+   * @category Composition
+   */
+  static using: Compose = _compose;
+
   /**
    * Database table this model maps to. Usually set for you by the `@table("…")`
    * decorator; assign directly to override.
@@ -660,7 +700,7 @@ export class BaseModel {
    *
    * @category Attributes & mass assignment
    */
-  static fillable?: string[];
+  static fillable?: readonly string[];
 
   /**
    * Denylist of camelCase field names blocked from create() / fill().
@@ -669,7 +709,7 @@ export class BaseModel {
    *
    * @category Attributes & mass assignment
    */
-  static guarded?: string[];
+  static guarded?: readonly string[];
 
   /**
    * Disable mass-assignment protection for this model — every attribute passed
@@ -1198,6 +1238,11 @@ export class BaseModel {
    * Mass-assign `data` (respecting {@link fillable} / {@link guarded}) onto a new
    * instance and {@link save} it, returning the persisted model.
    *
+   * When the model declares `static fillable` as a literal tuple (`as const`), the
+   * payload type is narrowed to exactly those columns — so a column deliberately kept
+   * out of `fillable` is neither required nor accepted here, instead of being demanded
+   * by the type and rejected by {@link fill} at runtime.
+   *
    * @throws {MassAssignmentError} when `data` contains a non-fillable key.
    *
    * @example
@@ -1205,7 +1250,10 @@ export class BaseModel {
    *
    * @category Persistence
    */
-  static async create<T extends BaseModel>(this: ModelCtor<T>, data: InsertPayload<T>): Promise<T> {
+  static async create<T extends BaseModel, F extends string = string>(
+    this: ModelCtor<T> & { fillable?: readonly F[] | undefined },
+    data: FillablePayload<T, F>,
+  ): Promise<T> {
     const inst = new this();
     inst.fill(data as UpdatePayload<T>);
     return inst.save() as Promise<T>;
@@ -1604,9 +1652,12 @@ export class BaseModel {
     // On INSERT: hash every hashable field that holds a non-empty string.
     // On UPDATE: only hash hashable fields whose value changed since the last
     //            save (avoids re-hashing an already-stored bcrypt hash).
+    // One keyed view of the instance for the whole method: the hashable pass and the
+    // insert's default-filling both need to read and write columns by name.
+    const self = this as unknown as Record<string, unknown>;
+
     const hashable = ModelClass.hashable;
     if (hashable && hashable.length > 0) {
-      const self = this as unknown as Record<string, unknown>;
       if (!this._exists) {
         for (const key of hashable) {
           const val = self[key];
@@ -1635,7 +1686,24 @@ export class BaseModel {
       const row: Record<string, unknown> = _writeDialect.run(dialect, () => {
         const r: Record<string, unknown> = {};
         for (const [key, val] of ownDataEntries(this, SYSTEM_KEYS, rels, colKeys)) {
-          r[toSnake(key)] = _serializeForWrite(key, val, casts, colReg);
+          // A declared field that was never assigned is `undefined`, and writing that
+          // as an explicit NULL made `@column({ default: … })` inert: the INSERT named
+          // the column, so the database never applied its own default and a NOT NULL
+          // column failed outright. Fall back to the declared default, and if there
+          // isn't one, omit the column entirely so the database decides.
+          //
+          // Only `undefined` is treated this way. An explicit `null` is a deliberate
+          // "store NULL" and still writes one.
+          let effective = val;
+          if (effective === undefined) {
+            const declared = colReg?.get(key)?.default;
+            if (declared === undefined) continue; // omit → database default / NULL
+            effective = typeof declared === "function" ? (declared as () => unknown)() : declared;
+            // Keep the instance consistent with the row we are about to write, so the
+            // value is readable straight after save() without a reload.
+            self[key] = effective;
+          }
+          r[toSnake(key)] = _serializeForWrite(key, effective, casts, colReg);
         }
         if (ModelClass.timestamps) {
           const now = _serializeDate(new Date());
@@ -2495,5 +2563,7 @@ function _applyRow(inst: BaseModel, row: Record<string, unknown>): void {
   (inst as unknown as { _original: Record<string, unknown> })._original = orig;
 }
 
-// Backward-compat alias (index.ts exports `Model`)
+// `Model` is the canonical name at the declaration site — `class User extends Model.using(…)`
+// mirrors Flow's `class PostsPage extends Component.using(…)`. `BaseModel` remains exported as
+// an alias (same class object) for code that references the base class by that name.
 export { BaseModel as Model };

package/src/model/ModelQueryBuilder.ts

@@ -1,6 +1,6 @@
 import type { SQLInstance } from "../db/sql-types.ts";
 import { Carbon } from "@zerotal/core/carbon";
-import { QueryBuilder, OPERATORS, _inlineValue } from "../db/QueryBuilder.ts";
+import { QueryBuilder, OPERATORS, _inlineValue, dialectFor } from "../db/QueryBuilder.ts";
 import {
   toCamelKey as _toCamel,
   toSnakeColumn as _toSnakeColumn,
@@ -1261,11 +1261,26 @@ export class ModelQueryBuilder<M extends BaseModel> extends QueryBuilder {
     if (colType === "boolean") {
       return value ? 1 : 0;
     }
-    if (colType === "json" && typeof value !== "string") {
+    if (colType === "json") {
+      // Match how writes encode: strings are stringified too, so a column holding
+      // `"051001"` is found by `where("value", "051001")` rather than only by a caller
+      // who knows to pre-encode the quotes themselves.
       return JSON.stringify(value);
     }
     // Carbon instances always serialize to ISO string regardless of column metadata.
     if (value instanceof Carbon) return value.toDatabase();
+    // …and so does a plain Date. Without this, a comparison against a column the cast
+    // lookup above can't see — most importantly the framework-managed `created_at` /
+    // `updated_at` / `deleted_at`, which carry no `@column` metadata — bound the Date
+    // object itself and matched nothing. `where("created_at", ">=", monthStart)` is the
+    // commonest reporting query there is, and it silently returned zero rows: a
+    // dashboard reading "0 this month" looks like a quiet month, not a broken query.
+    // A Date in a comparison is unambiguous intent, so serialize it the way writes do.
+    if (value instanceof Date) {
+      return dialectFor(this._sql) === "mysql"
+        ? value.toISOString().replace("T", " ").slice(0, 19)
+        : value.toISOString();
+    }
     return value;
   }
 

package/src/model/SoftDeletes.ts

@@ -4,10 +4,10 @@
 // `deletedAt`, `forceDelete()`, `restore()`, `trashed()`, and the `withTrashed()` /
 // `onlyTrashed()` query scopes. A hard-delete model has none of these.
 //
-//   import { BaseModelWith, SoftDeletes } from "@zerotal/orm";
+//   import { Model, SoftDeletes } from "@zerotal/orm";
 //
 //   @table("posts")
-//   class Post extends BaseModelWith(SoftDeletes) {
+//   class Post extends Model.using(SoftDeletes) {
 //     @column() title!: string;
 //   }
 //
@@ -47,7 +47,7 @@ interface SoftDeleteModelClass<T extends BaseModel> {
  * @example
  * ```ts
  * @table("posts")
- * class Post extends BaseModelWith(SoftDeletes) {
+ * class Post extends Model.using(SoftDeletes) {
  *   @column() title!: string;
  * }
  *

package/src/model/State.ts

@@ -4,7 +4,7 @@
 // workflow carry the API — `transitionTo` / `forceState` / `onTransition` / the
 // `states` + `stateField` statics never appear on models that don't use them.
 //
-//   import { BaseModelWith } from "@zerotal/orm";
+//   import { Model, State } from "@zerotal/orm";
 //
 //   const States = {
 //     pending: { canTransitionTo: ["active", "cancelled"] as const },
@@ -14,7 +14,7 @@
 //     cancelled: { canTransitionTo: [] as const },
 //   } as const;
 //
-//   class Subscription extends BaseModelWith(State) {
+//   class Subscription extends Model.using(State) {
 //     static states = States;
 //     @column() status!: keyof typeof States;
 //   }
@@ -132,7 +132,7 @@ interface StateModelClass {
  *   cancelled: { canTransitionTo: [] as const },
  * } as const;
  *
- * class Subscription extends BaseModelWith(State) {
+ * class Subscription extends Model.using(State) {
  *   static states = States;
  *   @column() status!: keyof typeof States;
  * }

package/src/model/decorators/column.ts

@@ -19,8 +19,8 @@ export { columnRegistry };
  *
  * | Shorthand   | Equivalent options                              |
  * |-------------|--------------------------------------------------|
- * | `"string"`  | `{ type: "string" }`                            |
- * | `"text"`    | `{ type: "string" }` (large text, alias)        |
+ * | `"string"`  | `{ type: "string" }` (VARCHAR)                   |
+ * | `"text"`    | `{ type: "text" }` (unbounded TEXT)             |
  * | `"integer"` | `{ type: "number", cast: "integer" }`           |
  * | `"number"`  | `{ type: "number" }`                            |
  * | `"float"`   | `{ type: "number", cast: "float" }`             |
@@ -68,14 +68,32 @@ export type ColumnShorthand =
  * ```
  */
 export interface ColumnOptions {
-  /** Logical storage type; drives schema generation and auto-migration. @default "string" */
-  type?: "string" | "number" | "boolean" | "datetime" | "json";
+  /**
+   * Logical storage type; drives schema generation and auto-migration.
+   *
+   * `"string"` is a bounded VARCHAR; `"text"` is the unbounded TEXT type — a real
+   * distinction on Postgres and MySQL, where a long body in a VARCHAR(255) is an
+   * error rather than a slow column.
+   *
+   * @default "string"
+   */
+  type?: "string" | "text" | "number" | "boolean" | "datetime" | "json";
   /** Mark this column as the table's primary key. */
   primary?: boolean;
   /** Allow SQL `NULL` for this column. */
   nullable?: boolean;
   /** Default value applied when none is provided. */
   default?: unknown;
+  /**
+   * Add a unique index on this column during schema generation / auto-migration.
+   *
+   * Declared here rather than left to a hand-written migration because uniqueness is
+   * usually a correctness property (a webhook idempotency key, an invoice number),
+   * and `migrate:generate` can only emit constraints it can see declared.
+   */
+  unique?: boolean;
+  /** Add a plain (non-unique) index on this column. */
+  index?: boolean;
   /**
    * Shorthand cast types automatically serialize/deserialize the column value.
    * Can also be a custom object with `get`/`set` functions for full control.
@@ -113,7 +131,7 @@ export interface ColumnOptions {
  */
 const SHORTHAND_MAP: Record<ColumnShorthand, ColumnOptions> = {
   string: { type: "string" },
-  text: { type: "string" },
+  text: { type: "text" },
   integer: { type: "number", cast: "integer" },
   number: { type: "number" },
   float: { type: "number", cast: "float" },
@@ -124,7 +142,31 @@ const SHORTHAND_MAP: Record<ColumnShorthand, ColumnOptions> = {
   array: { type: "json", cast: "array" },
 };
 
-function resolveOptions(arg?: ColumnShorthand | ColumnOptions): ColumnOptions {
+/**
+ * Resolve the decorator's arguments to one options object.
+ *
+ * `extra` is the second argument of the `@column("string", { nullable: true })` form —
+ * the shorthand covers the common case and nullability is the most common modifier, so
+ * writing `@column({ type: "number", cast: "integer", nullable: true })` just to say
+ * "nullable int" is noise. The shorthand's own `type`/`cast` win: `extra` is typed as
+ * `Omit<ColumnOptions, "type">`, so it cannot contradict the type it is modifying.
+ */
+function resolveOptions(
+  arg?: ColumnShorthand | ColumnOptions,
+  extra?: Omit<ColumnOptions, "type">,
+): ColumnOptions {
+  const base = _resolveBase(arg);
+  if (!extra) return base;
+  // Spread `base` last for type/cast so the shorthand keeps ownership of them, and never
+  // write an explicit `undefined` — under exactOptionalPropertyTypes that is a distinct,
+  // and invalid, value rather than an absent key.
+  const merged: ColumnOptions = { ...extra };
+  if (base.type !== undefined) merged.type = base.type;
+  if (extra.cast === undefined && base.cast !== undefined) merged.cast = base.cast;
+  return merged;
+}
+
+function _resolveBase(arg?: ColumnShorthand | ColumnOptions): ColumnOptions {
   if (arg === undefined) return { type: "string" };
   if (typeof arg === "string") {
     const a = arg as string;
@@ -243,8 +285,15 @@ type ColumnDecorator = (value: undefined, context: ClassFieldDecoratorContext) =
 export function column(): ColumnDecorator;
 export function column(type: ColumnShorthand): ColumnDecorator;
 export function column(options: ColumnOptions): ColumnDecorator;
-export function column(arg?: ColumnShorthand | ColumnOptions): ColumnDecorator {
-  const options = resolveOptions(arg);
+export function column(
+  type: ColumnShorthand,
+  options: Omit<ColumnOptions, "type">,
+): ColumnDecorator;
+export function column(
+  arg?: ColumnShorthand | ColumnOptions,
+  extra?: Omit<ColumnOptions, "type">,
+): ColumnDecorator {
+  const options = resolveOptions(arg, extra);
   // The decorator BODY runs synchronously at definition time with the correct
   // `context.name` (the only thing Bun 1.3.x compiles reliably for field decorators).
   // We can't defer to a field initializer or addInitializer — Bun cross-wires those

package/src/model/decorators/table.ts

@@ -46,7 +46,7 @@ interface TableConfig {
  * export class Post extends BaseModel { ... }
  *
  * Soft deletes are opt-in via the `SoftDeletes` mixin, not `@table`:
- * `class Post extends BaseModelWith(SoftDeletes) {}` — see /docs/orm/lifecycle.
+ * `class Post extends Model.using(SoftDeletes) {}` — see /docs/orm/lifecycle.
  */
 export interface TableDecoratorBuilder {
   /** Apply the decorator to a class constructor (called automatically by TS). */
@@ -77,7 +77,7 @@ export interface TableDecoratorBuilder {
  * ```
  *
  * Timestamps are **on by default** — use `.withoutTimestamps()` to opt out. Soft
- * deletes are **opt-in via the `SoftDeletes` mixin**: `extends BaseModelWith(SoftDeletes)`.
+ * deletes are **opt-in via the `SoftDeletes` mixin**: `extends Model.using(SoftDeletes)`.
  *
  * `@table` is the single, required way to configure a model: besides setting the
  * table name and options, it anchors the class's `@column`/relation registrations at