@fluidframework/tree 2.0.0-dev-rc.1.0.0.224419

package/dist/treeFactory.d.ts

@@ -0,0 +1,55 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { IChannelAttributes, IChannelFactory, IChannelServices, IFluidDataStoreRuntime } from "@fluidframework/datastore-definitions";
+import { IFluidHandle, IFluidLoadable } from "@fluidframework/core-interfaces";
+import { ITelemetryContext, ISummaryTreeWithStats, IExperimentalIncrementalSummaryContext, IGarbageCollectionData } from "@fluidframework/runtime-definitions";
+import { SharedTreeOptions } from "./shared-tree";
+import { ITree, ImplicitFieldSchema, TreeConfiguration, TreeFieldFromImplicitField, TreeView } from "./class-tree";
+/**
+ * Configuration to specialize a Tree DDS for a particular use.
+ * @internal
+ */
+export interface TreeOptions extends SharedTreeOptions {
+    /**
+     * Name appended to {@link @fluidframework/datastore-definitions#IChannelFactory."type"} to identify this factory configuration.
+     * @privateRemarks
+     * TODO: evaluate if this design is a good idea, or if "subtype" should be removed.
+     * TODO: evaluate if schematize should be separated from DDS construction.
+     */
+    readonly subtype?: string;
+}
+/**
+ * A channel factory that creates an {@link ITree}.
+ * @internal
+ */
+export declare class TreeFactory implements IChannelFactory {
+    private readonly options;
+    readonly type: string;
+    readonly attributes: IChannelAttributes;
+    constructor(options: TreeOptions);
+    load(runtime: IFluidDataStoreRuntime, id: string, services: IChannelServices, channelAttributes: Readonly<IChannelAttributes>): Promise<ITree>;
+    create(runtime: IFluidDataStoreRuntime, id: string): ITree;
+}
+/**
+ * SharedTree is a hierarchical data structure for collaboratively editing JSON-like trees
+ * of objects, arrays, and other data types.
+ *
+ * @internal
+ */
+export declare class SharedTree implements ITree {
+    static getFactory(): TreeFactory;
+    schematize<TRoot extends ImplicitFieldSchema>(config: TreeConfiguration<TRoot>): TreeView<TreeFieldFromImplicitField<TRoot>>;
+    private useFactory;
+    get id(): string;
+    get attributes(): IChannelAttributes;
+    get handle(): IFluidHandle;
+    get IFluidLoadable(): IFluidLoadable;
+    getAttachSummary(fullTree?: boolean | undefined, trackState?: boolean | undefined, telemetryContext?: ITelemetryContext | undefined): ISummaryTreeWithStats;
+    summarize(fullTree?: boolean | undefined, trackState?: boolean | undefined, telemetryContext?: ITelemetryContext | undefined, incrementalSummaryContext?: IExperimentalIncrementalSummaryContext | undefined): Promise<ISummaryTreeWithStats>;
+    isAttached(): boolean;
+    connect(services: IChannelServices): void;
+    getGCData(fullGC?: boolean | undefined): IGarbageCollectionData;
+}
+//# sourceMappingURL=treeFactory.d.ts.map

package/dist/treeFactory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"treeFactory.d.ts","sourceRoot":"","sources":["../src/treeFactory.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACN,kBAAkB,EAClB,eAAe,EACf,gBAAgB,EAChB,sBAAsB,EACtB,MAAM,uCAAuC,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AAC/E,OAAO,EACN,iBAAiB,EACjB,qBAAqB,EACrB,sCAAsC,EACtC,sBAAsB,EACtB,MAAM,qCAAqC,CAAC;AAC7C,OAAO,EAAgC,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAChF,OAAO,EACN,KAAK,EACL,mBAAmB,EACnB,iBAAiB,EACjB,0BAA0B,EAC1B,QAAQ,EACR,MAAM,cAAc,CAAC;AAEtB;;;GAGG;AACH,MAAM,WAAW,WAAY,SAAQ,iBAAiB;IACrD;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;GAGG;AACH,qBAAa,WAAY,YAAW,eAAe;IAI/B,OAAO,CAAC,QAAQ,CAAC,OAAO;IAH3C,SAAgB,IAAI,EAAE,MAAM,CAAC;IAC7B,SAAgB,UAAU,EAAE,kBAAkB,CAAC;gBAEX,OAAO,EAAE,WAAW;IAU3C,IAAI,CAChB,OAAO,EAAE,sBAAsB,EAC/B,EAAE,EAAE,MAAM,EACV,QAAQ,EAAE,gBAAgB,EAC1B,iBAAiB,EAAE,QAAQ,CAAC,kBAAkB,CAAC,GAC7C,OAAO,CAAC,KAAK,CAAC;IAMV,MAAM,CAAC,OAAO,EAAE,sBAAsB,EAAE,EAAE,EAAE,MAAM,GAAG,KAAK;CAKjE;AAED;;;;;GAKG;AACH,qBAAa,UAAW,YAAW,KAAK;WAOzB,UAAU,IAAI,WAAW;IAIhC,UAAU,CAAC,KAAK,SAAS,mBAAmB,EAClD,MAAM,EAAE,iBAAiB,CAAC,KAAK,CAAC,GAC9B,QAAQ,CAAC,0BAA0B,CAAC,KAAK,CAAC,CAAC;IAI9C,OAAO,CAAC,UAAU;IAIlB,IAAW,EAAE,IAAI,MAAM,CAEtB;IAED,IAAW,UAAU,IAAI,kBAAkB,CAE1C;IAED,IAAW,MAAM,IAAI,YAAY,CAEhC;IAED,IAAW,cAAc,IAAI,cAAc,CAE1C;IAEM,gBAAgB,CACtB,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,EAC9B,UAAU,CAAC,EAAE,OAAO,GAAG,SAAS,EAChC,gBAAgB,CAAC,EAAE,iBAAiB,GAAG,SAAS,GAC9C,qBAAqB;IAIX,SAAS,CACrB,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,EAC9B,UAAU,CAAC,EAAE,OAAO,GAAG,SAAS,EAChC,gBAAgB,CAAC,EAAE,iBAAiB,GAAG,SAAS,EAChD,yBAAyB,CAAC,EAAE,sCAAsC,GAAG,SAAS,GAC5E,OAAO,CAAC,qBAAqB,CAAC;IAI1B,UAAU,IAAI,OAAO;IAIrB,OAAO,CAAC,QAAQ,EAAE,gBAAgB,GAAG,IAAI;IAIzC,SAAS,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,SAAS,GAAG,sBAAsB;CAGtE"}

package/dist/treeFactory.js

@@ -0,0 +1,85 @@
+"use strict";
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SharedTree = exports.TreeFactory = void 0;
+const shared_tree_1 = require("./shared-tree");
+/**
+ * A channel factory that creates an {@link ITree}.
+ * @internal
+ */
+class TreeFactory {
+    constructor(options) {
+        this.options = options;
+        this.type = `https://graph.microsoft.com/types/tree/${options.subtype ?? "default"}`;
+        this.attributes = {
+            type: this.type,
+            snapshotFormatVersion: "0.0.0",
+            packageVersion: "0.0.0",
+        };
+    }
+    async load(runtime, id, services, channelAttributes) {
+        const tree = new shared_tree_1.SharedTree(id, runtime, channelAttributes, this.options, "SharedTree");
+        await tree.load(services);
+        return tree;
+    }
+    create(runtime, id) {
+        const tree = new shared_tree_1.SharedTree(id, runtime, this.attributes, this.options, "SharedTree");
+        tree.initializeLocal();
+        return tree;
+    }
+}
+exports.TreeFactory = TreeFactory;
+/**
+ * SharedTree is a hierarchical data structure for collaboratively editing JSON-like trees
+ * of objects, arrays, and other data types.
+ *
+ * @internal
+ */
+class SharedTree {
+    // The IFluidContainer ContainerSchema currently requires a constructable class that
+    // implements the union of IChannel and the interface to be returned to the user.
+    //
+    // Temporarily, we provide one until the following work items is addressed:
+    // https://dev.azure.com/fluidframework/internal/_workitems/edit/6458
+    static getFactory() {
+        return new TreeFactory({});
+    }
+    schematize(config) {
+        return this.useFactory();
+    }
+    useFactory() {
+        throw new Error("Use factory to create instance.");
+    }
+    get id() {
+        return this.useFactory();
+    }
+    get attributes() {
+        return this.useFactory();
+    }
+    get handle() {
+        return this.useFactory();
+    }
+    get IFluidLoadable() {
+        return this.useFactory();
+    }
+    getAttachSummary(fullTree, trackState, telemetryContext) {
+        return this.useFactory();
+    }
+    async summarize(fullTree, trackState, telemetryContext, incrementalSummaryContext) {
+        return this.useFactory();
+    }
+    isAttached() {
+        return this.useFactory();
+    }
+    connect(services) {
+        return this.useFactory();
+    }
+    getGCData(fullGC) {
+        return this.useFactory();
+    }
+}
+exports.SharedTree = SharedTree;
+//# sourceMappingURL=treeFactory.js.map

package/dist/treeFactory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"treeFactory.js","sourceRoot":"","sources":["../src/treeFactory.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAeH,+CAAgF;AAuBhF;;;GAGG;AACH,MAAa,WAAW;IAIvB,YAAoC,OAAoB;QAApB,YAAO,GAAP,OAAO,CAAa;QACvD,IAAI,CAAC,IAAI,GAAG,0CAA0C,OAAO,CAAC,OAAO,IAAI,SAAS,EAAE,CAAC;QAErF,IAAI,CAAC,UAAU,GAAG;YACjB,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,qBAAqB,EAAE,OAAO;YAC9B,cAAc,EAAE,OAAO;SACvB,CAAC;IACH,CAAC;IAEM,KAAK,CAAC,IAAI,CAChB,OAA+B,EAC/B,EAAU,EACV,QAA0B,EAC1B,iBAA+C;QAE/C,MAAM,IAAI,GAAG,IAAI,wBAAc,CAAC,EAAE,EAAE,OAAO,EAAE,iBAAiB,EAAE,IAAI,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;QAC5F,MAAM,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC1B,OAAO,IAAI,CAAC;IACb,CAAC;IAEM,MAAM,CAAC,OAA+B,EAAE,EAAU;QACxD,MAAM,IAAI,GAAG,IAAI,wBAAc,CAAC,EAAE,EAAE,OAAO,EAAE,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;QAC1F,IAAI,CAAC,eAAe,EAAE,CAAC;QACvB,OAAO,IAAI,CAAC;IACb,CAAC;CACD;AA9BD,kCA8BC;AAED;;;;;GAKG;AACH,MAAa,UAAU;IACtB,oFAAoF;IACpF,iFAAiF;IACjF,EAAE;IACF,2EAA2E;IAC3E,qEAAqE;IAE9D,MAAM,CAAC,UAAU;QACvB,OAAO,IAAI,WAAW,CAAC,EAAE,CAAC,CAAC;IAC5B,CAAC;IAEM,UAAU,CAChB,MAAgC;QAEhC,OAAO,IAAI,CAAC,UAAU,EAAE,CAAC;IAC1B,CAAC;IAEO,UAAU;QACjB,MAAM,IAAI,KAAK,CAAC,iCAAiC,CAAC,CAAC;IACpD,CAAC;IAED,IAAW,EAAE;QACZ,OAAO,IAAI,CAAC,UAAU,EAAE,CAAC;IAC1B,CAAC;IAED,IAAW,UAAU;QACpB,OAAO,IAAI,CAAC,UAAU,EAAE,CAAC;IAC1B,CAAC;IAED,IAAW,MAAM;QAChB,OAAO,IAAI,CAAC,UAAU,EAAE,CAAC;IAC1B,CAAC;IAED,IAAW,cAAc;QACxB,OAAO,IAAI,CAAC,UAAU,EAAE,CAAC;IAC1B,CAAC;IAEM,gBAAgB,CACtB,QAA8B,EAC9B,UAAgC,EAChC,gBAAgD;QAEhD,OAAO,IAAI,CAAC,UAAU,EAAE,CAAC;IAC1B,CAAC;IAEM,KAAK,CAAC,SAAS,CACrB,QAA8B,EAC9B,UAAgC,EAChC,gBAAgD,EAChD,yBAA8E;QAE9E,OAAO,IAAI,CAAC,UAAU,EAAE,CAAC;IAC1B,CAAC;IAEM,UAAU;QAChB,OAAO,IAAI,CAAC,UAAU,EAAE,CAAC;IAC1B,CAAC;IAEM,OAAO,CAAC,QAA0B;QACxC,OAAO,IAAI,CAAC,UAAU,EAAE,CAAC;IAC1B,CAAC;IAEM,SAAS,CAAC,MAA4B;QAC5C,OAAO,IAAI,CAAC,UAAU,EAAE,CAAC;IAC1B,CAAC;CACD;AAjED,gCAiEC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport {\n\tIChannelAttributes,\n\tIChannelFactory,\n\tIChannelServices,\n\tIFluidDataStoreRuntime,\n} from \"@fluidframework/datastore-definitions\";\nimport { IFluidHandle, IFluidLoadable } from \"@fluidframework/core-interfaces\";\nimport {\n\tITelemetryContext,\n\tISummaryTreeWithStats,\n\tIExperimentalIncrementalSummaryContext,\n\tIGarbageCollectionData,\n} from \"@fluidframework/runtime-definitions\";\nimport { SharedTree as SharedTreeImpl, SharedTreeOptions } from \"./shared-tree\";\nimport {\n\tITree,\n\tImplicitFieldSchema,\n\tTreeConfiguration,\n\tTreeFieldFromImplicitField,\n\tTreeView,\n} from \"./class-tree\";\n\n/**\n * Configuration to specialize a Tree DDS for a particular use.\n * @internal\n */\nexport interface TreeOptions extends SharedTreeOptions {\n\t/**\n\t * Name appended to {@link @fluidframework/datastore-definitions#IChannelFactory.\"type\"} to identify this factory configuration.\n\t * @privateRemarks\n\t * TODO: evaluate if this design is a good idea, or if \"subtype\" should be removed.\n\t * TODO: evaluate if schematize should be separated from DDS construction.\n\t */\n\treadonly subtype?: string;\n}\n\n/**\n * A channel factory that creates an {@link ITree}.\n * @internal\n */\nexport class TreeFactory implements IChannelFactory {\n\tpublic readonly type: string;\n\tpublic readonly attributes: IChannelAttributes;\n\n\tpublic constructor(private readonly options: TreeOptions) {\n\t\tthis.type = `https://graph.microsoft.com/types/tree/${options.subtype ?? \"default\"}`;\n\n\t\tthis.attributes = {\n\t\t\ttype: this.type,\n\t\t\tsnapshotFormatVersion: \"0.0.0\",\n\t\t\tpackageVersion: \"0.0.0\",\n\t\t};\n\t}\n\n\tpublic async load(\n\t\truntime: IFluidDataStoreRuntime,\n\t\tid: string,\n\t\tservices: IChannelServices,\n\t\tchannelAttributes: Readonly<IChannelAttributes>,\n\t): Promise<ITree> {\n\t\tconst tree = new SharedTreeImpl(id, runtime, channelAttributes, this.options, \"SharedTree\");\n\t\tawait tree.load(services);\n\t\treturn tree;\n\t}\n\n\tpublic create(runtime: IFluidDataStoreRuntime, id: string): ITree {\n\t\tconst tree = new SharedTreeImpl(id, runtime, this.attributes, this.options, \"SharedTree\");\n\t\ttree.initializeLocal();\n\t\treturn tree;\n\t}\n}\n\n/**\n * SharedTree is a hierarchical data structure for collaboratively editing JSON-like trees\n * of objects, arrays, and other data types.\n *\n * @internal\n */\nexport class SharedTree implements ITree {\n\t// The IFluidContainer ContainerSchema currently requires a constructable class that\n\t// implements the union of IChannel and the interface to be returned to the user.\n\t//\n\t// Temporarily, we provide one until the following work items is addressed:\n\t// https://dev.azure.com/fluidframework/internal/_workitems/edit/6458\n\n\tpublic static getFactory(): TreeFactory {\n\t\treturn new TreeFactory({});\n\t}\n\n\tpublic schematize<TRoot extends ImplicitFieldSchema>(\n\t\tconfig: TreeConfiguration<TRoot>,\n\t): TreeView<TreeFieldFromImplicitField<TRoot>> {\n\t\treturn this.useFactory();\n\t}\n\n\tprivate useFactory(): never {\n\t\tthrow new Error(\"Use factory to create instance.\");\n\t}\n\n\tpublic get id(): string {\n\t\treturn this.useFactory();\n\t}\n\n\tpublic get attributes(): IChannelAttributes {\n\t\treturn this.useFactory();\n\t}\n\n\tpublic get handle(): IFluidHandle {\n\t\treturn this.useFactory();\n\t}\n\n\tpublic get IFluidLoadable(): IFluidLoadable {\n\t\treturn this.useFactory();\n\t}\n\n\tpublic getAttachSummary(\n\t\tfullTree?: boolean | undefined,\n\t\ttrackState?: boolean | undefined,\n\t\ttelemetryContext?: ITelemetryContext | undefined,\n\t): ISummaryTreeWithStats {\n\t\treturn this.useFactory();\n\t}\n\n\tpublic async summarize(\n\t\tfullTree?: boolean | undefined,\n\t\ttrackState?: boolean | undefined,\n\t\ttelemetryContext?: ITelemetryContext | undefined,\n\t\tincrementalSummaryContext?: IExperimentalIncrementalSummaryContext | undefined,\n\t): Promise<ISummaryTreeWithStats> {\n\t\treturn this.useFactory();\n\t}\n\n\tpublic isAttached(): boolean {\n\t\treturn this.useFactory();\n\t}\n\n\tpublic connect(services: IChannelServices): void {\n\t\treturn this.useFactory();\n\t}\n\n\tpublic getGCData(fullGC?: boolean | undefined): IGarbageCollectionData {\n\t\treturn this.useFactory();\n\t}\n}\n"]}

package/dist/tsdoc-metadata.json

@@ -0,0 +1,11 @@
+// This file is read by tools that parse documentation comments conforming to the TSDoc standard.
+// It should be published with your NPM package.  It should not be tracked by Git.
+{
+  "tsdocVersion": "0.12",
+  "toolPackages": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "packageVersion": "7.38.3"
+    }
+  ]
+}

package/dist/util/brand.d.ts

@@ -0,0 +1,179 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { TUnsafe } from "@sinclair/typebox";
+import { Covariant, isAny } from "./typeCheck";
+import { Assume } from "./utils";
+/**
+ * Constructs a "Branded" type, adding a type-checking only field to `ValueType`.
+ *
+ * Two usages of `Brand` should never use the same `Name`.
+ * If they do, the resulting types will be assignable which defeats the point of this type.
+ *
+ * This type is constructed such that the first line of type errors when assigning
+ * mismatched branded types will be:
+ * `Type 'Name1' is not assignable to type 'Name2'.`
+ *
+ * These branded types are not opaque: A `Brand<A, B>` can still be used as a `B`.
+ * @internal
+ */
+export type Brand<ValueType, Name extends string | ErasedType<string>> = ValueType & BrandedType<ValueType, Name extends Erased<infer TName> ? TName : Assume<Name, string>>;
+/**
+ * "opaque" handle which can be used to expose a branded type without referencing its value type.
+ *
+ * Recommended usage is to use `interface` instead of `type` so tooling (such as tsc and refactoring tools)
+ * uses the type name instead of expanding it:
+ * ```typescript
+ * export interface MyType extends Erased<"myPackage.MyType">{}
+ * ```
+ * @internal
+ */
+export type Erased<Name extends string> = ErasedType<Name>;
+/**
+ * Helper for {@link Erased}.
+ * This is split out into its own as that's the only way to:
+ * - have doc comments for the member.
+ * - make the member protected (so you don't accidentally try and read it).
+ * - get nominal typing (so types produced without using this class can never be assignable to it).
+ *
+ * See `InternalTypes.MakeNominal` for some more details.
+ *
+ * Do not use this class with `instanceof`: this will always be false at runtime,
+ * but the compiler may think it's true in some cases.
+ *
+ * @sealed
+ * @internal
+ */
+export declare abstract class ErasedType<out Name extends string> {
+    /**
+     * Compile time only marker to make type checking more strict.
+     * This method will not exist at runtime and accessing it is invalid.
+     * See {@link Brand} for details.
+     *
+     * @privateRemarks
+     * `Name` is used as the return type of a method rather than a a simple readonly member as this allows types with two brands to be intersected without getting `never`.
+     * The method takes in never to help emphasize that its not callable.
+     */
+    protected abstract brand(dummy: never): Name;
+    /**
+     * This class should never exist at runtime, so make it un-constructable.
+     */
+    private constructor();
+}
+/**
+ * Helper for {@link Brand}.
+ * This is split out into its own as that's the only way to:
+ * - have doc comments for the member.
+ * - make the member protected (so you don't accidentally try and read it).
+ * - get nominal typing (so types produced without using this class can never be assignable to it).
+ * - allow use as {@link Opaque} branded type (not assignable to `ValueType`, but captures `ValueType`).
+ *
+ * See `InternalTypes.MakeNominal` for some more details.
+ *
+ * Do not use this class with `instanceof`: this will always be false at runtime,
+ * but the compiler may think it's true in some cases.
+ *
+ * @remarks
+ * This is covariant over ValueType.
+ * This is suitable for when ValueType is immutable (like string or number),
+ * which is the common use-case for branding.
+ *
+ * @sealed
+ * @internal
+ */
+export declare abstract class BrandedType<out ValueType, Name extends string> {
+    protected _typeCheck?: Covariant<ValueType>;
+    /**
+     * Compile time only marker to make type checking more strict.
+     * This method will not exist at runtime and accessing it is invalid.
+     * See {@link Brand} for details.
+     *
+     * @privateRemarks
+     * `Name` is used as the return type of a method rather than a a simple readonly member as this allows types with two brands to be intersected without getting `never`.
+     * The method takes in never to help emphasize that its not callable.
+     */
+    protected abstract brand(dummy: never): Name;
+    /**
+     * This class should never exist at runtime, so make it un-constructable.
+     */
+    private constructor();
+}
+/**
+ * Converts a Branded type into an "opaque" handle.
+ * This prevents the value from being used directly, but does not fully type erase it
+ * (and this its not really fully opaque):
+ * The type can be recovered using {@link extractFromOpaque},
+ * however if we assume only code that produces these "opaque" handles does that conversion,
+ * they can function like opaque handles.
+ *
+ * Recommended usage is to use `interface` instead of `type` so tooling (such as tsc and refactoring tools)
+ * uses the type name instead of expanding it:
+ * ```typescript
+ * export interface MyType extends Opaque<Brand<string, "myPackage.MyType">>{}
+ * ```
+ * @internal
+ */
+export type Opaque<T extends Brand<any, string>> = T extends BrandedType<infer ValueType, infer Name> ? BrandedType<ValueType, Name> : never;
+/**
+ * See {@link extractFromOpaque}.
+ * @internal
+ */
+export type ExtractFromOpaque<TOpaque extends BrandedType<any, string>> = TOpaque extends BrandedType<infer ValueType, infer Name> ? isAny<ValueType> extends true ? unknown : Brand<ValueType, Name> : never;
+/**
+ * Implementation detail of type branding. Should not be used directly outside this file,
+ * but shows up as part of branded types so API-Extractor requires it to be exported.
+ * @internal
+ */
+export type ValueFromBranded<T extends BrandedType<any, string>> = T extends BrandedType<infer ValueType, string> ? ValueType : never;
+/**
+ * Implementation detail of type branding. Should not be used directly outside this file,
+ * but shows up as part of branded types so API-Extractor requires it to be exported.
+ * @internal
+ */
+export type NameFromBranded<T extends BrandedType<any, string>> = T extends BrandedType<any, infer Name> ? Name : never;
+/**
+ * Converts a {@link Opaque} handle to the underlying branded type.
+ *
+ * It is assumed that only code that produces these "opaque" handles does this conversion,
+ * allowing these handles to be considered opaque.
+ * @internal
+ */
+export declare function extractFromOpaque<TOpaque extends BrandedType<any, string>>(value: TOpaque): ExtractFromOpaque<TOpaque>;
+/**
+ * Converts a {@link Erased} handle to the underlying branded type.
+ *
+ * It is assumed that only code that produces these "opaque" handles does this conversion,
+ * allowing these handles to be considered opaque.
+ * @internal
+ */
+export declare function fromErased<TBranded extends BrandedType<unknown, string>, TName extends string = NameFromBranded<TBranded>>(value: ErasedType<TName>): TBranded;
+/**
+ * Adds a type {@link Brand} to a value.
+ *
+ * Only do this when specifically allowed by the requirements of the type being converted to.
+ * @internal
+ */
+export declare function brand<T extends Brand<any, string>>(value: T extends BrandedType<infer ValueType, string> ? ValueType : never): T;
+/**
+ * Adds a type {@link Brand} to a value, returning it as a {@link Opaque} handle.
+ *
+ * Only do this when specifically allowed by the requirements of the type being converted to.
+ * @internal
+ */
+export declare function brandOpaque<T extends BrandedType<any, string>>(value: isAny<ValueFromBranded<T>> extends true ? never : ValueFromBranded<T>): BrandedType<ValueFromBranded<T>, NameFromBranded<T>>;
+/**
+ * Adds a type {@link Brand} to a value, returning it as a {@link Erased} handle.
+ *
+ * Only do this when specifically allowed by the requirements of the type being converted to.
+ * @internal
+ */
+export declare function brandErased<T extends BrandedType<any, string>>(value: isAny<ValueFromBranded<T>> extends true ? never : ValueFromBranded<T>): ErasedType<NameFromBranded<T>>;
+/**
+ * Create a TypeBox string schema for a branded string type.
+ * This only validates that the value is a string,
+ * and not that it came from the correct branded type (that information is lost when serialized).
+ */
+export declare function brandedStringType<T extends string>(): TUnsafe<T>;
+export declare function brandedNumberType<T extends number>(): TUnsafe<T>;
+//# sourceMappingURL=brand.d.ts.map

package/dist/util/brand.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"brand.d.ts","sourceRoot":"","sources":["../../src/util/brand.ts"],"names":[],"mappings":"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"}

package/dist/util/brand.js

@@ -0,0 +1,130 @@
+"use strict";
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.brandedNumberType = exports.brandedStringType = exports.brandErased = exports.brandOpaque = exports.brand = exports.fromErased = exports.extractFromOpaque = exports.BrandedType = exports.ErasedType = void 0;
+const typebox_1 = require("@sinclair/typebox");
+/**
+ * Helper for {@link Erased}.
+ * This is split out into its own as that's the only way to:
+ * - have doc comments for the member.
+ * - make the member protected (so you don't accidentally try and read it).
+ * - get nominal typing (so types produced without using this class can never be assignable to it).
+ *
+ * See `InternalTypes.MakeNominal` for some more details.
+ *
+ * Do not use this class with `instanceof`: this will always be false at runtime,
+ * but the compiler may think it's true in some cases.
+ *
+ * @sealed
+ * @internal
+ */
+class ErasedType {
+    /**
+     * This class should never exist at runtime, so make it un-constructable.
+     */
+    constructor() { }
+}
+exports.ErasedType = ErasedType;
+/**
+ * Helper for {@link Brand}.
+ * This is split out into its own as that's the only way to:
+ * - have doc comments for the member.
+ * - make the member protected (so you don't accidentally try and read it).
+ * - get nominal typing (so types produced without using this class can never be assignable to it).
+ * - allow use as {@link Opaque} branded type (not assignable to `ValueType`, but captures `ValueType`).
+ *
+ * See `InternalTypes.MakeNominal` for some more details.
+ *
+ * Do not use this class with `instanceof`: this will always be false at runtime,
+ * but the compiler may think it's true in some cases.
+ *
+ * @remarks
+ * This is covariant over ValueType.
+ * This is suitable for when ValueType is immutable (like string or number),
+ * which is the common use-case for branding.
+ *
+ * @sealed
+ * @internal
+ */
+class BrandedType {
+    /**
+     * This class should never exist at runtime, so make it un-constructable.
+     */
+    constructor() { }
+}
+exports.BrandedType = BrandedType;
+/**
+ * Converts a {@link Opaque} handle to the underlying branded type.
+ *
+ * It is assumed that only code that produces these "opaque" handles does this conversion,
+ * allowing these handles to be considered opaque.
+ * @internal
+ */
+function extractFromOpaque(value) {
+    return value;
+}
+exports.extractFromOpaque = extractFromOpaque;
+/**
+ * Converts a {@link Erased} handle to the underlying branded type.
+ *
+ * It is assumed that only code that produces these "opaque" handles does this conversion,
+ * allowing these handles to be considered opaque.
+ * @internal
+ */
+function fromErased(value) {
+    return value;
+}
+exports.fromErased = fromErased;
+/**
+ * Adds a type {@link Brand} to a value.
+ *
+ * Only do this when specifically allowed by the requirements of the type being converted to.
+ * @internal
+ */
+function brand(value) {
+    return value;
+}
+exports.brand = brand;
+/**
+ * Adds a type {@link Brand} to a value, returning it as a {@link Opaque} handle.
+ *
+ * Only do this when specifically allowed by the requirements of the type being converted to.
+ * @internal
+ */
+function brandOpaque(value) {
+    return value;
+}
+exports.brandOpaque = brandOpaque;
+/**
+ * Adds a type {@link Brand} to a value, returning it as a {@link Erased} handle.
+ *
+ * Only do this when specifically allowed by the requirements of the type being converted to.
+ * @internal
+ */
+function brandErased(value) {
+    return value;
+}
+exports.brandErased = brandErased;
+/**
+ * Create a TypeBox string schema for a branded string type.
+ * This only validates that the value is a string,
+ * and not that it came from the correct branded type (that information is lost when serialized).
+ */
+function brandedStringType() {
+    // This could use:
+    // return TypeSystem.CreateType<T>(name, (options, value) => typeof value === "string")();
+    // Since there isn't any useful custom validation to do and
+    // TUnsafe is documented as unsupported in `typebox/compiler`,
+    // opt for the compile time behavior like the above, but the runtime behavior of the built in string type.
+    return typebox_1.Type.String();
+}
+exports.brandedStringType = brandedStringType;
+function brandedNumberType() {
+    // See comments on `brandedStringType`.
+    return typebox_1.Type.Number();
+}
+exports.brandedNumberType = brandedNumberType;
+//# sourceMappingURL=brand.js.map

package/dist/util/brand.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"brand.js","sourceRoot":"","sources":["../../src/util/brand.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH,+CAAkD;AAgClD;;;;;;;;;;;;;;GAcG;AACH,MAAsB,UAAU;IAY/B;;OAEG;IACH,gBAAuB,CAAC;CACxB;AAhBD,gCAgBC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAsB,WAAW;IAahC;;OAEG;IACH,gBAAuB,CAAC;CACxB;AAjBD,kCAiBC;AA2DD;;;;;;GAMG;AACH,SAAgB,iBAAiB,CAChC,KAAc;IAEd,OAAO,KAAmC,CAAC;AAC5C,CAAC;AAJD,8CAIC;AAED;;;;;;GAMG;AACH,SAAgB,UAAU,CAGxB,KAAwB;IACzB,OAAO,KAA4B,CAAC;AACrC,CAAC;AALD,gCAKC;AAED;;;;;GAKG;AACH,SAAgB,KAAK,CACpB,KAAyE;IAEzE,OAAO,KAAU,CAAC;AACnB,CAAC;AAJD,sBAIC;AAED;;;;;GAKG;AACH,SAAgB,WAAW,CAC1B,KAA4E;IAE5E,OAAO,KAA6D,CAAC;AACtE,CAAC;AAJD,kCAIC;AAED;;;;;GAKG;AACH,SAAgB,WAAW,CAC1B,KAA4E;IAE5E,OAAO,KAAuC,CAAC;AAChD,CAAC;AAJD,kCAIC;AAED;;;;GAIG;AACH,SAAgB,iBAAiB;IAChC,kBAAkB;IAClB,0FAA0F;IAC1F,2DAA2D;IAC3D,8DAA8D;IAC9D,0GAA0G;IAC1G,OAAO,cAAI,CAAC,MAAM,EAA2B,CAAC;AAC/C,CAAC;AAPD,8CAOC;AAED,SAAgB,iBAAiB;IAChC,uCAAuC;IACvC,OAAO,cAAI,CAAC,MAAM,EAA2B,CAAC;AAC/C,CAAC;AAHD,8CAGC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { TUnsafe, Type } from \"@sinclair/typebox\";\nimport { Covariant, isAny } from \"./typeCheck\";\nimport { Assume } from \"./utils\";\n\n/**\n * Constructs a \"Branded\" type, adding a type-checking only field to `ValueType`.\n *\n * Two usages of `Brand` should never use the same `Name`.\n * If they do, the resulting types will be assignable which defeats the point of this type.\n *\n * This type is constructed such that the first line of type errors when assigning\n * mismatched branded types will be:\n * `Type 'Name1' is not assignable to type 'Name2'.`\n *\n * These branded types are not opaque: A `Brand<A, B>` can still be used as a `B`.\n * @internal\n */\nexport type Brand<ValueType, Name extends string | ErasedType<string>> = ValueType &\n\tBrandedType<ValueType, Name extends Erased<infer TName> ? TName : Assume<Name, string>>;\n\n/**\n * \"opaque\" handle which can be used to expose a branded type without referencing its value type.\n *\n * Recommended usage is to use `interface` instead of `type` so tooling (such as tsc and refactoring tools)\n * uses the type name instead of expanding it:\n * ```typescript\n * export interface MyType extends Erased<\"myPackage.MyType\">{}\n * ```\n * @internal\n */\nexport type Erased<Name extends string> = ErasedType<Name>;\n\n/**\n * Helper for {@link Erased}.\n * This is split out into its own as that's the only way to:\n * - have doc comments for the member.\n * - make the member protected (so you don't accidentally try and read it).\n * - get nominal typing (so types produced without using this class can never be assignable to it).\n *\n * See `InternalTypes.MakeNominal` for some more details.\n *\n * Do not use this class with `instanceof`: this will always be false at runtime,\n * but the compiler may think it's true in some cases.\n *\n * @sealed\n * @internal\n */\nexport abstract class ErasedType<out Name extends string> {\n\t/**\n\t * Compile time only marker to make type checking more strict.\n\t * This method will not exist at runtime and accessing it is invalid.\n\t * See {@link Brand} for details.\n\t *\n\t * @privateRemarks\n\t * `Name` is used as the return type of a method rather than a a simple readonly member as this allows types with two brands to be intersected without getting `never`.\n\t * The method takes in never to help emphasize that its not callable.\n\t */\n\tprotected abstract brand(dummy: never): Name;\n\n\t/**\n\t * This class should never exist at runtime, so make it un-constructable.\n\t */\n\tprivate constructor() {}\n}\n\n/**\n * Helper for {@link Brand}.\n * This is split out into its own as that's the only way to:\n * - have doc comments for the member.\n * - make the member protected (so you don't accidentally try and read it).\n * - get nominal typing (so types produced without using this class can never be assignable to it).\n * - allow use as {@link Opaque} branded type (not assignable to `ValueType`, but captures `ValueType`).\n *\n * See `InternalTypes.MakeNominal` for some more details.\n *\n * Do not use this class with `instanceof`: this will always be false at runtime,\n * but the compiler may think it's true in some cases.\n *\n * @remarks\n * This is covariant over ValueType.\n * This is suitable for when ValueType is immutable (like string or number),\n * which is the common use-case for branding.\n *\n * @sealed\n * @internal\n */\nexport abstract class BrandedType<out ValueType, Name extends string> {\n\tprotected _typeCheck?: Covariant<ValueType>;\n\t/**\n\t * Compile time only marker to make type checking more strict.\n\t * This method will not exist at runtime and accessing it is invalid.\n\t * See {@link Brand} for details.\n\t *\n\t * @privateRemarks\n\t * `Name` is used as the return type of a method rather than a a simple readonly member as this allows types with two brands to be intersected without getting `never`.\n\t * The method takes in never to help emphasize that its not callable.\n\t */\n\tprotected abstract brand(dummy: never): Name;\n\n\t/**\n\t * This class should never exist at runtime, so make it un-constructable.\n\t */\n\tprivate constructor() {}\n}\n\n/**\n * Converts a Branded type into an \"opaque\" handle.\n * This prevents the value from being used directly, but does not fully type erase it\n * (and this its not really fully opaque):\n * The type can be recovered using {@link extractFromOpaque},\n * however if we assume only code that produces these \"opaque\" handles does that conversion,\n * they can function like opaque handles.\n *\n * Recommended usage is to use `interface` instead of `type` so tooling (such as tsc and refactoring tools)\n * uses the type name instead of expanding it:\n * ```typescript\n * export interface MyType extends Opaque<Brand<string, \"myPackage.MyType\">>{}\n * ```\n * @internal\n */\nexport type Opaque<T extends Brand<any, string>> = T extends BrandedType<\n\tinfer ValueType,\n\tinfer Name\n>\n\t? BrandedType<ValueType, Name>\n\t: never;\n\n/**\n * See {@link extractFromOpaque}.\n * @internal\n */\nexport type ExtractFromOpaque<TOpaque extends BrandedType<any, string>> =\n\tTOpaque extends BrandedType<infer ValueType, infer Name>\n\t\t? isAny<ValueType> extends true\n\t\t\t? unknown\n\t\t\t: Brand<ValueType, Name>\n\t\t: never;\n\n/**\n * Implementation detail of type branding. Should not be used directly outside this file,\n * but shows up as part of branded types so API-Extractor requires it to be exported.\n * @internal\n */\nexport type ValueFromBranded<T extends BrandedType<any, string>> = T extends BrandedType<\n\tinfer ValueType,\n\tstring\n>\n\t? ValueType\n\t: never;\n\n/**\n * Implementation detail of type branding. Should not be used directly outside this file,\n * but shows up as part of branded types so API-Extractor requires it to be exported.\n * @internal\n */\nexport type NameFromBranded<T extends BrandedType<any, string>> = T extends BrandedType<\n\tany,\n\tinfer Name\n>\n\t? Name\n\t: never;\n\n/**\n * Converts a {@link Opaque} handle to the underlying branded type.\n *\n * It is assumed that only code that produces these \"opaque\" handles does this conversion,\n * allowing these handles to be considered opaque.\n * @internal\n */\nexport function extractFromOpaque<TOpaque extends BrandedType<any, string>>(\n\tvalue: TOpaque,\n): ExtractFromOpaque<TOpaque> {\n\treturn value as ExtractFromOpaque<TOpaque>;\n}\n\n/**\n * Converts a {@link Erased} handle to the underlying branded type.\n *\n * It is assumed that only code that produces these \"opaque\" handles does this conversion,\n * allowing these handles to be considered opaque.\n * @internal\n */\nexport function fromErased<\n\tTBranded extends BrandedType<unknown, string>,\n\tTName extends string = NameFromBranded<TBranded>,\n>(value: ErasedType<TName>): TBranded {\n\treturn value as unknown as TBranded;\n}\n\n/**\n * Adds a type {@link Brand} to a value.\n *\n * Only do this when specifically allowed by the requirements of the type being converted to.\n * @internal\n */\nexport function brand<T extends Brand<any, string>>(\n\tvalue: T extends BrandedType<infer ValueType, string> ? ValueType : never,\n): T {\n\treturn value as T;\n}\n\n/**\n * Adds a type {@link Brand} to a value, returning it as a {@link Opaque} handle.\n *\n * Only do this when specifically allowed by the requirements of the type being converted to.\n * @internal\n */\nexport function brandOpaque<T extends BrandedType<any, string>>(\n\tvalue: isAny<ValueFromBranded<T>> extends true ? never : ValueFromBranded<T>,\n): BrandedType<ValueFromBranded<T>, NameFromBranded<T>> {\n\treturn value as BrandedType<ValueFromBranded<T>, NameFromBranded<T>>;\n}\n\n/**\n * Adds a type {@link Brand} to a value, returning it as a {@link Erased} handle.\n *\n * Only do this when specifically allowed by the requirements of the type being converted to.\n * @internal\n */\nexport function brandErased<T extends BrandedType<any, string>>(\n\tvalue: isAny<ValueFromBranded<T>> extends true ? never : ValueFromBranded<T>,\n): ErasedType<NameFromBranded<T>> {\n\treturn value as ErasedType<NameFromBranded<T>>;\n}\n\n/**\n * Create a TypeBox string schema for a branded string type.\n * This only validates that the value is a string,\n * and not that it came from the correct branded type (that information is lost when serialized).\n */\nexport function brandedStringType<T extends string>(): TUnsafe<T> {\n\t// This could use:\n\t// return TypeSystem.CreateType<T>(name, (options, value) => typeof value === \"string\")();\n\t// Since there isn't any useful custom validation to do and\n\t// TUnsafe is documented as unsupported in `typebox/compiler`,\n\t// opt for the compile time behavior like the above, but the runtime behavior of the built in string type.\n\treturn Type.String() as unknown as TUnsafe<T>;\n}\n\nexport function brandedNumberType<T extends number>(): TUnsafe<T> {\n\t// See comments on `brandedStringType`.\n\treturn Type.Number() as unknown as TUnsafe<T>;\n}\n"]}

package/dist/util/brandedMap.d.ts

@@ -0,0 +1,46 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { Invariant } from "./typeCheck";
+/**
+ * Key in a {@link BrandedMapSubset}.
+ * @internal
+ */
+export type BrandedKey<TKey, TContent> = TKey & Invariant<TContent>;
+/**
+ * @internal
+ */
+export type BrandedKeyContent<TKey extends BrandedKey<unknown, any>> = TKey extends BrandedKey<unknown, infer TContent> ? TContent : never;
+/**
+ * A Map where the keys carry the types of values which they correspond to.
+ *
+ * Example usage:
+ * ```typescript
+ * type FooSlot<TContent> = BrandedKey<Opaque<Brand<number, "FooSlot">>, TContent>;
+ * const counterSlot = brandedSlot<FooSlot<number>>();
+ * const slots: BrandedMapSubset<FooSlot<any>> = new Map();
+ * slots.set(counterSlot, slots.get(counterSlot) ?? 0 + 1);
+ * ```
+ *
+ * @remarks
+ * These APIs are designed so that a Map can be used to implement this type.
+ *
+ * @internal
+ */
+export interface BrandedMapSubset<K extends BrandedKey<unknown, any>> {
+    get<K2 extends K>(key: K2): BrandedKeyContent<K2> | undefined;
+    has(key: K): boolean;
+    set<K2 extends K>(key: K2, value: BrandedKeyContent<K2>): this;
+    delete(key: K): boolean;
+}
+/**
+ * Version of {@link getOrCreate} with better typing for {@link BrandedMapSubset}.
+ */
+export declare function getOrCreateSlotContent<M extends BrandedMapSubset<BrandedKey<unknown, any>>, K extends BrandedKey<unknown, any>>(map: M, key: K, defaultValue: (key: K) => BrandedKeyContent<K>): BrandedKeyContent<K>;
+/**
+ * Define a strongly typed slot in which data can be stored in a {@link BrandedMapSubset}.
+ * @internal
+ */
+export declare function brandedSlot<TSlot extends BrandedKey<any, any>>(): TSlot;
+//# sourceMappingURL=brandedMap.d.ts.map

package/dist/util/brandedMap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"brandedMap.d.ts","sourceRoot":"","sources":["../../src/util/brandedMap.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAGxC;;;GAGG;AACH,MAAM,MAAM,UAAU,CAAC,IAAI,EAAE,QAAQ,IAAI,IAAI,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;AAEpE;;GAEG;AACH,MAAM,MAAM,iBAAiB,CAAC,IAAI,SAAS,UAAU,CAAC,OAAO,EAAE,GAAG,CAAC,IAAI,IAAI,SAAS,UAAU,CAC7F,OAAO,EACP,MAAM,QAAQ,CACd,GACE,QAAQ,GACR,KAAK,CAAC;AAET;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,gBAAgB,CAAC,CAAC,SAAS,UAAU,CAAC,OAAO,EAAE,GAAG,CAAC;IACnE,GAAG,CAAC,EAAE,SAAS,CAAC,EAAE,GAAG,EAAE,EAAE,GAAG,iBAAiB,CAAC,EAAE,CAAC,GAAG,SAAS,CAAC;IAC9D,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,OAAO,CAAC;IACrB,GAAG,CAAC,EAAE,SAAS,CAAC,EAAE,GAAG,EAAE,EAAE,EAAE,KAAK,EAAE,iBAAiB,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC;IAC/D,MAAM,CAAC,GAAG,EAAE,CAAC,GAAG,OAAO,CAAC;CACxB;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CACrC,CAAC,SAAS,gBAAgB,CAAC,UAAU,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC,EACpD,CAAC,SAAS,UAAU,CAAC,OAAO,EAAE,GAAG,CAAC,EACjC,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,YAAY,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,iBAAiB,CAAC,CAAC,CAAC,GAAG,iBAAiB,CAAC,CAAC,CAAC,CAItF;AASD;;;GAGG;AACH,wBAAgB,WAAW,CAAC,KAAK,SAAS,UAAU,CAAC,GAAG,EAAE,GAAG,CAAC,KAAK,KAAK,CAEvE"}

package/dist/util/brandedMap.js

@@ -0,0 +1,32 @@
+"use strict";
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.brandedSlot = exports.getOrCreateSlotContent = void 0;
+const utils_1 = require("./utils");
+/**
+ * Version of {@link getOrCreate} with better typing for {@link BrandedMapSubset}.
+ */
+function getOrCreateSlotContent(map, key, defaultValue) {
+    const result = (0, utils_1.getOrCreate)(map, key, defaultValue);
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+    return result;
+}
+exports.getOrCreateSlotContent = getOrCreateSlotContent;
+/**
+ * A counter used to allocate unique numbers (See {@link brandedSlot}) to use as {@link BrandedKey}s.
+ * This allows the keys to be small integers, which are efficient to use as keys in maps.
+ * See {@link BrandedMapSubset}.
+ */
+let slotCounter = 0;
+/**
+ * Define a strongly typed slot in which data can be stored in a {@link BrandedMapSubset}.
+ * @internal
+ */
+function brandedSlot() {
+    return slotCounter++;
+}
+exports.brandedSlot = brandedSlot;
+//# sourceMappingURL=brandedMap.js.map

package/dist/util/brandedMap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"brandedMap.js","sourceRoot":"","sources":["../../src/util/brandedMap.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAGH,mCAAsC;AAyCtC;;GAEG;AACH,SAAgB,sBAAsB,CAGpC,GAAM,EAAE,GAAM,EAAE,YAA8C;IAC/D,MAAM,MAAM,GAAyB,IAAA,mBAAW,EAAC,GAAG,EAAE,GAAG,EAAE,YAAY,CAAC,CAAC;IACzE,+DAA+D;IAC/D,OAAO,MAAM,CAAC;AACf,CAAC;AAPD,wDAOC;AAED;;;;GAIG;AACH,IAAI,WAAW,GAAG,CAAC,CAAC;AAEpB;;;GAGG;AACH,SAAgB,WAAW;IAC1B,OAAO,WAAW,EAAW,CAAC;AAC/B,CAAC;AAFD,kCAEC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { Invariant } from \"./typeCheck\";\nimport { getOrCreate } from \"./utils\";\n\n/**\n * Key in a {@link BrandedMapSubset}.\n * @internal\n */\nexport type BrandedKey<TKey, TContent> = TKey & Invariant<TContent>;\n\n/**\n * @internal\n */\nexport type BrandedKeyContent<TKey extends BrandedKey<unknown, any>> = TKey extends BrandedKey<\n\tunknown,\n\tinfer TContent\n>\n\t? TContent\n\t: never;\n\n/**\n * A Map where the keys carry the types of values which they correspond to.\n *\n * Example usage:\n * ```typescript\n * type FooSlot<TContent> = BrandedKey<Opaque<Brand<number, \"FooSlot\">>, TContent>;\n * const counterSlot = brandedSlot<FooSlot<number>>();\n * const slots: BrandedMapSubset<FooSlot<any>> = new Map();\n * slots.set(counterSlot, slots.get(counterSlot) ?? 0 + 1);\n * ```\n *\n * @remarks\n * These APIs are designed so that a Map can be used to implement this type.\n *\n * @internal\n */\nexport interface BrandedMapSubset<K extends BrandedKey<unknown, any>> {\n\tget<K2 extends K>(key: K2): BrandedKeyContent<K2> | undefined;\n\thas(key: K): boolean;\n\tset<K2 extends K>(key: K2, value: BrandedKeyContent<K2>): this;\n\tdelete(key: K): boolean;\n}\n\n/**\n * Version of {@link getOrCreate} with better typing for {@link BrandedMapSubset}.\n */\nexport function getOrCreateSlotContent<\n\tM extends BrandedMapSubset<BrandedKey<unknown, any>>,\n\tK extends BrandedKey<unknown, any>,\n>(map: M, key: K, defaultValue: (key: K) => BrandedKeyContent<K>): BrandedKeyContent<K> {\n\tconst result: BrandedKeyContent<K> = getOrCreate(map, key, defaultValue);\n\t// eslint-disable-next-line @typescript-eslint/no-unsafe-return\n\treturn result;\n}\n\n/**\n * A counter used to allocate unique numbers (See {@link brandedSlot}) to use as {@link BrandedKey}s.\n * This allows the keys to be small integers, which are efficient to use as keys in maps.\n * See {@link BrandedMapSubset}.\n */\nlet slotCounter = 0;\n\n/**\n * Define a strongly typed slot in which data can be stored in a {@link BrandedMapSubset}.\n * @internal\n */\nexport function brandedSlot<TSlot extends BrandedKey<any, any>>(): TSlot {\n\treturn slotCounter++ as TSlot;\n}\n"]}

package/dist/util/idAllocator.d.ts

@@ -0,0 +1,29 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+/**
+ * Used for allocating IDs unique to a particular instance of the allocator.
+ * @internal
+ */
+export interface IdAllocator<TId = number> {
+    /**
+     * Allocates a block of `count` consecutive IDs and returns the first ID in the block.
+     * For convenience can be called with no parameters to allocate a single ID.
+     */
+    allocate: (count?: number) => TId;
+    /**
+     * @returns The next ID that will be allocated by this allocator.
+     */
+    getNextId: () => TId;
+}
+export interface IdAllocationState {
+    maxId: number;
+}
+/**
+ * @internal
+ */
+export declare function idAllocatorFromMaxId(maxId?: number | undefined): IdAllocator;
+export declare function idAllocatorFromState(state: IdAllocationState): IdAllocator;
+export declare const fakeIdAllocator: IdAllocator;
+//# sourceMappingURL=idAllocator.d.ts.map

package/dist/util/idAllocator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"idAllocator.d.ts","sourceRoot":"","sources":["../../src/util/idAllocator.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH;;;GAGG;AACH,MAAM,WAAW,WAAW,CAAC,GAAG,GAAG,MAAM;IACxC;;;OAGG;IACH,QAAQ,EAAE,CAAC,KAAK,CAAC,EAAE,MAAM,KAAK,GAAG,CAAC;IAClC;;OAEG;IACH,SAAS,EAAE,MAAM,GAAG,CAAC;CACrB;AAED,MAAM,WAAW,iBAAiB;IACjC,KAAK,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,GAAE,MAAM,GAAG,SAAqB,GAAG,WAAW,CAEvF;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,iBAAiB,GAAG,WAAW,CAW1E;AAED,eAAO,MAAM,eAAe,EAAE,WAG7B,CAAC"}