@genesislcap/foundation-comms 15.79.2 → 15.80.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 (64) hide show
  1. package/asconfig.json +15 -0
  2. package/assembly/scdb/README.md +74 -0
  3. package/assembly/scdb/bench.mjs +32 -0
  4. package/assembly/scdb/decoder.ts +217 -0
  5. package/assembly/scdb/decoder.wasm +0 -0
  6. package/assembly/scdb/inline-wasm-base64.mjs +24 -0
  7. package/dist/dts/connect/connect.d.ts +2 -0
  8. package/dist/dts/connect/connect.d.ts.map +1 -1
  9. package/dist/dts/connect/http.connect.d.ts +10 -0
  10. package/dist/dts/connect/http.connect.d.ts.map +1 -1
  11. package/dist/dts/connect/message.d.ts +18 -0
  12. package/dist/dts/connect/message.d.ts.map +1 -1
  13. package/dist/dts/connect/scdbStreamDecoder.d.ts +66 -0
  14. package/dist/dts/connect/scdbStreamDecoder.d.ts.map +1 -0
  15. package/dist/dts/connect/socket.d.ts +23 -0
  16. package/dist/dts/connect/socket.d.ts.map +1 -1
  17. package/dist/dts/connect/socket.types.d.ts +14 -0
  18. package/dist/dts/connect/socket.types.d.ts.map +1 -1
  19. package/dist/dts/datasource/datasource.d.ts.map +1 -1
  20. package/dist/dts/datasource/datasource.types.d.ts +8 -0
  21. package/dist/dts/datasource/datasource.types.d.ts.map +1 -1
  22. package/dist/dts/datasource/index.d.ts +1 -0
  23. package/dist/dts/datasource/index.d.ts.map +1 -1
  24. package/dist/dts/datasource/scdb/base64.d.ts +6 -0
  25. package/dist/dts/datasource/scdb/base64.d.ts.map +1 -0
  26. package/dist/dts/datasource/scdb/dictionaryHash.d.ts +40 -0
  27. package/dist/dts/datasource/scdb/dictionaryHash.d.ts.map +1 -0
  28. package/dist/dts/datasource/scdb/index.d.ts +6 -0
  29. package/dist/dts/datasource/scdb/index.d.ts.map +1 -0
  30. package/dist/dts/datasource/scdb/scdb-js-bench.d.mts +2 -0
  31. package/dist/dts/datasource/scdb/scdb-js-bench.d.mts.map +1 -0
  32. package/dist/dts/datasource/scdb/scdbDecode.d.ts +24 -0
  33. package/dist/dts/datasource/scdb/scdbDecode.d.ts.map +1 -0
  34. package/dist/dts/datasource/scdb/scdbDecoder.d.ts +42 -0
  35. package/dist/dts/datasource/scdb/scdbDecoder.d.ts.map +1 -0
  36. package/dist/dts/datasource/scdb/scdbWasmDecoder.d.ts +27 -0
  37. package/dist/dts/datasource/scdb/scdbWasmDecoder.d.ts.map +1 -0
  38. package/dist/dts/datasource/scdb/scdbjDecoder.d.ts +35 -0
  39. package/dist/dts/datasource/scdb/scdbjDecoder.d.ts.map +1 -0
  40. package/dist/dts/datasource/scdb/wasm/decoder.wasm.base64.d.ts +7 -0
  41. package/dist/dts/datasource/scdb/wasm/decoder.wasm.base64.d.ts.map +1 -0
  42. package/dist/dts/testing/mocks/connect/socket.d.ts +1 -0
  43. package/dist/dts/testing/mocks/connect/socket.d.ts.map +1 -1
  44. package/dist/esm/connect/connect.js +22 -3
  45. package/dist/esm/connect/http.connect.js +33 -1
  46. package/dist/esm/connect/message.js +3 -1
  47. package/dist/esm/connect/scdbStreamDecoder.js +160 -0
  48. package/dist/esm/connect/socket.js +72 -2
  49. package/dist/esm/datasource/datasource.js +3 -0
  50. package/dist/esm/datasource/index.js +1 -0
  51. package/dist/esm/datasource/scdb/base64.js +17 -0
  52. package/dist/esm/datasource/scdb/dictionaryHash.js +45 -0
  53. package/dist/esm/datasource/scdb/index.js +5 -0
  54. package/dist/esm/datasource/scdb/scdb-golden-v1.json +15 -0
  55. package/dist/esm/datasource/scdb/scdb-js-bench.mjs +461 -0
  56. package/dist/esm/datasource/scdb/scdbDecode.js +67 -0
  57. package/dist/esm/datasource/scdb/scdbDecoder.js +279 -0
  58. package/dist/esm/datasource/scdb/scdbWasmDecoder.js +213 -0
  59. package/dist/esm/datasource/scdb/scdbjDecoder.js +60 -0
  60. package/dist/esm/datasource/scdb/wasm/decoder.wasm.base64.js +6 -0
  61. package/dist/esm/testing/mocks/connect/socket.js +3 -0
  62. package/dist/foundation-comms.api.json +1453 -8
  63. package/dist/foundation-comms.d.ts +251 -0
  64. package/package.json +14 -12
@@ -20,6 +20,9 @@ import { TypedBroadcastChannel } from '@genesislcap/foundation-broadcast-channel
20
20
  import { User as User_2 } from '@genesislcap/foundation-user';
21
21
  import { UUID } from '@genesislcap/foundation-utils';
22
22
 
23
+ /** @internal */
24
+ export declare function assertScdbMagic(bytes: Uint8Array): void;
25
+
23
26
  /**
24
27
  * Auth is the main interface for authenticating with a Genesis Server endpoint.
25
28
  * @public
@@ -164,6 +167,13 @@ export declare type BasicCredentialsInput = {
164
167
  */
165
168
  export declare function buildRequestCacheKey(resourceName: string, params?: RequestParams): string;
166
169
 
170
+ export declare interface ColumnarQueryUpdate {
171
+ ENCODING?: string;
172
+ ROW?: Array<Record<string, unknown>>;
173
+ RBUF?: Uint8Array | string | number[];
174
+ SCDBJ?: ScdbjPayload;
175
+ }
176
+
167
177
  /**
168
178
  * @public
169
179
  */
@@ -1001,6 +1011,8 @@ export declare type DataserverParams = {
1001
1011
  MOVING_VIEW?: boolean;
1002
1012
  ORDER_BY?: string;
1003
1013
  REVERSE?: boolean;
1014
+ /** Per-subscription columnar encoding override; overrides ConnectConfig.connect.dataserverEncoding. */
1015
+ ENCODING?: ScdbEncoding;
1004
1016
  };
1005
1017
 
1006
1018
  /**
@@ -1753,6 +1765,13 @@ export declare interface DatasourceOptions {
1753
1765
  * @remarks Only works with DATASERVER resources.
1754
1766
  */
1755
1767
  reverse?: boolean;
1768
+ /**
1769
+ * Per-datasource columnar payload encoding, overriding the app-wide
1770
+ * `ConnectConfig.connect.dataserverEncoding`. `'SCDBJ_V1'` (JSON-columnar) or `'SCDB_V1'` (binary).
1771
+ * Negotiated + decoded transparently. Undefined => use the app-wide setting (or row mode).
1772
+ * @remarks Only works with DATASERVER resources.
1773
+ */
1774
+ encoding?: ScdbEncoding;
1756
1775
  /**
1757
1776
  * Whether to disable polling when using request/reply
1758
1777
  * @remarks Only works with REQUEST_SERVER resources, which have no stream and so poll for
@@ -1847,6 +1866,47 @@ export declare interface Dataview {
1847
1866
  hideSearch?: boolean;
1848
1867
  }
1849
1868
 
1869
+ /**
1870
+ * Decodes a QUERY_UPDATE to row objects. Chooses by `ENCODING`:
1871
+ * - `SCDB_V1` -> binary blob: WASM decoder when provided (fastest), else pure-JS.
1872
+ * - `SCDBJ_V1` -> JSON-columnar transpose.
1873
+ * - otherwise -> the message's existing `ROW` array (legacy).
1874
+ */
1875
+ export declare function decodeColumnarQueryUpdate(msg: ColumnarQueryUpdate, dictionary: readonly string[], wasm?: ScdbWasm): Array<Record<string, unknown>>;
1876
+
1877
+ /**
1878
+ * Decodes a self-describing columnar req/rep reply (dictionary inline) into plain result rows
1879
+ * (cells only, no synthetic `DETAILS`). req/rep replies are full result sets, so unlike a dataserver
1880
+ * `QUERY_UPDATE` they carry no per-row operation / rowRef.
1881
+ */
1882
+ export declare function decodeColumnarReply(msg: ColumnarQueryUpdate, dictionary: readonly string[]): Array<Record<string, unknown>>;
1883
+
1884
+ /**
1885
+ * Decodes an SCDB `RBUF` blob into delta records, using the column dictionary (ordered field-name
1886
+ * list) the client derives from the resource's metadata and validates against the server's
1887
+ * `DICT_HASH`. Each record's `cells` is a fresh target object passed to [decodeColumns].
1888
+ */
1889
+ export declare function decodeScdb(bytes: Uint8Array, dictionary: readonly string[]): ScdbRecord[];
1890
+
1891
+ /**
1892
+ * Transposes a parsed SCDBJ payload into plain result rows (cells only, no `DETAILS`). Used for
1893
+ * req/rep replies, which are full result sets without per-row operation / rowRef semantics.
1894
+ */
1895
+ export declare function decodeScdbjToCells(payload: ScdbjPayload, dictionary: readonly string[]): Array<Record<string, unknown>>;
1896
+
1897
+ /**
1898
+ * Transposes a parsed SCDBJ payload into the legacy dataserver ROW shape:
1899
+ * `[{ ...cells, DETAILS: { OPERATION, ROW_REF } }]`, using the column dictionary.
1900
+ */
1901
+ export declare function decodeScdbjToRows(payload: ScdbjPayload, dictionary: readonly string[]): Array<Record<string, unknown>>;
1902
+
1903
+ /**
1904
+ * Reconstructs the legacy `ROW` array shape directly (the hot path used in the live socket flow):
1905
+ * `[{ ...cells, DETAILS: { OPERATION, ROW_REF } }]`. Builds straight into the row objects with no
1906
+ * intermediate record/cells allocation.
1907
+ */
1908
+ export declare function decodeScdbToRows(bytes: Uint8Array, dictionary: readonly string[]): Array<Record<string, unknown>>;
1909
+
1850
1910
  /**
1851
1911
  * The default implementation for the Auth interface.
1852
1912
  * @public
@@ -1902,6 +1962,7 @@ export declare class DefaultConnect implements Connect {
1902
1962
  private config;
1903
1963
  private transport;
1904
1964
  isWorking: boolean;
1965
+ private readonly httpScdbDecoder;
1905
1966
  get isConnected(): boolean;
1906
1967
  get isConnectedSubject(): BehaviorSubject<boolean>;
1907
1968
  get isConnected$(): Observable<boolean>;
@@ -1921,6 +1982,7 @@ export declare class DefaultConnect implements Connect {
1921
1982
  * @internal
1922
1983
  */
1923
1984
  private get httpHost();
1985
+ private requestOverHttp;
1924
1986
  /**
1925
1987
  * Sends an event/commit or metadata-style message, routing it over HTTP (POST) when
1926
1988
  * `useHttpReqRep` is active and falling back to the WebSocket otherwise.
@@ -2272,6 +2334,9 @@ export declare class DefaultHttpConnect implements Connect {
2272
2334
  */
2273
2335
  private streams;
2274
2336
  private inFlightRequests;
2337
+ private readonly scdbDecoder;
2338
+ /** Guards the one-time warning when a columnar encoding is stripped from a dataserver HTTP call. */
2339
+ private dataserverEncodingStrippedWarned;
2275
2340
  /**
2276
2341
  * Promise that tracks an ongoing session refresh to prevent concurrent refreshes from the same instance.
2277
2342
  * @internal
@@ -2312,6 +2377,13 @@ export declare class DefaultHttpConnect implements Connect {
2312
2377
  getMetadata(resourceName: string, useCache?: boolean): Promise<Metadata>;
2313
2378
  getJSONSchema(resourceName: string): Promise<SchemaResponse>;
2314
2379
  request(resourceName: string, params?: RequestParams, useCache?: boolean): Promise<Message>;
2380
+ /**
2381
+ * Removes a negotiated columnar `ENCODING` from a dataserver HTTP message. Dataserver columnar
2382
+ * encodings batch updates across a streamed connection in a way the HTTP poll/snapshot model
2383
+ * cannot reconstruct, so dataserver-over-HTTP always uses row mode (req/rep-over-HTTP is fine and
2384
+ * is handled separately). Warns once if anything was stripped so misconfiguration is visible.
2385
+ */
2386
+ private stripDataserverColumnarEncoding;
2315
2387
  getAvailableResources(params?: any, useCache?: boolean): Promise<ResourcesMessage>;
2316
2388
  commitEvent(eventName: string, params?: CommitParams): Promise<Message>;
2317
2389
  private maybeTurbo;
@@ -2430,6 +2502,12 @@ export declare const defaultKVStorageConfig: KVStorageConfig;
2430
2502
  export declare class DefaultMessageBuilder implements MessageBuilder {
2431
2503
  private session;
2432
2504
  private uuid;
2505
+ /**
2506
+ * Columnar payload encoding to request on DATA_LOGON via `DETAILS.ENCODING`
2507
+ * (`'SCDB_V1'` binary, `'SCDBJ_V1'` json-columnar). Undefined => legacy row mode.
2508
+ * A per-request `params.ENCODING` overrides this default.
2509
+ */
2510
+ scdbEncoding?: ScdbEncoding;
2433
2511
  /**
2434
2512
  * UUID will be created in the DI with the App specific requirements.
2435
2513
  * Keeping it encapsulated means messages will always conform.
@@ -2672,7 +2750,10 @@ export declare class DefaultSocket implements Socket {
2672
2750
  private websocket;
2673
2751
  private wsMessages;
2674
2752
  private wsMessageHandlers;
2753
+ private _scdbDecoder;
2754
+ private scdbWasmRequested;
2675
2755
  http: Http;
2756
+ private metaCache;
2676
2757
  get isConfigured(): boolean;
2677
2758
  get isConnecting(): boolean;
2678
2759
  get isConnected(): boolean;
@@ -2698,6 +2779,8 @@ export declare class DefaultSocket implements Socket {
2698
2779
  * Temp putting the user in place to bridge the hasValidSession logic.
2699
2780
  */
2700
2781
  user: User_2, config: ConnectConfig);
2782
+ /** Makes SCDB columnar payloads transparent (no-op unless an encoding was negotiated). */
2783
+ private get scdbDecoder();
2701
2784
  private get heartbeatLoggingIsEnabled();
2702
2785
  private get messageLoggingIsEnabled();
2703
2786
  connect(host?: string, connectOptions?: SocketConnectOptions, reconnectOptions?: SocketReconnectOptions): Promise<boolean>;
@@ -2730,6 +2813,19 @@ export declare class DefaultSocket implements Socket {
2730
2813
  private setMessageHandler;
2731
2814
  private sendDataLogoff;
2732
2815
  private removeMessageHandler;
2816
+ /**
2817
+ * Wires the SCDB decoder's metadata-refresh hook, used to fetch a resource's missing or stale
2818
+ * metadata. The host passes a force-refresh, e.g. `Connect.getMetadata(resource, false)`.
2819
+ */
2820
+ setScdbMetadataRefresher(refresher: (resourceName: string) => void | Promise<unknown>): void;
2821
+ /**
2822
+ * Loads the bundled WASM decoder for the `SCDB_V1` binary encoding once (lazy, idempotent). Called
2823
+ * eagerly when the app-wide `dataserverEncoding` is binary, and on demand the first time a binary
2824
+ * payload is seen (so a per-datasource/grid `encoding: 'SCDB_V1'` also gets the fast-path, not just
2825
+ * the app-wide opt-in). On any failure (no WebAssembly, CSP, SSR) we silently keep the pure-JS
2826
+ * decoder — output is identical.
2827
+ */
2828
+ private ensureScdbWasm;
2733
2829
  private getMessageHandler;
2734
2830
  private logMessageTypeFlow;
2735
2831
  }
@@ -2783,6 +2879,42 @@ export declare function describeDataserverPagingStop(stop: {
2783
2879
  attribute: string;
2784
2880
  }): string | undefined;
2785
2881
 
2882
+ /**
2883
+ * Ordered field-name list (the SCDB dictionary) for a resource, from its metadata. The order MUST
2884
+ * match the server's, which derives the dictionary per resource type: a DATASERVER hashes its `FIELD`
2885
+ * list, a REQUEST_SERVER its `REPLY_FIELD` (⇒ `REPLY.FIELD`) list. Selecting by `TYPE` — rather than
2886
+ * "first non-null" — matters because a metadata object can legitimately carry BOTH `FIELD` and
2887
+ * `REPLY_FIELD`; picking the wrong one yields a hash that never matches the server's `DICT_HASH`, so
2888
+ * no columnar message for that resource can be decoded. Falls back to a lenient scan for unknown types.
2889
+ */
2890
+ export declare function dictionaryFromMetadata(metadata: {
2891
+ TYPE?: string;
2892
+ FIELD?: FieldLike[];
2893
+ REPLY_FIELD?: FieldLike[];
2894
+ REPLY?: {
2895
+ FIELD?: FieldLike[];
2896
+ };
2897
+ }): string[];
2898
+
2899
+ /**
2900
+ * Dictionary derivation + fingerprinting for the metadata-driven dictionary mechanism.
2901
+ *
2902
+ * The server no longer ships the column dictionary; instead the client derives it from the resource
2903
+ * metadata it already holds (`id = index` into the ordered field list) and validates it against a
2904
+ * small hash the server sends with the columnar payload. A columnar message that fails validation
2905
+ * is not decoded.
2906
+ */
2907
+ /**
2908
+ * FNV-1a 32-bit hash of the field names joined by '\n', as lowercase 8-char hex. MUST match the
2909
+ * Kotlin `ColumnDictionary.contentHash` in genesis-columnar (cross-language vector:
2910
+ * ['QUANTITY','PRICE','SYMBOL'] -> '40e6db4f').
2911
+ *
2912
+ * Hashes UTF-16 code units (`charCodeAt`), matching Kotlin's `Char.code` — NOT the UTF-8 bytes used for
2913
+ * on-wire strings. Field names are ASCII in practice so the two coincide; keep both ends on UTF-16 units
2914
+ * (do not switch to UTF-8 bytes) or a non-ASCII field name would hash differently across languages.
2915
+ */
2916
+ export declare function dictionaryHash(fieldNames: readonly string[]): string;
2917
+
2786
2918
  /**
2787
2919
  * EntityDatasource DI interface.
2788
2920
  *
@@ -2937,6 +3069,11 @@ export declare const exponentialScheduler: SocketReconnectScheduler;
2937
3069
  */
2938
3070
  export declare const extractFieldDefinitions: (metadata: Metadata) => MetadataDetail[];
2939
3071
 
3072
+ /** Minimal shape of the cached resource metadata fields we need. */
3073
+ declare interface FieldLike {
3074
+ NAME: string;
3075
+ }
3076
+
2940
3077
  /**
2941
3078
  * Field Metadata definition.
2942
3079
  * @public
@@ -3265,6 +3402,13 @@ export declare type GetCredentialOptions = CredentialRequestOptions & {};
3265
3402
  */
3266
3403
  export declare function getDatasource(): Datasource;
3267
3404
 
3405
+ /**
3406
+ * Lazily instantiates (once) the bundled decoder from inlined base64 — no asset/fetch config, works
3407
+ * in any bundler and SSR. This is what the socket layer uses for the `SCDB_V1` fast-path. Rejects if
3408
+ * WebAssembly is unavailable; callers fall back to the pure-JS decoder.
3409
+ */
3410
+ export declare function getDefaultScdbWasm(): Promise<ScdbWasm>;
3411
+
3268
3412
  /**
3269
3413
  * Gets GenesisResources from the DI container.
3270
3414
  *
@@ -3518,6 +3662,12 @@ export declare type IndexDetail = {
3518
3662
  FIELDS: string;
3519
3663
  };
3520
3664
 
3665
+ /**
3666
+ * Instantiates the decoder. Defaults to the inlined `decoder.wasm`; pass your own bytes (bundler
3667
+ * import / fetch / fs.readFile) to override. Returns an object whose `decodeToRows` is synchronous.
3668
+ */
3669
+ export declare function initScdbWasm(wasmBytes?: BufferSource): Promise<ScdbWasm>;
3670
+
3521
3671
  /**
3522
3672
  * Regular Expression to test valid WebSocket (wss and ws) hosts
3523
3673
  * @public
@@ -3792,6 +3942,11 @@ declare type Message_2 = any;
3792
3942
  * @public
3793
3943
  */
3794
3944
  export declare interface MessageBuilder {
3945
+ /**
3946
+ * Columnar payload encoding to request on DATA_LOGON (`'SCDB_V1'` | `'SCDBJ_V1'`). Undefined =>
3947
+ * legacy row mode. Normally set from `ConnectConfig.connect.dataserverEncoding`.
3948
+ */
3949
+ scdbEncoding?: ScdbEncoding;
3795
3950
  /**
3796
3951
  * Creates a login message.
3797
3952
  *
@@ -4061,6 +4216,8 @@ export declare namespace MessageDetails {
4061
4216
  */
4062
4217
  export type DataserverRequest = {
4063
4218
  DATASOURCE_NAME: string;
4219
+ /** Requested columnar payload encoding: 'SCDB_V1' (binary) or 'SCDBJ_V1' (json-columnar). */
4220
+ ENCODING?: ScdbEncoding;
4064
4221
  };
4065
4222
  /**
4066
4223
  * Details type to request FEATURE metadata
@@ -4551,6 +4708,8 @@ export declare type RequestDetailsParam = {
4551
4708
  OFFSET?: number;
4552
4709
  ORDER_BY?: string;
4553
4710
  VIEW_NUMBER?: number;
4711
+ /** Requested columnar reply encoding (e.g. 'SCDBJ_V1'); mirrors the dataserver negotiation. */
4712
+ ENCODING?: ScdbEncoding;
4554
4713
  };
4555
4714
 
4556
4715
  /**
@@ -4663,6 +4822,79 @@ export declare type RowData = {
4663
4822
  ROW_REF: string;
4664
4823
  };
4665
4824
 
4825
+ /** The columnar wire encodings a client can negotiate via `DETAILS.ENCODING` (absent = legacy row mode). */
4826
+ export declare type ScdbEncoding = 'SCDB_V1' | 'SCDBJ_V1';
4827
+
4828
+ /**
4829
+ * SCDBJ (JSON-columnar) decoder.
4830
+ *
4831
+ * The no-WASM peer of the binary `scdbDecoder`. The server sends a `QUERY_UPDATE` whose payload is a
4832
+ * plain JSON object (decoded for free by the existing envelope `JSON.parse`); this transposes it back
4833
+ * into the legacy `ROW` array of row objects that ag-Grid consumes. Because native `JSON.parse` does
4834
+ * the bulk work and only the transpose is JS, this is at parity with row-JSON on a full snapshot and
4835
+ * faster on deltas, while being ~2x smaller on the wire (no repeated field-name keys).
4836
+ *
4837
+ * Wire shape (short keys; see genesis-columnar/docs/scdb-v1.md):
4838
+ * { n, r:[rowRef strings], o: opCode | [opCodes], c:[ { i:colId, x?:[presentIdx], v:[values] } ] }
4839
+ * `x` omitted => dense column. Values are aligned to the present cells; a `null` entry is an explicit
4840
+ * change-to-null. Column ids index the metadata-derived dictionary.
4841
+ */
4842
+ export declare interface ScdbjPayload {
4843
+ n: number;
4844
+ r: string[];
4845
+ o: number | number[];
4846
+ c: Array<{
4847
+ i: number;
4848
+ x?: number[];
4849
+ v: unknown[];
4850
+ }>;
4851
+ }
4852
+
4853
+ /**
4854
+ * SCDB v1 (Sparse Columnar Delta Block) decoder.
4855
+ *
4856
+ * Decodes the binary `RBUF` payload that a Genesis dataserver sends when a client negotiates
4857
+ * `DETAILS.ENCODING = SCDB_V1`. The wire format is defined, language-neutrally, in the server repo
4858
+ * at `genesis-columnar/docs/scdb-v1.md` and is pinned by the shared golden vectors in
4859
+ * `scdb-golden-v1.json` (this directory). The Kotlin `ScdbReader` is the reference implementation;
4860
+ * this decoder must stay byte-for-byte compatible with it.
4861
+ *
4862
+ * Performance notes (see scdb-js-bench.mjs):
4863
+ * - single pass straight into the output objects — no per-column intermediate arrays;
4864
+ * - dense columns (flagged by the encoder) skip the presence bitmap and the per-row presence test;
4865
+ * - varints decode in Number space (exact for |v| < 2^53), using BigInt only past 49 bits;
4866
+ * - strings take a manual ASCII fast-path (TextDecoder has a fixed per-call overhead).
4867
+ *
4868
+ * Browser contract:
4869
+ * - operates over the `Uint8Array` the existing msgpack envelope decoder already produces for `RBUF`;
4870
+ * - `ROW_REF` decodes to a `string` (sent as decimal text) — matches the existing contract, no BigInt;
4871
+ * - 64-bit LONG *values* decode to `number` when safe, else `bigint` (the customNumberParser rule).
4872
+ */
4873
+ export declare type ScdbOperation = 'INSERT' | 'MODIFY' | 'DELETE';
4874
+
4875
+ /** A decoded delta row. `cells` contains only changed fields; an explicit `null` is change-to-null. */
4876
+ export declare interface ScdbRecord {
4877
+ rowRef: string;
4878
+ operation: ScdbOperation;
4879
+ cells: Record<string, unknown>;
4880
+ }
4881
+
4882
+ /**
4883
+ * WASM fast-path decoder for the binary SCDB (`SCDB_V1`) payload.
4884
+ *
4885
+ * Instantiates the AssemblyScript decoder (`wasm/decoder.wasm`), which parses the binary blob at
4886
+ * near-native speed into a columnar result in linear memory; this module then assembles the legacy
4887
+ * `ROW` array of objects that ag-Grid consumes. Measured ~1.5x faster than native `JSON.parse` on a
4888
+ * full snapshot and ~2.5x on deltas, while the payload stays ~3x smaller on the wire. See
4889
+ * `wasm/README.md` and the benchmark for numbers.
4890
+ *
4891
+ * If wasm is unavailable (or instantiation fails), callers fall back to the pure-JS `decodeScdbToRows`
4892
+ * from `scdbDecoder.ts` — same output, no toolchain.
4893
+ */
4894
+ export declare interface ScdbWasm {
4895
+ decodeToRows(blob: Uint8Array, dictionary: readonly string[]): Array<Record<string, unknown>>;
4896
+ }
4897
+
4666
4898
  /**
4667
4899
  * Schema Response definition.
4668
4900
  * @public
@@ -4912,6 +5144,11 @@ export declare interface Socket extends Omit<SocketStatus, 'serialize' | 'onClos
4912
5144
  */
4913
5145
  sendForStreamWithoutTeardown<T>(message: Message<T | any>, onMessage: Function, onError: Function): Observable<Message>;
4914
5146
  socketMessages(): SocketSubject<Message>;
5147
+ /**
5148
+ * Wires a metadata-refresh hook for the SCDB columnar decoder, used to fetch a resource's missing
5149
+ * or stale metadata (e.g. `getMetadata(r, false)`).
5150
+ */
5151
+ setScdbMetadataRefresher?(refresher: (resourceName: string) => void | Promise<unknown>): void;
4915
5152
  host: string;
4916
5153
  }
4917
5154
 
@@ -4975,6 +5212,19 @@ export declare type SocketConnectOptions = {
4975
5212
  * The path to a proxy server to use for the connection.
4976
5213
  */
4977
5214
  proxyPath?: string;
5215
+ /**
5216
+ * Opt in to a columnar dataserver payload encoding for all DATA_LOGON subscriptions, negotiated
5217
+ * transparently — every consumer (grids, React wrappers, FAST components, custom datasources)
5218
+ * benefits with no code change, since request + decode happen in this comms layer.
5219
+ *
5220
+ * - `'SCDBJ_V1'` — JSON-columnar: ~2x smaller, decoded with native JSON.parse + transpose. No
5221
+ * extra runtime; works in every bundler and SSR. Recommended default.
5222
+ * - `'SCDB_V1'` — binary blob: ~3x smaller and ~1.5–2.5x faster to decode via the bundled WASM
5223
+ * decoder (falls back to a pure-JS decoder if WebAssembly is unavailable).
5224
+ *
5225
+ * Undefined (default) keeps the legacy row encoding. Old servers ignore it and send rows.
5226
+ */
5227
+ dataserverEncoding?: ScdbEncoding;
4978
5228
  };
4979
5229
 
4980
5230
  /**
@@ -5042,6 +5292,7 @@ export declare class SocketMock implements Socket {
5042
5292
  sendForStream<T>(message: Message<any>, onMessage: Function, onError: Function, onComplete?: Function): Observable<Message>;
5043
5293
  sendForStreamWithoutTeardown<T>(message: Message<any>, onMessage: Function, onError: Function): Observable<Message>;
5044
5294
  socketMessages(): SocketSubject<Message>;
5295
+ setScdbMetadataRefresher(): void;
5045
5296
  reset(): void;
5046
5297
  }
5047
5298
 
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@genesislcap/foundation-comms",
3
3
  "description": "Genesis Foundation UI Comms",
4
- "version": "15.79.2",
4
+ "version": "15.80.0",
5
5
  "sideEffects": false,
6
6
  "license": "SEE LICENSE IN license.txt",
7
7
  "main": "dist/esm/index.js",
@@ -42,6 +42,7 @@
42
42
  "build": "genx build -b ts",
43
43
  "build:webpack": "genx build",
44
44
  "build:vite": "genx build -b vite",
45
+ "build:wasm": "asc --target release && node assembly/scdb/inline-wasm-base64.mjs",
45
46
  "build:webpack:stats": "genx analyze",
46
47
  "circular": "npx -y madge --extensions ts --circular ./src",
47
48
  "clean": "rimraf dist temp tsconfig.tsbuildinfo",
@@ -74,23 +75,24 @@
74
75
  }
75
76
  },
76
77
  "devDependencies": {
77
- "@genesislcap/foundation-testing": "15.79.2",
78
- "@genesislcap/genx": "15.79.2",
79
- "@genesislcap/ts-builder": "15.79.2",
80
- "@genesislcap/uvu-playwright-builder": "15.79.2",
81
- "@genesislcap/vite-builder": "15.79.2",
82
- "@genesislcap/webpack-builder": "15.79.2",
78
+ "@genesislcap/foundation-testing": "15.80.0",
79
+ "@genesislcap/genx": "15.80.0",
80
+ "@genesislcap/ts-builder": "15.80.0",
81
+ "@genesislcap/uvu-playwright-builder": "15.80.0",
82
+ "@genesislcap/vite-builder": "15.80.0",
83
+ "@genesislcap/webpack-builder": "15.80.0",
83
84
  "@types/js-cookie": "^3.0.2",
84
85
  "@types/json-schema": "^7.0.11",
85
86
  "@types/webappsec-credential-management": "^0.6.2",
87
+ "assemblyscript": "^0.28.19",
86
88
  "sinon": "^17.0.1"
87
89
  },
88
90
  "dependencies": {
89
- "@genesislcap/foundation-broadcast-channel": "15.79.2",
90
- "@genesislcap/foundation-logger": "15.79.2",
91
- "@genesislcap/foundation-user": "15.79.2",
92
- "@genesislcap/foundation-utils": "15.79.2",
93
- "@genesislcap/web-core": "15.79.2",
91
+ "@genesislcap/foundation-broadcast-channel": "15.80.0",
92
+ "@genesislcap/foundation-logger": "15.80.0",
93
+ "@genesislcap/foundation-user": "15.80.0",
94
+ "@genesislcap/foundation-utils": "15.80.0",
95
+ "@genesislcap/web-core": "15.80.0",
94
96
  "@microsoft/fast-element": "1.14.0",
95
97
  "@microsoft/fast-foundation": "2.50.0",
96
98
  "bowser": "^2.11.0",