Component Namespace
Utilities for composing application "components" which contribute to a shared configuration.
To use, import via fluid-framework/alpha.
For more information about our API support guarantees, see here.
Signature
export declare namespace Component
Remarks
Nothing in this namespace is specific to tree schema, however it is designed to be able to handle the needs of components which work with TreeSchema.
This is mainly used to implement "open polymorphism", where the set of allowed types for a field or collection can be extended by independently authored libraries (components) instead of being fixed up front.
This basically amounts to dependency injection, where the "injection" is done at "composition" time to build the schema.
Tree's schema do not natively support open polymorphism: all possible implementations must be explicitly listed. These tools work around these limitations by carefully controlling evaluation order: the source code can be structured in an open polymorphism style which at runtime evaluates into closed polymorphism by having each component register its implementations into a central collection (typically an AllowedTypes array).
Each component is expressed as a Factory: a function which receives a lazy reference to the composed configuration and returns the content that component contributes. Because the configuration is provided lazily, components may reference (including recursively) types contributed by other components, as long as nothing evaluates the lazy references until composition has completed. Use compose(allComponents) to combine a set of components into a Composed.
See openPolymorphism.integration.ts for worked examples of this pattern.
Interfaces
| Interface | Alerts | Modifiers | Description |
|---|---|---|---|
| Composed | Alpha | sealed | The result of composing multiple components. |
| Configurable | Alpha | An item which can be configured (evaluated) against a composed configuration to produce a result. |
Types
| TypeAlias | Alerts | Modifiers | Description |
|---|---|---|---|
| ComposedDefault | Alpha | sealed | The default configuration type for a composition. Also the type of Composed when using the default composition. |
| Factory | Alpha | A function which takes in a lazy configuration and returns the content a component contributes. | |
| LazyArray | Alpha | A function which returns an array of lazy values which each evaluate to T. |
Functions
| Function | Alerts | Return Type | Description |
|---|---|---|---|
| compose(allComponents) | Alpha | Composed<TComponent> | Combine multiple components into a single Composed. |
| compose(allComponents, lazyConfiguration) | Alpha | Composed<TComponent, TConfig> | Combine multiple components into a single Composed. |
| memoize(factory) | Alpha | (() => T) | Wrap a 0 argument function to cache the result. |
Function Details
compose
Combine multiple components into a single Composed.
For more information about our API support guarantees, see here.
Signature
function compose<TComponent>(allComponents: readonly Factory<TComponent>[]): Composed<TComponent>;
Type Parameters
| Parameter | Description |
|---|---|
| TComponent | The content each component contributes. |
Remarks
The Composed itself is used as the configuration made available to components: the simple case where components read composed content directly from the composition. To produce a custom aggregated configuration, use the overload which takes a lazyConfiguration builder.
Parameters
| Parameter | Type | Description |
|---|---|---|
| allComponents | readonly Factory<TComponent>[] | The components to compose. |
Returns
The composed components, from which configuration and per-component content can be read.
Return type: Composed<TComponent>
compose
Combine multiple components into a single Composed.
For more information about our API support guarantees, see here.
Signature
function compose<TComponent, TConfig>(allComponents: readonly Factory<TComponent, TConfig>[], lazyConfiguration: (composed: Composed<TComponent, TConfig>) => TConfig): Composed<TComponent, TConfig>;
Type Parameters
| Parameter | Description |
|---|---|
| TComponent | The content each component contributes. |
| TConfig | The composed configuration type made available to components. |
Parameters
| Parameter | Type | Description |
|---|---|---|
| allComponents | readonly Factory<TComponent, TConfig>[] | The components to compose. |
| lazyConfiguration | (composed: Composed<TComponent, TConfig>) => TConfig | Builds the composed configuration from the composed components. This is invoked once, after all components have been created, and can aggregate content contributed by the components (for example via getComposed(property)). |
Returns
The composed components, from which configuration and per-component content can be read.
Return type: Composed<TComponent, TConfig>
memoize
Wrap a 0 argument function to cache the result.
For more information about our API support guarantees, see here.
Signature
memoize: <T>(factory: () => T) => (() => T)
Type Parameters
| Parameter | Description |
|---|---|
| T |
Remarks
Do not use for impure functions.
Generally Component utilities have built in caching in most cases, but this is occasionally helpful when manually implementing laziness.
Note that this takes a different approach than use in evaluateLazySchema(value) where the function evaluation is done using a utility that adds caching.
Parameters
| Parameter | Type | Description |
|---|---|---|
| factory | () => T | The factory function to memoize. |
Returns
A function that returns the cached result of the factory.
Return type: (() => T)