@fluidframework/datastore-definitions 1.4.0-115997 → 2.0.0-dev-rc.1.0.0.224419

package/src/dataStoreRuntime.ts

@@ -3,113 +3,134 @@
  * Licensed under the MIT License.
  */
 
-import { IDisposable, IEvent, IEventProvider, ITelemetryLogger } from "@fluidframework/common-definitions";
 import {
-    IFluidHandleContext,
-    IFluidRouter,
-    IFluidHandle,
+	IEvent,
+	IEventProvider,
+	ITelemetryLogger,
+	IDisposable,
+	IFluidHandleContext,
+	IFluidHandle,
+	FluidObject,
 } from "@fluidframework/core-interfaces";
 import {
-    IAudience,
-    IDeltaManager,
-    AttachState,
-    ILoaderOptions,
+	IAudience,
+	IDeltaManager,
+	AttachState,
+	ILoaderOptions,
 } from "@fluidframework/container-definitions";
 import {
-    IDocumentMessage,
-    IQuorumClients,
-    ISequencedDocumentMessage,
+	IDocumentMessage,
+	IQuorumClients,
+	ISequencedDocumentMessage,
 } from "@fluidframework/protocol-definitions";
-import { IInboundSignalMessage, IProvideFluidDataStoreRegistry } from "@fluidframework/runtime-definitions";
-import { IChannel } from ".";
+import { IInboundSignalMessage } from "@fluidframework/runtime-definitions";
+import { IIdCompressor } from "@fluidframework/id-compressor";
+import { IChannel } from "./channel";
 
+/**
+ * Events emitted by {@link IFluidDataStoreRuntime}.
+ * @public
+ */
 export interface IFluidDataStoreRuntimeEvents extends IEvent {
-    (
-        // eslint-disable-next-line @typescript-eslint/unified-signatures
-        event: "disconnected" | "dispose" | "attaching" | "attached",
-        listener: () => void,
-    );
-    (event: "op", listener: (message: ISequencedDocumentMessage) => void);
-    (event: "signal", listener: (message: IInboundSignalMessage, local: boolean) => void);
-    (event: "connected", listener: (clientId: string) => void);
+	(event: "disconnected" | "dispose" | "attaching" | "attached", listener: () => void);
+	(event: "op", listener: (message: ISequencedDocumentMessage) => void);
+	(event: "signal", listener: (message: IInboundSignalMessage, local: boolean) => void);
+	(event: "connected", listener: (clientId: string) => void);
 }
 
 /**
  * Represents the runtime for the data store. Contains helper functions/state of the data store.
+ * @public
  */
-export interface IFluidDataStoreRuntime extends
-    IFluidRouter,
-    IEventProvider<IFluidDataStoreRuntimeEvents>,
-    IDisposable,
-    Partial<IProvideFluidDataStoreRegistry> {
-
-    readonly id: string;
-
-    readonly IFluidHandleContext: IFluidHandleContext;
-
-    readonly rootRoutingContext: IFluidHandleContext;
-    readonly channelsRoutingContext: IFluidHandleContext;
-    readonly objectsRoutingContext: IFluidHandleContext;
-
-    readonly options: ILoaderOptions;
-
-    readonly deltaManager: IDeltaManager<ISequencedDocumentMessage, IDocumentMessage>;
-
-    readonly clientId: string | undefined;
-
-    readonly connected: boolean;
-
-    readonly logger: ITelemetryLogger;
-
-    /**
-     * Indicates the attachment state of the data store to a host service.
-     */
-    readonly attachState: AttachState;
-
-    /**
-     * Returns the channel with the given id
-     */
-    getChannel(id: string): Promise<IChannel>;
-
-    /**
-     * Creates a new channel of the given type.
-     * @param id - ID of the channel to be created.  A unique ID will be generated if left undefined.
-     * @param type - Type of the channel.
-     */
-    createChannel(id: string | undefined, type: string): IChannel;
-
-    /**
-     * Bind the channel with the data store runtime. If the runtime
-     * is attached then we attach the channel to make it live.
-     */
-    bindChannel(channel: IChannel): void;
-
-    // Blob related calls
-    /**
-     * Api to upload a blob of data.
-     * @param blob - blob to be uploaded.
-     */
-    uploadBlob(blob: ArrayBufferLike): Promise<IFluidHandle<ArrayBufferLike>>;
-
-    /**
-     * Submits the signal to be sent to other clients.
-     * @param type - Type of the signal.
-     * @param content - Content of the signal.
-     */
-    submitSignal(type: string, content: any): void;
-
-    /**
-     * Returns the current quorum.
-     */
-    getQuorum(): IQuorumClients;
-
-    /**
-     * Returns the current audience.
-     */
-    getAudience(): IAudience;
-
-    /**
-     * Resolves when a local data store is attached.
-     */
-    waitAttached(): Promise<void>;
+export interface IFluidDataStoreRuntime
+	extends IEventProvider<IFluidDataStoreRuntimeEvents>,
+		IDisposable {
+	readonly id: string;
+
+	readonly IFluidHandleContext: IFluidHandleContext;
+
+	readonly rootRoutingContext: IFluidHandleContext;
+	readonly channelsRoutingContext: IFluidHandleContext;
+	readonly objectsRoutingContext: IFluidHandleContext;
+
+	readonly options: ILoaderOptions;
+
+	readonly deltaManager: IDeltaManager<ISequencedDocumentMessage, IDocumentMessage>;
+
+	readonly clientId: string | undefined;
+
+	readonly connected: boolean;
+
+	readonly logger: ITelemetryLogger;
+
+	/**
+	 * Indicates the attachment state of the data store to a host service.
+	 */
+	readonly attachState: AttachState;
+
+	readonly idCompressor?: IIdCompressor;
+
+	/**
+	 * Returns the channel with the given id
+	 */
+	getChannel(id: string): Promise<IChannel>;
+
+	/**
+	 * Invokes the given callback and expects that no ops are submitted
+	 * until execution finishes. If an op is submitted, an error will be raised.
+	 *
+	 * Can be disabled by feature gate `Fluid.ContainerRuntime.DisableOpReentryCheck`
+	 *
+	 * @param callback - the callback to be invoked
+	 */
+	ensureNoDataModelChanges<T>(callback: () => T): T;
+
+	/**
+	 * Creates a new channel of the given type.
+	 * @param id - ID of the channel to be created.  A unique ID will be generated if left undefined.
+	 * @param type - Type of the channel.
+	 */
+	createChannel(id: string | undefined, type: string): IChannel;
+
+	/**
+	 * Bind the channel with the data store runtime. If the runtime
+	 * is attached then we attach the channel to make it live.
+	 */
+	bindChannel(channel: IChannel): void;
+
+	// Blob related calls
+	/**
+	 * Api to upload a blob of data.
+	 * @param blob - blob to be uploaded.
+	 */
+	uploadBlob(blob: ArrayBufferLike, signal?: AbortSignal): Promise<IFluidHandle<ArrayBufferLike>>;
+
+	/**
+	 * Submits the signal to be sent to other clients.
+	 * @param type - Type of the signal.
+	 * @param content - Content of the signal.
+	 * @param targetClientId - When specified, the signal is only sent to the provided client id.
+	 */
+	submitSignal(type: string, content: any, targetClientId?: string): void;
+
+	/**
+	 * Returns the current quorum.
+	 */
+	getQuorum(): IQuorumClients;
+
+	/**
+	 * Returns the current audience.
+	 */
+	getAudience(): IAudience;
+
+	/**
+	 * Resolves when a local data store is attached.
+	 */
+	waitAttached(): Promise<void>;
+
+	/**
+	 * Exposes a handle to the root object / entryPoint of the data store. Use this as the primary way of interacting
+	 * with it.
+	 */
+	readonly entryPoint: IFluidHandle<FluidObject>;
 }

package/src/index.ts

@@ -4,14 +4,21 @@
  */
 
 /**
-* This package defines the interfaces required to implement and/or communicate
-* with a data store.
-*
-* @packageDocumentation
-*/
+ * This library defines the interfaces required to implement and/or communicate
+ * with a data store.
+ *
+ * @packageDocumentation
+ */
 
-export * from "./channel";
-export * from "./dataStoreRuntime";
-export * from "./jsonable";
-export * from "./serializable";
-export * from "./storage";
+export {
+	IChannel,
+	IChannelFactory,
+	IChannelServices,
+	IChannelStorageService,
+	IDeltaConnection,
+	IDeltaHandler,
+} from "./channel";
+export { IFluidDataStoreRuntime, IFluidDataStoreRuntimeEvents } from "./dataStoreRuntime";
+export type { Jsonable, JsonableTypeWith, Internal_InterfaceOfJsonableTypesWith } from "./jsonable";
+export { Serializable } from "./serializable";
+export { IChannelAttributes } from "./storage";

package/src/jsonable.ts

@@ -3,6 +3,43 @@
  * Licensed under the MIT License.
  */
 
+/**
+ * Type constraint for types that are likely serializable as JSON or have a custom
+ * alternate type.
+ *
+ * @remarks
+ * Use `JsonableTypeWith<never>` for just JSON serializable types.
+ * See {@link Jsonable} for serialization pitfalls.
+ *
+ * @privateRemarks
+ * Perfer using `Jsonable<unknown>` over this type that is an implementation detail.
+ * @alpha
+ */
+export type JsonableTypeWith<T> =
+	| undefined
+	| null
+	| boolean
+	| number
+	| string
+	| T
+	| Internal_InterfaceOfJsonableTypesWith<T>
+	| ArrayLike<JsonableTypeWith<T>>;
+
+/**
+ * @remarks
+ * This type is a kludge and not intended for general use.
+ *
+ * @privateRemarks
+ * Internal type testing for compatibility uses TypeOnly filter which cannot handle recursive "pure" types.
+ * This interface along with ArrayLike above avoids pure type recursion issues, but introduces a limitation on
+ * the ability of {@link Jsonable} to detect array-like types that are not handled naively ({@link JSON.stringify}).
+ * The TypeOnly filter is not useful for {@link JsonableTypeWith}; so, if type testing improves, this can be removed.
+ * @alpha
+ */
+export interface Internal_InterfaceOfJsonableTypesWith<T> {
+	[index: string | number]: JsonableTypeWith<T>;
+}
+
 /**
  * Used to constrain a type `T` to types that are serializable as JSON.
  * Produces a compile-time error if `T` contains non-Jsonable members.
@@ -10,42 +47,62 @@
  * @remarks
  * Note that this does NOT prevent using 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 an a value typed with json compatible
+ * This means that one can, for example, pass in a value typed with json compatible
  * interface into this function,
  * that could actually be a class with lots on non-json compatible fields and methods.
  *
  * Important: `T extends Jsonable<T>` is incorrect (does not even compile).
- * `T extends Jsonable` is also incorrect since `Jsonable` is just `any` and thus applies no constraint at all.
  *
  * The optional 'TReplaced' parameter may be used to permit additional leaf types to support
  * situations where a `replacer` is used to handle special values (e.g., `Jsonable<{ x: IFluidHandle }, IFluidHandle>`).
  *
  * Note that `Jsonable<T>` does not protect against the following pitfalls when serializing with JSON.stringify():
  *
- *  - `undefined` properties on objects are omitted (i.e., properties become undefined instead of equal to undefined).
- *  - When `undefined` appears as the root object or as an array element it is coerced to `null`.
- *  - Non-finite numbers (`NaN`, `+/-Infinity`) are also coerced to `null`.
- *  - prototypes and non-enumerable properties are lost.
+ * - `undefined` properties on objects are omitted (i.e., properties become undefined instead of equal to undefined).
+ *
+ * - When `undefined` appears as the root object or as an array element it is coerced to `null`.
+ *
+ * - Non-finite numbers (`NaN`, `+/-Infinity`) are also coerced to `null`.
+ *
+ * - prototypes and non-enumerable properties are lost.
+ *
+ * - `ArrayLike` types that are not arrays and are serialized as `{ length: number }`.
  *
  * Also, `Jsonable<T>` does not prevent the construction of circular references.
  *
- * Using `Jsonable` (with no type parameters) or `Jsonable<any>` is just a type alias for `any`
- * and should not be used if type safety is desired.
+ * Using `Jsonable<unknown>` or `Jsonable<any>` is a type alias for
+ * {@link JsonableTypeWith}`<never>` and should not be used if precise type safety is desired.
+ *
+ * @example Typical usage
  *
- * @example
- * Typical usage:
- * ```ts
- *      function foo<T>(value: Jsonable<T>) { ... }
+ * ```typescript
+ * function foo<T>(value: Jsonable<T>) { ... }
  * ```
+ * @alpha
  */
-export type Jsonable<T = any, TReplaced = void> =
-    T extends undefined | null | boolean | number | string | TReplaced
-        ? T
-        // eslint-disable-next-line @typescript-eslint/ban-types
-        : Extract<T, Function> extends never
-            ? {
-                [K in keyof T]: Extract<K, symbol> extends never
-                    ? Jsonable<T[K], TReplaced>
-                    : never
-            }
-            : never;
+export type Jsonable<T, TReplaced = never> = /* test for 'any' */ boolean extends (
+	T extends never ? true : false
+)
+	? /* 'any' => */ JsonableTypeWith<TReplaced>
+	: /* test for 'unknown' */ unknown extends T
+	? /* 'unknown' => */ JsonableTypeWith<TReplaced>
+	: /* test for Jsonable primitive types */ T extends
+			| undefined /* is not serialized */
+			| null
+			| boolean
+			| number
+			| string
+			| TReplaced
+	? /* primitive types => */ T
+	: // eslint-disable-next-line @typescript-eslint/ban-types
+	/* test for not a function */ Extract<T, Function> extends never
+	? /* not a function =>  => test for object */ T extends object
+		? /* object => test for array */ T extends (infer U)[] // prefer ArrayLike test to catch non-array array-like types
+			? /* array => */ Jsonable<U, TReplaced>[]
+			: /* property bag => */ {
+					[K in keyof T]: Extract<K, symbol> extends never
+						? Jsonable<T[K], TReplaced>
+						: never;
+			  }
+		: /* not an object => */ never
+	: /* function => */ never;

package/src/serializable.ts

@@ -17,10 +17,11 @@ import { Jsonable } from "./jsonable";
  * Important: `T extends Serializable<T>` is generally incorrect.
  * (Any value of `T` extends the serializable subset of itself.)
  *
- * @example
- * Typical usage:
+ * @example Typical usage
+ *
  * ```typescript
- *      function serialize<T>(value: Serializable<T>) { ... }
+ * function serialize<T>(value: Serializable<T>) { ... }
  * ```
+ * @alpha
  */
-export type Serializable<T = any> = Jsonable<T, IFluidHandle>;
+export type Serializable<T> = Jsonable<T, IFluidHandle>;

package/src/storage.ts

@@ -5,21 +5,22 @@
 
 /**
  * Represents the attributes of a channel/DDS.
+ * @public
  */
 export interface IChannelAttributes {
-    /**
-     * Type name of the DDS for factory look up with ISharedObjectRegistry
-     */
-    readonly type: string;
+	/**
+	 * Type name of the DDS for factory look up with ISharedObjectRegistry
+	 */
+	readonly type: string;
 
-    /**
-     * Format version of the snapshot
-     * Currently, only use to display a debug message if the version is incompatible
-     */
-    readonly snapshotFormatVersion: string;
+	/**
+	 * Format version of the snapshot
+	 * Currently, only use to display a debug message if the version is incompatible
+	 */
+	readonly snapshotFormatVersion: string;
 
-    /**
-     * The package version of the code of the DDS, for debug only
-     */
-    readonly packageVersion?: string;
+	/**
+	 * The package version of the code of the DDS, for debug only
+	 */
+	readonly packageVersion?: string;
 }

package/tsconfig.json

@@ -1,14 +1,12 @@
 {
-    "extends": "@fluidframework/build-common/ts-common-config.json",
-    "exclude": [
-        "src/test/**/*"
-    ],
-    "compilerOptions": {
-        "rootDir": "./src",
-        "outDir": "./dist",
-        "composite": true,
-    },
-    "include": [
-        "src/**/*"
-    ]
+	"extends": [
+		"../../../common/build/build-common/tsconfig.base.json",
+		"../../../common/build/build-common/tsconfig.esm-only.json",
+	],
+	"include": ["src/**/*"],
+	"exclude": ["src/test/**/*"],
+	"compilerOptions": {
+		"rootDir": "./src",
+		"outDir": "./dist",
+	},
 }

package/.eslintrc.js

@@ -1,13 +0,0 @@
-/*!
- * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
- * Licensed under the MIT License.
- */
-
-module.exports = {
-    "parserOptions": {
-        "project": ["./tsconfig.json", "./src/test/tsconfig.json"]
-    },
-    "extends": [
-        "@fluidframework/eslint-config-fluid"
-    ]
-}