Skip to content

Model

Defines schema-backed domain models with separate database and JSON shapes.

A model keeps one field declaration as the source of truth and derives variants for selecting, inserting, updating, and JSON encoding. This is useful when the database shape is not exactly the same as the public API shape, such as generated ids, audit timestamps, nullable columns, private fields, or values that need different encodings at different boundaries. Each generated variant is its own schema, so callers can validate or encode the shape that matches the operation they are performing.

55 exports Added in v4.0.0 Source

Constructors

Override

Added in v4.0.0 Source

Marks a value as an explicit override for fields that otherwise use an overrideable default.

Signature

declare const Override: <A>(value: A) => A & Brand<"Override">;

Getters

fields

Added in v4.0.0 Source

Returns the variant field definitions stored on a model or variant struct.

Signature

declare const fields: <A extends VariantSchema.Struct<any>>(
  self: A,
) => A[typeof VariantSchema.TypeId];

Models

Any type

Added in v4.0.0 Source

Base shape of a variant model schema, including its fields and the generated database and JSON variant schemas.

Signature

type Any = Schema.Top & {
  readonly fields: Schema.Struct.Fields;
  readonly insert: Schema.Top;
  readonly json: Schema.Top;
  readonly jsonCreate: Schema.Top;
  readonly jsonUpdate: Schema.Top;
  readonly update: Schema.Top;
};

VariantsDatabase type

Added in v4.0.0 Source

Database-facing variant names generated for model schemas.

Signature

type VariantsDatabase = "select" | "insert" | "update";

VariantsJson type

Added in v4.0.0 Source

JSON API-facing variant names generated for model schemas.

Signature

type VariantsJson = "json" | "jsonCreate" | "jsonUpdate";

Other

Class

Source

Signature

declare const Class: <Self = never>(
  identifier: string,
) => <Fields extends Fields>(
  fields: Fields &
    Validate<Fields, "json" | "select" | "insert" | "update" | "jsonCreate" | "jsonUpdate">,
  annotations?: Declaration<Self, readonly [Struct<ExtractFields<"select", Fields, true>>]>,
) => [Self] extends [never]
  ? "Missing `Self` generic - use `class Self extends Class<Self>()({ ... })`"
  : Class<Self, Fields, Struct<ExtractFields<"select", Fields, true>>> & {
      insert: Struct<{
        [K in string | number | symbol]: ExtractFields<"insert", Fields, false>[K];
      }>;
      json: Struct<{ [K in string | number | symbol]: ExtractFields<"json", Fields, false>[K] }>;
      jsonCreate: Struct<{
        [K in string | number | symbol]: ExtractFields<"jsonCreate", Fields, false>[K];
      }>;
      jsonUpdate: Struct<{
        [K in string | number | symbol]: ExtractFields<"jsonUpdate", Fields, false>[K];
      }>;
      select: Struct<{
        [K in string | number | symbol]: ExtractFields<"select", Fields, false>[K];
      }>;
      update: Struct<{
        [K in string | number | symbol]: ExtractFields<"update", Fields, false>[K];
      }>;
    };

extract

Source

Signature

declare const extract: {
  <V extends "json" | "select" | "insert" | "update" | "jsonCreate" | "jsonUpdate">(
    variant: V,
  ): <A extends Struct<any>>(self: A) => Extract<V, A, V extends "select" ? true : false>;
  <
    V extends "json" | "select" | "insert" | "update" | "jsonCreate" | "jsonUpdate",
    A extends Struct<any>,
  >(
    self: A,
    variant: V,
  ): Extract<V, A, V extends "select" ? true : false>;
};

Field

Source

Signature

declare const Field: <
  A extends ConfigWithKeys<"json" | "select" | "insert" | "update" | "jsonCreate" | "jsonUpdate">,
>(
  config: A & { [K in string | number | symbol]: never },
) => Field<A>;

fieldEvolve

Source

Signature

declare const fieldEvolve: {
  <
    Self extends Top | Field<any>,
    Mapping extends
      | {
          [key: string]: (variant: any) => Top | undefined;
        }
      | {
          insert?: (variant: Top) => Top;
          json?: (variant: Top) => Top;
          jsonCreate?: (variant: Top) => Top;
          jsonUpdate?: (variant: Top) => Top;
          select?: (variant: Top) => Top;
          update?: (variant: Top) => Top;
        },
  >(
    f: Mapping,
  ): (self: Self) => Field<
    Self extends Field<S>
      ? {
          [K in string | number | symbol]: K extends keyof Mapping
            ? Mapping[K] extends (arg: any) => any
              ? ReturnType<any[any]>
              : S[K]
            : S[K];
        }
      : {
          insert: "insert" extends keyof Mapping
            ? Mapping[keyof Mapping & "insert"] extends (arg: any) => any
              ? ReturnType<any[any]>
              : Self
            : Self;
          json: "json" extends keyof Mapping
            ? Mapping[keyof Mapping & "json"] extends (arg: any) => any
              ? ReturnType<any[any]>
              : Self
            : Self;
          jsonCreate: "jsonCreate" extends keyof Mapping
            ? Mapping[keyof Mapping & "jsonCreate"] extends (arg: any) => any
              ? ReturnType<any[any]>
              : Self
            : Self;
          jsonUpdate: "jsonUpdate" extends keyof Mapping
            ? Mapping[keyof Mapping & "jsonUpdate"] extends (arg: any) => any
              ? ReturnType<any[any]>
              : Self
            : Self;
          select: "select" extends keyof Mapping
            ? Mapping[keyof Mapping & "select"] extends (arg: any) => any
              ? ReturnType<any[any]>
              : Self
            : Self;
          update: "update" extends keyof Mapping
            ? Mapping[keyof Mapping & "update"] extends (arg: any) => any
              ? ReturnType<any[any]>
              : Self
            : Self;
        }
  >;
  <
    Self extends Top | Field<any>,
    Mapping extends
      | {
          [key: string]: (variant: any) => Top | undefined;
        }
      | {
          insert?: (variant: Top) => Top;
          json?: (variant: Top) => Top;
          jsonCreate?: (variant: Top) => Top;
          jsonUpdate?: (variant: Top) => Top;
          select?: (variant: Top) => Top;
          update?: (variant: Top) => Top;
        },
  >(
    self: Self,
    f: Mapping,
  ): Field<
    Self extends Field<S>
      ? {
          [K in string | number | symbol]: K extends keyof Mapping
            ? Mapping[K] extends (arg: any) => any
              ? ReturnType<any[any]>
              : S[K]
            : S[K];
        }
      : {
          insert: "insert" extends keyof Mapping
            ? Mapping[keyof Mapping & "insert"] extends (arg: any) => any
              ? ReturnType<any[any]>
              : Self
            : Self;
          json: "json" extends keyof Mapping
            ? Mapping[keyof Mapping & "json"] extends (arg: any) => any
              ? ReturnType<any[any]>
              : Self
            : Self;
          jsonCreate: "jsonCreate" extends keyof Mapping
            ? Mapping[keyof Mapping & "jsonCreate"] extends (arg: any) => any
              ? ReturnType<any[any]>
              : Self
            : Self;
          jsonUpdate: "jsonUpdate" extends keyof Mapping
            ? Mapping[keyof Mapping & "jsonUpdate"] extends (arg: any) => any
              ? ReturnType<any[any]>
              : Self
            : Self;
          select: "select" extends keyof Mapping
            ? Mapping[keyof Mapping & "select"] extends (arg: any) => any
              ? ReturnType<any[any]>
              : Self
            : Self;
          update: "update" extends keyof Mapping
            ? Mapping[keyof Mapping & "update"] extends (arg: any) => any
              ? ReturnType<any[any]>
              : Self
            : Self;
        }
  >;
};

FieldExcept

Source

Signature

declare const FieldExcept: <Keys extends readonly Array<"json" | "select" | "insert" | "update" | "jsonCreate" | "jsonUpdate">>(keys: Keys) => <S extends Top>(schema: S) => Field<{ [K in "json" | "select" | "insert" | "update" | "jsonCreate" | "jsonUpdate"]: S }>

FieldOnly

Source

Signature

declare const FieldOnly: <Keys extends readonly Array<"json" | "select" | "insert" | "update" | "jsonCreate" | "jsonUpdate">>(keys: Keys) => <S extends Top>(schema: S) => Field<{ [K in "json" | "select" | "insert" | "update" | "jsonCreate" | "jsonUpdate"]: S }>

Struct

Source

Signature

declare const Struct: <A extends Fields>(
  fields: A & Validate<A, "json" | "select" | "insert" | "update" | "jsonCreate" | "jsonUpdate">,
) => Struct<A>;

Union

Source

Signature

declare const Union: <Members extends readonly Array<Struct<any>>>(members: Members) => Union<Members, "select"> & Variants<Members, "json" | "select" | "insert" | "update" | "jsonCreate" | "jsonUpdate">

Schemas

BooleanSqlite

Added in v4.0.0 Source

Schema for sqlite booleans that are represented as 0 | 1 in database variants and boolean in JSON variants.

Signature

declare const BooleanSqlite: BooleanSqlite;

BooleanSqlite interface

Added in v4.0.0 Source

Variant field type for SQLite booleans stored as 0 | 1 in database variants and exposed as boolean in JSON variants.

Signature

interface BooleanSqlite extends Field<{
  readonly insert: Schema.BooleanFromBit;
  readonly json: Schema.Boolean;
  readonly jsonCreate: Schema.Boolean;
  readonly jsonUpdate: Schema.Boolean;
  readonly select: Schema.BooleanFromBit;
  readonly update: Schema.BooleanFromBit;
}> {}

Date

Added in v4.0.0 Source

Schema for a DateTime.Utc that is serialized as a date string in the format YYYY-MM-DD.

Signature

declare const Date: Date;

Date interface

Added in v4.0.0 Source

Schema type for a DateTime.Utc date-only value encoded as a YYYY-MM-DD string.

Signature

interface Date extends decodeTo<Schema.instanceOf<DateTime.Utc>, Schema.String> {
  constructor(_: never);
}

DateTimeFromDateWithNow

Added in v4.0.0 Source

Schema for an overrideable UTC date-time field encoded as a JavaScript Date and defaulted to the current DateTime.Utc.

Signature

declare const DateTimeFromDateWithNow: Overrideable<DateTimeUtcFromDate>;

DateTimeFromNumberWithNow

Added in v4.0.0 Source

Schema for an overrideable UTC date-time field encoded as milliseconds and defaulted to the current DateTime.Utc.

Signature

declare const DateTimeFromNumberWithNow: Overrideable<DateTimeUtcFromMillis>;

DateTimeInsert

Added in v4.0.0 Source

A field that represents a date-time value that is inserted as the current DateTime.Utc. It is serialized as a string for the database.

Details

It is omitted from updates and is available for selection.

Signature

declare const DateTimeInsert: DateTimeInsert;

DateTimeInsert interface

Added in v4.0.0 Source

Variant field type for a UTC date-time stored as a string, defaulted to the current time on insert, available for selection, and omitted from updates.

Signature

interface DateTimeInsert extends Field<{
  readonly insert: VariantSchema.Overrideable<Schema.DateTimeUtcFromString>;
  readonly json: Schema.DateTimeUtcFromString;
  readonly select: Schema.DateTimeUtcFromString;
}> {}

DateTimeInsertFromDate

Added in v4.0.0 Source

A field that represents a date-time value that is inserted as the current DateTime.Utc. It is serialized as a Date for the database.

Details

It is omitted from updates and is available for selection.

Signature

declare const DateTimeInsertFromDate: DateTimeInsertFromDate;

DateTimeInsertFromDate interface

Added in v4.0.0 Source

Variant field type for a UTC date-time stored as a JavaScript Date in database variants, encoded as a string for JSON, and defaulted on insert.

Signature

interface DateTimeInsertFromDate extends Field<{
  readonly insert: VariantSchema.Overrideable<Schema.DateTimeUtcFromDate>;
  readonly json: Schema.DateTimeUtcFromString;
  readonly select: Schema.DateTimeUtcFromDate;
}> {}

DateTimeInsertFromNumber

Added in v4.0.0 Source

A field that represents a date-time value that is inserted as the current DateTime.Utc. It is serialized as a number.

Details

It is omitted from updates and is available for selection.

Signature

declare const DateTimeInsertFromNumber: DateTimeInsertFromNumber;

DateTimeInsertFromNumber interface

Added in v4.0.0 Source

Variant field type for a UTC date-time encoded as milliseconds and defaulted to the current time on insert.

Signature

interface DateTimeInsertFromNumber extends Field<{
  readonly insert: VariantSchema.Overrideable<Schema.DateTimeUtcFromMillis>;
  readonly json: Schema.DateTimeUtcFromMillis;
  readonly select: Schema.DateTimeUtcFromMillis;
}> {}

DateTimeUpdate

Added in v4.0.0 Source

A field that represents a date-time value that is updated as the current DateTime.Utc. It is serialized as a string for the database.

Details

It is set to the current DateTime.Utc on updates and inserts and is available for selection.

Signature

declare const DateTimeUpdate: DateTimeUpdate;

DateTimeUpdate interface

Added in v4.0.0 Source

Variant field type for a UTC date-time stored as a string and defaulted to the current time on both inserts and updates.

Signature

interface DateTimeUpdate extends Field<{
  readonly insert: VariantSchema.Overrideable<Schema.DateTimeUtcFromString>;
  readonly json: Schema.DateTimeUtcFromString;
  readonly select: Schema.DateTimeUtcFromString;
  readonly update: VariantSchema.Overrideable<Schema.DateTimeUtcFromString>;
}> {}

DateTimeUpdateFromDate

Added in v4.0.0 Source

A field that represents a date-time value that is updated as the current DateTime.Utc. It is serialized as a Date for the database.

Details

It is set to the current DateTime.Utc on updates and inserts and is available for selection.

Signature

declare const DateTimeUpdateFromDate: DateTimeUpdateFromDate;

DateTimeUpdateFromDate interface

Added in v4.0.0 Source

Variant field type for a UTC date-time stored as a JavaScript Date in database variants, encoded as a string for JSON, and defaulted on inserts and updates.

Signature

interface DateTimeUpdateFromDate extends Field<{
  readonly insert: VariantSchema.Overrideable<Schema.DateTimeUtcFromDate>;
  readonly json: Schema.DateTimeUtcFromString;
  readonly select: Schema.DateTimeUtcFromDate;
  readonly update: VariantSchema.Overrideable<Schema.DateTimeUtcFromDate>;
}> {}

DateTimeUpdateFromNumber

Added in v4.0.0 Source

A field that represents a date-time value that is updated as the current DateTime.Utc. It is serialized as a number.

Details

It is set to the current DateTime.Utc on updates and inserts and is available for selection.

Signature

declare const DateTimeUpdateFromNumber: DateTimeUpdateFromNumber;

DateTimeUpdateFromNumber interface

Added in v4.0.0 Source

Variant field type for a UTC date-time encoded as milliseconds and defaulted to the current time on both inserts and updates.

Signature

interface DateTimeUpdateFromNumber extends Field<{
  readonly insert: VariantSchema.Overrideable<Schema.DateTimeUtcFromMillis>;
  readonly json: Schema.DateTimeUtcFromMillis;
  readonly select: Schema.DateTimeUtcFromMillis;
  readonly update: VariantSchema.Overrideable<Schema.DateTimeUtcFromMillis>;
}> {}

DateTimeWithNow

Added in v4.0.0 Source

Schema for an overrideable UTC date-time field encoded as a string and defaulted to the current DateTime.Utc.

Signature

declare const DateTimeWithNow: Overrideable<DateTimeUtcFromString>;

DateWithNow

Added in v4.0.0 Source

Schema for an overrideable UTC date-only field whose constructor default is the current date with the time component removed.

Signature

declare const DateWithNow: Overrideable<Date>;

FieldOption

Added in v4.0.0 Source

Converts a field to one that is optional for all variants.

Details

For the database variants, it will accept nullable values. For the JSON variants, it will also accept missing keys.

Signature

declare const FieldOption: <Field extends Top | Field<any>>(
  self: Field,
) => Field extends Top
  ? FieldOption<Field>
  : Field extends Field<S>
    ? Field<{
        [K in string | number | symbol]: S[K] extends Top
          ? K extends VariantsDatabase
            ? OptionFromNullOr<any[any]>
            : optionalOption<any[any]>
          : never;
      }>
    : never;

FieldOption interface

Added in v4.0.0 Source

Convert a field to one that is optional for all variants.

Details

For the database variants, it will accept nullable values. For the JSON variants, it will also accept missing keys.

Signature

interface FieldOption<S extends Schema.Top> extends Field<{
  readonly insert: Schema.OptionFromNullOr<S>;
  readonly json: optionalOption<S>;
  readonly jsonCreate: optionalOption<S>;
  readonly jsonUpdate: optionalOption<S>;
  readonly select: Schema.OptionFromNullOr<S>;
  readonly update: Schema.OptionFromNullOr<S>;
}> {}

GeneratedByApp

Added in v4.0.0 Source

A field that represents a value generated by the application and present in database variants and the read JSON variant, but omitted from JSON create and update variants.

Signature

declare const GeneratedByApp: <S extends Top>(schema: S) => GeneratedByApp<S>;

GeneratedByApp interface

Added in v4.0.0 Source

Variant field type for an application-generated value that is present in database variants and read JSON, but omitted from JSON create and update variants.

Signature

interface GeneratedByApp<S extends Schema.Top> extends Field<{
  readonly insert: S;
  readonly json: S;
  readonly select: S;
  readonly update: S;
}> {}

GeneratedByDb

Added in v4.0.0 Source

Creates a variant field for a database-generated column available in read variants only.

Details

The field is included in select and json, and omitted from insert, update, jsonCreate, and jsonUpdate.

See

  • Field for generated columns that need a custom variant set, such as primary keys used in update payloads.

Signature

declare const GeneratedByDb: <S extends Top>(schema: S) => GeneratedByDb<S>;

GeneratedByDb interface

Added in v4.0.0 Source

Variant field type for a database-generated column that is present in read variants only.

Details

The field is included in select and json, and omitted from insert, update, jsonCreate, and jsonUpdate.

See

  • Field for generated columns that need a custom variant set, such as primary keys used in update payloads.

Signature

interface GeneratedByDb<S extends Schema.Top> extends Field<{
  readonly json: S;
  readonly select: S;
}> {}

JsonFromString

Added in v4.0.0 Source

A field that represents a JSON value stored as text in the database.

Details

The "json" variants will use the object schema directly.

Signature

declare const JsonFromString: <S extends Top>(schema: S) => JsonFromString<S>;

JsonFromString interface

Added in v4.0.0 Source

Variant field type for a JSON value stored as text in database variants and exposed through the supplied schema in JSON variants.

Signature

interface JsonFromString<S extends Schema.Top> extends Field<{
  readonly insert: Schema.fromJsonString<S>;
  readonly json: S;
  readonly jsonCreate: S;
  readonly jsonUpdate: S;
  readonly select: Schema.fromJsonString<S>;
  readonly update: Schema.fromJsonString<S>;
}> {}

optionalOption

Added in v4.0.0 Source

Creates a schema for optional keys that decodes missing or null encoded values through Option and encodes Option values back to optional nullable keys.

Signature

declare const optionalOption: <S extends Constraint>(schema: S) => optionalOption<S>;

optionalOption interface

Added in v4.0.0 Source

Schema type for an optional object key whose encoded value may be missing or null and whose decoded value is an Option.

Signature

interface optionalOption<S extends Schema.Constraint> extends decodeTo<
  Schema.Option<Schema.toType<S>>,
  Schema.optionalKey<Schema.NullOr<S>>
> {
  constructor(_: never);
}

Sensitive

Added in v4.0.0 Source

A field that represents a sensitive value that should not be exposed in the JSON variants.

Signature

declare const Sensitive: <S extends Top>(schema: S) => Sensitive<S>;

Sensitive interface

Added in v4.0.0 Source

Variant field type for a sensitive value that is available to database variants and omitted from all JSON variants.

Signature

interface Sensitive<S extends Schema.Top> extends Field<{
  readonly insert: S;
  readonly select: S;
  readonly update: S;
}> {}

Uint8Array

Added in v4.0.0 Source

Schema for binary Uint8Array values backed by an ArrayBuffer.

Signature

declare const Uint8Array: Schema.instanceOf<Uint8Array<ArrayBuffer>>;

UuidV4BytesInsert

Added in v4.0.0 Source

A field that represents a binary UUID v4 that is generated on inserts.

Signature

declare const UuidV4BytesInsert: <B extends string>(
  schema: brand<instanceOf<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>, B>,
) => UuidV4BytesInsert<B>;

UuidV4BytesInsert interface

Added in v4.0.0 Source

Variant field type for a branded binary UUID v4 value whose insert variant generates a UUID by default.

Signature

interface UuidV4BytesInsert<B extends string> extends Field<{
  readonly insert: Schema.withConstructorDefault<
    Schema.brand<Schema.instanceOf<Uint8Array<ArrayBuffer>>, B>
  >;
  readonly json: Schema.brand<Schema.instanceOf<Uint8Array<ArrayBuffer>>, B>;
  readonly select: Schema.brand<Schema.instanceOf<Uint8Array<ArrayBuffer>>, B>;
  readonly update: Schema.brand<Schema.instanceOf<Uint8Array<ArrayBuffer>>, B>;
}> {}

UuidV4BytesWithGenerate

Added in v4.0.0 Source

Adds a constructor default that generates a binary UUID v4 for a branded Uint8Array schema.

Signature

declare function UuidV4BytesWithGenerate<B extends string>(
  schema: brand<instanceOf<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>, B>,
): withConstructorDefault<brand<instanceOf<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>, B>>;

UuidV4Insert

Added in v4.0.0 Source

A field that represents a string UUID v4 that is generated on inserts.

Signature

declare const UuidV4Insert: <B extends string>(schema: brand<String, B>) => UuidV4Insert<B>;

UuidV4Insert interface

Added in v4.0.0 Source

Variant field type for a branded string UUID v4 value whose insert variant generates a UUID by default.

Signature

interface UuidV4Insert<B extends string> extends Field<{
  readonly insert: Schema.withConstructorDefault<Schema.brand<Schema.String, B>>;
  readonly json: Schema.brand<Schema.String, B>;
  readonly select: Schema.brand<Schema.String, B>;
  readonly update: Schema.brand<Schema.String, B>;
}> {}

UuidV4WithGenerate

Added in v4.0.0 Source

Adds a constructor default that generates a string UUID v4.

Signature

declare function UuidV4WithGenerate<B extends string>(
  schema: brand<String, B>,
): withConstructorDefault<brand<String, B>>;

UuidV7Insert

Added in v4.0.0 Source

A field that represents a string UUID v7 that is generated on inserts.

Signature

declare const UuidV7Insert: <B extends string>(schema: brand<String, B>) => UuidV7Insert<B>;

UuidV7Insert interface

Added in v4.0.0 Source

Variant field type for a branded string UUID v7 value whose insert variant generates a UUID by default.

Signature

interface UuidV7Insert<B extends string> extends Field<{
  readonly insert: Schema.withConstructorDefault<Schema.brand<Schema.String, B>>;
  readonly json: Schema.brand<Schema.String, B>;
  readonly select: Schema.brand<Schema.String, B>;
  readonly update: Schema.brand<Schema.String, B>;
}> {}

UuidV7WithGenerate

Added in v4.0.0 Source

Adds a constructor default that generates a string UUID v7.

Signature

declare function UuidV7WithGenerate<B extends string>(
  schema: brand<String, B>,
): withConstructorDefault<brand<String, B>>;