@zerotal/orm 1.0.4 → 1.3.0

package/src/model/mixins.ts

@@ -1,22 +1,25 @@
 // ── Model mixins ──────────────────────────────────────────────────────────────
 //
-// `BaseModelWith(...)` composes any number of model mixins on top of `BaseModel`,
-// so packages can ship reusable model behaviour (auth contract, roles, permissions,
-// soft deletes, …) that apps stack without "wrapper hell":
+// Mixin composition machinery for the ORM. The entry point is `Model.using(...)`
+// (see BaseModel.ts) — this module owns the types it is built from, and the fold
+// itself. Nothing here imports `BaseModel`: the fold seeds from its receiver, so
+// this is a leaf module.
+//
+// `Model.using(...)` composes any number of model mixins, so packages can ship
+// reusable model behaviour (auth contract, roles, permissions, soft deletes, …)
+// that apps stack without "wrapper hell":
 //
 //   // before — nested, base repeated, order reads inside-out
 //   class User extends Roles(Permissions(AuthUser)) {}
 //
 //   // after — flat, left-to-right, base baked in
-//   class User extends BaseModelWith(Authenticatable, Permissions, Roles) {}
+//   class User extends Model.using(Authenticatable, Permissions, Roles) {}
 //
 // A mixin is the canonical generic form `(<T>(Base: T) => class extends Base { … })`.
-// Because each one returns `class extends Base`, BaseModel's full static surface
+// Because each one returns `class extends Base`, the base's full static surface
 // (`User.query()`, `find()`, `create()`, scopes, …) and every mixin's instance
 // members flow through to the final class — fully type-checked.
 
-import { BaseModel } from "./BaseModel.ts";
-
 /** A concrete class constructor. */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any -- generic mixin base bound
 export type Constructor<T = object> = new (...args: any[]) => T;
@@ -32,505 +35,127 @@ export type Mixin<TIn extends Constructor = Constructor, TOut extends Constructo
   Base: TIn,
 ) => TOut;
 
-type Base = typeof BaseModel;
-
-// Typed overloads (1–8 mixins) thread the accumulated type through each step so the
-// result is `BaseModel`'s statics + every mixin's members. Need more? Nest a
-// `BaseModelWith(...)` call or add another overload.
-
 /**
- * Compose any number of model {@link Mixin | mixins} on top of {@link BaseModel},
- * folding them left-to-right so the resulting class carries `BaseModel`'s full
- * static surface (`query()`, `find()`, `create()`, scopes, …) plus every mixin's
- * instance and static members — all fully type-checked.
- *
- * Prefer this over hand-nesting mixins (`Roles(Permissions(AuthUser))`), which
- * reads inside-out and repeats the base. Each overload (1–20 mixins) threads the
- * accumulated type through every step; for more, nest a second `BaseModelWith(...)`.
+ * The call signatures behind `Model.using(...)`.
  *
- * @param mixins - Mixin factories applied in order; each receives the class the
- *   previous one produced.
- * @returns A model class extending `BaseModel` with every mixin applied.
+ * Each overload threads the accumulated type through every step, so the composed class carries
+ * the base's full static surface plus every mixin's instance and static members — fully
+ * type-checked. The `this: TBase` parameter is what makes the base polymorphic: `using` composes
+ * onto whatever class it is called on, not onto a hardcoded `BaseModel`.
  *
- * @example
- * ```ts
- * class User extends BaseModelWith(Authenticatable, Permissions, Roles) {}
- * ```
+ * Overloads cover 1–8 mixins. There is no ceiling: the composed class carries `using` too, so
+ * `Model.using(a, b).using(c, d)` chains.
  */
-export function BaseModelWith<A extends Constructor>(a: (base: Base) => A): A;
-export function BaseModelWith<A extends Constructor, B extends Constructor>(
-  a: (base: Base) => A,
-  b: (base: A) => B,
-): B;
-export function BaseModelWith<A extends Constructor, B extends Constructor, C extends Constructor>(
-  a: (base: Base) => A,
-  b: (base: A) => B,
-  c: (base: B) => C,
-): C;
-export function BaseModelWith<
-  A extends Constructor,
-  B extends Constructor,
-  C extends Constructor,
-  D extends Constructor,
->(a: (base: Base) => A, b: (base: A) => B, c: (base: B) => C, d: (base: C) => D): D;
-export function BaseModelWith<
-  A extends Constructor,
-  B extends Constructor,
-  C extends Constructor,
-  D extends Constructor,
-  E extends Constructor,
->(
-  a: (base: Base) => A,
-  b: (base: A) => B,
-  c: (base: B) => C,
-  d: (base: C) => D,
-  e: (base: D) => E,
-): E;
-export function BaseModelWith<
-  A extends Constructor,
-  B extends Constructor,
-  C extends Constructor,
-  D extends Constructor,
-  E extends Constructor,
-  F extends Constructor,
->(
-  a: (base: Base) => A,
-  b: (base: A) => B,
-  c: (base: B) => C,
-  d: (base: C) => D,
-  e: (base: D) => E,
-  f: (base: E) => F,
-): F;
-export function BaseModelWith<
-  A extends Constructor,
-  B extends Constructor,
-  C extends Constructor,
-  D extends Constructor,
-  E extends Constructor,
-  F extends Constructor,
-  G extends Constructor,
->(
-  a: (base: Base) => A,
-  b: (base: A) => B,
-  c: (base: B) => C,
-  d: (base: C) => D,
-  e: (base: D) => E,
-  f: (base: E) => F,
-  g: (base: F) => G,
-): G;
-export function BaseModelWith<
-  A extends Constructor,
-  B extends Constructor,
-  C extends Constructor,
-  D extends Constructor,
-  E extends Constructor,
-  F extends Constructor,
-  G extends Constructor,
-  H extends Constructor,
->(
-  a: (base: Base) => A,
-  b: (base: A) => B,
-  c: (base: B) => C,
-  d: (base: C) => D,
-  e: (base: D) => E,
-  f: (base: E) => F,
-  g: (base: F) => G,
-  h: (base: G) => H,
-): H;
-export function BaseModelWith<
-  A extends Constructor,
-  B extends Constructor,
-  C extends Constructor,
-  D extends Constructor,
-  E extends Constructor,
-  F extends Constructor,
-  G extends Constructor,
-  H extends Constructor,
-  I extends Constructor,
->(
-  a: (base: Base) => A,
-  b: (base: A) => B,
-  c: (base: B) => C,
-  d: (base: C) => D,
-  e: (base: D) => E,
-  f: (base: E) => F,
-  g: (base: F) => G,
-  h: (base: G) => H,
-  i: (base: H) => I,
-): I;
-export function BaseModelWith<
-  A extends Constructor,
-  B extends Constructor,
-  C extends Constructor,
-  D extends Constructor,
-  E extends Constructor,
-  F extends Constructor,
-  G extends Constructor,
-  H extends Constructor,
-  I extends Constructor,
-  J extends Constructor,
->(
-  a: (base: Base) => A,
-  b: (base: A) => B,
-  c: (base: B) => C,
-  d: (base: C) => D,
-  e: (base: D) => E,
-  f: (base: E) => F,
-  g: (base: F) => G,
-  h: (base: G) => H,
-  i: (base: H) => I,
-  j: (base: I) => J,
-): J;
-export function BaseModelWith<
-  A extends Constructor,
-  B extends Constructor,
-  C extends Constructor,
-  D extends Constructor,
-  E extends Constructor,
-  F extends Constructor,
-  G extends Constructor,
-  H extends Constructor,
-  I extends Constructor,
-  J extends Constructor,
-  K extends Constructor,
->(
-  a: (base: Base) => A,
-  b: (base: A) => B,
-  c: (base: B) => C,
-  d: (base: C) => D,
-  e: (base: D) => E,
-  f: (base: E) => F,
-  g: (base: F) => G,
-  h: (base: G) => H,
-  i: (base: H) => I,
-  j: (base: I) => J,
-  k: (base: J) => K,
-): K;
-export function BaseModelWith<
-  A extends Constructor,
-  B extends Constructor,
-  C extends Constructor,
-  D extends Constructor,
-  E extends Constructor,
-  F extends Constructor,
-  G extends Constructor,
-  H extends Constructor,
-  I extends Constructor,
-  J extends Constructor,
-  K extends Constructor,
-  L extends Constructor,
->(
-  a: (base: Base) => A,
-  b: (base: A) => B,
-  c: (base: B) => C,
-  d: (base: C) => D,
-  e: (base: D) => E,
-  f: (base: E) => F,
-  g: (base: F) => G,
-  h: (base: G) => H,
-  i: (base: H) => I,
-  j: (base: I) => J,
-  k: (base: J) => K,
-  l: (base: K) => L,
-): L;
-export function BaseModelWith<
-  A extends Constructor,
-  B extends Constructor,
-  C extends Constructor,
-  D extends Constructor,
-  E extends Constructor,
-  F extends Constructor,
-  G extends Constructor,
-  H extends Constructor,
-  I extends Constructor,
-  J extends Constructor,
-  K extends Constructor,
-  L extends Constructor,
-  M extends Constructor,
->(
-  a: (base: Base) => A,
-  b: (base: A) => B,
-  c: (base: B) => C,
-  d: (base: C) => D,
-  e: (base: D) => E,
-  f: (base: E) => F,
-  g: (base: F) => G,
-  h: (base: G) => H,
-  i: (base: H) => I,
-  j: (base: I) => J,
-  k: (base: J) => K,
-  l: (base: K) => L,
-  m: (base: L) => M,
-): M;
-export function BaseModelWith<
-  A extends Constructor,
-  B extends Constructor,
-  C extends Constructor,
-  D extends Constructor,
-  E extends Constructor,
-  F extends Constructor,
-  G extends Constructor,
-  H extends Constructor,
-  I extends Constructor,
-  J extends Constructor,
-  K extends Constructor,
-  L extends Constructor,
-  M extends Constructor,
-  N extends Constructor,
->(
-  a: (base: Base) => A,
-  b: (base: A) => B,
-  c: (base: B) => C,
-  d: (base: C) => D,
-  e: (base: D) => E,
-  f: (base: E) => F,
-  g: (base: F) => G,
-  h: (base: G) => H,
-  i: (base: H) => I,
-  j: (base: I) => J,
-  k: (base: J) => K,
-  l: (base: K) => L,
-  m: (base: L) => M,
-  n: (base: M) => N,
-): N;
-export function BaseModelWith<
-  A extends Constructor,
-  B extends Constructor,
-  C extends Constructor,
-  D extends Constructor,
-  E extends Constructor,
-  F extends Constructor,
-  G extends Constructor,
-  H extends Constructor,
-  I extends Constructor,
-  J extends Constructor,
-  K extends Constructor,
-  L extends Constructor,
-  M extends Constructor,
-  N extends Constructor,
-  O extends Constructor,
->(
-  a: (base: Base) => A,
-  b: (base: A) => B,
-  c: (base: B) => C,
-  d: (base: C) => D,
-  e: (base: D) => E,
-  f: (base: E) => F,
-  g: (base: F) => G,
-  h: (base: G) => H,
-  i: (base: H) => I,
-  j: (base: I) => J,
-  k: (base: J) => K,
-  l: (base: K) => L,
-  m: (base: L) => M,
-  n: (base: M) => N,
-  o: (base: N) => O,
-): O;
-export function BaseModelWith<
-  A extends Constructor,
-  B extends Constructor,
-  C extends Constructor,
-  D extends Constructor,
-  E extends Constructor,
-  F extends Constructor,
-  G extends Constructor,
-  H extends Constructor,
-  I extends Constructor,
-  J extends Constructor,
-  K extends Constructor,
-  L extends Constructor,
-  M extends Constructor,
-  N extends Constructor,
-  O extends Constructor,
-  P extends Constructor,
->(
-  a: (base: Base) => A,
-  b: (base: A) => B,
-  c: (base: B) => C,
-  d: (base: C) => D,
-  e: (base: D) => E,
-  f: (base: E) => F,
-  g: (base: F) => G,
-  h: (base: G) => H,
-  i: (base: H) => I,
-  j: (base: I) => J,
-  k: (base: J) => K,
-  l: (base: K) => L,
-  m: (base: L) => M,
-  n: (base: M) => N,
-  o: (base: N) => O,
-  p: (base: O) => P,
-): P;
-export function BaseModelWith<
-  A extends Constructor,
-  B extends Constructor,
-  C extends Constructor,
-  D extends Constructor,
-  E extends Constructor,
-  F extends Constructor,
-  G extends Constructor,
-  H extends Constructor,
-  I extends Constructor,
-  J extends Constructor,
-  K extends Constructor,
-  L extends Constructor,
-  M extends Constructor,
-  N extends Constructor,
-  O extends Constructor,
-  P extends Constructor,
-  Q extends Constructor,
->(
-  a: (base: Base) => A,
-  b: (base: A) => B,
-  c: (base: B) => C,
-  d: (base: C) => D,
-  e: (base: D) => E,
-  f: (base: E) => F,
-  g: (base: F) => G,
-  h: (base: G) => H,
-  i: (base: H) => I,
-  j: (base: I) => J,
-  k: (base: J) => K,
-  l: (base: K) => L,
-  m: (base: L) => M,
-  n: (base: M) => N,
-  o: (base: N) => O,
-  p: (base: O) => P,
-  q: (base: P) => Q,
-): Q;
-export function BaseModelWith<
-  A extends Constructor,
-  B extends Constructor,
-  C extends Constructor,
-  D extends Constructor,
-  E extends Constructor,
-  F extends Constructor,
-  G extends Constructor,
-  H extends Constructor,
-  I extends Constructor,
-  J extends Constructor,
-  K extends Constructor,
-  L extends Constructor,
-  M extends Constructor,
-  N extends Constructor,
-  O extends Constructor,
-  P extends Constructor,
-  Q extends Constructor,
-  R extends Constructor,
->(
-  a: (base: Base) => A,
-  b: (base: A) => B,
-  c: (base: B) => C,
-  d: (base: C) => D,
-  e: (base: D) => E,
-  f: (base: E) => F,
-  g: (base: F) => G,
-  h: (base: G) => H,
-  i: (base: H) => I,
-  j: (base: I) => J,
-  k: (base: J) => K,
-  l: (base: K) => L,
-  m: (base: L) => M,
-  n: (base: M) => N,
-  o: (base: N) => O,
-  p: (base: O) => P,
-  q: (base: P) => Q,
-  r: (base: Q) => R,
-): R;
-export function BaseModelWith<
-  A extends Constructor,
-  B extends Constructor,
-  C extends Constructor,
-  D extends Constructor,
-  E extends Constructor,
-  F extends Constructor,
-  G extends Constructor,
-  H extends Constructor,
-  I extends Constructor,
-  J extends Constructor,
-  K extends Constructor,
-  L extends Constructor,
-  M extends Constructor,
-  N extends Constructor,
-  O extends Constructor,
-  P extends Constructor,
-  Q extends Constructor,
-  R extends Constructor,
-  S extends Constructor,
->(
-  a: (base: Base) => A,
-  b: (base: A) => B,
-  c: (base: B) => C,
-  d: (base: C) => D,
-  e: (base: D) => E,
-  f: (base: E) => F,
-  g: (base: F) => G,
-  h: (base: G) => H,
-  i: (base: H) => I,
-  j: (base: I) => J,
-  k: (base: J) => K,
-  l: (base: K) => L,
-  m: (base: L) => M,
-  n: (base: M) => N,
-  o: (base: N) => O,
-  p: (base: O) => P,
-  q: (base: P) => Q,
-  r: (base: Q) => R,
-  s: (base: R) => S,
-): S;
-export function BaseModelWith<
-  A extends Constructor,
-  B extends Constructor,
-  C extends Constructor,
-  D extends Constructor,
-  E extends Constructor,
-  F extends Constructor,
-  G extends Constructor,
-  H extends Constructor,
-  I extends Constructor,
-  J extends Constructor,
-  K extends Constructor,
-  L extends Constructor,
-  M extends Constructor,
-  N extends Constructor,
-  O extends Constructor,
-  P extends Constructor,
-  Q extends Constructor,
-  R extends Constructor,
-  S extends Constructor,
-  T extends Constructor,
->(
-  a: (base: Base) => A,
-  b: (base: A) => B,
-  c: (base: B) => C,
-  d: (base: C) => D,
-  e: (base: D) => E,
-  f: (base: E) => F,
-  g: (base: F) => G,
-  h: (base: G) => H,
-  i: (base: H) => I,
-  j: (base: I) => J,
-  k: (base: J) => K,
-  l: (base: K) => L,
-  m: (base: L) => M,
-  n: (base: M) => N,
-  o: (base: N) => O,
-  p: (base: O) => P,
-  q: (base: P) => Q,
-  r: (base: Q) => R,
-  s: (base: R) => S,
-  t: (base: S) => T,
-): T;
+export interface Compose {
+  <TBase extends Constructor, A extends Constructor>(this: TBase, a: (base: TBase) => A): A;
+  <TBase extends Constructor, A extends Constructor, B extends Constructor>(
+    this: TBase,
+    a: (base: TBase) => A,
+    b: (base: A) => B,
+  ): B;
+  <TBase extends Constructor, A extends Constructor, B extends Constructor, C extends Constructor>(
+    this: TBase,
+    a: (base: TBase) => A,
+    b: (base: A) => B,
+    c: (base: B) => C,
+  ): C;
+  <
+    TBase extends Constructor,
+    A extends Constructor,
+    B extends Constructor,
+    C extends Constructor,
+    D extends Constructor,
+  >(
+    this: TBase,
+    a: (base: TBase) => A,
+    b: (base: A) => B,
+    c: (base: B) => C,
+    d: (base: C) => D,
+  ): D;
+  <
+    TBase extends Constructor,
+    A extends Constructor,
+    B extends Constructor,
+    C extends Constructor,
+    D extends Constructor,
+    E extends Constructor,
+  >(
+    this: TBase,
+    a: (base: TBase) => A,
+    b: (base: A) => B,
+    c: (base: B) => C,
+    d: (base: C) => D,
+    e: (base: D) => E,
+  ): E;
+  <
+    TBase extends Constructor,
+    A extends Constructor,
+    B extends Constructor,
+    C extends Constructor,
+    D extends Constructor,
+    E extends Constructor,
+    F extends Constructor,
+  >(
+    this: TBase,
+    a: (base: TBase) => A,
+    b: (base: A) => B,
+    c: (base: B) => C,
+    d: (base: C) => D,
+    e: (base: D) => E,
+    f: (base: E) => F,
+  ): F;
+  <
+    TBase extends Constructor,
+    A extends Constructor,
+    B extends Constructor,
+    C extends Constructor,
+    D extends Constructor,
+    E extends Constructor,
+    F extends Constructor,
+    G extends Constructor,
+  >(
+    this: TBase,
+    a: (base: TBase) => A,
+    b: (base: A) => B,
+    c: (base: B) => C,
+    d: (base: C) => D,
+    e: (base: D) => E,
+    f: (base: E) => F,
+    g: (base: F) => G,
+  ): G;
+  <
+    TBase extends Constructor,
+    A extends Constructor,
+    B extends Constructor,
+    C extends Constructor,
+    D extends Constructor,
+    E extends Constructor,
+    F extends Constructor,
+    G extends Constructor,
+    H extends Constructor,
+  >(
+    this: TBase,
+    a: (base: TBase) => A,
+    b: (base: A) => B,
+    c: (base: B) => C,
+    d: (base: C) => D,
+    e: (base: D) => E,
+    f: (base: E) => F,
+    g: (base: F) => G,
+    h: (base: G) => H,
+  ): H;
+}
 
-// Implementation: fold the mixins over BaseModel, left to right. The base param is
-// `any` so each typed overload above (whose base is the narrower `typeof BaseModel`
-// or a prior mixin's result) stays assignable to this implementation signature.
-export function BaseModelWith(
+/**
+ * The fold behind {@link Compose}: apply each mixin left-to-right, seeding from `this` (the
+ * class `using` was called on). Assigned to `BaseModel.using` — not exported publicly.
+ *
+ * @internal
+ */
+export const _compose = function (
+  this: Constructor,
   // eslint-disable-next-line @typescript-eslint/no-explicit-any -- variadic mixin folder
   ...mixins: Array<(base: any) => Constructor>
 ): Constructor {
-  return mixins.reduce<Constructor>(
-    (acc, mixin) => mixin(acc),
-    BaseModel as unknown as Constructor,
-  );
-}
+  return mixins.reduce<Constructor>((acc, mixin) => mixin(acc), this);
+} as Compose;

package/src/model/payload.ts

@@ -92,6 +92,36 @@ type ColumnKeys<T> = WritableKeys<T> &
  */
 export type InsertPayload<T> = Omit<Pick<T, ColumnKeys<T>>, AutoManagedKeys>;
 
+/**
+ * The insert payload narrowed to a model's mass-assignable columns.
+ *
+ * `create()` funnels into `fill()`, which throws {@link MassAssignmentError} for any key
+ * outside `fillable`. Without this narrowing the type demands fields the runtime forbids:
+ * a non-optional column deliberately kept out of `fillable` — a compliance flag that must
+ * never come from a request body — is *required* by `InsertPayload`, and supplying it
+ * throws. There was no way to satisfy both.
+ *
+ * `Fillable` is inferred from the model's `static fillable`. Declare it `as const` (or as
+ * a literal tuple) and the payload becomes exactly the assignable columns: the flag is no
+ * longer required, and passing it is a compile error rather than a runtime one. When
+ * `fillable` is absent or widened to `string[]`, `Fillable` is `string` and the payload is
+ * the unnarrowed {@link InsertPayload}, so existing models are unaffected.
+ *
+ * @example
+ * class Customer extends BaseModel {
+ *   static fillable = ['name', 'email'] as const;
+ *   @column() name!: string;
+ *   @column() email!: string;
+ *   @column({ type: 'boolean', cast: 'boolean', default: false }) legalHold!: boolean;
+ * }
+ *
+ * await Customer.create({ name: 'Ada', email: 'ada@example.com' }); // ok — legalHold not required
+ * await Customer.create({ name: 'Ada', email: 'a@b.c', legalHold: true }); // compile error
+ */
+export type FillablePayload<T, Fillable extends string> = string extends Fillable
+  ? InsertPayload<T>
+  : Pick<InsertPayload<T>, Extract<keyof InsertPayload<T>, Fillable>>;
+
 /**
  * Data shape accepted when updating an existing record.
  * Every field is optional — pass only what should change.