@genesislcap/mock-server 15.51.1 → 15.52.0

package/src/db/schema.ts

@@ -0,0 +1,523 @@
+// The field schema of a table, view, query, request server or event: what
+// META_REQUEST and JSON_SCHEMA_REQUEST describe, and which columns a query's
+// rows carry. Declared fields (TableDef.fields) win; without them the fields
+// are inferred from the rows (metadata.ts), as before declared schemas
+// existed, so a config that declares nothing keeps working.
+
+import { isLegacyFidelity } from '../protocol/fidelity.ts';
+import { daoClassOf, titleCase } from '../protocol/fieldTypes.ts';
+import type {
+  FieldDef,
+  GenesisFieldType,
+  MockServerConfig,
+  QueryDef,
+  RequestReplyDef,
+  Row,
+  TableDef,
+  ViewDef,
+} from '../types.ts';
+import { deriveFields } from './metadata.ts';
+import type { Store } from './store.ts';
+
+export interface ResolvedField {
+  name: string;
+  // A GenesisFieldType, or whatever a fieldTypes override names.
+  type: string;
+  nullable: boolean;
+  // Filled in by the database on insert (sequence / auto-increment).
+  generated: boolean;
+  values?: string[];
+  // undefined: no default.
+  default?: unknown;
+  maxSize?: number;
+  minLength?: number;
+  description?: string;
+  title?: string;
+  // FieldDef.optional; for an event field, resolved by eventFields.
+  optional?: boolean;
+  // The table the column comes from (for a view, the joined table for a
+  // join's column), for generated enum class names.
+  table?: string;
+}
+
+export interface ResolvedSchema {
+  fields: ResolvedField[];
+  // True when the fields come from TableDef.fields rather than from rows.
+  declared: boolean;
+}
+
+function pkFieldsOf(def: TableDef): string[] {
+  return Array.isArray(def.pkField) ? def.pkField : [def.pkField];
+}
+
+// The declared generated fields, plus the key of a table that mints its own
+// keys through sequencePrefix.
+export function generatedFieldsOf(def: TableDef): Set<string> {
+  const generated = new Set((def.generated ?? []).map((entry) => entry.field));
+  const pkFields = pkFieldsOf(def);
+  if (def.sequencePrefix && pkFields.length === 1) generated.add(pkFields[0]);
+  return generated;
+}
+
+function fromFieldDef(
+  field: FieldDef | (Omit<FieldDef, 'name'> & { name: string }),
+  table: string | undefined,
+  notNullByDefault: boolean,
+  generated: boolean,
+): ResolvedField {
+  return {
+    name: field.name,
+    type: field.type,
+    nullable: field.nullable ?? !notNullByDefault,
+    generated,
+    ...(field.values ? { values: field.values } : {}),
+    ...(field.default !== undefined ? { default: field.default } : {}),
+    ...(field.maxSize !== undefined ? { maxSize: field.maxSize } : {}),
+    ...(field.minLength !== undefined ? { minLength: field.minLength } : {}),
+    ...(field.description !== undefined ? { description: field.description } : {}),
+    ...(field.title !== undefined ? { title: field.title } : {}),
+    ...(field.optional !== undefined ? { optional: field.optional } : {}),
+    ...(table ? { table } : {}),
+  };
+}
+
+function declaredTableFields(tableName: string, def: TableDef): ResolvedField[] {
+  const pkFields = pkFieldsOf(def);
+  const generated = generatedFieldsOf(def);
+  return (def.fields ?? []).map((field) =>
+    fromFieldDef(
+      field,
+      tableName,
+      pkFields.includes(field.name) || generated.has(field.name),
+      generated.has(field.name),
+    ),
+  );
+}
+
+// Inference from rows: a type per column (metadata.ts), nothing nullable but
+// the key, no defaults or enum values (rows can't say).
+function inferredFields(
+  rows: Row[],
+  pkFields: string[],
+  generated: Set<string>,
+  table: string | undefined,
+): ResolvedField[] {
+  return deriveFields(rows).map(({ NAME, TYPE }) => ({
+    name: NAME,
+    type: TYPE,
+    nullable: !(pkFields.includes(NAME) || generated.has(NAME)),
+    generated: generated.has(NAME),
+    ...(table ? { table } : {}),
+  }));
+}
+
+function derivedTypeDef(
+  name: string,
+  entry: NonNullable<ViewDef['derivedTypes']>[string],
+): Omit<FieldDef, 'name'> & { name: string } {
+  return typeof entry === 'string' ? { name, type: entry } : { ...entry, name };
+}
+
+function viewOf(name: string, config: MockServerConfig, store: Store): ViewDef | undefined {
+  return store.views.get(name) ?? config.views?.[name];
+}
+
+// A view over a declared base table: the base table's columns, each join's
+// selected columns typed from the joined table (nullable, since a base row
+// may have no match), and the derived fields typed from derivedTypes (or
+// inferred from the view's rows when not given) — narrowed to the view's
+// fields block when it has one.
+function declaredViewFields(
+  viewName: string,
+  view: ViewDef,
+  config: MockServerConfig,
+  store: Store,
+): ResolvedField[] {
+  const fields = new Map<string, ResolvedField>();
+  for (const field of resolveSourceSchema(view.base, config, store).fields) {
+    fields.set(field.name, field);
+  }
+  for (const join of view.joins ?? []) {
+    const joined = resolveSourceSchema(join.table, config, store).fields;
+    for (const [alias, sourceField] of Object.entries(join.select ?? {})) {
+      const source = joined.find((field) => field.name === sourceField);
+      const { title: _title, ...rest } = source ?? {
+        name: alias,
+        type: 'STRING',
+        nullable: true,
+        generated: false,
+      };
+      fields.set(alias, { ...rest, name: alias, nullable: true, generated: false });
+    }
+  }
+  const derivedNames = Object.keys(view.derived ?? {});
+  const untyped = derivedNames.filter((name) => !view.derivedTypes?.[name]);
+  const inferred =
+    untyped.length > 0
+      ? deriveFields(
+          store
+            .getMetadataRows(viewName)
+            .map((row) => Object.fromEntries(untyped.map((name) => [name, row[name]]))),
+        )
+      : [];
+  for (const name of derivedNames) {
+    const typed = view.derivedTypes?.[name];
+    fields.set(
+      name,
+      typed
+        ? fromFieldDef(derivedTypeDef(name, typed), undefined, false, false)
+        : {
+            name,
+            type: inferred.find((field) => field.NAME === name)?.TYPE ?? 'STRING',
+            nullable: true,
+            generated: false,
+          },
+    );
+  }
+  return view.fields ? pick(fields, view.fields) : [...fields.values()];
+}
+
+function pick(fields: Map<string, ResolvedField>, names: string[]): ResolvedField[] {
+  return names.flatMap((name) => {
+    const field = fields.get(name);
+    return field ? [field] : [];
+  });
+}
+
+function isDeclared(source: string, config: MockServerConfig, store: Store): boolean {
+  const table = config.tables?.[source];
+  if (table) return !!table.fields;
+  const view = viewOf(source, config, store);
+  return view ? isDeclared(view.base, config, store) : false;
+}
+
+// The fields of a table or view. Unknown names resolve to no fields. Under
+// fidelity: 'legacy' everything is inferred, as up to 15.47: declarations,
+// fields blocks and derivedTypes are ignored.
+export function resolveSourceSchema(
+  source: string,
+  config: MockServerConfig,
+  store: Store,
+): ResolvedSchema {
+  const legacy = isLegacyFidelity(config);
+  const table = config.tables?.[source];
+  if (!legacy && table?.fields) {
+    return { fields: declaredTableFields(source, table), declared: true };
+  }
+  const view = viewOf(source, config, store);
+  if (!legacy && view && isDeclared(view.base, config, store)) {
+    return { fields: declaredViewFields(source, view, config, store), declared: true };
+  }
+  const generated = table ? generatedFieldsOf(table) : new Set<string>();
+  let fields = inferredFields(
+    store.getMetadataRows(source),
+    store.getPkFields(source),
+    generated,
+    table ? source : view?.base,
+  );
+  if (legacy) return { fields, declared: false };
+  // derivedTypes and the fields block describe a view even when the rest of
+  // it is inferred.
+  if (view?.derivedTypes) {
+    fields = fields.map((field) => {
+      const typed = view.derivedTypes?.[field.name];
+      return typed
+        ? fromFieldDef(derivedTypeDef(field.name, typed), undefined, false, false)
+        : field;
+    });
+  }
+  if (view?.fields) fields = pick(new Map(fields.map((field) => [field.name, field])), view.fields);
+  return { fields, declared: false };
+}
+
+// fieldTypes overrides the TYPE of the named fields, declared or inferred.
+export function withTypeOverrides(
+  schema: ResolvedSchema,
+  fieldTypes: Record<string, string> | undefined,
+): ResolvedSchema {
+  if (!fieldTypes) return schema;
+  return {
+    ...schema,
+    fields: schema.fields.map((field) =>
+      fieldTypes[field.name] ? { ...field, type: fieldTypes[field.name] } : field,
+    ),
+  };
+}
+
+// A query's fields block: those fields only, in its order. Names the source
+// doesn't have are dropped, as the real dataserver drops them.
+export function projectSchema(schema: ResolvedSchema, names: string[] | undefined): ResolvedSchema {
+  if (!names) return schema;
+  const byName = new Map(schema.fields.map((field) => [field.name, field]));
+  return {
+    ...schema,
+    fields: names.flatMap((name) => {
+      const field = byName.get(name);
+      return field ? [field] : [];
+    }),
+  };
+}
+
+export function querySchema(
+  query: QueryDef,
+  config: MockServerConfig,
+  store: Store,
+): ResolvedSchema {
+  return projectSchema(
+    withTypeOverrides(resolveSourceSchema(query.source, config, store), query.fieldTypes),
+    isLegacyFidelity(config) ? undefined : query.fields,
+  );
+}
+
+// A resolver-only request server has no table: its fields come from the
+// def's metadataRows sample.
+export function requestReplySchema(
+  requestReply: RequestReplyDef,
+  config: MockServerConfig,
+  store: Store,
+): ResolvedSchema {
+  const schema = requestReply.source
+    ? resolveSourceSchema(requestReply.source, config, store)
+    : {
+        fields: inferredFields(requestReply.metadataRows ?? [], [], new Set(), undefined),
+        declared: false,
+      };
+  return withTypeOverrides(schema, requestReply.fieldTypes);
+}
+
+// The record identity a criteria-only request server adds to every reply row.
+export const RECORD_IDENTITY_FIELDS: ResolvedField[] = [
+  { name: 'RECORD_ID', type: 'LONG', nullable: false, generated: true },
+  { name: 'TIMESTAMP', type: 'NANO_TIMESTAMP', nullable: false, generated: true },
+];
+
+// The request block's fields: requestFields, else the source's key.
+export function requestFieldsOf(requestReply: RequestReplyDef, store: Store): string[] {
+  if (requestReply.requestFields) return requestReply.requestFields;
+  return requestReply.source ? store.getPkFields(requestReply.source) : [];
+}
+
+// An ENUM's values, or undefined when none are known: a client must then be
+// told nothing rather than an empty list (grid-pro builds an empty select from
+// VALID_VALUES: [], and a JSON schema `enum: []` accepts no value at all).
+export function knownValues(field: ResolvedField): string[] | undefined {
+  return field.values?.length ? field.values : undefined;
+}
+
+// The DEFAULT an event field reports (META DEFAULT, JSON schema `default`).
+// Only an optional property has one, and it is its type's default
+// (PALMetadataUtils.kt:159, getPropertyDefaultValue, GSF v8.15.29): the
+// dictionary default, or for an ENUM with none the enum's first value
+// (PALMetadataUtils.kt:205, EnumType defaultValue = ... ?: jsonValues.firstOrNull()).
+export function eventDefaultOf(field: ResolvedField): unknown {
+  if (!field.optional) return undefined;
+  if (field.default !== undefined) return field.default;
+  return field.type === 'ENUM' ? knownValues(field)?.[0] : undefined;
+}
+
+// --- query rows --------------------------------------------------------------
+
+function sourceFieldNames(
+  source: string,
+  config: MockServerConfig,
+  store: Store,
+): string[] | undefined {
+  const table = config.tables?.[source];
+  if (table) return table.fields?.map((field) => field.name);
+  const view = viewOf(source, config, store);
+  if (!view) return undefined;
+  const base = sourceFieldNames(view.base, config, store);
+  // An undeclared base: the view's own fields block is all that is known.
+  if (!base) return view.fields;
+  const names = new Set(base);
+  for (const join of view.joins ?? []) {
+    for (const alias of Object.keys(join.select ?? {})) names.add(alias);
+  }
+  for (const name of Object.keys(view.derived ?? {})) names.add(name);
+  return view.fields ? view.fields.filter((name) => names.has(name)) : [...names];
+}
+
+// The columns a query's rows carry, in order: its fields block, else every
+// declared column of its source (a view's own fields block included).
+// undefined when neither is known, and always under fidelity: 'legacy': rows
+// go out as stored.
+export function queryFieldNames(
+  query: QueryDef | undefined,
+  config: MockServerConfig,
+  store: Store,
+): string[] | undefined {
+  if (!query || isLegacyFidelity(config)) return undefined;
+  const names = sourceFieldNames(query.source, config, store);
+  if (!query.fields) return names;
+  return names ? query.fields.filter((name) => names.includes(name)) : query.fields;
+}
+
+// A row with exactly these columns. The real dataserver sends every column it
+// exposes, null when unset, so a missing value goes out as null.
+export function projectRow(row: Row, names: string[] | undefined): Row {
+  if (!names) return row;
+  return Object.fromEntries(names.map((name) => [name, row[name] ?? null]));
+}
+
+// --- events ------------------------------------------------------------------
+
+// Any event named .../_DELETE(_...)? takes only the key fields, which is what
+// entity-management's delete confirmation copies from the selected row.
+export function isDeleteEventName(name: string): boolean {
+  return /_DELETE(_|$)/.test(name);
+}
+
+// Zero-config default: EVENT_<TABLE>_<VERB...> maps to <TABLE> if it's a
+// registered table name (longest match wins, so e.g. a hypothetical
+// COUNTERPARTY_AUTH table can't shadow COUNTERPARTY). Covers every event
+// naming pattern in this codebase (INSERT, MODIFY, DELETE, plus suffixed
+// variants like INSERT_WITH_APPROVAL, DEMO_INSERT, MODIFY_PRICE, INSERT_FAIL)
+// without hand-maintaining a table per event. Override via
+// config.eventSchemas for names that don't follow this convention.
+export function inferEventTable(
+  eventName: string | undefined,
+  tableNames: string[],
+): string | undefined {
+  if (!eventName) return undefined;
+  // Not every caller asks by event name: entity-management resolves a grid's
+  // schema from the bare resource/table name (FEATURE: 'TRADE'), so accept an
+  // exact table match before requiring the EVENT_ prefix. Without this the
+  // request errors with UNKNOWN_RESOURCE and the form renders no fields.
+  if (tableNames.includes(eventName)) return eventName;
+  if (!eventName.startsWith('EVENT_')) return undefined;
+  const rest = eventName.slice('EVENT_'.length);
+  const candidates = tableNames.filter((name) => rest === name || rest.startsWith(`${name}_`));
+  candidates.sort((a, b) => b.length - a.length);
+  return candidates[0];
+}
+
+export interface EventTarget {
+  // How the real server describes the DETAILS class: 'table', a generated
+  // DAO (titles, lengths, ranges, genesis types; fields sorted by name);
+  // 'byId', a delete's <Table>.ById (the key fields only, all mandatory, no
+  // annotations); 'dto', a custom class (EventSchemaOverride.fields, no
+  // annotations).
+  kind: 'table' | 'byId' | 'dto';
+  // The table (or view) the DETAILS take. For a 'dto', where its ENUM
+  // columns come from, if anywhere.
+  table?: string;
+  // DESCRIPTION: the DETAILS class name.
+  className: string;
+  // TITLE, on 'table' events only.
+  title?: string;
+  fieldTypes?: Record<string, string>;
+  fields?: FieldDef[];
+}
+
+// The table an event writes: config.eventSchemas first, then the
+// EVENT_<TABLE>_<VERB> convention. Only a registered event (an eventHandlers
+// or eventSchemas entry) has metadata, as only a deployed event handler has
+// on the real server; anything else is the router's 404. `bareTable` also
+// accepts a plain table name, which only JSON_SCHEMA_REQUEST does (see the
+// README).
+export function resolveEventTarget(
+  name: string | undefined,
+  config: MockServerConfig,
+  { bareTable = false }: { bareTable?: boolean } = {},
+): EventTarget | undefined {
+  if (!name) return undefined;
+  const override = config.eventSchemas?.[name];
+  if (name.startsWith('EVENT_') && !override && !config.eventHandlers?.[name]) return undefined;
+  const tableNames = Object.keys(config.tables ?? {});
+  const table =
+    override?.table ??
+    (bareTable || name.startsWith('EVENT_') ? inferEventTable(name, tableNames) : undefined);
+  const fieldTypes = override?.fieldTypes ? { fieldTypes: override.fieldTypes } : {};
+  if (override?.fields) {
+    return {
+      kind: 'dto',
+      ...(table ? { table } : {}),
+      className: override.className ?? daoClassOf(table ?? name.replace(/^EVENT_/, '')),
+      fields: override.fields,
+      ...fieldTypes,
+    };
+  }
+  if (!table) return undefined;
+  const byId = override?.pkOnly ?? isDeleteEventName(name);
+  return byId
+    ? {
+        kind: 'byId',
+        table,
+        className: override?.className ?? `${daoClassOf(table)}.ById`,
+        ...fieldTypes,
+      }
+    : {
+        kind: 'table',
+        table,
+        className: override?.className ?? daoClassOf(table),
+        title: titleCase(table),
+        ...fieldTypes,
+      };
+}
+
+// Kotlin reflection lists a class's properties sorted by their (camelCase)
+// names, and the real server only then turns them into UPPER_UNDERSCORE —
+// so DATE_FIELD (dateField) sorts before DATETIME_FIELD (datetimeField),
+// which a plain sort of the field names would reverse.
+function propertyName(field: ResolvedField): string {
+  return field.name
+    .toLowerCase()
+    .replace(/_+([a-z0-9])/g, (_match, char: string) => char.toUpperCase());
+}
+
+const byName = (a: ResolvedField, b: ResolvedField) => {
+  const [left, right] = [propertyName(a), propertyName(b)];
+  return left < right ? -1 : left > right ? 1 : 0;
+};
+
+// The fields an event's DETAILS take, sorted by name as the real server
+// lists a class's properties — except a delete's, which are the key fields
+// in key order, all mandatory. A key field the schema doesn't know (an
+// inferred table with no rows) is still listed, as a STRING. `optional` is
+// always resolved: FieldDef.optional when given, else whether the class
+// property has a default (PALMetadataUtils.kt mapMemberProperty: optional =
+// propertyType != Mandatory). A generated DAO gives every nullable and every
+// generated column a default; a custom DTO's defaults are invisible, so a
+// DTO field is optional only when it declares a default or `optional: true`.
+export function eventFields(
+  target: EventTarget,
+  config: MockServerConfig,
+  store: Store,
+): ResolvedField[] {
+  if (target.kind === 'dto') {
+    const resolved = (target.fields ?? []).map((field) =>
+      fromFieldDef(field, target.table, false, false),
+    );
+    return withTypeOverrides({ fields: resolved, declared: true }, target.fieldTypes)
+      .fields.map((field) => ({
+        ...field,
+        optional: field.optional ?? field.default !== undefined,
+      }))
+      .sort(byName);
+  }
+  const table = target.table!;
+  const { fields } = withTypeOverrides(
+    resolveSourceSchema(table, config, store),
+    target.fieldTypes,
+  );
+  if (target.kind === 'byId') {
+    return store.getPkFields(table).map((name) => {
+      const { default: _default, ...field } = fields.find(
+        (candidate) => candidate.name === name,
+      ) ?? {
+        name,
+        type: 'STRING' satisfies GenesisFieldType,
+        nullable: false,
+        generated: false,
+      };
+      return { ...field, nullable: false, generated: false, optional: false };
+    });
+  }
+  return fields
+    .map((field) => ({
+      ...field,
+      optional:
+        field.optional ?? (field.generated || field.nullable || field.default !== undefined),
+    }))
+    .sort(byName);
+}