@fluidframework/core-interfaces 2.61.0 → 2.62.0

package/.mocharc.cjs

@@ -7,4 +7,16 @@
 
 // @fluid-internal/mocha-test-setup depends on this package, so we can't use it.
 
-module.exports = { recursive: true };
+const testCJS = process.env.FLUID_TEST_MODULE_SYSTEM === "CJS";
+const outputFilePrefix = testCJS ? "CJS-" : "";
+const suiteName = "@fluidframework/core-interfaces" + (testCJS ? " - CJS" : "");
+module.exports = {
+	spec: testCJS ? "dist/test/**/*.spec.*js" : "lib/test/**/*.spec.*js",
+	recursive: true,
+	require: [testCJS ? "./dist/test/mochaHooks.js" : "./lib/test/mochaHooks.js"],
+	reporter: "mocha-multi-reporters",
+	"reporter-options": [
+		`configFile=test-config.json,cmrOutput=xunit+output+${outputFilePrefix}:xunit+suiteName+${suiteName}`,
+	],
+	"unhandled-rejections": "strict",
+};

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # @fluidframework/core-interfaces
 
+## 2.62.0
+
+Dependency updates only.
+
 ## 2.61.0
 
 Dependency updates only.

package/dist/brandedType.d.ts

@@ -6,15 +6,68 @@
  * Base branded type which can be used to annotate other type.
  *
  * @remarks
- * To use derive another class declaration and ideally add additional private
- * properties to further distinguish the type.
+ * `BrandedType` is covariant over its type parameter, which could be leveraged
+ * for any generic type, but the preferred pattern is to specify variance
+ * explicitly in a derived class making that clear and guaranteeing branding is
+ * unique. It is convenient to have the derived class be the generic given to
+ * `BrandedType`.
+ *
+ * ### Direct use [simple]
+ *
+ * Use `T & BrandedType<"BrandName">` to create a type conforming to `T` and
+ * also branded with name "BrandName".
+ *
+ * ### Derived class use [preferred]
+ *
+ * Derive another class declaration and ideally add additional
+ * protected properties to distinguish the type. (Private properties would
+ * {@link https://github.com/microsoft/TypeScript/issues/20979#issuecomment-361432516|lose their type when exported}
+ * and public properties would allow structural typing and show up on the branded
+ * values.)
+ *
+ * Then use `T & MyBrandedType<U>` to create a type conforming to `T` and
+ * also branded with the derived brand.
+ *
+ * ### Runtime
  *
  * Since branded types are not real value types, they will always need to be
- * created using `as` syntax and very often `as unknown` first.
+ * created using `as` syntax and often `as unknown` first.
  *
  * This class should never exist at runtime, so it is only declared.
  *
- * @sealed
+ * @example
+ * Definition of two branded types with different variance:
+ * ```typescript
+ * // A brand that is covariant over given T
+ * declare class CovariantBrand<T> extends BrandedType<CovariantBrand<unknown>> {
+ *    // Does not allow unrelated or less derived CovariantBrand-ed types to be
+ *    // assigned. CovariantBrand<string> is not assignable to CovariantBrand<"literal">.
+ *    protected readonly CovariantBrand: T;
+ *    private constructor();
+ * }
+ * // A brand that is contravariant over given T
+ * declare class ContravariantBrand<T> extends BrandedType<ContravariantBrand<unknown>> {
+ *    // Does not allow unrelated or more derived ContravariantBrand-ed types to be
+ *    // assigned. ContravariantBrand<"literal"> is not assignable to ContravariantBrand<string>.
+ *    protected readonly ContravariantBrand: (_: T) => void;
+ *    private constructor();
+ * }
+ * ```
+ *
+ * Applying a brand to a type through type-guard:
+ * ```typescript
+ * function numberIs5(n: number): n is number & CovariantBrand<5> {
+ *    return n === 5;
+ * }
+ * function onlyAccept4_5_or_6(_n: number & CovariantBrand<4 | 5 | 6>): void {}
+ *
+ * function example(n: number) {
+ *    if (numberIs5(n)) {
+ *       onlyAccept4_5_or_6(n); // OK: CovariantBrand<5> is assignable to CovariantBrand<4 | 5 | 6>;
+ *   }
+ * }
+ * ```
+ *
  * @internal
  */
 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;;;;;;;;;;;;;;GAcG;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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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"}

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 * To use derive another class declaration and ideally add additional private\n * properties to further distinguish the type.\n *\n * Since branded types are not real value types, they will always need to be\n * created using `as` syntax and very often `as unknown` first.\n *\n * This class should never exist at runtime, so it is only declared.\n *\n * @sealed\n * @internal\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 * @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 * @internal\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/brandedType.d.ts

@@ -6,15 +6,68 @@
  * Base branded type which can be used to annotate other type.
  *
  * @remarks
- * To use derive another class declaration and ideally add additional private
- * properties to further distinguish the type.
+ * `BrandedType` is covariant over its type parameter, which could be leveraged
+ * for any generic type, but the preferred pattern is to specify variance
+ * explicitly in a derived class making that clear and guaranteeing branding is
+ * unique. It is convenient to have the derived class be the generic given to
+ * `BrandedType`.
+ *
+ * ### Direct use [simple]
+ *
+ * Use `T & BrandedType<"BrandName">` to create a type conforming to `T` and
+ * also branded with name "BrandName".
+ *
+ * ### Derived class use [preferred]
+ *
+ * Derive another class declaration and ideally add additional
+ * protected properties to distinguish the type. (Private properties would
+ * {@link https://github.com/microsoft/TypeScript/issues/20979#issuecomment-361432516|lose their type when exported}
+ * and public properties would allow structural typing and show up on the branded
+ * values.)
+ *
+ * Then use `T & MyBrandedType<U>` to create a type conforming to `T` and
+ * also branded with the derived brand.
+ *
+ * ### Runtime
  *
  * Since branded types are not real value types, they will always need to be
- * created using `as` syntax and very often `as unknown` first.
+ * created using `as` syntax and often `as unknown` first.
  *
  * This class should never exist at runtime, so it is only declared.
  *
- * @sealed
+ * @example
+ * Definition of two branded types with different variance:
+ * ```typescript
+ * // A brand that is covariant over given T
+ * declare class CovariantBrand<T> extends BrandedType<CovariantBrand<unknown>> {
+ *    // Does not allow unrelated or less derived CovariantBrand-ed types to be
+ *    // assigned. CovariantBrand<string> is not assignable to CovariantBrand<"literal">.
+ *    protected readonly CovariantBrand: T;
+ *    private constructor();
+ * }
+ * // A brand that is contravariant over given T
+ * declare class ContravariantBrand<T> extends BrandedType<ContravariantBrand<unknown>> {
+ *    // Does not allow unrelated or more derived ContravariantBrand-ed types to be
+ *    // assigned. ContravariantBrand<"literal"> is not assignable to ContravariantBrand<string>.
+ *    protected readonly ContravariantBrand: (_: T) => void;
+ *    private constructor();
+ * }
+ * ```
+ *
+ * Applying a brand to a type through type-guard:
+ * ```typescript
+ * function numberIs5(n: number): n is number & CovariantBrand<5> {
+ *    return n === 5;
+ * }
+ * function onlyAccept4_5_or_6(_n: number & CovariantBrand<4 | 5 | 6>): void {}
+ *
+ * function example(n: number) {
+ *    if (numberIs5(n)) {
+ *       onlyAccept4_5_or_6(n); // OK: CovariantBrand<5> is assignable to CovariantBrand<4 | 5 | 6>;
+ *   }
+ * }
+ * ```
+ *
  * @internal
  */
 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;;;;;;;;;;;;;;GAcG;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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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"}

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 * To use derive another class declaration and ideally add additional private\n * properties to further distinguish the type.\n *\n * Since branded types are not real value types, they will always need to be\n * created using `as` syntax and very often `as unknown` first.\n *\n * This class should never exist at runtime, so it is only declared.\n *\n * @sealed\n * @internal\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 * @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 * @internal\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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluidframework/core-interfaces",
-  "version": "2.61.0",
+  "version": "2.62.0",
   "description": "Fluid object interfaces",
   "homepage": "https://fluidframework.com",
   "repository": {
@@ -143,8 +143,8 @@
     "test": "npm run test:mocha",
     "test:coverage": "c8 npm test",
     "test:mocha": "npm run test:mocha:esm && echo skipping cjs to avoid overhead - npm run test:mocha:cjs",
-    "test:mocha:cjs": "mocha dist/test",
-    "test:mocha:esm": "mocha lib/test",
+    "test:mocha:cjs": "cross-env FLUID_TEST_MODULE_SYSTEM=CJS mocha",
+    "test:mocha:esm": "mocha",
     "test:mocha:verbose": "cross-env FLUID_TEST_VERBOSE=1 npm run test:mocha",
     "tsc": "fluid-tsc commonjs --project ./tsconfig.cjs.json && npm run place:cjs:package-stub",
     "tsc:watch": "npm run place:cjs:package-stub && fluid-tsc commonjs --project ./tsconfig.cjs.json --watch",

package/src/brandedType.ts

@@ -7,15 +7,68 @@
  * Base branded type which can be used to annotate other type.
  *
  * @remarks
- * To use derive another class declaration and ideally add additional private
- * properties to further distinguish the type.
+ * `BrandedType` is covariant over its type parameter, which could be leveraged
+ * for any generic type, but the preferred pattern is to specify variance
+ * explicitly in a derived class making that clear and guaranteeing branding is
+ * unique. It is convenient to have the derived class be the generic given to
+ * `BrandedType`.
+ *
+ * ### Direct use [simple]
+ *
+ * Use `T & BrandedType<"BrandName">` to create a type conforming to `T` and
+ * also branded with name "BrandName".
+ *
+ * ### Derived class use [preferred]
+ *
+ * Derive another class declaration and ideally add additional
+ * protected properties to distinguish the type. (Private properties would
+ * {@link https://github.com/microsoft/TypeScript/issues/20979#issuecomment-361432516|lose their type when exported}
+ * and public properties would allow structural typing and show up on the branded
+ * values.)
+ *
+ * Then use `T & MyBrandedType<U>` to create a type conforming to `T` and
+ * also branded with the derived brand.
+ *
+ * ### Runtime
  *
  * Since branded types are not real value types, they will always need to be
- * created using `as` syntax and very often `as unknown` first.
+ * created using `as` syntax and often `as unknown` first.
  *
  * This class should never exist at runtime, so it is only declared.
  *
- * @sealed
+ * @example
+ * Definition of two branded types with different variance:
+ * ```typescript
+ * // A brand that is covariant over given T
+ * declare class CovariantBrand<T> extends BrandedType<CovariantBrand<unknown>> {
+ *    // Does not allow unrelated or less derived CovariantBrand-ed types to be
+ *    // assigned. CovariantBrand<string> is not assignable to CovariantBrand<"literal">.
+ *    protected readonly CovariantBrand: T;
+ *    private constructor();
+ * }
+ * // A brand that is contravariant over given T
+ * declare class ContravariantBrand<T> extends BrandedType<ContravariantBrand<unknown>> {
+ *    // Does not allow unrelated or more derived ContravariantBrand-ed types to be
+ *    // assigned. ContravariantBrand<"literal"> is not assignable to ContravariantBrand<string>.
+ *    protected readonly ContravariantBrand: (_: T) => void;
+ *    private constructor();
+ * }
+ * ```
+ *
+ * Applying a brand to a type through type-guard:
+ * ```typescript
+ * function numberIs5(n: number): n is number & CovariantBrand<5> {
+ *    return n === 5;
+ * }
+ * function onlyAccept4_5_or_6(_n: number & CovariantBrand<4 | 5 | 6>): void {}
+ *
+ * function example(n: number) {
+ *    if (numberIs5(n)) {
+ *       onlyAccept4_5_or_6(n); // OK: CovariantBrand<5> is assignable to CovariantBrand<4 | 5 | 6>;
+ *   }
+ * }
+ * ```
+ *
  * @internal
  */
 export declare class BrandedType<out Brand> {

package/test-config.json

@@ -0,0 +1,7 @@
+{
+	"reporterEnabled": "spec,xunit",
+	"xunitReporterOptions": {
+		"output": "nyc/{id}junit-report.xml",
+		"suiteName": "{id}"
+	}
+}