@twin.org/core 0.0.3-next.8 → 0.0.3

package/dist/es/models/IHealth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IHealth.js","sourceRoot":"","sources":["../../../src/models/IHealth.ts"],"names":[],"mappings":"","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { HealthStatus } from \"./healthStatus.js\";\n\n/**\n * Provides health information for a component.\n */\nexport interface IHealth {\n\t/**\n\t * The source of the health information.\n\t */\n\tsource: string;\n\n\t/**\n\t * The description of the component as an i18n key.\n\t */\n\tdescription?: string;\n\n\t/**\n\t * The overall status of the component, the entries can also report their own health.\n\t */\n\tstatus: HealthStatus;\n\n\t/**\n\t * The message for the status if there are further details to provide as an i18n key.\n\t */\n\tmessage?: string;\n\n\t/**\n\t * Data to substitute in the i18n key for the message.\n\t */\n\tdata?: { [id: string]: unknown };\n\n\t/**\n\t * The grouped child components, if any.\n\t */\n\tgrouped?: IHealth[];\n}\n"]}

package/dist/es/models/IMutexWorkerMessage.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=IMutexWorkerMessage.js.map

package/dist/es/models/IMutexWorkerMessage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IMutexWorkerMessage.js","sourceRoot":"","sources":["../../../src/models/IMutexWorkerMessage.ts"],"names":[],"mappings":"","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { MessagePort } from \"node:worker_threads\";\nimport type { MutexMessageTypes } from \"./mutexMessageTypes.js\";\n\n/**\n * Message sent from a worker thread to the main thread to request a SharedArrayBuffer for a given mutex key.\n */\nexport interface IMutexWorkerMessage {\n\t/**\n\t * The message type.\n\t */\n\ttype: typeof MutexMessageTypes.GetBuffer;\n\n\t/**\n\t * The mutex key for which the buffer is requested.\n\t */\n\tkey: string;\n\n\t/**\n\t * The SharedArrayBuffer for the mutex, sent from the worker to the main thread.\n\t */\n\tsignal: SharedArrayBuffer;\n\n\t/**\n\t * The MessagePort for the main thread to respond with the buffer, sent from the worker to the main thread.\n\t */\n\tport: MessagePort;\n}\n"]}

package/dist/es/models/healthStatus.js

@@ -0,0 +1,21 @@
+// Copyright 2024 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+/**
+ * The health status of the component.
+ */
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export const HealthStatus = {
+    /**
+     * OK.
+     */
+    Ok: "ok",
+    /**
+     * Warning.
+     */
+    Warning: "warning",
+    /**
+     * Error.
+     */
+    Error: "error"
+};
+//# sourceMappingURL=healthStatus.js.map

package/dist/es/models/healthStatus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"healthStatus.js","sourceRoot":"","sources":["../../../src/models/healthStatus.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AAEvC;;GAEG;AACH,gEAAgE;AAChE,MAAM,CAAC,MAAM,YAAY,GAAG;IAC3B;;OAEG;IACH,EAAE,EAAE,IAAI;IAER;;OAEG;IACH,OAAO,EAAE,SAAS;IAElB;;OAEG;IACH,KAAK,EAAE,OAAO;CACL,CAAC","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\n\n/**\n * The health status of the component.\n */\n// eslint-disable-next-line @typescript-eslint/naming-convention\nexport const HealthStatus = {\n\t/**\n\t * OK.\n\t */\n\tOk: \"ok\",\n\n\t/**\n\t * Warning.\n\t */\n\tWarning: \"warning\",\n\n\t/**\n\t * Error.\n\t */\n\tError: \"error\"\n} as const;\n\n/**\n * The health status of the component.\n */\nexport type HealthStatus = (typeof HealthStatus)[keyof typeof HealthStatus];\n"]}

package/dist/es/models/mutexMessageTypes.js

@@ -0,0 +1,13 @@
+// Copyright 2026 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+/**
+ * Mutex message types.
+ */
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export const MutexMessageTypes = {
+    /**
+     * Get buffer.
+     */
+    GetBuffer: "twin:mutex:getBuffer"
+};
+//# sourceMappingURL=mutexMessageTypes.js.map

package/dist/es/models/mutexMessageTypes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mutexMessageTypes.js","sourceRoot":"","sources":["../../../src/models/mutexMessageTypes.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AAEvC;;GAEG;AACH,gEAAgE;AAChE,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAChC;;OAEG;IACH,SAAS,EAAE,sBAAsB;CACxB,CAAC","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\n\n/**\n * Mutex message types.\n */\n// eslint-disable-next-line @typescript-eslint/naming-convention\nexport const MutexMessageTypes = {\n\t/**\n\t * Get buffer.\n\t */\n\tGetBuffer: \"twin:mutex:getBuffer\"\n} as const;\n\n/**\n * Mutex message types.\n */\nexport type MutexMessageTypes = (typeof MutexMessageTypes)[keyof typeof MutexMessageTypes];\n"]}

package/dist/es/types/objectOrArray.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"objectOrArray.js","sourceRoot":"","sources":["../../../src/types/objectOrArray.ts"],"names":[],"mappings":"","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\n/**\n * Object or array data type\n */\nexport type ObjectOrArray<T = unknown> = T | T[];\n"]}

package/dist/es/types/singleOccurrenceArray.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=singleOccurrenceArray.js.map

package/dist/es/types/singleOccurrenceArray.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"singleOccurrenceArray.js","sourceRoot":"","sources":["../../../src/types/singleOccurrenceArray.ts"],"names":[],"mappings":"","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { SingleOccurrenceArrayDepthHelper } from \"./singleOccurrenceArrayDepthHelper.js\";\n\n/**\n * Utility type to create a non-empty array with values of type T and exactly one value of type U.\n */\nexport type SingleOccurrenceArray<T = unknown, U = never> = SingleOccurrenceArrayDepthHelper<\n\tT,\n\tU,\n\t[]\n>;\n"]}

package/dist/es/types/singleOccurrenceArrayDepthHelper.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=singleOccurrenceArrayDepthHelper.js.map

package/dist/es/types/singleOccurrenceArrayDepthHelper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"singleOccurrenceArrayDepthHelper.js","sourceRoot":"","sources":["../../../src/types/singleOccurrenceArrayDepthHelper.ts"],"names":[],"mappings":"","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\n/**\n * Helper with bounded recursion depth to keep type instantiation tractable.\n */\nexport type SingleOccurrenceArrayDepthHelper<T, U, Depth extends 0[]> = Depth[\"length\"] extends 16\n\t? [U, ...T[]]\n\t: [U, ...T[]] | [T, ...SingleOccurrenceArrayDepthHelper<T, U, [0, ...Depth]>];\n"]}

package/dist/es/types/urn.js

@@ -1,6 +1,5 @@
 import { GuardError } from "../errors/guardError.js";
 import { RandomHelper } from "../helpers/randomHelper.js";
-import { Converter } from "../utils/converter.js";
 import { Guards } from "../utils/guards.js";
 import { Is } from "../utils/is.js";
 /**
@@ -40,7 +39,7 @@ export class Urn {
      * @returns A new Id in URN format.
      */
     static generateRandom(namespace) {
-        return new Urn(namespace, Converter.bytesToHex(RandomHelper.generate(32)));
+        return new Urn(namespace, RandomHelper.generateUuidV7("compact"));
     }
     /**
      * Does the provided urn match the namespace.

package/dist/es/types/urn.js.map

@@ -1 +1 @@
-{"version":3,"file":"urn.js","sourceRoot":"","sources":["../../../src/types/urn.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAE1D,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAClD,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC5C,OAAO,EAAE,EAAE,EAAE,MAAM,gBAAgB,CAAC;AAEpC;;GAEG;AACH,MAAM,OAAO,GAAG;IACf;;OAEG;IACI,MAAM,CAAU,UAAU,SAAyB;IAE1D;;;OAGG;IACc,SAAS,CAAW;IAErC;;;;OAIG;IACH,YAAY,mBAA2B,EAAE,iBAAoC;QAC5E,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,UAAU,yBAA+B,mBAAmB,CAAC,CAAC;QAErF,oCAAoC;QACpC,IAAI,CAAC,SAAS,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC,mBAAmB,CAAC,CAAC,CAAC;QAEzD,IAAI,EAAE,CAAC,KAAK,CAAC,iBAAiB,CAAC,EAAE,CAAC;YACjC,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC,UAAU,uBAA6B,iBAAiB,CAAC,CAAC;YAChF,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,iBAAiB,CAAC,CAAC;QAC3C,CAAC;aAAM,CAAC;YACP,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,UAAU,uBAA6B,iBAAiB,CAAC,CAAC;YACjF,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,WAAW,CAAC,iBAAiB,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;QACxE,CAAC;IACF,CAAC;IAED;;;;OAIG;IACI,MAAM,CAAC,cAAc,CAAC,SAAiB;QAC7C,OAAO,IAAI,GAAG,CAAC,SAAS,EAAE,SAAS,CAAC,UAAU,CAAC,YAAY,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IAC5E,CAAC;IAED;;;;;OAKG;IACI,MAAM,CAAC,YAAY,CAAC,GAAW,EAAE,SAAiB;QACxD,IAAI,CAAC,EAAE,CAAC,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC;YAC1B,OAAO,KAAK,CAAC;QACd,CAAC;QACD,IAAI,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;YAC5B,GAAG,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;QACpB,CAAC;QAED,IAAI,GAAG,CAAC,MAAM,KAAK,SAAS,CAAC,MAAM,EAAE,CAAC;YACrC,OAAO,GAAG,KAAK,SAAS,CAAC;QAC1B,CAAC;QAED,OAAO,GAAG,CAAC,UAAU,CAAC,GAAG,SAAS,GAAG,CAAC,CAAC;IACxC,CAAC;IAED;;;;OAIG;IACI,MAAM,CAAC,aAAa,CAAC,GAAY;QACvC,IAAI,CAAC,EAAE,CAAC,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC;YAC1B,OAAO;QACR,CAAC;QAED,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAE7B,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,KAAK,EAAE,CAAC;YACxB,KAAK,CAAC,KAAK,EAAE,CAAC;QACf,CAAC;QAED,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACtB,OAAO;QACR,CAAC;QAED,IAAI,CAAC,uBAAuB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YAC7C,OAAO;QACR,CAAC;QAED,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACvC,IAAI,CAAC,6BAA6B,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;gBACnD,OAAO;YACR,CAAC;QACF,CAAC;QAED,OAAO,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAC1C,CAAC;IAED;;;;OAIG;IACI,MAAM,CAAC,eAAe,CAAC,GAAW;QACxC,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAE7B,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,KAAK,EAAE,CAAC;YACxB,KAAK,CAAC,KAAK,EAAE,CAAC;QACf,CAAC;QAED,OAAO,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAC1C,CAAC;IAED;;;;OAIG;IACI,MAAM,CAAC,SAAS,CAAC,GAAY;QACnC,IAAI,EAAE,CAAC,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC;YACzB,IAAI,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;gBAC5B,OAAO,GAAG,CAAC;YACZ,CAAC;YACD,OAAO,OAAO,GAAG,EAAE,CAAC;QACrB,CAAC;IACF,CAAC;IAED;;;;;;OAMG;IACI,MAAM,CAAC,KAAK,CAAC,MAAc,EAAE,QAAgB,EAAE,KAAc;QACnE,MAAM,CAAC,WAAW,CAAC,MAAM,EAAE,QAAQ,EAAE,KAAK,CAAC,CAAC;QAE5C,MAAM,MAAM,GAAG,GAAG,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;QAExC,IAAI,CAAC,MAAM,EAAE,CAAC;YACb,MAAM,IAAI,UAAU,CAAC,MAAM,EAAE,WAAW,EAAE,QAAQ,EAAE,KAAK,CAAC,CAAC;QAC5D,CAAC;IACF,CAAC;IAED;;;;;;;OAOG;IACI,MAAM,CAAC,QAAQ,CACrB,QAAgB,EAChB,KAAc,EACd,QAA8B,EAC9B,iBAA0B;QAE1B,IAAI,CAAC,EAAE,CAAC,WAAW,CAAC,KAAK,CAAC,EAAE,CAAC;YAC5B,QAAQ,CAAC,IAAI,CAAC;gBACb,QAAQ;gBACR,MAAM,EAAE,uBAAuB;gBAC/B,UAAU,EAAE,EAAE,SAAS,EAAE,iBAAiB,IAAI,6BAA6B,EAAE,KAAK,EAAE;aACpF,CAAC,CAAC;YAEH,OAAO,KAAK,CAAC;QACd,CAAC;QAED,MAAM,MAAM,GAAG,GAAG,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;QAExC,IAAI,EAAE,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC;YAC1B,QAAQ,CAAC,IAAI,CAAC;gBACb,QAAQ;gBACR,MAAM,EAAE,kBAAkB;gBAC1B,UAAU,EAAE,EAAE,SAAS,EAAE,iBAAiB,IAAI,6BAA6B,EAAE,KAAK,EAAE;aACpF,CAAC,CAAC;YAEH,OAAO,KAAK,CAAC;QACd,CAAC;QAED,OAAO,IAAI,CAAC;IACb,CAAC;IAED;;;;OAIG;IACI,KAAK,CAAC,aAAqB,CAAC;QAClC,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;IACzC,CAAC;IAED;;;OAGG;IACI,mBAAmB;QACzB,OAAO,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;IAC1B,CAAC;IAED;;;OAGG;IACI,eAAe;QACrB,OAAO,IAAI,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAC3D,CAAC;IAED;;;;OAIG;IACI,sBAAsB,CAAC,aAAqB,CAAC;QACnD,OAAO,IAAI,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,UAAU,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAC9E,CAAC;IAED;;;;OAIG;IACI,iBAAiB,CAAC,aAAqB,CAAC;QAC9C,OAAO,IAAI,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,UAAU,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACxF,CAAC;IAED;;;;OAIG;IACI,QAAQ,CAAC,aAAsB,IAAI;QACzC,OAAO,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;IAClF,CAAC;IAED;;;;;OAKG;IACK,WAAW,CAAC,GAAW;QAC9B,OAAO,GAAG,CAAC,OAAO,CAAC,aAAa,EAAE,IAAI,CAAC,CAAC;IACzC,CAAC","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport { nameof } from \"@twin.org/nameof\";\nimport { GuardError } from \"../errors/guardError.js\";\nimport { RandomHelper } from \"../helpers/randomHelper.js\";\nimport type { IValidationFailure } from \"../models/IValidationFailure.js\";\nimport { Converter } from \"../utils/converter.js\";\nimport { Guards } from \"../utils/guards.js\";\nimport { Is } from \"../utils/is.js\";\n\n/**\n * Class to help with urns.\n */\nexport class Urn {\n\t/**\n\t * Runtime name for the class.\n\t */\n\tpublic static readonly CLASS_NAME: string = nameof<Urn>();\n\n\t/**\n\t * The specific part of the namespace.\n\t * @internal\n\t */\n\tprivate readonly _urnParts: string[];\n\n\t/**\n\t * Create a new instance of Urn.\n\t * @param namespaceIdentifier The identifier for the namespace.\n\t * @param namespaceSpecific The specific part of the namespace.\n\t */\n\tconstructor(namespaceIdentifier: string, namespaceSpecific: string | string[]) {\n\t\tGuards.stringValue(Urn.CLASS_NAME, nameof(namespaceIdentifier), namespaceIdentifier);\n\n\t\t// Strip leading and trailing colons\n\t\tthis._urnParts = [this.stripColons(namespaceIdentifier)];\n\n\t\tif (Is.array(namespaceSpecific)) {\n\t\t\tGuards.arrayValue(Urn.CLASS_NAME, nameof(namespaceSpecific), namespaceSpecific);\n\t\t\tthis._urnParts.push(...namespaceSpecific);\n\t\t} else {\n\t\t\tGuards.stringValue(Urn.CLASS_NAME, nameof(namespaceSpecific), namespaceSpecific);\n\t\t\tthis._urnParts.push(...this.stripColons(namespaceSpecific).split(\":\"));\n\t\t}\n\t}\n\n\t/**\n\t * Generate a random identifier with 32 byte id.\n\t * @param namespace The prefix for the urn.\n\t * @returns A new Id in URN format.\n\t */\n\tpublic static generateRandom(namespace: string): Urn {\n\t\treturn new Urn(namespace, Converter.bytesToHex(RandomHelper.generate(32)));\n\t}\n\n\t/**\n\t * Does the provided urn match the namespace.\n\t * @param urn The urn to check.\n\t * @param namespace The namespace to match.\n\t * @returns True if the namespace matches.\n\t */\n\tpublic static hasNamespace(urn: string, namespace: string): boolean {\n\t\tif (!Is.stringValue(urn)) {\n\t\t\treturn false;\n\t\t}\n\t\tif (urn.startsWith(\"urn:\")) {\n\t\t\turn = urn.slice(4);\n\t\t}\n\n\t\tif (urn.length === namespace.length) {\n\t\t\treturn urn === namespace;\n\t\t}\n\n\t\treturn urn.startsWith(`${namespace}:`);\n\t}\n\n\t/**\n\t * Try and parse a string into the urn parts.\n\t * @param urn The urn to parse.\n\t * @returns The formatted urn or undefined if the value is not a urn.\n\t */\n\tpublic static tryParseExact(urn: unknown): Urn | undefined {\n\t\tif (!Is.stringValue(urn)) {\n\t\t\treturn;\n\t\t}\n\n\t\tconst parts = urn.split(\":\");\n\n\t\tif (parts[0] === \"urn\") {\n\t\t\tparts.shift();\n\t\t}\n\n\t\tif (parts.length < 2) {\n\t\t\treturn;\n\t\t}\n\n\t\tif (!/[\\da-z][\\da-z-]{0,31}/.test(parts[0])) {\n\t\t\treturn;\n\t\t}\n\n\t\tfor (let i = 1; i < parts.length; i++) {\n\t\t\tif (!/[\\d!#$%'()*+,./:;=?@_a-z-]+/.test(parts[i])) {\n\t\t\t\treturn;\n\t\t\t}\n\t\t}\n\n\t\treturn new Urn(parts[0], parts.slice(1));\n\t}\n\n\t/**\n\t * Construct a urn from a string that has already been validated.\n\t * @param urn The urn to parse.\n\t * @returns The formatted urn.\n\t */\n\tpublic static fromValidString(urn: string): Urn {\n\t\tconst parts = urn.split(\":\");\n\n\t\tif (parts[0] === \"urn\") {\n\t\t\tparts.shift();\n\t\t}\n\n\t\treturn new Urn(parts[0], parts.slice(1));\n\t}\n\n\t/**\n\t * Add a urn: prefix if there isn't one already.\n\t * @param urn The urn string to add a prefix to.\n\t * @returns The urn with a prefix.\n\t */\n\tpublic static addPrefix(urn: unknown): string | undefined {\n\t\tif (Is.stringValue(urn)) {\n\t\t\tif (urn.startsWith(\"urn:\")) {\n\t\t\t\treturn urn;\n\t\t\t}\n\t\t\treturn `urn:${urn}`;\n\t\t}\n\t}\n\n\t/**\n\t * Parse a string into the urn parts.\n\t * @param source The source of the error.\n\t * @param property The name of the property.\n\t * @param value The urn to parse.\n\t * @throws GuardError If the value does not match the assertion.\n\t */\n\tpublic static guard(source: string, property: string, value: unknown): asserts value is string {\n\t\tGuards.stringValue(source, property, value);\n\n\t\tconst result = Urn.tryParseExact(value);\n\n\t\tif (!result) {\n\t\t\tthrow new GuardError(source, \"guard.urn\", property, value);\n\t\t}\n\t}\n\n\t/**\n\t * Validate a string as a Urn.\n\t * @param property Throw an exception if the urn property is invalid.\n\t * @param value The urn to parse.\n\t * @param failures The list of failures to add to.\n\t * @param fieldNameResource The optional human readable name for the field as an i18 resource.\n\t * @returns The formatted urn.\n\t */\n\tpublic static validate(\n\t\tproperty: string,\n\t\tvalue: unknown,\n\t\tfailures: IValidationFailure[],\n\t\tfieldNameResource?: string\n\t): value is string {\n\t\tif (!Is.stringValue(value)) {\n\t\t\tfailures.push({\n\t\t\t\tproperty,\n\t\t\t\treason: \"validation.beNotEmpty\",\n\t\t\t\tproperties: { fieldName: fieldNameResource ?? \"validation.defaultFieldName\", value }\n\t\t\t});\n\n\t\t\treturn false;\n\t\t}\n\n\t\tconst result = Urn.tryParseExact(value);\n\n\t\tif (Is.undefined(result)) {\n\t\t\tfailures.push({\n\t\t\t\tproperty,\n\t\t\t\treason: \"validation.beUrn\",\n\t\t\t\tproperties: { fieldName: fieldNameResource ?? \"validation.defaultFieldName\", value }\n\t\t\t});\n\n\t\t\treturn false;\n\t\t}\n\n\t\treturn true;\n\t}\n\n\t/**\n\t * Get the parts.\n\t * @param startIndex The index to start from, defaults to 0.\n\t * @returns The parts.\n\t */\n\tpublic parts(startIndex: number = 0): string[] {\n\t\treturn this._urnParts.slice(startIndex);\n\t}\n\n\t/**\n\t * Get the namespace identifier.\n\t * @returns The namespace identifier.\n\t */\n\tpublic namespaceIdentifier(): string {\n\t\treturn this._urnParts[0];\n\t}\n\n\t/**\n\t * Get the namespace method, the first component after the identifier.\n\t * @returns The namespace method.\n\t */\n\tpublic namespaceMethod(): string {\n\t\treturn this._urnParts.length > 1 ? this._urnParts[1] : \"\";\n\t}\n\n\t/**\n\t * Get the namespace specific parts.\n\t * @param startIndex The index to start from, defaults to 0.\n\t * @returns The namespace specific parts.\n\t */\n\tpublic namespaceSpecificParts(startIndex: number = 0): string[] {\n\t\treturn this._urnParts.length > 1 ? this._urnParts.slice(startIndex + 1) : [];\n\t}\n\n\t/**\n\t * Get the namespace specific.\n\t * @param startIndex The index to start from, defaults to 0.\n\t * @returns The namespace specific.\n\t */\n\tpublic namespaceSpecific(startIndex: number = 0): string {\n\t\treturn this._urnParts.length > 1 ? this._urnParts.slice(startIndex + 1).join(\":\") : \"\";\n\t}\n\n\t/**\n\t * Convert the parts in to a full string.\n\t * @param omitPrefix Omit the urn: prefix from the string.\n\t * @returns The formatted urn.\n\t */\n\tpublic toString(omitPrefix: boolean = true): string {\n\t\treturn omitPrefix ? this._urnParts.join(\":\") : `urn:${this._urnParts.join(\":\")}`;\n\t}\n\n\t/**\n\t * Strip the leading and trailing colons from a string.\n\t * @param val The value to strip.\n\t * @returns The stripped string.\n\t * @internal\n\t */\n\tprivate stripColons(val: string): string {\n\t\treturn val.replace(/^:?(.*?):?$/, \"$1\");\n\t}\n}\n"]}
+{"version":3,"file":"urn.js","sourceRoot":"","sources":["../../../src/types/urn.ts"],"names":[],"mappings":"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","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport { nameof } from \"@twin.org/nameof\";\nimport { GuardError } from \"../errors/guardError.js\";\nimport { RandomHelper } from \"../helpers/randomHelper.js\";\nimport type { IValidationFailure } from \"../models/IValidationFailure.js\";\nimport { Guards } from \"../utils/guards.js\";\nimport { Is } from \"../utils/is.js\";\n\n/**\n * Class to help with urns.\n */\nexport class Urn {\n\t/**\n\t * Runtime name for the class.\n\t */\n\tpublic static readonly CLASS_NAME: string = nameof<Urn>();\n\n\t/**\n\t * The specific part of the namespace.\n\t * @internal\n\t */\n\tprivate readonly _urnParts: string[];\n\n\t/**\n\t * Create a new instance of Urn.\n\t * @param namespaceIdentifier The identifier for the namespace.\n\t * @param namespaceSpecific The specific part of the namespace.\n\t */\n\tconstructor(namespaceIdentifier: string, namespaceSpecific: string | string[]) {\n\t\tGuards.stringValue(Urn.CLASS_NAME, nameof(namespaceIdentifier), namespaceIdentifier);\n\n\t\t// Strip leading and trailing colons\n\t\tthis._urnParts = [this.stripColons(namespaceIdentifier)];\n\n\t\tif (Is.array(namespaceSpecific)) {\n\t\t\tGuards.arrayValue(Urn.CLASS_NAME, nameof(namespaceSpecific), namespaceSpecific);\n\t\t\tthis._urnParts.push(...namespaceSpecific);\n\t\t} else {\n\t\t\tGuards.stringValue(Urn.CLASS_NAME, nameof(namespaceSpecific), namespaceSpecific);\n\t\t\tthis._urnParts.push(...this.stripColons(namespaceSpecific).split(\":\"));\n\t\t}\n\t}\n\n\t/**\n\t * Generate a random identifier with 32 byte id.\n\t * @param namespace The prefix for the urn.\n\t * @returns A new Id in URN format.\n\t */\n\tpublic static generateRandom(namespace: string): Urn {\n\t\treturn new Urn(namespace, RandomHelper.generateUuidV7(\"compact\"));\n\t}\n\n\t/**\n\t * Does the provided urn match the namespace.\n\t * @param urn The urn to check.\n\t * @param namespace The namespace to match.\n\t * @returns True if the namespace matches.\n\t */\n\tpublic static hasNamespace(urn: string, namespace: string): boolean {\n\t\tif (!Is.stringValue(urn)) {\n\t\t\treturn false;\n\t\t}\n\t\tif (urn.startsWith(\"urn:\")) {\n\t\t\turn = urn.slice(4);\n\t\t}\n\n\t\tif (urn.length === namespace.length) {\n\t\t\treturn urn === namespace;\n\t\t}\n\n\t\treturn urn.startsWith(`${namespace}:`);\n\t}\n\n\t/**\n\t * Try and parse a string into the urn parts.\n\t * @param urn The urn to parse.\n\t * @returns The formatted urn or undefined if the value is not a urn.\n\t */\n\tpublic static tryParseExact(urn: unknown): Urn | undefined {\n\t\tif (!Is.stringValue(urn)) {\n\t\t\treturn;\n\t\t}\n\n\t\tconst parts = urn.split(\":\");\n\n\t\tif (parts[0] === \"urn\") {\n\t\t\tparts.shift();\n\t\t}\n\n\t\tif (parts.length < 2) {\n\t\t\treturn;\n\t\t}\n\n\t\tif (!/[\\da-z][\\da-z-]{0,31}/.test(parts[0])) {\n\t\t\treturn;\n\t\t}\n\n\t\tfor (let i = 1; i < parts.length; i++) {\n\t\t\tif (!/[\\d!#$%'()*+,./:;=?@_a-z-]+/.test(parts[i])) {\n\t\t\t\treturn;\n\t\t\t}\n\t\t}\n\n\t\treturn new Urn(parts[0], parts.slice(1));\n\t}\n\n\t/**\n\t * Construct a urn from a string that has already been validated.\n\t * @param urn The urn to parse.\n\t * @returns The formatted urn.\n\t */\n\tpublic static fromValidString(urn: string): Urn {\n\t\tconst parts = urn.split(\":\");\n\n\t\tif (parts[0] === \"urn\") {\n\t\t\tparts.shift();\n\t\t}\n\n\t\treturn new Urn(parts[0], parts.slice(1));\n\t}\n\n\t/**\n\t * Add a urn: prefix if there isn't one already.\n\t * @param urn The urn string to add a prefix to.\n\t * @returns The urn with a prefix.\n\t */\n\tpublic static addPrefix(urn: unknown): string | undefined {\n\t\tif (Is.stringValue(urn)) {\n\t\t\tif (urn.startsWith(\"urn:\")) {\n\t\t\t\treturn urn;\n\t\t\t}\n\t\t\treturn `urn:${urn}`;\n\t\t}\n\t}\n\n\t/**\n\t * Parse a string into the urn parts.\n\t * @param source The source of the error.\n\t * @param property The name of the property.\n\t * @param value The urn to parse.\n\t * @throws GuardError If the value does not match the assertion.\n\t */\n\tpublic static guard(source: string, property: string, value: unknown): asserts value is string {\n\t\tGuards.stringValue(source, property, value);\n\n\t\tconst result = Urn.tryParseExact(value);\n\n\t\tif (!result) {\n\t\t\tthrow new GuardError(source, \"guard.urn\", property, value);\n\t\t}\n\t}\n\n\t/**\n\t * Validate a string as a Urn.\n\t * @param property Throw an exception if the urn property is invalid.\n\t * @param value The urn to parse.\n\t * @param failures The list of failures to add to.\n\t * @param fieldNameResource The optional human readable name for the field as an i18 resource.\n\t * @returns The formatted urn.\n\t */\n\tpublic static validate(\n\t\tproperty: string,\n\t\tvalue: unknown,\n\t\tfailures: IValidationFailure[],\n\t\tfieldNameResource?: string\n\t): value is string {\n\t\tif (!Is.stringValue(value)) {\n\t\t\tfailures.push({\n\t\t\t\tproperty,\n\t\t\t\treason: \"validation.beNotEmpty\",\n\t\t\t\tproperties: { fieldName: fieldNameResource ?? \"validation.defaultFieldName\", value }\n\t\t\t});\n\n\t\t\treturn false;\n\t\t}\n\n\t\tconst result = Urn.tryParseExact(value);\n\n\t\tif (Is.undefined(result)) {\n\t\t\tfailures.push({\n\t\t\t\tproperty,\n\t\t\t\treason: \"validation.beUrn\",\n\t\t\t\tproperties: { fieldName: fieldNameResource ?? \"validation.defaultFieldName\", value }\n\t\t\t});\n\n\t\t\treturn false;\n\t\t}\n\n\t\treturn true;\n\t}\n\n\t/**\n\t * Get the parts.\n\t * @param startIndex The index to start from, defaults to 0.\n\t * @returns The parts.\n\t */\n\tpublic parts(startIndex: number = 0): string[] {\n\t\treturn this._urnParts.slice(startIndex);\n\t}\n\n\t/**\n\t * Get the namespace identifier.\n\t * @returns The namespace identifier.\n\t */\n\tpublic namespaceIdentifier(): string {\n\t\treturn this._urnParts[0];\n\t}\n\n\t/**\n\t * Get the namespace method, the first component after the identifier.\n\t * @returns The namespace method.\n\t */\n\tpublic namespaceMethod(): string {\n\t\treturn this._urnParts.length > 1 ? this._urnParts[1] : \"\";\n\t}\n\n\t/**\n\t * Get the namespace specific parts.\n\t * @param startIndex The index to start from, defaults to 0.\n\t * @returns The namespace specific parts.\n\t */\n\tpublic namespaceSpecificParts(startIndex: number = 0): string[] {\n\t\treturn this._urnParts.length > 1 ? this._urnParts.slice(startIndex + 1) : [];\n\t}\n\n\t/**\n\t * Get the namespace specific.\n\t * @param startIndex The index to start from, defaults to 0.\n\t * @returns The namespace specific.\n\t */\n\tpublic namespaceSpecific(startIndex: number = 0): string {\n\t\treturn this._urnParts.length > 1 ? this._urnParts.slice(startIndex + 1).join(\":\") : \"\";\n\t}\n\n\t/**\n\t * Convert the parts in to a full string.\n\t * @param omitPrefix Omit the urn: prefix from the string.\n\t * @returns The formatted urn.\n\t */\n\tpublic toString(omitPrefix: boolean = true): string {\n\t\treturn omitPrefix ? this._urnParts.join(\":\") : `urn:${this._urnParts.join(\":\")}`;\n\t}\n\n\t/**\n\t * Strip the leading and trailing colons from a string.\n\t * @param val The value to strip.\n\t * @returns The stripped string.\n\t * @internal\n\t */\n\tprivate stripColons(val: string): string {\n\t\treturn val.replace(/^:?(.*?):?$/, \"$1\");\n\t}\n}\n"]}

package/dist/es/utils/asyncCache.js

@@ -6,6 +6,26 @@ import { SharedStore } from "./sharedStore.js";
  * Cache the results from asynchronous requests.
  */
 export class AsyncCache {
+    /**
+     * Cache key for the shared cache object in the SharedStore.
+     * @internal
+     */
+    static _CACHE_KEY = "asyncCache";
+    /**
+     * Cache key for the entry key of the soonest-expiring cache entry, used to optimize cleanup.
+     * @internal
+     */
+    static _NEXT_EXPIRY_CACHE_KEY = "asyncCacheNextExpiryKey";
+    /**
+     * Cache key for the timestamp of the last full cleanup scan.
+     * @internal
+     */
+    static _LAST_CLEANUP_KEY = "asyncCacheLastCleanup";
+    /**
+     * Minimum interval in ms between full cleanup scans.
+     * @internal
+     */
+    static _CLEANUP_INTERVAL_MS = 5000;
     /**
      * Execute an async request and cache the result.
      * @param key The key for the entry in the cache.
@@ -14,117 +34,140 @@ export class AsyncCache {
      * @param cacheFailures Cache failure results, defaults to false.
      * @returns The response.
      */
-    static exec(key, ttlMs, requestMethod, cacheFailures) {
-        const cacheEnabled = Is.integer(ttlMs) && ttlMs >= 0;
-        if (cacheEnabled) {
-            AsyncCache.cleanupExpired();
-            const cache = AsyncCache.getSharedCache();
-            // Do we have a cache entry for the key
-            if (cache[key]) {
-                if (!Is.empty(cache[key].result)) {
-                    // If the cache has already resulted in a value, resolve it
-                    return Promise.resolve(cache[key].result);
-                }
-                else if (!Is.empty(cache[key].error)) {
-                    // If the cache has already resulted in an error, reject it
-                    return Promise.reject(cache[key].error);
-                }
-                // Otherwise create a promise to return and store the resolver
-                // and rejector in the cache entry, so that we can call then
-                // when the request is done
-                let storedResolve;
-                let storedReject;
-                const wait = new Promise((resolve, reject) => {
-                    storedResolve = resolve;
-                    storedReject = reject;
+    static async exec(key, ttlMs, requestMethod, cacheFailures) {
+        const cacheEnabled = Is.integer(ttlMs) && ttlMs > 0;
+        if (!cacheEnabled) {
+            // No caching, just execute the request method
+            return requestMethod();
+        }
+        AsyncCache.cleanupExpired();
+        // Cleanup will not necessarily remove the entry for the key we are requesting
+        // as it is throttled, so we also check and evict if expired here to ensure we don't return stale data.
+        AsyncCache.evictIfExpired(key);
+        const cache = AsyncCache.getSharedCache();
+        const cachedEntry = cache[key];
+        // Do we have a cache entry for the key
+        if (cachedEntry) {
+            if (!Is.empty(cachedEntry.result)) {
+                // If the cache has already resulted in a value, resolve it
+                return Promise.resolve(cachedEntry.result);
+            }
+            else if (!Is.empty(cachedEntry.error)) {
+                // If the cache has already resulted in an error, reject it
+                return Promise.reject(cachedEntry.error);
+            }
+            // Otherwise create a promise to return and store the resolver
+            // and rejector in the cache entry, so that we can call then
+            // when the request is done
+            let storedResolve;
+            let storedReject;
+            const wait = new Promise((resolve, reject) => {
+                storedResolve = resolve;
+                storedReject = reject;
+            });
+            if (!Is.empty(storedResolve) && !Is.empty(storedReject)) {
+                cachedEntry.promiseQueue.push({
+                    requestMethod,
+                    resolve: storedResolve,
+                    reject: storedReject
                 });
-                if (!Is.empty(storedResolve) && !Is.empty(storedReject)) {
-                    cache[key].promiseQueue.push({
-                        requestMethod,
-                        resolve: storedResolve,
-                        reject: storedReject
-                    });
-                }
-                return wait;
             }
-            // If we don't have a cache entry, create a new one
-            cache[key] = {
-                promiseQueue: [],
-                expires: ttlMs === 0 ? 0 : Date.now() + ttlMs
-            };
-            // Return a promise that wraps the original request method
-            // so that we can store any results or errors in the cache
-            return new Promise((resolve, reject) => {
-                // Call the request method and store the result
-                requestMethod()
-                    // eslint-disable-next-line promise/prefer-await-to-then
-                    .then(res => {
-                    // If the request was successful, store the result
-                    cache[key].result = res;
-                    // and resolve both this promise and all the waiters
-                    resolve(res);
-                    for (const wait of cache[key].promiseQueue) {
-                        wait.resolve(res);
+            return wait;
+        }
+        // If we don't have a cache entry, create a new one
+        const expires = Date.now() + ttlMs;
+        const cacheEntry = {
+            inProgress: true,
+            promiseQueue: [],
+            expires
+        };
+        cache[key] = cacheEntry;
+        AsyncCache.updateNextExpiryKey(key, expires);
+        // Return a promise that wraps the original request method
+        // so that we can store any results or errors in the cache
+        return new Promise((resolve, reject) => {
+            // Call the request method and store the result
+            requestMethod()
+                // eslint-disable-next-line promise/prefer-await-to-then
+                .then(res => {
+                // If the request was successful, store the result
+                cacheEntry.inProgress = false;
+                cacheEntry.result = res;
+                // and resolve both this promise and all the waiters
+                resolve(res);
+                for (const wait of cacheEntry.promiseQueue) {
+                    wait.resolve(res);
+                }
+                cacheEntry.promiseQueue = [];
+                return res;
+            })
+                // eslint-disable-next-line promise/prefer-await-to-then
+                .catch((err) => {
+                // Reject the promise
+                reject(err);
+                cacheEntry.inProgress = false;
+                // Handle the waiters based on the cacheFailures flag
+                if (cacheFailures ?? false) {
+                    // If we are caching failures, store the error and reject the waiters
+                    cacheEntry.error = err;
+                    for (const wait of cacheEntry.promiseQueue) {
+                        wait.reject(err);
                     }
-                    return res;
-                })
-                    // eslint-disable-next-line promise/prefer-await-to-then
-                    .catch((err) => {
-                    // Reject the promise
-                    reject(err);
-                    // Handle the waiters based on the cacheFailures flag
-                    if (cacheFailures ?? false) {
-                        // If we are caching failures, store the error and reject the waiters
-                        cache[key].error = err;
-                        for (const wait of cache[key].promiseQueue) {
-                            wait.reject(err);
-                        }
-                        // Clear the waiters so we don't call them again
-                        cache[key].promiseQueue = [];
+                    // Clear the waiters so we don't call them again
+                    cacheEntry.promiseQueue = [];
+                }
+                else {
+                    // If not caching failures for any queued requests we
+                    // have no value to either resolve or reject, so we
+                    // just resolve with the original request method
+                    for (const wait of cacheEntry.promiseQueue) {
+                        // eslint-disable-next-line @typescript-eslint/no-floating-promises
+                        AsyncCache.resolveWaiter(wait.requestMethod, wait.resolve, wait.reject);
                     }
-                    else {
-                        // If not caching failures for any queued requests we
-                        // have no value to either resolve or reject, so we
-                        // just resolve with the original request method
-                        for (const wait of cache[key].promiseQueue) {
-                            wait.resolve(wait.requestMethod());
-                        }
+                    if (cache[key] === cacheEntry) {
                         delete cache[key];
                     }
-                });
+                }
             });
-        }
+        });
     }
     /**
      * Get an entry from the cache.
      * @param key The key to get from the cache.
-     * @returns The item from the cache if it exists.
+     * @returns The item from the cache if it exists, or undefined if the key is missing, expired, or
+     * its request is still in-progress. Throws if a cached failure exists for the key.
      */
     static async get(key) {
+        if (AsyncCache.evictIfExpired(key)) {
+            return undefined;
+        }
         const cache = AsyncCache.getSharedCache();
-        if (!Is.empty(cache[key].result)) {
+        const entry = cache[key];
+        if (!Is.empty(entry?.result)) {
             // If the cache has already resulted in a value, resolve it
-            return cache[key].result;
+            return entry.result;
         }
-        else if (!Is.empty(cache[key].error)) {
+        if (!Is.empty(entry?.error)) {
             // If the cache has already resulted in an error, reject it
-            throw cache[key].error;
+            throw entry.error;
         }
     }
     /**
      * Set an entry into the cache.
      * @param key The key to set in the cache.
      * @param value The value to set in the cache.
-     * @param ttlMs The TTL of the entry in the cache in ms, defaults to 1s.
+     * @param ttlMs The TTL of the entry in the cache in milliseconds. Defaults to 1000 (1 second).
      * @returns Nothing.
      */
     static async set(key, value, ttlMs) {
+        const expires = Date.now() + (ttlMs ?? 1000);
         const cache = AsyncCache.getSharedCache();
         cache[key] = {
             result: value,
             promiseQueue: [],
-            expires: Date.now() + (ttlMs ?? 1000)
+            expires
         };
+        AsyncCache.updateNextExpiryKey(key, expires);
     }
     /**
      * Remove an entry from the cache.
@@ -133,6 +176,10 @@ export class AsyncCache {
     static remove(key) {
         const cache = AsyncCache.getSharedCache();
         delete cache[key];
+        const nextKey = SharedStore.get(AsyncCache._NEXT_EXPIRY_CACHE_KEY);
+        if (nextKey === key) {
+            AsyncCache.recalculateNextKey();
+        }
     }
     /**
      * Clear the cache.
@@ -141,26 +188,45 @@ export class AsyncCache {
     static clearCache(prefix) {
         const cache = AsyncCache.getSharedCache();
         if (Is.stringValue(prefix)) {
+            const nextKey = SharedStore.get(AsyncCache._NEXT_EXPIRY_CACHE_KEY);
+            let nextKeyRemoved = false;
             for (const entry in cache) {
                 if (entry.startsWith(prefix)) {
+                    if (entry === nextKey) {
+                        nextKeyRemoved = true;
+                    }
                     delete cache[entry];
                 }
             }
+            if (nextKeyRemoved) {
+                AsyncCache.recalculateNextKey();
+            }
         }
         else {
-            SharedStore.set("asyncCache", {});
+            SharedStore.set(AsyncCache._CACHE_KEY, {});
+            SharedStore.set(AsyncCache._NEXT_EXPIRY_CACHE_KEY, undefined);
+            SharedStore.set(AsyncCache._LAST_CLEANUP_KEY, Date.now());
         }
     }
     /**
      * Perform a cleanup of the expired entries in the cache.
      */
     static cleanupExpired() {
-        const cache = AsyncCache.getSharedCache();
-        for (const entry in cache) {
-            if (cache[entry].expires > 0 && cache[entry].expires < Date.now()) {
-                delete cache[entry];
-            }
+        const now = Date.now();
+        const lastCleanup = SharedStore.get(AsyncCache._LAST_CLEANUP_KEY) ?? 0;
+        if (now - lastCleanup < AsyncCache._CLEANUP_INTERVAL_MS) {
+            return;
+        }
+        const expiry = AsyncCache.getNextExpiry();
+        if (expiry !== undefined && expiry > now) {
+            // Nothing is expired yet. Stamp the time so the throttle suppresses further checks
+            // for the next interval. Per-key freshness is still guaranteed because exec() and
+            // get() call evictIfExpired() directly before reading the cache.
+            SharedStore.set(AsyncCache._LAST_CLEANUP_KEY, now);
+            return;
         }
+        SharedStore.set(AsyncCache._LAST_CLEANUP_KEY, now);
+        AsyncCache.recalculateNextKey();
     }
     /**
      * Get the shared cache.
@@ -168,12 +234,94 @@ export class AsyncCache {
      * @internal
      */
     static getSharedCache() {
-        let sharedCache = SharedStore.get("asyncCache");
+        let sharedCache = SharedStore.get(AsyncCache._CACHE_KEY);
         if (Is.undefined(sharedCache)) {
             sharedCache = {};
-            SharedStore.set("asyncCache", sharedCache);
+            SharedStore.set(AsyncCache._CACHE_KEY, sharedCache);
         }
         return sharedCache;
     }
+    /**
+     * Resolve a waiter by re-running its request method safely.
+     * @param requestMethod The method to execute.
+     * @param resolve The resolver for the waiter.
+     * @param reject The rejector for the waiter.
+     */
+    static async resolveWaiter(requestMethod, resolve, reject) {
+        try {
+            resolve(await requestMethod());
+        }
+        catch (waitErr) {
+            reject(waitErr);
+        }
+    }
+    /**
+     * Scan all cache entries, delete any that have expired, and record the key of the
+     * soonest-expiring remaining entry.
+     * @internal
+     */
+    static recalculateNextKey() {
+        const now = Date.now();
+        const cache = AsyncCache.getSharedCache();
+        if (Object.keys(cache).length === 0) {
+            SharedStore.set(AsyncCache._NEXT_EXPIRY_CACHE_KEY, undefined);
+            return;
+        }
+        let newNextKey;
+        let newNextExpiry = Number.MAX_SAFE_INTEGER;
+        for (const entryKey in cache) {
+            const { expires, inProgress } = cache[entryKey];
+            if (expires > 0 && expires < now && inProgress !== true) {
+                delete cache[entryKey];
+            }
+            else if (expires > 0 && expires < newNextExpiry) {
+                newNextExpiry = expires;
+                newNextKey = entryKey;
+            }
+        }
+        SharedStore.set(AsyncCache._NEXT_EXPIRY_CACHE_KEY, newNextKey);
+    }
+    /**
+     * Update the tracked next-expiry entry key if the given entry expires sooner than the current one.
+     * @param key The cache entry key.
+     * @param expires The expiry timestamp of the entry.
+     * @internal
+     */
+    static updateNextExpiryKey(key, expires) {
+        const expiry = AsyncCache.getNextExpiry();
+        if (expiry !== undefined && expiry <= expires) {
+            return;
+        }
+        SharedStore.set(AsyncCache._NEXT_EXPIRY_CACHE_KEY, key);
+    }
+    /**
+     * Deletes the given key from the cache if it has expired and is not in-progress.
+     * Returns true if the entry was evicted.
+     * @param key The cache entry key to check.
+     * @internal
+     */
+    static evictIfExpired(key) {
+        const cache = AsyncCache.getSharedCache();
+        const entry = cache[key];
+        if (!Is.empty(entry) && entry.expires > 0 && entry.expires < Date.now() && !entry.inProgress) {
+            delete cache[key];
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Returns the expiry timestamp of the tracked next-expiry entry, or undefined if there
+     * is no tracked entry or it is no longer present in the cache.
+     * @internal
+     */
+    static getNextExpiry() {
+        const nextKey = SharedStore.get(AsyncCache._NEXT_EXPIRY_CACHE_KEY);
+        if (Is.empty(nextKey)) {
+            return undefined;
+        }
+        const cache = AsyncCache.getSharedCache();
+        const nextEntry = cache[nextKey];
+        return Is.empty(nextEntry) ? undefined : nextEntry.expires;
+    }
 }
 //# sourceMappingURL=asyncCache.js.map