@twin.org/context 0.0.3-next.1

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2024 IOTA Stiftung.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,21 @@
+# TWIN Framework Context
+
+This package contains helper methods and classes for using contexts.
+
+## Installation
+
+```shell
+npm install @twin.org/context
+```
+
+## Examples
+
+Usage of the APIs is shown in the examples [docs/examples.md](docs/examples.md)
+
+## Reference
+
+Detailed reference documentation for the API can be found in [docs/reference/index.md](docs/reference/index.md)
+
+## Changelog
+
+The changes between each version can be found in [docs/changelog.md](docs/changelog.md)

package/dist/es/factories/contextIdHandlerFactory.js

@@ -0,0 +1,9 @@
+// Copyright 2024 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+import { Factory } from "@twin.org/core";
+/**
+ * Factory for creating implementation of context ID handlers.
+ */
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export const ContextIdHandlerFactory = Factory.createFactory("contextIdHandler");
+//# sourceMappingURL=contextIdHandlerFactory.js.map

package/dist/es/factories/contextIdHandlerFactory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contextIdHandlerFactory.js","sourceRoot":"","sources":["../../../src/factories/contextIdHandlerFactory.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AACvC,OAAO,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAGzC;;GAEG;AACH,gEAAgE;AAChE,MAAM,CAAC,MAAM,uBAAuB,GAAG,OAAO,CAAC,aAAa,CAAoB,kBAAkB,CAAC,CAAC","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport { Factory } from \"@twin.org/core\";\nimport type { IContextIdHandler } from \"../models/IContextIdHandler.js\";\n\n/**\n * Factory for creating implementation of context ID handlers.\n */\n// eslint-disable-next-line @typescript-eslint/naming-convention\nexport const ContextIdHandlerFactory = Factory.createFactory<IContextIdHandler>(\"contextIdHandler\");\n"]}

package/dist/es/helpers/contextIdHelper.js

@@ -0,0 +1,144 @@
+// Copyright 2024 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+import { GeneralError, Guards, Is } from "@twin.org/core";
+import { ContextIdHandlerFactory } from "../factories/contextIdHandlerFactory.js";
+/**
+ * Class to help with context IDs.
+ */
+export class ContextIdHelper {
+    /**
+     * Runtime name for the class.
+     */
+    static CLASS_NAME = "ContextIdHelper";
+    /**
+     * Perform a runtime guard on the provided context ID value.
+     * @param contextIds The context IDs to guard.
+     * @param key The context ID key to guard.
+     * @throws Guard error if the value is invalid.
+     */
+    static guard(contextIds, key) {
+        Guards.stringValue(ContextIdHelper.CLASS_NAME, "key", key);
+        if (Is.undefined(contextIds?.[key])) {
+            throw new GeneralError(ContextIdHelper.CLASS_NAME, "contextIdMissing", { key });
+        }
+        const handler = ContextIdHandlerFactory.getIfExists(key);
+        if (handler?.guard) {
+            handler.guard(contextIds[key]);
+        }
+        else {
+            Guards.stringValue(ContextIdHelper.CLASS_NAME, `contextIds.${key}`, contextIds[key]);
+        }
+    }
+    /**
+     * Gets the short version of a context ID.
+     * @param contextIds The context IDs to get the short version from.
+     * @param key The context ID key to get the short version for.
+     * @returns The short version of the context ID.
+     * @throws Guard error if the value is invalid.
+     */
+    static short(contextIds, key) {
+        Guards.stringValue(ContextIdHelper.CLASS_NAME, "key", key);
+        if (Is.undefined(contextIds?.[key])) {
+            throw new GeneralError(ContextIdHelper.CLASS_NAME, "contextIdMissing", { key });
+        }
+        const handler = ContextIdHandlerFactory.getIfExists(key);
+        if (handler?.short) {
+            return handler.short(contextIds[key]);
+        }
+        return contextIds[key];
+    }
+    /**
+     * Perform a runtime guard on the provided context ID values.
+     * @param contextIds The context IDs to guard.
+     * @param keys The context ID keys to guard.
+     * @throws Guard error if the value is invalid.
+     */
+    static guardAll(contextIds, keys) {
+        if (Is.arrayValue(keys)) {
+            for (const key of keys) {
+                ContextIdHelper.guard(contextIds, key);
+            }
+        }
+    }
+    /**
+     * Gets the short versions of multiple context IDs.
+     * @param contextIds The context IDs to get the short versions from.
+     * @param keys The context ID keys to get the short versions for.
+     * @returns The short versions of the context IDs.
+     */
+    static shortAll(contextIds, keys) {
+        const short = {};
+        if (Is.arrayValue(keys)) {
+            for (const key of keys) {
+                short[key] = ContextIdHelper.short(contextIds, key);
+            }
+        }
+        return short;
+    }
+    /**
+     * Gets the combined short version.
+     * @param contextIds The context IDs to get the short versions from.
+     * @param keys The context ID keys to get the short versions for.
+     * @param separator The separator to use between parts.
+     * @returns The short version combined.
+     */
+    static shortCombined(contextIds, keys, separator = "/") {
+        const short = ContextIdHelper.shortAll(contextIds, keys);
+        if (Object.keys(short).length === 0) {
+            return undefined;
+        }
+        return Object.values(short).join(separator);
+    }
+    /**
+     * Split a combined short version in to the separate context IDs.
+     * @param keys The context ID keys to get the short versions for.
+     * @param combined The combined short version to separate.
+     * @param separator The separator used between parts.
+     * @returns The short version combined.
+     * @throws GeneralError if the number of parts does not match the number of keys.
+     */
+    static shortSplit(keys, combined, separator = "/") {
+        Guards.arrayValue(ContextIdHelper.CLASS_NAME, "keys", keys);
+        Guards.stringValue(ContextIdHelper.CLASS_NAME, "combined", combined);
+        const parts = combined.split(separator);
+        const result = {};
+        if (parts.length !== keys.length) {
+            throw new GeneralError(ContextIdHelper.CLASS_NAME, "contextIdSplitMismatch", {
+                expected: keys.length,
+                actual: parts.length
+            });
+        }
+        for (let i = 0; i < keys.length; i++) {
+            result[keys[i]] = parts[i];
+        }
+        return result;
+    }
+    /**
+     * Create a combined key.
+     * @param contextIds The context IDs to create the combined key for.
+     * @param keys The context ID keys to get the short versions for.
+     * @param separator The separator to use between parts.
+     * @returns The short version combined.
+     */
+    static combinedContextKey(contextIds, keys, separator = "/") {
+        ContextIdHelper.guardAll(contextIds, keys);
+        const short = ContextIdHelper.shortAll(contextIds, keys);
+        if (Object.keys(short).length === 0) {
+            return undefined;
+        }
+        return Object.values(short).join(separator);
+    }
+    /**
+     * Pick only the desired keys from the available keys.
+     * @param availableKeys The available keys to pick from.
+     * @param desiredKeys The desired keys to pick.
+     * @returns The picked keys.
+     */
+    static pickKeysFromAvailable(availableKeys, desiredKeys) {
+        if (!Is.arrayValue(availableKeys) || !Is.arrayValue(desiredKeys)) {
+            return [];
+        }
+        return desiredKeys.filter(key => availableKeys.includes(key));
+    }
+}
+//# sourceMappingURL=contextIdHelper.js.map

package/dist/es/helpers/contextIdHelper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contextIdHelper.js","sourceRoot":"","sources":["../../../src/helpers/contextIdHelper.ts"],"names":[],"mappings":"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","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport { GeneralError, Guards, Is } from \"@twin.org/core\";\nimport { nameof } from \"@twin.org/nameof\";\nimport { ContextIdHandlerFactory } from \"../factories/contextIdHandlerFactory.js\";\nimport type { IContextIds } from \"../models/IContextIds.js\";\n\n/**\n * Class to help with context IDs.\n */\nexport class ContextIdHelper {\n\t/**\n\t * Runtime name for the class.\n\t */\n\tpublic static readonly CLASS_NAME: string = nameof<ContextIdHelper>();\n\n\t/**\n\t * Perform a runtime guard on the provided context ID value.\n\t * @param contextIds The context IDs to guard.\n\t * @param key The context ID key to guard.\n\t * @throws Guard error if the value is invalid.\n\t */\n\tpublic static guard<T extends { [k: string]: string | undefined }, K extends string>(\n\t\tcontextIds: T | undefined,\n\t\tkey: K\n\t): asserts contextIds is T & { [P in K]: string } {\n\t\tGuards.stringValue(ContextIdHelper.CLASS_NAME, nameof(key), key);\n\n\t\tif (Is.undefined(contextIds?.[key])) {\n\t\t\tthrow new GeneralError(ContextIdHelper.CLASS_NAME, \"contextIdMissing\", { key });\n\t\t}\n\n\t\tconst handler = ContextIdHandlerFactory.getIfExists(key);\n\t\tif (handler?.guard) {\n\t\t\thandler.guard(contextIds[key]);\n\t\t} else {\n\t\t\tGuards.stringValue(ContextIdHelper.CLASS_NAME, `contextIds.${key}`, contextIds[key]);\n\t\t}\n\t}\n\n\t/**\n\t * Gets the short version of a context ID.\n\t * @param contextIds The context IDs to get the short version from.\n\t * @param key The context ID key to get the short version for.\n\t * @returns The short version of the context ID.\n\t * @throws Guard error if the value is invalid.\n\t */\n\tpublic static short(contextIds: IContextIds | undefined, key: string): string {\n\t\tGuards.stringValue(ContextIdHelper.CLASS_NAME, nameof(key), key);\n\t\tif (Is.undefined(contextIds?.[key])) {\n\t\t\tthrow new GeneralError(ContextIdHelper.CLASS_NAME, \"contextIdMissing\", { key });\n\t\t}\n\n\t\tconst handler = ContextIdHandlerFactory.getIfExists(key);\n\t\tif (handler?.short) {\n\t\t\treturn handler.short(contextIds[key]);\n\t\t}\n\t\treturn contextIds[key];\n\t}\n\n\t/**\n\t * Perform a runtime guard on the provided context ID values.\n\t * @param contextIds The context IDs to guard.\n\t * @param keys The context ID keys to guard.\n\t * @throws Guard error if the value is invalid.\n\t */\n\tpublic static guardAll<T extends { [k: string]: string | undefined }, K extends string>(\n\t\tcontextIds: T | undefined,\n\t\tkeys: readonly K[] | undefined\n\t): asserts contextIds is T & { [P in K]: string } {\n\t\tif (Is.arrayValue(keys)) {\n\t\t\tfor (const key of keys) {\n\t\t\t\tContextIdHelper.guard(contextIds, key);\n\t\t\t}\n\t\t}\n\t}\n\n\t/**\n\t * Gets the short versions of multiple context IDs.\n\t * @param contextIds The context IDs to get the short versions from.\n\t * @param keys The context ID keys to get the short versions for.\n\t * @returns The short versions of the context IDs.\n\t */\n\tpublic static shortAll(\n\t\tcontextIds: IContextIds | undefined,\n\t\tkeys: string[] | undefined\n\t): IContextIds {\n\t\tconst short: IContextIds = {};\n\t\tif (Is.arrayValue(keys)) {\n\t\t\tfor (const key of keys) {\n\t\t\t\tshort[key] = ContextIdHelper.short(contextIds, key);\n\t\t\t}\n\t\t}\n\t\treturn short;\n\t}\n\n\t/**\n\t * Gets the combined short version.\n\t * @param contextIds The context IDs to get the short versions from.\n\t * @param keys The context ID keys to get the short versions for.\n\t * @param separator The separator to use between parts.\n\t * @returns The short version combined.\n\t */\n\tpublic static shortCombined(\n\t\tcontextIds: IContextIds | undefined,\n\t\tkeys: string[] | undefined,\n\t\tseparator: string = \"/\"\n\t): string | undefined {\n\t\tconst short = ContextIdHelper.shortAll(contextIds, keys);\n\t\tif (Object.keys(short).length === 0) {\n\t\t\treturn undefined;\n\t\t}\n\t\treturn Object.values(short).join(separator);\n\t}\n\n\t/**\n\t * Split a combined short version in to the separate context IDs.\n\t * @param keys The context ID keys to get the short versions for.\n\t * @param combined The combined short version to separate.\n\t * @param separator The separator used between parts.\n\t * @returns The short version combined.\n\t * @throws GeneralError if the number of parts does not match the number of keys.\n\t */\n\tpublic static shortSplit(keys: string[], combined: string, separator: string = \"/\"): IContextIds {\n\t\tGuards.arrayValue<string>(ContextIdHelper.CLASS_NAME, nameof(keys), keys);\n\t\tGuards.stringValue(ContextIdHelper.CLASS_NAME, nameof(combined), combined);\n\n\t\tconst parts = combined.split(separator);\n\t\tconst result: IContextIds = {};\n\n\t\tif (parts.length !== keys.length) {\n\t\t\tthrow new GeneralError(ContextIdHelper.CLASS_NAME, \"contextIdSplitMismatch\", {\n\t\t\t\texpected: keys.length,\n\t\t\t\tactual: parts.length\n\t\t\t});\n\t\t}\n\n\t\tfor (let i = 0; i < keys.length; i++) {\n\t\t\tresult[keys[i]] = parts[i];\n\t\t}\n\n\t\treturn result;\n\t}\n\n\t/**\n\t * Create a combined key.\n\t * @param contextIds The context IDs to create the combined key for.\n\t * @param keys The context ID keys to get the short versions for.\n\t * @param separator The separator to use between parts.\n\t * @returns The short version combined.\n\t */\n\tpublic static combinedContextKey(\n\t\tcontextIds: IContextIds | undefined,\n\t\tkeys: string[] | undefined,\n\t\tseparator: string = \"/\"\n\t): string | undefined {\n\t\tContextIdHelper.guardAll(contextIds, keys);\n\n\t\tconst short = ContextIdHelper.shortAll(contextIds, keys);\n\n\t\tif (Object.keys(short).length === 0) {\n\t\t\treturn undefined;\n\t\t}\n\n\t\treturn Object.values(short).join(separator);\n\t}\n\n\t/**\n\t * Pick only the desired keys from the available keys.\n\t * @param availableKeys The available keys to pick from.\n\t * @param desiredKeys The desired keys to pick.\n\t * @returns The picked keys.\n\t */\n\tpublic static pickKeysFromAvailable(availableKeys?: string[], desiredKeys?: string[]): string[] {\n\t\tif (!Is.arrayValue(availableKeys) || !Is.arrayValue(desiredKeys)) {\n\t\t\treturn [];\n\t\t}\n\n\t\treturn desiredKeys.filter(key => availableKeys.includes(key));\n\t}\n}\n"]}

package/dist/es/index.js

@@ -0,0 +1,9 @@
+// Copyright 2024 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+export * from "./factories/contextIdHandlerFactory.js";
+export * from "./helpers/contextIdHelper.js";
+export * from "./models/contextIdKeys.js";
+export * from "./models/IContextIdHandler.js";
+export * from "./models/IContextIds.js";
+export * from "./utils/contextIdStore.js";
+//# sourceMappingURL=index.js.map

package/dist/es/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AACvC,cAAc,wCAAwC,CAAC;AACvD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,yBAAyB,CAAC;AACxC,cAAc,2BAA2B,CAAC","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nexport * from \"./factories/contextIdHandlerFactory.js\";\nexport * from \"./helpers/contextIdHelper.js\";\nexport * from \"./models/contextIdKeys.js\";\nexport * from \"./models/IContextIdHandler.js\";\nexport * from \"./models/IContextIds.js\";\nexport * from \"./utils/contextIdStore.js\";\n"]}

package/dist/es/models/IContextIdHandler.js

@@ -0,0 +1,4 @@
+// Copyright 2024 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+export {};
+//# sourceMappingURL=IContextIdHandler.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"IContextIdHandler.js","sourceRoot":"","sources":["../../../src/models/IContextIdHandler.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\n\n/**\n * Interface describing a context ID handler.\n */\nexport interface IContextIdHandler {\n\t/**\n\t * The short form version of the context ID, should be unique enough to partition data.\n\t * @param value The full context ID value.\n\t * @returns The short form version of the context ID.\n\t */\n\tshort?(value: string): string;\n\n\t/**\n\t * Performs a runtime guard on the provided context ID value.\n\t * @param value The context ID value to guard.\n\t * @throws Guard error if the value is invalid.\n\t */\n\tguard?(value: string): void;\n}\n"]}

package/dist/es/models/IContextIds.js

@@ -0,0 +1,4 @@
+// Copyright 2024 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+export {};
+//# sourceMappingURL=IContextIds.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"IContextIds.js","sourceRoot":"","sources":["../../../src/models/IContextIds.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\n\n/**\n * Interface describing context ids which can be accessed async from a request.\n */\nexport interface IContextIds {\n\t/**\n\t * The context id keys and values.\n\t */\n\t[id: string]: string | undefined;\n}\n"]}

package/dist/es/models/contextIdKeys.js

@@ -0,0 +1,25 @@
+// Copyright 2024 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+/**
+ * Default definition of some context keys.
+ */
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export const ContextIdKeys = {
+    /**
+     * Standard property type definition for node.
+     */
+    Node: "node",
+    /**
+     * Standard property type definition for tenant.
+     */
+    Tenant: "tenant",
+    /**
+     * Standard property type definition for organization.
+     */
+    Organization: "organization",
+    /**
+     * Standard property type definition for user.
+     */
+    User: "user"
+};
+//# sourceMappingURL=contextIdKeys.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"contextIdKeys.js","sourceRoot":"","sources":["../../../src/models/contextIdKeys.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AAEvC;;GAEG;AACH,gEAAgE;AAChE,MAAM,CAAC,MAAM,aAAa,GAAG;IAC5B;;OAEG;IACH,IAAI,EAAE,MAAM;IAEZ;;OAEG;IACH,MAAM,EAAE,QAAQ;IAEhB;;OAEG;IACH,YAAY,EAAE,cAAc;IAE5B;;OAEG;IACH,IAAI,EAAE,MAAM;CACH,CAAC","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\n\n/**\n * Default definition of some context keys.\n */\n// eslint-disable-next-line @typescript-eslint/naming-convention\nexport const ContextIdKeys = {\n\t/**\n\t * Standard property type definition for node.\n\t */\n\tNode: \"node\",\n\n\t/**\n\t * Standard property type definition for tenant.\n\t */\n\tTenant: \"tenant\",\n\n\t/**\n\t * Standard property type definition for organization.\n\t */\n\tOrganization: \"organization\",\n\n\t/**\n\t * Standard property type definition for user.\n\t */\n\tUser: \"user\"\n} as const;\n\n/**\n * Default definition of some context keys.\n */\nexport type ContextIdKeys = (typeof ContextIdKeys)[keyof typeof ContextIdKeys];\n"]}

package/dist/es/utils/contextIdStore.js

@@ -0,0 +1,49 @@
+import { BaseError, GeneralError } from "@twin.org/core";
+/**
+ * Class to maintain context ids and execute an async method.
+ */
+export class ContextIdStore {
+    /**
+     * Runtime name for the class.
+     */
+    static CLASS_NAME = "ContextIdStore";
+    /**
+     * The async local storage for the context ids.
+     */
+    static _storage;
+    /**
+     * Execute the method wrapped in the context.
+     * @param contextIds The context IDs.
+     * @param asyncMethod The async method to run.
+     * @returns Nothing.
+     */
+    static async run(contextIds, asyncMethod) {
+        return (await ContextIdStore.createStorage()).run(contextIds, asyncMethod);
+    }
+    /**
+     * Get the context IDs.
+     * @returns The context IDs.
+     */
+    static async getContextIds() {
+        return (await ContextIdStore.createStorage()).getStore();
+    }
+    /**
+     * Create the storage if it doesn't exist.
+     * @returns The storage.
+     */
+    static async createStorage() {
+        if (!ContextIdStore._storage) {
+            try {
+                const hooks = await import("node:async_hooks");
+                ContextIdStore._storage = new hooks.AsyncLocalStorage({
+                    name: "AsyncContextIdsStorage"
+                });
+            }
+            catch (err) {
+                throw new GeneralError(ContextIdStore.CLASS_NAME, "asyncHooksNotAvailable", undefined, BaseError.fromError(err));
+            }
+        }
+        return ContextIdStore._storage;
+    }
+}
+//# sourceMappingURL=contextIdStore.js.map

package/dist/es/utils/contextIdStore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contextIdStore.js","sourceRoot":"","sources":["../../../src/utils/contextIdStore.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAIzD;;GAEG;AACH,MAAM,OAAO,cAAc;IAC1B;;OAEG;IACI,MAAM,CAAU,UAAU,oBAAoC;IAErE;;OAEG;IACK,MAAM,CAAC,QAAQ,CAAiC;IAExD;;;;;OAKG;IACI,MAAM,CAAC,KAAK,CAAC,GAAG,CAAc,UAAuB,EAAE,WAAoB;QACjF,OAAO,CAAC,MAAM,cAAc,CAAC,aAAa,EAAE,CAAC,CAAC,GAAG,CAAI,UAAU,EAAE,WAAW,CAAC,CAAC;IAC/E,CAAC;IAED;;;OAGG;IACI,MAAM,CAAC,KAAK,CAAC,aAAa;QAChC,OAAO,CAAC,MAAM,cAAc,CAAC,aAAa,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC;IAC1D,CAAC;IAED;;;OAGG;IACK,MAAM,CAAC,KAAK,CAAC,aAAa;QACjC,IAAI,CAAC,cAAc,CAAC,QAAQ,EAAE,CAAC;YAC9B,IAAI,CAAC;gBACJ,MAAM,KAAK,GAAG,MAAM,MAAM,CAAC,kBAAkB,CAAC,CAAC;gBAC/C,cAAc,CAAC,QAAQ,GAAG,IAAI,KAAK,CAAC,iBAAiB,CAAc;oBAClE,IAAI,EAAE,wBAAwB;iBAC9B,CAAC,CAAC;YACJ,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACd,MAAM,IAAI,YAAY,CACrB,cAAc,CAAC,UAAU,EACzB,wBAAwB,EACxB,SAAS,EACT,SAAS,CAAC,SAAS,CAAC,GAAG,CAAC,CACxB,CAAC;YACH,CAAC;QACF,CAAC;QACD,OAAO,cAAc,CAAC,QAAQ,CAAC;IAChC,CAAC","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { AsyncLocalStorage } from \"node:async_hooks\";\nimport { BaseError, GeneralError } from \"@twin.org/core\";\nimport { nameof } from \"@twin.org/nameof\";\nimport type { IContextIds } from \"../models/IContextIds.js\";\n\n/**\n * Class to maintain context ids and execute an async method.\n */\nexport class ContextIdStore {\n\t/**\n\t * Runtime name for the class.\n\t */\n\tpublic static readonly CLASS_NAME: string = nameof<ContextIdStore>();\n\n\t/**\n\t * The async local storage for the context ids.\n\t */\n\tprivate static _storage: AsyncLocalStorage<IContextIds>;\n\n\t/**\n\t * Execute the method wrapped in the context.\n\t * @param contextIds The context IDs.\n\t * @param asyncMethod The async method to run.\n\t * @returns Nothing.\n\t */\n\tpublic static async run<T = unknown>(contextIds: IContextIds, asyncMethod: () => T): Promise<T> {\n\t\treturn (await ContextIdStore.createStorage()).run<T>(contextIds, asyncMethod);\n\t}\n\n\t/**\n\t * Get the context IDs.\n\t * @returns The context IDs.\n\t */\n\tpublic static async getContextIds(): Promise<IContextIds | undefined> {\n\t\treturn (await ContextIdStore.createStorage()).getStore();\n\t}\n\n\t/**\n\t * Create the storage if it doesn't exist.\n\t * @returns The storage.\n\t */\n\tprivate static async createStorage(): Promise<AsyncLocalStorage<IContextIds>> {\n\t\tif (!ContextIdStore._storage) {\n\t\t\ttry {\n\t\t\t\tconst hooks = await import(\"node:async_hooks\");\n\t\t\t\tContextIdStore._storage = new hooks.AsyncLocalStorage<IContextIds>({\n\t\t\t\t\tname: \"AsyncContextIdsStorage\"\n\t\t\t\t});\n\t\t\t} catch (err) {\n\t\t\t\tthrow new GeneralError(\n\t\t\t\t\tContextIdStore.CLASS_NAME,\n\t\t\t\t\t\"asyncHooksNotAvailable\",\n\t\t\t\t\tundefined,\n\t\t\t\t\tBaseError.fromError(err)\n\t\t\t\t);\n\t\t\t}\n\t\t}\n\t\treturn ContextIdStore._storage;\n\t}\n}\n"]}

package/dist/types/factories/contextIdHandlerFactory.d.ts

@@ -0,0 +1,6 @@
+import { Factory } from "@twin.org/core";
+import type { IContextIdHandler } from "../models/IContextIdHandler.js";
+/**
+ * Factory for creating implementation of context ID handlers.
+ */
+export declare const ContextIdHandlerFactory: Factory<IContextIdHandler>;

package/dist/types/helpers/contextIdHelper.d.ts

@@ -0,0 +1,79 @@
+import type { IContextIds } from "../models/IContextIds.js";
+/**
+ * Class to help with context IDs.
+ */
+export declare class ContextIdHelper {
+    /**
+     * Runtime name for the class.
+     */
+    static readonly CLASS_NAME: string;
+    /**
+     * Perform a runtime guard on the provided context ID value.
+     * @param contextIds The context IDs to guard.
+     * @param key The context ID key to guard.
+     * @throws Guard error if the value is invalid.
+     */
+    static guard<T extends {
+        [k: string]: string | undefined;
+    }, K extends string>(contextIds: T | undefined, key: K): asserts contextIds is T & {
+        [P in K]: string;
+    };
+    /**
+     * Gets the short version of a context ID.
+     * @param contextIds The context IDs to get the short version from.
+     * @param key The context ID key to get the short version for.
+     * @returns The short version of the context ID.
+     * @throws Guard error if the value is invalid.
+     */
+    static short(contextIds: IContextIds | undefined, key: string): string;
+    /**
+     * Perform a runtime guard on the provided context ID values.
+     * @param contextIds The context IDs to guard.
+     * @param keys The context ID keys to guard.
+     * @throws Guard error if the value is invalid.
+     */
+    static guardAll<T extends {
+        [k: string]: string | undefined;
+    }, K extends string>(contextIds: T | undefined, keys: readonly K[] | undefined): asserts contextIds is T & {
+        [P in K]: string;
+    };
+    /**
+     * Gets the short versions of multiple context IDs.
+     * @param contextIds The context IDs to get the short versions from.
+     * @param keys The context ID keys to get the short versions for.
+     * @returns The short versions of the context IDs.
+     */
+    static shortAll(contextIds: IContextIds | undefined, keys: string[] | undefined): IContextIds;
+    /**
+     * Gets the combined short version.
+     * @param contextIds The context IDs to get the short versions from.
+     * @param keys The context ID keys to get the short versions for.
+     * @param separator The separator to use between parts.
+     * @returns The short version combined.
+     */
+    static shortCombined(contextIds: IContextIds | undefined, keys: string[] | undefined, separator?: string): string | undefined;
+    /**
+     * Split a combined short version in to the separate context IDs.
+     * @param keys The context ID keys to get the short versions for.
+     * @param combined The combined short version to separate.
+     * @param separator The separator used between parts.
+     * @returns The short version combined.
+     * @throws GeneralError if the number of parts does not match the number of keys.
+     */
+    static shortSplit(keys: string[], combined: string, separator?: string): IContextIds;
+    /**
+     * Create a combined key.
+     * @param contextIds The context IDs to create the combined key for.
+     * @param keys The context ID keys to get the short versions for.
+     * @param separator The separator to use between parts.
+     * @returns The short version combined.
+     */
+    static combinedContextKey(contextIds: IContextIds | undefined, keys: string[] | undefined, separator?: string): string | undefined;
+    /**
+     * Pick only the desired keys from the available keys.
+     * @param availableKeys The available keys to pick from.
+     * @param desiredKeys The desired keys to pick.
+     * @returns The picked keys.
+     */
+    static pickKeysFromAvailable(availableKeys?: string[], desiredKeys?: string[]): string[];
+}

package/dist/types/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./factories/contextIdHandlerFactory.js";
+export * from "./helpers/contextIdHelper.js";
+export * from "./models/contextIdKeys.js";
+export * from "./models/IContextIdHandler.js";
+export * from "./models/IContextIds.js";
+export * from "./utils/contextIdStore.js";

package/dist/types/models/IContextIdHandler.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Interface describing a context ID handler.
+ */
+export interface IContextIdHandler {
+    /**
+     * The short form version of the context ID, should be unique enough to partition data.
+     * @param value The full context ID value.
+     * @returns The short form version of the context ID.
+     */
+    short?(value: string): string;
+    /**
+     * Performs a runtime guard on the provided context ID value.
+     * @param value The context ID value to guard.
+     * @throws Guard error if the value is invalid.
+     */
+    guard?(value: string): void;
+}

package/dist/types/models/IContextIds.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Interface describing context ids which can be accessed async from a request.
+ */
+export interface IContextIds {
+    /**
+     * The context id keys and values.
+     */
+    [id: string]: string | undefined;
+}

package/dist/types/models/contextIdKeys.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Default definition of some context keys.
+ */
+export declare const ContextIdKeys: {
+    /**
+     * Standard property type definition for node.
+     */
+    readonly Node: "node";
+    /**
+     * Standard property type definition for tenant.
+     */
+    readonly Tenant: "tenant";
+    /**
+     * Standard property type definition for organization.
+     */
+    readonly Organization: "organization";
+    /**
+     * Standard property type definition for user.
+     */
+    readonly User: "user";
+};
+/**
+ * Default definition of some context keys.
+ */
+export type ContextIdKeys = (typeof ContextIdKeys)[keyof typeof ContextIdKeys];

package/dist/types/utils/contextIdStore.d.ts

@@ -0,0 +1,31 @@
+import type { IContextIds } from "../models/IContextIds.js";
+/**
+ * Class to maintain context ids and execute an async method.
+ */
+export declare class ContextIdStore {
+    /**
+     * Runtime name for the class.
+     */
+    static readonly CLASS_NAME: string;
+    /**
+     * The async local storage for the context ids.
+     */
+    private static _storage;
+    /**
+     * Execute the method wrapped in the context.
+     * @param contextIds The context IDs.
+     * @param asyncMethod The async method to run.
+     * @returns Nothing.
+     */
+    static run<T = unknown>(contextIds: IContextIds, asyncMethod: () => T): Promise<T>;
+    /**
+     * Get the context IDs.
+     * @returns The context IDs.
+     */
+    static getContextIds(): Promise<IContextIds | undefined>;
+    /**
+     * Create the storage if it doesn't exist.
+     * @returns The storage.
+     */
+    private static createStorage;
+}

package/docs/changelog.md

@@ -0,0 +1,22 @@
+# Changelog
+
+## [0.0.3-next.1](https://github.com/twinfoundation/framework/compare/context-v0.0.3-next.0...context-v0.0.3-next.1) (2025-11-10)
+
+
+### Features
+
+* add context id features ([#206](https://github.com/twinfoundation/framework/issues/206)) ([ef0d4ee](https://github.com/twinfoundation/framework/commit/ef0d4ee11a4f5fc6cc6f52a4958ce905c04ee13b))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/core bumped from 0.0.3-next.0 to 0.0.3-next.1
+    * @twin.org/nameof bumped from 0.0.3-next.0 to 0.0.3-next.1
+  * devDependencies
+    * @twin.org/nameof-transformer bumped from 0.0.3-next.0 to 0.0.3-next.1
+    * @twin.org/nameof-vitest-plugin bumped from 0.0.3-next.0 to 0.0.3-next.1
+    * @twin.org/validate-locales bumped from 0.0.3-next.0 to 0.0.3-next.1
+
+## @twin.org/context - Changelog

package/docs/examples.md

@@ -0,0 +1 @@
+# @twin.org/context - Examples

package/docs/reference/classes/ContextIdHelper.md

@@ -0,0 +1,295 @@
+# Class: ContextIdHelper
+
+Class to help with context IDs.
+
+## Constructors
+
+### Constructor
+
+> **new ContextIdHelper**(): `ContextIdHelper`
+
+#### Returns
+
+`ContextIdHelper`
+
+## Properties
+
+### CLASS\_NAME
+
+> `readonly` `static` **CLASS\_NAME**: `string`
+
+Runtime name for the class.
+
+## Methods
+
+### guard()
+
+> `static` **guard**\<`T`, `K`\>(`contextIds`, `key`): `asserts contextIds is T & { [P in string]: string }`
+
+Perform a runtime guard on the provided context ID value.
+
+#### Type Parameters
+
+##### T
+
+`T` *extends* `object`
+
+##### K
+
+`K` *extends* `string`
+
+#### Parameters
+
+##### contextIds
+
+The context IDs to guard.
+
+`T` | `undefined`
+
+##### key
+
+`K`
+
+The context ID key to guard.
+
+#### Returns
+
+`asserts contextIds is T & { [P in string]: string }`
+
+#### Throws
+
+Guard error if the value is invalid.
+
+***
+
+### short()
+
+> `static` **short**(`contextIds`, `key`): `string`
+
+Gets the short version of a context ID.
+
+#### Parameters
+
+##### contextIds
+
+The context IDs to get the short version from.
+
+[`IContextIds`](../interfaces/IContextIds.md) | `undefined`
+
+##### key
+
+`string`
+
+The context ID key to get the short version for.
+
+#### Returns
+
+`string`
+
+The short version of the context ID.
+
+#### Throws
+
+Guard error if the value is invalid.
+
+***
+
+### guardAll()
+
+> `static` **guardAll**\<`T`, `K`\>(`contextIds`, `keys`): `asserts contextIds is T & { [P in string]: string }`
+
+Perform a runtime guard on the provided context ID values.
+
+#### Type Parameters
+
+##### T
+
+`T` *extends* `object`
+
+##### K
+
+`K` *extends* `string`
+
+#### Parameters
+
+##### contextIds
+
+The context IDs to guard.
+
+`T` | `undefined`
+
+##### keys
+
+The context ID keys to guard.
+
+readonly `K`[] | `undefined`
+
+#### Returns
+
+`asserts contextIds is T & { [P in string]: string }`
+
+#### Throws
+
+Guard error if the value is invalid.
+
+***
+
+### shortAll()
+
+> `static` **shortAll**(`contextIds`, `keys`): [`IContextIds`](../interfaces/IContextIds.md)
+
+Gets the short versions of multiple context IDs.
+
+#### Parameters
+
+##### contextIds
+
+The context IDs to get the short versions from.
+
+[`IContextIds`](../interfaces/IContextIds.md) | `undefined`
+
+##### keys
+
+The context ID keys to get the short versions for.
+
+`string`[] | `undefined`
+
+#### Returns
+
+[`IContextIds`](../interfaces/IContextIds.md)
+
+The short versions of the context IDs.
+
+***
+
+### shortCombined()
+
+> `static` **shortCombined**(`contextIds`, `keys`, `separator`): `string` \| `undefined`
+
+Gets the combined short version.
+
+#### Parameters
+
+##### contextIds
+
+The context IDs to get the short versions from.
+
+[`IContextIds`](../interfaces/IContextIds.md) | `undefined`
+
+##### keys
+
+The context ID keys to get the short versions for.
+
+`string`[] | `undefined`
+
+##### separator
+
+`string` = `"/"`
+
+The separator to use between parts.
+
+#### Returns
+
+`string` \| `undefined`
+
+The short version combined.
+
+***
+
+### shortSplit()
+
+> `static` **shortSplit**(`keys`, `combined`, `separator`): [`IContextIds`](../interfaces/IContextIds.md)
+
+Split a combined short version in to the separate context IDs.
+
+#### Parameters
+
+##### keys
+
+`string`[]
+
+The context ID keys to get the short versions for.
+
+##### combined
+
+`string`
+
+The combined short version to separate.
+
+##### separator
+
+`string` = `"/"`
+
+The separator used between parts.
+
+#### Returns
+
+[`IContextIds`](../interfaces/IContextIds.md)
+
+The short version combined.
+
+#### Throws
+
+GeneralError if the number of parts does not match the number of keys.
+
+***
+
+### combinedContextKey()
+
+> `static` **combinedContextKey**(`contextIds`, `keys`, `separator`): `string` \| `undefined`
+
+Create a combined key.
+
+#### Parameters
+
+##### contextIds
+
+The context IDs to create the combined key for.
+
+[`IContextIds`](../interfaces/IContextIds.md) | `undefined`
+
+##### keys
+
+The context ID keys to get the short versions for.
+
+`string`[] | `undefined`
+
+##### separator
+
+`string` = `"/"`
+
+The separator to use between parts.
+
+#### Returns
+
+`string` \| `undefined`
+
+The short version combined.
+
+***
+
+### pickKeysFromAvailable()
+
+> `static` **pickKeysFromAvailable**(`availableKeys?`, `desiredKeys?`): `string`[]
+
+Pick only the desired keys from the available keys.
+
+#### Parameters
+
+##### availableKeys?
+
+`string`[]
+
+The available keys to pick from.
+
+##### desiredKeys?
+
+`string`[]
+
+The desired keys to pick.
+
+#### Returns
+
+`string`[]
+
+The picked keys.

package/docs/reference/classes/ContextIdStore.md

@@ -0,0 +1,69 @@
+# Class: ContextIdStore
+
+Class to maintain context ids and execute an async method.
+
+## Constructors
+
+### Constructor
+
+> **new ContextIdStore**(): `ContextIdStore`
+
+#### Returns
+
+`ContextIdStore`
+
+## Properties
+
+### CLASS\_NAME
+
+> `readonly` `static` **CLASS\_NAME**: `string`
+
+Runtime name for the class.
+
+## Methods
+
+### run()
+
+> `static` **run**\<`T`\>(`contextIds`, `asyncMethod`): `Promise`\<`T`\>
+
+Execute the method wrapped in the context.
+
+#### Type Parameters
+
+##### T
+
+`T` = `unknown`
+
+#### Parameters
+
+##### contextIds
+
+[`IContextIds`](../interfaces/IContextIds.md)
+
+The context IDs.
+
+##### asyncMethod
+
+() => `T`
+
+The async method to run.
+
+#### Returns
+
+`Promise`\<`T`\>
+
+Nothing.
+
+***
+
+### getContextIds()
+
+> `static` **getContextIds**(): `Promise`\<[`IContextIds`](../interfaces/IContextIds.md) \| `undefined`\>
+
+Get the context IDs.
+
+#### Returns
+
+`Promise`\<[`IContextIds`](../interfaces/IContextIds.md) \| `undefined`\>
+
+The context IDs.

package/docs/reference/index.md

@@ -0,0 +1,20 @@
+# @twin.org/context
+
+## Classes
+
+- [ContextIdHelper](classes/ContextIdHelper.md)
+- [ContextIdStore](classes/ContextIdStore.md)
+
+## Interfaces
+
+- [IContextIdHandler](interfaces/IContextIdHandler.md)
+- [IContextIds](interfaces/IContextIds.md)
+
+## Type Aliases
+
+- [ContextIdKeys](type-aliases/ContextIdKeys.md)
+
+## Variables
+
+- [ContextIdHandlerFactory](variables/ContextIdHandlerFactory.md)
+- [ContextIdKeys](variables/ContextIdKeys.md)

package/docs/reference/interfaces/IContextIdHandler.md

@@ -0,0 +1,49 @@
+# Interface: IContextIdHandler
+
+Interface describing a context ID handler.
+
+## Methods
+
+### short()?
+
+> `optional` **short**(`value`): `string`
+
+The short form version of the context ID, should be unique enough to partition data.
+
+#### Parameters
+
+##### value
+
+`string`
+
+The full context ID value.
+
+#### Returns
+
+`string`
+
+The short form version of the context ID.
+
+***
+
+### guard()?
+
+> `optional` **guard**(`value`): `void`
+
+Performs a runtime guard on the provided context ID value.
+
+#### Parameters
+
+##### value
+
+`string`
+
+The context ID value to guard.
+
+#### Returns
+
+`void`
+
+#### Throws
+
+Guard error if the value is invalid.

package/docs/reference/interfaces/IContextIds.md

@@ -0,0 +1,9 @@
+# Interface: IContextIds
+
+Interface describing context ids which can be accessed async from a request.
+
+## Indexable
+
+\[`id`: `string`\]: `string` \| `undefined`
+
+The context id keys and values.

package/docs/reference/type-aliases/ContextIdKeys.md

@@ -0,0 +1,5 @@
+# Type Alias: ContextIdKeys
+
+> **ContextIdKeys** = *typeof* [`ContextIdKeys`](../variables/ContextIdKeys.md)\[keyof *typeof* [`ContextIdKeys`](../variables/ContextIdKeys.md)\]
+
+Default definition of some context keys.

package/docs/reference/variables/ContextIdHandlerFactory.md

@@ -0,0 +1,5 @@
+# Variable: ContextIdHandlerFactory
+
+> `const` **ContextIdHandlerFactory**: `Factory`\<[`IContextIdHandler`](../interfaces/IContextIdHandler.md)\>
+
+Factory for creating implementation of context ID handlers.

package/docs/reference/variables/ContextIdKeys.md

@@ -0,0 +1,31 @@
+# Variable: ContextIdKeys
+
+> `const` **ContextIdKeys**: `object`
+
+Default definition of some context keys.
+
+## Type Declaration
+
+### Node
+
+> `readonly` **Node**: `"node"` = `"node"`
+
+Standard property type definition for node.
+
+### Tenant
+
+> `readonly` **Tenant**: `"tenant"` = `"tenant"`
+
+Standard property type definition for tenant.
+
+### Organization
+
+> `readonly` **Organization**: `"organization"` = `"organization"`
+
+Standard property type definition for organization.
+
+### User
+
+> `readonly` **User**: `"user"` = `"user"`
+
+Standard property type definition for user.

package/locales/en.json

@@ -0,0 +1,11 @@
+{
+	"error": {
+		"contextIdHelper": {
+			"contextIdMissing": "The context ID \"{key}\" is missing from the provided context IDs",
+			"contextIdSplitMismatch": "The context ID split parts length \"{actual}\" does not match the provided keys length \"{expected}\""
+		},
+		"contextIdStore": {
+			"asyncHooksNotAvailable": "Async Hooks are not available in this environment, please ensure you are running in Node.js"
+		}
+	}
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+	"name": "@twin.org/context",
+	"version": "0.0.3-next.1",
+	"description": "Helper methods/classes for context handling",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/twinfoundation/framework.git",
+		"directory": "packages/context"
+	},
+	"author": "martyn.janes@iota.org",
+	"license": "Apache-2.0",
+	"type": "module",
+	"engines": {
+		"node": ">=20.0.0"
+	},
+	"dependencies": {
+		"@twin.org/core": "0.0.3-next.1",
+		"@twin.org/nameof": "0.0.3-next.1"
+	},
+	"main": "./dist/es/index.js",
+	"types": "./dist/types/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/types/index.d.ts",
+			"import": "./dist/es/index.js",
+			"default": "./dist/es/index.js"
+		},
+		"./locales/*.json": "./locales/*.json"
+	},
+	"files": [
+		"dist/es",
+		"dist/types",
+		"locales",
+		"docs"
+	],
+	"keywords": [
+		"twin",
+		"trade",
+		"iota",
+		"framework",
+		"blockchain",
+		"context",
+		"foundation",
+		"utilities"
+	],
+	"bugs": {
+		"url": "git+https://github.com/twinfoundation/framework/issues"
+	},
+	"homepage": "https://twindev.org"
+}