@fluidframework/shared-object-base 2.0.0-rc.2.0.1 → 2.0.0-rc.3.0.0

package/src/sharedObject.ts

@@ -3,38 +3,42 @@
  * Licensed under the MIT License.
  */
 
-import { v4 as uuid } from "uuid";
-import { IFluidHandle, ITelemetryBaseProperties } from "@fluidframework/core-interfaces";
-import {
-	ITelemetryLoggerExt,
-	createChildLogger,
-	DataProcessingError,
-	EventEmitterWithErrorHandling,
-	loggerToMonitoringContext,
-	MonitoringContext,
-	SampledTelemetryHelper,
-	tagCodeArtifacts,
-} from "@fluidframework/telemetry-utils";
-import { assert } from "@fluidframework/core-utils";
 import { EventEmitterEventType } from "@fluid-internal/client-utils";
 import { AttachState } from "@fluidframework/container-definitions";
+import { IFluidHandle, ITelemetryBaseProperties } from "@fluidframework/core-interfaces";
+import { assert } from "@fluidframework/core-utils/internal";
 import {
 	IChannelAttributes,
-	IFluidDataStoreRuntime,
-	IChannelStorageService,
+	type IChannelFactory,
 	IChannelServices,
+	IChannelStorageService,
+	IFluidDataStoreRuntime,
 } from "@fluidframework/datastore-definitions";
 import { ISequencedDocumentMessage } from "@fluidframework/protocol-definitions";
 import {
+	IExperimentalIncrementalSummaryContext,
 	IGarbageCollectionData,
 	ISummaryTreeWithStats,
 	ITelemetryContext,
+} from "@fluidframework/runtime-definitions";
+import {
 	blobCountPropertyName,
 	totalBlobSizePropertyName,
-	IExperimentalIncrementalSummaryContext,
-} from "@fluidframework/runtime-definitions";
-import { FluidSerializer, IFluidSerializer } from "./serializer.js";
+} from "@fluidframework/runtime-definitions/internal";
+import { ITelemetryLoggerExt } from "@fluidframework/telemetry-utils";
+import {
+	DataProcessingError,
+	EventEmitterWithErrorHandling,
+	MonitoringContext,
+	SampledTelemetryHelper,
+	createChildLogger,
+	loggerToMonitoringContext,
+	tagCodeArtifacts,
+} from "@fluidframework/telemetry-utils/internal";
+import { v4 as uuid } from "uuid";
+
 import { SharedObjectHandle } from "./handle.js";
+import { FluidSerializer, IFluidSerializer } from "./serializer.js";
 import { SummarySerializer } from "./summarySerializer.js";
 import { ISharedObject, ISharedObjectEvents } from "./types.js";
 import { makeHandlesSerializable, parseHandles } from "./utils.js";
@@ -774,3 +778,52 @@ export abstract class SharedObject<
 		telemetryContext?.set(this.telemetryContextPrefix, propertyName, prevTotal + incrementBy);
 	}
 }
+
+/**
+ * Defines a kind of shared object.
+ * Used in containers to register a shared object implementation, and to create new instances of a given type of shared object.
+ * @public
+ */
+export interface ISharedObjectKind<TSharedObject> {
+	/**
+	 * Get a factory which can be used by the Fluid Framework to programmatically instantiate shared objects within containers.
+	 * @remarks
+	 * The produced factory is intended for use with the FluidDataStoreRegistry and is used by the Fluid Framework to instantiate already existing Channels.
+	 * To create new shared objects use:
+	 *
+	 * - {@link @fluidframework/fluid-static#IFluidContainer.create} if using `@fluidframework/fluid-static`, for example via `@fluidframework/azure-client`.
+	 *
+	 * - {@link ISharedObjectKind.create} if using a custom container definitions (and thus not using {@link @fluidframework/fluid-static#IFluidContainer}).
+	 *
+	 * @privateRemarks
+	 * TODO:
+	 * Many tests use this and can't use {@link ISharedObjectKind.create}.
+	 * The docs should make it clear why that's ok, and why {@link ISharedObjectKind.create} isn't in such a way that when reading non app code (like tests in this package)
+	 * someone can tell if the wrong one is being used without running it and seeing if it works.
+	 */
+	getFactory(): IChannelFactory<TSharedObject>;
+
+	/**
+	 * Create a shared object.
+	 * @param runtime - The data store runtime that the new shared object belongs to.
+	 * @param id - Optional name of the shared object.
+	 * @returns Newly created shared object.
+	 *
+	 * @example
+	 * To create a `SharedTree`, call the static create method:
+	 *
+	 * ```typescript
+	 * const myTree = SharedTree.create(this.runtime, id);
+	 * ```
+	 * @remarks
+	 * If using `@fluidframework/fluid-static` (for example via `@fluidframework/azure-client`), use {@link @fluidframework/fluid-static#IFluidContainer.create} instead of calling this directly.
+	 *
+	 * @privateRemarks
+	 * TODO:
+	 * This returns null when used with MockFluidDataStoreRuntime, so its unclear how tests should create DDS instances unless using `RootDataObject.create` (which most tests shouldn't to minimize dependencies).
+	 * In practice tests either avoid mock runtimes, use getFactory(), or call the DDS constructor directly. It is unclear (from docs) how getFactory().create differs but it does not rely on runtime.createChannel so it works with mock runtimes.
+	 * TODO:
+	 * See note on ISharedObjectKind.getFactory.
+	 */
+	create(runtime: IFluidDataStoreRuntime, id?: string): TSharedObject;
+}

package/src/summarySerializer.ts

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

package/src/utils.ts

@@ -5,7 +5,8 @@
 
 import { IFluidHandle } from "@fluidframework/core-interfaces";
 import { ISummaryTreeWithStats } from "@fluidframework/runtime-definitions";
-import { SummaryTreeBuilder } from "@fluidframework/runtime-utils";
+import { SummaryTreeBuilder } from "@fluidframework/runtime-utils/internal";
+
 import { IFluidSerializer } from "./serializer.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/shared-object-base-alpha.d.ts

@@ -1,427 +0,0 @@
-import { EventEmitterEventType } from '@fluid-internal/client-utils';
-import { EventEmitterWithErrorHandling } from '@fluidframework/telemetry-utils';
-import { IChannel } from '@fluidframework/datastore-definitions';
-import { IChannelAttributes } from '@fluidframework/datastore-definitions';
-import { IChannelServices } from '@fluidframework/datastore-definitions';
-import { IChannelStorageService } from '@fluidframework/datastore-definitions';
-import { IErrorEvent } from '@fluidframework/core-interfaces';
-import { IEventProvider } from '@fluidframework/core-interfaces';
-import { IEventThisPlaceHolder } from '@fluidframework/core-interfaces';
-import { IExperimentalIncrementalSummaryContext } from '@fluidframework/runtime-definitions';
-import { IFluidDataStoreRuntime } from '@fluidframework/datastore-definitions';
-import { IFluidHandle } from '@fluidframework/core-interfaces';
-import { IFluidHandleContext } from '@fluidframework/core-interfaces';
-import { IGarbageCollectionData } from '@fluidframework/runtime-definitions';
-import { ISequencedDocumentMessage } from '@fluidframework/protocol-definitions';
-import { ISummaryTreeWithStats } from '@fluidframework/runtime-definitions';
-import { ITelemetryContext } from '@fluidframework/runtime-definitions';
-import { ITelemetryLoggerExt } from '@fluidframework/telemetry-utils';
-
-/* Excluded from this release type: bindHandles */
-
-/* Excluded from this release type: createSingleBlobSummary */
-
-/* Excluded from this release type: FluidSerializer */
-
-/**
- * @public
- */
-export declare interface IFluidSerializer {
-    /**
-     * Given a mostly-plain object that may have handle objects embedded within, will return a fully-plain object
-     * where any embedded IFluidHandles have been replaced with a serializable form.
-     *
-     * The original `input` object is not mutated.  This method will shallowly clones all objects in the path from
-     * the root to any replaced handles.  (If no handles are found, returns the original object.)
-     */
-    encode(value: any, bind: IFluidHandle): any;
-    /**
-     * Given a fully-jsonable object tree that may have encoded handle objects embedded within, will return an
-     * equivalent object tree where any encoded IFluidHandles have been replaced with their decoded form.
-     *
-     * The original `input` object is not mutated.  This method will shallowly clone all objects in the path from
-     * the root to any replaced handles.  (If no handles are found, returns the original object.)
-     *
-     * The decoded handles are implicitly bound to the handle context of this serializer.
-     */
-    decode(input: any): any;
-    /**
-     * Stringifies a given value. Converts any IFluidHandle to its stringified equivalent.
-     */
-    stringify(value: any, bind: IFluidHandle): string;
-    /**
-     * Parses the given JSON input string and returns the JavaScript object defined by it. Any Fluid
-     * handles will be realized as part of the parse
-     */
-    parse(value: string): any;
-}
-
-/**
- * Base interface for shared objects from which other interfaces derive. Implemented by SharedObject
- * @public
- */
-export declare interface ISharedObject<TEvent extends ISharedObjectEvents = ISharedObjectEvents> extends IChannel, IEventProvider<TEvent> {
-    /**
-     * Binds the given shared object to its containing data store runtime, causing it to attach once
-     * the runtime attaches.
-     */
-    bindToContext(): void;
-    /**
-     * Returns the GC data for this shared object. 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;
-}
-
-/**
- * Events emitted by {@link ISharedObject}.
- * @public
- */
-export declare interface ISharedObjectEvents extends IErrorEvent {
-    /**
-     * Fires before an incoming operation (op) is applied to the shared object.
-     *
-     * @remarks Note: this should be considered an internal implementation detail. It is not recommended for external
-     * use.
-     *
-     * @eventProperty
-     */
-    (event: "pre-op", listener: (op: ISequencedDocumentMessage, local: boolean, target: IEventThisPlaceHolder) => void): any;
-    /**
-     * Fires after an incoming op is applied to the shared object.
-     *
-     * @remarks Note: this should be considered an internal implementation detail. It is not recommended for external
-     * use.
-     *
-     * @eventProperty
-     */
-    (event: "op", listener: (op: ISequencedDocumentMessage, local: boolean, target: IEventThisPlaceHolder) => void): any;
-}
-
-/**
- * Given a mostly-plain object that may have handle objects embedded within, will return a fully-plain object
- * where any embedded IFluidHandles have been replaced with a serializable form.
- *
- * The original `input` object is not mutated.  This method will shallowly clones all objects in the path from
- * the root to any replaced handles.  (If no handles are found, returns the original object.)
- *
- * @param input - The mostly-plain object
- * @param context - The handle context for the container
- * @param bind - Bind any other handles we find in the object against this given handle.
- * @returns The fully-plain object
- * @alpha
- */
-export declare function makeHandlesSerializable(value: any, serializer: IFluidSerializer, bind: IFluidHandle): any;
-
-/**
- * Given a fully-plain object that may have serializable-form handles within, will return the mostly-plain object
- * with handle objects created instead.
- * @param value - The fully-plain object
- * @param serializer - The serializer that knows how to convert serializable-form handles into handle objects
- * @param context - The handle context for the container
- * @returns The mostly-plain object with handle objects within
- * @alpha
- */
-export declare function parseHandles(value: any, serializer: IFluidSerializer): any;
-
-/* Excluded from this release type: serializeHandles */
-
-/**
- * SharedObject with simplified, synchronous summarization and GC.
- * DDS implementations with async and incremental summarization should extend SharedObjectCore directly instead.
- * @alpha
- */
-export declare abstract class SharedObject<TEvent extends ISharedObjectEvents = ISharedObjectEvents> extends SharedObjectCore<TEvent> {
-    private readonly telemetryContextPrefix;
-    /**
-     * True while we are garbage collecting this object's data.
-     */
-    private _isGCing;
-    /**
-     * The serializer to use to serialize / parse handles, if any.
-     */
-    private readonly _serializer;
-    protected get serializer(): IFluidSerializer;
-    /**
-     * @param id - The id of the shared object
-     * @param runtime - The IFluidDataStoreRuntime which contains the shared object
-     * @param attributes - Attributes of the shared object
-     */
-    constructor(id: string, runtime: IFluidDataStoreRuntime, attributes: IChannelAttributes, telemetryContextPrefix: string);
-    /**
-     * {@inheritDoc @fluidframework/datastore-definitions#(IChannel:interface).getAttachSummary}
-     */
-    getAttachSummary(fullTree?: boolean, trackState?: boolean, telemetryContext?: ITelemetryContext): ISummaryTreeWithStats;
-    /**
-     * {@inheritDoc @fluidframework/datastore-definitions#(IChannel:interface).summarize}
-     */
-    summarize(fullTree?: boolean, trackState?: boolean, telemetryContext?: ITelemetryContext, incrementalSummaryContext?: IExperimentalIncrementalSummaryContext): Promise<ISummaryTreeWithStats>;
-    /**
-     * {@inheritDoc (ISharedObject:interface).getGCData}
-     */
-    getGCData(fullGC?: boolean): IGarbageCollectionData;
-    /**
-     * Calls the serializer over all data in this object that reference other GC nodes.
-     * Derived classes must override this to provide custom list of references to other GC nodes.
-     */
-    protected processGCDataCore(serializer: IFluidSerializer): void;
-    /**
-     * Gets a form of the object that can be serialized.
-     * @returns A tree representing the snapshot of the shared object.
-     */
-    protected abstract summarizeCore(serializer: IFluidSerializer, telemetryContext?: ITelemetryContext, incrementalSummaryContext?: IExperimentalIncrementalSummaryContext): ISummaryTreeWithStats;
-    private incrementTelemetryMetric;
-}
-
-/**
- * Base class from which all shared objects derive.
- * @alpha
- */
-export declare abstract class SharedObjectCore<TEvent extends ISharedObjectEvents = ISharedObjectEvents> extends EventEmitterWithErrorHandling<TEvent> implements ISharedObject<TEvent> {
-    id: string;
-    protected runtime: IFluidDataStoreRuntime;
-    readonly attributes: IChannelAttributes;
-    get IFluidLoadable(): this;
-    private readonly opProcessingHelper;
-    private readonly callbacksHelper;
-    /**
-     * The handle referring to this SharedObject
-     */
-    readonly handle: IFluidHandle;
-    /**
-     * Telemetry logger for the shared object
-     */
-    protected readonly logger: ITelemetryLoggerExt;
-    private readonly mc;
-    /**
-     * Connection state
-     */
-    private _connected;
-    /**
-     * Services used by the shared object
-     */
-    private services;
-    /**
-     * True if the dds is bound to its parent.
-     */
-    private _isBoundToContext;
-    /**
-     * Tracks error that closed this object.
-     */
-    private closeError?;
-    /**
-     * Gets the connection state
-     * @returns The state of the connection
-     */
-    get connected(): boolean;
-    /**
-     * @param id - The id of the shared object
-     * @param runtime - The IFluidDataStoreRuntime which contains the shared object
-     * @param attributes - Attributes of the shared object
-     */
-    constructor(id: string, runtime: IFluidDataStoreRuntime, attributes: IChannelAttributes);
-    /**
-     * This function is only supposed to be called from SharedObjectCore's constructor and
-     * depends on a few things being set already. assert() calls make sure of it.
-     * @returns The telemetry sampling helpers, so the constructor can be the one to assign them
-     * to variables to avoid complaints from TypeScript.
-     */
-    private setUpSampledTelemetryHelpers;
-    /**
-     * Marks this objects as closed. Any attempt to change it (local changes or processing remote ops)
-     * would result in same error thrown. If called multiple times, only first error is remembered.
-     * @param error - error object that is thrown whenever an attempt is made to modify this object
-     */
-    private closeWithError;
-    /**
-     * Verifies that this object is not closed via closeWithError(). If it is, throws an error used to close it.
-     */
-    private verifyNotClosed;
-    /**
-     * Event listener handler helper that can be used to react to exceptions thrown from event listeners
-     * It wraps error with DataProcessingError, closes this object and throws resulting error.
-     * See closeWithError() for more details
-     * Ideally such situation never happens, as consumers of DDS should never throw exceptions
-     * in event listeners (i.e. catch any of the issues and make determination on how to handle it).
-     * When such exceptions propagate through, most likely data model is no longer consistent, i.e.
-     * DDS state does not match what user sees. Because of it DDS moves to "corrupted state" and does not
-     * allow processing of ops or local changes, which very quickly results in container closure.
-     */
-    private eventListenerErrorHandler;
-    private setBoundAndHandleAttach;
-    /**
-     * A shared object, after construction, can either be loaded in the case that it is already part of
-     * a shared document. Or later attached if it is being newly added.
-     * @param services - Services used by the shared object
-     */
-    load(services: IChannelServices): Promise<void>;
-    /**
-     * Initializes the object as a local, non-shared object. This object can become shared after
-     * it is attached to the document.
-     */
-    initializeLocal(): void;
-    /**
-     * {@inheritDoc (ISharedObject:interface).bindToContext}
-     */
-    bindToContext(): void;
-    /**
-     * {@inheritDoc @fluidframework/datastore-definitions#(IChannel:interface).connect}
-     */
-    connect(services: IChannelServices): void;
-    /**
-     * {@inheritDoc @fluidframework/datastore-definitions#(IChannel:interface).isAttached}
-     */
-    isAttached(): boolean;
-    /**
-     * {@inheritDoc @fluidframework/datastore-definitions#(IChannel:interface).getAttachSummary}
-     */
-    abstract getAttachSummary(fullTree?: boolean, trackState?: boolean, telemetryContext?: ITelemetryContext): ISummaryTreeWithStats;
-    /**
-     * {@inheritDoc @fluidframework/datastore-definitions#(IChannel:interface).summarize}
-     */
-    abstract summarize(fullTree?: boolean, trackState?: boolean, telemetryContext?: ITelemetryContext): Promise<ISummaryTreeWithStats>;
-    /**
-     * {@inheritDoc (ISharedObject:interface).getGCData}
-     */
-    abstract getGCData(fullGC?: boolean): IGarbageCollectionData;
-    /**
-     * Called when a handle is decoded by this object. A handle in the object's data represents an outbound reference
-     * to another object in the container.
-     * @param decodedHandle - The handle of the Fluid object that is decoded.
-     */
-    protected handleDecoded(decodedHandle: IFluidHandle): void;
-    /**
-     * Allows the distributed data type to perform custom loading
-     * @param services - Storage used by the shared object
-     */
-    protected abstract loadCore(services: IChannelStorageService): Promise<void>;
-    /**
-     * Allows the distributed data type to perform custom local loading.
-     */
-    protected initializeLocalCore(): void;
-    /**
-     * Allows the distributive data type the ability to perform custom processing once an attach has happened.
-     * Also called after non-local data type get loaded.
-     */
-    protected didAttach(): void;
-    /**
-     * Derived classes must override this to do custom processing on a remote message.
-     * @param message - The message to process
-     * @param local - True if the shared object is local
-     * @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.
-     */
-    protected abstract processCore(message: ISequencedDocumentMessage, local: boolean, localOpMetadata: unknown): any;
-    /**
-     * Called when the object has disconnected from the delta stream.
-     */
-    protected abstract onDisconnect(): any;
-    /**
-     * The serializer to serialize / parse handles.
-     */
-    protected abstract get serializer(): IFluidSerializer;
-    /**
-     * Submits a message by the local client to the runtime.
-     * @param content - Content of the message. Note: handles contained in the
-     * message object should not be encoded in any way
-     * @param localOpMetadata - The local metadata associated with the message. This is kept locally by the runtime
-     * and not sent to the server. This will be sent back when this message is received back from the server. This is
-     * also sent if we are asked to resubmit the message.
-     */
-    protected submitLocalMessage(content: any, localOpMetadata?: unknown): void;
-    /**
-     * Marks this object as dirty so that it is part of the next summary. It is called by a SharedSummaryBlock
-     * that want to be part of summary but does not generate ops.
-     */
-    protected dirty(): void;
-    /**
-     * Called when the object has fully connected to the delta stream
-     * Default implementation for DDS, override if different behavior is required.
-     */
-    protected onConnect(): void;
-    /**
-     * Called when a message has to be resubmitted. This typically happens after a reconnection for unacked messages.
-     * The default implementation here is to resubmit the same message. The client can override if different behavior
-     * is required. It can choose to resubmit the same message, submit different / multiple messages or not submit
-     * anything at all.
-     * @param content - The content of the original message.
-     * @param localOpMetadata - The local metadata associated with the original message.
-     */
-    protected reSubmitCore(content: any, localOpMetadata: unknown): void;
-    /**
-     * Promises that are waiting for an ack from the server before resolving should use this instead of new Promise.
-     * It ensures that if something changes that will interrupt that ack (e.g. the FluidDataStoreRuntime disposes),
-     * the Promise will reject.
-     * If runtime is disposed when this call is made, executor is not run and promise is rejected right away.
-     */
-    protected newAckBasedPromise<T>(executor: (resolve: (value: T | PromiseLike<T>) => void, reject: (reason?: any) => void) => void): Promise<T>;
-    private attachDeltaHandler;
-    /**
-     * Set the state of connection to services.
-     * @param connected - true if connected, false otherwise.
-     */
-    private setConnectionState;
-    /**
-     * Handles a message being received from the remote delta server.
-     * @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.
-     */
-    private process;
-    /**
-     * Called when a message has to be resubmitted. This typically happens for unacked messages after a
-     * reconnection.
-     * @param content - The content of the original message.
-     * @param localOpMetadata - The local metadata associated with the original message.
-     */
-    private reSubmit;
-    /**
-     * Revert an op
-     */
-    protected rollback(content: any, localOpMetadata: unknown): void;
-    /**
-     * Apply changes from the provided op content just as if a local client has made the change,
-     * including submitting the op. Used when rehydrating an attached container
-     * with pending changes. The rehydration process replays all remote ops
-     * and applies stashed ops after the remote op with a sequence number
-     * that matches that of the stashed op is applied. This ensures
-     * stashed ops are applied at the same state they were originally created.
-     *
-     * It is possible that stashed ops have been sent in the past, and will be found when
-     * the shared object catches up with remotes ops.
-     * So this prepares the SharedObject for seeing potentially seeing the ACK.
-     * If no matching remote op is found, all the applied stashed ops will go
-     * through the normal resubmit flow upon reconnection, which allows the dds
-     * to rebase them to the latest state, and then resubmit them.
-     *
-     * @param content - Contents of a stashed op.
-     */
-    protected abstract applyStashedOp(content: any): void;
-    /**
-     * Emit an event. This function is only intended for use by DDS classes that extend SharedObject/SharedObjectCore,
-     * specifically to emit events that are part of the public interface of the DDS (i.e. those that can have listeners
-     * attached to them by the consumers of the DDS). It should not be called from outside the class or to emit events
-     * which are only internal to the DDS. Support for calling it from outside the DDS instance might be removed in the
-     * future.
-     * @param event - The event to emit.
-     * @param args - Arguments to pass to the event listeners.
-     * @returns `true` if the event had listeners, `false` otherwise.
-     */
-    emit(event: EventEmitterEventType, ...args: any[]): boolean;
-    /**
-     * Use to emit events inside {@link SharedObjectCore}, with no telemetry measurement
-     * done on the duration of the callbacks. Simply calls `super.emit()`.
-     * @param event - Event to emit
-     * @param args - Arguments for the event
-     * @returns Whatever `super.emit()` returns.
-     */
-    private emitInternal;
-}
-
-/* Excluded from this release type: SummarySerializer */
-
-/* Excluded from this release type: ValueType */
-
-export { }