@fluidframework/aqueduct 2.0.0-dev.7.3.0.212138 → 2.0.0-dev.7.4.0.214930

package/dist/aqueduct-alpha.d.ts

@@ -0,0 +1,459 @@
+/**
+ * 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
+ */
+
+import { AsyncFluidObjectProvider } from '@fluidframework/synthesize';
+import { ContainerRuntime } from '@fluidframework/container-runtime';
+import { FluidDataStoreRuntime } from '@fluidframework/datastore';
+import { FluidObject } from '@fluidframework/core-interfaces';
+import { FluidObjectSymbolProvider } from '@fluidframework/synthesize';
+import { IChannelFactory } from '@fluidframework/datastore-definitions';
+import { IContainer } from '@fluidframework/container-definitions';
+import { IContainerContext } from '@fluidframework/container-definitions';
+import { IContainerRuntime } from '@fluidframework/container-runtime-definitions';
+import { IContainerRuntimeBase } from '@fluidframework/runtime-definitions';
+import { IContainerRuntimeOptions } from '@fluidframework/container-runtime';
+import { IEvent } from '@fluidframework/core-interfaces';
+import { IFluidDataStoreContext } from '@fluidframework/runtime-definitions';
+import { IFluidDataStoreContextDetached } from '@fluidframework/runtime-definitions';
+import { IFluidDataStoreFactory } from '@fluidframework/runtime-definitions';
+import { IFluidDataStoreRegistry } from '@fluidframework/runtime-definitions';
+import { IFluidDataStoreRuntime } from '@fluidframework/datastore-definitions';
+import { IFluidDependencySynthesizer } from '@fluidframework/synthesize';
+import { IFluidHandle } from '@fluidframework/core-interfaces';
+import { IFluidLoadable } from '@fluidframework/core-interfaces';
+import type { IFluidMountableViewClass } from '@fluidframework/view-interfaces';
+import { IFluidRouter } from '@fluidframework/core-interfaces';
+import { IProvideFluidDataStoreRegistry } from '@fluidframework/runtime-definitions';
+import { IProvideFluidHandle } from '@fluidframework/core-interfaces';
+import { IRequest } from '@fluidframework/core-interfaces';
+import { IResponse } from '@fluidframework/core-interfaces';
+import { ISharedDirectory } from '@fluidframework/map';
+import { NamedFluidDataStoreRegistryEntries } from '@fluidframework/runtime-definitions';
+import { NamedFluidDataStoreRegistryEntry } from '@fluidframework/runtime-definitions';
+import { RequestParser } from '@fluidframework/runtime-utils';
+import { RuntimeFactoryHelper } from '@fluidframework/runtime-utils';
+import { RuntimeRequestHandler } from '@fluidframework/request-handler';
+
+/**
+ * BaseContainerRuntimeFactory produces container runtimes with the specified data store and service registries,
+ * request handlers, runtimeOptions, and entryPoint initialization function.
+ * It can be subclassed to implement a first-time initialization procedure for the containers it creates.
+ * @public
+ */
+export declare class BaseContainerRuntimeFactory extends RuntimeFactoryHelper implements IProvideFluidDataStoreRegistry {
+    get IFluidDataStoreRegistry(): IFluidDataStoreRegistry;
+    private readonly registry;
+    private readonly registryEntries;
+    private readonly dependencyContainer?;
+    private readonly runtimeOptions?;
+    private readonly requestHandlers;
+    private readonly provideEntryPoint;
+    /**
+     * @param registryEntries - The data store registry for containers produced
+     * @param dependencyContainer - deprecated, will be removed in a future release
+     * @param requestHandlers - Request handlers for containers produced
+     * @param runtimeOptions - The runtime options passed to the ContainerRuntime when instantiating it
+     * @param provideEntryPoint - Function that will initialize the entryPoint of the ContainerRuntime instances
+     * created with this factory
+     */
+    constructor(props: {
+        registryEntries: NamedFluidDataStoreRegistryEntries;
+        dependencyContainer?: IFluidDependencySynthesizer;
+        /** @deprecated Will be removed in future major release. Migrate all usage of IFluidRouter to the "entryPoint" pattern. Refer to Removing-IFluidRouter.md */
+        requestHandlers?: RuntimeRequestHandler[];
+        runtimeOptions?: IContainerRuntimeOptions;
+        provideEntryPoint: (runtime: IContainerRuntime) => Promise<FluidObject>;
+    });
+    instantiateFirstTime(runtime: ContainerRuntime): Promise<void>;
+    instantiateFromExisting(runtime: ContainerRuntime): Promise<void>;
+    preInitialize(context: IContainerContext, existing: boolean): Promise<ContainerRuntime>;
+    /**
+     * Subclasses may override containerInitializingFirstTime to perform any setup steps at the time the container
+     * is created. This likely includes creating any initial data stores that are expected to be there at the outset.
+     * @param runtime - The container runtime for the container being initialized
+     */
+    protected containerInitializingFirstTime(runtime: IContainerRuntime): Promise<void>;
+    /**
+     * Subclasses may override containerHasInitialized to perform any steps after the container has initialized.
+     * This likely includes loading any data stores that are expected to be there at the outset.
+     * @param runtime - The container runtime for the container being initialized
+     */
+    protected containerHasInitialized(runtime: IContainerRuntime): Promise<void>;
+}
+
+/**
+ * A ContainerRuntimeFactory that initializes Containers with a single default data store, which can be requested from
+ * the container with an empty URL.
+ *
+ * This factory should be exposed as fluidExport off the entry point to your module.
+ * @public
+ */
+export declare class ContainerRuntimeFactoryWithDefaultDataStore extends BaseContainerRuntimeFactory {
+    static readonly defaultDataStoreId = "default";
+    protected readonly defaultFactory: IFluidDataStoreFactory;
+    /**
+     * Constructor
+     * @param defaultFactory -
+     * @param registryEntries -
+     * @param dependencyContainer - deprecated, will be removed in a future release
+     * @param requestHandlers -
+     * @param runtimeOptions -
+     * @param provideEntryPoint -
+     */
+    constructor(props: {
+        defaultFactory: IFluidDataStoreFactory;
+        registryEntries: NamedFluidDataStoreRegistryEntries;
+        dependencyContainer?: IFluidDependencySynthesizer;
+        /** @deprecated Will be removed in future major release. Migrate all usage of IFluidRouter to the "entryPoint" pattern. Refer to Removing-IFluidRouter.md */
+        requestHandlers?: RuntimeRequestHandler[];
+        runtimeOptions?: IContainerRuntimeOptions;
+        provideEntryPoint?: (runtime: IContainerRuntime) => Promise<FluidObject>;
+    });
+    /**
+     * {@inheritDoc BaseContainerRuntimeFactory.containerInitializingFirstTime}
+     */
+    protected containerInitializingFirstTime(runtime: IContainerRuntime): Promise<void>;
+}
+
+/**
+ * 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
+ * @public
+ */
+export declare abstract class DataObject<I extends DataObjectTypes = DataObjectTypes> extends PureDataObject<I> {
+    private internalRoot;
+    private readonly rootDirectoryId;
+    /**
+     * 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;
+    /**
+     * Initializes internal objects and calls initialization overrides.
+     * Caller is responsible for ensuring this is only invoked once.
+     */
+    initializeInternal(existing: boolean): Promise<void>;
+    /**
+     * Generates an error string indicating an item is uninitialized.
+     * @param item - The name of the item that was uninitialized.
+     */
+    protected getUninitializedErrorString(item: string): string;
+}
+
+/**
+ * DataObjectFactory is the IFluidDataStoreFactory for use with DataObjects.
+ * It facilitates DataObject's features (such as its shared directory) by
+ * ensuring relevant shared objects etc are available to the factory.
+ *
+ * @typeParam TObj - DataObject (concrete type)
+ * @typeParam I - The input types for the DataObject
+ * @public
+ */
+export declare class DataObjectFactory<TObj extends DataObject<I>, I extends DataObjectTypes = DataObjectTypes> extends PureDataObjectFactory<TObj, I> {
+    constructor(type: string, ctor: new (props: IDataObjectProps<I>) => TObj, sharedObjects: readonly IChannelFactory[] | undefined, optionalProviders: FluidObjectSymbolProvider<I["OptionalProviders"]>, registryEntries?: NamedFluidDataStoreRegistryEntries, runtimeFactory?: typeof FluidDataStoreRuntime);
+}
+
+/**
+ * This type is used as the base generic input to DataObject and PureDataObject.
+ * @public
+ */
+export declare 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
+     */
+    InitialState?: any;
+    /**
+     * represents events that will be available in the EventForwarder
+     */
+    Events?: IEvent;
+}
+
+/**
+ * Default request handler for a Fluid object that returns the object itself if:
+ *
+ * 1. the request url is empty
+ *
+ * 2. the request url is "/"
+ *
+ * 3. the request url starts with "/" and is followed by a query param, such as /?key=value
+ *
+ * Returns a 404 error for any other url.
+ * @deprecated Will be removed in future major release. Migrate all usage of IFluidRouter to the "entryPoint" pattern. Refer to Removing-IFluidRouter.md
+ * @public
+ */
+export declare function defaultFluidObjectRequestHandler(fluidObject: FluidObject, request: IRequest): IResponse;
+
+/**
+ * Pipe through container request into internal request.
+ * If request is empty and default url is provided, redirect request to such default url.
+ * @param defaultRootId - optional default root data store ID to pass request in case request is empty.
+ * @deprecated Will be removed in future major release. Migrate all usage of IFluidRouter to the "entryPoint" pattern. Refer to Removing-IFluidRouter.md
+ * @public
+ */
+export declare const defaultRouteRequestHandler: (defaultRootId: string) => (request: IRequest, runtime: IContainerRuntime) => Promise<IResponse | undefined>;
+
+/**
+ * @deprecated Will be removed in future major release. Migrate all usage of IFluidRouter to the "entryPoint" pattern. Refer to Removing-IFluidRouter.md
+ * Helper function for getting the default Fluid Object from a Container. This function only works for
+ * Containers that support "/" request.
+ *
+ * @typeParam T - Defines the type you expect to be returned.
+ *
+ * @param container - Container you're attempting to get the object from
+ * @public
+ */
+export declare function getDefaultObjectFromContainer<T = FluidObject>(container: IContainer): Promise<T>;
+
+/**
+ * @deprecated Will be removed in future major release. Migrate all usage of IFluidRouter to the "entryPoint" pattern. Refer to Removing-IFluidRouter.md
+ * Helper function for getting a Fluid Object from a Container given a path/url. This function only works for
+ * Containers that support getting FluidObjects via request.
+ *
+ * @typeParam T - Defines the type you expect to be returned.
+ *
+ * @param path - Unique path/url of the FluidObject
+ * @param container - Container you're attempting to get the object from
+ * @public
+ */
+export declare function getObjectFromContainer<T = FluidObject>(path: string, container: IContainer): Promise<T>;
+
+/**
+ * @deprecated Will be removed in future major release. Migrate all usage of IFluidRouter to the "entryPoint" pattern. Refer to Removing-IFluidRouter.md
+ * Helper function for getting as Fluid Object from a Container given a Unique Id. This function only works for
+ * Containers that support getting FluidObjects via request.
+ *
+ * @typeParam T - Defines the type you expect to be returned.
+ *
+ * @param id - Unique id of the FluidObject
+ * @param container - Container you're attempting to get the object from
+ * @public
+ */
+export declare function getObjectWithIdFromContainer<T = FluidObject>(id: string, container: IContainer): Promise<T>;
+
+/**
+ * @public
+ */
+export declare interface IDataObjectProps<I extends DataObjectTypes = DataObjectTypes> {
+    readonly runtime: IFluidDataStoreRuntime;
+    readonly context: IFluidDataStoreContext;
+    readonly providers: AsyncFluidObjectProvider<I["OptionalProviders"]>;
+    readonly initProps?: I["InitialState"];
+}
+
+/**
+ * Useful interface in places where it's useful to do type erasure for PureDataObject generic
+ * @public
+ */
+export declare interface IRootDataObjectFactory extends IFluidDataStoreFactory {
+    createRootInstance(rootDataStoreId: string, runtime: IContainerRuntime): Promise<IFluidRouter>;
+}
+
+/**
+ * A mountable view is only required if the view needs to be mounted across a bundle boundary.  Mounting across
+ * bundle boundaries breaks some frameworks, so the mountable view is used to ensure the mounting is done within
+ * the same bundle as the view.  For example, React hooks don't work if mounted across bundles since there will
+ * be two React instances, breaking the Rules of Hooks.  When cross-bundle mounting isn't required, the mountable
+ * view isn't necessary.
+ *
+ * When a request is received with a mountableView: true header, this request handler will reissue the request
+ * without the header, and respond with a mountable view of the given class using the response.
+ * @param MountableViewClass - The type of mountable view to use when responding
+ * @deprecated Will be removed in future major release. Migrate all usage of IFluidRouter to the "entryPoint" pattern. Refer to Removing-IFluidRouter.md
+ * @public
+ */
+export declare const mountableViewRequestHandler: (MountableViewClass: IFluidMountableViewClass, handlers: RuntimeRequestHandler[]) => (request: RequestParser, runtime: IContainerRuntime) => Promise<IResponse>;
+
+/**
+ * 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
+ * @public
+ */
+export declare abstract class PureDataObject<I extends DataObjectTypes = DataObjectTypes> extends TypedEventEmitter<I["Events"] & IEvent> implements IFluidLoadable, IFluidRouter, 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;
+    get id(): string;
+    /**
+     * @deprecated Will be removed in future major release. Migrate all usage of IFluidRouter to the "entryPoint" pattern. Refer to Removing-IFluidRouter.md
+     */
+    get IFluidRouter(): this;
+    get IFluidLoadable(): this;
+    get IFluidHandle(): IFluidHandle<this>;
+    /**
+     * Handle to a data store
+     */
+    get handle(): IFluidHandle<this>;
+    static getDataObject(runtime: IFluidDataStoreRuntime): Promise<PureDataObject<DataObjectTypes>>;
+    constructor(props: IDataObjectProps<I>);
+    /**
+     * 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
+     */
+    request(req: IRequest): Promise<IResponse>;
+    /**
+     * 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.
+     */
+    finishInitialization(existing: boolean): Promise<void>;
+    /**
+     * 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.
+     */
+    initializeInternal(existing: boolean): Promise<void>;
+    /**
+     * Called every time the data store is initialized, before initializingFirstTime or
+     * initializingFromExisting is called.
+     */
+    protected 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 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 initializingFromExisting(): Promise<void>;
+    /**
+     * Called every time the data store is initialized after create or existing.
+     */
+    protected hasInitialized(): Promise<void>;
+}
+
+/**
+ * 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
+ * @public
+ */
+export declare class PureDataObjectFactory<TObj extends PureDataObject<I>, I extends DataObjectTypes = DataObjectTypes> implements IFluidDataStoreFactory, Partial<IProvideFluidDataStoreRegistry>, IRootDataObjectFactory {
+    readonly type: string;
+    private readonly ctor;
+    private readonly optionalProviders;
+    private readonly runtimeClass;
+    private readonly sharedObjectRegistry;
+    private readonly registry;
+    constructor(type: string, ctor: new (props: IDataObjectProps<I>) => TObj, sharedObjects: readonly IChannelFactory[], optionalProviders: FluidObjectSymbolProvider<I["OptionalProviders"]>, registryEntries?: NamedFluidDataStoreRegistryEntries, runtimeClass?: typeof FluidDataStoreRuntime);
+    get IFluidDataStoreFactory(): this;
+    get IFluidDataStoreRegistry(): IFluidDataStoreRegistry | undefined;
+    /**
+     * 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
+     */
+    get registryEntry(): NamedFluidDataStoreRegistryEntry;
+    /**
+     * This is where we do data store setup.
+     *
+     * @param context - data store context used to load a data store runtime
+     */
+    instantiateDataStore(context: IFluidDataStoreContext, existing: boolean): Promise<FluidDataStoreRuntime>;
+    /**
+     * 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.
+     * @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.
+     */
+    createChildInstance(parentContext: IFluidDataStoreContext, initialState?: I["InitialState"]): Promise<TObj>;
+    /**
+     * 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.
+     * @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.
+     */
+    createPeerInstance(peerContext: IFluidDataStoreContext, initialState?: I["InitialState"]): Promise<TObj>;
+    /**
+     * 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.
+     * @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.
+     */
+    createInstance(runtime: IContainerRuntimeBase, initialState?: I["InitialState"]): Promise<TObj>;
+    /**
+     * 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.
+     */
+    createRootInstance(rootDataStoreId: string, runtime: IContainerRuntime, initialState?: I["InitialState"]): Promise<TObj>;
+    protected createNonRootInstanceCore(containerRuntime: IContainerRuntimeBase, packagePath: Readonly<string[]>, initialState?: I["InitialState"]): Promise<TObj>;
+    protected createInstanceCore(context: IFluidDataStoreContextDetached, initialState?: I["InitialState"]): Promise<TObj>;
+}
+
+/* Excluded from this release type: TypedEventEmitter */
+
+export { }