Skip to content

Commit bef7f59

Browse files
CraigMacomberCraigMacomber
authored
Promote annotated allowed type related utilities to beta. (#25728)
## Description This is not intended to have any significant user facing impact, just do most of the stabilizations needed to promote SchemaFactoryAlpha's `staged` and `types` APIs. When those are promoted, a changeset will be included for them.
1 parent bc3a1a8 commit bef7f59

File tree

9 files changed

+255
-34
lines changed

9 files changed

+255
-34
lines changed

‎packages/common/core-interfaces/api-report/core-interfaces.legacy.beta.api.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,12 @@
77
// @public
88
export type ConfigTypes = string | number | boolean | number[] | string[] | boolean[] | undefined;
99

10+
// @beta @sealed @system
11+
export abstract class ErasedBaseType<out Name = unknown> {
12+
protected constructor();
13+
protected abstract brand(dummy: never): Name;
14+
}
15+
1016
// @public @sealed
1117
export abstract class ErasedType<out Name = unknown> {
1218
static [Symbol.hasInstance](value: never): value is never;

‎packages/common/core-interfaces/src/erasedType.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -96,10 +96,10 @@ export abstract class ErasedType<out Name = unknown> {
9696
*
9797
* This class should only be a `type` package export, preventing users from extending it directly.
9898
*
99-
* Since {@link ErasedTypeImplementation} is exported as `@internal`, this restricts implementations of the sealed interfaces to users of `@internal` APIs, which should be anything withing this release group.
99+
* Since {@link ErasedTypeImplementation} is exported as `@internal`, this restricts implementations of the sealed interfaces to users of `@internal` APIs, which should be anything within this release group.
100100
* Any finer grained restrictions can be done as documentation, but not type enforced.
101101
* @sealed
102-
* @alpha
102+
* @beta
103103
* @system
104104
*/
105105
export abstract class ErasedBaseType<out Name = unknown> {

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

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ export function adaptEnum<TScope extends string, const TEnum extends Record<stri
1515
}, Record<string, never>, true, Record<string, never>, undefined>; }[keyof TEnum]>;
1616
};
1717

18-
// @alpha @input
18+
// @beta @input
1919
export interface AllowedTypeMetadata {
2020
readonly custom?: unknown;
2121
readonly stagedSchemaUpgrade?: SchemaUpgrade;
@@ -24,13 +24,13 @@ export interface AllowedTypeMetadata {
2424
// @public @system
2525
export type AllowedTypes = readonly LazyItem<TreeNodeSchema>[];
2626

27-
// @alpha @sealed
27+
// @beta @sealed
2828
export type AllowedTypesFull<T extends readonly AnnotatedAllowedType[] = readonly AnnotatedAllowedType[]> = AnnotatedAllowedTypes<T> & UnannotateAllowedTypesList<T>;
2929

30-
// @alpha @sealed
30+
// @beta @sealed
3131
export type AllowedTypesFullEvaluated = AllowedTypesFull<readonly AnnotatedAllowedType<TreeNodeSchema>[]>;
3232

33-
// @alpha @sealed
33+
// @beta @sealed @system
3434
export type AllowedTypesFullFromMixed<T extends readonly (AnnotatedAllowedType | LazyItem<TreeNodeSchema>)[]> = UnannotateAllowedTypesList<T> & AnnotatedAllowedTypes<AnnotateAllowedTypesList<T>>;
3535

3636
// @alpha @sealed @system
@@ -39,15 +39,15 @@ export type AllowedTypesFullFromMixedUnsafe<T extends readonly Unenforced<Annota
3939
// @alpha @sealed @system
4040
export type AllowedTypesFullUnsafe<T extends readonly AnnotatedAllowedTypeUnsafe[] = readonly AnnotatedAllowedTypeUnsafe[]> = AnnotatedAllowedTypes<T> & UnannotateAllowedTypesListUnsafe<T>;
4141

42-
// @alpha @input
42+
// @beta @input
4343
export interface AllowedTypesMetadata {
4444
readonly custom?: unknown;
4545
}
4646

4747
// @alpha
4848
export function allowUnused<T>(t?: T): void;
4949

50-
// @alpha @system
50+
// @beta @system
5151
export type AnnotateAllowedTypesList<T extends readonly (AnnotatedAllowedType | LazyItem<TreeNodeSchema>)[]> = {
5252
[I in keyof T]: T[I] extends AnnotatedAllowedType<unknown> ? T[I] : AnnotatedAllowedType<T[I]>;
5353
};
@@ -57,13 +57,13 @@ export type AnnotateAllowedTypesListUnsafe<T extends readonly Unenforced<Annotat
5757
[I in keyof T]: T[I] extends AnnotatedAllowedTypeUnsafe ? T[I] : AnnotatedAllowedTypeUnsafe<T[I]>;
5858
};
5959

60-
// @alpha @sealed
60+
// @beta @sealed
6161
export interface AnnotatedAllowedType<T = LazyItem<TreeNodeSchema>> {
6262
readonly metadata: AllowedTypeMetadata;
6363
readonly type: T;
6464
}
6565

66-
// @alpha @sealed
66+
// @beta @sealed
6767
export interface AnnotatedAllowedTypes<T = readonly AnnotatedAllowedType[]> extends ErasedBaseType<"tree.AnnotatedAllowedTypes"> {
6868
evaluate(): AllowedTypesFullEvaluated;
6969
evaluateIdentifiers(): ReadonlySet<string>;
@@ -965,7 +965,7 @@ export interface SchemaStaticsAlpha {
965965
readonly typesRecursive: <const T extends readonly Unenforced<AnnotatedAllowedType | LazyItem<TreeNodeSchema>>[]>(t: T, metadata?: AllowedTypesMetadata) => AllowedTypesFullFromMixedUnsafe<T>;
966966
}
967967

968-
// @alpha @sealed
968+
// @beta @sealed
969969
export class SchemaUpgrade {
970970
// (undocumented)
971971
protected _typeCheck: MakeNominal;
@@ -1638,7 +1638,7 @@ const typeNameSymbol: unique symbol;
16381638
// @public @system
16391639
export const typeSchemaSymbol: unique symbol;
16401640

1641-
// @alpha @system
1641+
// @beta @system
16421642
export type UnannotateAllowedTypesList<T extends readonly (AnnotatedAllowedType | LazyItem<TreeNodeSchema>)[]> = {
16431643
[I in keyof T]: T[I] extends AnnotatedAllowedType<infer X> ? X : T[I];
16441644
};

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

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,9 +15,49 @@ export function adaptEnum<TScope extends string, const TEnum extends Record<stri
1515
}, Record<string, never>, true, Record<string, never>, undefined>; }[keyof TEnum]>;
1616
};
1717

18+
// @beta @input
19+
export interface AllowedTypeMetadata {
20+
readonly custom?: unknown;
21+
readonly stagedSchemaUpgrade?: SchemaUpgrade;
22+
}
23+
1824
// @public @system
1925
export type AllowedTypes = readonly LazyItem<TreeNodeSchema>[];
2026

27+
// @beta @sealed
28+
export type AllowedTypesFull<T extends readonly AnnotatedAllowedType[] = readonly AnnotatedAllowedType[]> = AnnotatedAllowedTypes<T> & UnannotateAllowedTypesList<T>;
29+
30+
// @beta @sealed
31+
export type AllowedTypesFullEvaluated = AllowedTypesFull<readonly AnnotatedAllowedType<TreeNodeSchema>[]>;
32+
33+
// @beta @sealed @system
34+
export type AllowedTypesFullFromMixed<T extends readonly (AnnotatedAllowedType | LazyItem<TreeNodeSchema>)[]> = UnannotateAllowedTypesList<T> & AnnotatedAllowedTypes<AnnotateAllowedTypesList<T>>;
35+
36+
// @beta @input
37+
export interface AllowedTypesMetadata {
38+
readonly custom?: unknown;
39+
}
40+
41+
// @beta @system
42+
export type AnnotateAllowedTypesList<T extends readonly (AnnotatedAllowedType | LazyItem<TreeNodeSchema>)[]> = {
43+
[I in keyof T]: T[I] extends AnnotatedAllowedType<unknown> ? T[I] : AnnotatedAllowedType<T[I]>;
44+
};
45+
46+
// @beta @sealed
47+
export interface AnnotatedAllowedType<T = LazyItem<TreeNodeSchema>> {
48+
readonly metadata: AllowedTypeMetadata;
49+
readonly type: T;
50+
}
51+
52+
// @beta @sealed
53+
export interface AnnotatedAllowedTypes<T = readonly AnnotatedAllowedType[]> extends ErasedBaseType<"tree.AnnotatedAllowedTypes"> {
54+
evaluate(): AllowedTypesFullEvaluated;
55+
evaluateIdentifiers(): ReadonlySet<string>;
56+
evaluateSet(): ReadonlySet<TreeNodeSchema>;
57+
readonly metadata: AllowedTypesMetadata;
58+
readonly types: T;
59+
}
60+
2161
// @public @system
2262
type ApplyKind<T, Kind extends FieldKind> = {
2363
[FieldKind.Required]: T;
@@ -474,6 +514,12 @@ export interface SchemaStatics {
474514
readonly string: LeafSchema<"string", string>;
475515
}
476516

517+
// @beta @sealed
518+
export class SchemaUpgrade {
519+
// (undocumented)
520+
protected _typeCheck: MakeNominal;
521+
}
522+
477523
// @public @system
478524
type ScopedSchemaName<TScope extends string | undefined, TName extends number | string> = TScope extends undefined ? `${TName}` : `${TScope}.${TName}`;
479525

@@ -773,6 +819,11 @@ const typeNameSymbol: unique symbol;
773819
// @public @system
774820
export const typeSchemaSymbol: unique symbol;
775821

822+
// @beta @system
823+
export type UnannotateAllowedTypesList<T extends readonly (AnnotatedAllowedType | LazyItem<TreeNodeSchema>)[]> = {
824+
[I in keyof T]: T[I] extends AnnotatedAllowedType<infer X> ? X : T[I];
825+
};
826+
776827
// @public
777828
export type Unenforced<_DesiredExtendsConstraint> = unknown;
778829

‎packages/dds/tree/api-report/tree.legacy.beta.api.md‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,9 +15,49 @@ export function adaptEnum<TScope extends string, const TEnum extends Record<stri
1515
}, Record<string, never>, true, Record<string, never>, undefined>; }[keyof TEnum]>;
1616
};
1717

18+
// @beta @input
19+
export interface AllowedTypeMetadata {
20+
readonly custom?: unknown;
21+
readonly stagedSchemaUpgrade?: SchemaUpgrade;
22+
}
23+
1824
// @public @system
1925
export type AllowedTypes = readonly LazyItem<TreeNodeSchema>[];
2026

27+
// @beta @sealed
28+
export type AllowedTypesFull<T extends readonly AnnotatedAllowedType[] = readonly AnnotatedAllowedType[]> = AnnotatedAllowedTypes<T> & UnannotateAllowedTypesList<T>;
29+
30+
// @beta @sealed
31+
export type AllowedTypesFullEvaluated = AllowedTypesFull<readonly AnnotatedAllowedType<TreeNodeSchema>[]>;
32+
33+
// @beta @sealed @system
34+
export type AllowedTypesFullFromMixed<T extends readonly (AnnotatedAllowedType | LazyItem<TreeNodeSchema>)[]> = UnannotateAllowedTypesList<T> & AnnotatedAllowedTypes<AnnotateAllowedTypesList<T>>;
35+
36+
// @beta @input
37+
export interface AllowedTypesMetadata {
38+
readonly custom?: unknown;
39+
}
40+
41+
// @beta @system
42+
export type AnnotateAllowedTypesList<T extends readonly (AnnotatedAllowedType | LazyItem<TreeNodeSchema>)[]> = {
43+
[I in keyof T]: T[I] extends AnnotatedAllowedType<unknown> ? T[I] : AnnotatedAllowedType<T[I]>;
44+
};
45+
46+
// @beta @sealed
47+
export interface AnnotatedAllowedType<T = LazyItem<TreeNodeSchema>> {
48+
readonly metadata: AllowedTypeMetadata;
49+
readonly type: T;
50+
}
51+
52+
// @beta @sealed
53+
export interface AnnotatedAllowedTypes<T = readonly AnnotatedAllowedType[]> extends ErasedBaseType<"tree.AnnotatedAllowedTypes"> {
54+
evaluate(): AllowedTypesFullEvaluated;
55+
evaluateIdentifiers(): ReadonlySet<string>;
56+
evaluateSet(): ReadonlySet<TreeNodeSchema>;
57+
readonly metadata: AllowedTypesMetadata;
58+
readonly types: T;
59+
}
60+
2161
// @public @system
2262
type ApplyKind<T, Kind extends FieldKind> = {
2363
[FieldKind.Required]: T;
@@ -477,6 +517,12 @@ export interface SchemaStatics {
477517
readonly string: LeafSchema<"string", string>;
478518
}
479519

520+
// @beta @sealed
521+
export class SchemaUpgrade {
522+
// (undocumented)
523+
protected _typeCheck: MakeNominal;
524+
}
525+
480526
// @public @system
481527
type ScopedSchemaName<TScope extends string | undefined, TName extends number | string> = TScope extends undefined ? `${TName}` : `${TScope}.${TName}`;
482528

@@ -785,6 +831,11 @@ const typeNameSymbol: unique symbol;
785831
// @public @system
786832
export const typeSchemaSymbol: unique symbol;
787833

834+
// @beta @system
835+
export type UnannotateAllowedTypesList<T extends readonly (AnnotatedAllowedType | LazyItem<TreeNodeSchema>)[]> = {
836+
[I in keyof T]: T[I] extends AnnotatedAllowedType<infer X> ? X : T[I];
837+
};
838+
788839
// @public
789840
export type Unenforced<_DesiredExtendsConstraint> = unknown;
790841

‎packages/dds/tree/src/simple-tree/core/allowedTypes.ts‎

Lines changed: 10 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -60,7 +60,7 @@ export type AllowedTypes = readonly LazyItem<TreeNodeSchema>[];
6060
* @privateRemarks
6161
* Since this is sealed, users are not supposed to create instances of it directly.
6262
* Making it extend ErasedType could enforce that.
63-
* @alpha
63+
* @beta
6464
* @sealed
6565
*/
6666
export interface AnnotatedAllowedType<T = LazyItem<TreeNodeSchema>> {
@@ -77,7 +77,7 @@ export interface AnnotatedAllowedType<T = LazyItem<TreeNodeSchema>> {
7777
/**
7878
* {@link AllowedTypesFull} but with the lazy schema references eagerly evaluated.
7979
* @sealed
80-
* @alpha
80+
* @beta
8181
*/
8282
export type AllowedTypesFullEvaluated = AllowedTypesFull<
8383
readonly AnnotatedAllowedType<TreeNodeSchema>[]
@@ -95,7 +95,7 @@ export function isAnnotatedAllowedTypes(
9595

9696
/**
9797
* Stores annotations for a set of allowed types.
98-
* @alpha
98+
* @beta
9999
* @sealed
100100
*/
101101
export interface AnnotatedAllowedTypes<T = readonly AnnotatedAllowedType[]>
@@ -139,7 +139,7 @@ export interface AnnotatedAllowedTypes<T = readonly AnnotatedAllowedType[]>
139139
* Stores annotations for a set of allowed types.
140140
* @remarks
141141
* Most expressive form of AllowedTypes which any of the implicit types can be normalized to.
142-
* @alpha
142+
* @beta
143143
* @sealed
144144
*/
145145
export type AllowedTypesFull<
@@ -148,8 +148,7 @@ export type AllowedTypesFull<
148148

149149
/**
150150
* Creates an {@link AllowedTypesFull} type from a mixed array of annotated and unannotated allowed types.
151-
* @alpha
152-
* @sealed
151+
* @system @sealed @beta
153152
*/
154153
export type AllowedTypesFullFromMixed<
155154
T extends readonly (AnnotatedAllowedType | LazyItem<TreeNodeSchema>)[],
@@ -360,7 +359,7 @@ export class AnnotatedAllowedTypesInternal<
360359
* Annotations that apply to a set of allowed types.
361360
* @remarks
362361
* Additional optionals may be added to this as non-breaking changes, so implementations of it should be simple object literals with no unlisted members.
363-
* @alpha
362+
* @beta
364363
* @input
365364
*/
366365
export interface AllowedTypesMetadata {
@@ -385,7 +384,7 @@ export function isAnnotatedAllowedType(
385384
* Annotations that apply to an individual allowed type.
386385
* @remarks
387386
* Additional optionals may be added to this as non-breaking changes, so implementations of it should be simple object literals with no unlisted members.
388-
* @alpha
387+
* @beta
389388
* @input
390389
*/
391390
export interface AllowedTypeMetadata {
@@ -413,7 +412,7 @@ export let createSchemaUpgrade: () => SchemaUpgrade;
413412
* TODO:#38722 implement runtime schema upgrades.
414413
* Until then, the class purely behaves mostly as a placeholder.
415414
* TODO: Consider allowing users to store a name for the upgrade to use in error messages.
416-
* @sealed @alpha
415+
* @sealed @beta
417416
*/
418417
export class SchemaUpgrade {
419418
protected _typeCheck!: MakeNominal;
@@ -461,7 +460,7 @@ export type ImplicitAllowedTypes = AllowedTypes | TreeNodeSchema;
461460

462461
/**
463462
* Removes annotations from a list of allowed types that may contain annotations.
464-
* @system @alpha
463+
* @system @beta
465464
*/
466465
export type UnannotateAllowedTypesList<
467466
T extends readonly (AnnotatedAllowedType | LazyItem<TreeNodeSchema>)[],
@@ -471,7 +470,7 @@ export type UnannotateAllowedTypesList<
471470

472471
/**
473472
* Add annotations to a list of allowed types that may or may not contain annotations.
474-
* @system @alpha
473+
* @system @beta
475474
*/
476475
export type AnnotateAllowedTypesList<
477476
T extends readonly (AnnotatedAllowedType | LazyItem<TreeNodeSchema>)[],

0 commit comments

Comments
 (0)