@fluidframework/tree 2.111.0 → 2.112.0

package/CHANGELOG.md

@@ -1,5 +1,150 @@
 # @fluidframework/tree
 
+## 2.112.0
+
+### Minor Changes
+
+- Add Component utilities for composing open-polymorphic schema ([#27628](https://github.com/microsoft/FluidFramework/pull/27628)) [7a56d096bf](https://github.com/microsoft/FluidFramework/commit/7a56d096bffab133ab4e7ab9c8f9c465b7ba9e81)
+
+  A new `@alpha` `Component` namespace is now exported from `@fluidframework/tree` (and re-exported from `fluid-framework`). It provides utilities for composing independently authored application "components" that contribute to a shared configuration, which is useful for implementing ["open polymorphism"](<https://en.wikipedia.org/wiki/Polymorphism_(computer_science)>) schema patterns where the set of allowed types for a field or collection can be extended by separate libraries.
+
+  Each component is expressed as a `Component.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. `Component.compose` combines a set of components into a `Component.Composed`, from which the aggregated configuration and per-component content can be read.
+
+  ```typescript
+  /** Example application component content type. */
+  interface MyAppComponentContent {
+    /**
+     * Item types contributed by this component.
+     * We are just typing them as TreeNodeSchema here to keep things simple.
+     * Real use would often provide some static factory to be able to create instances, as well as some APIs all item nodes should implement.
+     */
+    readonly items: Component.LazyArray<TreeNodeSchema>;
+  }
+
+  type MyAppComponent = Component.Factory<MyAppComponentContent>;
+
+  // A simple component, which does not depend on any other context.
+  const textComponent: MyAppComponent = () => ({
+    items: () => [() => TextItem],
+  });
+
+  // A component which creates an item type which recursively depends on all item types.
+  const containerComponent: MyAppComponent = (config) => ({
+    items: () => [
+      () =>
+        class extends sf.array("Container", config().getComposed("items")) {},
+    ],
+  });
+
+  const appConfig = Component.compose([containerComponent, textComponent]);
+
+  // The config's items can now be used to create a TreeViewConfiguration, root schema, or whatever else is needed.
+  class Root extends sf.object("Root", {
+    content: appConfig.getComposed("items"),
+  }) {}
+  ```
+
+  See the worked examples in [openPolymorphism.integration.ts](https://github.com/microsoft/FluidFramework/blob/main/packages/dds/tree/src/test/openPolymorphism.integration.ts) for end-to-end usage with SharedTree schema.
+
+- Independent tree views now accept an optional telemetry logger ([#27567](https://github.com/microsoft/FluidFramework/pull/27567)) [5fbbcab0af](https://github.com/microsoft/FluidFramework/commit/5fbbcab0aff87519ae6f112611f0c1e62f30d97e)
+
+  The alpha `independentView`, `independentInitializedView`, and `createIndependentTreeAlpha` APIs now accept an optional `logger` on their options.
+  Previously these standalone (non-`SharedTree`) views had no way to surface telemetry,
+  so internal events—including those emitted when the tree enters a broken state—were dropped.
+  Passing a logger forwards those events to the caller's telemetry pipeline.
+  This makes it possible to diagnose failures in scenarios that use independent tree views, such as snapshot import/export, schema migration, and other out-of-container workflows.
+
+  Events emitted by an independent tree view are tagged with the `independentView` namespace.
+  If no logger is provided, behavior is unchanged and telemetry events continue to be dropped.
+
+  The `logger` option is typed as `ITelemetryBaseLogger` from `@fluidframework/core-interfaces`,
+  so any standard Fluid telemetry logger can be passed directly.
+
+  ```typescript
+  // ...
+  const view = independentView(
+    new TreeViewConfiguration({ schema: MySchema }),
+    {
+      logger: myTelemetryLogger,
+    },
+  );
+  // ...
+  ```
+
+- Shared branch names ([#27708](https://github.com/microsoft/FluidFramework/pull/27708)) [1f08b9210b](https://github.com/microsoft/FluidFramework/commit/1f08b9210bf7ba3adbc98c45b02ab8a6a58929f5)
+
+  The existing [`createSharedBranch`](https://fluidframework.com/docs/api/tree/itreealpha-interface#createsharedbranch-methodsignature) alpha API now takes an optional `name` string parameter that is associated with the shared branch.
+  This name can be retrieved by passing the shared branch ID to `getSharedBranchName`.
+
+  Note that, unlike the shared branch IDs, shared branch names are not guaranteed to be unique.
+
+  #### Compatibility Implications
+
+  This change breaks compatibility in the following ways:
+  - A document written by a client running an earlier FF version cannot be opened by a client running this version.
+  - A document written by a client running this version cannot be opened by a client running an earlier FF version.
+  - Clients running earlier FF versions will crash upon receiving ops from clients running this version.
+  - Clients running this version will crash upon receiving ops from clients running earlier FF versions.
+
+  These breaks are only applicable for clients with `enableSharedBranches` turned on. Other clients are unaffected.
+
+- Add at, pop, shift, unshift, findLast, and findLastIndex methods to TreeArrayNodeAlpha ([#27686](https://github.com/microsoft/FluidFramework/pull/27686)) [59669008b9](https://github.com/microsoft/FluidFramework/commit/59669008b9f9f70ccb94030a6382afcdf8f28cd4)
+
+  `TreeArrayNodeAlpha` now has `at`, `pop`, `shift`, `unshift`, `findLast`, and `findLastIndex` methods, further aligning it with JavaScript's built-in Array API:
+  - `at(index)` `at` was already implemented at runtime, and consumers compiling with `lib: ES2022` or later could already see it through the inherited `ReadonlyArray` typings. This change adds no new runtime behavior, but makes `at` an explicitly declared, documented part of the API, independent of the consumer's TypeScript `lib` configuration.
+  - `unshift(...items)` is an alias for `insertAtStart`, mirroring how `push` aliases `insertAtEnd`: it inserts new item(s) at the start of the array. Unlike `Array.prototype.unshift`, it does not return the new length of the array.
+  - `pop()` removes and returns the last item in the array, or returns `undefined` (without modifying the array) if it is empty.
+  - `shift()` removes and returns the first item in the array, or returns `undefined` (without modifying the array) if it is empty.
+  - `findLast(predicate, thisArg?)` and `findLastIndex(predicate, thisArg?)` search the array from the last item to the first, returning the last matching item (or `undefined`) and its index (or `-1`) respectively, like their `Array.prototype` equivalents. As with `Array.prototype.findLast`, passing a type guard as the `findLast` predicate narrows the returned item's type.
+
+  These methods are available on `TreeArrayNodeAlpha`, which can be obtained from an existing `TreeArrayNode` via `asAlpha`, or by declaring the schema with `SchemaFactoryAlpha`'s `arrayAlpha`.
+
+  #### Usage
+
+  ```typescript
+  import { SchemaFactory, asAlpha } from "@fluidframework/tree/alpha";
+
+  const sf = new SchemaFactory("example");
+  const Inventory = sf.array("Inventory", sf.string);
+  const inventory = asAlpha(new Inventory(["Apples", "Bananas", "Pears"]));
+
+  // inventory: ["Apples", "Bananas", "Pears"]
+  inventory.unshift("Oranges", "Grapes");
+  // inventory: ["Oranges", "Grapes", "Apples", "Bananas", "Pears"]
+
+  inventory.at(0); // "Oranges"
+  inventory.at(-1); // "Pears"
+  inventory.at(10); // undefined
+
+  inventory.findLast((item) => item.startsWith("G")); // "Grapes"
+  inventory.findLastIndex((item) => item.startsWith("G")); // 1
+
+  // inventory: ["Oranges", "Grapes", "Apples", "Bananas", "Pears"]
+  inventory.pop(); // "Pears"
+  // inventory ["Oranges", "Grapes", "Apples", "Bananas"]
+
+  inventory.shift(); // "Oranges"
+  // inventory: ["Grapes", "Apples", "Bananas"]
+  ```
+
+- Retain history option ([#27696](https://github.com/microsoft/FluidFramework/pull/27696)) [2fa44c6ed2](https://github.com/microsoft/FluidFramework/commit/2fa44c6ed222a8ed88a632a0bf3cad0c26e72514)
+
+  Adds a new `retainHistory` flag to [`SharedTreeOptions`](https://fluidframework.com/docs/api/tree/sharedtreeoptions-interface) (defaults to `false`).
+  Setting `retainHistory` to `true` will prevent SharedTree from garbage-collecting historical data about old changes.
+  Note that this will cause unbounded growth both in memory on the client and in summaries/snapshots (the at-rest data representing a Fluid document).
+  For these reasons, this option is only intended for debugging and experimentation.
+
+### Patch Changes
+
+- Fix insertable types when using typesRecursive with multiple allowed types ([#27698](https://github.com/microsoft/FluidFramework/pull/27698)) [b72f836d09](https://github.com/microsoft/FluidFramework/commit/b72f836d09437654e0ef5787625073f9da41cf9f)
+
+  The allowed types produced by `SchemaFactoryBeta.typesRecursive` (and `SchemaFactoryAlpha.typesRecursive`) are now processed correctly when used in a recursive schema that permits more than one type.
+
+  Previously, passing their output to a recursive schema (for example `factory.arrayRecursive` or `factory.mapRecursive`) computed the node's insertable content type as `never`.
+  This caused valid insertions to fail to compile.
+  Recursive schemas built from a `typesRecursive` list with two or more types now accept insertable content for each of the allowed types as expected.
+  Recursive schemas that use a single type were unaffected.
+
 ## 2.111.0
 
 ### Minor Changes

package/api-report/tree.alpha.api.md

@@ -218,6 +218,31 @@ export interface CommitMetadata {
 // @alpha
 export function comparePersistedSchema(persisted: JsonCompatible, view: ImplicitFieldSchema, options: ICodecOptions): Omit<SchemaCompatibilityStatus, "canInitialize">;
 
+// @alpha
+export namespace Component {
+    export function compose<TComponent>(allComponents: readonly Factory<TComponent>[]): Composed<TComponent>;
+    export function compose<TComponent, TConfig>(allComponents: readonly Factory<TComponent, TConfig>[], lazyConfiguration: (composed: Composed<TComponent, TConfig>) => TConfig): Composed<TComponent, TConfig>;
+    const memoize: <T>(factory: () => T) => (() => T);
+    // @sealed
+    export interface Composed<TComponent, TConfig = ComposedDefault<TComponent>> {
+        readonly components: readonly TComponent[];
+        readonly config: TConfig;
+        getComponent<TFactory extends Factory<TComponent, TConfig>>(factory: TFactory): ReturnType<TFactory>;
+        getComposed<TKey extends keyof {
+            [Property in keyof TComponent as TComponent[Property] extends LazyArray<unknown> | undefined ? Property : never]: boolean;
+        }>(property: TKey): readonly (Exclude<TComponent[TKey], undefined> extends LazyArray<infer U> ? () => U : never)[];
+        getConfigured<TConfigurable extends Configurable<TConfig, unknown, TComponent>>(configurable: TConfigurable): ReturnType<TConfigurable["configure"]>;
+    }
+    // @sealed
+    export type ComposedDefault<TComponent> = Composed<TComponent, ComposedDefault<TComponent>>;
+    export interface Configurable<TConfigPartial, out TResult, TComponent> {
+        configure(config: TConfigPartial, components: Composed<TComponent, TConfigPartial>): TResult;
+    }
+    // @input
+    export type Factory<TComponent, TConfig = ComposedDefault<TComponent>> = (lazyConfiguration: () => TConfig) => TComponent;
+    export type LazyArray<T> = () => readonly (() => T)[];
+}
+
 // @beta
 export type ConciseTree<THandle = IFluidHandle> = Exclude<TreeLeafValue, IFluidHandle> | THandle | ConciseTree<THandle>[] | {
     [key: string]: ConciseTree<THandle>;
@@ -242,7 +267,7 @@ export function createIdentifierIndex<TSchema extends ImplicitFieldSchema>(view:
 export function createIndependentTreeAlpha<const TSchema extends ImplicitFieldSchema>(options?: CreateIndependentTreeAlphaOptions): ViewableTree & Pick<ITreeAlpha, "exportVerbose" | "exportSimpleSchema">;
 
 // @alpha
-export type CreateIndependentTreeAlphaOptions = ForestOptions & ((IndependentViewOptions & {
+export type CreateIndependentTreeAlphaOptions = ForestOptions & IndependentViewTelemetryOptions & ((IndependentViewOptions & {
     content?: never;
 }) | (ICodecOptions & {
     content: ViewContent;
@@ -538,16 +563,21 @@ export function incrementalEncodingPolicyForAllowedTypes(rootSchema: TreeSchema)
 export const incrementalSummaryHint: unique symbol;
 
 // @alpha
-export function independentInitializedView<const TSchema extends ImplicitFieldSchema>(config: TreeViewConfiguration<TSchema>, options: ForestOptions & ICodecOptions, content: ViewContent): TreeViewAlpha<TSchema>;
+export function independentInitializedView<const TSchema extends ImplicitFieldSchema>(config: TreeViewConfiguration<TSchema>, options: ForestOptions & ICodecOptions & IndependentViewTelemetryOptions, content: ViewContent): TreeViewAlpha<TSchema>;
 
 // @alpha
 export function independentView<const TSchema extends ImplicitFieldSchema>(config: TreeViewConfiguration<TSchema>, options?: IndependentViewOptions): TreeViewAlpha<TSchema>;
 
 // @alpha @input
-export interface IndependentViewOptions extends ForestOptions, Partial<CodecWriteOptions> {
+export interface IndependentViewOptions extends ForestOptions, Partial<CodecWriteOptions>, IndependentViewTelemetryOptions {
     idCompressor?: IIdCompressor | undefined;
 }
 
+// @alpha @input
+export interface IndependentViewTelemetryOptions {
+    readonly logger?: ITelemetryBaseLogger | undefined;
+}
+
 // @public @system
 type _InlineTrick = 0;
 
@@ -648,10 +678,11 @@ export interface ITree extends ViewableTree, IFluidLoadable {
 
 // @alpha @sealed
 export interface ITreeAlpha extends ITree {
-    createSharedBranch(): string;
+    createSharedBranch(name?: string): string;
     exportSimpleSchema(): SimpleTreeSchema;
     exportVerbose(): VerboseTree | undefined;
     getSharedBranchIds(): string[];
+    getSharedBranchName(branchId: string): string | undefined;
     viewSharedBranchWith<TRoot extends ImplicitFieldSchema>(branchId: string, config: TreeViewConfiguration<TRoot>): TreeView<TRoot>;
 }
 
@@ -844,6 +875,9 @@ export const MapNodeSchema: {
     readonly [Symbol.hasInstance]: (value: TreeNodeSchema) => value is MapNodeSchema;
 };
 
+// @alpha @deprecated
+export const minimize: TransactionPostProcessor;
+
 // @alpha
 export interface NoChangeConstraint {
     // (undocumented)
@@ -1248,6 +1282,7 @@ export interface SharedTreeFormatOptions {
 // @alpha @input
 export interface SharedTreeOptions extends SharedTreeOptionsBeta, Partial<CodecWriteOptions>, Partial<SharedTreeFormatOptions> {
     readonly enableSharedBranches?: boolean;
+    readonly retainHistory?: boolean;
     shouldEncodeIncrementally?: IncrementalEncodingPolicy;
 }
 
@@ -1454,7 +1489,7 @@ export namespace System_Unsafe {
     // @system
     export type InsertableTreeNodeFromAllowedTypesUnsafe<TList extends AllowedTypesUnsafe> = IsUnion<TList> extends true ? never : {
         readonly [Property in keyof TList]: TList[Property] extends LazyItem<infer TSchema extends TreeNodeSchemaUnsafe> ? InsertableTypedNodeUnsafe<TSchema> : never;
-    }[number];
+    }[NumberKeys<TList>];
     // @system
     export type InsertableTreeNodeFromImplicitAllowedTypesUnsafe<TSchema extends ImplicitAllowedTypesUnsafe> = [TSchema] extends [TreeNodeSchemaUnsafe] ? InsertableTypedNodeUnsafe<TSchema> : [TSchema] extends [AllowedTypesUnsafe] ? InsertableTreeNodeFromAllowedTypesUnsafe<TSchema> : never;
     // @system
@@ -1749,7 +1784,14 @@ export const TreeArrayNode: {
 
 // @alpha @sealed
 export interface TreeArrayNodeAlpha<TAllowedTypes extends System_Unsafe.ImplicitAllowedTypesUnsafe = ImplicitAllowedTypes, out T = [TAllowedTypes] extends [ImplicitAllowedTypes] ? TreeNodeFromImplicitAllowedTypes<TAllowedTypes> : TreeNodeFromImplicitAllowedTypes<ImplicitAllowedTypes>, in TNew = [TAllowedTypes] extends [ImplicitAllowedTypes] ? InsertableTreeNodeFromImplicitAllowedTypes<TAllowedTypes> : InsertableTreeNodeFromImplicitAllowedTypes<ImplicitAllowedTypes>> extends TreeArrayNode<TAllowedTypes, T, TNew> {
+    at(index: number): T | undefined;
+    findLast<S extends T>(predicate: (value: T, index: number, array: readonly T[]) => value is S, thisArg?: unknown): S | undefined;
+    findLast(predicate: (value: T, index: number, array: readonly T[]) => unknown, thisArg?: unknown): T | undefined;
+    findLastIndex(predicate: (value: T, index: number, array: readonly T[]) => unknown, thisArg?: unknown): number;
+    pop(): T | undefined;
+    shift(): T | undefined;
     splice(start: number, deleteCount?: number, ...items: readonly (TNew | IterableTreeArrayContent<TNew>)[]): T[];
+    unshift(...value: readonly (TNew | IterableTreeArrayContent<TNew>)[]): void;
 }
 
 // @beta @sealed
@@ -1776,6 +1818,7 @@ export interface TreeBranch extends IDisposable {
 // @alpha @sealed
 export interface TreeBranchAlpha extends TreeBranch, TreeContextAlpha {
     applyChange(change: JsonCompatibleReadOnly): void;
+    computeNetChangeIfRebasedOnto(branch: TreeBranch): JsonCompatibleReadOnly | undefined;
     readonly events: Listenable_2<TreeBranchEvents>;
     // (undocumented)
     fork(): TreeBranchAlpha;

package/api-report/tree.beta.api.md

@@ -737,7 +737,7 @@ export namespace System_Unsafe {
     // @system
     export type InsertableTreeNodeFromAllowedTypesUnsafe<TList extends AllowedTypesUnsafe> = IsUnion<TList> extends true ? never : {
         readonly [Property in keyof TList]: TList[Property] extends LazyItem<infer TSchema extends TreeNodeSchemaUnsafe> ? InsertableTypedNodeUnsafe<TSchema> : never;
-    }[number];
+    }[NumberKeys<TList>];
     // @system
     export type InsertableTreeNodeFromImplicitAllowedTypesUnsafe<TSchema extends ImplicitAllowedTypesUnsafe> = [TSchema] extends [TreeNodeSchemaUnsafe] ? InsertableTypedNodeUnsafe<TSchema> : [TSchema] extends [AllowedTypesUnsafe] ? InsertableTreeNodeFromAllowedTypesUnsafe<TSchema> : never;
     // @system

package/api-report/tree.legacy.beta.api.md

@@ -749,7 +749,7 @@ export namespace System_Unsafe {
     // @system
     export type InsertableTreeNodeFromAllowedTypesUnsafe<TList extends AllowedTypesUnsafe> = IsUnion<TList> extends true ? never : {
         readonly [Property in keyof TList]: TList[Property] extends LazyItem<infer TSchema extends TreeNodeSchemaUnsafe> ? InsertableTypedNodeUnsafe<TSchema> : never;
-    }[number];
+    }[NumberKeys<TList>];
     // @system
     export type InsertableTreeNodeFromImplicitAllowedTypesUnsafe<TSchema extends ImplicitAllowedTypesUnsafe> = [TSchema] extends [TreeNodeSchemaUnsafe] ? InsertableTypedNodeUnsafe<TSchema> : [TSchema] extends [AllowedTypesUnsafe] ? InsertableTreeNodeFromAllowedTypesUnsafe<TSchema> : never;
     // @system

package/api-report/tree.legacy.public.api.md

@@ -391,7 +391,7 @@ export namespace System_Unsafe {
     // @system
     export type InsertableTreeNodeFromAllowedTypesUnsafe<TList extends AllowedTypesUnsafe> = IsUnion<TList> extends true ? never : {
         readonly [Property in keyof TList]: TList[Property] extends LazyItem<infer TSchema extends TreeNodeSchemaUnsafe> ? InsertableTypedNodeUnsafe<TSchema> : never;
-    }[number];
+    }[NumberKeys<TList>];
     // @system
     export type InsertableTreeNodeFromImplicitAllowedTypesUnsafe<TSchema extends ImplicitAllowedTypesUnsafe> = [TSchema] extends [TreeNodeSchemaUnsafe] ? InsertableTypedNodeUnsafe<TSchema> : [TSchema] extends [AllowedTypesUnsafe] ? InsertableTreeNodeFromAllowedTypesUnsafe<TSchema> : never;
     // @system

package/api-report/tree.public.api.md

@@ -391,7 +391,7 @@ export namespace System_Unsafe {
     // @system
     export type InsertableTreeNodeFromAllowedTypesUnsafe<TList extends AllowedTypesUnsafe> = IsUnion<TList> extends true ? never : {
         readonly [Property in keyof TList]: TList[Property] extends LazyItem<infer TSchema extends TreeNodeSchemaUnsafe> ? InsertableTypedNodeUnsafe<TSchema> : never;
-    }[number];
+    }[NumberKeys<TList>];
     // @system
     export type InsertableTreeNodeFromImplicitAllowedTypesUnsafe<TSchema extends ImplicitAllowedTypesUnsafe> = [TSchema] extends [TreeNodeSchemaUnsafe] ? InsertableTypedNodeUnsafe<TSchema> : [TSchema] extends [AllowedTypesUnsafe] ? InsertableTreeNodeFromAllowedTypesUnsafe<TSchema> : never;
     // @system

package/dist/componentApi.d.ts

@@ -0,0 +1,198 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+/**
+ * Utilities for composing application "components" which contribute to a shared configuration.
+ *
+ * @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 {@link 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
+ * {@link AllowedTypes} array).
+ *
+ * Each component is expressed as a {@link Component.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 {@link Component.(compose:1)} to combine a set of components into a {@link Component.Composed}.
+ *
+ * See {@link https://github.com/microsoft/FluidFramework/blob/main/packages/dds/tree/src/test/openPolymorphism.integration.ts|openPolymorphism.integration.ts} for worked examples of this pattern.
+ *
+ * @privateRemarks
+ * The examples and integration tests for this pattern live in `openPolymorphism.integration.ts`.
+ * Those tests and the docs here should be kept in sync.
+ *
+ * @alpha
+ */
+export declare namespace Component {
+    /**
+     * A function which takes in a lazy configuration and returns the content a component contributes.
+     *
+     * @remarks
+     * The lazy configuration allows the component to reference items from the composed configuration, which can
+     * include items the component itself contributes (allowing recursive references between components).
+     *
+     * The execution of the factory must not evaluate `lazyConfiguration` (doing so will error):
+     * instead the returned `TComponent` can capture `lazyConfiguration` and evaluate it at a later time
+     * (after all components have been composed).
+     *
+     * @typeParam TComponent - The content a component contributes.
+     * @typeParam TConfig - The composed configuration type made available to components.
+     * Defaults to the {@link Component.Composed} produced by composition: the common case where
+     * components read composed content directly from the composition and no custom configuration type is needed.
+     *
+     * @input
+     * @alpha
+     */
+    type Factory<TComponent, TConfig = ComposedDefault<TComponent>> = (lazyConfiguration: () => TConfig) => TComponent;
+    /**
+     * A function which returns an array of lazy values which each evaluate to `T`.
+     *
+     * @remarks
+     * This mirrors the shape of {@link AllowedTypes} where all of the values are lazy:
+     * the outer function and inner functions defer evaluation until after composition is complete.
+     *
+     * @typeParam T - The type each lazy value evaluates to.
+     *
+     * @alpha
+     */
+    type LazyArray<T> = () => readonly (() => T)[];
+    /**
+     * Wrap a 0 argument function to cache the result.
+     * @remarks
+     * Do not use for impure functions.
+     *
+     * Generally {@link 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 {@link evaluateLazySchema} where the function evaluation is done using a utility that adds caching.
+     *
+     * @param factory - The factory function to memoize.
+     * @returns A function that returns the cached result of the factory.
+     * @alpha
+     */
+    const memoize: <T>(factory: () => T) => (() => T);
+    /**
+     * An item which can be configured (evaluated) against a composed configuration to produce a result.
+     *
+     * @remarks
+     * Use {@link Component.Composed.getConfigured} to evaluate a `Configurable`.
+     * The result is cached, so a given `Configurable` is only evaluated once per composition.
+     *
+     * @typeParam TConfigPartial - The configuration type made available when configuring.
+     * @typeParam TResult - The result produced by configuring.
+     * @typeParam TComponent - The content components contribute.
+     *
+     * @alpha
+     */
+    interface Configurable<TConfigPartial, out TResult, TComponent> {
+        /**
+         * Produce the configured result.
+         * @param config - The composed configuration.
+         * @param components - The composed components.
+         */
+        configure(config: TConfigPartial, components: Composed<TComponent, TConfigPartial>): TResult;
+    }
+    /**
+     * Combine multiple {@link Component.Factory|components} into a single {@link Component.Composed}.
+     *
+     * @remarks
+     * The {@link Component.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.
+     *
+     * @param allComponents - The components to compose.
+     * @returns The composed components, from which configuration and per-component content can be read.
+     *
+     * @typeParam TComponent - The content each component contributes.
+     *
+     * @alpha
+     */
+    function compose<TComponent>(allComponents: readonly Factory<TComponent>[]): Composed<TComponent>;
+    /**
+     * Combine multiple {@link Component.Factory|components} into a single {@link Component.Composed}.
+     *
+     * @param allComponents - The components to compose.
+     * @param lazyConfiguration - 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 {@link Component.Composed.getComposed}).
+     * @returns The composed components, from which configuration and per-component content can be read.
+     *
+     * @typeParam TComponent - The content each component contributes.
+     * @typeParam TConfig - The composed configuration type made available to components.
+     *
+     * @alpha
+     */
+    function compose<TComponent, TConfig>(allComponents: readonly Factory<TComponent, TConfig>[], lazyConfiguration: (composed: Composed<TComponent, TConfig>) => TConfig): Composed<TComponent, TConfig>;
+    /**
+     * The default configuration type for a composition.
+     * Also the type of Composed when using the default composition.
+     * @privateRemarks
+     * Declaring this as its own type makes the recursion possible instead of having to list the config parameter as unknown.
+     * This makes it easier to understand what is going on when seeing this type in the intellisense.
+     * @sealed @alpha
+     */
+    type ComposedDefault<TComponent> = Composed<TComponent, ComposedDefault<TComponent>>;
+    /**
+     * The result of composing multiple components.
+     *
+     * @remarks
+     * Create using {@link Component.(compose:1)}.
+     *
+     * @typeParam TComponent - The content each component contributes.
+     * @typeParam TConfig - The composed configuration type made available to components.
+     * Defaults to the composition itself: the common case where no custom configuration type is needed.
+     *
+     * @sealed @alpha
+     */
+    interface Composed<TComponent, TConfig = ComposedDefault<TComponent>> {
+        /**
+         * The components which were composed.
+         */
+        readonly components: readonly TComponent[];
+        /**
+         * The configuration which was produced when composing.
+         */
+        readonly config: TConfig;
+        /**
+         * Get a component by its factory.
+         *
+         * @param factory - The factory used to look up the component. Must have been provided when composing.
+         * @returns The content created by the provided factory.
+         * This result is cached during composition and not reevaluated.
+         */
+        getComponent<TFactory extends Factory<TComponent, TConfig>>(factory: TFactory): ReturnType<TFactory>;
+        /**
+         * Configure a {@link Component.Configurable}.
+         * @remarks
+         * The result is cached when first evaluated, so subsequent calls with the same `configurable` return the
+         * same result.
+         * @param configurable - The item to configure against this composition.
+         */
+        getConfigured<TConfigurable extends Configurable<TConfig, unknown, TComponent>>(configurable: TConfigurable): ReturnType<TConfigurable["configure"]>;
+        /**
+         * Compose the contents of a {@link Component.LazyArray} property from all components.
+         * @remarks
+         * The result is cached when first evaluated, so subsequent calls with the same `property` return the
+         * same result.
+         * @param property - The property of the components to compose.
+         * @returns The concatenation of the lazy values contributed by each component for `property`.
+         * Components which omit the property contribute nothing.
+         */
+        getComposed<TKey extends keyof {
+            [Property in keyof TComponent as TComponent[Property] extends LazyArray<unknown> | undefined ? Property : never]: boolean;
+        }>(property: TKey): readonly (Exclude<TComponent[TKey], undefined> extends LazyArray<infer U> ? () => U : never)[];
+    }
+}
+//# sourceMappingURL=componentApi.d.ts.map

package/dist/componentApi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"componentApi.d.ts","sourceRoot":"","sources":["../src/componentApi.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,yBAAiB,SAAS,CAAC;IAC1B;;;;;;;;;;;;;;;;;;OAkBG;IACH,KAAY,OAAO,CAAC,UAAU,EAAE,OAAO,GAAG,eAAe,CAAC,UAAU,CAAC,IAAI,CACxE,iBAAiB,EAAE,MAAM,OAAO,KAC5B,UAAU,CAAC;IAEhB;;;;;;;;;;OAUG;IACH,KAAY,SAAS,CAAC,CAAC,IAAI,MAAM,SAAS,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC;IAEtD;;;;;;;;;;;;;OAaG;IACI,MAAM,OAAO,eAAgB,MAAM,CAAC,KAAG,CAAC,MAAM,CAAC,CAUrD,CAAC;IAEF;;;;;;;;;;;;OAYG;IACH,UAAiB,YAAY,CAAC,cAAc,EAAE,GAAG,CAAC,OAAO,EAAE,UAAU;QACpE;;;;WAIG;QACH,SAAS,CACR,MAAM,EAAE,cAAc,EACtB,UAAU,EAAE,QAAQ,CAAC,UAAU,EAAE,cAAc,CAAC,GAC9C,OAAO,CAAC;KACX;IAuGD;;;;;;;;;;;;;;OAcG;IACH,SAAgB,OAAO,CAAC,UAAU,EACjC,aAAa,EAAE,SAAS,OAAO,CAAC,UAAU,CAAC,EAAE,GAC3C,QAAQ,CAAC,UAAU,CAAC,CAAC;IACxB;;;;;;;;;;;;;OAaG;IACH,SAAgB,OAAO,CAAC,UAAU,EAAE,OAAO,EAC1C,aAAa,EAAE,SAAS,OAAO,CAAC,UAAU,EAAE,OAAO,CAAC,EAAE,EACtD,iBAAiB,EAAE,CAAC,QAAQ,EAAE,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC,KAAK,OAAO,GACrE,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;IASjC;;;;;;;OAOG;IACH,KAAY,eAAe,CAAC,UAAU,IAAI,QAAQ,CAAC,UAAU,EAAE,eAAe,CAAC,UAAU,CAAC,CAAC,CAAC;IAE5F;;;;;;;;;;;OAWG;IACH,UAAiB,QAAQ,CAAC,UAAU,EAAE,OAAO,GAAG,eAAe,CAAC,UAAU,CAAC;QAC1E;;WAEG;QACH,QAAQ,CAAC,UAAU,EAAE,SAAS,UAAU,EAAE,CAAC;QAE3C;;WAEG;QACH,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;QAEzB;;;;;;WAMG;QACH,YAAY,CAAC,QAAQ,SAAS,OAAO,CAAC,UAAU,EAAE,OAAO,CAAC,EACzD,OAAO,EAAE,QAAQ,GACf,UAAU,CAAC,QAAQ,CAAC,CAAC;QAExB;;;;;;WAMG;QACH,aAAa,CAAC,aAAa,SAAS,YAAY,CAAC,OAAO,EAAE,OAAO,EAAE,UAAU,CAAC,EAC7E,YAAY,EAAE,aAAa,GACzB,UAAU,CAAC,aAAa,CAAC,WAAW,CAAC,CAAC,CAAC;QAE1C;;;;;;;;WAQG;QACH,WAAW,CACV,IAAI,SAAS,MAAM;aACjB,QAAQ,IAAI,MAAM,UAAU,IAAI,UAAU,CAAC,QAAQ,CAAC,SAClD,SAAS,CAAC,OAAO,CAAC,GAClB,SAAS,GACT,QAAQ,GACR,KAAK,GAAG,OAAO;SAClB,EAED,QAAQ,EAAE,IAAI,GACZ,SAAS,CAAC,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,SAAS,CAAC,SAAS,SAAS,CAAC,MAAM,CAAC,CAAC,GACzE,MAAM,CAAC,GACP,KAAK,CAAC,EAAE,CAAC;KACZ;CACD"}