@fluidframework/core-interfaces 2.92.0 → 2.100.0

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # @fluidframework/core-interfaces
 
+## 2.100.0
+
+### Minor Changes
+
+- Node 22 is now the minimum supported Node.js version ([#27116](https://github.com/microsoft/FluidFramework/pull/27116)) [e8214d29663](https://github.com/microsoft/FluidFramework/commit/e8214d29663f5ee98d737daed82506a25d8de8d0)
+
+  All Fluid Framework client packages now require Node.js 22 or later. This aligns with the standing Node upgrade policy as Node 20 reaches end-of-life on April 30, 2026.
+
+## 2.93.0
+
+### Minor Changes
+
+- Add Fluid-controlled map and iterator interfaces ([#26951](https://github.com/microsoft/FluidFramework/pull/26951)) [4735742f15](https://github.com/microsoft/FluidFramework/commit/4735742f15718419e974ead1d5e2e809863d3723)
+
+  `TreeIndex` now extends `FluidReadonlyMap` instead of the built-in `ReadonlyMap`, and `TreeMapNodeAlpha` which extends `FluidReadonlyMap` instead of the built-in `ReadonlyMap` has been added.
+  This works to uncouple Fluid's public API surface to the TypeScript standard library's map types, preventing future breakage when those types change.
+
+- Promote tree index APIs from alpha to beta ([#26993](https://github.com/microsoft/FluidFramework/pull/26993)) [37f2f17c118](https://github.com/microsoft/FluidFramework/commit/37f2f17c118baea142b0e842f5b262255d8bb12c)
+
+  The following APIs have been promoted from `@alpha` to `@beta`:
+  - `TreeIndex`
+  - `TreeIndexKey`
+  - `TreeIndexNodes`
+  - `createTreeIndex`
+  - `IdentifierIndex`
+  - `createIdentifierIndex`
+
+  Additionally, the following `@fluidframework/core-interfaces` types have been promoted from `@alpha` to `@beta`:
+  - `FluidReadonlyMap`
+  - `FluidIterable`
+  - `FluidIterableIterator`
+  - `FluidMap`
+
 ## 2.92.0
 
 Dependency updates only.

package/README.md

@@ -59,7 +59,7 @@ When making such a request please include if the configuration already works (an
 
 ### Supported Runtimes
 
--   NodeJs ^20.10.0 except that we will drop support for it [when NodeJs 20 loses its upstream support on 2026-04-30](https://github.com/nodejs/release#release-schedule), and will support a newer LTS version of NodeJS (22) at least 1 year before 20 is end-of-life. This same policy applies to NodeJS 22 when it is end of life (2027-04-30).
+-   NodeJs ^22.22.2 except that we will drop support for it [when NodeJs 22 loses its upstream support on 2027-04-30](https://github.com/nodejs/release#release-schedule), and will support a newer LTS version of NodeJS at least 1 year before 22 is end-of-life.
     -   Running Fluid in a Node.js environment with the `--no-experimental-fetch` flag is not supported.
 -   Modern browsers supporting the es2022 standard library: in response to asks we can add explicit support for using babel to polyfill to target specific standards or runtimes (meaning we can avoid/remove use of things that don't polyfill robustly, but otherwise target modern standards).
 

package/api-report/core-interfaces.beta.api.md

@@ -4,6 +4,13 @@
 
 ```ts
 
+// @public
+export class BrandedType<out Brand> {
+    static [Symbol.hasInstance](value: never): value is never;
+    protected constructor();
+    protected readonly brand: (dummy: never) => Brand;
+}
+
 // @public
 export type ConfigTypes = string | number | boolean | number[] | string[] | boolean[] | undefined;
 
@@ -319,15 +326,20 @@ export type Listeners<T extends object> = {
 };
 
 // @public
-export const LogLevel: {
-    readonly verbose: 10;
-    readonly default: 20;
-    readonly error: 30;
-};
+export const LogLevel: LogLevelConst;
 
 // @public
 export type LogLevel = (typeof LogLevel)[keyof typeof LogLevel];
 
+// @public
+export interface LogLevelConst {
+    readonly default: 20;
+    readonly error: 30;
+    readonly essential: 30;
+    readonly info: 20;
+    readonly verbose: 10;
+}
+
 // @public
 export type Off = () => void;
 

package/api-report/core-interfaces.legacy.alpha.api.md

@@ -4,7 +4,7 @@
 
 ```ts
 
-// @beta
+// @public
 export class BrandedType<out Brand> {
     static [Symbol.hasInstance](value: never): value is never;
     protected constructor();
@@ -58,6 +58,29 @@ export type FluidErrorTypesAlpha = (typeof FluidErrorTypesAlpha)[keyof typeof Fl
 // @public
 export const fluidHandleSymbol: unique symbol;
 
+// @beta @sealed
+export interface FluidIterable<T> {
+    [Symbol.iterator](): FluidIterableIterator<T>;
+}
+
+// @beta @sealed
+export interface FluidIterableIterator<T> extends FluidIterable<T> {
+    next(): {
+        value: T;
+        done?: false;
+    } | {
+        value: any;
+        done: true;
+    };
+}
+
+// @beta @sealed
+export interface FluidMap<K, V> extends FluidReadonlyMap<K, V> {
+    delete(key: K): void;
+    forEach(callbackfn: (value: V, key: K, map: FluidMap<K, V>) => void, thisArg?: any): void;
+    set(key: K, value: V): void;
+}
+
 // @public
 export type FluidObject<T = unknown> = {
     [P in FluidObjectProviderKeys<T>]?: T[P];
@@ -69,6 +92,19 @@ export type FluidObjectKeys<T> = keyof FluidObject<T>;
 // @public
 export type FluidObjectProviderKeys<T, TProp extends keyof T = keyof T> = string extends TProp ? never : number extends TProp ? never : TProp extends keyof Required<T>[TProp] ? Required<T>[TProp] extends Required<Required<T>[TProp]>[TProp] ? TProp : never : never;
 
+// @beta @sealed
+export interface FluidReadonlyMap<K, V> {
+    [Symbol.iterator](): FluidIterableIterator<[K, V]>;
+    readonly [Symbol.toStringTag]: string;
+    entries(): FluidIterableIterator<[K, V]>;
+    forEach(callbackfn: (value: V, key: K, map: FluidReadonlyMap<K, V>) => void, thisArg?: any): void;
+    get(key: K): V | undefined;
+    has(key: K): boolean;
+    keys(): FluidIterableIterator<K>;
+    readonly size: number;
+    values(): FluidIterableIterator<V>;
+}
+
 // @public
 export interface IConfigProviderBase {
     getRawConfig(name: string): ConfigTypes;
@@ -435,15 +471,20 @@ export type Listeners<T extends object> = {
 };
 
 // @public
-export const LogLevel: {
-    readonly verbose: 10;
-    readonly default: 20;
-    readonly error: 30;
-};
+export const LogLevel: LogLevelConst;
 
 // @public
 export type LogLevel = (typeof LogLevel)[keyof typeof LogLevel];
 
+// @public
+export interface LogLevelConst {
+    readonly default: 20;
+    readonly error: 30;
+    readonly essential: 30;
+    readonly info: 20;
+    readonly verbose: 10;
+}
+
 // @public
 export type Off = () => void;
 

package/api-report/core-interfaces.legacy.beta.api.md

@@ -4,7 +4,7 @@
 
 ```ts
 
-// @beta
+// @public
 export class BrandedType<out Brand> {
     static [Symbol.hasInstance](value: never): value is never;
     protected constructor();
@@ -45,6 +45,29 @@ export type FluidErrorTypes = (typeof FluidErrorTypes)[keyof typeof FluidErrorTy
 // @public
 export const fluidHandleSymbol: unique symbol;
 
+// @beta @sealed
+export interface FluidIterable<T> {
+    [Symbol.iterator](): FluidIterableIterator<T>;
+}
+
+// @beta @sealed
+export interface FluidIterableIterator<T> extends FluidIterable<T> {
+    next(): {
+        value: T;
+        done?: false;
+    } | {
+        value: any;
+        done: true;
+    };
+}
+
+// @beta @sealed
+export interface FluidMap<K, V> extends FluidReadonlyMap<K, V> {
+    delete(key: K): void;
+    forEach(callbackfn: (value: V, key: K, map: FluidMap<K, V>) => void, thisArg?: any): void;
+    set(key: K, value: V): void;
+}
+
 // @public
 export type FluidObject<T = unknown> = {
     [P in FluidObjectProviderKeys<T>]?: T[P];
@@ -56,6 +79,19 @@ export type FluidObjectKeys<T> = keyof FluidObject<T>;
 // @public
 export type FluidObjectProviderKeys<T, TProp extends keyof T = keyof T> = string extends TProp ? never : number extends TProp ? never : TProp extends keyof Required<T>[TProp] ? Required<T>[TProp] extends Required<Required<T>[TProp]>[TProp] ? TProp : never : never;
 
+// @beta @sealed
+export interface FluidReadonlyMap<K, V> {
+    [Symbol.iterator](): FluidIterableIterator<[K, V]>;
+    readonly [Symbol.toStringTag]: string;
+    entries(): FluidIterableIterator<[K, V]>;
+    forEach(callbackfn: (value: V, key: K, map: FluidReadonlyMap<K, V>) => void, thisArg?: any): void;
+    get(key: K): V | undefined;
+    has(key: K): boolean;
+    keys(): FluidIterableIterator<K>;
+    readonly size: number;
+    values(): FluidIterableIterator<V>;
+}
+
 // @public
 export interface IConfigProviderBase {
     getRawConfig(name: string): ConfigTypes;
@@ -422,15 +458,20 @@ export type Listeners<T extends object> = {
 };
 
 // @public
-export const LogLevel: {
-    readonly verbose: 10;
-    readonly default: 20;
-    readonly error: 30;
-};
+export const LogLevel: LogLevelConst;
 
 // @public
 export type LogLevel = (typeof LogLevel)[keyof typeof LogLevel];
 
+// @public
+export interface LogLevelConst {
+    readonly default: 20;
+    readonly error: 30;
+    readonly essential: 30;
+    readonly info: 20;
+    readonly verbose: 10;
+}
+
 // @public
 export type Off = () => void;
 

package/api-report/core-interfaces.legacy.public.api.md

@@ -4,6 +4,13 @@
 
 ```ts
 
+// @public
+export class BrandedType<out Brand> {
+    static [Symbol.hasInstance](value: never): value is never;
+    protected constructor();
+    protected readonly brand: (dummy: never) => Brand;
+}
+
 // @public
 export type ConfigTypes = string | number | boolean | number[] | string[] | boolean[] | undefined;
 
@@ -319,15 +326,20 @@ export type Listeners<T extends object> = {
 };
 
 // @public
-export const LogLevel: {
-    readonly verbose: 10;
-    readonly default: 20;
-    readonly error: 30;
-};
+export const LogLevel: LogLevelConst;
 
 // @public
 export type LogLevel = (typeof LogLevel)[keyof typeof LogLevel];
 
+// @public
+export interface LogLevelConst {
+    readonly default: 20;
+    readonly error: 30;
+    readonly essential: 30;
+    readonly info: 20;
+    readonly verbose: 10;
+}
+
 // @public
 export type Off = () => void;
 

package/api-report/core-interfaces.public.api.md

@@ -4,6 +4,13 @@
 
 ```ts
 
+// @public
+export class BrandedType<out Brand> {
+    static [Symbol.hasInstance](value: never): value is never;
+    protected constructor();
+    protected readonly brand: (dummy: never) => Brand;
+}
+
 // @public
 export type ConfigTypes = string | number | boolean | number[] | string[] | boolean[] | undefined;
 
@@ -319,15 +326,20 @@ export type Listeners<T extends object> = {
 };
 
 // @public
-export const LogLevel: {
-    readonly verbose: 10;
-    readonly default: 20;
-    readonly error: 30;
-};
+export const LogLevel: LogLevelConst;
 
 // @public
 export type LogLevel = (typeof LogLevel)[keyof typeof LogLevel];
 
+// @public
+export interface LogLevelConst {
+    readonly default: 20;
+    readonly error: 30;
+    readonly essential: 30;
+    readonly info: 20;
+    readonly verbose: 10;
+}
+
 // @public
 export type Off = () => void;
 

package/dist/brandedType.d.ts

@@ -35,6 +35,19 @@
  *
  * This class should never exist at runtime, so it is only declared.
  *
+ * As this is a class and not just an interface, to match derived types, the
+ * declarations for any two derivatives must come from the same source - the
+ * same package version. If a type must cross package boundaries, as may be the
+ * case for cross layer types, the derived type should pick a specific version
+ * of core-interfaces to import BrandedType from. Exact versions are best, but
+ * as security best practice, use ~ specification.  Consumers are expected to
+ * use a package manager that will produce consistency over minor patches.
+ * A change in version should be considered a breaking change.
+ *
+ * In the preferred derived class pattern, the derived class is subject to the
+ * same identity rules and might benefit from being in a type-only `-definitions`
+ * package. See {@link ErasedType} example comments for version stable patterns.
+ *
  * @example
  * Definition of two branded types with different variance:
  * ```typescript
@@ -68,7 +81,7 @@
  * }
  * ```
  *
- * @beta
+ * @public
  */
 export declare class BrandedType<out Brand> {
     /**

package/dist/brandedType.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"brandedType.d.ts","sourceRoot":"","sources":["../src/brandedType.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmEG;AACH,MAAM,CAAC,OAAO,OAAO,WAAW,CAAC,GAAG,CAAC,KAAK;IACzC;;;;;;;;;OASG;IACH,SAAS,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,KAAK,CAAC;IAElD,SAAS;IAET;;;;;OAKG;WACW,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,IAAI,KAAK;CAChE"}
+{"version":3,"file":"brandedType.d.ts","sourceRoot":"","sources":["../src/brandedType.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgFG;AACH,MAAM,CAAC,OAAO,OAAO,WAAW,CAAC,GAAG,CAAC,KAAK;IACzC;;;;;;;;;OASG;IACH,SAAS,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,KAAK,CAAC;IAElD,SAAS;IAET;;;;;OAKG;WACW,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,IAAI,KAAK;CAChE"}

package/dist/brandedType.js.map

@@ -1 +1 @@
-{"version":3,"file":"brandedType.js","sourceRoot":"","sources":["../src/brandedType.ts"],"names":[],"mappings":";AAAA;;;GAGG","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\n/**\n * Base branded type which can be used to annotate other type.\n *\n * @remarks\n * `BrandedType` is covariant over its type parameter, which could be leveraged\n * for any generic type, but the preferred pattern is to specify variance\n * explicitly in a derived class making that clear and guaranteeing branding is\n * unique. It is convenient to have the derived class be the generic given to\n * `BrandedType`.\n *\n * ### Direct use [simple]\n *\n * Use `T & BrandedType<\"BrandName\">` to create a type conforming to `T` and\n * also branded with name \"BrandName\".\n *\n * ### Derived class use [preferred]\n *\n * Derive another class declaration and ideally add additional\n * protected properties to distinguish the type. (Private properties would\n * {@link https://github.com/microsoft/TypeScript/issues/20979#issuecomment-361432516|lose their type when exported}\n * and public properties would allow structural typing and show up on the branded\n * values.)\n *\n * Then use `T & MyBrandedType<U>` to create a type conforming to `T` and\n * also branded with the derived brand.\n *\n * ### Runtime\n *\n * Since branded types are not real value types, they will always need to be\n * created using `as` syntax and often `as unknown` first.\n *\n * This class should never exist at runtime, so it is only declared.\n *\n * @example\n * Definition of two branded types with different variance:\n * ```typescript\n * // A brand that is covariant over given T\n * declare class CovariantBrand<T> extends BrandedType<CovariantBrand<unknown>> {\n *    // Does not allow unrelated or less derived CovariantBrand-ed types to be\n *    // assigned. CovariantBrand<string> is not assignable to CovariantBrand<\"literal\">.\n *    protected readonly CovariantBrand: T;\n *    private constructor();\n * }\n * // A brand that is contravariant over given T\n * declare class ContravariantBrand<T> extends BrandedType<ContravariantBrand<unknown>> {\n *    // Does not allow unrelated or more derived ContravariantBrand-ed types to be\n *    // assigned. ContravariantBrand<\"literal\"> is not assignable to ContravariantBrand<string>.\n *    protected readonly ContravariantBrand: (_: T) => void;\n *    private constructor();\n * }\n * ```\n *\n * Applying a brand to a type through type-guard:\n * ```typescript\n * function numberIs5(n: number): n is number & CovariantBrand<5> {\n *    return n === 5;\n * }\n * function onlyAccept4_5_or_6(_n: number & CovariantBrand<4 | 5 | 6>): void {}\n *\n * function example(n: number) {\n *    if (numberIs5(n)) {\n *       onlyAccept4_5_or_6(n); // OK: CovariantBrand<5> is assignable to CovariantBrand<4 | 5 | 6>;\n *   }\n * }\n * ```\n *\n * @beta\n */\nexport declare class BrandedType<out Brand> {\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 *\n\t * @privateRemarks\n\t * `Brand` is used as the return type of a method rather than a simple\n\t * readonly property as this allows types with two brands to be\n\t * intersected without getting `never`.\n\t * The method takes in `never` to help emphasize that it's not callable.\n\t */\n\tprotected readonly brand: (dummy: never) => Brand;\n\n\tprotected constructor();\n\n\t/**\n\t * Since this class is a compile time only type brand, `instanceof` will\n\t * never work with it. * This `Symbol.hasInstance` implementation ensures\n\t * that `instanceof` will error if used, and in TypeScript 5.3 and newer\n\t * will produce a compile time error if used.\n\t */\n\tpublic static [Symbol.hasInstance](value: never): value is never;\n}\n"]}
+{"version":3,"file":"brandedType.js","sourceRoot":"","sources":["../src/brandedType.ts"],"names":[],"mappings":";AAAA;;;GAGG","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\n/**\n * Base branded type which can be used to annotate other type.\n *\n * @remarks\n * `BrandedType` is covariant over its type parameter, which could be leveraged\n * for any generic type, but the preferred pattern is to specify variance\n * explicitly in a derived class making that clear and guaranteeing branding is\n * unique. It is convenient to have the derived class be the generic given to\n * `BrandedType`.\n *\n * ### Direct use [simple]\n *\n * Use `T & BrandedType<\"BrandName\">` to create a type conforming to `T` and\n * also branded with name \"BrandName\".\n *\n * ### Derived class use [preferred]\n *\n * Derive another class declaration and ideally add additional\n * protected properties to distinguish the type. (Private properties would\n * {@link https://github.com/microsoft/TypeScript/issues/20979#issuecomment-361432516|lose their type when exported}\n * and public properties would allow structural typing and show up on the branded\n * values.)\n *\n * Then use `T & MyBrandedType<U>` to create a type conforming to `T` and\n * also branded with the derived brand.\n *\n * ### Runtime\n *\n * Since branded types are not real value types, they will always need to be\n * created using `as` syntax and often `as unknown` first.\n *\n * This class should never exist at runtime, so it is only declared.\n *\n * As this is a class and not just an interface, to match derived types, the\n * declarations for any two derivatives must come from the same source - the\n * same package version. If a type must cross package boundaries, as may be the\n * case for cross layer types, the derived type should pick a specific version\n * of core-interfaces to import BrandedType from. Exact versions are best, but\n * as security best practice, use ~ specification.  Consumers are expected to\n * use a package manager that will produce consistency over minor patches.\n * A change in version should be considered a breaking change.\n *\n * In the preferred derived class pattern, the derived class is subject to the\n * same identity rules and might benefit from being in a type-only `-definitions`\n * package. See {@link ErasedType} example comments for version stable patterns.\n *\n * @example\n * Definition of two branded types with different variance:\n * ```typescript\n * // A brand that is covariant over given T\n * declare class CovariantBrand<T> extends BrandedType<CovariantBrand<unknown>> {\n *    // Does not allow unrelated or less derived CovariantBrand-ed types to be\n *    // assigned. CovariantBrand<string> is not assignable to CovariantBrand<\"literal\">.\n *    protected readonly CovariantBrand: T;\n *    private constructor();\n * }\n * // A brand that is contravariant over given T\n * declare class ContravariantBrand<T> extends BrandedType<ContravariantBrand<unknown>> {\n *    // Does not allow unrelated or more derived ContravariantBrand-ed types to be\n *    // assigned. ContravariantBrand<\"literal\"> is not assignable to ContravariantBrand<string>.\n *    protected readonly ContravariantBrand: (_: T) => void;\n *    private constructor();\n * }\n * ```\n *\n * Applying a brand to a type through type-guard:\n * ```typescript\n * function numberIs5(n: number): n is number & CovariantBrand<5> {\n *    return n === 5;\n * }\n * function onlyAccept4_5_or_6(_n: number & CovariantBrand<4 | 5 | 6>): void {}\n *\n * function example(n: number) {\n *    if (numberIs5(n)) {\n *       onlyAccept4_5_or_6(n); // OK: CovariantBrand<5> is assignable to CovariantBrand<4 | 5 | 6>;\n *   }\n * }\n * ```\n *\n * @public\n */\nexport declare class BrandedType<out Brand> {\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 *\n\t * @privateRemarks\n\t * `Brand` is used as the return type of a method rather than a simple\n\t * readonly property as this allows types with two brands to be\n\t * intersected without getting `never`.\n\t * The method takes in `never` to help emphasize that it's not callable.\n\t */\n\tprotected readonly brand: (dummy: never) => Brand;\n\n\tprotected constructor();\n\n\t/**\n\t * Since this class is a compile time only type brand, `instanceof` will\n\t * never work with it. * This `Symbol.hasInstance` implementation ensures\n\t * that `instanceof` will error if used, and in TypeScript 5.3 and newer\n\t * will produce a compile time error if used.\n\t */\n\tpublic static [Symbol.hasInstance](value: never): value is never;\n}\n"]}

package/dist/deepReadonly.d.ts

@@ -10,14 +10,14 @@ import type { DeepReadonlyRecursionLimit, InternalUtilityTypes, ReadonlySupporte
  * @privateRemarks
  * WeakRef should be added when lib is updated to ES2021 or later.
  *
- * @beta
+ * @public
  * @system
  */
 export type DeepReadonlySupportedGenericsDefault = Map<unknown, unknown> | Promise<unknown> | Set<unknown> | WeakMap<object, unknown> | WeakSet<object>;
 /**
  * Options for {@link DeepReadonly}.
  *
- * @beta
+ * @public
  */
 export interface DeepReadonlyOptions {
     /**
@@ -44,7 +44,7 @@ export interface DeepReadonlyOptions {
  * {@link DeepReadonlySupportedGenericsDefault} for generics that have
  * immutability applied to generic type by default.
  *
- * @beta
+ * @public
  */
 export type DeepReadonly<T, Options extends DeepReadonlyOptions = {
     DeepenedGenerics: DeepReadonlySupportedGenericsDefault;

package/dist/deepReadonly.js.map

@@ -1 +1 @@
-{"version":3,"file":"deepReadonly.js","sourceRoot":"","sources":["../src/deepReadonly.ts"],"names":[],"mappings":";AAAA;;;GAGG","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport type {\n\tDeepReadonlyRecursionLimit,\n\tInternalUtilityTypes,\n\tReadonlySupportedGenerics,\n} from \"./exposedInternalUtilityTypes.js\";\n\n/**\n * Default set of generic that {@link DeepReadonly} will apply deep immutability\n * to generic types.\n *\n * @privateRemarks\n * WeakRef should be added when lib is updated to ES2021 or later.\n *\n * @beta\n * @system\n */\nexport type DeepReadonlySupportedGenericsDefault =\n\t| Map<unknown, unknown>\n\t| Promise<unknown>\n\t| Set<unknown>\n\t| WeakMap<object, unknown>\n\t| WeakSet<object>;\n\n/**\n * Options for {@link DeepReadonly}.\n *\n * @beta\n */\nexport interface DeepReadonlyOptions {\n\t/**\n\t * Union of Built-in and IFluidHandle whose generics will also be made deeply immutable.\n\t *\n\t * The default value is `Map` | `Promise` | `Set` | `WeakMap` | `WeakSet`.\n\t */\n\tDeepenedGenerics?: ReadonlySupportedGenerics;\n\n\t/**\n\t * Limit on processing recursive types.\n\t *\n\t * The default value is `\"NoLimit\"`.\n\t */\n\tRecurseLimit?: DeepReadonlyRecursionLimit;\n}\n\n/**\n * Transforms type to a fully and deeply immutable type, with limitations.\n *\n * @remarks\n * This utility type is similar to a recursive `Readonly<T>`, but also\n * applies immutability to common generic types like `Map` and `Set`.\n *\n * Optionally, immutability can be applied to supported generics types. See\n * {@link DeepReadonlySupportedGenericsDefault} for generics that have\n * immutability applied to generic type by default.\n *\n * @beta\n */\nexport type DeepReadonly<\n\tT,\n\tOptions extends DeepReadonlyOptions = {\n\t\tDeepenedGenerics: DeepReadonlySupportedGenericsDefault;\n\t\tRecurseLimit: \"NoLimit\";\n\t},\n> = InternalUtilityTypes.DeepReadonlyImpl<\n\tT,\n\tOptions extends { DeepenedGenerics: unknown }\n\t\t? Options[\"DeepenedGenerics\"]\n\t\t: DeepReadonlySupportedGenericsDefault,\n\tOptions extends { RecurseLimit: DeepReadonlyRecursionLimit }\n\t\t? Options[\"RecurseLimit\"]\n\t\t: \"NoLimit\"\n>;\n"]}
+{"version":3,"file":"deepReadonly.js","sourceRoot":"","sources":["../src/deepReadonly.ts"],"names":[],"mappings":";AAAA;;;GAGG","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport type {\n\tDeepReadonlyRecursionLimit,\n\tInternalUtilityTypes,\n\tReadonlySupportedGenerics,\n} from \"./exposedInternalUtilityTypes.js\";\n\n/**\n * Default set of generic that {@link DeepReadonly} will apply deep immutability\n * to generic types.\n *\n * @privateRemarks\n * WeakRef should be added when lib is updated to ES2021 or later.\n *\n * @public\n * @system\n */\nexport type DeepReadonlySupportedGenericsDefault =\n\t| Map<unknown, unknown>\n\t| Promise<unknown>\n\t| Set<unknown>\n\t| WeakMap<object, unknown>\n\t| WeakSet<object>;\n\n/**\n * Options for {@link DeepReadonly}.\n *\n * @public\n */\nexport interface DeepReadonlyOptions {\n\t/**\n\t * Union of Built-in and IFluidHandle whose generics will also be made deeply immutable.\n\t *\n\t * The default value is `Map` | `Promise` | `Set` | `WeakMap` | `WeakSet`.\n\t */\n\tDeepenedGenerics?: ReadonlySupportedGenerics;\n\n\t/**\n\t * Limit on processing recursive types.\n\t *\n\t * The default value is `\"NoLimit\"`.\n\t */\n\tRecurseLimit?: DeepReadonlyRecursionLimit;\n}\n\n/**\n * Transforms type to a fully and deeply immutable type, with limitations.\n *\n * @remarks\n * This utility type is similar to a recursive `Readonly<T>`, but also\n * applies immutability to common generic types like `Map` and `Set`.\n *\n * Optionally, immutability can be applied to supported generics types. See\n * {@link DeepReadonlySupportedGenericsDefault} for generics that have\n * immutability applied to generic type by default.\n *\n * @public\n */\nexport type DeepReadonly<\n\tT,\n\tOptions extends DeepReadonlyOptions = {\n\t\tDeepenedGenerics: DeepReadonlySupportedGenericsDefault;\n\t\tRecurseLimit: \"NoLimit\";\n\t},\n> = InternalUtilityTypes.DeepReadonlyImpl<\n\tT,\n\tOptions extends { DeepenedGenerics: unknown }\n\t\t? Options[\"DeepenedGenerics\"]\n\t\t: DeepReadonlySupportedGenericsDefault,\n\tOptions extends { RecurseLimit: DeepReadonlyRecursionLimit }\n\t\t? Options[\"RecurseLimit\"]\n\t\t: \"NoLimit\"\n>;\n"]}

package/dist/erasedType.d.ts

@@ -12,13 +12,30 @@
  * allowing code outside of a package to have a reference/handle to something in the package in a type safe way without the package having to publicly export the types of the object.
  * This should not be confused with the more specific IFluidHandle which is also named after this design pattern.
  *
+ * As this is a class and not just an interface, to match derived types, the
+ * declarations for any two derivatives must come from the same source - the
+ * same package version. If a type must cross package boundaries, as may be the
+ * case for cross layer types, the derived type should pick a specific version
+ * of core-interfaces to import ErasedType from. Exact versions are best, but
+ * as security best practice, use ~ specification. Consumers are expected to
+ * use a package manager that will produce consistency over minor patches.
+ * A change in version should be considered a breaking change.
+ *
  * 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.
  *
  * @example
+ * package.json:
+ * ```json
+ *   "dependencies": {
+ *     "@fluidframework/erased-type-v1": "npm:@fluidframework/core-interfaces@~2.0.0"
+ *   }
+ * ```
+ * source.ts:
  * ```typescript
+ * import { ErasedType as ErasedTypeV1 } from "@fluidframework/erased-type-v1";
  * // public sealed type
- * export interface ErasedMyType extends ErasedType<"myPackage.MyType"> {}
+ * export interface ErasedMyType extends ErasedTypeV1<"myPackage.MyType"> {}
  * // internal type
  * export interface MyType {
  * 	example: number;
@@ -34,6 +51,7 @@
  *
  * 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.
+ *
  * @privateRemarks
  * For this pattern to work well it needs to be difficult for a user of the erased type to
  * implicitly use something other than a instance received from the package as an instance of the erased type in type safe code.
@@ -71,22 +89,29 @@ export declare abstract class ErasedType<out Name = unknown> {
     private constructor();
     /**
      * Since this class is a compile time only type brand, `instanceof` will never work with it.
-     * This `Symbol.hasInstance` implementation ensures that `instanceof` will error if used,
-     * and in TypeScript 5.3 and newer will produce a compile time error if used.
+     * This `Symbol.hasInstance` declaration (no definition) ensures that `instanceof` will
+     * produce `ReferenceError` if used at runtime. And in TypeScript 5.3 and newer will produce
+     * a compile time error if used.
      */
     static [Symbol.hasInstance](value: never): value is never;
 }
 /**
  * Used to mark a `@sealed` interface in a strongly typed way to prevent external implementations.
+ *
  * @remarks
  * This is an alternative to {@link ErasedType} which is more ergonomic to implement in the case where the implementation can extend `ErasedTypeImplementation`.
  *
  * Users of interfaces extending this should never refer to anything about this class:
  * migrating the type branding to another mechanism, like {@link ErasedType} should be considered a non-breaking change.
+ *
+ * @see {@link ErasedType} for version compatibility notes.
+ *
  * @privateRemarks
  * Implement interfaces which extend this by sub-classing {@link ErasedTypeImplementation}.
  *
  * This class should only be a `type` package export, preventing users from extending it directly.
+ * But since {@link ErasedTypeImplementation} does extend it, an implementation
+ * of the constructor must be provided, unlike {@link ErasedType}.
  *
  * Since {@link ErasedTypeImplementation} is exported as `@internal`, this restricts implementations of the sealed interfaces to users of `@internal` APIs, which should be anything within this release group.
  * Any finer grained restrictions can be done as documentation, but not type enforced.

package/dist/erasedType.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"erasedType.d.ts","sourceRoot":"","sources":["../src/erasedType.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,8BAAsB,UAAU,CAAC,GAAG,CAAC,IAAI,GAAG,OAAO;IAClD;;;;;;OAMG;IACH,SAAS,CAAC,QAAQ,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI;IAE5C;;OAEG;IACH,OAAO;IAEP;;;;OAIG;WACW,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,IAAI,KAAK;CAKhE;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,8BAAsB,cAAc,CAAC,GAAG,CAAC,IAAI,GAAG,OAAO;IACtD;;;;;;OAMG;IACH,SAAS,CAAC,QAAQ,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI;IAE5C;;;;;;OAMG;IACH,SAAS;CACT;AAED;;;;;;;;;GASG;AACH,8BAAsB,wBAAwB,CAC7C,UAAU,SAAS,cAAc,CAChC,SAAQ,cAAc,CAAC,UAAU,SAAS,cAAc,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,GAAG,KAAK,CAAC;IACrF,SAAS,CAAC,QAAQ,CAAC,KAAK,EAAG,CAC1B,KAAK,EAAE,KAAK,KACR,UAAU,SAAS,cAAc,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,GAAG,KAAK,CAAC;IAElE,SAAS;IAIT;;OAEG;WACW,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,KAAK,SAAS;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,EACrE,IAAI,EAAE,KAAK,EACX,KAAK,EAAE,OAAO,GACZ,KAAK,IAAI,mBAAmB,CAAC,KAAK,CAAC;IAQtC;;;;;;;;;OASG;WACW,MAAM,CAAC,KAAK,SAAS;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,EACvD,IAAI,EAAE,KAAK,EACX,KAAK,EAAE,cAAc,GAAG,mBAAmB,CAAC,KAAK,CAAC,GAChD,OAAO,CAAC,KAAK,IAAI,mBAAmB,CAAC,KAAK,CAAC;IAM9C;;;;OAIG;IACI,MAAM,CAAC,KAAK,SAAS,UAAU,EAAE,IAAI,EAAE,KAAK,GAAG,UAAU;CAGhE;AAED;;;;;GAKG;AACH,MAAM,MAAM,mBAAmB,CAAC,MAAM,IAAI,YAAY,CAAC,CAAC,UAAU,KAAK,CAAC,GAAG,MAAM,CAAC,CAAC"}
+{"version":3,"file":"erasedType.d.ts","sourceRoot":"","sources":["../src/erasedType.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuEG;AACH,MAAM,CAAC,OAAO,CAAC,QAAQ,OAAO,UAAU,CAAC,GAAG,CAAC,IAAI,GAAG,OAAO;IAC1D;;;;;;OAMG;IACH,SAAS,CAAC,QAAQ,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI;IAE5C;;OAEG;IACH,OAAO;IAEP;;;;;OAKG;WACW,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,IAAI,KAAK;CAChE;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,8BAAsB,cAAc,CAAC,GAAG,CAAC,IAAI,GAAG,OAAO;IACtD;;;;;;OAMG;IACH,SAAS,CAAC,QAAQ,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI;IAE5C;;;;;;OAMG;IACH,SAAS;CACT;AAED;;;;;;;;;GASG;AACH,8BAAsB,wBAAwB,CAC7C,UAAU,SAAS,cAAc,CAChC,SAAQ,cAAc,CAAC,UAAU,SAAS,cAAc,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,GAAG,KAAK,CAAC;IACrF,SAAS,CAAC,QAAQ,CAAC,KAAK,EAAG,CAC1B,KAAK,EAAE,KAAK,KACR,UAAU,SAAS,cAAc,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,GAAG,KAAK,CAAC;IAElE,SAAS;IAIT;;OAEG;WACW,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,KAAK,SAAS;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,EACrE,IAAI,EAAE,KAAK,EACX,KAAK,EAAE,OAAO,GACZ,KAAK,IAAI,mBAAmB,CAAC,KAAK,CAAC;IAQtC;;;;;;;;;OASG;WACW,MAAM,CAAC,KAAK,SAAS;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,EACvD,IAAI,EAAE,KAAK,EACX,KAAK,EAAE,cAAc,GAAG,mBAAmB,CAAC,KAAK,CAAC,GAChD,OAAO,CAAC,KAAK,IAAI,mBAAmB,CAAC,KAAK,CAAC;IAM9C;;;;OAIG;IACI,MAAM,CAAC,KAAK,SAAS,UAAU,EAAE,IAAI,EAAE,KAAK,GAAG,UAAU;CAGhE;AAED;;;;;GAKG;AACH,MAAM,MAAM,mBAAmB,CAAC,MAAM,IAAI,YAAY,CAAC,CAAC,UAAU,KAAK,CAAC,GAAG,MAAM,CAAC,CAAC"}

package/dist/erasedType.js

@@ -4,87 +4,24 @@
  * Licensed under the MIT License.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ErasedTypeImplementation = exports.ErasedBaseType = exports.ErasedType = void 0;
-/**
- * Erased type which can be used to expose a opaque/erased version of a type without referencing the actual type.
- * @remarks
- * This similar to the {@link https://en.wikipedia.org/wiki/Type_erasure | type erasure} pattern,
- * but for erasing types at the package boundary.
- *
- * This can be used to implement the TypeScript typing for the {@link https://en.wikipedia.org/wiki/Handle_(computing) | handle} pattern,
- * allowing code outside of a package to have a reference/handle to something in the package in a type safe way without the package having to publicly export the types of the object.
- * This should not be confused with the more specific IFluidHandle which is also named after this design pattern.
- *
- * 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.
- *
- * @example
- * ```typescript
- * // public sealed type
- * export interface ErasedMyType extends ErasedType<"myPackage.MyType"> {}
- * // internal type
- * export interface MyType {
- * 	example: number;
- * }
- * // Usage
- * function extract(input: ErasedMyType): MyType {
- * 	return input as unknown as MyType;
- * }
- * function erase(input: MyType): ErasedMyType {
- * 	return input as unknown as ErasedMyType;
- * }
- * ```
- *
- * 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.
- * @privateRemarks
- * For this pattern to work well it needs to be difficult for a user of the erased type to
- * implicitly use something other than a instance received from the package as an instance of the erased type in type safe code.
- *
- * This means that this type must not be able to be implicitly converted to from any strong type (not `any` or `never`),
- * and no amount of auto complete or auto-implement refactoring will produce something that can be used as an erased type.
- * This is accomplished by:
- *
- * 1. requiring that values of this type be an instance of this class.
- * Typescript does not enforce this requirement for class: only for classes with protected or private members, so such member is included.
- *
- * 2. making this class impossible to get an instance of.
- * This is done by having a private constructor.
- *
- * 3. ensuring different erased types also using this library can not be implicitly converted between each-other.
- * This is done by using the "Name" type parameter.
- * Note that just having the type parameter is not enough since the presence of type parameters has no impact on implicit conversion in TypeScript:
- * only the usages of the type parameter matter.
- *
- * @sealed
- * @public
- */
-class ErasedType {
-    /**
-     * This class should never exist at runtime, so make it un-constructable.
-     */
-    constructor() { }
-    /**
-     * Since this class is a compile time only type brand, `instanceof` will never work with it.
-     * This `Symbol.hasInstance` implementation ensures that `instanceof` will error if used,
-     * and in TypeScript 5.3 and newer will produce a compile time error if used.
-     */
-    static [Symbol.hasInstance](value) {
-        throw new Error("ErasedType is a compile time type brand not a real class that can be used with `instanceof` at runtime.");
-    }
-}
-exports.ErasedType = ErasedType;
+exports.ErasedTypeImplementation = exports.ErasedBaseType = void 0;
 /**
  * Used to mark a `@sealed` interface in a strongly typed way to prevent external implementations.
+ *
  * @remarks
  * This is an alternative to {@link ErasedType} which is more ergonomic to implement in the case where the implementation can extend `ErasedTypeImplementation`.
  *
  * Users of interfaces extending this should never refer to anything about this class:
  * migrating the type branding to another mechanism, like {@link ErasedType} should be considered a non-breaking change.
+ *
+ * @see {@link ErasedType} for version compatibility notes.
+ *
  * @privateRemarks
  * Implement interfaces which extend this by sub-classing {@link ErasedTypeImplementation}.
  *
  * This class should only be a `type` package export, preventing users from extending it directly.
+ * But since {@link ErasedTypeImplementation} does extend it, an implementation
+ * of the constructor must be provided, unlike {@link ErasedType}.
  *
  * Since {@link ErasedTypeImplementation} is exported as `@internal`, this restricts implementations of the sealed interfaces to users of `@internal` APIs, which should be anything within this release group.
  * Any finer grained restrictions can be done as documentation, but not type enforced.