@fluidframework/shared-object-base 2.113.1 → 2.115.0

package/src/dataStoreKind.ts

@@ -0,0 +1,301 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import type { IFluidLoadable, FluidObject } from "@fluidframework/core-interfaces";
+import {
+	type ISharedObjectRegistry,
+	FluidDataStoreRuntime,
+} from "@fluidframework/datastore/internal";
+import type { IFluidDataStoreRuntime } from "@fluidframework/datastore-definitions/internal";
+import {
+	type Registry,
+	type DataStoreKind,
+	lookupInRegistry,
+} from "@fluidframework/driver-definitions/internal";
+import type {
+	IFluidDataStoreContext,
+	IFluidDataStoreChannel,
+} from "@fluidframework/runtime-definitions/internal";
+import { DataStoreKindImplementation } from "@fluidframework/runtime-utils/internal";
+import { UsageError } from "@fluidframework/telemetry-utils/internal";
+
+import type {
+	ISharedObjectKind,
+	SharedObjectKey,
+	SharedObjectKindAlpha,
+} from "./sharedObject.js";
+import type { ISharedObject } from "./types.js";
+
+/**
+ * This file provides the implementation of {@link @fluidframework/driver-definitions#DataStoreKind}
+ * and is therefore a key part of the implementation of the {@link @fluidframework/driver-definitions#ServiceClient} API surface.
+ *
+ * Note that much of the API surface beyond {@link defineDataStore} could be removed/deduplicated
+ * if the unification noted in the TODOs in {@link SharedObjectRegistry} is implemented.
+ */
+
+/**
+ * A {@link @fluidframework/driver-definitions#Registry} of shared object kinds that can be created or loaded within a data store.
+ * @remarks
+ * Supports lazy code loading in a limited way (a single lazy load per registry).
+ * @privateRemarks
+ * TODO: The framework provided SharedObjects should be exposed in a way indistinguishable from custom sub-data stores.
+ * This can be done by unifying the DataStoreKind and SharedObjectKindAlpha types.
+ * For now, this would mean having DataStoreKind extend SharedObjectKindAlpha, since we can allow a data store in all places SharedObjects are allowed,
+ * but do not allow SharedObjects at the root.
+ * Fixing this, and allowing shared objects at the root (maybe use a trivial wrapper data store) could simplify things, allowing data stores and Containers to share some types (like how they create detached contents, have registries, have a root etc).
+ *
+ * Part of this unification could be to relax the output from the factories / registries. Allowing the output to be an arbitrary type, which might be a promise, and might not be one could help.
+ * Removal of the IFluidLoadable requirement, and allowing the returned type to expose handles to itself however it wants (or not at all) might be viable and simplify typing and allow for strongly typed handles at creation time at least).
+ * Maybe when Registry(type) gives a promise, it could instead give a factory which outputs a promise wrapped type? The check that the provided creation key is valid for that factory can be deferred until the promise resolves.
+ *
+ * Idea: creation key can have an interface that subsets the factory / SharedObjectKindAlpha / DataStoreKind so they can be used, or some branded key (string, and/or object with stronger identity what knows the type string) can be used.
+ * Have Key interface contain validation function to check that the factory used (or maybe the value produced from it) is valid for that key.
+ * During load, validation would simply check the factory's type string matches the key's type string.
+ * When using SharedObjectKindAlpha or DataStoreKind, validation can check factory object identity against key.
+ *
+ * Goal: Mostly unify container, data store and shared object abstractions.
+ * Maybe unify a bit with service client since it also has a way to create detached things with an initialized root then attach them.
+ * SharedObjects are just built in leaf data stores.
+ *
+ * @input
+ * @alpha
+ */
+export type SharedObjectRegistry = () => Promise<
+	Registry<SharedObjectKindAlpha<IFluidLoadable>>
+>;
+
+/**
+ * Creates a {@link SharedObjectRegistry} from an iterable of {@link SharedObjectKindAlpha}s or async getters for them.
+ * @alpha
+ */
+export function sharedObjectRegistryFromIterable(
+	entries: Iterable<
+		| SharedObjectKindAlpha<IFluidLoadable>
+		| { type: string; kind: () => Promise<SharedObjectKindAlpha<IFluidLoadable>> }
+	>,
+): SharedObjectRegistry {
+	return async () => {
+		const map = new Map<string, SharedObjectKindAlpha<IFluidLoadable>>();
+		for (const entry of entries) {
+			if ("kind" in entry) {
+				map.set(entry.type, await entry.kind());
+			} else {
+				map.set(asSharedObjectKind(entry).getFactory().type, entry);
+			}
+		}
+		return (type: string) => {
+			const entry = map.get(type);
+			if (entry === undefined) {
+				throw new UsageError(`Unknown shared object type: ${type}`);
+			}
+			return entry;
+		};
+	};
+}
+
+/**
+ * Options which define how to construct a particular {@link @fluidframework/driver-definitions#DataStoreKind}.
+ * @remarks
+ * Use {@link defineDataStore} to create a {@link @fluidframework/driver-definitions#DataStoreKind} from these options.
+ * @input
+ * @alpha
+ */
+export interface DataStoreOptions<in out TRoot extends IFluidLoadable, out TOutput> {
+	/**
+	 * The type identifier for the data object factory.
+	 * @remarks
+	 * Persisted identifier which specifies which {@link @fluidframework/driver-definitions#DataStoreKind} to use when loading it.
+	 * @privateRemarks
+	 * Equivalent to `DataObjectFactoryProps.type`.
+	 */
+	readonly type: string;
+
+	/**
+	 * The registry of shared object kinds (including other data stores) that can be loaded or created within this data store.
+	 *
+	 * TODO: actually allow this to contain data stores.
+	 */
+	readonly registry: SharedObjectRegistry;
+
+	/**
+	 * Create the initial content of the data store, and return the root shared object.
+	 * @privateRemarks
+	 * TODO:
+	 * This requires the caller to produce a single root shared object (which is keyed by {@link rootSharedObjectId}).
+	 * This should be fine for new code, but code migrated from legacy APIs might need more flexibility.
+	 * Such use-cases could be accommodated providing a legacy alternative to `defineDataStore` where `instantiateFirstTime` and `view` directly expose access to named root shared objects.
+	 * This should be easy to implement, but is currently not included.
+	 */
+	instantiateFirstTime(
+		rootCreator: SharedObjectCreator<TRoot>,
+		context: DataStoreContext,
+	): Promise<TRoot>;
+
+	/**
+	 * Construct a view of the data store's root shared object.
+	 *
+	 * @param root - The root shared object of the data store, created by `instantiateFirstTime` (though possibly created by another client and loaded by this one).
+	 * @param context - A {@link DataStoreContext} that can be used to create additional shared objects.
+	 */
+	view(root: TRoot, context: DataStoreContext): Promise<TOutput>;
+}
+
+/**
+ * Creates a {@link @fluidframework/driver-definitions#DataStoreKind} from {@link DataStoreOptions}.
+ * @alpha
+ */
+export function defineDataStore<T, TRoot extends IFluidLoadable>(
+	options: DataStoreOptions<TRoot, T>,
+): DataStoreKind<T> {
+	return new DataStoreKindImplementation<T>({
+		type: options.type,
+		async instantiateDataStore(
+			context: IFluidDataStoreContext,
+			existing: boolean,
+		): Promise<IFluidDataStoreChannel> {
+			return createDataStore(context, existing, options);
+		},
+	});
+}
+
+/**
+ * Casts a {@link SharedObjectKindAlpha} to its encapsulated {@link ISharedObjectKind} view.
+ *
+ * @remarks
+ * {@link SharedObjectKindAlpha} is a sealed type,
+ * so we can assume it implements {@link ISharedObjectKind} and down cast to it.
+ */
+function asSharedObjectKind<T extends IFluidLoadable>(
+	kind: SharedObjectKindAlpha<T>,
+): ISharedObjectKind<T> {
+	const candidate = kind as unknown as Partial<ISharedObjectKind<T>>;
+	// Sanity check to help catch misuse since SharedObjectKindAlpha is typed structurally and seems implementable.
+	if (typeof candidate.getFactory !== "function" || typeof candidate.create !== "function") {
+		throw new UsageError(
+			"Invalid SharedObjectKindAlpha: this type is sealed and may not have custom implementations.",
+		);
+	}
+	return candidate as ISharedObjectKind<T>;
+}
+
+function convertRegistry(
+	lookup: Registry<SharedObjectKindAlpha<IFluidLoadable>>,
+): ISharedObjectRegistry {
+	return {
+		get: (type: string) => {
+			const entry = lookup(type);
+			return asSharedObjectKind(entry).getFactory();
+		},
+	};
+}
+
+/**
+ * Data stores keep their shared objects inside channels which get names.
+ * This is the name of the channel which we conventionally use for the root shared object of a data store in most cases.
+ * @remarks
+ * There can be other named channels, or the root could use a different name, but we are trying to migrate away from such patterns.
+ * Currently the DataStoreKind pattern used in this file follows and requires this convention,
+ * but we may relax that in the future for interop with legacy data if necessary.
+ */
+const rootSharedObjectId = "root";
+
+/**
+ * Creates a data store channel.
+ * @param context - The data store context.
+ * @param existing - Whether the data store already exists. When true, this loads it, when false a new one is created.
+ * @param options - The data store options.
+ * @returns A promise that resolves to the created data store channel.
+ * @remarks
+ * Currently this is limited to data stores which have a single named channel,
+ * which must have the {@link rootSharedObjectId} and is attached at creation time.
+ * This limitation may be relaxed in the future.
+ */
+async function createDataStore<T, TRoot extends IFluidLoadable>(
+	context: IFluidDataStoreContext,
+	existing: boolean,
+	options: DataStoreOptions<TRoot, T>,
+): Promise<IFluidDataStoreChannel> {
+	const sharedObjectRegistry = await options.registry();
+	const runtime: FluidDataStoreRuntime = new FluidDataStoreRuntime(
+		context,
+		convertRegistry(sharedObjectRegistry),
+		existing,
+		async (runtimeInner: IFluidDataStoreRuntime) => {
+			const innerContext: DataStoreContext = {
+				async createSharedObject<T2 extends IFluidLoadable>(
+					key: SharedObjectKey<T2>,
+				): Promise<T2> {
+					const kind = lookupInRegistry(sharedObjectRegistry, key);
+					// Create detached channel.
+					return asSharedObjectKind(kind).create(runtimeInner);
+				},
+			};
+
+			let createdRoot: TRoot | undefined;
+
+			const rootCreator: SharedObjectCreator<TRoot> = {
+				async createSharedObject<T2 extends TRoot>(key: SharedObjectKey<T2>): Promise<T2> {
+					// Create named channel under the root id.
+					// Error if called twice.
+					if (createdRoot !== undefined) {
+						throw new UsageError("Root shared object already created");
+					}
+					const kind = lookupInRegistry(sharedObjectRegistry, key);
+					const result = asSharedObjectKind(kind).create(runtimeInner, rootSharedObjectId);
+
+					// Every shared object is also an ISharedObject;
+					const rootSharedObject = result as IFluidLoadable as ISharedObject;
+					// bind the newly created root so it becomes part of this data store.
+					rootSharedObject.bindToContext();
+
+					createdRoot = result;
+					return result;
+				},
+			};
+
+			let root: TRoot | undefined;
+			if (existing) {
+				// getChannel returns the type-erased IChannel; the registered root kind guarantees it is a TRoot.
+				root = (await runtimeInner.getChannel(rootSharedObjectId)) as IFluidLoadable as TRoot;
+			} else {
+				root = await options.instantiateFirstTime(rootCreator, innerContext);
+				if (root !== createdRoot) {
+					throw new UsageError(
+						"instantiateFirstTime did not return root created with rootCreator",
+					);
+				}
+			}
+
+			// view returns the data store's output type; the runtime only needs it as an opaque FluidObject entry point.
+			return (await options.view(root, innerContext)) as unknown as FluidObject;
+		},
+	);
+
+	return runtime;
+}
+
+/**
+ * Creates instances of SharedObjectKinds.
+ * @privateRemarks
+ * See IFluidContainer.create.
+ * @sealed
+ * @alpha
+ */
+export interface SharedObjectCreator<TConstraint = IFluidLoadable> {
+	/**
+	 * Create an instance of `kind`, which must be registered in the registry of the surrounding data store.
+	 */
+	createSharedObject<T extends TConstraint>(kind: SharedObjectKey<T>): Promise<T>;
+}
+
+/**
+ * Contextual information about a data store which is provided when instantiating or loading it.
+ * @privateRemarks
+ * TODO: this can expose more contextual information about the data store as needed.
+ * @sealed
+ * @alpha
+ */
+export interface DataStoreContext extends SharedObjectCreator {}

package/src/index.ts

@@ -10,7 +10,10 @@ export {
 	SharedObjectCore,
 	type ISharedObjectKind,
 	type SharedObjectKind,
+	type SharedObjectKindAlpha,
 	createSharedObjectKind,
+	createSharedObjectKindAlpha,
+	type SharedObjectKey,
 } from "./sharedObject.js";
 export type { ISharedObject, ISharedObjectEvents } from "./types.js";
 export {
@@ -32,3 +35,11 @@ export {
 	type SharedObjectOptions,
 	mergeAPIs,
 } from "./sharedObjectKernel.js";
+export { defineDataStore, sharedObjectRegistryFromIterable } from "./dataStoreKind.js";
+export { makeStubDataStoreKind } from "./stubSharedObject.js";
+export type {
+	DataStoreOptions,
+	SharedObjectCreator,
+	SharedObjectRegistry,
+	DataStoreContext,
+} from "./dataStoreKind.js";

package/src/packageVersion.ts

@@ -6,4 +6,4 @@
  */
 
 export const pkgName = "@fluidframework/shared-object-base";
-export const pkgVersion = "2.113.1";
+export const pkgVersion = "2.115.0";

package/src/sharedObject.ts

@@ -25,6 +25,7 @@ import type {
 import type {
 	IDocumentMessage,
 	ISequencedDocumentMessage,
+	RegistryKey,
 } from "@fluidframework/driver-definitions/internal";
 import {
 	type IExperimentalIncrementalSummaryContext,
@@ -51,6 +52,7 @@ import {
 	type ICustomData,
 	type IFluidErrorBase,
 	LoggingError,
+	UsageError,
 	extractTelemetryLoggerExt,
 } from "@fluidframework/telemetry-utils/internal";
 // eslint-disable-next-line import-x/no-internal-modules -- Needed to avoid specialized /internal ITelemetryLoggerExt
@@ -985,6 +987,31 @@ export interface SharedObjectKind<out TSharedObject = unknown>
 	is(value: IFluidLoadable): value is IFluidLoadable & TSharedObject;
 }
 
+/**
+ * A {@link @fluidframework/driver-definitions#RegistryKey} for a {@link SharedObjectKind}.
+ * @remarks
+ * This is implemented by {@link SharedObjectKind}, but alternative implementations can be used if needed.
+ *
+ * If you want lazy loading and need a key that does not eagerly load the {@link SharedObjectKind}, an alternative {@link SharedObjectKey} can be implemented.
+ * @privateRemarks
+ * TODO: A built in common pattern for the lazy key case should be provided.
+ * TODO: things probably break if "adapt" does anything except throw or return the result from the input promise.
+ * @input
+ * @alpha
+ */
+export type SharedObjectKey<T> = RegistryKey<SharedObjectKindAlpha<T>, SharedObjectKindAlpha>;
+
+/**
+ * A {@link SharedObjectKind} that also implements {@link SharedObjectKey}.
+ * @privateRemarks
+ * All concrete shared object kinds (produced by {@link createSharedObjectKind}) implement this interface.
+ * @sealed
+ * @alpha
+ */
+export interface SharedObjectKindAlpha<out TSharedObject = unknown>
+	extends SharedObjectKind<TSharedObject>,
+		SharedObjectKey<TSharedObject> {}
+
 /**
  * Utility for creating ISharedObjectKind instances.
  * @remarks
@@ -997,8 +1024,23 @@ export interface SharedObjectKind<out TSharedObject = unknown>
 export function createSharedObjectKind<TSharedObject>(
 	factory: (new () => IChannelFactory<TSharedObject>) & { readonly Type: string },
 ): ISharedObjectKind<TSharedObject> & SharedObjectKind<TSharedObject> {
+	return createSharedObjectKindAlpha(factory);
+}
+
+/**
+ * Utility for creating ISharedObjectKind instances.
+ * @remarks
+ * This takes in a class which implements IChannelFactory,
+ * and uses it to return a single value which is intended to be used as the API entry point for the corresponding shared object type.
+ * The returned value implements {@link ISharedObjectKind} for use in the encapsulated API, as well as the type erased {@link SharedObjectKind} used by the declarative API.
+ * See {@link @fluidframework/fluid-static#ContainerSchema} for how this is used in the declarative API.
+ * @internal
+ */
+export function createSharedObjectKindAlpha<TSharedObject>(
+	factory: (new () => IChannelFactory<TSharedObject>) & { readonly Type: string },
+): ISharedObjectKind<TSharedObject> & SharedObjectKindAlpha<TSharedObject> {
 	const result: ISharedObjectKind<TSharedObject> &
-		Omit<SharedObjectKind<TSharedObject>, "brand"> = {
+		Omit<SharedObjectKindAlpha<TSharedObject>, "brand"> = {
 		getFactory(): IChannelFactory<TSharedObject> {
 			return new factory();
 		},
@@ -1010,9 +1052,25 @@ export function createSharedObjectKind<TSharedObject>(
 		is(value: IFluidLoadable): value is IFluidLoadable & TSharedObject {
 			return isChannel(value) && value.attributes.type === factory.Type;
 		},
+
+		type: factory.Type,
+
+		adapt: (value: SharedObjectKindAlpha): SharedObjectKindAlpha<TSharedObject> => {
+			if (value === resultFinal) {
+				return resultFinal;
+			}
+			if (value.type === result.type) {
+				throw new UsageError(`Conflicting SharedObjectKinds with same type: ${result.type}`);
+			}
+			throw new UsageError(
+				`Mismatched SharedObjectKind type. Expected: ${result.type}, got: ${value.type}`,
+			);
+		},
 	};
 
-	return result as typeof result & SharedObjectKind<TSharedObject>;
+	const resultFinal = result as typeof result & SharedObjectKindAlpha<TSharedObject>;
+
+	return resultFinal;
 }
 
 function isChannel(loadable: IFluidLoadable): loadable is IChannel {

package/src/sharedObjectKernel.ts

@@ -28,10 +28,10 @@ import { extractTelemetryLoggerExt } from "@fluidframework/telemetry-utils/inter
 
 import type { IFluidSerializer } from "./serializer.js";
 import {
-	createSharedObjectKind,
+	createSharedObjectKindAlpha,
 	SharedObject,
 	type ISharedObjectKind,
-	type SharedObjectKind,
+	type SharedObjectKindAlpha,
 } from "./sharedObject.js";
 import type { ISharedObjectEvents, ISharedObject } from "./types.js";
 import type { IChannelView } from "./utils.js";
@@ -494,6 +494,6 @@ function makeChannelFactory<T extends object>(options: SharedObjectOptions<T>) {
  */
 export function makeSharedObjectKind<T extends object>(
 	options: SharedObjectOptions<T>,
-): ISharedObjectKind<T> & SharedObjectKind<T> {
-	return createSharedObjectKind<T>(makeChannelFactory(options));
+): ISharedObjectKind<T> & SharedObjectKindAlpha<T> {
+	return createSharedObjectKindAlpha<T>(makeChannelFactory(options));
 }

package/src/stubSharedObject.ts

@@ -0,0 +1,66 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import type { IFluidLoadable } from "@fluidframework/core-interfaces";
+import type { DataStoreKind } from "@fluidframework/driver-definitions/internal";
+import type { ISummaryTreeWithStats } from "@fluidframework/runtime-definitions/internal";
+
+import { defineDataStore, sharedObjectRegistryFromIterable } from "./dataStoreKind.js";
+import {
+	type SharedKernel,
+	type SharedKernelFactory,
+	makeSharedObjectKind,
+} from "./sharedObjectKernel.js";
+import { createSingleBlobSummary } from "./utils.js";
+
+class StatelessKernel implements SharedKernel {
+	summarizeCore(): ISummaryTreeWithStats {
+		return createSingleBlobSummary("header", "{}");
+	}
+	onDisconnect(): void {}
+	reSubmitCore(): void {}
+	applyStashedOp(): void {}
+	processMessagesCore(): void {}
+}
+
+const statelessKernelFactory: SharedKernelFactory<object> = {
+	create() {
+		const kernel = new StatelessKernel();
+		return { kernel, view: {} };
+	},
+	async loadCore() {
+		const kernel = new StatelessKernel();
+		return { kernel, view: {} };
+	},
+};
+
+const statelessSharedObjectKind = makeSharedObjectKind<IFluidLoadable>({
+	type: "com.microsoft.fluid.test.stateless",
+	attributes: {
+		type: "com.microsoft.fluid.test.stateless",
+		snapshotFormatVersion: "0.1",
+	},
+	telemetryContextPrefix: "test_stateless_",
+	factory: statelessKernelFactory,
+});
+
+/**
+ * Creates a trivial stub {@link @fluidframework/driver-definitions#DataStoreKind} backed by a
+ * stateless shared object.
+ * Useful in tests that need a valid data store but don't care about the content.
+ * @internal
+ */
+export function makeStubDataStoreKind(type: string): DataStoreKind {
+	return defineDataStore({
+		type,
+		registry: sharedObjectRegistryFromIterable([statelessSharedObjectKind]),
+		async instantiateFirstTime(rootCreator) {
+			return rootCreator.createSharedObject(statelessSharedObjectKind);
+		},
+		async view() {
+			return {};
+		},
+	});
+}