@genesislcap/mock-server 15.51.1 → 15.53.0

package/src/types.ts

@@ -4,6 +4,7 @@
 
 import type { IncomingMessage, ServerResponse } from 'node:http';
 import type { Store } from './db/store.ts';
+import type { NackErrorInput } from './protocol/errors.ts';
 
 export type Row = Record<string, any>;
 
@@ -14,6 +15,81 @@ export interface GenesisMessage {
   [key: string]: any;
 }
 
+// The Genesis dictionary field types (global.genesis.dictionary.Field.Type).
+export type GenesisFieldType =
+  | 'STRING'
+  | 'ENUM'
+  | 'INT'
+  | 'SHORT'
+  | 'LONG'
+  | 'DOUBLE'
+  | 'BIGDECIMAL'
+  | 'BOOLEAN'
+  | 'DATE'
+  | 'DATETIME'
+  | 'NANO_TIMESTAMP'
+  | 'RAW';
+
+// One column of a table, as the project's tables dictionary declares it
+// (`field("NAME", STRING(100)).notNull()`). META_REQUEST and
+// JSON_SCHEMA_REQUEST are built from these when a table declares them; see the
+// README's "Declared schema".
+export interface FieldDef {
+  name: string;
+  type: GenesisFieldType;
+  // Default true, as in the dictionary (`.notNull()` makes it false). Primary
+  // key and generated fields default to false.
+  nullable?: boolean;
+  // ENUM values, in dictionary order.
+  values?: string[];
+  // The dictionary `.default(...)`. A non-null field with a default is
+  // optional in event schemas.
+  default?: unknown;
+  // STRING column size (`STRING(100)`): MAX_LENGTH / maxLength.
+  maxSize?: number;
+  // `metadata { minLength = 0 }`: MIN_LENGTH / minLength.
+  minLength?: number;
+  // Replaces the DESCRIPTION / description the real server fills with the
+  // field's JVM class (kotlin.String, org.joda.time.DateTime, ...). Leave it
+  // unset for DATE/DATETIME: foundation-forms recognises dates partly by that
+  // class name.
+  description?: string;
+  // Defaults to the name in title case ('COUNTERPARTY_ID' -> 'Counterparty Id').
+  title?: string;
+  // Whether an event payload may leave it out (OPTIONAL, and not in the JSON
+  // schema's `required`). The real server makes a field optional only when
+  // its class property has a default. Unset: a table field is optional when
+  // it is nullable, generated or has a default (the generated DAO defaults
+  // all of those); a custom DTO field only when it has a `default` — set
+  // `optional: true` for a Kotlin default the metadata can't show, such as
+  // `val enabled: Boolean? = true`.
+  optional?: boolean;
+}
+
+// A field the database fills on insert when the record leaves it out (a
+// supplied value is kept). Metadata marks it NULLABLE:false, OPTIONAL:true
+// and leaves it out of `required`. A SEQUENCE mints values like the key's
+// sequence (`prefix`, else the table's sequencePrefix, in its
+// sequenceFormat); an AUTO_INCREMENT counts up from the highest seeded value
+// (1 when there is none). A table with `sequencePrefix` gets its key
+// generated as a SEQUENCE without declaring it here.
+export interface GeneratedFieldDef {
+  field: string;
+  kind: 'SEQUENCE' | 'AUTO_INCREMENT';
+  prefix?: string;
+}
+
+// The verbs of the generic CRUD events (see TableDef.events).
+export type CrudEventVerb = 'INSERT' | 'MODIFY' | 'DELETE';
+
+// A table or dataserver-query index (`indices { unique("A") }`). FIELDS is
+// sent space-separated (`'A B'`).
+export interface IndexDef {
+  name: string;
+  fields: string[];
+  unique?: boolean;
+}
+
 export interface TableDef {
   // A single field, or several for composite-keyed tables (e.g. PRICE keyed
   // by [RFQ_ID, SIDE]). Composite rows are identified by the fields' values
@@ -23,9 +99,40 @@ export interface TableDef {
   pkField: string | string[];
   sequencePrefix?: string;
   sequenceWidth?: number;
+  // How generated pk values look. See SequenceFormat.
+  sequenceFormat?: SequenceFormat;
   rows?: Row[];
+  // Declared columns, in dictionary order. When present they are the schema:
+  // metadata, JSON schemas and dataserver rows follow them (missing values go
+  // out as null), even with no rows at all. When absent, field metadata is
+  // inferred from the rows (src/db/metadata.ts).
+  fields?: FieldDef[];
+  generated?: GeneratedFieldDef[];
+  // Table indices. The generic CRUD events NACK DUPLICATE_KEY on a unique
+  // one, and a unique index over exactly the key fields names the primary
+  // key (else '<TABLE>_BY_<fields>'). A dataserver query only reports the
+  // indices on its own QueryDef.indexes, as the real dataserver does.
+  indexes?: IndexDef[];
+  // Registers generic CRUD event handlers for this table —
+  // EVENT_<TABLE>_INSERT, EVENT_<TABLE>_MODIFY, EVENT_<TABLE>_DELETE — the
+  // ones Genesis Create generates (entityDb.insert / modify / delete, no
+  // onValidate): insert the record (generating sequence and auto-increment
+  // fields, GENERATED listing them all; DUPLICATE_KEY on a taken key), modify
+  // or delete it by its primary key (RECORD_NOT_FOUND), ack VALIDATE without
+  // writing, push the change live. They are listed in RESOURCES and described
+  // by META_REQUEST / JSON_SCHEMA_REQUEST like any registered event. An
+  // eventHandlers entry of the same name wins. See the README's "Generic CRUD
+  // events".
+  events?: CrudEventVerb[];
 }
 
+// 'prefix' (the default): sequencePrefix + a counter padded to sequenceWidth
+// ('TR001'). 'genesis': the platform's id format (genesis-db IdStrategy.java)
+// — the counter padded to 15 digits, the sequence id (sequencePrefix, two
+// characters in a GSF dictionary), then location 'LO' and system '1':
+// '000000000000001TRLO1'.
+export type SequenceFormat = 'prefix' | 'genesis';
+
 export interface JoinDef {
   table: string;
   on: [string, string];
@@ -53,6 +160,16 @@ export interface ViewDef {
   joins?: JoinDef[];
   antiJoins?: AntiJoinDef[];
   derived?: Record<string, (row: Row) => any>;
+  // Types of the `derived` fields (`derivedField("TOTAL", DOUBLE)`): a type,
+  // or a full field definition without its name. Columns from the base table
+  // and from `joins[].select` take their declared types from their source
+  // tables; a derived field with no entry here is inferred from the rows.
+  derivedTypes?: Record<string, GenesisFieldType | Omit<FieldDef, 'name'>>;
+  // The view's fields { } block: the only columns it exposes, in this order
+  // (base, joined and derived alike). Unset: every base column, then each
+  // join's select, then the derived fields. Keep the key fields in it — they
+  // are the ROW_REF.
+  fields?: string[];
 }
 
 // The authenticated identity a resource-level auth hook sees. userName is
@@ -76,7 +193,17 @@ export interface ResourceAuthDef {
 
 export interface QueryDef {
   source: string;
+  // Overrides the TYPE of named fields, declared or inferred.
   fieldTypes?: Record<string, string>;
+  // The query's `fields { }` block: the only columns it exposes, in this
+  // order, in rows and in META_REQUEST. Names the source doesn't have are
+  // dropped from metadata. RECORD_ID and TIMESTAMP reach dataserver rows only
+  // when named here.
+
+  fields?: string[];
+  // The query's `indices { }` block, reported as META_REQUEST INDEXES. With
+  // none, INDEXES is the default [{NAME: null, FIELDS: 'RECORD_ID'}].
+  indexes?: IndexDef[];
   // Server-side where-clause equivalent, applied before any client
   // CRITERIA_MATCH — to both the DATA_LOGON snapshot and live pushes. Use it
   // for things the real query's filter/where clause does (e.g. keep template
@@ -100,22 +227,60 @@ export interface RequestReplyDef {
   // (`resolver`) — for request servers that calculate rather than read (date
   // calculations, holiday validate/roll, premium schedules, composite
   // lookups). A resolver receives the REQUEST fields and returns the REPLY
-  // rows verbatim; throw NackError for a protocol-correct error reply. When
-  // both are set, resolver wins. With resolver only, set `metadataRows` (a
-  // representative sample reply) or `fieldTypes` so META_REQUEST can still
-  // derive REPLY_FIELD metadata.
+  // rows verbatim; throw NackError for a protocol-correct error reply (a
+  // MSG_NACK). When both are set, resolver wins. With resolver only, set
+  // `metadataRows` (a representative sample reply) or `fieldTypes` so
+  // META_REQUEST can still derive REPLY_FIELD metadata.
   source?: string;
   resolver?: (ctx: RequestReplyResolverCtx) => Row[];
   metadataRows?: Row[];
   fieldTypes?: Record<string, string>;
+  // The request server's `filter { }` / `where { }` clause. With `filter` or
+  // `auth`, a criteria-only server reads past the rows they drop, and
+  // NEXT_OFFSET says where it stopped (README: Request servers).
   filter?: (row: Row) => boolean;
   auth?: ResourceAuthDef;
+  // `criteriaOnlyRequest = true` in the request server's config. REQUEST must
+  // then be present (an object; its fields are ignored), DETAILS.OFFSET pages,
+  // DETAILS.ORDER_BY sorts by fields, and every REP_ carries MORE_ROWS (plus
+  // NEXT_OFFSET while there are more). META_REQUEST reports REQUEST_FIELD: [],
+  // CRITERIA_ONLY_REQUEST: true, SORTABLE_FIELDS and CRITERIA_FIELDS. Without
+  // it, REQUEST's fields select rows (exact values, `*` wildcards,
+  // FIELD_FROM/FIELD_TO ranges; an array runs each) and OFFSET is ignored.
+  // See the README's "Request servers".
+  criteriaOnly?: boolean;
+  // The request block's fields (REQUEST_FIELD, and the JSON schema's REQUEST).
+  // Defaults to the source's primary key, as for a GPAL requestReply(TABLE).
+  requestFields?: string[];
+  // The reply block (`reply { }` in GPAL): REP_ rows carry exactly these
+  // columns, in this order, null when unset, and so do REPLY_FIELD and the JSON
+  // schema's REPLY. Names a declared source doesn't have are dropped.
+  // RECORD_ID and TIMESTAMP are sent only when named here. Unset: every column
+  // of the source followed by RECORD_ID and TIMESTAMP, as GSF sends a table
+  // entity. Ignored with a resolver.
+  fields?: string[];
+  // `config { maxRows = N }`: the most rows a REP_ carries when the request
+  // names no DETAILS.MAX_ROWS. Default 10000 (RequestReply.DEFAULT_MAXIMUM_ROWS).
+  rowLimit?: number;
 }
 
+// How META_REQUEST / JSON_SCHEMA_REQUEST describe an event whose name doesn't
+// follow EVENT_<TABLE>_<VERB>: the table (or view) its DETAILS take, and
+// whether only the key fields are sent (a delete).
 export interface EventSchemaOverride {
   table?: string;
   pkOnly?: boolean;
   fieldTypes?: Record<string, string>;
+  // The event's own DETAILS class, for an event that takes a custom DTO
+  // (`eventHandler<MyInput>`) rather than a table row. Described as the real
+  // server describes a non-table class: no titles, lengths, ranges or
+  // genesis types; `nullable`, `default` and `optional` as declared. A
+  // nullable field is still mandatory unless it has a default or
+  // `optional: true` (Kotlin `val x: T?` must be sent; `val x: T? = null`
+  // needn't be). `table` then only names where its ENUM columns come from.
+  fields?: FieldDef[];
+  // The DTO's class name, reported as the event's DESCRIPTION.
+  className?: string;
 }
 
 export interface ResourceItem {
@@ -179,9 +344,19 @@ export interface EventHandlerCtx {
   message: GenesisMessage;
   broadcast: BroadcastFn;
   broadcastTableChange: BroadcastTableChangeFn;
+  // `VALIDATE: true` on the message: the client asks whether the event would
+  // succeed. GSF then runs only the handler's onValidate and answers its NACK,
+  // or an EVENT_ACK with GENERATED: [] — nothing is written. A handler that
+  // writes should run its checks and return before writing when this is set;
+  // the generic CRUD events do.
+  validate: boolean;
 }
 
-export type EventHandlerResult = { generated?: Row[] } | void;
+// `warnings` turns the reply into an EVENT_NACK carrying them in WARNING
+// (with an empty ERROR), as a GSF handler's warning-only EventNack does.
+// Return them from a handler that has not written anything yet: the mock has
+// no transaction to roll back, and doesn't honour IGNORE_WARNINGS yet.
+export type EventHandlerResult = { generated?: Row[]; warnings?: NackErrorInput[] } | void;
 
 export type EventHandler = (details: Row, ctx: EventHandlerCtx) => EventHandlerResult;
 
@@ -245,11 +420,18 @@ export interface MockServerConfig {
   httpRoutes?: HttpRouteDef[];
   onMessage?: OnMessageHook;
   productName?: string;
+  // The Genesis application name, as in the generated enum classes the real
+  // server names in event metadata
+  // (global.genesis.gen.dao.enums.<appName>.<table>.<Field>). Unset: the
+  // segment is left out. Nothing a client does depends on it.
+  appName?: string;
 }
 
+// A META_REQUEST FIELD / REQUEST_FIELD / REPLY_FIELD entry.
 export interface FieldMetadata {
   NAME: string;
   TYPE: string;
+  VALID_VALUES?: string[];
 }
 
 // Minimal shape both `ws`'s WebSocket and Bun's ServerWebSocket satisfy —