@fluidframework/datastore-definitions 2.0.0-rc.2.0.2 → 2.0.0-rc.3.0.0

package/src/dataStoreRuntime.ts

@@ -3,23 +3,24 @@
  * Licensed under the MIT License.
  */
 
+import type { AttachState, IAudience, IDeltaManager } from "@fluidframework/container-definitions";
 import type {
+	FluidObject,
+	IDisposable,
 	IEvent,
 	IEventProvider,
-	IDisposable,
-	IFluidHandleContext,
 	IFluidHandle,
-	FluidObject,
+	IFluidHandleContext,
 	ITelemetryBaseLogger,
 } from "@fluidframework/core-interfaces";
-import type { IAudience, IDeltaManager, AttachState } from "@fluidframework/container-definitions";
+import type { IIdCompressor } from "@fluidframework/id-compressor";
 import type {
 	IDocumentMessage,
 	IQuorumClients,
 	ISequencedDocumentMessage,
 } from "@fluidframework/protocol-definitions";
 import type { IInboundSignalMessage } from "@fluidframework/runtime-definitions";
-import type { IIdCompressor } from "@fluidframework/id-compressor";
+
 import type { IChannel } from "./channel.js";
 
 /**
@@ -88,6 +89,21 @@ export interface IFluidDataStoreRuntime
 	 */
 	createChannel(id: string | undefined, type: string): IChannel;
 
+	/**
+	 * This api allows adding channel to data store after it was created.
+	 * This allows callers to cusmomize channel instance. For example, channel implementation
+	 * could have various modes of operations. As long as such configuration is provided at creation
+	 * and stored in summaries (such that all users of such channel instance behave the same), this
+	 * could be useful technique to have customized solutions without introducing a number of data structures
+	 * that all have same implementation.
+	 * This is also useful for scenarios like SharedTree DDS, where schema is provided at creation and stored in a summary.
+	 * The channel type should be present in the registry, otherwise the runtime would reject
+	 * the channel. The runtime used to create the channel object should be same to which
+	 * it is added.
+	 * @param channel - channel which needs to be added to the runtime.
+	 */
+	addChannel(channel: IChannel): void;
+
 	/**
 	 * Bind the channel with the data store runtime. If the runtime
 	 * is attached then we attach the channel to make it live.
@@ -104,10 +120,10 @@ export interface IFluidDataStoreRuntime
 	/**
 	 * Submits the signal to be sent to other clients.
 	 * @param type - Type of the signal.
-	 * @param content - Content of the signal.
+	 * @param content - Content of the signal. Should be a JSON serializable object or primitive.
 	 * @param targetClientId - When specified, the signal is only sent to the provided client id.
 	 */
-	submitSignal(type: string, content: any, targetClientId?: string): void;
+	submitSignal: (type: string, content: unknown, targetClientId?: string) => void;
 
 	/**
 	 * Returns the current quorum.

package/src/serializable.ts

@@ -4,6 +4,7 @@
  */
 
 import type { IFluidHandle } from "@fluidframework/core-interfaces";
+
 import type { Jsonable } from "./jsonable.js";
 
 /**

package/api-extractor-cjs.json

@@ -1,8 +0,0 @@
-{
-	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
-	"extends": "../../../common/build/build-common/api-extractor-base.cjs.primary.json",
-	// CJS is actually secondary; so, no report.
-	"apiReport": {
-		"enabled": false
-	}
-}

package/dist/datastore-definitions-alpha.d.ts

@@ -1,496 +0,0 @@
-/**
- * This library defines the interfaces required to implement and/or communicate
- * with a data store.
- *
- * @packageDocumentation
- */
-
-import type { AttachState } from '@fluidframework/container-definitions';
-import type { FluidObject } from '@fluidframework/core-interfaces';
-import type { IAudience } from '@fluidframework/container-definitions';
-import type { IDeltaManager } from '@fluidframework/container-definitions';
-import type { IDisposable } from '@fluidframework/core-interfaces';
-import type { IDocumentMessage } from '@fluidframework/protocol-definitions';
-import type { IEvent } from '@fluidframework/core-interfaces';
-import type { IEventProvider } from '@fluidframework/core-interfaces';
-import type { IExperimentalIncrementalSummaryContext } from '@fluidframework/runtime-definitions';
-import type { IFluidHandle } from '@fluidframework/core-interfaces';
-import type { IFluidHandleContext } from '@fluidframework/core-interfaces';
-import type { IFluidLoadable } from '@fluidframework/core-interfaces';
-import type { IGarbageCollectionData } from '@fluidframework/runtime-definitions';
-import type { IIdCompressor } from '@fluidframework/id-compressor';
-import type { IInboundSignalMessage } from '@fluidframework/runtime-definitions';
-import type { IQuorumClients } from '@fluidframework/protocol-definitions';
-import type { ISequencedDocumentMessage } from '@fluidframework/protocol-definitions';
-import type { ISummaryTreeWithStats } from '@fluidframework/runtime-definitions';
-import type { ITelemetryBaseLogger } from '@fluidframework/core-interfaces';
-import type { ITelemetryContext } from '@fluidframework/runtime-definitions';
-
-/**
- * @public
- */
-export declare interface IChannel extends IFluidLoadable {
-    /**
-     * A readonly identifier for the channel
-     */
-    readonly id: string;
-    readonly attributes: IChannelAttributes;
-    /**
-     * Generates summary of the channel synchronously. It is called when an `attach message`
-     * for a local channel is generated. In other words, when the channel is being attached
-     * to make it visible to other clients.
-     *
-     * @remarks
-     *
-     * Note: Since the Attach Summary is generated for local channels when making them visible to
-     * remote clients, they don't have any previous summaries to compare against. For this reason,
-     * the attach summary cannot contain summary handles (paths to sub-trees or blobs).
-     * It can, however, contain {@link @fluidframework/protocol-definitions#ISummaryAttachment}
-     * (handles to blobs uploaded async via the blob manager).
-     *
-     * @param fullTree - A flag indicating whether the attempt should generate a full
-     * summary tree without any handles for unchanged subtrees.
-     *
-     * Default: `false`
-     *
-     * @param trackState - An optimization for tracking state of objects across summaries. If the state
-     * of an object did not change since last successful summary, an
-     * {@link @fluidframework/protocol-definitions#ISummaryHandle} can be used
-     * instead of re-summarizing it. If this is `false`, the expectation is that you should never
-     * send an `ISummaryHandle`, since you are not expected to track state.
-     *
-     * Note: The goal is to remove the trackState and automatically decided whether the
-     * handles will be used or not: {@link https://github.com/microsoft/FluidFramework/issues/10455}
-     *
-     * Default: `false`
-     *
-     * @param telemetryContext - See {@link @fluidframework/runtime-definitions#ITelemetryContext}.
-     *
-     * @returns A summary capturing the current state of the channel.
-     */
-    getAttachSummary(fullTree?: boolean, trackState?: boolean, telemetryContext?: ITelemetryContext): ISummaryTreeWithStats;
-    /**
-     * Generates summary of the channel asynchronously.
-     * This should not be called where the channel can be modified while summarization is in progress.
-     *
-     * @param fullTree - flag indicating whether the attempt should generate a full
-     * summary tree without any handles for unchanged subtrees. It should only be set to true when generating
-     * a summary from the entire container.
-     *
-     * Default: `false`
-     *
-     * @param trackState - An optimization for tracking state of objects across summaries. If the state
-     * of an object did not change since last successful summary, an
-     * {@link @fluidframework/protocol-definitions#ISummaryHandle} can be used
-     * instead of re-summarizing it. If this is `false`, the expectation is that you should never
-     * send an `ISummaryHandle`, since you are not expected to track state.
-     *
-     * Default: `false`
-     *
-     * Note: The goal is to remove the trackState and automatically decided whether the
-     * handles will be used or not: {@link https://github.com/microsoft/FluidFramework/issues/10455}
-     *
-     * @param telemetryContext - See {@link @fluidframework/runtime-definitions#ITelemetryContext}.
-     *
-     * @returns A summary capturing the current state of the channel.
-     */
-    summarize(fullTree?: boolean, trackState?: boolean, telemetryContext?: ITelemetryContext, incrementalSummaryContext?: IExperimentalIncrementalSummaryContext): Promise<ISummaryTreeWithStats>;
-    /**
-     * Checks if the channel is attached to storage.
-     * @returns True iff the channel is attached.
-     */
-    isAttached(): boolean;
-    /**
-     * Enables the channel to send and receive ops.
-     * @param services - The services to connect to.
-     */
-    connect(services: IChannelServices): void;
-    /**
-     * Returns the GC data for this channel. It contains a list of GC nodes that contains references to
-     * other GC nodes.
-     * @param fullGC - true to bypass optimizations and force full generation of GC data.
-     */
-    getGCData(fullGC?: boolean): IGarbageCollectionData;
-}
-
-/**
- * Represents the attributes of a channel/DDS.
- * @public
- */
-export declare interface IChannelAttributes {
-    /**
-     * 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;
-    /**
-     * The package version of the code of the DDS, for debug only
-     */
-    readonly packageVersion?: string;
-}
-
-/**
- * Definitions of a channel factory.
- *
- * @remarks
- *
- * The runtime must be able to produce "channels" of the correct in-memory object type for the collaborative session.
- * Here "channels" are typically distributed data structures (DDSs).
- *
- * The runtime will consult with a registry of such factories during
- * {@link https://fluidframework.com/docs/build/containers/ | Container} load and when receiving "attach" operations
- * (ops), which indicate a new instance of a channel being introduced to the collaboration session, to produce the
- * appropriate in-memory object.
- *
- * Factories follow a common model but enable custom behavior.
- *
- * @example
- *
- * If a collaboration includes a {@link https://fluidframework.com/docs/data-structures/map/ | SharedMap},
- * the collaborating clients will need to have access to a factory that can produce the `SharedMap` object.
- *
- * @privateRemarks
- * TChannel extends IFluidLoadable instead of TChannel since doing so enables LoadableObjectClass to be covariant over its input parameter.
- * This means that code like fluid-static's `InitialObjects` can be simple and type safe and LoadableObjectClass<any> is not needed.
- * This approach (not requiring TChannel to extend IChannel) also makes it possible for SharedObject's public interfaces to not include IChannel if desired
- * (while still requiring the implementation to implement it).
- *
- * @public
- */
-export declare interface IChannelFactory<out TChannel extends IFluidLoadable = IFluidLoadable> {
-    /**
-     * String representing the type of the factory.
-     */
-    readonly type: string;
-    /**
-     * Attributes of the channel.
-     */
-    readonly attributes: IChannelAttributes;
-    /**
-     * Loads the given channel. This call is only ever invoked internally as the only thing
-     * that is ever directly loaded is the document itself. Load will then only be called on documents that
-     * were created and added to a channel.
-     * @param runtime - Data store runtime containing state/info/helper methods about the data store.
-     * @param id - ID of the channel.
-     * @param services - Services to read objects at a given path using the delta connection.
-     * @param channelAttributes - The attributes for the the channel to be loaded.
-     * @returns The loaded object
-     *
-     * @privateRemarks
-     * Thought: should the storage object include the version information and limit access to just files
-     * for the given object? The latter seems good in general. But both are probably good things. We then just
-     * need a way to allow the document to provide later storage for the object.
-     */
-    load(runtime: IFluidDataStoreRuntime, id: string, services: IChannelServices, channelAttributes: Readonly<IChannelAttributes>): Promise<TChannel & IChannel>;
-    /**
-     * Creates a local version of the channel.
-     * Calling attach on the object later will insert it into the object stream.
-     * @param runtime - The runtime the new object will be associated with
-     * @param id - The unique ID of the new object
-     * @returns The newly created object.
-     *
-     * @privateRemarks
-     * NOTE here - When we attach we need to submit all the pending ops prior to actually doing the attach
-     * for consistency.
-     */
-    create(runtime: IFluidDataStoreRuntime, id: string): TChannel & IChannel;
-}
-
-/**
- * Storage services to read the objects at a given path using the given delta connection.
- * @public
- */
-export declare interface IChannelServices {
-    deltaConnection: IDeltaConnection;
-    objectStorage: IChannelStorageService;
-}
-
-/**
- * Storage services to read the objects at a given path.
- * @public
- */
-export declare interface IChannelStorageService {
-    /**
-     * Reads the object contained at the given path. Returns a buffer representation for the object.
-     */
-    readBlob(path: string): Promise<ArrayBufferLike>;
-    /**
-     * Determines if there is an object contained at the given path.
-     */
-    contains(path: string): Promise<boolean>;
-    /**
-     * Lists the blobs that exist at a specific path.
-     */
-    list(path: string): Promise<string[]>;
-}
-
-/**
- * Interface to represent a connection to a delta notification stream.
- * @public
- */
-export declare interface IDeltaConnection {
-    connected: boolean;
-    /**
-     * Send new messages to the server.
-     * @param messageContent - The content of the message to be sent.
-     * @param localOpMetadata - The local metadata associated with the message. This is kept locally by the runtime
-     * and not sent to the server. It will be provided back when this message is acknowledged by the server. It will
-     * also be provided back when asked to resubmit the message.
-     */
-    submit(messageContent: any, localOpMetadata: unknown): void;
-    /**
-     * Attaches a message handler to the delta connection
-     */
-    attach(handler: IDeltaHandler): void;
-    /**
-     * Indicates that the channel is dirty and needs to be part of the summary. It is called by a SharedSummaryBlock
-     * that needs to be part of the summary but does not generate ops.
-     */
-    dirty(): void;
-    /**
-     * @deprecated There is no replacement for this, its functionality is no longer needed at this layer.
-     * It will be removed in a future release, sometime after 2.0.0-internal.8.0.0
-     *
-     * Called when a new outbound reference is added to another node. This is used by garbage collection to identify
-     * all references added in the system.
-     * @param srcHandle - The handle of the node that added the reference.
-     * @param outboundHandle - The handle of the outbound node that is referenced.
-     */
-    addedGCOutboundReference?(srcHandle: IFluidHandle, outboundHandle: IFluidHandle): void;
-}
-
-/**
- * Handler provided by shared data structure to process requests from the runtime.
- * @public
- */
-export declare interface IDeltaHandler {
-    /**
-     * Processes the op.
-     * @param message - The message to process
-     * @param local - Whether the message originated from the local client
-     * @param localOpMetadata - For local client messages, this is the metadata that was submitted with the message.
-     * For messages from a remote client, this will be undefined.
-     */
-    process: (message: ISequencedDocumentMessage, local: boolean, localOpMetadata: unknown) => void;
-    /**
-     * State change events to indicate changes to the delta connection
-     * @param connected - true if connected, false otherwise
-     */
-    setConnectionState(connected: boolean): void;
-    /**
-     * Called when the runtime asks the client to resubmit an op. This may be because the Container reconnected and
-     * this op was not acked.
-     * The client can choose to resubmit the same message, submit different / multiple messages or not submit anything
-     * at all.
-     * @param message - The original message that was submitted.
-     * @param localOpMetadata - The local metadata associated with the original message.
-     */
-    reSubmit(message: any, localOpMetadata: unknown): void;
-    /**
-     * Apply changes from an op just as if a local client has made the change,
-     * including submitting the op. Used when rehydrating an attached container
-     * with pending changes. This prepares the SharedObject for seeing an ACK
-     * for the op or resubmitting the op upon reconnection.
-     * @param content - Contents of a stashed op.
-     * @returns Should return void.
-     *
-     * @privateRemarks
-     * This interface is undergoing changes. Right now it support both the old
-     * flow, where just local metadata is returned, and a more ergonomic flow
-     * where operations are applied just like local edits, including
-     * submission of the op if attached. Soon the old flow will be removed
-     * and only the new flow will be supported.
-     */
-    applyStashedOp(message: any): void;
-    /**
-     * Revert a local op.
-     * @param message - The original message that was submitted.
-     * @param localOpMetadata - The local metadata associated with the original message.
-     */
-    rollback?(message: any, localOpMetadata: unknown): void;
-}
-
-/**
- * Represents the runtime for the data store. Contains helper functions/state of the data store.
- * @public
- */
-export declare interface IFluidDataStoreRuntime extends IEventProvider<IFluidDataStoreRuntimeEvents>, IDisposable {
-    readonly id: string;
-    readonly IFluidHandleContext: IFluidHandleContext;
-    readonly rootRoutingContext: IFluidHandleContext;
-    readonly channelsRoutingContext: IFluidHandleContext;
-    readonly objectsRoutingContext: IFluidHandleContext;
-    readonly options: Record<string | number, any>;
-    readonly deltaManager: IDeltaManager<ISequencedDocumentMessage, IDocumentMessage>;
-    readonly clientId: string | undefined;
-    readonly connected: boolean;
-    readonly logger: ITelemetryBaseLogger;
-    /**
-     * 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;
-    /**
-     * 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>;
-}
-
-/**
- * Events emitted by {@link IFluidDataStoreRuntime}.
- * @public
- */
-export declare interface IFluidDataStoreRuntimeEvents extends IEvent {
-    (event: "disconnected" | "dispose" | "attaching" | "attached", listener: () => void): any;
-    (event: "op", listener: (message: ISequencedDocumentMessage) => void): any;
-    (event: "signal", listener: (message: IInboundSignalMessage, local: boolean) => void): any;
-    (event: "connected", listener: (clientId: string) => void): any;
-}
-
-/**
- * @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 declare 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.
- *
- * @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 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).
- *
- * 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.
- *
- * - `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<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
- *
- * ```typescript
- * function foo<T>(value: Jsonable<T>) { ... }
- * ```
- * @alpha
- */
-export declare type Jsonable<T, TReplaced = never> = boolean extends (T extends never ? true : false) ? JsonableTypeWith<TReplaced> : unknown extends T ? JsonableTypeWith<TReplaced> : T extends undefined | null | boolean | number | string | TReplaced ? T : Extract<T, Function> extends never ? T extends object ? T extends (infer U)[] ? Jsonable<U, TReplaced>[] : {
-    [K in keyof T]: Extract<K, symbol> extends never ? Jsonable<T[K], TReplaced> : never;
-} : never : never;
-
-/**
- * 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 declare type JsonableTypeWith<T> = undefined | null | boolean | number | string | T | Internal_InterfaceOfJsonableTypesWith<T> | ArrayLike<JsonableTypeWith<T>>;
-
-/**
- * Used to constrain a type 'T' to types that Fluid can intrinsically serialize.  Produces a
- * compile-time error if `T` contains non-serializable members.
- *
- * @remarks
- * See Jsonable for caveats regarding serialization of `undefined`, non-finite numbers,
- * and circular references.
- *
- * Important: `T extends Serializable<T>` is generally incorrect.
- * (Any value of `T` extends the serializable subset of itself.)
- *
- * @example Typical usage
- *
- * ```typescript
- * function serialize<T>(value: Serializable<T>) { ... }
- * ```
- * @alpha
- */
-export declare type Serializable<T> = Jsonable<T, IFluidHandle>;
-
-export { }