@genesislcap/mock-server 15.7.3-alpha-277c463.0 → 15.7.3-alpha-e7d4aa5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (71) hide show
  1. package/README.md +237 -52
  2. package/dist/db/criteria.d.ts +5 -0
  3. package/dist/db/criteria.js +304 -0
  4. package/dist/db/metadata.d.ts +3 -0
  5. package/dist/db/metadata.js +35 -0
  6. package/dist/db/store.d.ts +27 -0
  7. package/dist/db/store.js +226 -0
  8. package/dist/handlers/auth.d.ts +9 -0
  9. package/dist/handlers/auth.js +99 -0
  10. package/dist/handlers/commitEvent.d.ts +8 -0
  11. package/dist/handlers/commitEvent.js +40 -0
  12. package/dist/handlers/dataLogon.d.ts +5 -0
  13. package/dist/handlers/dataLogon.js +46 -0
  14. package/dist/handlers/heartbeat.d.ts +3 -0
  15. package/dist/handlers/heartbeat.js +16 -0
  16. package/dist/handlers/http.d.ts +4 -0
  17. package/dist/handlers/http.js +165 -0
  18. package/dist/handlers/jsonSchema.d.ts +5 -0
  19. package/dist/handlers/jsonSchema.js +77 -0
  20. package/dist/handlers/meta.d.ts +4 -0
  21. package/dist/handlers/meta.js +42 -0
  22. package/dist/handlers/requestReply.d.ts +4 -0
  23. package/dist/handlers/requestReply.js +68 -0
  24. package/dist/handlers/resourceAuth.d.ts +5 -0
  25. package/dist/handlers/resourceAuth.js +27 -0
  26. package/dist/handlers/resources.d.ts +3 -0
  27. package/dist/handlers/resources.js +34 -0
  28. package/dist/index.d.ts +6 -0
  29. package/dist/index.js +5 -0
  30. package/dist/launch.d.ts +19 -0
  31. package/dist/launch.js +59 -0
  32. package/dist/protocol/connection.d.ts +24 -0
  33. package/dist/protocol/connection.js +35 -0
  34. package/dist/protocol/errors.d.ts +17 -0
  35. package/dist/protocol/errors.js +16 -0
  36. package/dist/protocol/messageTypes.d.ts +28 -0
  37. package/dist/protocol/messageTypes.js +42 -0
  38. package/dist/protocol/router.d.ts +6 -0
  39. package/dist/protocol/router.js +101 -0
  40. package/dist/protocol/rowUpdate.d.ts +4 -0
  41. package/dist/protocol/rowUpdate.js +17 -0
  42. package/dist/server.d.ts +23 -0
  43. package/dist/server.js +274 -0
  44. package/dist/types.d.ts +142 -0
  45. package/dist/types.js +4 -0
  46. package/package.json +16 -6
  47. package/src/db/criteria.ts +53 -21
  48. package/src/db/store.ts +100 -27
  49. package/src/handlers/commitEvent.ts +13 -5
  50. package/src/handlers/dataLogon.ts +11 -4
  51. package/src/handlers/heartbeat.ts +16 -3
  52. package/src/handlers/http.ts +27 -0
  53. package/src/handlers/jsonSchema.ts +3 -3
  54. package/src/handlers/meta.ts +11 -3
  55. package/src/handlers/requestReply.ts +22 -8
  56. package/src/handlers/resourceAuth.ts +37 -0
  57. package/src/handlers/resources.ts +8 -1
  58. package/src/index.ts +9 -0
  59. package/src/launch.ts +95 -0
  60. package/src/protocol/connection.ts +3 -1
  61. package/src/protocol/messageTypes.ts +9 -0
  62. package/src/protocol/router.ts +19 -12
  63. package/src/protocol/rowUpdate.ts +5 -4
  64. package/src/server.ts +73 -8
  65. package/src/types.ts +132 -8
  66. package/test/criteria.test.ts +0 -174
  67. package/test/jsonSchema.test.ts +0 -38
  68. package/test/metadata.test.ts +0 -49
  69. package/test/server.test.ts +0 -289
  70. package/test/store.test.ts +0 -181
  71. package/tsconfig.json +0 -18
package/README.md CHANGED
@@ -3,30 +3,30 @@
3
3
  A reusable, in-memory Genesis Framework WebSocket protocol server for client
4
4
  automation and local dev — no JVM, no database, starts in milliseconds.
5
5
 
6
- Written in TypeScript, runs directly from source under **either** runtime, no
7
- build step:
8
-
9
- - **Node (>=22.6)**: `node --experimental-strip-types src/index.ts`. Node's
10
- type-stripping flag erases type annotations at load time; it does not
11
- type-check. This is the default/safe choice — nothing extra to install
12
- beyond the Node version the rest of this monorepo already requires.
13
- - **[Bun](https://bun.sh) (>=1.1.0)**: `bun run src/index.ts`. Bun's own TS
14
- support is used instead — faster startup, but requires installing Bun
15
- separately (`brew install bun` or https://bun.sh/install).
16
-
17
- Both runtimes execute the exact same `.ts` sources unmodified — this package
18
- deliberately avoids any Bun-only API (e.g. `Bun.serve`'s native WebSocket
19
- support) in favor of `node:http` + the `ws` package, which both runtimes
20
- support identically. All relative imports use explicit `.ts` extensions
21
- (`import { X } from './foo.ts'`) rather than the more common `.js`-referring-
22
- to-`.ts` convention, because Node's type-stripping resolver requires the
23
- literal extension match — Bun is lenient about this but Node isn't, so `.ts`
24
- is the one form that works everywhere. `tsconfig.json` sets
25
- `allowImportingTsExtensions: true` so `tsc` accepts this without complaint.
6
+ Written in TypeScript; **development and tests run straight from source**
7
+ under either runtime (`node --experimental-strip-types` on Node >=22.6, or
8
+ `bun run` — this package deliberately avoids Bun-only APIs like `Bun.serve`
9
+ in favor of `node:http` + the `ws` package, which both support identically).
10
+ All relative imports use explicit `.ts` extensions
11
+ (`import { X } from './foo.ts'`) because Node's type-stripping resolver
12
+ requires the literal extension match; `allowImportingTsExtensions` keeps
13
+ `tsc` happy with that.
14
+
15
+ **Consumers get compiled JavaScript.** `npm run build` (`tsc -p
16
+ tsconfig.build.json`, with `rewriteRelativeImportExtensions` turning the
17
+ `.ts` specifiers into `.js`) emits `dist/`, and the package's
18
+ `main`/`types`/`exports` point there. This is not optional polish: Node
19
+ **refuses** to strip types for files inside a real (non-symlinked)
20
+ `node_modules` (`ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING`), so a
21
+ published package shipping only `.ts` is unusable with plain `node` outside
22
+ this monorepo. The `exports` map keeps a `"bun"` condition on `src/index.ts`
23
+ so Bun users still run the source directly. In-repo, `npm run bootstrap`
24
+ builds `dist` (via `lerna run build --no-private`); when hacking on the
25
+ engine against a consumer, keep `npm run --workspace=@genesislcap/mock-server
26
+ build:watch` running.
26
27
 
27
28
  Type-check with `npm run --workspace=@genesislcap/mock-server typecheck`
28
- (`tsc --noEmit`) — this is for editor/CI type-checking only; neither runtime
29
- compiles or reads the emitted output (there isn't any, `noEmit: true`).
29
+ (`tsc --noEmit` over src + tests).
30
30
 
31
31
  This package is the **protocol engine only**: message routing, `SOURCE_REF`
32
32
  correlation, `CRITERIA_MATCH` evaluation, subscription/broadcast plumbing, and
@@ -78,6 +78,166 @@ const server = createMockServer(config);
78
78
  server.start(9064);
79
79
  ```
80
80
 
81
+ ## Project-fidelity features
82
+
83
+ Beyond the basic table/view/query plumbing in the example above, the config
84
+ covers the server-side behaviors real projects lean on:
85
+
86
+ - **Computed request-replies** — for request servers that calculate rather
87
+ than read (date calculations, holiday validate/roll, premium schedules,
88
+ keyed composite lookups), give the `RequestReplyDef` a `resolver` instead
89
+ of a `source`. It receives `{ request, message, user, store }` (the keyed
90
+ `REQUEST` fields, the raw message, the requesting user, the live store) and
91
+ returns the `REPLY` rows verbatim; throw `NackError` for a
92
+ protocol-correct error. Set `metadataRows` (a representative sample reply)
93
+ so `META_REQUEST` can still derive `REPLY_FIELD`:
94
+
95
+ ```ts
96
+ requestReplies: {
97
+ DATE_CALC: {
98
+ resolver: ({ request }) => [computeDates(request.DATE, request.CALENDAR)],
99
+ metadataRows: [{ INPUT_DATE: '20260101', RESULT_DATE: '20260105' }],
100
+ },
101
+ }
102
+ ```
103
+
104
+ - **Query filters (where-clause equivalent)** — `QueryDef.filter` narrows a
105
+ dataserver query the way the real query's filter clause does (keep template
106
+ rows out of a main-entries query, CANCELLED out of a blotter). Applied to
107
+ both the `DATA_LOGON` snapshot and live pushes, before any client
108
+ `CRITERIA_MATCH`:
109
+
110
+ ```ts
111
+ queries: {
112
+ ALL_TRADES: { source: 'TRADE_VIEW', filter: (row) => row.TRADE_STATUS !== 'CANCELLED' },
113
+ }
114
+ ```
115
+
116
+ - **Permissioning (auth maps / hideFields)** — `auth` on a query or
117
+ request-reply scopes what each user sees. `rowFilter(row, user)` drops rows
118
+ (snapshots, live pushes, and `REQ_` replies); `hideFields` (a list, or a
119
+ function of the user) strips columns from rows **and** from `META_REQUEST`
120
+ field metadata, so e.g. sales users never see the trader side of mirrored
121
+ columns. `user` is `{ userName, profile, permission }` for the requesting
122
+ connection:
123
+
124
+ ```ts
125
+ queries: {
126
+ ALL_RFQS: {
127
+ source: 'RFQ_VIEW',
128
+ auth: {
129
+ rowFilter: (row, user) => user.profile.includes('TRADER') || row.SIDE === 'SALES',
130
+ hideFields: (user) => (user.profile.includes('TRADER') ? [] : ['TRADER_PX']),
131
+ },
132
+ },
133
+ }
134
+ ```
135
+
136
+ - **Join predicates and anti-joins** — a view join takes a `where(joinRow,
137
+ baseRow)` predicate for matches the `on` equality alone can't express
138
+ (side-specific price joins), and `antiJoins` keeps only base rows with NO
139
+ match (the `USER_WITHOUT_DETAIL` pattern):
140
+
141
+ ```ts
142
+ views: {
143
+ RFQ_SALES_VIEW: {
144
+ base: 'RFQ',
145
+ joins: [{ table: 'RFQ_PRICE', on: ['RFQ_ID', 'RFQ_ID'], select: { SALES_PX: 'PX' },
146
+ where: (price) => price.SIDE === 'SALES' }],
147
+ },
148
+ USER_WITHOUT_DETAIL: {
149
+ base: 'USER',
150
+ antiJoins: [{ table: 'USER_DETAIL', on: ['USER_NAME', 'USER_NAME'] }],
151
+ },
152
+ }
153
+ ```
154
+
155
+ - **Composite primary keys** — `pkField` accepts an array
156
+ (`pkField: ['RFQ_ID', 'SIDE']`). Rows are identified by the fields' values
157
+ joined with `'|'` (so values must not contain `'|'`), which becomes the
158
+ `ROW_REF` — no synthetic key column, nothing extra in grids. Event handlers
159
+ on composite tables pass `store.rowKey(table, row)` to
160
+ `broadcastTableChange`; sequence generation still requires a single
161
+ `pkField`.
162
+
163
+ ## Running several servers in parallel (and one-command dev stacks)
164
+
165
+ Every `createMockServer()` instance is fully isolated — its own store,
166
+ connections, sessions, and tokens — so parallel test workers/shards can each
167
+ run their own server in one process or many. The only shared resource is
168
+ ports; don't hand-assign them, use `listen()`:
169
+
170
+ ```ts
171
+ const server = createMockServer(config);
172
+ const port = await server.listen(); // port 0 -> OS picks a free one
173
+ // hand `ws://localhost:${port}` to this worker's client
174
+ ```
175
+
176
+ To boot a **mock server + client dev process as one command** (and N such
177
+ pairs side by side), use `launchStack` — it starts the server on an
178
+ ephemeral port, spawns the client command with `API_HOST` pointed at it, and
179
+ ties the lifetimes (client exit stops the server; one Ctrl+C tears down the
180
+ pair):
181
+
182
+ ```ts
183
+ // mock-server/src/dev.ts
184
+ import { launchStack } from '@genesislcap/mock-server';
185
+ import { config } from './config.ts';
186
+
187
+ await launchStack({ config, clientCommand: 'npm run dev:vite' });
188
+ ```
189
+
190
+ `clientEnv: (port) => ({ ... })` adds per-instance env on top of the default
191
+ `API_HOST` (e.g. to pin the client dev server's own port; vite's default
192
+ auto-increment already avoids collisions otherwise). Pass
193
+ `tieLifetimes: false` to manage shutdown yourself (e.g. inside a test
194
+ runner).
195
+
196
+ ## Extension points
197
+
198
+ For everything the protocol handlers don't cover, three hooks avoid ever
199
+ having to monkey-patch the engine:
200
+
201
+ - **`config.httpRoutes`** — extra HTTP endpoints on the engine's shared
202
+ `http.Server` (e.g. a project's `GET pbi/configs`). Tried before the
203
+ built-in login/SSO handlers, so they can also override those. A string
204
+ `path` matches `pathname.endsWith(path)` (tolerating any gateway prefix);
205
+ a RegExp is tested against the full pathname:
206
+
207
+ ```ts
208
+ httpRoutes: [{
209
+ method: 'GET',
210
+ path: 'pbi/configs',
211
+ handler: (req, res) => {
212
+ res.writeHead(200, { 'Content-Type': 'application/json' });
213
+ res.end(JSON.stringify({ CONFIGS: [...] }));
214
+ },
215
+ }]
216
+ ```
217
+
218
+ - **`config.onMessage`** — called for every parsed WS message before routing.
219
+ Return a message to continue routing with it (possibly rewritten — e.g.
220
+ normalizing a criteria dialect), `false` if the hook fully handled it
221
+ (reply via `ctx.connection.reply`), or nothing to route the original:
222
+
223
+ ```ts
224
+ onMessage: (message, { connection }) => {
225
+ if (message.MESSAGE_TYPE === 'CUSTOM_PING') {
226
+ connection.reply(message, { MESSAGE_TYPE: 'CUSTOM_PONG' });
227
+ return false;
228
+ }
229
+ }
230
+ ```
231
+
232
+ - **`config.defaultEventHandler`** — fallback for commit events with no
233
+ registered handler, so a project with dozens of events can adopt
234
+ incrementally (`defaultEventHandler: () => ({})` acks everything
235
+ unhandled) instead of enumerating ack-only handlers. Unregistered events
236
+ NACK with `UNKNOWN_RESOURCE` when unset. Note `RESOURCES_REQUEST` only
237
+ lists *named* events (`eventHandlers` + `eventSchemas` keys) — if the
238
+ client's resource gate blocks an event served only by the default handler,
239
+ name it in `config.eventSchemas` or `config.resources`.
240
+
81
241
  ## Two auth transports
82
242
 
83
243
  Genesis client apps built on `@genesislcap/foundation-auth`'s login UI don't
@@ -97,18 +257,30 @@ CI/local dev. Leave it unset to require an explicit `EVENT_LOGIN_AUTH` POST
97
257
  (validated against `config.auth.users`, same as the WS flow) before
98
258
  `event-login-details` will succeed on a later reload.
99
259
 
100
- WS data traffic (`DATA_LOGON`, `REQ_*`, `META_REQUEST`, `JSON_SCHEMA_REQUEST`,
101
- commit events) requires authentication, like the real server: either the
102
- connection logged in over WS, or the message carries a `SESSION_AUTH_TOKEN`
103
- this server issued over **either** transport — foundation-comms stamps the
104
- stored token onto every outgoing message, which is exactly how a client that
105
- logged in over HTTP (including via `httpAutoLogin`) authenticates its WS
106
- traffic. The WS token-refresh login (`EVENT_LOGIN_AUTH` with only
260
+ An **opt-in** auth gate (`config.auth.requireAuth: true`) rejects WS data
261
+ traffic (`DATA_LOGON`, `REQ_*`, `META_REQUEST`, `JSON_SCHEMA_REQUEST`, commit
262
+ events) with a `NOT_LOGGED_ON` error until the connection logs in over WS or
263
+ the message carries a `SESSION_AUTH_TOKEN` this server issued over **either**
264
+ transport. The WS token-refresh login (`EVENT_LOGIN_AUTH` with only
107
265
  `DETAILS.REFRESH_AUTH_TOKEN`, no credentials — foundation-comms'
108
- `createRefreshTokenMessage`) is honored the same way. Unauthenticated data
109
- messages get a `NOT_LOGGED_ON` error shaped like the target handler's own
110
- error replies. Set `config.auth.requireAuth: false` to switch the gate off
111
- and accept everything.
266
+ `createRefreshTokenMessage`) is honored via the same token registry.
267
+
268
+ `GET gwf/sso/list` is served too: foundation-auth's login screen fetches it
269
+ whenever SSO is toggled on, and treats a failed fetch as fatal — red "Failed
270
+ to fetch identity providers" **and** the credentials form hidden — while an
271
+ empty `IDPS` list is rejected as well ("Identity provider list empty").
272
+ Configure real entries via `config.auth.ssoIdentityProviders`
273
+ (`{ ID, DESCRIPTION, TYPE }`, foundation-auth's `IDENTITY_PROVIDER` DTO);
274
+ when unset the mock serves one non-functional placeholder so the login
275
+ screen still renders with SSO enabled. Clicking a provider navigates to the
276
+ real SSO login URL, which the mock does not implement.
277
+
278
+ The gate is **off by default** for a hard-won reason: clients that log in
279
+ over foundation-auth's HTTP transport send **no** `SESSION_AUTH_TOKEN` on any
280
+ WebSocket message — session storage's `authToken` is never populated by that
281
+ flow, so `message.ts`'s token stamp serializes to nothing (verified from
282
+ browser frame captures). A default-on gate would reject every datasource such
283
+ a client opens. Enable it only for clients that authenticate over WS.
112
284
 
113
285
  ## Protocol coverage
114
286
 
@@ -227,7 +399,15 @@ extracted from for how each was actually found:
227
399
  array, uppercase keys. Throw `NackError` from an event handler or
228
400
  request-reply resolver rather than hand-rolling this shape; a lowercase
229
401
  `{error, details}` object crashes the real client's `.forEach`.
230
- 3. **`DATA_LOGON` snapshot and later live pushes use the identical envelope**
402
+ 3. **Commit-event acks are the GENERIC `EVENT_ACK`/`EVENT_NACK`** — never
403
+ `<EVENT_NAME>_ACK`/`_NACK`. The reply is correlated purely by
404
+ `SOURCE_REF`; real consumers match the MESSAGE_TYPE string exactly
405
+ (`foundation-comms`' `kv.service` checks `=== 'EVENT_ACK'`,
406
+ entity-management and the showcase's `customEvents.ts` check
407
+ `=== 'EVENT_NACK'`). Get this wrong and every successful commit renders
408
+ as a failure toast while every NACK passes as silent success.
409
+ `handleCommitEvent()` (`src/handlers/commitEvent.ts`) does this for you.
410
+ 4. **`DATA_LOGON` snapshot and later live pushes use the identical envelope**
231
411
  (`MESSAGE_TYPE: 'QUERY_UPDATE'`, same `SOURCE_REF`) — the client
232
412
  distinguishes insert/amend/delete purely via each row's
233
413
  `DETAILS.OPERATION` (`'INSERT' | 'MODIFY' | 'DELETE'`, no other vocabulary
@@ -235,7 +415,7 @@ extracted from for how each was actually found:
235
415
  (`src/protocol/rowUpdate.ts`) does this for you — always route pushes
236
416
  through `broadcast()`/`broadcastTableChange()`, never `connection.send()`
237
417
  directly.
238
- 4. **Datasource `init()` needs `TYPE: 'DATASERVER'` plus a non-empty `FIELD`
418
+ 5. **Datasource `init()` needs `TYPE: 'DATASERVER'` plus a non-empty `FIELD`
239
419
  array** or the client silently reports "no fields returned" and gives up.
240
420
  `deriveFields()` (`src/db/metadata.ts`) infers this from the rows' own JS
241
421
  types — falling back to the registration-time seed rows when every live
@@ -245,25 +425,30 @@ extracted from for how each was actually found:
245
425
  whole numbers still infers as `LONG` — if it's semantically a `DOUBLE`
246
426
  (e.g. a NOTIONAL that happens to be round in the seed data), say so via
247
427
  the `fieldTypes` override on the query/request-reply.
248
- 5. **`CRITERIA_MATCH` needs more than `==`.** `compileCriteria()`
249
- (`src/db/criteria.ts`) supports `== != > >= < <= AND OR NOT` (also `&&`/`||`)
250
- and parentheses via a small typed grammar (not `eval`/`new Function` — a
251
- malformed criteria string can only fail to parse, never execute arbitrary
252
- JS). It also understands the `Expr.<fn>(field, value)` function-call
253
- criteria that grid date/text filters generate — mirroring
254
- `foundation-criteria`'s `serialisers.ts` and `foundation-ui`'s date-range
255
- filter: `contains`, `containsIgnoreCase`, `dateIsToday`, `dateIsEqual`,
256
- `dateIsGreaterEqual`, `dateIsLessEqual`, `dateTimeIsEqual`,
428
+ 6. **`CRITERIA_MATCH` needs more than `==`.** `compileCriteria()`
429
+ (`src/db/criteria.ts`) supports `== != > >= < <= AND OR NOT` (also
430
+ `&&`/`||`/`!`) and parentheses via a small typed grammar (not
431
+ `eval`/`new Function` — a malformed criteria string can only fail to
432
+ parse, never execute arbitrary JS). It understands both function-call
433
+ dialects real clients emit: the `Expr.<fn>(field, value)` form from
434
+ `foundation-criteria`'s `serialisers.ts` / `foundation-ui`'s date-range
435
+ filter, and the `<FIELD>.<fn>(value)` method-call form project filter
436
+ builders generate (e.g. `DEAL_CURRENCIES.containsIgnoreCase('USD')`) —
437
+ both share the same functions: `contains`, `containsIgnoreCase` (substring
438
+ on strings, membership on array-valued fields), `dateIsToday`,
439
+ `dateIsEqual`, `dateIsGreaterEqual`, `dateIsLessEqual`, `dateTimeIsEqual`,
257
440
  `dateTimeIsGreaterEqual`, `dateTimeIsLessEqual`, `dateTimeIsAfter`,
258
441
  `dateTimeIsBefore` (`dateIs*` compares by calendar day, `dateTimeIs*` by
259
- full timestamp; date values are `'YYYYMMDD-HH:MM[:SS]'`, matching
260
- `formatDate()` in `serialisers.ts`). Any other criteria this grammar still
261
- doesn't cover fails open instead of crashing the handler: `compileCriteria()`
262
- logs a warning and returns a match-all predicate, so `DATA_LOGON` still
263
- responds (unfiltered) rather than leaving the client's grid stuck on
264
- "Loading...". Add new `Expr.*` entries to `EXPR_FUNCTIONS` in `criteria.ts`
265
- if you hit one that isn't covered yet.
266
- 6. **Composite-key AMEND/DELETE matching needs a fallback beyond the PK.**
442
+ full timestamp). Date literals accept `'YYYYMMDD-HH:MM[:SS[.mmm]]'` — the
443
+ milliseconds matter: `getGroovyDateFormat()` emits them, and a parser that
444
+ rejects them makes every `dateTimeIs*` comparison silently false, so a
445
+ grid whose default filter is "Today" renders as an empty screen with no
446
+ warning. Any criteria this grammar still doesn't cover fails open instead
447
+ of crashing the handler: `compileCriteria()` logs a warning and returns a
448
+ match-all predicate, so `DATA_LOGON` still responds (unfiltered) rather
449
+ than leaving the client's grid stuck on "Loading...". Add new entries to
450
+ `EXPR_FUNCTIONS` in `criteria.ts` if you hit one that isn't covered yet.
451
+ 7. **Composite-key AMEND/DELETE matching needs a fallback beyond the PK.**
267
452
  `Store.findRow()` (`src/db/store.ts`) tries the configured PK field, then
268
453
  any single field that uniquely identifies one row, then the full
269
454
  combination of provided fields — needed for tables where no single field
@@ -0,0 +1,5 @@
1
+ import type { Row } from '../types.ts';
2
+ export type Predicate = (record: Row) => boolean;
3
+ /** Compiles a CRITERIA_MATCH string into a predicate function(record) => boolean. */
4
+ export declare function compileCriteria(criteria?: string | null): Predicate;
5
+ export declare function filterByCriteria(rows: Row[], criteria?: string | null): Row[];
@@ -0,0 +1,304 @@
1
+ // Evaluator for Genesis CRITERIA_MATCH expressions, e.g.:
2
+ // TRADE_STATUS == 'CONFIRMED' AND QUANTITY > 100
3
+ // NOT (SIDE == 'SELL') OR PRICE >= 100.5
4
+ // Expr.dateTimeIsGreaterEqual(TRADE_DATE, '20240101-00:00:00') && COUNTERPARTY_ID == 'CPTY001'
5
+ //
6
+ // Supports: == = != <> > >= < <=, AND OR NOT (also && || !), parentheses,
7
+ // string/number/boolean literals, bare field identifiers, and two
8
+ // function-call dialects real clients emit:
9
+ // - `Expr.<fn>(field, value)` — foundation-criteria's serialisers.ts
10
+ // (grid date/text filters);
11
+ // - `<FIELD>.<fn>(value)` method-call form — e.g.
12
+ // `DEAL_CURRENCIES.containsIgnoreCase('USD')`, as emitted by
13
+ // project-level filter builders. Same EXPR_FUNCTIONS, with the receiver
14
+ // field as the implicit first argument.
15
+ // Deliberately NOT eval()/new Function() — this parses a small typed grammar
16
+ // so a malformed or hostile criteria string can only fail to parse, never
17
+ // execute arbitrary JS.
18
+ const TOKEN_RE = /\s*(&&|\|\||<=|>=|!=|<>|==|=|<|>|!|\(|\)|,|'(?:[^'\\]|\\.)*'|"(?:[^"\\]|\\.)*"|-?\d+(?:\.\d+)?|[A-Za-z_][A-Za-z0-9_.]*)/g;
19
+ function tokenize(input) {
20
+ const tokens = [];
21
+ let match;
22
+ let lastIndex = 0;
23
+ TOKEN_RE.lastIndex = 0;
24
+ while ((match = TOKEN_RE.exec(input))) {
25
+ if (match.index !== lastIndex) {
26
+ throw new Error(`Unable to tokenize criteria near: ${input.slice(lastIndex)}`);
27
+ }
28
+ tokens.push(match[1]);
29
+ lastIndex = TOKEN_RE.lastIndex;
30
+ }
31
+ if (lastIndex !== input.length) {
32
+ throw new Error(`Unable to tokenize criteria near: ${input.slice(lastIndex)}`);
33
+ }
34
+ return tokens;
35
+ }
36
+ function parseLiteral(token) {
37
+ if (/^['"]/.test(token))
38
+ return token.slice(1, -1).replace(/\\(.)/g, '$1');
39
+ if (/^-?\d+(?:\.\d+)?$/.test(token))
40
+ return Number(token);
41
+ if (token === 'true')
42
+ return true;
43
+ if (token === 'false')
44
+ return false;
45
+ if (token === 'null')
46
+ return null;
47
+ return undefined; // not a literal -> treat as a field reference
48
+ }
49
+ const COMPARATORS = new Set(['==', '=', '!=', '<>', '<', '<=', '>', '>=']);
50
+ // Genesis date/datetime values serialize as 'YYYYMMDD-HH:MM[:SS[.mmm]]' —
51
+ // foundation-criteria's serialisers.ts formatDate stops at seconds, but
52
+ // getGroovyDateFormat() emits milliseconds too, and a parser that rejects
53
+ // them makes every Expr.dateTimeIs* comparison silently false (date-filtered
54
+ // grids render zero rows with no warning). Row values may already be epoch
55
+ // millis (number) or an ISO string. Returns null if unparseable.
56
+ function parseGenesisDateTime(value) {
57
+ if (typeof value === 'number')
58
+ return value;
59
+ if (typeof value !== 'string')
60
+ return null;
61
+ const match = value.match(/^(\d{4})(\d{2})(\d{2})-(\d{2}):(\d{2})(?::(\d{2})(?:\.(\d{1,3}))?)?$/);
62
+ if (match) {
63
+ const MS_DIGITS = 3; // '.5' means 500ms, not 5ms — right-pad to full precision
64
+ const [, y, mo, d, h, mi, s, ms] = match;
65
+ return Date.UTC(Number(y), Number(mo) - 1, Number(d), Number(h), Number(mi), Number(s ?? '0'), Number((ms ?? '0').padEnd(MS_DIGITS, '0')));
66
+ }
67
+ const parsed = Date.parse(value);
68
+ return Number.isNaN(parsed) ? null : parsed;
69
+ }
70
+ const HOURS_PER_DAY = 24;
71
+ const MINUTES_PER_HOUR = 60;
72
+ const SECONDS_PER_MINUTE = 60;
73
+ const MS_PER_SECOND = 1000;
74
+ const MS_PER_DAY = HOURS_PER_DAY * MINUTES_PER_HOUR * SECONDS_PER_MINUTE * MS_PER_SECOND;
75
+ function toEpochDay(value) {
76
+ const epoch = parseGenesisDateTime(value);
77
+ return epoch === null ? null : Math.floor(epoch / MS_PER_DAY);
78
+ }
79
+ // Expr.<fn>(field, value) function-call criteria, as emitted by
80
+ // foundation-criteria's serialisers.ts (contains/containsIgnoreCase/dateIs*)
81
+ // and foundation-ui's date-range filter.ts (dateTimeIsAfter/dateTimeIsBefore,
82
+ // which operator-map.ts maps onto the same >=/<= semantics as
83
+ // dateTimeIsGreaterEqual/dateTimeIsLessEqual). `dateIs*` compares by calendar
84
+ // day (UTC), `dateTimeIs*` compares full timestamps.
85
+ const EXPR_FUNCTIONS = {
86
+ // Multi-value fields (e.g. DEAL_CURRENCIES) may hold an array — treat
87
+ // "contains" as membership there, substring match on strings.
88
+ contains: (record, args, resolve) => {
89
+ const value = resolve(args[0], record);
90
+ const needle = resolve(args[1], record);
91
+ if (typeof needle !== 'string')
92
+ return false;
93
+ if (Array.isArray(value))
94
+ return value.some((v) => typeof v === 'string' && v === needle);
95
+ return typeof value === 'string' && value.includes(needle);
96
+ },
97
+ containsIgnoreCase: (record, args, resolve) => {
98
+ const value = resolve(args[0], record);
99
+ const needle = resolve(args[1], record);
100
+ if (typeof needle !== 'string')
101
+ return false;
102
+ const lowered = needle.toLowerCase();
103
+ if (Array.isArray(value)) {
104
+ return value.some((v) => typeof v === 'string' && v.toLowerCase() === lowered);
105
+ }
106
+ return typeof value === 'string' && value.toLowerCase().includes(lowered);
107
+ },
108
+ dateIsToday: (record, args, resolve) => {
109
+ const day = toEpochDay(resolve(args[0], record));
110
+ return day !== null && day === toEpochDay(Date.now());
111
+ },
112
+ dateIsEqual: (record, args, resolve) => compareByDay(record, args, resolve, (a, b) => a === b),
113
+ dateIsGreaterEqual: (record, args, resolve) => compareByDay(record, args, resolve, (a, b) => a >= b),
114
+ dateIsLessEqual: (record, args, resolve) => compareByDay(record, args, resolve, (a, b) => a <= b),
115
+ dateTimeIsEqual: (record, args, resolve) => compareByTime(record, args, resolve, (a, b) => a === b),
116
+ dateTimeIsGreaterEqual: (record, args, resolve) => compareByTime(record, args, resolve, (a, b) => a >= b),
117
+ dateTimeIsLessEqual: (record, args, resolve) => compareByTime(record, args, resolve, (a, b) => a <= b),
118
+ dateTimeIsAfter: (record, args, resolve) => compareByTime(record, args, resolve, (a, b) => a >= b),
119
+ dateTimeIsBefore: (record, args, resolve) => compareByTime(record, args, resolve, (a, b) => a <= b),
120
+ };
121
+ function compareByDay(record, args, resolve, cmp) {
122
+ const a = toEpochDay(resolve(args[0], record));
123
+ const b = toEpochDay(resolve(args[1], record));
124
+ return a !== null && b !== null && cmp(a, b);
125
+ }
126
+ function compareByTime(record, args, resolve, cmp) {
127
+ const a = parseGenesisDateTime(resolve(args[0], record));
128
+ const b = parseGenesisDateTime(resolve(args[1], record));
129
+ return a !== null && b !== null && cmp(a, b);
130
+ }
131
+ class Parser {
132
+ tokens;
133
+ pos = 0;
134
+ constructor(tokens) {
135
+ this.tokens = tokens;
136
+ }
137
+ get position() {
138
+ return this.pos;
139
+ }
140
+ peek() {
141
+ return this.tokens[this.pos];
142
+ }
143
+ next() {
144
+ const token = this.tokens[this.pos];
145
+ this.pos += 1;
146
+ return token;
147
+ }
148
+ parseExpression() {
149
+ return this.parseOr();
150
+ }
151
+ parseOr() {
152
+ let left = this.parseAnd();
153
+ while (this.peek() === '||' || this.peek()?.toUpperCase() === 'OR') {
154
+ this.next();
155
+ const right = this.parseAnd();
156
+ const prev = left;
157
+ left = (record) => prev(record) || right(record);
158
+ }
159
+ return left;
160
+ }
161
+ parseAnd() {
162
+ let left = this.parseNot();
163
+ while (this.peek() === '&&' || this.peek()?.toUpperCase() === 'AND') {
164
+ this.next();
165
+ const right = this.parseNot();
166
+ const prev = left;
167
+ left = (record) => prev(record) && right(record);
168
+ }
169
+ return left;
170
+ }
171
+ parseNot() {
172
+ const next = this.peek();
173
+ if (next === '!' || next?.toUpperCase() === 'NOT') {
174
+ this.next();
175
+ const operand = this.parseNot();
176
+ return (record) => !operand(record);
177
+ }
178
+ return this.parseComparison();
179
+ }
180
+ parseComparison() {
181
+ if (this.peek() === '(') {
182
+ this.next();
183
+ const inner = this.parseExpression();
184
+ if (this.next() !== ')')
185
+ throw new Error('Missing closing parenthesis in criteria');
186
+ return inner;
187
+ }
188
+ const leftToken = this.next();
189
+ if (leftToken === undefined) {
190
+ throw new Error('Expected operand on the left side of comparison');
191
+ }
192
+ // Both function-call dialects arrive as one dotted token followed by '(':
193
+ // 'Expr.containsIgnoreCase' (foundation-criteria) or
194
+ // 'DEAL_CURRENCIES.containsIgnoreCase' (field method-call form).
195
+ if (leftToken.includes('.') && this.peek() === '(') {
196
+ return this.parseFunctionCall(leftToken);
197
+ }
198
+ const op = this.peek();
199
+ if (!op || !COMPARATORS.has(op)) {
200
+ throw new Error(`Expected comparator, got: ${op}`);
201
+ }
202
+ this.next();
203
+ const rightToken = this.next();
204
+ if (rightToken === undefined) {
205
+ throw new Error('Expected operand on the right side of comparison');
206
+ }
207
+ const resolveLeft = (record) => this.resolveValue(leftToken, record);
208
+ const resolveRight = (record) => this.resolveValue(rightToken, record);
209
+ return (record) => {
210
+ const a = resolveLeft(record);
211
+ const b = resolveRight(record);
212
+ switch (op) {
213
+ case '==':
214
+ case '=':
215
+ return a === b;
216
+ case '!=':
217
+ case '<>':
218
+ return a !== b;
219
+ case '>':
220
+ return a > b;
221
+ case '>=':
222
+ return a >= b;
223
+ case '<':
224
+ return a < b;
225
+ case '<=':
226
+ return a <= b;
227
+ default:
228
+ return false;
229
+ }
230
+ };
231
+ }
232
+ resolveValue(token, record) {
233
+ const literal = parseLiteral(token);
234
+ if (literal !== undefined)
235
+ return literal;
236
+ return record[token];
237
+ }
238
+ parseFunctionCall(name) {
239
+ this.next(); // consume '('
240
+ const args = [];
241
+ if (this.peek() !== ')') {
242
+ const arg = this.next();
243
+ if (arg === undefined)
244
+ throw new Error(`Unterminated argument list in ${name}(...)`);
245
+ args.push(arg);
246
+ while (this.peek() === ',') {
247
+ this.next();
248
+ const nextArg = this.next();
249
+ if (nextArg === undefined)
250
+ throw new Error(`Unterminated argument list in ${name}(...)`);
251
+ args.push(nextArg);
252
+ }
253
+ }
254
+ if (this.next() !== ')')
255
+ throw new Error(`Missing closing parenthesis in ${name}(...)`);
256
+ // 'Expr.<fn>(field, value)' passes args through as-is; the method-call
257
+ // form '<FIELD>.<fn>(value)' makes the receiver field the implicit first
258
+ // argument, so both dialects share EXPR_FUNCTIONS.
259
+ const dotIndex = name.lastIndexOf('.');
260
+ const receiver = name.slice(0, dotIndex);
261
+ const fnName = name.slice(dotIndex + 1);
262
+ const handler = EXPR_FUNCTIONS[fnName];
263
+ if (!handler)
264
+ throw new Error(`Unsupported criteria function: ${name}`);
265
+ const allArgs = receiver === 'Expr' ? args : [receiver, ...args];
266
+ const resolve = (token, record) => this.resolveValue(token, record);
267
+ return (record) => handler(record, allArgs, resolve);
268
+ }
269
+ }
270
+ /** Compiles a CRITERIA_MATCH string into a predicate function(record) => boolean. */
271
+ export function compileCriteria(criteria) {
272
+ if (!criteria || typeof criteria !== 'string' || criteria.trim() === '') {
273
+ return () => true;
274
+ }
275
+ // Real Genesis clients can emit CRITERIA_MATCH syntax this grammar doesn't
276
+ // cover yet (e.g. function-call criteria like Expr.dateTimeIsGreaterEqual(...)
277
+ // from date-range filters). Failing open — matching everything and logging —
278
+ // keeps DATA_LOGON/broadcast working (unfiltered) instead of crashing the
279
+ // handler and leaving the client's grid stuck on "Loading...".
280
+ try {
281
+ const tokens = tokenize(criteria.trim());
282
+ const parser = new Parser(tokens);
283
+ const predicate = parser.parseExpression();
284
+ if (parser.position !== tokens.length) {
285
+ throw new Error(`Unexpected trailing tokens in criteria: ${criteria}`);
286
+ }
287
+ return predicate;
288
+ }
289
+ catch (error) {
290
+ console.warn(`[mock-server] Unsupported CRITERIA_MATCH syntax, ignoring filter: ${criteria}`, error);
291
+ return () => true;
292
+ }
293
+ }
294
+ export function filterByCriteria(rows, criteria) {
295
+ const predicate = compileCriteria(criteria);
296
+ return rows.filter((row) => {
297
+ try {
298
+ return predicate(row);
299
+ }
300
+ catch {
301
+ return false;
302
+ }
303
+ });
304
+ }
@@ -0,0 +1,3 @@
1
+ import type { FieldMetadata, Row } from '../types.ts';
2
+ /** rows: array of plain row objects. Returns a FIELD array covering every key seen. */
3
+ export declare function deriveFields(rows: Row[], overrides?: Record<string, string>): FieldMetadata[];