Data Object Factories

/**
 * Bare-bones IFluidDataStoreFactory for use with PureDataObject.
 * Consumers should typically use DataObjectFactory unless creating another base factory.
 * @typeParam TObj - The concrete data object type
 * @typeParam I - The input types for the data object
 */
class PureDataObjectFactory<
  TObj extends PureDataObject<I>,
  I extends DataObjectTypes = DataObjectTypes
> implements IFluidDataStoreFactory, Partial<IProvideFluidDataStoreRegistry>

/** The type identifier for this factory */
public readonly type: string;

/** IFluidDataStoreFactory interface implementation */
public get IFluidDataStoreFactory(): this;

/** Optional data store registry for nested factories */
public get IFluidDataStoreRegistry(): IFluidDataStoreRegistry | undefined;

/** Registry entry for use in container runtime factories */
public get registryEntry(): NamedFluidDataStoreRegistryEntry;

/**
 * Core factory method called by Fluid runtime to instantiate data stores
 * @param context - The data store context
 * @param existing - Whether loading from existing data store
 */
public async instantiateDataStore(
  context: IFluidDataStoreContext,
  existing: boolean
): Promise<IFluidDataStoreChannel>;

/**
 * Creates a child instance using parent context's registry
 * @param parentContext - Parent data store context
 * @param initialState - Optional initial state
 * @param loadingGroupId - Optional loading group for performance optimization
 */
public async createChildInstance(
  parentContext: IFluidDataStoreContext,
  initialState?: I["InitialState"],
  loadingGroupId?: string
): Promise<TObj>;

/**
 * Creates a peer instance using peer context's registry
 * @param peerContext - Peer data store context
 * @param initialState - Optional initial state
 * @param loadingGroupId - Optional loading group for performance optimization
 */
public async createPeerInstance(
  peerContext: IFluidDataStoreContext,
  initialState?: I["InitialState"],
  loadingGroupId?: string
): Promise<TObj>;

/**
 * Creates an instance using container's registry
 * @param runtime - Container runtime
 * @param initialState - Optional initial state
 * @param loadingGroupId - Optional loading group for performance optimization
 */
public async createInstance(
  runtime: IContainerRuntimeBase,
  initialState?: I["InitialState"],
  loadingGroupId?: string
): Promise<TObj>;

/**
 * Creates an instance with aliasing support
 * @param containerRuntime - Container runtime
 * @param initialState - Optional initial state
 * @param packagePath - Path to factory in registry
 * @param loadingGroupId - Optional loading group for performance optimization
 * @returns Tuple of [data object, data store] for aliasing operations
 */
public async createInstanceWithDataStore(
  containerRuntime: IContainerRuntimeBase,
  initialState?: I["InitialState"],
  packagePath?: Readonly<string[]>,
  loadingGroupId?: string
): Promise<[TObj, IDataStore]>;

/**
 * Creates a root instance with automatic aliasing (deprecated)
 * @param rootDataStoreId - The alias for the root data store
 * @param runtime - Container runtime
 * @param initialState - Optional initial state
 */
public async createRootInstance(
  rootDataStoreId: string,
  runtime: IContainerRuntime,
  initialState?: I["InitialState"]
): Promise<TObj>;

// Basic factory creation
const factory = new PureDataObjectFactory({
  type: "my-data-object",
  ctor: MyDataObject,
  sharedObjects: [SharedMap.getFactory()],
  optionalProviders: { IFluidUserInfo },
});

// Create instance in container
const runtime = container.runtime;
const instance = await factory.createInstance(runtime, { initialValue: 42 });

/**
 * IFluidDataStoreFactory for use with DataObjects.
 * Automatically ensures SharedDirectory and SharedMap factories are registered.
 * @typeParam TObj - The concrete DataObject type
 * @typeParam I - The input types for the data object
 */
class DataObjectFactory<
  TObj extends DataObject<I>,
  I extends DataObjectTypes = DataObjectTypes
> extends PureDataObjectFactory<TObj, I>

/**
 * Creates a DataObjectFactory with automatic SharedDirectory/SharedMap registration
 * @param props - Factory configuration properties
 */
public constructor(props: DataObjectFactoryProps<TObj, I>);

/**
 * Legacy constructor (deprecated)
 * @param type - Factory type identifier
 * @param ctor - Data object constructor
 * @param sharedObjects - Optional shared object factories
 * @param optionalProviders - Optional providers for dependency injection
 * @param registryEntries - Optional registry entries for nested factories
 * @param runtimeFactory - Optional custom runtime factory
 */
public constructor(
  type: string,
  ctor: new (props: IDataObjectProps<I>) => TObj,
  sharedObjects?: readonly IChannelFactory[],
  optionalProviders?: FluidObjectSymbolProvider<I["OptionalProviders"]>,
  registryEntries?: NamedFluidDataStoreRegistryEntries,
  runtimeFactory?: typeof FluidDataStoreRuntime
);

class CounterDataObject extends DataObject {
  // Implementation using this.root SharedDirectory
}

const CounterFactory = new DataObjectFactory({
  type: "counter",
  ctor: CounterDataObject,
  sharedObjects: [SharedCounter.getFactory()], // SharedDirectory automatically added
});

/**
 * IFluidDataStoreFactory for use with TreeDataObjects.
 * Automatically ensures SharedTree factory is registered.
 * @typeParam TDataObject - The concrete TreeDataObject type
 * @typeParam TDataObjectTypes - The input types for the data object
 */
class TreeDataObjectFactory<
  TDataObject extends TreeDataObject<TDataObjectTypes>,
  TDataObjectTypes extends DataObjectTypes = DataObjectTypes
> extends PureDataObjectFactory<TDataObject, TDataObjectTypes>

/**
 * Creates a TreeDataObjectFactory with automatic SharedTree registration
 * @param props - Factory configuration properties
 */
public constructor(props: DataObjectFactoryProps<TDataObject, TDataObjectTypes>);

class DocumentTreeDataObject extends TreeDataObject {
  // Implementation using this.tree SharedTree
}

const DocumentTreeFactory = new TreeDataObjectFactory({
  type: "document-tree",
  ctor: DocumentTreeDataObject,
  // SharedTree factory automatically added
});

/**
 * Properties required to create any data object factory
 * @typeParam TObj - The concrete data object type
 * @typeParam I - The input types for the data object
 */
interface DataObjectFactoryProps<
  TObj extends PureDataObject<I>,
  I extends DataObjectTypes = DataObjectTypes
> {
  /** Type identifier for the data object factory */
  readonly type: string;

  /** Constructor function for the data object */
  readonly ctor: new (props: IDataObjectProps<I>) => TObj;

  /** Shared objects (DDSes) to be registered with the data object */
  readonly sharedObjects?: readonly IChannelFactory[];

  /** Optional providers for dependency injection */
  readonly optionalProviders?: FluidObjectSymbolProvider<I["OptionalProviders"]>;

  /** Registry entries for nested data store factories */
  readonly registryEntries?: NamedFluidDataStoreRegistryEntries;

  /** Custom runtime class for advanced scenarios */
  readonly runtimeClass?: typeof FluidDataStoreRuntime;

  /** Optional policies that can be applied to the data object */
  readonly policies?: Partial<IFluidDataStorePolicies>;
}

interface IMyProvider {
  getValue(): string;
}

class MyDataObject extends PureDataObject<{
  OptionalProviders: IMyProvider;
}> {
  protected async hasInitialized() {
    const provider = await this.providers.IMyProvider;
    if (provider) {
      console.log("Provider value:", provider.getValue());
    }
  }
}

const factory = new PureDataObjectFactory({
  type: "my-object",
  ctor: MyDataObject,
  optionalProviders: { IMyProvider },
});

const childFactory = new DataObjectFactory({
  type: "child",
  ctor: ChildDataObject,
});

const parentFactory = new DataObjectFactory({
  type: "parent",
  ctor: ParentDataObject,
  registryEntries: [childFactory.registryEntry],
});

// Parent can now create child instances
class ParentDataObject extends DataObject {
  protected async initializingFirstTime() {
    const child = await childFactory.createChildInstance(this.context);
    this.root.set("child", child.handle);
  }
}

const factory = new DataObjectFactory({
  type: "secure-object",
  ctor: SecureDataObject,
  policies: {
    // Custom policies for security, performance, etc.
    gcOptions: { gcAllowed: false },
  },
});