@genesislcap/foundation-comms 15.50.0 → 15.50.1

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.
@@ -0,0 +1,69 @@
1
+ /**
2
+ * Where paging a DATASERVER subscription with MORE_ROWS stands.
3
+ * - `more`: more rows can be requested.
4
+ * - `end`: MORE_ROWS is false, so the data ran out.
5
+ * - `view-full`: the client holds MAX_VIEW rows, so GSF will send no more, although MORE_ROWS
6
+ * stays true while matching rows remain past the cap.
7
+ * - `stalled`: a MORE_ROWS was answered with no rows and MORE_ROWS still true while the view has
8
+ * room. That is not a MAX_VIEW cap - GSF sends the same empty page when building the reply
9
+ * failed - but requesting again on every empty page could loop, so paging stops.
10
+ * @internal
11
+ */
12
+ export type DataserverPagingStatus = 'more' | 'end' | 'view-full' | 'stalled';
13
+ /**
14
+ * The view cap GSF applies for the MAX_VIEW a DATA_LOGON sent.
15
+ * @remarks Mirrors GSF's `ClientOptions`: a missing MAX_VIEW (or a `null`, which is how `NaN`
16
+ * serialises) falls back to the server default of 1000, and 0 is an unlimited view.
17
+ * @param maxView - The MAX_VIEW the subscription was opened with.
18
+ * @returns The cap, or `Infinity` for an unlimited view.
19
+ * @internal
20
+ */
21
+ export declare function resolveMaxView(maxView: unknown): number;
22
+ /**
23
+ * Reads where paging a DATASERVER subscription stands after a message.
24
+ * @remarks GSF (8.15.x) does not end the stream when a fixed view fills at MAX_VIEW: it keeps
25
+ * MORE_ROWS true while matching rows remain past the cap, and answers every later MORE_ROWS with
26
+ * an empty `{ QUERY_UPDATE, MORE_ROWS: true }`, still moving its cursor past the rows the view had
27
+ * no room for. A client that pages on MORE_ROWS has to stop at the cap itself. Once the server
28
+ * stops reading past a full view (genesislcap/genesis-server#7117) the reply after the cap becomes
29
+ * an empty `MORE_ROWS: false`; the row count check here still catches the cap first.
30
+ *
31
+ * A moving view at the cap evicts its oldest rows for newer ones rather than filling up, so it
32
+ * reports `more`: an empty page there only means the batch held nothing newer than the view.
33
+ * @internal
34
+ */
35
+ export declare function dataserverPagingStatus(state: {
36
+ /** The latest MORE_ROWS the server sent. */
37
+ moreRows: boolean | undefined;
38
+ /** Whether this message answered a MORE_ROWS request with no rows. */
39
+ emptyReply: boolean;
40
+ /** Rows the client holds from the view. */
41
+ rowsHeld: number;
42
+ /** The MAX_VIEW the subscription was opened with. */
43
+ maxView: unknown;
44
+ /** Whether the subscription is a moving view. */
45
+ movingView?: boolean;
46
+ }): DataserverPagingStatus;
47
+ /**
48
+ * The warning to log when paging stops short of the data.
49
+ * @param stop - Why paging stopped, and what is known about the view.
50
+ * @returns The message, or `undefined` when the stop needs no warning: the view reached MAX_VIEW
51
+ * exactly where an unfiltered ROWS_COUNT says the data ends.
52
+ * @internal
53
+ */
54
+ export declare function describeDataserverPagingStop(stop: {
55
+ status: 'view-full' | 'stalled';
56
+ resourceName: string;
57
+ rowsHeld: number;
58
+ maxView: unknown;
59
+ /**
60
+ * Whether the server confirmed rows remain past the view, by answering a MORE_ROWS with an
61
+ * empty page.
62
+ */
63
+ emptyReply: boolean;
64
+ /** The resource's ROWS_COUNT, only when the view has no criteria (it ignores CRITERIA_MATCH). */
65
+ totalRows?: number;
66
+ /** The attribute that sets MAX_VIEW on the element, such as `max-view`. */
67
+ attribute: string;
68
+ }): string | undefined;
69
+ //# sourceMappingURL=dataserverPaging.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"dataserverPaging.d.ts","sourceRoot":"","sources":["../../../src/datasource/dataserverPaging.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AACH,MAAM,MAAM,sBAAsB,GAAG,MAAM,GAAG,KAAK,GAAG,WAAW,GAAG,SAAS,CAAC;AAE9E;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAMvD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE;IAC5C,4CAA4C;IAC5C,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;IAC9B,sEAAsE;IACtE,UAAU,EAAE,OAAO,CAAC;IACpB,2CAA2C;IAC3C,QAAQ,EAAE,MAAM,CAAC;IACjB,qDAAqD;IACrD,OAAO,EAAE,OAAO,CAAC;IACjB,iDAAiD;IACjD,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB,GAAG,sBAAsB,CAQzB;AAED;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAAC,IAAI,EAAE;IACjD,MAAM,EAAE,WAAW,GAAG,SAAS,CAAC;IAChC,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB;;;OAGG;IACH,UAAU,EAAE,OAAO,CAAC;IACpB,iGAAiG;IACjG,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2EAA2E;IAC3E,SAAS,EAAE,MAAM,CAAC;CACnB,GAAG,MAAM,GAAG,SAAS,CAuBrB"}
@@ -1,5 +1,6 @@
1
1
  export * from './criteriaFiltersToFields';
2
2
  export * from './dataServerResultFilter';
3
+ export * from './dataserverPaging';
3
4
  export * from './datasource.config';
4
5
  export * from './datasource.mixins';
5
6
  export * from './datasource';
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/datasource/index.ts"],"names":[],"mappings":"AAAA,cAAc,2BAA2B,CAAC;AAC1C,cAAc,0BAA0B,CAAC;AACzC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/datasource/index.ts"],"names":[],"mappings":"AAAA,cAAc,2BAA2B,CAAC;AAC1C,cAAc,0BAA0B,CAAC;AACzC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC"}
@@ -0,0 +1,70 @@
1
+ import { DatasourceDefaults } from './datasource.config';
2
+ /**
3
+ * The view cap GSF applies for the MAX_VIEW a DATA_LOGON sent.
4
+ * @remarks Mirrors GSF's `ClientOptions`: a missing MAX_VIEW (or a `null`, which is how `NaN`
5
+ * serialises) falls back to the server default of 1000, and 0 is an unlimited view.
6
+ * @param maxView - The MAX_VIEW the subscription was opened with.
7
+ * @returns The cap, or `Infinity` for an unlimited view.
8
+ * @internal
9
+ */
10
+ export function resolveMaxView(maxView) {
11
+ const value = maxView === null || maxView === undefined ? NaN : Number(maxView);
12
+ if (!Number.isFinite(value)) {
13
+ return DatasourceDefaults.MAX_VIEW_1000;
14
+ }
15
+ return value === 0 ? Infinity : value;
16
+ }
17
+ /**
18
+ * Reads where paging a DATASERVER subscription stands after a message.
19
+ * @remarks GSF (8.15.x) does not end the stream when a fixed view fills at MAX_VIEW: it keeps
20
+ * MORE_ROWS true while matching rows remain past the cap, and answers every later MORE_ROWS with
21
+ * an empty `{ QUERY_UPDATE, MORE_ROWS: true }`, still moving its cursor past the rows the view had
22
+ * no room for. A client that pages on MORE_ROWS has to stop at the cap itself. Once the server
23
+ * stops reading past a full view (genesislcap/genesis-server#7117) the reply after the cap becomes
24
+ * an empty `MORE_ROWS: false`; the row count check here still catches the cap first.
25
+ *
26
+ * A moving view at the cap evicts its oldest rows for newer ones rather than filling up, so it
27
+ * reports `more`: an empty page there only means the batch held nothing newer than the view.
28
+ * @internal
29
+ */
30
+ export function dataserverPagingStatus(state) {
31
+ if (state.moreRows === false) {
32
+ return 'end';
33
+ }
34
+ if (state.rowsHeld >= resolveMaxView(state.maxView)) {
35
+ return state.movingView ? 'more' : 'view-full';
36
+ }
37
+ return state.emptyReply ? 'stalled' : 'more';
38
+ }
39
+ /**
40
+ * The warning to log when paging stops short of the data.
41
+ * @param stop - Why paging stopped, and what is known about the view.
42
+ * @returns The message, or `undefined` when the stop needs no warning: the view reached MAX_VIEW
43
+ * exactly where an unfiltered ROWS_COUNT says the data ends.
44
+ * @internal
45
+ */
46
+ export function describeDataserverPagingStop(stop) {
47
+ const cap = resolveMaxView(stop.maxView);
48
+ const capLabel = isUnset(stop.maxView) ? `${cap}, the server default` : `${cap}`;
49
+ const total = stop.totalRows;
50
+ if (stop.status === 'stalled') {
51
+ return `${stop.resourceName} stopped at ${stop.rowsHeld} rows: the server answered MORE_ROWS with an empty page while still reporting more rows, with room left in the view (MAX_VIEW ${capLabel}). This is not the MAX_VIEW cap; check the data server log for "Problem building client message".`;
52
+ }
53
+ // The data may end exactly at the cap: a chunked reply carries MORE_ROWS true on every chunk,
54
+ // and only a later empty message says false.
55
+ if (!stop.emptyReply && total !== undefined && total <= stop.rowsHeld) {
56
+ return undefined;
57
+ }
58
+ const totalPastCap = total !== undefined && total > stop.rowsHeld;
59
+ const ofTotal = totalPastCap ? ` of ${total}` : '';
60
+ // Rows past the cap are known to exist when the server said so with an empty page, or when an
61
+ // unfiltered ROWS_COUNT is larger; otherwise the row count is all there is to go on.
62
+ const pastCap = stop.emptyReply || totalPastCap
63
+ ? ' and the server holds more rows past it'
64
+ : ', so any rows past it are not loaded';
65
+ return `${stop.resourceName} stopped at ${stop.rowsHeld}${ofTotal} rows: the DATASERVER view is full at MAX_VIEW (${capLabel})${pastCap}. Raise ${stop.attribute} past the row count to reach the rest.`;
66
+ }
67
+ /** Whether no MAX_VIEW was given, so the server default applies. @internal */
68
+ function isUnset(maxView) {
69
+ return maxView === null || maxView === undefined || !Number.isFinite(Number(maxView));
70
+ }
@@ -1,5 +1,6 @@
1
1
  export * from './criteriaFiltersToFields';
2
2
  export * from './dataServerResultFilter';
3
+ export * from './dataserverPaging';
3
4
  export * from './datasource.config';
4
5
  export * from './datasource.mixins';
5
6
  export * from './datasource';
@@ -936,6 +936,45 @@ declare type DATA_LOGON_DETAILS = {
936
936
  REVERSE?: boolean;
937
937
  };
938
938
 
939
+ /**
940
+ * Where paging a DATASERVER subscription with MORE_ROWS stands.
941
+ * - `more`: more rows can be requested.
942
+ * - `end`: MORE_ROWS is false, so the data ran out.
943
+ * - `view-full`: the client holds MAX_VIEW rows, so GSF will send no more, although MORE_ROWS
944
+ * stays true while matching rows remain past the cap.
945
+ * - `stalled`: a MORE_ROWS was answered with no rows and MORE_ROWS still true while the view has
946
+ * room. That is not a MAX_VIEW cap - GSF sends the same empty page when building the reply
947
+ * failed - but requesting again on every empty page could loop, so paging stops.
948
+ * @internal
949
+ */
950
+ export declare type DataserverPagingStatus = 'more' | 'end' | 'view-full' | 'stalled';
951
+
952
+ /**
953
+ * Reads where paging a DATASERVER subscription stands after a message.
954
+ * @remarks GSF (8.15.x) does not end the stream when a fixed view fills at MAX_VIEW: it keeps
955
+ * MORE_ROWS true while matching rows remain past the cap, and answers every later MORE_ROWS with
956
+ * an empty `{ QUERY_UPDATE, MORE_ROWS: true }`, still moving its cursor past the rows the view had
957
+ * no room for. A client that pages on MORE_ROWS has to stop at the cap itself. Once the server
958
+ * stops reading past a full view (genesislcap/genesis-server#7117) the reply after the cap becomes
959
+ * an empty `MORE_ROWS: false`; the row count check here still catches the cap first.
960
+ *
961
+ * A moving view at the cap evicts its oldest rows for newer ones rather than filling up, so it
962
+ * reports `more`: an empty page there only means the batch held nothing newer than the view.
963
+ * @internal
964
+ */
965
+ export declare function dataserverPagingStatus(state: {
966
+ /** The latest MORE_ROWS the server sent. */
967
+ moreRows: boolean | undefined;
968
+ /** Whether this message answered a MORE_ROWS request with no rows. */
969
+ emptyReply: boolean;
970
+ /** Rows the client holds from the view. */
971
+ rowsHeld: number;
972
+ /** The MAX_VIEW the subscription was opened with. */
973
+ maxView: unknown;
974
+ /** Whether the subscription is a moving view. */
975
+ movingView?: boolean;
976
+ }): DataserverPagingStatus;
977
+
939
978
  /**
940
979
  * Parameters for a DATA_LOGON messages
941
980
  * @remarks
@@ -2711,6 +2750,29 @@ export declare class DefaultSocketStatus implements SocketStatus {
2711
2750
  onClose(event: CloseEvent): void;
2712
2751
  }
2713
2752
 
2753
+ /**
2754
+ * The warning to log when paging stops short of the data.
2755
+ * @param stop - Why paging stopped, and what is known about the view.
2756
+ * @returns The message, or `undefined` when the stop needs no warning: the view reached MAX_VIEW
2757
+ * exactly where an unfiltered ROWS_COUNT says the data ends.
2758
+ * @internal
2759
+ */
2760
+ export declare function describeDataserverPagingStop(stop: {
2761
+ status: 'view-full' | 'stalled';
2762
+ resourceName: string;
2763
+ rowsHeld: number;
2764
+ maxView: unknown;
2765
+ /**
2766
+ * Whether the server confirmed rows remain past the view, by answering a MORE_ROWS with an
2767
+ * empty page.
2768
+ */
2769
+ emptyReply: boolean;
2770
+ /** The resource's ROWS_COUNT, only when the view has no criteria (it ignores CRITERIA_MATCH). */
2771
+ totalRows?: number;
2772
+ /** The attribute that sets MAX_VIEW on the element, such as `max-view`. */
2773
+ attribute: string;
2774
+ }): string | undefined;
2775
+
2714
2776
  /**
2715
2777
  * EntityDatasource DI interface.
2716
2778
  *
@@ -4498,6 +4560,16 @@ export declare type RequestServerResult = {
4498
4560
  SEQUENCE_ID?: number;
4499
4561
  };
4500
4562
 
4563
+ /**
4564
+ * The view cap GSF applies for the MAX_VIEW a DATA_LOGON sent.
4565
+ * @remarks Mirrors GSF's `ClientOptions`: a missing MAX_VIEW (or a `null`, which is how `NaN`
4566
+ * serialises) falls back to the server default of 1000, and 0 is an unlimited view.
4567
+ * @param maxView - The MAX_VIEW the subscription was opened with.
4568
+ * @returns The cap, or `Infinity` for an unlimited view.
4569
+ * @internal
4570
+ */
4571
+ export declare function resolveMaxView(maxView: unknown): number;
4572
+
4501
4573
  declare type RESOURCE_DETAILS = {
4502
4574
  NAME: string;
4503
4575
  CREATED_AT: number;
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.50.0",
4
+ "version": "15.50.1",
5
5
  "sideEffects": false,
6
6
  "license": "SEE LICENSE IN license.txt",
7
7
  "main": "dist/esm/index.js",
@@ -74,23 +74,23 @@
74
74
  }
75
75
  },
76
76
  "devDependencies": {
77
- "@genesislcap/foundation-testing": "15.50.0",
78
- "@genesislcap/genx": "15.50.0",
79
- "@genesislcap/ts-builder": "15.50.0",
80
- "@genesislcap/uvu-playwright-builder": "15.50.0",
81
- "@genesislcap/vite-builder": "15.50.0",
82
- "@genesislcap/webpack-builder": "15.50.0",
77
+ "@genesislcap/foundation-testing": "15.50.1",
78
+ "@genesislcap/genx": "15.50.1",
79
+ "@genesislcap/ts-builder": "15.50.1",
80
+ "@genesislcap/uvu-playwright-builder": "15.50.1",
81
+ "@genesislcap/vite-builder": "15.50.1",
82
+ "@genesislcap/webpack-builder": "15.50.1",
83
83
  "@types/js-cookie": "^3.0.2",
84
84
  "@types/json-schema": "^7.0.11",
85
85
  "@types/webappsec-credential-management": "^0.6.2",
86
86
  "sinon": "^17.0.1"
87
87
  },
88
88
  "dependencies": {
89
- "@genesislcap/foundation-broadcast-channel": "15.50.0",
90
- "@genesislcap/foundation-logger": "15.50.0",
91
- "@genesislcap/foundation-user": "15.50.0",
92
- "@genesislcap/foundation-utils": "15.50.0",
93
- "@genesislcap/web-core": "15.50.0",
89
+ "@genesislcap/foundation-broadcast-channel": "15.50.1",
90
+ "@genesislcap/foundation-logger": "15.50.1",
91
+ "@genesislcap/foundation-user": "15.50.1",
92
+ "@genesislcap/foundation-utils": "15.50.1",
93
+ "@genesislcap/web-core": "15.50.1",
94
94
  "@microsoft/fast-element": "1.14.0",
95
95
  "@microsoft/fast-foundation": "2.50.0",
96
96
  "bowser": "^2.11.0",