@fluidframework/core-interfaces 2.62.0 → 2.63.0-359286

package/lib/jsonString.js

@@ -0,0 +1,27 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+/**
+ * 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;
+/**
+ * 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.
+ *
+ * Note that `JsonParse` cannot verify at runtime that the input is valid JSON
+ * or that it matches type T. It is the caller's responsibility to ensure that
+ * the input is valid JSON and the output conforms to the expected type.
+ *
+ * @internal
+ */
+export const JsonParse = JSON.parse;
+//# sourceMappingURL=jsonString.js.map

package/lib/jsonString.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsonString.js","sourceRoot":"","sources":["../src/jsonString.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAyFH;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,IAAI,CAAC,SAShB,CAAC;AAEnB;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,IAAI,CAAC,KAEoC,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\n// eslint-disable-next-line @typescript-eslint/consistent-type-imports -- incorrect rule: misunderstands `declare`d types.\nimport type { BrandedType } from \"./brandedType.js\";\nimport type { InternalUtilityTypes } from \"./exposedInternalUtilityTypes.js\";\nimport type { JsonDeserialized } from \"./jsonDeserialized.js\";\nimport type { JsonSerializable, JsonSerializableOptions } from \"./jsonSerializable.js\";\n\n/**\n * Brand for JSON that has been stringified.\n *\n * Usage: Intersect with another type to apply branding.\n *\n * @sealed\n */\ndeclare class JsonStringBrand<T> extends BrandedType<JsonString<unknown>> {\n\tpublic toString(): string;\n\tprotected readonly EncodedValue: T;\n\tprivate constructor();\n}\n\n/**\n * Distributes `JsonStringBrand` over union elements of T.\n *\n * @remarks\n * This is useful to allow `JsonString<A | B>` to be assigned to `JsonString<A> | JsonString<B>`.\n *\n * The downside is that enums are expanded to union of members and thus cannot be\n * reconstituted exactly (even if IntelliSense shows the original enum type). This\n * can be removed if exact enum preservation is found to be more important.\n */\ntype DistributeJsonStringBrand<T> = T extends unknown ? JsonStringBrand<T> : never;\n\n/**\n * Distributes branding over union elements of T unless result could prevent T\n * from being reconstituted (as in the case of an enum type), in which case it\n * falls back to a single JsonStringBrand for the entire T.\n *\n * @remarks\n * Note that an enum unioned with anything else will be distributed. It seems\n * however that TypeScript can/will reconstitute the enum type in that case.\n */\ntype BrandForJsonString<T> = InternalUtilityTypes.IfSameType<\n\tDistributeJsonStringBrand<T> extends JsonStringBrand<infer U> ? U : never,\n\tT,\n\tDistributeJsonStringBrand<T>,\n\tJsonStringBrand<T>\n>;\n\n/**\n * Branded `string` for JSON that has been stringified.\n *\n * @remarks\n *\n * Use {@link JsonStringify} to encode JSON producing values of this type and\n * {@link JsonParse} to decode them.\n *\n * For custom encoding/decoding:\n *\n * - cast to with `as unknown as JsonString<T>` when value of type `T` has been stringified.\n *\n * - use a form of {@link JsonDeserialized} for safety when parsing.\n *\n * @sealed\n * @internal\n */\nexport type JsonString<T> = string & BrandForJsonString<T>;\n\n/**\n * Compile options for {@link JsonStringify}.\n *\n * @remarks\n * This only impacts type checking -- it has no impact on runtime.\n *\n * The options are currently a subset of {@link JsonSerializableOptions}, specifically\n * only `IgnoreInaccessibleMembers` is supported.\n *\n * No instance of this should ever exist at runtime.\n *\n * @privateRemarks\n * Consider adding `AllowUnknown` option to allow precisely `unknown` types to\n * be passed through. With `unknown` expected successful serialization could not\n * be checked at compile time. At deserialization time, `unknown` does not\n * guarantee any type and thus allowing does not erode type safety.\n *\n * @internal\n */\nexport type JsonStringifyOptions = Pick<JsonSerializableOptions, \"IgnoreInaccessibleMembers\">;\n\n/**\n * Performs basic JSON serialization using `JSON.stringify` and brands the result as {@link JsonString}`<T>`.\n *\n * @remarks\n * Parameter `value` must be JSON-serializable and thus type T is put through filter {@link JsonSerializable}.\n *\n * @internal\n */\nexport const JsonStringify = JSON.stringify as <\n\tT,\n\tOptions extends JsonStringifyOptions = Record<never, never>,\n>(\n\tvalue: JsonSerializable<\n\t\tT,\n\t\t// Make sure only options that are known are passed through.\n\t\tPick<Options, Extract<keyof JsonStringifyOptions, keyof Options>>\n\t>,\n) => JsonString<T>;\n\n/**\n * Performs basic JSON parsing using `JSON.parse` given a {@link JsonString}`<T>` (`string`).\n *\n * @remarks\n * Return type is filtered through {@link JsonDeserialized}`<T>` for best accuracy.\n *\n * Note that `JsonParse` cannot verify at runtime that the input is valid JSON\n * or that it matches type T. It is the caller's responsibility to ensure that\n * the input is valid JSON and the output conforms to the expected type.\n *\n * @internal\n */\nexport const JsonParse = JSON.parse as <T extends JsonString<unknown>>(\n\ttext: T,\n) => T extends JsonString<infer U> ? JsonDeserialized<U> : unknown;\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluidframework/core-interfaces",
-  "version": "2.62.0",
+  "version": "2.63.0-359286",
   "description": "Fluid object interfaces",
   "homepage": "https://fluidframework.com",
   "repository": {
@@ -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": {
@@ -76,7 +76,7 @@
     "@fluid-tools/build-cli": "^0.58.3",
     "@fluidframework/build-common": "^2.0.3",
     "@fluidframework/build-tools": "^0.58.3",
-    "@fluidframework/core-interfaces-previous": "npm:@fluidframework/core-interfaces@2.60.0",
+    "@fluidframework/core-interfaces-previous": "npm:@fluidframework/core-interfaces@2.62.0",
     "@fluidframework/eslint-config-fluid": "^6.0.0",
     "@microsoft/api-extractor": "7.52.11",
     "@types/mocha": "^10.0.10",

package/src/cjs/package.json

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

package/src/exposedInternalUtilityTypes.ts

@@ -871,6 +871,9 @@ export namespace InternalUtilityTypes {
 	export type JsonSerializableImpl<
 		T,
 		Options extends Partial<FilterControls> & {
+			/**
+			 * See {@link JsonSerializableOptions} for meaning and expected use.
+			 */
 			IgnoreInaccessibleMembers?: "ignore-inaccessible-members";
 		},
 		TAncestorTypes extends unknown[] = [],
@@ -903,7 +906,7 @@ export namespace InternalUtilityTypes {
 			Controls extends FilterControlsWithSubstitution
 			? /* test for 'any' */ boolean extends (T extends never ? true : false)
 				? /* 'any' => */ Controls["DegenerateSubstitute"]
-				: Options["IgnoreInaccessibleMembers"] extends "ignore-inaccessible-members"
+				: Options extends { IgnoreInaccessibleMembers: "ignore-inaccessible-members" }
 					? JsonSerializableFilter<T, Controls, TAncestorTypes, TNextAncestor>
 					: /* test for non-public properties (class instance type) */
 						IfNonPublicProperties<

package/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";
 

package/src/jsonSerializable.ts

@@ -33,9 +33,17 @@ export interface JsonSerializableOptions {
 
 	/**
 	 * When set, inaccessible (protected and private) members throughout type T are
-	 * ignored as if not present.
+	 * ignored as if not present. Otherwise, inaccessible members are considered
+	 * an error (type checking will mention `SerializationErrorPerNonPublicProperties`).
 	 *
-	 * The default value is not present.
+	 * @remarks
+	 * For this option to be set and accurately filter inaccessible members, all
+	 * inaccessible members (if any) must be either inherited, symbol keyed, or
+	 * non-enumerable.
+	 *
+	 * The default is that `IgnoreInaccessibleMembers` property is not specified,
+	 * which means that inaccessible members are considered an error, even if
+	 * they would not be serialized at runtime.
 	 */
 	IgnoreInaccessibleMembers?: "ignore-inaccessible-members";
 }

package/src/jsonString.ts

@@ -0,0 +1,126 @@
+/*!
+ * 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 { InternalUtilityTypes } from "./exposedInternalUtilityTypes.js";
+import type { JsonDeserialized } from "./jsonDeserialized.js";
+import type { JsonSerializable, JsonSerializableOptions } 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();
+}
+
+/**
+ * Distributes `JsonStringBrand` over union elements of T.
+ *
+ * @remarks
+ * This is useful to allow `JsonString<A | B>` to be assigned to `JsonString<A> | JsonString<B>`.
+ *
+ * The downside is that enums are expanded to union of members and thus cannot be
+ * reconstituted exactly (even if IntelliSense shows the original enum type). This
+ * can be removed if exact enum preservation is found to be more important.
+ */
+type DistributeJsonStringBrand<T> = T extends unknown ? JsonStringBrand<T> : never;
+
+/**
+ * Distributes branding over union elements of T unless result could prevent T
+ * from being reconstituted (as in the case of an enum type), in which case it
+ * falls back to a single JsonStringBrand for the entire T.
+ *
+ * @remarks
+ * Note that an enum unioned with anything else will be distributed. It seems
+ * however that TypeScript can/will reconstitute the enum type in that case.
+ */
+type BrandForJsonString<T> = InternalUtilityTypes.IfSameType<
+	DistributeJsonStringBrand<T> extends JsonStringBrand<infer U> ? U : never,
+	T,
+	DistributeJsonStringBrand<T>,
+	JsonStringBrand<T>
+>;
+
+/**
+ * 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 & BrandForJsonString<T>;
+
+/**
+ * Compile options for {@link JsonStringify}.
+ *
+ * @remarks
+ * This only impacts type checking -- it has no impact on runtime.
+ *
+ * The options are currently a subset of {@link JsonSerializableOptions}, specifically
+ * only `IgnoreInaccessibleMembers` is supported.
+ *
+ * No instance of this should ever exist at runtime.
+ *
+ * @privateRemarks
+ * Consider adding `AllowUnknown` option to allow precisely `unknown` types to
+ * be passed through. With `unknown` expected successful serialization could not
+ * be checked at compile time. At deserialization time, `unknown` does not
+ * guarantee any type and thus allowing does not erode type safety.
+ *
+ * @internal
+ */
+export type JsonStringifyOptions = Pick<JsonSerializableOptions, "IgnoreInaccessibleMembers">;
+
+/**
+ * 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,
+	Options extends JsonStringifyOptions = Record<never, never>,
+>(
+	value: JsonSerializable<
+		T,
+		// Make sure only options that are known are passed through.
+		Pick<Options, Extract<keyof JsonStringifyOptions, keyof 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.
+ *
+ * Note that `JsonParse` cannot verify at runtime that the input is valid JSON
+ * or that it matches type T. It is the caller's responsibility to ensure that
+ * the input is valid JSON and the output conforms to the expected type.
+ *
+ * @internal
+ */
+export const JsonParse = JSON.parse as <T extends JsonString<unknown>>(
+	text: T,
+) => T extends JsonString<infer U> ? JsonDeserialized<U> : unknown;