Model unstable

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 Since v4.0.0 Source

Constructors

Override

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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 unstable

Since v4.0.0

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 unstable

Since v4.0.0

Database-facing variant names generated for model schemas.

Signature

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

VariantsJson

type unstable

Since v4.0.0

JSON API-facing variant names generated for model schemas.

Signature

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

Other

Class

unstable

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

unstable

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

unstable

Signature

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

fieldEvolve

unstable

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

unstable

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

unstable

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

unstable

Signature

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

Union

unstable

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

unstable

Since v4.0.0

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 unstable

Since v4.0.0

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

unstable

Since v4.0.0

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 unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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 unstable

Since v4.0.0

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

unstable

Since v4.0.0

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 unstable

Since v4.0.0

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

unstable

Since v4.0.0

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 unstable

Since v4.0.0

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

unstable

Since v4.0.0

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 unstable

Since v4.0.0

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

unstable

Since v4.0.0

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 unstable

Since v4.0.0

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

unstable

Since v4.0.0

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 unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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 unstable

Since v4.0.0

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

unstable

Since v4.0.0

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 unstable

Since v4.0.0

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

unstable

Since v4.0.0

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 unstable

Since v4.0.0

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

unstable

Since v4.0.0

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 unstable

Since v4.0.0

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

unstable

Since v4.0.0

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 unstable

Since v4.0.0

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

unstable

Since v4.0.0

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 unstable

Since v4.0.0

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

unstable

Since v4.0.0

Schema for binary Uint8Array values backed by an ArrayBuffer.

Signature

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

UuidV4BytesInsert

unstable

Since v4.0.0

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 unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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 unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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 unstable

Since v4.0.0

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

unstable

Since v4.0.0

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>>