@zerotal/orm 1.1.0 → 1.4.0

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

@@ -29,6 +29,8 @@ export { columnRegistry };
  * | `"date"`    | `{ type: "datetime", cast: "date" }`            |
  * | `"json"`    | `{ type: "json", cast: "json" }`                |
  * | `"array"`   | `{ type: "json", cast: "array" }`               |
+ * | `"encrypted"` | `{ type: "text", cast: "encrypted" }`         |
+ * | `"encrypted:json"` | `{ type: "text", cast: "encrypted:json" }` |
  */
 export type ColumnShorthand =
   | "string"
@@ -40,7 +42,9 @@ export type ColumnShorthand =
   | "datetime"
   | "date"
   | "json"
-  | "array";
+  | "array"
+  | "encrypted"
+  | "encrypted:json";
 
 /**
  * Full option object accepted by `@column({ ... })`.
@@ -105,6 +109,12 @@ export interface ColumnOptions {
    * - 'integer'        — parseInt on both read and write
    * - 'float'          — parseFloat on both read and write
    * - 'enum'           — pass-through; pairs with `enumValues` for TS enum columns
+   * - 'encrypted'      — AES-256-GCM at rest under `APP_KEY`, plaintext on the model
+   * - 'encrypted:json' — the same, for a structured value (stringified, then encrypted)
+   *
+   * Encrypted columns need `type: "text"` (a payload outgrows the plaintext) and
+   * cannot be filtered on — `where()` against one throws, because a fresh IV per
+   * write means the ciphertext never repeats. See `casts/encrypted.ts`.
    */
   cast?:
     | "datetime"
@@ -116,6 +126,8 @@ export interface ColumnOptions {
     | "float"
     | "enum"
     | "immutable_datetime"
+    | "encrypted"
+    | "encrypted:json"
     | `decimal:${number}`
     | {
         get?: (dbValue: unknown) => unknown;
@@ -140,6 +152,10 @@ const SHORTHAND_MAP: Record<ColumnShorthand, ColumnOptions> = {
   date: { type: "datetime", cast: "date" },
   json: { type: "json", cast: "json" },
   array: { type: "json", cast: "array" },
+  // TEXT, not string: the stored payload is ~1.4× the plaintext plus 28 bytes of
+  // IV and auth tag, so a VARCHAR that held the value will not hold its ciphertext.
+  encrypted: { type: "text", cast: "encrypted" },
+  "encrypted:json": { type: "text", cast: "encrypted:json" },
 };
 
 /**

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