Skip to content

Commit 62969ad

Browse files
CraigMacomberCraigMacomber
authored
ExtensibleUnionNode API renames (microsoft#26393)
## Description Apply feedback from API review for ExtensibleUnionNode ## Breaking Changes Users of this alpha API will need to update their API use and documents.
1 parent a0b52db commit 62969ad

File tree

6 files changed

+39
-43
lines changed

6 files changed

+39
-43
lines changed

‎packages/dds/tree/api-report/tree.alpha.api.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -275,10 +275,10 @@ export function evaluateLazySchema<T extends TreeNodeSchema>(value: LazyItem<T>)
275275
export function exportCompatibilitySchemaSnapshot(config: Pick<TreeViewConfiguration, "schema">): JsonCompatibleReadOnly;
276276

277277
// @alpha
278-
export namespace ExtensibleSchemaUnion {
279-
export function extensibleSchemaUnion<const T extends readonly TreeNodeSchema[], const TScope extends string, const TName extends string>(types: T, inputSchemaFactory: SchemaFactoryBeta<TScope>, name: TName): Statics<T> & TreeNodeSchemaCore_2<ScopedSchemaName_2<`com.fluidframework.extensibleSchemaUnion<${TScope}>`, TName>, NodeKind_2, false, unknown, never, unknown> & (new (data: InternalTreeNode_2) => Members<TreeNodeFromImplicitAllowedTypes<T>> & TreeNode_2 & WithType_2<ScopedSchemaName_2<`com.fluidframework.extensibleSchemaUnion<${TScope}>`, TName>, NodeKind_2, unknown>);
278+
export namespace ExtensibleUnionNode {
279+
export function createSchema<const T extends readonly TreeNodeSchema[], const TScope extends string, const TName extends string>(types: T, inputSchemaFactory: SchemaFactoryBeta<TScope>, name: TName): Statics<T> & TreeNodeSchemaCore_2<ScopedSchemaName_2<`com.fluidframework.extensibleUnionNode<${TScope}>`, TName>, NodeKind_2, false, unknown, never, unknown> & (new (data: InternalTreeNode_2) => Members<TreeNodeFromImplicitAllowedTypes<T>> & TreeNode_2 & WithType_2<ScopedSchemaName_2<`com.fluidframework.extensibleUnionNode<${TScope}>`, TName>, NodeKind_2, unknown>);
280280
export interface Members<T> {
281-
readonly child: T | undefined;
281+
readonly union: T | undefined;
282282
}
283283
export interface Statics<T extends readonly TreeNodeSchema[]> {
284284
create<TThis extends TreeNodeSchema>(this: TThis, child: TreeNodeFromImplicitAllowedTypes<T>): TreeFieldFromImplicitField<TThis>;

packages/dds/tree/src/extensibleSchemaUnion.ts renamed to packages/dds/tree/src/extensibleUnionNode.ts

Lines changed: 15 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -21,9 +21,9 @@ import {
2121
import type { UnionToIntersection } from "./util/index.js";
2222

2323
/**
24-
* Utilities for creating extensible schema unions.
24+
* Utilities for creating extensible unions using a node.
2525
* @remarks
26-
* Use {@link ExtensibleSchemaUnion.extensibleSchemaUnion} to create the union schema.
26+
* Use {@link ExtensibleUnionNode.createSchema} to create the union schema.
2727
*
2828
* Unlike a schema union created using {@link SchemaStaticsBeta.staged | staged} allowed types, this union allows for unknown future types to exist in addition to the known types.
2929
* This allows for faster roll-outs of new types without waiting for old clients to be updated to be aware of them.
@@ -35,41 +35,41 @@ import type { UnionToIntersection } from "./util/index.js";
3535
*
3636
* @example
3737
* ```typescript
38-
* const sf = new SchemaFactoryBeta("extensibleSchemaUnionExample.items");
38+
* const sf = new SchemaFactoryBeta("extensibleUnionNodeExample.items");
3939
* class ItemA extends sf.object("A", { x: sf.string }) {}
4040
* class ItemB extends sf.object("B", { x: sf.number }) {}
4141
*
42-
* class AnyItem extends ExtensibleSchemaUnion.extensibleSchemaUnion(
42+
* class AnyItem extends ExtensibleUnionNode.createSchema(
4343
* [ItemA, ItemB], // Future versions may add more members here
4444
* sf,
4545
* "ExtensibleUnion",
4646
* ) {}
4747
* // Instances of the union are created using `create`.
4848
* const anyItem = AnyItem.create(new ItemA({ x: "hello" }));
49-
* // Reading the content from the union is done via `child`,
49+
* // Reading the content from the union is done via the `union` property,
5050
* // which can be `undefined` to handle the case where a future version of this schema allows a type unknown to the current version.
51-
* const childNode: ItemA | ItemB | undefined = anyItem.child;
51+
* const childNode: ItemA | ItemB | undefined = anyItem.union;
5252
* // To determine which member of the union was present, its schema can be inspected:
5353
* const aSchema = Tree.schema(childNode ?? assert.fail("No child"));
5454
* assert.equal(aSchema, ItemA);
5555
* ```
5656
* @alpha
5757
*/
58-
export namespace ExtensibleSchemaUnion {
58+
export namespace ExtensibleUnionNode {
5959
/**
60-
* Members for classes created by {@link ExtensibleSchemaUnion.extensibleSchemaUnion}.
60+
* Members for classes created by {@link ExtensibleUnionNode.createSchema}.
6161
* @alpha
6262
*/
6363
export interface Members<T> {
6464
/**
65-
* The child wrapped by this node, which is has one of the type allowed by the union,
65+
* The child wrapped by this node has one of the types allowed by the union,
6666
* or `undefined` if the type is one which was added to the union by a future version of this schema.
6767
*/
68-
readonly child: T | undefined;
68+
readonly union: T | undefined;
6969
}
7070

7171
/**
72-
* Statics for classes created by {@link ExtensibleSchemaUnion.extensibleSchemaUnion}.
72+
* Statics for classes created by {@link ExtensibleUnionNode.createSchema}.
7373
* @alpha
7474
*/
7575
export interface Statics<T extends readonly TreeNodeSchema[]> {
@@ -86,11 +86,11 @@ export namespace ExtensibleSchemaUnion {
8686
* Create an extensible schema union which currently supports the types in `types`,
8787
* but tolerates collaboration with future versions that may include additional types.
8888
* @remarks
89-
* See {@link ExtensibleSchemaUnion} for an example use.
89+
* See {@link ExtensibleUnionNode} for an example use.
9090
* @alpha
9191
*/
9292
// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
93-
export function extensibleSchemaUnion<
93+
export function createSchema<
9494
const T extends readonly TreeNodeSchema[],
9595
const TScope extends string,
9696
const TName extends string,
@@ -101,13 +101,13 @@ export namespace ExtensibleSchemaUnion {
101101
}
102102
const schemaFactory = createCustomizedFluidFrameworkScopedFactory(
103103
inputSchemaFactory,
104-
"extensibleSchemaUnion",
104+
"extensibleUnionNode",
105105
);
106106
class Union
107107
extends schemaFactory.object(name, record, { allowUnknownOptionalFields: true })
108108
implements Members<TreeNodeFromImplicitAllowedTypes<T>>
109109
{
110-
public get child(): TreeNodeFromImplicitAllowedTypes<T> | undefined {
110+
public get union(): TreeNodeFromImplicitAllowedTypes<T> | undefined {
111111
for (const [_key, child] of TreeAlpha.children(this)) {
112112
return child as TreeNodeFromImplicitAllowedTypes<T>;
113113
}

‎packages/dds/tree/src/index.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -371,4 +371,4 @@ export { TableSchema, type System_TableSchema } from "./tableSchema.js";
371371
export { asAlpha, asBeta } from "./api.js";
372372

373373
export { TextAsTree, FormattedTextAsTree } from "./text/index.js";
374-
export { ExtensibleSchemaUnion } from "./extensibleSchemaUnion.js";
374+
export { ExtensibleUnionNode } from "./extensibleUnionNode.js";

packages/dds/tree/src/test/domain-schema-compatibility-snapshots/extensibleSchemaUnion-example/2.82.0.json renamed to packages/dds/tree/src/test/domain-schema-compatibility-snapshots/extensibleUnionNode-example/2.83.0.json

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
"root": {
44
"kind": 1,
55
"simpleAllowedTypes": {
6-
"com.fluidframework.extensibleSchemaUnion<extensibleSchemaUnion-example>.ExtensibleUnion": {
6+
"com.fluidframework.extensibleUnionNode<extensibleUnionNode-example>.ExtensibleUnion": {
77
"isStaged": false
88
}
99
}
@@ -21,7 +21,7 @@
2121
"leafKind": 1
2222
}
2323
},
24-
"com.fluidframework.extensibleSchemaUnion<extensibleSchemaUnion-example>.ExtensibleUnion": {
24+
"com.fluidframework.extensibleUnionNode<extensibleUnionNode-example>.ExtensibleUnion": {
2525
"object": {
2626
"kind": 2,
2727
"fields": {

packages/dds/tree/src/test/extensibleSchemaUnion.spec.ts renamed to packages/dds/tree/src/test/extensibleUnionNode.spec.ts

Lines changed: 15 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55

66
import { strict as assert } from "node:assert";
77

8-
import { ExtensibleSchemaUnion } from "../extensibleSchemaUnion.js";
8+
import { ExtensibleUnionNode } from "../extensibleUnionNode.js";
99
import { Tree } from "../shared-tree/index.js";
1010
import {
1111
checkSchemaCompatibilitySnapshots,
@@ -16,45 +16,45 @@ import {
1616
import { testSchemaCompatibilitySnapshots } from "./snapshots/index.js";
1717
import { inMemorySnapshotFileSystem } from "./utils.js";
1818

19-
describe("extensibleSchemaUnion", () => {
19+
describe("extensibleUnionNode", () => {
2020
it("examples", () => {
21-
const sf = new SchemaFactoryBeta("extensibleSchemaUnionExample.items");
21+
const sf = new SchemaFactoryBeta("extensibleUnionNodeExample.items");
2222
class ItemA extends sf.object("A", { x: sf.string }) {}
2323
class ItemB extends sf.object("B", { x: sf.number }) {}
2424

25-
class AnyItem extends ExtensibleSchemaUnion.extensibleSchemaUnion(
25+
class AnyItem extends ExtensibleUnionNode.createSchema(
2626
[ItemA, ItemB], // Future versions may add more members here
2727
sf,
2828
"ExtensibleUnion",
2929
) {}
3030
// Instances of the union are created using `create`.
3131
const anyItem = AnyItem.create(new ItemA({ x: "hello" }));
32-
// Reading the content from the union is done via `child`,
32+
// Reading the content from the union is done via the `union` property,
3333
// which can be `undefined` to handle the case where a future version of this schema allows a type unknown to the current version.
34-
const childNode: ItemA | ItemB | undefined = anyItem.child;
34+
const childNode: ItemA | ItemB | undefined = anyItem.union;
3535
// To determine which member of the union was present, its schema can be inspected:
3636
const aSchema = Tree.schema(childNode ?? assert.fail("No child"));
3737
assert.equal(aSchema, ItemA);
3838
});
3939

4040
// Test that this packages doesn't make any schema changes.
4141
it("compatibility", () => {
42-
// Test schema compatibility for an example schema using extensibleSchemaUnion.
42+
// Test schema compatibility for an example schema using extensibleUnionNode.
4343
const currentViewSchema = new TreeViewConfiguration({
44-
schema: ExtensibleSchemaUnion.extensibleSchemaUnion(
44+
schema: ExtensibleUnionNode.createSchema(
4545
[SchemaFactoryBeta.number, SchemaFactoryBeta.string],
46-
new SchemaFactoryBeta("extensibleSchemaUnion-example"),
46+
new SchemaFactoryBeta("extensibleUnionNode-example"),
4747
"ExtensibleUnion",
4848
),
4949
});
5050
testSchemaCompatibilitySnapshots(
5151
currentViewSchema,
52-
"2.82.0",
53-
"extensibleSchemaUnion-example",
52+
"2.83.0",
53+
"extensibleUnionNode-example",
5454
);
5555
});
5656

57-
// Test that users of ExtensibleSchemaUnion can evolve their schema over time.
57+
// Test that users of ExtensibleUnionNode can evolve their schema over time.
5858
it("workflow over time", () => {
5959
const snapshotDirectory = "dir";
6060
const [fileSystem] = inMemorySnapshotFileSystem();
@@ -65,7 +65,7 @@ describe("extensibleSchemaUnion", () => {
6565
class B extends factory.object("B", {}) {}
6666
class C extends factory.object("C", {}) {}
6767

68-
const a = ExtensibleSchemaUnion.extensibleSchemaUnion([A], factory, "ExtensibleUnion");
68+
const a = ExtensibleUnionNode.createSchema([A], factory, "ExtensibleUnion");
6969

7070
// Create the initial snapshot.
7171
checkSchemaCompatibilitySnapshots({
@@ -77,7 +77,7 @@ describe("extensibleSchemaUnion", () => {
7777
snapshotDirectory,
7878
});
7979

80-
const b = ExtensibleSchemaUnion.extensibleSchemaUnion([A, B], factory, "ExtensibleUnion");
80+
const b = ExtensibleUnionNode.createSchema([A, B], factory, "ExtensibleUnion");
8181

8282
checkSchemaCompatibilitySnapshots({
8383
version: "2.0.0",
@@ -88,11 +88,7 @@ describe("extensibleSchemaUnion", () => {
8888
snapshotDirectory,
8989
});
9090

91-
const c = ExtensibleSchemaUnion.extensibleSchemaUnion(
92-
[A, B, C],
93-
factory,
94-
"ExtensibleUnion",
95-
);
91+
const c = ExtensibleUnionNode.createSchema([A, B, C], factory, "ExtensibleUnion");
9692

9793
checkSchemaCompatibilitySnapshots({
9894
version: "3.0.0",

‎packages/framework/fluid-framework/api-report/fluid-framework.alpha.api.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -329,10 +329,10 @@ export function evaluateLazySchema<T extends TreeNodeSchema>(value: LazyItem<T>)
329329
export function exportCompatibilitySchemaSnapshot(config: Pick<TreeViewConfiguration, "schema">): JsonCompatibleReadOnly;
330330

331331
// @alpha
332-
export namespace ExtensibleSchemaUnion {
333-
export function extensibleSchemaUnion<const T extends readonly TreeNodeSchema[], const TScope extends string, const TName extends string>(types: T, inputSchemaFactory: SchemaFactoryBeta<TScope>, name: TName): Statics<T> & TreeNodeSchemaCore_2<ScopedSchemaName_2<`com.fluidframework.extensibleSchemaUnion<${TScope}>`, TName>, NodeKind_2, false, unknown, never, unknown> & (new (data: InternalTreeNode_2) => Members<TreeNodeFromImplicitAllowedTypes<T>> & TreeNode_2 & WithType_2<ScopedSchemaName_2<`com.fluidframework.extensibleSchemaUnion<${TScope}>`, TName>, NodeKind_2, unknown>);
332+
export namespace ExtensibleUnionNode {
333+
export function createSchema<const T extends readonly TreeNodeSchema[], const TScope extends string, const TName extends string>(types: T, inputSchemaFactory: SchemaFactoryBeta<TScope>, name: TName): Statics<T> & TreeNodeSchemaCore_2<ScopedSchemaName_2<`com.fluidframework.extensibleUnionNode<${TScope}>`, TName>, NodeKind_2, false, unknown, never, unknown> & (new (data: InternalTreeNode_2) => Members<TreeNodeFromImplicitAllowedTypes<T>> & TreeNode_2 & WithType_2<ScopedSchemaName_2<`com.fluidframework.extensibleUnionNode<${TScope}>`, TName>, NodeKind_2, unknown>);
334334
export interface Members<T> {
335-
readonly child: T | undefined;
335+
readonly union: T | undefined;
336336
}
337337
export interface Statics<T extends readonly TreeNodeSchema[]> {
338338
create<TThis extends TreeNodeSchema>(this: TThis, child: TreeNodeFromImplicitAllowedTypes<T>): TreeFieldFromImplicitField<TThis>;

0 commit comments

Comments
 (0)