@fluidframework/core-interfaces 2.23.0 → 2.30.0

package/src/exposedUtilityTypes.ts

@@ -0,0 +1,20 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+// Usage: Access these types via /internal/exposedUtilityTypes import spec when
+// system level but externally exposed version of utilities are needed.
+// Import via /internal when use is not exposed externally.
+// Should a customer need access to these types, export should be relocated to
+// index.ts and retagged export from internal.ts may be removed.
+
+export type { JsonDeserialized, JsonDeserializedOptions } from "./jsonDeserialized.js";
+export type { JsonSerializable, JsonSerializableOptions } from "./jsonSerializable.js";
+export type {
+	SerializationErrorPerNonPublicProperties,
+	SerializationErrorPerUndefinedArrayElement,
+} from "./jsonSerializationErrors.js";
+export type { JsonTypeWith, NonNullJsonObjectWith } from "./jsonType.js";
+
+export type { InternalUtilityTypes } from "./exposedInternalUtilityTypes.js";

package/src/internal.ts

@@ -0,0 +1,73 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+// eslint-disable-next-line no-restricted-syntax
+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 set of utility types re-tagged as internal for FF client convenience.
+// These types are not intended for direct use by customers and api-extractor will
+// flag misuse. If an externally visible version of these types is needed, import
+// from via /internal/exposedUtilityTypes rather than /internal.
+import type { InternalUtilityTypes as ExposedInternalUtilityTypes } from "./exposedInternalUtilityTypes.js";
+import type {
+	JsonDeserialized as ExposedJsonDeserialized,
+	JsonDeserializedOptions,
+} from "./jsonDeserialized.js";
+import type {
+	JsonSerializable as ExposedJsonSerializable,
+	JsonSerializableOptions,
+} from "./jsonSerializable.js";
+import type { JsonTypeWith as ExposedJsonTypeWith } from "./jsonType.js";
+
+// Note: There are no docs for these re-exports. `@inheritdoc` cannot be used as:
+//   1. api-extractor does not support renames.
+//   2. api-extractor does not support package paths. ("Import paths are not supported")
+// Also not useful, at least in VS Code, as substitution is not made in place.
+
+/**
+ * @internal
+ */
+export type JsonDeserialized<
+	T,
+	Options extends JsonDeserializedOptions = {
+		AllowExactly: [];
+		AllowExtensionOf: never;
+	},
+> = ExposedJsonDeserialized<T, Options>;
+
+/**
+ * @internal
+ */
+export type JsonSerializable<
+	T,
+	Options extends JsonSerializableOptions = {
+		AllowExactly: [];
+		AllowExtensionOf: never;
+	},
+> = ExposedJsonSerializable<T, Options>;
+
+/**
+ * @internal
+ */
+export type JsonTypeWith<T> = ExposedJsonTypeWith<T>;
+
+/**
+ * @internal
+ */
+// eslint-disable-next-line @typescript-eslint/no-namespace
+export namespace InternalUtilityTypes {
+	/* eslint-disable jsdoc/require-jsdoc */
+	export type IfSameType<
+		X,
+		Y,
+		IfSame = unknown,
+		IfDifferent = never,
+	> = ExposedInternalUtilityTypes.IfSameType<X, Y, IfSame, IfDifferent>;
+	/* eslint-enable jsdoc/require-jsdoc */
+}

package/src/jsonDeserialized.ts

@@ -0,0 +1,118 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import type { InternalUtilityTypes } from "./exposedInternalUtilityTypes.js";
+
+/**
+ * Options for {@link JsonDeserialized}.
+ *
+ * @beta
+ */
+export interface JsonDeserializedOptions {
+	/**
+	 * Tuple of exact types that are managed by custom deserialization logic (beyond
+	 * {@link https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse|JSON.parse}
+	 * without a reviver). Only exact types matching specification will be
+	 * preserved unaltered.
+	 *
+	 * The default value is `[]`.
+	 */
+	AllowExactly?: unknown[];
+
+	/**
+	 * General types that are managed by custom deserialization logic (beyond
+	 * {@link https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse|JSON.parse}
+	 * without a reviver). Any type satisfying specification will be preserved
+	 * unaltered.
+	 *
+	 * The default value is `never`.
+	 */
+	AllowExtensionOf?: unknown;
+}
+
+/**
+ * Produces a type that results from a type `T` serialized and deserialized
+ * through JSON using {@link https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify|JSON.stringify}
+ * (without replacer) and {@link https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse|JSON.parse}
+ * (without reviver), respectively as base model.
+ *
+ * @typeParam T - The type that was serialized.
+ * @typeParam Options - Options for the filter. See {@link JsonDeserializedOptions}.
+ *
+ * @remarks
+ * Before adding use of this utility type, consider using a utility like
+ * {@link https://github.com/sinclairzx81/typebox#readme | TypeBox} that allows
+ * for runtime validation.
+ *
+ * This filter can be used to derive the expected type of a JSON deserialized
+ * value whether or not the type of value serialized meets serialization
+ * constraints (see {@link JsonSerializable} including serialization pitfalls).
+ *
+ * When used as a filter to inferred generic `T`, a compile-time error can be
+ * produced trying to assign `JsonDeserialized<T>` to `T`.
+ *
+ * Simply deserialized JSON never contains `bigint`, `undefined`, `symbol`,
+ * or function values. (Object properties which had those types before encoding
+ * are omitted during serialization and thus won't be present after
+ * deserialization.) Therefore, through this filter, such properties:
+ *
+ * - become optional with those types excluded (when there are other supported
+ * types in union)
+ *
+ * - are removed (when nothing else in union is supported)
+ *
+ * - in an array are (1) replaced with `null` if `undefined`, `symbol`, and
+ * function values or (2) simply removed (become `never`) if `bigint` value as
+ * serialization attempts will throw.
+ *
+ * Examples results:
+ *
+ * | Before serialization  | After deserialization | After in record    |       After in array |
+ * | --------------------- | --------------------- | ------------------ | --------------------:|
+ * | `undefined \| number` | `number`              | `prop?: number`    | `(number \| null)[]` |
+ * | `symbol \| number`    | `number`              | `prop?: number`    | `(number \| null)[]` |
+ * | `bigint \| number`    | `number`              | `prop: number`     |           `number[]` |
+ * | `undefined`           | N/A `never`           | (prop not present) |             `null[]` |
+ * | `symbol`              | N/A `never`           | (prop not present) |             `null[]` |
+ * | `bigint`              | N/A `never`           | N/A (prop not present) |    N/A `never[]` |
+ * | `bigint \| symbol`    | N/A `never`           | (prop not present) |             `null[]` |
+ * | `bigint \| number \| symbol` | `number`       | `prop?: number`    | `(number \| null)[]` |
+ *
+ * Setter and getter properties become value properties after filtering
+ * although no data will be persisted assuming those properties are backed
+ * by functions. If an implementation of getter/setter interface uses a
+ * simple data member (of supported type), that will persist.
+ *
+ * Recursive types without any required modification are preserved intact.
+ * Recursive types that require modification are unrolled a limited number of
+ * times (currently 4) and then further instances of recursion are replaced with
+ * {@link JsonTypeWith|JsonTypeWith<Options.AllowExactly[number] "or" Options.AllowExtensionOf>}.
+ *
+ * Under basic serialization, class instances become simple data objects that
+ * lose hidden properties and prototypes that are required for `instanceof`
+ * runtime checks. An exception is made for classes that are intersected with
+ * primitive types (specifically `boolean`, `string`, and `number`) under the
+ * assumption that such classes are present only as type modifiers (as would
+ * be the case for branding) and not as require runtime values.
+ *
+ * The optional 'Options.AllowExactly' and 'Options.AllowExtensionOf'
+ * parameters may be used to permit additional leaf types handled by custom
+ * serialization/deserialization logic.
+ *
+ * @example Example usage
+ *
+ * ```typescript
+ * function foo<T>(): JsonDeserialized<T> { ... }
+ * ```
+ *
+ * @beta
+ */
+export type JsonDeserialized<
+	T,
+	Options extends JsonDeserializedOptions = {
+		AllowExactly: [];
+		AllowExtensionOf: never;
+	},
+> = InternalUtilityTypes.JsonDeserializedImpl<T, Options>;

package/src/jsonSerializable.ts

@@ -0,0 +1,133 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import type { InternalUtilityTypes } from "./exposedInternalUtilityTypes.js";
+
+/**
+ * Options for {@link JsonSerializable}.
+ *
+ * @beta
+ */
+export interface JsonSerializableOptions {
+	/**
+	 * Tuple of exact types that are managed by custom serialization logic (beyond
+	 * {@link https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify|JSON.stringify}
+	 * without a replacer). Only exact types matching specification will be
+	 * preserved unaltered.
+	 *
+	 * The default value is `[]`.
+	 */
+	AllowExactly?: unknown[];
+
+	/**
+	 * General types that are managed by custom serialization logic (beyond
+	 * {@link https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify|JSON.stringify}
+	 * without a replacer). Any type satisfying specification will be preserved
+	 * unaltered.
+	 *
+	 * The default value is `never`.
+	 */
+	AllowExtensionOf?: unknown;
+
+	/**
+	 * When set, inaccessible (protected and private) members throughout type T are
+	 * ignored as if not present.
+	 *
+	 * The default value is not present.
+	 */
+	IgnoreInaccessibleMembers?: "ignore-inaccessible-members";
+}
+
+/**
+ * Used to constrain a type `T` to types that are serializable as JSON
+ * using {@link https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify|JSON.stringify}
+ * (without a replacer) as base model.
+ *
+ * Under typical use a compile-time error is produced if `T` contains
+ * non-JsonSerializable members.
+ *
+ * @typeParam T - The type to be constrained.
+ * @typeParam Options - Options for the filter. See {@link JsonSerializableOptions}.
+ *
+ * @remarks
+ * Before adding use of this utility type, consider using a utility like
+ * {@link https://github.com/sinclairzx81/typebox#readme | TypeBox} that allows
+ * for runtime validation.
+ *
+ * Note that this does NOT prevent use of values with non-JSON compatible data,
+ * it only prevents using values with types that include non-JSON compatible data.
+ * This means that one can, for example, pass in a value typed with JSON compatible
+ * interface into this filter, that could actually be a class with lots on non-JSON
+ * compatible fields and methods.
+ *
+ * Important: `T extends JsonSerializable<T>` is incorrect (does not even compile).
+ *
+ * The optional `Options.Allow*` parameters may be used to permit additional leaf types
+ * to support situations where a `replacer` is used to handle special values (e.g.,
+ * `JsonSerializable<{ x: IFluidHandle }, { AllowExtensionOf: IFluidHandle }>`).
+ *
+ * Note that `JsonSerializable<T>` does not protect against the following pitfalls
+ * when serializing with JSON.stringify():
+ *
+ * - Non-finite numbers (`NaN`, `+/-Infinity`) are coerced to `null`.
+ *
+ * - Prototypes and non-enumerable properties are lost.
+ *
+ * - `ArrayLike` types that are not arrays and are serialized as `{ length: number }`.
+ *
+ * - Getter and setters properties are lost. (Though appear supported.)
+ *
+ * - Functions with properties may be absent or the properties may be preserved
+ * depending on the runtime typo of the value. (If built via Object.assign the
+ * target member's type is preserved.) typeof =\> 'function' is lost whereas when
+ * typeof =\> 'object' the properties are preserved.
+ *
+ * - Sparse arrays are filled with `null`.
+ *
+ * Also, `JsonSerializable<T>` does not prevent the construction of circular references.
+ *
+ * Specifying `JsonSerializable<unknown>` or `JsonSerializable<any>` yields a type
+ * alias for {@link JsonTypeWith}`<never>` and should not be used if precise type
+ * safety is desired.
+ *
+ * Class instances are indistinguishable from general objects by type checking
+ * unless they have non-public members.
+ *
+ * - Unless `Option.IgnoreInaccessibleMembers` is used, types with non-public
+ * members will result in {@link SerializationErrorPerNonPublicProperties}.
+ * When `Option.IgnoreInaccessibleMembers` is `ignore-inaccessible-members`,
+ * non-public (non-function) members are preserved without error, but they are
+ * filtered away by the type filters and thus produce an incorrectly narrowed
+ * type compared to actual data. Though such a result may be customer desired.
+ *
+ * - An exception is made for classes  that are intersected with primitives
+ * (specifically `boolean`, `number`, * and `string`). In these cases, it is
+ * assumed that the class only exists as a type modifier and not as a value
+ * at runtime, and thus the class is permitted as no serialization is required.
+ *
+ * Perhaps a https://github.com/microsoft/TypeScript/issues/22677 fix will
+ * enable better support.
+ *
+ * @example Typical usage
+ *
+ * ```typescript
+ * function foo<T>(value: JsonSerializable<T>) { ... }
+ * ```
+ *
+ * @privateRemarks
+ * Upon recursion, the original type T is preserved intact. This is done to prevent
+ * infinite recursion and produces a technically incorrect result type. However, with
+ * proper use, that will never be an issue as any filtering of types will happen
+ * before T recursion.
+ *
+ * @beta
+ */
+export type JsonSerializable<
+	T,
+	Options extends JsonSerializableOptions = {
+		AllowExactly: [];
+		AllowExtensionOf: never;
+	},
+> = InternalUtilityTypes.JsonSerializableImpl<T, Options>;

package/src/jsonSerializationErrors.ts

@@ -0,0 +1,34 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/**
+ * Type resulting from {@link JsonSerializable} use given an array with
+ * `undefined` elements.
+ *
+ * @privateRemarks type is used over interface; so inspection of type
+ * result can be more informative than just the type name.
+ *
+ * @beta
+ * @system
+ */
+// eslint-disable-next-line @typescript-eslint/consistent-type-definitions
+export type SerializationErrorPerUndefinedArrayElement = {
+	"array serialization error": "undefined elements are not supported";
+};
+
+/**
+ * Type resulting from {@link JsonSerializable} use given a class with
+ * non-public properties.
+ *
+ * @privateRemarks type is used over interface; so inspection of type
+ * result can be more informative than just the type name.
+ *
+ * @beta
+ * @system
+ */
+// eslint-disable-next-line @typescript-eslint/consistent-type-definitions
+export type SerializationErrorPerNonPublicProperties = {
+	"object serialization error": "non-public properties are not supported";
+};

package/src/jsonType.ts

@@ -0,0 +1,37 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/**
+ * Type constraint for types that are likely encodable as JSON, deserializable from JSON,
+ * or have a custom alternate type.
+ *
+ * @remarks
+ * Use `JsonTypeWith<never>` for just JSON encodable/deserializable types.
+ * See {@link JsonSerializable} for encoding pitfalls.
+ *
+ * @privateRemarks
+ * Prefer using `JsonSerializable<unknown>` or `JsonDeserialized<unknown>` over this type that
+ * is an implementation detail.
+ *
+ * @beta
+ */
+export type JsonTypeWith<T> =
+	// eslint-disable-next-line @rushstack/no-new-null
+	| null
+	| boolean
+	| number
+	| string
+	| T
+	| { [key: string | number]: JsonTypeWith<T> }
+	| JsonTypeWith<T>[];
+
+/**
+ * Portion of {@link JsonTypeWith} that is an object (including array) and not null.
+ *
+ * @beta
+ */
+export type NonNullJsonObjectWith<T> =
+	| { [key: string | number]: JsonTypeWith<T> }
+	| JsonTypeWith<T>[];