Egon ORM

Appearance

egon-orm-workspace / egon-orm / FieldType

Interface: FieldType<TApp, TDb> ​

Defined in: core/src/contracts/type.ts:130

A type: the conversions between external input, application values and driver values for one kind of data. TApp is the value in application code; TDb is what the driver sends and receives.

Rules every implementation follows:

  • null and undefined never reach cast, fromDb, toDb or equal; the caller handles nullability.
  • cast never throws, whatever it is given; it returns { success: false } instead.
  • fromDb and toDb are on the hot path. When the driver already produces or accepts the application representation they must be the IDENTITY function itself, so that callers can skip the call with a reference check (type.fromDb !== IDENTITY).
  • A type is immutable and shared: it holds no per-value state.

The members are declared with method syntax on purpose: it makes a specific type such as FieldType<Date, string> assignable to AnyFieldType, which is how metadata stores types whose parameters are not known statically.

Example ​

ts
const upperString: FieldType<string, string> = {
  name: "upperString",
  db: { kind: "text" },
  cast: (input) =>
    typeof input === "string" ? { success: true, data: input.toUpperCase() } : { success: false },
  fromDb: IDENTITY,
  toDb: IDENTITY,
  equal: Object.is,
};

Type Parameters ​

TApp ​

TApp

TDb ​

TDb = unknown

Properties ​

db ​

ts
readonly db: DbType;

Defined in: core/src/contracts/type.ts:134

The logical column type; used for CAST, for migrations and by adapter type overrides.

name ​

ts
readonly name: string;

Defined in: core/src/contracts/type.ts:132

A stable name for error messages and adapter overrides: "string", "integer", "timestamp", …

Methods ​

cast() ​

ts
cast(input): CastResult<TApp>;

Defined in: core/src/contracts/type.ts:136

Converts untrusted external input (JSON, form data) to an application value. Used by changesets.

Parameters ​

input ​

unknown

Returns ​

CastResult<TApp>

equal() ​

ts
equal(a, b): boolean;

Defined in: core/src/contracts/type.ts:142

Whether two non-null application values are the same value. Drives change detection in changesets.

Parameters ​

a ​

TApp

b ​

TApp

Returns ​

boolean

fromDb() ​

ts
fromDb(value): TApp;

Defined in: core/src/contracts/type.ts:138

Converts a non-null driver value to an application value. Hot path: once per column per row.

Parameters ​

value ​

TDb

Returns ​

TApp

toDb() ​

ts
toDb(value): TDb;

Defined in: core/src/contracts/type.ts:140

Converts a non-null application value to a driver parameter.

Parameters ​

value ​

TApp

Returns ​

TDb