New Component Creation Paradigm

[skylerjokiel]

This proposal is to shift the Component creation paradigm from creating through the ContainerRuntime to creation through individual component factories. By moving component creation into factories we provide more control to the component developers when it comes to the creation of their objects.

It provides a cleaner developer experience and mirrors the current pattern of SharedObject creation.

In this new world IComponentFactory will have a createComponent function that will be used for the create new flow. This function will call into the create flow on the ContainerRuntime but will need to provide the instantiate function. The initialize function has the same signature as the existing instantiateComponent with: (context: IComponentContext) => void. The Component Factory developer can choose to simply use the existing instantiateComponent function or they can provide an alternate function on the create call. This is powerful because create can be further separated from standard instantiate.

In the generic case the code would look something like this:

public instantiateComponent(context: IComponentContext): void {
    //...
}

public async createComponent(context: IComponentContext): Promise<IComponent> {
    const cr = await context.createComponent(this.registryName, (c) => { this.instantiateComponent(c); });
    const response = await cr.request({url: "/"});
    if (response.status !== 200 || response.mimeType !== "fluid/component") {
        throw new Error("Failed to create component");
    }

    return response.value as IComponent;
}

In the specialized case we can take in props that are used only in the create flow:

public async createClickerComponent(
    props: IClickerWithInitialValueProps,
    context: IComponentContext): Promise<ClickerWithInitialValue> {
        const cr = await context.hostRuntime.createComponentDirect(
            this.registryName, this.createInstantiation(props));
        const response = await cr.request({url: "/"});
        if (response.status !== 200 || response.mimeType !== "fluid/component") {
            throw new Error("Failed to create component");
        }

        return response.value as ClickerWithInitialValue;
    }

private createInstantiation(props: IClickerWithInitialValueProps) {
    return (context: IComponentContext) => {
        // Create a new runtime for our component
        // The runtime is what Fluid uses to create DDS' and route to your component
        ComponentRuntime.load(
            context,
            this.sharedObjectRegistry,
            (runtime: ComponentRuntime) => {
                const clicker = new ClickerWithInitialValue(runtime, context, props);
                const clickerP = clicker.initialize();

                runtime.registerRequestHandler(async (request: IRequest) => {
                    await clickerP;
                    return clicker.request(request);
                });
            },
        );
    };
}

In the above example we have strongly typed props passed through the entire creation flow.

Aqueduct update

With the new pattern Component developers will be responsible for writing creation code. We will offer patterns and helpers through the Aqueduct to make this easier to consume. SharedComponentFactory will come with a default createComponent that will emulate the existing flow provided by calling through the instantiateComponent flow. Developers can overwrite or extend the SharedComponentFactory to implement their own strongly typed create with props flow (See below for more)

The this.context.hostRuntime.createComponent(...) pattern will still be supported in the short term but quickly deprecated.

To improve the developer experience we will be cleaning up two other existing parts:

1. Adding type to IComponentFactory. This will allow us to have a cleaner registry pattern. We'll need to support backwards compatibility with existing named components.
2. Merging createComponent and createSubComponent.

Backwards compatibility

Since our components can be dynamically loaded we need to ensure that Components on older versions can still be loaded with the new patterns. Since this change will keep existing loading flows using the instantiateRuntime call flow for loading existing components we only need to worry about the component creation flow.

We can either provide guidance for how to create an old component or expose a helper function that will wrap the instantiateComponent function in the create call the same way SharedComponentFactory will.

Key Problem Spaces

Container Developers define ComponentFactory Mapping

Currently the Container developer is responsible for defining the string used in the Registry for finding the corresponding Factory. This is a problem because if we do something like MyComponentFactory.create(this.context); then the Factory needs to know the name of the registry entry. So, the actual syntax would look something like MyComponentFactory.create(this.context, "registry-package-name"); which is pretty ugly because you are defining that name of the thing you are calling.
It's especially ugly in the dynamic case where you do something like:

const factory = (await this.context.hostRuntime.IComponentRegistry.get("clicker-pkg-name")).IComponentFactory;
if (factory) {
const component = await factory.create(this.context, "clicker-pkg-name");
}

In the above scenario we needed to provide the package name to get the registry entry and the package name to create because it doesn't know it's own name.

To resolve this we can follow the same pattern as Distributed Data Structures and expose a type on the IComponentFactory. With this pattern instead of the Container developer being responsible to provide the type it will be on the ComponentFactory to provide it's type. The most obvious problem with this is ensuring uniqueness of types. For this we should provide guidance to name types after package names. Since package names should be unique in themselves and public ones are enforced by npmjs then we are leveraging existing. If you are exporting multiple components from the same package you can postfix the component name with a /{component name} (Ex. @fluid-example/vltava/tabs)

Since Registries can consist of Factories or other Registries we should additionally expose type on IComponentRegistry so they can follow the same pattern.

Q - Should there be an IComponentType base interface? or is it okay if they all just have a type?

Component Creation without Props

Current Pattern

const componentRuntime = await this.context.hostRuntime.createComponent(pkg, id);
componentRuntime.attach();

const response = await componentRuntime.request({ url: "/" });
if (response.status === 200 && response.mimeType === "fluid/component") {
  const clicker = response.value;
    this.root.set("unique-clicker-id", clicker.handle);
}

New Pattern

const clicker = await ClickerFactory.createComponent(this.context);
this.root.set("unique-clicker-id", clicker.handle);

Component Creation with Props

Because we know the factory we can have specific create functions with strong typing.

const clicker = await ClickerWithInitialValueFactory.createClickerComponent({initialValue: 100}, this.context);
this.root.set("unique-clicker-id", clicker.handle);

Dynamic case

All Components should be able to create without initial state. For the dynamic case we can't presume what we are loading so we can't pass in state. We use the registry to get
the ComponentFactory since we don't have it and we call create on it.

const factory = await this.context.hostRuntime.IComponentRegistry.get(ClickerName);
if (factory) {
  const component = await factory.createComponent(this.context);
  this.root.set("unique-clicker-id", component.handle);
}

[skylerjokiel]

Initial Draft PR #538

[skylerjokiel]

This works has been split into more manageable tasks and has been mostly completed. Closing.