@fluidframework/core-interfaces 2.92.0 → 2.100.0

package/dist/public.d.ts

@@ -10,6 +10,7 @@
 
 export {
 	// #region @public APIs
+	BrandedType, 
 	ConfigTypes, 
 	ErasedType, 
 	ExtendEventProvider, 
@@ -38,6 +39,7 @@ export {
 	Listenable, 
 	Listeners, 
 	LogLevel, 
+	LogLevelConst, 
 	Off, 
 	ReplaceIEventThisPlaceHolder, 
 	Tagged, 

package/eslint.config.mts

@@ -4,7 +4,7 @@
  */
 
 import type { Linter } from "eslint";
-import { strict } from "../../../common/build/eslint-config-fluid/flat.mts";
+import { strict } from "@fluidframework/eslint-config-fluid/flat.mts";
 
 const config: Linter.Config[] = [
 	...strict,

package/lib/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/lib/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/lib/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/lib/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/lib/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/lib/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/lib/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/lib/erasedType.js

@@ -2,85 +2,23 @@
  * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
  * Licensed under the MIT License.
  */
-/**
- * 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
- */
-export 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.");
-    }
-}
 /**
  * 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/lib/erasedType.js.map

@@ -1 +1 @@
-{"version":3,"file":"erasedType.js","sourceRoot":"","sources":["../src/erasedType.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,MAAM,OAAgB,UAAU;IAU/B;;OAEG;IACH,gBAAuB,CAAC;IAExB;;;;OAIG;IACI,MAAM,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,KAAY;QAC9C,MAAM,IAAI,KAAK,CACd,yGAAyG,CACzG,CAAC;IACH,CAAC;CACD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,OAAgB,cAAc;IAUnC;;;;;;OAMG;IACH,gBAAyB,CAAC;CAC1B;AAED;;;;;;;;;GASG;AACH,MAAM,OAAgB,wBAEpB,SAAQ,cAA4E;IAKrF;QACC,KAAK,EAAE,CAAC;IACT,CAAC;IAED;;OAEG;IACI,MAAM,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,CAEjC,KAAc;QAEd,OAAO,CACN,OAAO,KAAK,KAAK,QAAQ;YACzB,KAAK,KAAK,IAAI;YACd,MAAM,CAAC,SAAS,CAAC,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,KAAK,CAAC,CAC1D,CAAC;IACH,CAAC;IAED;;;;;;;;;OASG;IACI,MAAM,CAAC,MAAM,CAEnB,KAAkD;QAElD,IAAI,CAAC,wBAAwB,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,KAAe,CAAC,EAAE,CAAC;YAC/E,MAAM,IAAI,SAAS,CAAC,iCAAiC,CAAC,CAAC;QACxD,CAAC;IACF,CAAC;IAED;;;;OAIG;IACI,MAAM;QACZ,OAAO,IAAI,CAAC;IACb,CAAC;CACD","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\n/**\n * Erased type which can be used to expose a opaque/erased version of a type without referencing the actual type.\n * @remarks\n * This similar to the {@link https://en.wikipedia.org/wiki/Type_erasure | type erasure} pattern,\n * but for erasing types at the package boundary.\n *\n * This can be used to implement the TypeScript typing for the {@link https://en.wikipedia.org/wiki/Handle_(computing) | handle} pattern,\n * 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.\n * This should not be confused with the more specific IFluidHandle which is also named after this design pattern.\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 *\n * @example\n * ```typescript\n * // public sealed type\n * export interface ErasedMyType extends ErasedType<\"myPackage.MyType\"> {}\n * // internal type\n * export interface MyType {\n * \texample: number;\n * }\n * // Usage\n * function extract(input: ErasedMyType): MyType {\n * \treturn input as unknown as MyType;\n * }\n * function erase(input: MyType): ErasedMyType {\n * \treturn input as unknown as ErasedMyType;\n * }\n * ```\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 * @privateRemarks\n * For this pattern to work well it needs to be difficult for a user of the erased type to\n * implicitly use something other than a instance received from the package as an instance of the erased type in type safe code.\n *\n * This means that this type must not be able to be implicitly converted to from any strong type (not `any` or `never`),\n * and no amount of auto complete or auto-implement refactoring will produce something that can be used as an erased type.\n * This is accomplished by:\n *\n * 1. requiring that values of this type be an instance of this class.\n * Typescript does not enforce this requirement for class: only for classes with protected or private members, so such member is included.\n *\n * 2. making this class impossible to get an instance of.\n * This is done by having a private constructor.\n *\n * 3. ensuring different erased types also using this library can not be implicitly converted between each-other.\n * This is done by using the \"Name\" type parameter.\n * Note that just having the type parameter is not enough since the presence of type parameters has no impact on implicit conversion in TypeScript:\n * only the usages of the type parameter matter.\n *\n * @sealed\n * @public\n */\nexport abstract class ErasedType<out Name = unknown> {\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 * @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\t/**\n\t * Since this class is a compile time only type brand, `instanceof` will never work with it.\n\t * This `Symbol.hasInstance` implementation ensures that `instanceof` will error if used,\n\t * and in TypeScript 5.3 and newer will produce a compile time error if used.\n\t */\n\tpublic static [Symbol.hasInstance](value: never): value is never {\n\t\tthrow new Error(\n\t\t\t\"ErasedType is a compile time type brand not a real class that can be used with `instanceof` at runtime.\",\n\t\t);\n\t}\n}\n\n/**\n * Used to mark a `@sealed` interface in a strongly typed way to prevent external implementations.\n * @remarks\n * This is an alternative to {@link ErasedType} which is more ergonomic to implement in the case where the implementation can extend `ErasedTypeImplementation`.\n *\n * Users of interfaces extending this should never refer to anything about this class:\n * migrating the type branding to another mechanism, like {@link ErasedType} should be considered a non-breaking change.\n * @privateRemarks\n * Implement interfaces which extend this by sub-classing {@link ErasedTypeImplementation}.\n *\n * This class should only be a `type` package export, preventing users from extending it directly.\n *\n * 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.\n * Any finer grained restrictions can be done as documentation, but not type enforced.\n * @sealed\n * @beta\n * @system\n */\nexport abstract class ErasedBaseType<out Name = unknown> {\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 * @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 * @privateRemarks\n\t * From an API perspective, private would be preferred here.\n\t * However protected is almost as good since this class is not package exported,\n\t * and it allows ErasedTypeImplementation to extend this class.\n\t */\n\tprotected constructor() {}\n}\n\n/**\n * An implementation of an {@link ErasedBaseType}.\n * For a given erased type interface, there should be exactly one implementation of it, and it must be defined by the same code which defined the interface.\n *\n * @typeParam TInterface - The erased type interface this class implements.\n * @remarks\n * {@link ErasedBaseType} is package exported only as a type, not a value, so the only way to subclass it is via this class.\n * This limitation help enforce the pattern that there is only one implementation of a given erased type interface.\n * @internal\n */\nexport abstract class ErasedTypeImplementation<\n\tTInterface extends ErasedBaseType,\n> extends ErasedBaseType<TInterface extends ErasedBaseType<infer Name> ? Name : never> {\n\tprotected readonly brand!: (\n\t\tdummy: never,\n\t) => TInterface extends ErasedBaseType<infer Name> ? Name : never;\n\n\tprotected constructor() {\n\t\tsuper();\n\t}\n\n\t/**\n\t * {@link https://www.typescriptlang.org/docs/handbook/2/narrowing.html#using-type-predicates|Type predicate} for narrowing the internal implementation type via `instanceof`.\n\t */\n\tpublic static [Symbol.hasInstance]<TThis extends { prototype: object }>(\n\t\tthis: TThis,\n\t\tvalue: unknown,\n\t): value is InstanceTypeRelaxed<TThis> {\n\t\treturn (\n\t\t\ttypeof value === \"object\" &&\n\t\t\tvalue !== null &&\n\t\t\tObject.prototype.isPrototypeOf.call(this.prototype, value)\n\t\t);\n\t}\n\n\t/**\n\t * {@link https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html#assertion-functions|Type assertion} which narrows from ErasedBaseType to the internal implementation type.\n\t * @remarks\n\t * This does a checked conversion, throwing a `TypeError` if invalid.\n\t *\n\t * It would be safer if this narrowed from `TInterface`, but that is not possible since type parameters can not be accessed in static methods.\n\t * Replacing `ErasedTypeImplementation` with a generic function which returns a non-generic class could be used to work around this limitation if desired.\n\t *\n\t * Derived classes can provide their own customized narrowing function with a more specific types if desired.\n\t */\n\tpublic static narrow<TThis extends { prototype: object }>(\n\t\tthis: TThis,\n\t\tvalue: ErasedBaseType | InstanceTypeRelaxed<TThis>,\n\t): asserts value is InstanceTypeRelaxed<TThis> {\n\t\tif (!ErasedTypeImplementation[Symbol.hasInstance].call(this, value as object)) {\n\t\t\tthrow new TypeError(\"Invalid ErasedBaseType instance\");\n\t\t}\n\t}\n\n\t/**\n\t * Upcasts the instance to the erased interface type.\n\t * @remarks\n\t * This is mainly useful when inferring the interface type is required.\n\t */\n\tpublic upCast<TThis extends TInterface>(this: TThis): TInterface {\n\t\treturn this;\n\t}\n}\n\n/**\n * The same as the built-in InstanceType, but works on classes with private constructors.\n * @privateRemarks\n * This is based on the trick in {@link https://stackoverflow.com/a/74657881}.\n * @internal\n */\nexport type InstanceTypeRelaxed<TClass> = InstanceType<(new () => never) & TClass>;\n"]}
+{"version":3,"file":"erasedType.js","sourceRoot":"","sources":["../src/erasedType.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAkGH;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,OAAgB,cAAc;IAUnC;;;;;;OAMG;IACH,gBAAyB,CAAC;CAC1B;AAED;;;;;;;;;GASG;AACH,MAAM,OAAgB,wBAEpB,SAAQ,cAA4E;IAKrF;QACC,KAAK,EAAE,CAAC;IACT,CAAC;IAED;;OAEG;IACI,MAAM,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,CAEjC,KAAc;QAEd,OAAO,CACN,OAAO,KAAK,KAAK,QAAQ;YACzB,KAAK,KAAK,IAAI;YACd,MAAM,CAAC,SAAS,CAAC,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,KAAK,CAAC,CAC1D,CAAC;IACH,CAAC;IAED;;;;;;;;;OASG;IACI,MAAM,CAAC,MAAM,CAEnB,KAAkD;QAElD,IAAI,CAAC,wBAAwB,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,KAAe,CAAC,EAAE,CAAC;YAC/E,MAAM,IAAI,SAAS,CAAC,iCAAiC,CAAC,CAAC;QACxD,CAAC;IACF,CAAC;IAED;;;;OAIG;IACI,MAAM;QACZ,OAAO,IAAI,CAAC;IACb,CAAC;CACD","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\n/**\n * Erased type which can be used to expose a opaque/erased version of a type without referencing the actual type.\n * @remarks\n * This similar to the {@link https://en.wikipedia.org/wiki/Type_erasure | type erasure} pattern,\n * but for erasing types at the package boundary.\n *\n * This can be used to implement the TypeScript typing for the {@link https://en.wikipedia.org/wiki/Handle_(computing) | handle} pattern,\n * 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.\n * This should not be confused with the more specific IFluidHandle which is also named after this design pattern.\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 ErasedType 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 * 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 *\n * @example\n * package.json:\n * ```json\n *   \"dependencies\": {\n *     \"@fluidframework/erased-type-v1\": \"npm:@fluidframework/core-interfaces@~2.0.0\"\n *   }\n * ```\n * source.ts:\n * ```typescript\n * import { ErasedType as ErasedTypeV1 } from \"@fluidframework/erased-type-v1\";\n * // public sealed type\n * export interface ErasedMyType extends ErasedTypeV1<\"myPackage.MyType\"> {}\n * // internal type\n * export interface MyType {\n * \texample: number;\n * }\n * // Usage\n * function extract(input: ErasedMyType): MyType {\n * \treturn input as unknown as MyType;\n * }\n * function erase(input: MyType): ErasedMyType {\n * \treturn input as unknown as ErasedMyType;\n * }\n * ```\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 * @privateRemarks\n * For this pattern to work well it needs to be difficult for a user of the erased type to\n * implicitly use something other than a instance received from the package as an instance of the erased type in type safe code.\n *\n * This means that this type must not be able to be implicitly converted to from any strong type (not `any` or `never`),\n * and no amount of auto complete or auto-implement refactoring will produce something that can be used as an erased type.\n * This is accomplished by:\n *\n * 1. requiring that values of this type be an instance of this class.\n * Typescript does not enforce this requirement for class: only for classes with protected or private members, so such member is included.\n *\n * 2. making this class impossible to get an instance of.\n * This is done by having a private constructor.\n *\n * 3. ensuring different erased types also using this library can not be implicitly converted between each-other.\n * This is done by using the \"Name\" type parameter.\n * Note that just having the type parameter is not enough since the presence of type parameters has no impact on implicit conversion in TypeScript:\n * only the usages of the type parameter matter.\n *\n * @sealed\n * @public\n */\nexport declare abstract class ErasedType<out Name = unknown> {\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 * @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\t/**\n\t * Since this class is a compile time only type brand, `instanceof` will never work with it.\n\t * This `Symbol.hasInstance` declaration (no definition) ensures that `instanceof` will\n\t * produce `ReferenceError` if used at runtime. And in TypeScript 5.3 and newer will produce\n\t * a compile time error if used.\n\t */\n\tpublic static [Symbol.hasInstance](value: never): value is never;\n}\n\n/**\n * Used to mark a `@sealed` interface in a strongly typed way to prevent external implementations.\n *\n * @remarks\n * This is an alternative to {@link ErasedType} which is more ergonomic to implement in the case where the implementation can extend `ErasedTypeImplementation`.\n *\n * Users of interfaces extending this should never refer to anything about this class:\n * migrating the type branding to another mechanism, like {@link ErasedType} should be considered a non-breaking change.\n *\n * @see {@link ErasedType} for version compatibility notes.\n *\n * @privateRemarks\n * Implement interfaces which extend this by sub-classing {@link ErasedTypeImplementation}.\n *\n * This class should only be a `type` package export, preventing users from extending it directly.\n * But since {@link ErasedTypeImplementation} does extend it, an implementation\n * of the constructor must be provided, unlike {@link ErasedType}.\n *\n * 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.\n * Any finer grained restrictions can be done as documentation, but not type enforced.\n * @sealed\n * @beta\n * @system\n */\nexport abstract class ErasedBaseType<out Name = unknown> {\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 * @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 * @privateRemarks\n\t * From an API perspective, private would be preferred here.\n\t * However protected is almost as good since this class is not package exported,\n\t * and it allows ErasedTypeImplementation to extend this class.\n\t */\n\tprotected constructor() {}\n}\n\n/**\n * An implementation of an {@link ErasedBaseType}.\n * For a given erased type interface, there should be exactly one implementation of it, and it must be defined by the same code which defined the interface.\n *\n * @typeParam TInterface - The erased type interface this class implements.\n * @remarks\n * {@link ErasedBaseType} is package exported only as a type, not a value, so the only way to subclass it is via this class.\n * This limitation help enforce the pattern that there is only one implementation of a given erased type interface.\n * @internal\n */\nexport abstract class ErasedTypeImplementation<\n\tTInterface extends ErasedBaseType,\n> extends ErasedBaseType<TInterface extends ErasedBaseType<infer Name> ? Name : never> {\n\tprotected readonly brand!: (\n\t\tdummy: never,\n\t) => TInterface extends ErasedBaseType<infer Name> ? Name : never;\n\n\tprotected constructor() {\n\t\tsuper();\n\t}\n\n\t/**\n\t * {@link https://www.typescriptlang.org/docs/handbook/2/narrowing.html#using-type-predicates|Type predicate} for narrowing the internal implementation type via `instanceof`.\n\t */\n\tpublic static [Symbol.hasInstance]<TThis extends { prototype: object }>(\n\t\tthis: TThis,\n\t\tvalue: unknown,\n\t): value is InstanceTypeRelaxed<TThis> {\n\t\treturn (\n\t\t\ttypeof value === \"object\" &&\n\t\t\tvalue !== null &&\n\t\t\tObject.prototype.isPrototypeOf.call(this.prototype, value)\n\t\t);\n\t}\n\n\t/**\n\t * {@link https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html#assertion-functions|Type assertion} which narrows from ErasedBaseType to the internal implementation type.\n\t * @remarks\n\t * This does a checked conversion, throwing a `TypeError` if invalid.\n\t *\n\t * It would be safer if this narrowed from `TInterface`, but that is not possible since type parameters can not be accessed in static methods.\n\t * Replacing `ErasedTypeImplementation` with a generic function which returns a non-generic class could be used to work around this limitation if desired.\n\t *\n\t * Derived classes can provide their own customized narrowing function with a more specific types if desired.\n\t */\n\tpublic static narrow<TThis extends { prototype: object }>(\n\t\tthis: TThis,\n\t\tvalue: ErasedBaseType | InstanceTypeRelaxed<TThis>,\n\t): asserts value is InstanceTypeRelaxed<TThis> {\n\t\tif (!ErasedTypeImplementation[Symbol.hasInstance].call(this, value as object)) {\n\t\t\tthrow new TypeError(\"Invalid ErasedBaseType instance\");\n\t\t}\n\t}\n\n\t/**\n\t * Upcasts the instance to the erased interface type.\n\t * @remarks\n\t * This is mainly useful when inferring the interface type is required.\n\t */\n\tpublic upCast<TThis extends TInterface>(this: TThis): TInterface {\n\t\treturn this;\n\t}\n}\n\n/**\n * The same as the built-in InstanceType, but works on classes with private constructors.\n * @privateRemarks\n * This is based on the trick in {@link https://stackoverflow.com/a/74657881}.\n * @internal\n */\nexport type InstanceTypeRelaxed<TClass> = InstanceType<(new () => never) & TClass>;\n"]}

package/lib/exposedInternalUtilityTypes.d.ts

@@ -19,7 +19,7 @@ declare const RecursionMarkerSymbol: unique symbol;
  * @privateRemarks
  * WeakRef should be added when lib is updated to ES2021 or later.
  *
- * @beta
+ * @public
  */
 export type ReadonlySupportedGenerics = IFluidHandle | Map<unknown, unknown> | Promise<unknown> | Set<unknown> | WeakMap<object, unknown> | WeakSet<object>;
 /**
@@ -31,7 +31,7 @@ export type ReadonlySupportedGenerics = IFluidHandle | Map<unknown, unknown> | P
  * depth limit when a recursive type is found. Use of `0` will stop applying
  * `DeepReadonly` at the first point recursion is detected.
  *
- * @beta
+ * @public
  * @system
  */
 export type DeepReadonlyRecursionLimit = "NoLimit" | 0 | `+${string}`;
@@ -51,7 +51,7 @@ export type DeepReadonlyRecursionLimit = "NoLimit" | 0 | `+${string}`;
  * exported anyway. All in namespace are left exported to avoid api-extractor
  * potentially failing to validate other modules correctly.
  *
- * @beta
+ * @public
  * @system
  */
 export declare namespace InternalUtilityTypes {