feat(client-core-interfaces): JsonString

with `JsonStringify` and `JsonParse` utilities

Test cases added:
```text
  JsonString
    ✔ `JsonString<string>` is assignable to `string`
    ✔ `string` is not assignable to `JsonString<unknown>`
    ✔ object is not assignable to `JsonString<unknown>`
    is covariant over T
      ✔ `JsonString<"literal">` is assignable to `JsonString<string>`
      ✔ `JsonString<Record<string, number>>` is assignable to `JsonString<Record<string, number | undefined>>`
      ✔ `JsonString<Record<string, number | undefined>>` is assignable to `JsonString<Record<string, unknown>>`
      ✔ `JsonString<bigint>` is assignable to `JsonString<unknown>`
    is not contravariant over T
      ✔ `JsonString<string>` is not assignable to `JsonString<"literal">`
      ✔ `JsonString<Record<string, number | undefined>>` is not assignable to `JsonString<Record<string, number>>`
      ✔ `JsonString<unknown>` is not assignable to `JsonString<bigint>`

  JsonStringify and JsonParse
    expected usage
      supports primitive types
        ✔ `boolean`
        ...
        ✔ branded `string`
        ✔ `JsonString<string>`
        ✔ `JsonString<{ arrayOfNumbers: number[] }>`
        ✔ `JsonString<Record<string, number>>`
        ✔ `JsonString<Record<string, number | undefined>>`
        ✔ `JsonString<bigint>`
        ✔ `JsonString<unknown>`
      supports literal types
        ✔ `true`
        ✔ `false`
        ✔ `0`
        ✔ "string"
        ✔ `null`
        ✔ object with literals
        ✔ array of literals
        ✔ tuple of literals
        ✔ specific numeric enum value
        ✔ specific string enum value
        ✔ specific const heterogenous enum value
        ✔ specific computed enum value
      supports array types
        ✔ array of `number`s
        ✔ readonly array of `number`s
        ✔ readonly array of simple objects
      supports object types
        ✔ empty object
        ✔ object with `never`
        ✔ object with `boolean`
        ...
        ✔ `string`|`number` indexed record of `string`s
        ✔ `string`|`number` indexed record of objects
        ✔ templated record of `numbers`
        ✔ `string` indexed record of `number`|`string`s with known properties
        ✔ `string`|`number` indexed record of `strings` with known `number` property (unassignable)
        ✔ branded-`string` indexed of `boolean`s
        ...
        ✔ object with possible type recursion through union
        ✔ object with optional type recursion
        ✔ object with deep type recursion
        ✔ object with alternating type recursion
        ✔ simple non-null object json (NonNullJsonObjectWith<never>)
        ✔ simple read-only non-null object json (ReadonlyNonNullJsonObjectWith<never>)
        ✔ non-const enums
        ✔ object with `readonly`
        ✔ object with getter implemented via value
        ✔ object with setter implemented via value
        ✔ object with matched getter and setter implemented via value
        ✔ object with mismatched getter and setter implemented via value
        class instance
          ✔ with public data (just cares about data)
        object with optional property
          ✔ without property
          ✔ with undefined value
          ✔ with defined value
        opaque Json types
          ✔ opaque serializable object
          ✔ opaque deserialized object
          ✔ opaque serializable and deserialized object
          ✔ opaque serializable unknown
          ✔ opaque deserialized unknown
          ✔ opaque serializable and deserialized unknown
          ✔ object with opaque serializable unknown
          ✔ object with opaque deserialized unknown
          ✔ recursive type with opaque serializable unknown
          ✔ recursive type with opaque deserialized unknown
          ✔ recursive type with opaque serializable and deserialized unknown
          ✔ recursive branded indexed object with OpaqueJsonDeserialized<unknown>
      supports union types
        ✔ simple json (JsonTypeWith<never>)
        ✔ simple read-only json (ReadonlyJsonTypeWith<never>)
      with NOT fully supported object types
        ✔ object with self reference throws on serialization
        known defect expectations
          ✔ sparse array of supported types
          ✔ object with sparse array of supported types
          getters and setters allowed but do not propagate
            ✔ object with `readonly` implemented via getter
            ✔ object with getter
            ✔ object with setter
            ✔ object with matched getter and setter
            ✔ object with mismatched getter and setter
          class instance
            with `ignore-inaccessible-members`
              ✔ with private data ignores private data (that propagates)
    invalid input usage
      assumptions
        ✔ const enums are never readable
      unsupported types cause compiler error
        ✔ `undefined`
        ✔ `unknown`
        ✔ `symbol`
        ✔ `unique symbol`
        ✔ `bigint`
        ✔ function
        ✔ function with supported properties
        ✔ object and function
        ✔ object with function with supported properties
        ✔ object with object and function
        ✔ function with class instance with private data
        ✔ function with class instance with public data
        ✔ class instance with private data and is function
        ✔ class instance with public data and is function
        ✔ `object` (plain object)
        ✔ `void`
        ✔ branded `object`
        ✔ branded object with `string`
        unions with unsupported primitive types
          ✔ `string | symbol`
          ✔ `bigint | string`
          ✔ `bigint | symbol`
          ✔ `number | bigint | symbol`
        array
          ✔ array of `bigint`s
          ✔ array of `symbol`s
          ...
        object
          ✔ object with exactly `bigint`
          ✔ object with optional `bigint`
          ✔ object with exactly `symbol`
          ...
          ✔ `string` indexed record of `unknown`
          ✔ `Partial<>` `string` indexed record of `unknown`
          ✔ `Partial<>` `string` indexed record of `numbers`
          ✔ `Partial<>` templated record of `numbers`
          ✔ object with recursion and `symbol`
          ✔ function object with recursion
          ✔ object and function with recursion
          ✔ nested function object with recursion
          ✔ nested object and function with recursion
          ✔ object with inherited recursion extended with unsupported properties
          object with `undefined`
            ✔ as exact property type
            ✔ in union property
            ...
          object with required `unknown`
            ✔ as exact property type
            ✔ as exact property type adjacent to recursion
            ✔ as exact property type in recursion
          of class instance
            ✔ with private data
            ✔ with private method
            ✔ with private getter
            ✔ with private setter
            ✔ with public method
            ✔ with private data in optional recursion
        opaque Json types requiring extra allowed types
          ✔ opaque serializable object with `bigint`
          ✔ opaque deserialized object with `bigint`
          ✔ opaque serializable and deserialized object with `bigint`
          ✔ opaque serializable object with number array expecting `bigint` support
          ✔ opaque deserialized object with number array expecting `bigint` support
          ✔ opaque serializable and deserialized object with number array expecting `bigint` support
        common class instances
          ✔ Map
          ✔ ReadonlyMap
          ✔ Set
          ✔ ReadonlySet
        Fluid types
          ✔ `IFluidHandle`
          ✔ object with `IFluidHandle`
    special cases
      ✔ explicit `any` generic still limits allowed types
      `number` edge cases
        supported
          ✔ MIN_SAFE_INTEGER
          ✔ MAX_SAFE_INTEGER
          ✔ MIN_VALUE
          ✔ MAX_VALUE
        resulting in `null`
          ✔ NaN
          ✔ +Infinity
          ✔ -Infinity

  JsonDeserialized
    positive compilation tests
      supported primitive types are preserved
        ✔ `JsonString<string>`
        ✔ `JsonString<{ arrayOfNumbers: number[] }>`
        ✔ `JsonString<Record<string, number>>`
        ✔ `JsonString<Record<string, number | undefined>>`
        ✔ JsonString<bigint>
        ✔ JsonString<unknown>

  JsonSerializable
    positive compilation tests
      supported primitive types
        ✔ `JsonString<string>`
        ✔ `JsonString<{ arrayOfNumbers: number[] }>`
        ✔ `JsonString<Record<string, number>>`
        ✔ `JsonString<Record<string, number | undefined>>`
        ✔ JsonString<bigint>
        ✔ JsonString<unknown>
```

Author: jason-ha

packages/common/core-interfaces/package.json

@@ -36,11 +36,11 @@
 		"./internal": {
 			"import": {
 				"types": "./lib/internal.d.ts",
-				"default": "./lib/index.js"
+				"default": "./lib/internal.js"
 			},
 			"require": {
 				"types": "./dist/internal.d.ts",
-				"default": "./dist/index.js"
+				"default": "./dist/internal.js"
 			}
 		},
 		"./internal/exposedUtilityTypes": {

packages/common/core-interfaces/src/cjs/package.json

@@ -12,7 +12,7 @@
 		},
 		"./internal": {
 			"types": "./internal.d.ts",
-			"default": "./index.js"
+			"default": "./internal.js"
 		},
 		"./internal/exposedUtilityTypes": "./exposedUtilityTypes.js"
 	}

packages/common/core-interfaces/src/internal.ts

@@ -7,9 +7,8 @@
 // eslint-disable-next-line no-restricted-syntax, @typescript-eslint/no-restricted-imports
 export * from "./index.js";
 
-// Important: all other exports must be type only exports. In package.json exports,
-//  index.js is listed as the runtime file. This is done so that all imports are
-//  using the same outer runtime file. (Could be changed if needed.)
+export type { JsonString, JsonStringifyOptions } from "./jsonString.js";
+export { JsonStringify, JsonParse } from "./jsonString.js";
 
 export type { JsonTypeToOpaqueJson, OpaqueJsonToJsonType } from "./jsonUtils.js";
 

packages/common/core-interfaces/src/jsonString.ts

@@ -0,0 +1,85 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+// eslint-disable-next-line @typescript-eslint/consistent-type-imports -- incorrect rule: misunderstands `declare`d types.
+import type { BrandedType } from "./brandedType.js";
+import type { JsonDeserialized } from "./jsonDeserialized.js";
+import type { JsonSerializable } from "./jsonSerializable.js";
+
+/**
+ * Brand for JSON that has been stringified.
+ *
+ * Usage: Intersect with another type to apply branding.
+ *
+ * @sealed
+ */
+declare class JsonStringBrand<T> extends BrandedType<JsonString<unknown>> {
+	public toString(): string;
+	protected readonly EncodedValue: T;
+	private constructor();
+}
+
+/**
+ * Branded `string` for JSON that has been stringified.
+ *
+ * @remarks
+ *
+ * Use {@link JsonStringify} to encode JSON producing values of this type and
+ * {@link JsonParse} to decode them.
+ *
+ * For custom encoding/decoding:
+ *
+ * - cast to with `as unknown as JsonString<T>` when value of type `T` has been stringified.
+ *
+ * - use a form of {@link JsonDeserialized} for safety when parsing.
+ *
+ * @sealed
+ * @internal
+ */
+export type JsonString<T> = string & JsonStringBrand<T>;
+
+/**
+ * Options for {@link JsonStringify}.
+ *
+ * @internal
+ */
+export interface JsonStringifyOptions {
+	/**
+	 * When set, inaccessible (protected and private) members throughout type T are
+	 * ignored as if not present. Otherwise, inaccessible members are considered
+	 * an error (type checking will mention `SerializationErrorPerNonPublicProperties`).
+	 *
+	 * @remarks
+	 * The default is that `IgnoreInaccessibleMembers` property is not specified,
+	 * which means that inaccessible members are considered an error.
+	 */
+	IgnoreInaccessibleMembers?: "ignore-inaccessible-members";
+}
+
+/**
+ * Performs basic JSON serialization using `JSON.stringify` and brands the result as {@link JsonString}`<T>`.
+ *
+ * @remarks
+ * Parameter `value` must be JSON-serializable and thus type T is put through filter {@link JsonSerializable}.
+ *
+ * @internal
+ */
+export const JsonStringify = JSON.stringify as <
+	T,
+	// eslint-disable-next-line @typescript-eslint/ban-types -- `Record<string, never>` is not sufficient replacement for empty object.
+	Options extends JsonStringifyOptions = {},
+>(
+	value: JsonSerializable<T, Options>,
+) => JsonString<T>;
+
+/**
+ * Performs basic JSON parsing using `JSON.parse` given a {@link JsonString}`<T>` (`string`).
+ *
+ * @remarks
+ * Return type is filtered through {@link JsonDeserialized}`<T>` for best accuracy.
+ *
+ * @internal
+ */
+export const JsonParse: <T>(text: JsonString<T>) => JsonDeserialized<T> = JSON.parse;

packages/common/core-interfaces/src/test/jsonDeserialized.spec.ts

@@ -21,6 +21,8 @@ import type {
 	BrandedKey,
 	BrandedString,
 	DecodedValueDirectoryOrRequiredState,
+	DeserializedOpaqueSerializableInRecursiveStructure,
+	DeserializedOpaqueSerializableAndDeserializedInRecursiveStructure,
 	DirectoryOfValues,
 	ObjectWithOptionalRecursion,
 } from "./testValues.js";
@@ -211,6 +213,12 @@ import {
 	opaqueSerializableObjectExpectingBigintSupport,
 	opaqueDeserializedObjectExpectingBigintSupport,
 	opaqueSerializableAndDeserializedObjectExpectingBigintSupport,
+	jsonStringOfString,
+	jsonStringOfObjectWithArrayOfNumbers,
+	jsonStringOfStringRecordOfNumbers,
+	jsonStringOfStringRecordOfNumberOrUndefined,
+	jsonStringOfBigInt,
+	jsonStringOfUnknown,
 } from "./testValues.js";
 
 import type { IFluidHandle } from "@fluidframework/core-interfaces";
@@ -220,7 +228,6 @@ import type {
 	JsonTypeWith,
 	NonNullJsonObjectWith,
 	OpaqueJsonDeserialized,
-	OpaqueJsonSerializable,
 } from "@fluidframework/core-interfaces/internal/exposedUtilityTypes";
 
 /**
@@ -368,6 +375,36 @@ describe("JsonDeserialized", () => {
 				assertIdenticalTypes(resultRead, brandedString);
 				assertNever<AnyLocations<typeof resultRead>>();
 			});
+			it("`JsonString<string>`", () => {
+				const resultRead = passThru(jsonStringOfString);
+				assertIdenticalTypes(resultRead, jsonStringOfString);
+				assertNever<AnyLocations<typeof resultRead>>();
+			});
+			it("`JsonString<{ arrayOfNumbers: number[] }>`", () => {
+				const resultRead = passThru(jsonStringOfObjectWithArrayOfNumbers);
+				assertIdenticalTypes(resultRead, jsonStringOfObjectWithArrayOfNumbers);
+				assertNever<AnyLocations<typeof resultRead>>();
+			});
+			it("`JsonString<Record<string, number>>`", () => {
+				const resultRead = passThru(jsonStringOfStringRecordOfNumbers);
+				assertIdenticalTypes(resultRead, jsonStringOfStringRecordOfNumbers);
+				assertNever<AnyLocations<typeof resultRead>>();
+			});
+			it("`JsonString<Record<string, number | undefined>>`", () => {
+				const resultRead = passThru(jsonStringOfStringRecordOfNumberOrUndefined);
+				assertIdenticalTypes(resultRead, jsonStringOfStringRecordOfNumberOrUndefined);
+				assertNever<AnyLocations<typeof resultRead>>();
+			});
+			it("JsonString<bigint>", () => {
+				const resultRead = passThru(jsonStringOfBigInt);
+				assertIdenticalTypes(resultRead, jsonStringOfBigInt);
+				assertNever<AnyLocations<typeof resultRead>>();
+			});
+			it("JsonString<unknown>", () => {
+				const resultRead = passThru(jsonStringOfUnknown);
+				assertIdenticalTypes(resultRead, jsonStringOfUnknown);
+				assertNever<AnyLocations<typeof resultRead>>();
+			});
 		});
 
 		describe("unions with unsupported primitive types preserve supported types", () => {
@@ -516,11 +553,15 @@ describe("JsonDeserialized", () => {
 			});
 			it("array of functions with properties becomes ({...}|null)[]", () => {
 				const resultRead = passThru(arrayOfFunctionsWithProperties, [null]);
+				// Note: a function with properties always results in `null`, but a property bag
+				// with a function is the property bag. Allow either to avoid order-based logic.
 				assertIdenticalTypes(resultRead, createInstanceOf<({ property: number } | null)[]>());
 				assertNever<AnyLocations<typeof resultRead>>();
 			});
 			it("array of objects and functions becomes ({...}|null)[]", () => {
 				const resultRead = passThru(arrayOfObjectAndFunctions, [{ property: 6 }]);
+				// Note: a function with properties always results in `null`, but a property bag
+				// with a function is the property bag. Allow either to avoid order-based logic.
 				assertIdenticalTypes(resultRead, createInstanceOf<({ property: number } | null)[]>());
 				assertNever<AnyLocations<typeof resultRead>>();
 			});
@@ -1677,15 +1718,6 @@ describe("JsonDeserialized", () => {
 				});
 				it("object with OpaqueJsonSerializable<unknown> in recursion is unrolled one time with OpaqueJsonDeserialized", () => {
 					const resultRead = passThru(opaqueSerializableInRecursiveStructure);
-					interface DeserializedOpaqueSerializableInRecursiveStructure {
-						items: {
-							[x: string | number]:
-								| OpaqueJsonDeserialized<DirectoryOfValues<OpaqueJsonSerializable<unknown>>>
-								| {
-										value?: OpaqueJsonDeserialized<unknown>;
-								  };
-						};
-					}
 					assertIdenticalTypes(
 						resultRead,
 						createInstanceOf<DeserializedOpaqueSerializableInRecursiveStructure>(),
@@ -1708,22 +1740,9 @@ describe("JsonDeserialized", () => {
 				// It might be better to preserve the intersection and return original type.
 				it("object with OpaqueJsonSerializable<unknown> & OpaqueJsonDeserialized<unknown> in recursion is unrolled one time with OpaqueJsonDeserialized", () => {
 					const resultRead = passThru(opaqueSerializableAndDeserializedInRecursiveStructure);
-					interface DeserializedOpaqueSerializableInRecursiveStructure {
-						items: {
-							[x: string | number]:
-								| OpaqueJsonDeserialized<
-										DirectoryOfValues<
-											OpaqueJsonSerializable<unknown> & OpaqueJsonDeserialized<unknown>
-										>
-								  >
-								| {
-										value?: OpaqueJsonDeserialized<unknown>;
-								  };
-						};
-					}
 					assertIdenticalTypes(
 						resultRead,
-						createInstanceOf<DeserializedOpaqueSerializableInRecursiveStructure>(),
+						createInstanceOf<DeserializedOpaqueSerializableAndDeserializedInRecursiveStructure>(),
 					);
 					assertNever<AnyLocations<typeof resultRead>>();
 					const transparentResult = revealOpaqueJson(resultRead);
@@ -1732,7 +1751,7 @@ describe("JsonDeserialized", () => {
 						createInstanceOf<{
 							items: {
 								[x: string | number]:
-									| DeserializedOpaqueSerializableInRecursiveStructure
+									| DeserializedOpaqueSerializableAndDeserializedInRecursiveStructure
 									| {
 											value?: JsonTypeWith<never>;
 									  };

packages/common/core-interfaces/src/test/jsonSerializable.spec.ts

@@ -202,6 +202,12 @@ import {
 	opaqueSerializableObjectExpectingBigintSupport,
 	opaqueDeserializedObjectExpectingBigintSupport,
 	opaqueSerializableAndDeserializedObjectExpectingBigintSupport,
+	jsonStringOfString,
+	jsonStringOfObjectWithArrayOfNumbers,
+	jsonStringOfStringRecordOfNumbers,
+	jsonStringOfStringRecordOfNumberOrUndefined,
+	jsonStringOfBigInt,
+	jsonStringOfUnknown,
 } from "./testValues.js";
 
 import type { IFluidHandle } from "@fluidframework/core-interfaces";
@@ -441,6 +447,36 @@ describe("JsonSerializable", () => {
 				assertIdenticalTypes(filteredIn, brandedString);
 				assertIdenticalTypes(filteredIn, out);
 			});
+			it("`JsonString<string>`", () => {
+				const { filteredIn, out } = passThru(jsonStringOfString);
+				assertIdenticalTypes(filteredIn, jsonStringOfString);
+				assertIdenticalTypes(filteredIn, out);
+			});
+			it("`JsonString<{ arrayOfNumbers: number[] }>`", () => {
+				const { filteredIn, out } = passThru(jsonStringOfObjectWithArrayOfNumbers);
+				assertIdenticalTypes(filteredIn, jsonStringOfObjectWithArrayOfNumbers);
+				assertIdenticalTypes(filteredIn, out);
+			});
+			it("`JsonString<Record<string, number>>`", () => {
+				const { filteredIn, out } = passThru(jsonStringOfStringRecordOfNumbers);
+				assertIdenticalTypes(filteredIn, jsonStringOfStringRecordOfNumbers);
+				assertIdenticalTypes(filteredIn, out);
+			});
+			it("`JsonString<Record<string, number | undefined>>`", () => {
+				const { filteredIn, out } = passThru(jsonStringOfStringRecordOfNumberOrUndefined);
+				assertIdenticalTypes(filteredIn, jsonStringOfStringRecordOfNumberOrUndefined);
+				assertIdenticalTypes(filteredIn, out);
+			});
+			it("JsonString<bigint>", () => {
+				const { filteredIn, out } = passThru(jsonStringOfBigInt);
+				assertIdenticalTypes(filteredIn, jsonStringOfBigInt);
+				assertIdenticalTypes(filteredIn, out);
+			});
+			it("JsonString<unknown>", () => {
+				const { filteredIn, out } = passThru(jsonStringOfUnknown);
+				assertIdenticalTypes(filteredIn, jsonStringOfUnknown);
+				assertIdenticalTypes(filteredIn, out);
+			});
 		});
 
 		describe("supported literal types", () => {
@@ -1566,8 +1602,10 @@ describe("JsonSerializable", () => {
 				});
 
 				it("`string` indexed record of `unknown`", () => {
-					// @ts-expect-error not assignable to parameter of type '{ [x: string]: JsonTypeWith<never> | OpaqueJsonSerializable<unknown>; }'.
-					const { filteredIn } = passThru(stringRecordOfUnknown);
+					const { filteredIn } = passThru(
+						// @ts-expect-error not assignable to parameter of type '{ [x: string]: JsonTypeWith<never> | OpaqueJsonSerializable<unknown>; }'.
+						stringRecordOfUnknown,
+					);
 					assertIdenticalTypes(
 						filteredIn,
 						createInstanceOf<{
@@ -1576,8 +1614,10 @@ describe("JsonSerializable", () => {
 					);
 				});
 				it("`Partial<>` `string` indexed record of `unknown`", () => {
-					// @ts-expect-error not assignable to parameter of type '{ [x: string]: JsonTypeWith<never> | OpaqueJsonSerializable<unknown>; }'.
-					const { filteredIn } = passThru(partialStringRecordOfUnknown);
+					const { filteredIn } = passThru(
+						// @ts-expect-error not assignable to parameter of type '{ [x: string]: JsonTypeWith<never> | OpaqueJsonSerializable<unknown>; }'.
+						partialStringRecordOfUnknown,
+					);
 					assertIdenticalTypes(
 						filteredIn,
 						createInstanceOf<{
@@ -1593,8 +1633,11 @@ describe("JsonSerializable", () => {
 					// Allowing `undefined` is possible if all indexed properties are
 					// identifiable. But rather than that, an implementation of `Partial<>`
 					// that doesn't add `| undefined` for index signatures would be preferred.
-					// @ts-expect-error not assignable to type '{ "error required property may not allow `undefined` value": never; }'
-					const { filteredIn } = passThru(partialStringRecordOfNumbers, { key1: 0 });
+					const { filteredIn } = passThru(
+						// @ts-expect-error not assignable to type '{ "error required property may not allow `undefined` value": never; }'
+						partialStringRecordOfNumbers,
+						{ key1: 0 },
+					);
 					assertIdenticalTypes(
 						filteredIn,
 						createInstanceOf<{
@@ -1611,8 +1654,11 @@ describe("JsonSerializable", () => {
 					// Allowing `undefined` is possible if all indexed properties are
 					// identifiable. But rather than that, an implementation of `Partial<>`
 					// that doesn't add `| undefined` for index signatures would be preferred.
-					// @ts-expect-error not assignable to type '{ "error required property may not allow `undefined` value": never; }'
-					const { filteredIn } = passThru(partialTemplatedRecordOfNumbers, { key1: 0 });
+					const { filteredIn } = passThru(
+						// @ts-expect-error not assignable to type '{ "error required property may not allow `undefined` value": never; }'
+						partialTemplatedRecordOfNumbers,
+						{ key1: 0 },
+					);
 					assertIdenticalTypes(
 						filteredIn,
 						createInstanceOf<{