@fluidframework/aqueduct 2.0.0-rc.2.0.2 → 2.0.0-rc.3.0.0

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,
+	type IFluidHandle,
+	type IFluidLoadable,
+	type IProvideFluidHandle,
+	type IRequest,
+	type IResponse,
+} from "@fluidframework/core-interfaces";
+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(): IFluidHandle<this> {
+		return this.handle;
+	}
+
+	/**
+	 * Handle to a data store
+	 */
+	public get handle(): IFluidHandle<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 IFluidHandle<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"];
+}

package/src/index.ts

@@ -0,0 +1,33 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/**
+ * The `aqueduct` package is a library for building Fluid objects and Fluid
+ * containers within the Fluid Framework. Its goal is to provide a thin base
+ * layer over the existing Fluid Framework interfaces that allows developers to
+ * get started quickly.
+ *
+ * @remarks
+ * About the library name: An "aqueduct" is a way to transport water from a source
+ * to another location. The library name was chosen because its purpose is to
+ * facilitate using lower level constructs and therefore handle 'fluid' items
+ * same as an aqueduct.
+ *
+ * @packageDocumentation
+ */
+
+export { DataObjectFactory, PureDataObjectFactory } from "./data-object-factories/index.js";
+export {
+	DataObject,
+	type DataObjectTypes,
+	type IDataObjectProps,
+	PureDataObject,
+} from "./data-objects/index.js";
+export {
+	BaseContainerRuntimeFactory,
+	type BaseContainerRuntimeFactoryProps,
+	ContainerRuntimeFactoryWithDefaultDataStore,
+	type ContainerRuntimeFactoryWithDefaultDataStoreProps,
+} from "./container-runtime-factories/index.js";

package/tsconfig.cjs.json

@@ -0,0 +1,7 @@
+{
+	// This config must be used in a "type": "commonjs" environment. (Use fluid-tsc commonjs.)
+	"extends": "./tsconfig.json",
+	"compilerOptions": {
+		"outDir": "./dist",
+	},
+}

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+	"extends": "../../../common/build/build-common/tsconfig.node16.json",
+	"include": ["src/**/*"],
+	"exclude": ["src/test/**/*"],
+	"compilerOptions": {
+		"rootDir": "./src",
+		"outDir": "./lib",
+	},
+}