@fluidframework/aqueduct 2.0.0-dev-rc.3.0.0.254866 → 2.0.0-dev-rc.5.0.0.263932

package/src/data-object-factories/pureDataObjectFactory.ts

@@ -0,0 +1,379 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { FluidDataStoreRegistry } from "@fluidframework/container-runtime/internal";
+import { type IContainerRuntime } from "@fluidframework/container-runtime-definitions/internal";
+import { type FluidObject, type IRequest } from "@fluidframework/core-interfaces";
+import { assert } from "@fluidframework/core-utils/internal";
+import {
+	FluidDataStoreRuntime,
+	type ISharedObjectRegistry,
+	mixinRequestHandler,
+} from "@fluidframework/datastore/internal";
+import {
+	type IChannelFactory,
+	type IFluidDataStoreRuntime,
+} from "@fluidframework/datastore-definitions";
+import {
+	type IContainerRuntimeBase,
+	type IDataStore,
+	type IFluidDataStoreChannel,
+	type IFluidDataStoreContext,
+	type IFluidDataStoreContextDetached,
+	type IFluidDataStoreFactory,
+	type IFluidDataStoreRegistry,
+	type IProvideFluidDataStoreRegistry,
+	type NamedFluidDataStoreRegistryEntries,
+	type NamedFluidDataStoreRegistryEntry,
+} from "@fluidframework/runtime-definitions/internal";
+import {
+	type AsyncFluidObjectProvider,
+	type FluidObjectSymbolProvider,
+	type IFluidDependencySynthesizer,
+} from "@fluidframework/synthesize/internal";
+
+import {
+	type DataObjectTypes,
+	type IDataObjectProps,
+	type PureDataObject,
+} from "../data-objects/index.js";
+
+/**
+ * Proxy over PureDataObject
+ * Does delayed creation & initialization of PureDataObject
+ */
+async function createDataObject<
+	TObj extends PureDataObject,
+	I extends DataObjectTypes = DataObjectTypes,
+>(
+	ctor: new (props: IDataObjectProps<I>) => TObj,
+	context: IFluidDataStoreContext,
+	sharedObjectRegistry: ISharedObjectRegistry,
+	optionalProviders: FluidObjectSymbolProvider<I["OptionalProviders"]>,
+	runtimeClassArg: typeof FluidDataStoreRuntime,
+	existing: boolean,
+	initProps?: I["InitialState"],
+): Promise<{
+	instance: TObj;
+	runtime: FluidDataStoreRuntime;
+}> {
+	// base
+	let runtimeClass = runtimeClassArg;
+
+	// request mixin in
+	runtimeClass = mixinRequestHandler(
+		async (request: IRequest, runtimeArg: FluidDataStoreRuntime) => {
+			// The provideEntryPoint callback below always returns TObj, so this cast is safe
+			const dataObject = (await runtimeArg.entryPoint.get()) as TObj;
+			assert(
+				dataObject.request !== undefined,
+				0x795 /* Data store runtime entryPoint does not have request */,
+			);
+			return dataObject.request(request);
+		},
+		runtimeClass,
+	);
+
+	// Create a new runtime for our data store, as if via new FluidDataStoreRuntime,
+	// but using the runtimeClass that's been augmented with mixins
+	// The runtime is what Fluid uses to create DDS' and route to your data store
+	const runtime: FluidDataStoreRuntime = new runtimeClass( // calls new FluidDataStoreRuntime(...)
+		context,
+		sharedObjectRegistry,
+		existing,
+		async (rt: IFluidDataStoreRuntime) => {
+			assert(instance !== undefined, 0x46a /* entryPoint is undefined */);
+			// Calling finishInitialization here like PureDataObject.getDataObject did, to keep the same behavior,
+			// since accessing the runtime's entryPoint is how we want the data object to be retrieved going forward.
+			// Without this I ran into issues with the load-existing flow not working correctly.
+			await instance.finishInitialization(true);
+			return instance;
+		} /* provideEntryPoint */,
+	);
+
+	// Create object right away.
+	// This allows object to register various callbacks with runtime before runtime
+	// becomes globally available. But it's not full initialization - constructor can't
+	// access DDSes or other services of runtime as objects are not fully initialized.
+	// In order to use object, we need to go through full initialization by calling finishInitialization().
+	const scope: FluidObject<IFluidDependencySynthesizer> = context.scope;
+	const providers =
+		scope.IFluidDependencySynthesizer?.synthesize<I["OptionalProviders"]>(
+			optionalProviders,
+			{},
+		) ??
+		// eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+		({} as AsyncFluidObjectProvider<never>);
+
+	const instance = new ctor({ runtime, context, providers, initProps });
+
+	// if it's a newly created object, we need to wait for it to finish initialization
+	// as that results in creation of DDSes, before it gets attached, providing atomic
+	// guarantee of creation.
+	// WARNING: we can't do the same (yet) for already existing PureDataObject!
+	// This will result in deadlock, as it tries to resolve internal handles, but any
+	// handle resolution goes through root (container runtime), which can't route it back
+	// to this data store, as it's still not initialized and not known to container runtime yet.
+	// In the future, we should address it by using relative paths for handles and be able to resolve
+	// local DDSes while data store is not fully initialized.
+	if (!existing) {
+		await instance.finishInitialization(existing);
+	}
+
+	return { instance, runtime };
+}
+
+/**
+ * PureDataObjectFactory is a barebones IFluidDataStoreFactory for use with PureDataObject.
+ * Consumers should typically use DataObjectFactory instead unless creating
+ * another base data store factory.
+ *
+ * @typeParam TObj - DataObject (concrete type)
+ * @typeParam I - The input types for the DataObject
+ * @alpha
+ */
+export class PureDataObjectFactory<
+		TObj extends PureDataObject<I>,
+		I extends DataObjectTypes = DataObjectTypes,
+	>
+	implements IFluidDataStoreFactory, Partial<IProvideFluidDataStoreRegistry>
+{
+	private readonly sharedObjectRegistry: ISharedObjectRegistry;
+	private readonly registry: IFluidDataStoreRegistry | undefined;
+
+	public constructor(
+		/**
+		 * {@inheritDoc @fluidframework/runtime-definitions#IFluidDataStoreFactory."type"}
+		 */
+		public readonly type: string,
+		private readonly ctor: new (props: IDataObjectProps<I>) => TObj,
+		sharedObjects: readonly IChannelFactory[],
+		private readonly optionalProviders: FluidObjectSymbolProvider<I["OptionalProviders"]>,
+		registryEntries?: NamedFluidDataStoreRegistryEntries,
+		private readonly runtimeClass: typeof FluidDataStoreRuntime = FluidDataStoreRuntime,
+	) {
+		if (this.type === "") {
+			throw new Error("undefined type member");
+		}
+		if (registryEntries !== undefined) {
+			this.registry = new FluidDataStoreRegistry(registryEntries);
+		}
+		this.sharedObjectRegistry = new Map(sharedObjects.map((ext) => [ext.type, ext]));
+	}
+
+	/**
+	 * {@inheritDoc @fluidframework/runtime-definitions#IProvideFluidDataStoreFactory.IFluidDataStoreFactory}
+	 */
+	public get IFluidDataStoreFactory(): this {
+		return this;
+	}
+
+	/**
+	 * {@inheritDoc @fluidframework/runtime-definitions#IProvideFluidDataStoreRegistry.IFluidDataStoreRegistry}
+	 */
+	public get IFluidDataStoreRegistry(): IFluidDataStoreRegistry | undefined {
+		return this.registry;
+	}
+
+	/**
+	 * Convenience helper to get the data store's/factory's data store registry entry.
+	 * The return type hides the factory's generics, easing grouping of registry
+	 * entries that differ only in this way into the same array.
+	 * @returns The NamedFluidDataStoreRegistryEntry
+	 */
+	public get registryEntry(): NamedFluidDataStoreRegistryEntry {
+		return [this.type, Promise.resolve(this)];
+	}
+
+	/**
+	 * {@inheritDoc @fluidframework/runtime-definitions#IFluidDataStoreFactory.instantiateDataStore}
+	 */
+	public async instantiateDataStore(
+		context: IFluidDataStoreContext,
+		existing: boolean,
+	): Promise<IFluidDataStoreChannel> {
+		const { runtime } = await createDataObject(
+			this.ctor,
+			context,
+			this.sharedObjectRegistry,
+			this.optionalProviders,
+			this.runtimeClass,
+			existing,
+		);
+
+		return runtime;
+	}
+
+	/**
+	 * Creates a new instance of the object. Uses parent context's registry to build package path to this factory.
+	 * In other words, registry of context passed in has to contain this factory, with the name that matches
+	 * this factory's type.
+	 * It is intended to be used by data store objects that create sub-objects.
+	 * @param context - The context being used to create the runtime
+	 * (the created object will have its own new context created as well)
+	 * @param initialState - The initial state to provide to the created data store.
+	 * @param loadingGroupId - NOT production ready, EXPERIMENTAL, please read {@link https://github.com/microsoft/FluidFramework/blob/main/packages/runtime/container-runtime/README.md | README}. The service needs to support this feature, does not work for most services
+	 * @returns an object created by this factory. Data store and objects created are not attached to container.
+	 * They get attached only when a handle to one of them is attached to already attached objects.
+	 */
+	public async createChildInstance(
+		parentContext: IFluidDataStoreContext,
+		initialState?: I["InitialState"],
+		loadingGroupId?: string,
+	): Promise<TObj> {
+		return this.createNonRootInstanceCore(
+			parentContext.containerRuntime,
+			[...parentContext.packagePath, this.type],
+			initialState,
+			loadingGroupId,
+		);
+	}
+
+	/**
+	 * Creates a new instance of the object. Uses peer context's registry and its package path to identify this factory.
+	 * In other words, registry of context passed in has to have this factory.
+	 * Intended to be used by data store objects that need to create peers (similar) instances of existing objects.
+	 * @param context - The component context being used to create the object
+	 * (the created object will have its own new context created as well)
+	 * @param initialState - The initial state to provide to the created component.
+	 * @param loadingGroupId - NOT production ready, EXPERIMENTAL, please read {@link https://github.com/microsoft/FluidFramework/blob/main/packages/runtime/container-runtime/README.md | README}. The service needs to support this feature, does not work for most services
+	 * @returns an object created by this factory. Data store and objects created are not attached to container.
+	 * They get attached only when a handle to one of them is attached to already attached objects.
+	 */
+	public async createPeerInstance(
+		peerContext: IFluidDataStoreContext,
+		initialState?: I["InitialState"],
+		loadingGroupId?: string, // DO NOT USE, this is an experimental feature
+	): Promise<TObj> {
+		return this.createNonRootInstanceCore(
+			peerContext.containerRuntime,
+			peerContext.packagePath,
+			initialState,
+			loadingGroupId,
+		);
+	}
+
+	/**
+	 * Creates a new instance of the object. Uses container's registry to find this factory.
+	 * It's expected that only container owners would use this functionality, as only such developers
+	 * have knowledge of entries in container registry.
+	 * The name in this registry for such record should match type of this factory.
+	 * @param runtime - container runtime. It's registry is used to create an object.
+	 * @param initialState - The initial state to provide to the created component.
+	 * @param loadingGroupId - NOT production ready, EXPERIMENTAL, please read {@link https://github.com/microsoft/FluidFramework/blob/main/packages/runtime/container-runtime/README.md | README}. The service needs to support this feature, does not work for most services
+	 * @returns an object created by this factory. Data store and objects created are not attached to container.
+	 * They get attached only when a handle to one of them is attached to already attached objects.
+	 */
+	public async createInstance(
+		runtime: IContainerRuntimeBase,
+		initialState?: I["InitialState"],
+		loadingGroupId?: string,
+	): Promise<TObj> {
+		return this.createNonRootInstanceCore(runtime, [this.type], initialState, loadingGroupId);
+	}
+
+	/**
+	 * Creates a new instance of the object with a datastore which exposes the aliasing api.
+	 * @param runtime - container runtime. It is the runtime that will be used to create the object. It will produce
+	 * the underlying infrastructure to get the data object to operate.
+	 * @param initialState - The initial state to provide to the created component.
+	 * @param packagePath - The path to the data store factory to use to create the data object.
+	 * @param loadingGroupId - NOT production ready, EXPERIMENTAL, please read {@link https://github.com/microsoft/FluidFramework/blob/main/packages/runtime/container-runtime/README.md | README}. The service needs to support this feature, does not work for most services
+	 * @returns an array containing the object created by this factory and an IDataStore object that enables users to
+	 * alias the data object.
+	 * The data object is attached only when it is attached to the handle graph that connects to an aliased object or
+	 * when the data object is aliased.
+	 */
+	public async createInstanceWithDataStore(
+		containerRuntime: IContainerRuntimeBase,
+		initialState?: I["InitialState"],
+		packagePath?: Readonly<string[]>,
+		loadingGroupId?: string,
+	): Promise<[TObj, IDataStore]> {
+		const context = containerRuntime.createDetachedDataStore(
+			packagePath ?? [this.type],
+			loadingGroupId,
+		);
+		const { instance, runtime } = await createDataObject(
+			this.ctor,
+			context,
+			this.sharedObjectRegistry,
+			this.optionalProviders,
+			this.runtimeClass,
+			false, // existing
+			initialState,
+		);
+		const dataStore = await context.attachRuntime(this, runtime);
+
+		return [instance, dataStore];
+	}
+
+	/**
+	 * Creates a new root instance of the object. Uses container's registry to find this factory.
+	 * It's expected that only container owners would use this functionality, as only such developers
+	 * have knowledge of entries in container registry.
+	 * The name in this registry for such record should match type of this factory.
+	 * @param runtime - container runtime. It's registry is used to create an object.
+	 * @param initialState - The initial state to provide to the created component.
+	 * @returns an object created by this factory. Data store and objects created are not attached to container.
+	 * They get attached only when a handle to one of them is attached to already attached objects.
+	 *
+	 * @deprecated - the issue is that it does not allow the customer to decide the conflict resolution policy when an
+	 * aliasing conflict occurs. Use {@link PureDataObjectFactory.createInstanceWithDataStore} instead.
+	 */
+	public async createRootInstance(
+		rootDataStoreId: string,
+		runtime: IContainerRuntime,
+		initialState?: I["InitialState"],
+	): Promise<TObj> {
+		const context = runtime.createDetachedDataStore([this.type]);
+		const { instance, runtime: dataStoreRuntime } = await createDataObject(
+			this.ctor,
+			context,
+			this.sharedObjectRegistry,
+			this.optionalProviders,
+			this.runtimeClass,
+			false, // existing
+			initialState,
+		);
+		const dataStore = await context.attachRuntime(this, dataStoreRuntime);
+		const result = await dataStore.trySetAlias(rootDataStoreId);
+		if (result !== "Success") {
+			const handle = await runtime.getAliasedDataStoreEntryPoint(rootDataStoreId);
+			assert(handle !== undefined, 0x8e1 /* Should have retrieved aliased handle */);
+			return (await handle.get()) as TObj;
+		}
+		return instance;
+	}
+
+	protected async createNonRootInstanceCore(
+		containerRuntime: IContainerRuntimeBase,
+		packagePath: Readonly<string[]>,
+		initialState?: I["InitialState"],
+		loadingGroupId?: string,
+	): Promise<TObj> {
+		const context = containerRuntime.createDetachedDataStore(packagePath, loadingGroupId);
+		return this.createInstanceCore(context, initialState);
+	}
+
+	protected async createInstanceCore(
+		context: IFluidDataStoreContextDetached,
+		initialState?: I["InitialState"],
+	): Promise<TObj> {
+		const { instance, runtime } = await createDataObject(
+			this.ctor,
+			context,
+			this.sharedObjectRegistry,
+			this.optionalProviders,
+			this.runtimeClass,
+			false, // existing
+			initialState,
+		);
+
+		await context.attachRuntime(this, runtime);
+
+		return instance;
+	}
+}

package/src/data-objects/dataObject.ts

@@ -0,0 +1,80 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+// eslint-disable-next-line import/no-deprecated
+import { type ISharedDirectory, MapFactory, SharedDirectory } from "@fluidframework/map/internal";
+
+import { PureDataObject } from "./pureDataObject.js";
+import { type DataObjectTypes } from "./types.js";
+
+/**
+ * DataObject is a base data store that is primed with a root directory. It
+ * ensures that it is created and ready before you can access it.
+ *
+ * Having a single root directory allows for easier development. Instead of creating
+ * and registering channels with the runtime any new DDS that is set on the root
+ * will automatically be registered.
+ *
+ * @typeParam I - The optional input types used to strongly type the data object
+ * @alpha
+ */
+export abstract class DataObject<
+	I extends DataObjectTypes = DataObjectTypes,
+> extends PureDataObject<I> {
+	private internalRoot: ISharedDirectory | undefined;
+	private readonly rootDirectoryId = "root";
+
+	/**
+	 * The root directory will either be ready or will return an error. If an error is thrown
+	 * the root has not been correctly created/set.
+	 */
+	protected get root(): ISharedDirectory {
+		if (!this.internalRoot) {
+			throw new Error(this.getUninitializedErrorString(`root`));
+		}
+
+		return this.internalRoot;
+	}
+
+	/**
+	 * Initializes internal objects and calls initialization overrides.
+	 * Caller is responsible for ensuring this is only invoked once.
+	 */
+	public async initializeInternal(existing: boolean): Promise<void> {
+		if (existing) {
+			// data store has a root directory so we just need to set it before calling initializingFromExisting
+			this.internalRoot = (await this.runtime.getChannel(
+				this.rootDirectoryId,
+			)) as ISharedDirectory;
+
+			// This will actually be an ISharedMap if the channel was previously created by the older version of
+			// DataObject which used a SharedMap.  Since SharedMap and SharedDirectory are compatible unless
+			// SharedDirectory-only commands are used on SharedMap, this will mostly just work for compatibility.
+			if (this.internalRoot.attributes.type === MapFactory.Type) {
+				this.runtime.logger.send({
+					category: "generic",
+					eventName: "MapDataObject",
+					message:
+						"Legacy document, SharedMap is masquerading as SharedDirectory in DataObject",
+				});
+			}
+		} else {
+			// Create a root directory and register it before calling initializingFirstTime
+			// eslint-disable-next-line import/no-deprecated
+			this.internalRoot = SharedDirectory.create(this.runtime, this.rootDirectoryId);
+			this.internalRoot.bindToContext();
+		}
+
+		await super.initializeInternal(existing);
+	}
+
+	/**
+	 * Generates an error string indicating an item is uninitialized.
+	 * @param item - The name of the item that was uninitialized.
+	 */
+	protected getUninitializedErrorString(item: string): string {
+		return `${item} must be initialized before being accessed.`;
+	}
+}

package/src/data-objects/index.ts

@@ -0,0 +1,8 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+export { DataObject } from "./dataObject.js";
+export { PureDataObject } from "./pureDataObject.js";
+export type { DataObjectTypes, IDataObjectProps } from "./types.js";

package/src/data-objects/pureDataObject.ts

@@ -0,0 +1,186 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { TypedEventEmitter } from "@fluid-internal/client-utils";
+import { type IEvent } from "@fluidframework/core-interfaces";
+import {
+	type IFluidHandleInternal,
+	type IFluidLoadable,
+	type IProvideFluidHandle,
+	type IRequest,
+	type IResponse,
+} from "@fluidframework/core-interfaces/internal";
+import { assert } from "@fluidframework/core-utils/internal";
+import { type IFluidDataStoreRuntime } from "@fluidframework/datastore-definitions";
+import { type IFluidDataStoreContext } from "@fluidframework/runtime-definitions/internal";
+import { create404Response } from "@fluidframework/runtime-utils/internal";
+import { type AsyncFluidObjectProvider } from "@fluidframework/synthesize/internal";
+
+import { type DataObjectTypes, type IDataObjectProps } from "./types.js";
+
+/**
+ * This is a bare-bones base class that does basic setup and enables for factory on an initialize call.
+ * You probably don't want to inherit from this data store directly unless
+ * you are creating another base data store class
+ *
+ * @typeParam I - The optional input types used to strongly type the data object
+ * @alpha
+ */
+export abstract class PureDataObject<I extends DataObjectTypes = DataObjectTypes>
+	extends TypedEventEmitter<I["Events"] & IEvent>
+	implements IFluidLoadable, IProvideFluidHandle
+{
+	/**
+	 * This is your FluidDataStoreRuntime object
+	 */
+	protected readonly runtime: IFluidDataStoreRuntime;
+
+	/**
+	 * This context is used to talk up to the ContainerRuntime
+	 */
+	protected readonly context: IFluidDataStoreContext;
+
+	/**
+	 * Providers are FluidObject keyed objects that provide back
+	 * a promise to the corresponding FluidObject or undefined.
+	 * Providers injected/provided by the Container and/or HostingApplication
+	 *
+	 * To define providers set FluidObject interfaces in the OptionalProviders generic type for your data store
+	 */
+	protected readonly providers: AsyncFluidObjectProvider<I["OptionalProviders"]>;
+
+	protected initProps?: I["InitialState"];
+
+	protected initializeP: Promise<void> | undefined;
+
+	public get id(): string {
+		return this.runtime.id;
+	}
+
+	/**
+	 * {@inheritDoc @fluidframework/core-interfaces#IProvideFluidLoadable.IFluidLoadable}
+	 */
+	public get IFluidLoadable(): this {
+		return this;
+	}
+
+	/**
+	 * {@inheritDoc @fluidframework/core-interfaces#IProvideFluidHandle.IFluidHandle}
+	 */
+	public get IFluidHandle(): IFluidHandleInternal<this> {
+		return this.handle;
+	}
+
+	/**
+	 * Handle to a data store
+	 */
+	public get handle(): IFluidHandleInternal<this> {
+		// PureDataObjectFactory already provides an entryPoint initialization function to the data store runtime,
+		// so this object should always have access to a non-null entryPoint. Need to cast because PureDataObject
+		// tried to be too smart with its typing for handles :).
+		assert(this.runtime.entryPoint !== undefined, 0x46b /* EntryPoint was undefined */);
+		return this.runtime.entryPoint as IFluidHandleInternal<this>;
+	}
+
+	public static async getDataObject(runtime: IFluidDataStoreRuntime): Promise<PureDataObject> {
+		const obj = await runtime.entryPoint.get();
+		return obj as PureDataObject;
+	}
+
+	public constructor(props: IDataObjectProps<I>) {
+		super();
+		this.runtime = props.runtime;
+		this.context = props.context;
+		this.providers = props.providers;
+		this.initProps = props.initProps;
+
+		/* eslint-disable @typescript-eslint/no-unsafe-member-access */
+		/* eslint-disable @typescript-eslint/no-explicit-any */
+		assert(
+			(this.runtime as any)._dataObject === undefined,
+			0x0bd /* "Object runtime already has DataObject!" */,
+		);
+		(this.runtime as any)._dataObject = this;
+		/* eslint-enable @typescript-eslint/no-explicit-any */
+		/* eslint-enable @typescript-eslint/no-unsafe-member-access */
+	}
+
+	/**
+	 * Return this object if someone requests it directly
+	 * We will return this object in two scenarios:
+	 *
+	 * 1. the request url is a "/"
+	 *
+	 * 2. the request url is empty
+	 */
+	public async request(req: IRequest): Promise<IResponse> {
+		return req.url === "" || req.url === "/" || req.url.startsWith("/?")
+			? { mimeType: "fluid/object", status: 200, value: this }
+			: create404Response(req);
+	}
+
+	/**
+	 * Call this API to ensure PureDataObject is fully initialized.
+	 * Initialization happens on demand, only on as-needed bases.
+	 * In most cases you should allow factory/object to decide when to finish initialization.
+	 * But if you are supplying your own implementation of DataStoreRuntime factory and overriding some methods
+	 * and need a fully initialized object, then you can call this API to ensure object is fully initialized.
+	 */
+	public async finishInitialization(existing: boolean): Promise<void> {
+		if (this.initializeP !== undefined) {
+			return this.initializeP;
+		}
+		this.initializeP = this.initializeInternal(existing);
+		return this.initializeP;
+	}
+
+	/**
+	 * Internal initialize implementation. Overwriting this will change the flow of the PureDataObject and should
+	 * generally not be done.
+	 *
+	 * Calls initializingFirstTime, initializingFromExisting, and hasInitialized. Caller is
+	 * responsible for ensuring this is only invoked once.
+	 */
+	public async initializeInternal(existing: boolean): Promise<void> {
+		await this.preInitialize();
+		if (existing) {
+			assert(
+				this.initProps === undefined,
+				0x0be /* "Trying to initialize from existing while initProps is set!" */,
+			);
+			await this.initializingFromExisting();
+		} else {
+			await this.initializingFirstTime(
+				(this.context.createProps as I["InitialState"]) ?? this.initProps,
+			);
+		}
+		await this.hasInitialized();
+	}
+
+	/**
+	 * Called every time the data store is initialized, before initializingFirstTime or
+	 * initializingFromExisting is called.
+	 */
+	protected async preInitialize(): Promise<void> {}
+
+	/**
+	 * Called the first time the data store is initialized (new creations with a new
+	 * data store runtime)
+	 *
+	 * @param props - Optional props to be passed in on create
+	 */
+	protected async initializingFirstTime(props?: I["InitialState"]): Promise<void> {}
+
+	/**
+	 * Called every time but the first time the data store is initialized (creations
+	 * with an existing data store runtime)
+	 */
+	protected async initializingFromExisting(): Promise<void> {}
+
+	/**
+	 * Called every time the data store is initialized after create or existing.
+	 */
+	protected async hasInitialized(): Promise<void> {}
+}

package/src/data-objects/types.ts

@@ -0,0 +1,40 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { type FluidObject, type IEvent } from "@fluidframework/core-interfaces";
+import { type IFluidDataStoreRuntime } from "@fluidframework/datastore-definitions";
+import { type IFluidDataStoreContext } from "@fluidframework/runtime-definitions/internal";
+import { type AsyncFluidObjectProvider } from "@fluidframework/synthesize/internal";
+
+/**
+ * This type is used as the base generic input to DataObject and PureDataObject.
+ * @alpha
+ */
+export interface DataObjectTypes {
+	/**
+	 * Represents a type that will define optional providers that will be injected.
+	 */
+	OptionalProviders?: FluidObject;
+	/**
+	 * The initial state type that the produced data object may take during creation.
+	 */
+	// TODO: Use a real type here.
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	InitialState?: any;
+	/**
+	 * Represents events that will be available in the EventForwarder.
+	 */
+	Events?: IEvent;
+}
+
+/**
+ * @alpha
+ */
+export interface IDataObjectProps<I extends DataObjectTypes = DataObjectTypes> {
+	readonly runtime: IFluidDataStoreRuntime;
+	readonly context: IFluidDataStoreContext;
+	readonly providers: AsyncFluidObjectProvider<I["OptionalProviders"]>;
+	readonly initProps?: I["InitialState"];
+}