@futdevpro/nts-dynamo 1.15.170 → 1.15.174

package/build/_modules/pagination/_models/keyset-cursor.interface.d.ts

@@ -0,0 +1,16 @@
+/** Construction policy for one route- or capability-bound keyset cursor codec. */
+export interface DyNTS_KeysetCursorSettings_Interface {
+    namespace: string;
+    dimensionCount: number;
+    maxValueLength?: number;
+}
+/** Canonical content-free ordering tuple carried by a keyset cursor. */
+export interface DyNTS_KeysetCursorValue_Interface {
+    values: string[];
+}
+/** Internal versioned cursor payload. It deliberately carries no tenant or subject authority. */
+export interface DyNTS_KeysetCursorPayload_Interface extends DyNTS_KeysetCursorValue_Interface {
+    contractVersion: 'dynts-keyset-cursor/1';
+    namespace: string;
+}
+//# sourceMappingURL=keyset-cursor.interface.d.ts.map

package/build/_modules/pagination/_models/keyset-cursor.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyset-cursor.interface.d.ts","sourceRoot":"","sources":["../../../../src/_modules/pagination/_models/keyset-cursor.interface.ts"],"names":[],"mappings":"AAAA,kFAAkF;AAClF,MAAM,WAAW,oCAAoC;IACnD,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,wEAAwE;AACxE,MAAM,WAAW,iCAAiC;IAChD,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,iGAAiG;AACjG,MAAM,WAAW,mCAAoC,SAAQ,iCAAiC;IAC5F,eAAe,EAAE,uBAAuB,CAAC;IACzC,SAAS,EAAE,MAAM,CAAC;CACnB"}

package/build/_modules/pagination/_models/keyset-cursor.interface.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=keyset-cursor.interface.js.map

package/build/_modules/pagination/_models/keyset-cursor.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyset-cursor.interface.js","sourceRoot":"","sources":["../../../../src/_modules/pagination/_models/keyset-cursor.interface.ts"],"names":[],"mappings":""}

package/build/_modules/pagination/index.d.ts

@@ -0,0 +1,3 @@
+export { DyNTS_KeysetCursor_ControlService } from './keyset-cursor.control-service';
+export type { DyNTS_KeysetCursorPayload_Interface, DyNTS_KeysetCursorSettings_Interface, DyNTS_KeysetCursorValue_Interface } from './_models/keyset-cursor.interface';
+//# sourceMappingURL=index.d.ts.map

package/build/_modules/pagination/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/_modules/pagination/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iCAAiC,EAAE,MAAM,iCAAiC,CAAC;AACpF,YAAY,EACV,mCAAmC,EACnC,oCAAoC,EACpC,iCAAiC,EAClC,MAAM,mCAAmC,CAAC"}

package/build/_modules/pagination/index.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DyNTS_KeysetCursor_ControlService = void 0;
+var keyset_cursor_control_service_1 = require("./keyset-cursor.control-service");
+Object.defineProperty(exports, "DyNTS_KeysetCursor_ControlService", { enumerable: true, get: function () { return keyset_cursor_control_service_1.DyNTS_KeysetCursor_ControlService; } });
+//# sourceMappingURL=index.js.map

package/build/_modules/pagination/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/_modules/pagination/index.ts"],"names":[],"mappings":";;;AAAA,iFAAoF;AAA3E,kJAAA,iCAAiC,OAAA"}

package/build/_modules/pagination/keyset-cursor.control-service.d.ts

@@ -0,0 +1,21 @@
+import { DyNTS_KeysetCursorSettings_Interface, DyNTS_KeysetCursorValue_Interface } from './_models/keyset-cursor.interface';
+/** Encodes deterministic, namespace-bound keyset positions without carrying caller authority. */
+export declare class DyNTS_KeysetCursor_ControlService {
+    static readonly contractVersion: 'dynts-keyset-cursor/1';
+    private static readonly absoluteMaxDimensions;
+    private static readonly absoluteMaxValueLength;
+    private static readonly maxCursorLength;
+    private readonly namespace;
+    private readonly dimensionCount;
+    private readonly maxValueLength;
+    /** Creates one codec whose cursors cannot be replayed in another declared namespace. */
+    constructor(set: DyNTS_KeysetCursorSettings_Interface);
+    /** Encodes an exact non-sensitive sort tuple as canonical unpadded base64url. */
+    encode(value: DyNTS_KeysetCursorValue_Interface): string;
+    /** Decodes only an exact canonical payload created for this codec namespace and tuple shape. */
+    decode(cursor: string): DyNTS_KeysetCursorValue_Interface;
+    private isValidPayload;
+    private isValidValue;
+    private error;
+}
+//# sourceMappingURL=keyset-cursor.control-service.d.ts.map

package/build/_modules/pagination/keyset-cursor.control-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyset-cursor.control-service.d.ts","sourceRoot":"","sources":["../../../src/_modules/pagination/keyset-cursor.control-service.ts"],"names":[],"mappings":"AAGA,OAAO,EAEL,oCAAoC,EACpC,iCAAiC,EAClC,MAAM,mCAAmC,CAAC;AAM3C,iGAAiG;AACjG,qBAAa,iCAAiC;IAC5C,gBAAuB,eAAe,EAAE,uBAAuB,CAA2B;IAC1F,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,qBAAqB,CAAa;IAC1D,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,sBAAsB,CAAe;IAC7D,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,eAAe,CAAgB;IACvD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IAExC,wFAAwF;gBAC5E,GAAG,EAAE,oCAAoC;IAuBrD,iFAAiF;IAC1E,MAAM,CAAC,KAAK,EAAE,iCAAiC,GAAG,MAAM;IAmB/D,gGAAgG;IACzF,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,iCAAiC;IAuChE,OAAO,CAAC,cAAc;IActB,OAAO,CAAC,YAAY;IAapB,OAAO,CAAC,KAAK;CASd"}

package/build/_modules/pagination/keyset-cursor.control-service.js

@@ -0,0 +1,116 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DyNTS_KeysetCursor_ControlService = void 0;
+const fsm_dynamo_1 = require("@futdevpro/fsm-dynamo");
+const global_settings_const_1 = require("../../_collections/global-settings.const");
+const DYNTS_KEYSET_CURSOR_PATTERN = /^[A-Za-z0-9_-]+$/u;
+const DYNTS_KEYSET_CURSOR_NAMESPACE_PATTERN = /^[a-z0-9][a-z0-9._:/-]{0,127}$/u;
+const DYNTS_KEYSET_CURSOR_VALUE_PATTERN = /^[A-Za-z0-9._:-]+$/u;
+/** Encodes deterministic, namespace-bound keyset positions without carrying caller authority. */
+class DyNTS_KeysetCursor_ControlService {
+    static contractVersion = 'dynts-keyset-cursor/1';
+    static absoluteMaxDimensions = 8;
+    static absoluteMaxValueLength = 256;
+    static maxCursorLength = 2048;
+    namespace;
+    dimensionCount;
+    maxValueLength;
+    /** Creates one codec whose cursors cannot be replayed in another declared namespace. */
+    constructor(set) {
+        const maxValueLength = set?.maxValueLength
+            ?? DyNTS_KeysetCursor_ControlService.absoluteMaxValueLength;
+        if (!set
+            || typeof set.namespace !== 'string'
+            || !DYNTS_KEYSET_CURSOR_NAMESPACE_PATTERN.test(set.namespace)
+            || !Number.isSafeInteger(set.dimensionCount)
+            || set.dimensionCount < 1
+            || set.dimensionCount > DyNTS_KeysetCursor_ControlService.absoluteMaxDimensions
+            || !Number.isSafeInteger(maxValueLength)
+            || maxValueLength < 1
+            || maxValueLength > DyNTS_KeysetCursor_ControlService.absoluteMaxValueLength) {
+            throw this.error(500, 'SETTINGS_INVALID', 'The keyset cursor settings are invalid.');
+        }
+        this.namespace = set.namespace;
+        this.dimensionCount = set.dimensionCount;
+        this.maxValueLength = maxValueLength;
+    }
+    /** Encodes an exact non-sensitive sort tuple as canonical unpadded base64url. */
+    encode(value) {
+        if (!this.isValidValue(value)) {
+            throw this.error(500, 'VALUE_INVALID', 'The keyset cursor value is invalid.');
+        }
+        const payload = {
+            contractVersion: DyNTS_KeysetCursor_ControlService.contractVersion,
+            namespace: this.namespace,
+            values: [...value.values],
+        };
+        const cursor = Buffer.from(JSON.stringify(payload), 'utf8').toString('base64url');
+        if (cursor.length > DyNTS_KeysetCursor_ControlService.maxCursorLength) {
+            throw this.error(500, 'VALUE_INVALID', 'The keyset cursor value is invalid.');
+        }
+        return cursor;
+    }
+    /** Decodes only an exact canonical payload created for this codec namespace and tuple shape. */
+    decode(cursor) {
+        try {
+            if (typeof cursor !== 'string'
+                || cursor.length < 1
+                || cursor.length > DyNTS_KeysetCursor_ControlService.maxCursorLength
+                || !DYNTS_KEYSET_CURSOR_PATTERN.test(cursor)) {
+                throw new Error('Cursor syntax is invalid.');
+            }
+            const decoded = Buffer.from(cursor, 'base64url');
+            if (decoded.toString('base64url') !== cursor) {
+                throw new Error('Cursor encoding is not canonical.');
+            }
+            const payload = JSON.parse(decoded.toString('utf8'));
+            if (!this.isValidPayload(payload)) {
+                throw new Error('Cursor payload is invalid.');
+            }
+            const canonicalPayload = {
+                contractVersion: DyNTS_KeysetCursor_ControlService.contractVersion,
+                namespace: this.namespace,
+                values: [...payload.values],
+            };
+            if (Buffer.from(JSON.stringify(canonicalPayload), 'utf8').toString('base64url') !== cursor) {
+                throw new Error('Cursor payload is not canonical.');
+            }
+            return { values: [...payload.values] };
+        }
+        catch {
+            throw this.error(400, 'CURSOR_INVALID', 'The keyset cursor is invalid.');
+        }
+    }
+    isValidPayload(value) {
+        if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+            return false;
+        }
+        const keys = Object.keys(value).sort();
+        const values = Reflect.get(value, 'values');
+        return keys.join(',') === 'contractVersion,namespace,values'
+            && Reflect.get(value, 'contractVersion') === DyNTS_KeysetCursor_ControlService.contractVersion
+            && Reflect.get(value, 'namespace') === this.namespace
+            && this.isValidValue({ values: Array.isArray(values) ? values : [] });
+    }
+    isValidValue(value) {
+        return typeof value === 'object'
+            && value !== null
+            && Array.isArray(value.values)
+            && value.values.length === this.dimensionCount
+            && value.values.every((item) => (typeof item === 'string'
+                && item.length >= 1
+                && item.length <= this.maxValueLength
+                && DYNTS_KEYSET_CURSOR_VALUE_PATTERN.test(item)));
+    }
+    error(status, suffix, message) {
+        return new fsm_dynamo_1.DyFM_Error({
+            status: status,
+            errorCode: `${global_settings_const_1.DyNTS_global_settings.systemShortCodeName}|KEYSET_CURSOR|${suffix}`,
+            message: message,
+            userMessage: status < 500 ? message : 'The keyset cursor could not be created safely.',
+            issuerService: this.constructor.name,
+        });
+    }
+}
+exports.DyNTS_KeysetCursor_ControlService = DyNTS_KeysetCursor_ControlService;
+//# sourceMappingURL=keyset-cursor.control-service.js.map

package/build/_modules/pagination/keyset-cursor.control-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyset-cursor.control-service.js","sourceRoot":"","sources":["../../../src/_modules/pagination/keyset-cursor.control-service.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@futdevpro/nts-dynamo",
-  "version": "01.15.170",
+  "version": "01.15.174",
   "description": "Dynamic NodeTS (NodeJS-Typescript), MongoDB Backend System Framework by Future Development Program Ltd.",
   "DyBu_settings": {
     "packageType": "server-package",
@@ -231,6 +231,12 @@
       "types": "./build/_modules/privacy-lifecycle/index.d.ts",
       "typings": "./build/_modules/privacy-lifecycle/index.d.ts"
     },
+    "./pagination": {
+      "default": "./build/_modules/pagination/index.js",
+      "module": "./build/_modules/pagination/index.js",
+      "types": "./build/_modules/pagination/index.d.ts",
+      "typings": "./build/_modules/pagination/index.d.ts"
+    },
     "./artifact-compiler": {
       "default": "./build/_modules/artifact-compiler/index.js",
       "module": "./build/_modules/artifact-compiler/index.js",
@@ -369,6 +375,9 @@
       "privacy-lifecycle": [
         "build/_modules/privacy-lifecycle/index.d.ts"
       ],
+      "pagination": [
+        "build/_modules/pagination/index.d.ts"
+      ],
       "artifact-compiler": [
         "build/_modules/artifact-compiler/index.d.ts"
       ],