refactor(tree): Update table schema APIs to use SchemaFactoryBeta
#25613
Conversation
There was a problem hiding this comment.
Pull Request Overview
This PR refactors TableSchema APIs to use SchemaFactoryBeta instead of SchemaFactoryAlpha, promoting dependencies to beta to prepare for TableSchema's own beta promotion.
- Updates TableSchema internal functions to use SchemaFactoryBeta
- Promotes SchemaFactoryObjectOptions from alpha to beta
- Adds objectBeta method to SchemaFactoryBeta for better object schema creation
Reviewed Changes
Copilot reviewed 15 out of 15 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
packages/dds/tree/src/tableSchema.ts |
Updates all internal table schema creation functions to use SchemaFactoryBeta instead of SchemaFactoryAlpha |
packages/dds/tree/src/simple-tree/api/schemaFactoryBeta.ts |
Adds new objectBeta method to SchemaFactoryBeta class |
packages/dds/tree/src/simple-tree/api/schemaFactory.ts |
Promotes SchemaFactoryObjectOptions to beta and creates alpha-specific version |
| API report files | Updates type signatures and exports to reflect the schema factory changes |
| Export files | Adds exports for new SchemaFactoryObjectOptionsAlpha interface |
| Changeset file | Documents the API changes and their impact |
| /* TConstructorExtra */ never, | ||
| /* TCustomMetadata */ TCustomMetadata | ||
| > { | ||
| // The compiler can't infer that UnannotateSchemaRecord<T> is equal to T so we have to do a bunch of typing to make the error go away. |
There was a problem hiding this comment.
This comment doesn't apply as you are not supporting annotated allowed types. You shouldn't be using UnannotateSchemaRecord below.
You might be better off waiting for #25595 and/or basing this implementation of the public version and adding the beta stuff rather than trying to remove all the other alpha stuff from it.
There was a problem hiding this comment.
Thought that might be the case. I'll rework this. But it can also wait. Either way.
There was a problem hiding this comment.
Actually, this same pattern and documentation exists in SchemaFactory.object as well.
| * @input | ||
| * @alpha | ||
| */ | ||
| export interface SchemaFactoryObjectOptionsAlpha<TCustomMetadata = unknown> |
There was a problem hiding this comment.
Note for reviewers: everything that was in SchemaFactoryObjectOptions is kept alpha via this new type except allowUnknownOptionalFields, which is made beta.
|
|
||
| // @beta @input | ||
| export interface SchemaFactoryObjectOptions<TCustomMetadata = unknown> extends NodeSchemaOptions<TCustomMetadata> { | ||
| readonly allowUnknownOptionalFields?: boolean; |
There was a problem hiding this comment.
stabilizing of allowUnknownOptionalFields to beta is a big deal, and deserves to be mentioned in the PR title and a changeset of its own.
I think there might be some lack of clarity still around how exactly that the semantics are for SchemaCompatibilityStatus.isEquivalent, SchemaCompatibilityStatus.canUpgrade and TreeView.upgradeSchema.
I'd like more clarity around how these interact with allowUnknownOptionalFields: currently neither those APIs nor SchemaFactoryObjectOptions.allowUnknownOptionalFields document the intended interactions, and I'm not sure if they are well tested either.
This area of our API (schema upgrade and compat) is particularly confusing at the moment with allowUnknownOptionalFields, staged and persisted metadata all breaking the old semantics.
I think we should have some real dedicated review and more specific targeted stabilization PR for this topic (and land some better docs first)
There was a problem hiding this comment.
@CraigMacomber @taylorsw04 do we have anything filed for clarifying / stabilizing this? I think it's important the table schema be able to leverage this feature so we have some flexibility for future additions.
There was a problem hiding this comment.
Work now tracked by https://dev.azure.com/fluidframework/internal/_workitems/edit/49975
I've converted this PR to a draft until that work is completed.
packages/framework/fluid-framework/api-report/fluid-framework.legacy.public.api.md
Outdated
Show resolved
Hide resolved
|
🔗 Found some broken links! 💔 Run a link check locally to find them. See linkcheck output |
One in a sequence of steps promoting dependencies of
TableSchemato beta so thatTableSchemaitself can be promoted to beta in the near future.Update
TableSchemato take aSchemaFactoryBetainstead ofSchemaFactoryAlpha.Promotes
SchemaFactoryObjectOptions.allowUnknownOptionalFieldsto beta (SchemaFactoryObjectOptionsis promoted to beta, but its other aspects remain alpha via the newSchemaFactoryObjectOptionsAlphatype).