diff --git a/.changeset/gross-apples-defend.md b/.changeset/gross-apples-defend.md new file mode 100644 index 000000000000..dbb90835c7dc --- /dev/null +++ b/.changeset/gross-apples-defend.md @@ -0,0 +1,21 @@ +--- +"fluid-framework": minor +"@fluidframework/tree": minor +"__section": feature +--- +Promote MinimumVersionForCollab to beta + +Promotes the [MinimumVersionForCollab](https://fluidframework.com/docs/api/runtime-definitions/minimumversionforcollab-typealias) type to beta, and adds option to [configuredSharedTreeBeta](https://fluidframework.com/docs/api/fluid-framework#configuredsharedtreebeta-function) for specifying it when creating a new `SharedTree`. + +This allows users to opt into new features and optimizations that are only available when certain minimum version thresholds are guaranteed. +For more details, see [FluidClientVersion](https://fluidframework.com/docs/api/fluid-framework#fluidclientversion-variable) + +#### Example usage + +```typescript +// Configure SharedTree DDS to limit the features it requires of collaborators and future document users to only those available in version `2.80.0` and later, overriding the `MinimumVersionForCollab` provided by the runtime (default: "2.0.0"). +// Edits made to this DDS by this client might cause clients older than the specified version to be unable to open the document and/or error out of collaboration sessions. +const SharedTree = configuredSharedTreeBeta({ + minVersionForCollab: FluidClientVersion.v2_80, +}); +``` diff --git a/packages/dds/tree/api-report/tree.alpha.api.md b/packages/dds/tree/api-report/tree.alpha.api.md index b4f03b12f45d..6bd044f4d1f8 100644 --- a/packages/dds/tree/api-report/tree.alpha.api.md +++ b/packages/dds/tree/api-report/tree.alpha.api.md @@ -158,12 +158,16 @@ export function cloneWithReplacements(root: unknown, rootKey: string, replacer: export type CodecName = string; // @alpha @input -export interface CodecWriteOptions extends ICodecOptions { +export interface CodecWriteOptions extends ICodecOptions, CodecWriteOptionsBeta { readonly allowPossiblyIncompatibleWriteVersionOverrides?: boolean; - readonly minVersionForCollab: MinimumVersionForCollab; readonly writeVersionOverrides?: ReadonlyMap; } +// @beta @input +export interface CodecWriteOptionsBeta { + readonly minVersionForCollab: MinimumVersionForCollab; +} + // @public export enum CommitKind { Default = 0, @@ -1124,7 +1128,7 @@ export interface SharedTreeOptions extends SharedTreeOptionsBeta, Partial; // @alpha @sealed export interface SimpleAllowedTypeAttributes { diff --git a/packages/dds/tree/api-report/tree.beta.api.md b/packages/dds/tree/api-report/tree.beta.api.md index 2f9c6e1502f2..d6a1f4e43594 100644 --- a/packages/dds/tree/api-report/tree.beta.api.md +++ b/packages/dds/tree/api-report/tree.beta.api.md @@ -89,6 +89,11 @@ Kind // @beta export function asBeta(view: TreeView): TreeViewBeta; +// @beta @input +export interface CodecWriteOptionsBeta { + readonly minVersionForCollab: MinimumVersionForCollab; +} + // @public export enum CommitKind { Default = 0, @@ -562,7 +567,7 @@ export class SchemaUpgrade { type ScopedSchemaName = TScope extends undefined ? `${TName}` : `${TScope}.${TName}`; // @beta @input -export type SharedTreeOptionsBeta = ForestOptions; +export type SharedTreeOptionsBeta = ForestOptions & Partial; // @public @sealed @system export interface SimpleNodeSchemaBase { diff --git a/packages/dds/tree/api-report/tree.legacy.beta.api.md b/packages/dds/tree/api-report/tree.legacy.beta.api.md index 0e476c9cf978..1f62f7347745 100644 --- a/packages/dds/tree/api-report/tree.legacy.beta.api.md +++ b/packages/dds/tree/api-report/tree.legacy.beta.api.md @@ -89,6 +89,11 @@ Kind // @beta export function asBeta(view: TreeView): TreeViewBeta; +// @beta @input +export interface CodecWriteOptionsBeta { + readonly minVersionForCollab: MinimumVersionForCollab; +} + // @public export enum CommitKind { Default = 0, @@ -574,7 +579,7 @@ export const SharedTreeAttributes: IChannelAttributes; export const SharedTreeFactoryType = "https://graph.microsoft.com/types/tree"; // @beta @input -export type SharedTreeOptionsBeta = ForestOptions; +export type SharedTreeOptionsBeta = ForestOptions & Partial; // @public @sealed @system export interface SimpleNodeSchemaBase { diff --git a/packages/dds/tree/src/codec/codec.ts b/packages/dds/tree/src/codec/codec.ts index a66fff889392..6575ff073cb9 100644 --- a/packages/dds/tree/src/codec/codec.ts +++ b/packages/dds/tree/src/codec/codec.ts @@ -138,11 +138,9 @@ export interface ICodecOptions { /** * Options relating to encoding of persisted data. - * @remarks - * Extends {@link ICodecOptions} with options that are specific to encoding data. - * @alpha @input + * @input @beta */ -export interface CodecWriteOptions extends ICodecOptions { +export interface CodecWriteOptionsBeta { /** * The minimum version of the Fluid Framework client output must be encoded to be compatible with. * @remarks @@ -153,16 +151,24 @@ export interface CodecWriteOptions extends ICodecOptions { * the data's format should be versioned and if they can't handle the format they should error. */ readonly minVersionForCollab: MinimumVersionForCollab; +} +/** + * Options relating to encoding of persisted data. + * @remarks + * Extends {@link ICodecOptions} with options that are specific to encoding data. + * @alpha @input + */ +export interface CodecWriteOptions extends ICodecOptions, CodecWriteOptionsBeta { /** * Overrides the version of the codec to use for encoding. * @remarks - * Without an override, the selected version will be based on {@link CodecWriteOptions.minVersionForCollab}. + * Without an override, the selected version will be based on {@link CodecWriteOptionsBeta.minVersionForCollab}. */ readonly writeVersionOverrides?: ReadonlyMap; /** - * If true, suppress errors when `writeVersionOverrides` selects a version which may not be compatible with the {@link CodecWriteOptions.minVersionForCollab}. + * If true, suppress errors when `writeVersionOverrides` selects a version which may not be compatible with the {@link CodecWriteOptionsBeta.minVersionForCollab}. */ readonly allowPossiblyIncompatibleWriteVersionOverrides?: boolean; } diff --git a/packages/dds/tree/src/codec/index.ts b/packages/dds/tree/src/codec/index.ts index 30a494130c84..c4497a799539 100644 --- a/packages/dds/tree/src/codec/index.ts +++ b/packages/dds/tree/src/codec/index.ts @@ -10,6 +10,7 @@ export { type ICodecFamily, type ICodecOptions, type CodecWriteOptions, + type CodecWriteOptionsBeta, type IDecoder, type IEncoder, type IJsonCodec, diff --git a/packages/dds/tree/src/index.ts b/packages/dds/tree/src/index.ts index be3823c522d8..043d97d47e26 100644 --- a/packages/dds/tree/src/index.ts +++ b/packages/dds/tree/src/index.ts @@ -319,6 +319,7 @@ export { persistedToSimpleSchema } from "./shared-tree/index.js"; export { type ICodecOptions, type CodecWriteOptions, + type CodecWriteOptionsBeta, FluidClientVersion, type FormatValidator, FormatValidatorNoOp, diff --git a/packages/dds/tree/src/shared-tree/sharedTree.ts b/packages/dds/tree/src/shared-tree/sharedTree.ts index 8d5849003edb..9c005a574646 100644 --- a/packages/dds/tree/src/shared-tree/sharedTree.ts +++ b/packages/dds/tree/src/shared-tree/sharedTree.ts @@ -21,6 +21,7 @@ import { import { type CodecTree, type CodecWriteOptions, + type CodecWriteOptionsBeta, DependentFormatVersion, FluidClientVersion, FormatValidatorNoOp, @@ -612,7 +613,7 @@ export function getCodecTreeForSharedTreeFormat( * Configuration options for SharedTree. * @beta @input */ -export type SharedTreeOptionsBeta = ForestOptions; +export type SharedTreeOptionsBeta = ForestOptions & Partial; /** * Configuration options for SharedTree with alpha features. diff --git a/packages/framework/fluid-framework/api-report/fluid-framework.alpha.api.md b/packages/framework/fluid-framework/api-report/fluid-framework.alpha.api.md index 22e4967a8a12..9aed3c98fc8a 100644 --- a/packages/framework/fluid-framework/api-report/fluid-framework.alpha.api.md +++ b/packages/framework/fluid-framework/api-report/fluid-framework.alpha.api.md @@ -165,12 +165,16 @@ export function cloneWithReplacements(root: unknown, rootKey: string, replacer: export type CodecName = string; // @alpha @input -export interface CodecWriteOptions extends ICodecOptions { +export interface CodecWriteOptions extends ICodecOptions, CodecWriteOptionsBeta { readonly allowPossiblyIncompatibleWriteVersionOverrides?: boolean; - readonly minVersionForCollab: MinimumVersionForCollab; readonly writeVersionOverrides?: ReadonlyMap; } +// @beta @input +export interface CodecWriteOptionsBeta { + readonly minVersionForCollab: MinimumVersionForCollab; +} + // @public export enum CommitKind { Default = 0, @@ -1502,7 +1506,7 @@ export interface SharedTreeOptions extends SharedTreeOptionsBeta, Partial; // @alpha @sealed export interface SimpleAllowedTypeAttributes { diff --git a/packages/framework/fluid-framework/api-report/fluid-framework.beta.api.md b/packages/framework/fluid-framework/api-report/fluid-framework.beta.api.md index 264c33b1e826..8f1ecfe7e114 100644 --- a/packages/framework/fluid-framework/api-report/fluid-framework.beta.api.md +++ b/packages/framework/fluid-framework/api-report/fluid-framework.beta.api.md @@ -96,6 +96,11 @@ export enum AttachState { Detached = "Detached" } +// @beta @input +export interface CodecWriteOptionsBeta { + readonly minVersionForCollab: MinimumVersionForCollab; +} + // @public export enum CommitKind { Default = 0, @@ -934,7 +939,7 @@ export interface SharedObjectKind extends ErasedTyp export const SharedTree: SharedObjectKind; // @beta @input -export type SharedTreeOptionsBeta = ForestOptions; +export type SharedTreeOptionsBeta = ForestOptions & Partial; // @public @sealed @system export interface SimpleNodeSchemaBase { diff --git a/packages/framework/fluid-framework/api-report/fluid-framework.legacy.beta.api.md b/packages/framework/fluid-framework/api-report/fluid-framework.legacy.beta.api.md index e3d6fed2cb9f..4af1bf159aa8 100644 --- a/packages/framework/fluid-framework/api-report/fluid-framework.legacy.beta.api.md +++ b/packages/framework/fluid-framework/api-report/fluid-framework.legacy.beta.api.md @@ -96,6 +96,11 @@ export enum AttachState { Detached = "Detached" } +// @beta @input +export interface CodecWriteOptionsBeta { + readonly minVersionForCollab: MinimumVersionForCollab; +} + // @public export enum CommitKind { Default = 0, @@ -1292,7 +1297,7 @@ export type SharedStringSegment = TextSegment | Marker; export const SharedTree: SharedObjectKind; // @beta @input -export type SharedTreeOptionsBeta = ForestOptions; +export type SharedTreeOptionsBeta = ForestOptions & Partial; export { Side } diff --git a/packages/runtime/runtime-definitions/README.md b/packages/runtime/runtime-definitions/README.md index 38204b9076cf..3cd5ae854cfb 100644 --- a/packages/runtime/runtime-definitions/README.md +++ b/packages/runtime/runtime-definitions/README.md @@ -30,6 +30,8 @@ For more information on the related support guarantees, see [API Support Levels] To access the `public` ([SemVer](https://semver.org/)) APIs, import via `@fluidframework/runtime-definitions` like normal. +To access the `beta` APIs, import via `@fluidframework/runtime-definitions/beta`. + To access the `legacy` APIs, import via `@fluidframework/runtime-definitions/legacy`. ## API Documentation diff --git a/packages/runtime/runtime-definitions/api-extractor/api-extractor-lint-beta.cjs.json b/packages/runtime/runtime-definitions/api-extractor/api-extractor-lint-beta.cjs.json new file mode 100644 index 000000000000..7af093bb825b --- /dev/null +++ b/packages/runtime/runtime-definitions/api-extractor/api-extractor-lint-beta.cjs.json @@ -0,0 +1,5 @@ +{ + "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json", + "extends": "/../../../common/build/build-common/api-extractor-lint.entrypoint.json", + "mainEntryPointFilePath": "/dist/beta.d.ts" +} diff --git a/packages/runtime/runtime-definitions/api-extractor/api-extractor-lint-beta.esm.json b/packages/runtime/runtime-definitions/api-extractor/api-extractor-lint-beta.esm.json new file mode 100644 index 000000000000..82773789eaee --- /dev/null +++ b/packages/runtime/runtime-definitions/api-extractor/api-extractor-lint-beta.esm.json @@ -0,0 +1,5 @@ +{ + "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json", + "extends": "/../../../common/build/build-common/api-extractor-lint.entrypoint.json", + "mainEntryPointFilePath": "/lib/beta.d.ts" +} diff --git a/packages/runtime/runtime-definitions/api-extractor/api-extractor.current.json b/packages/runtime/runtime-definitions/api-extractor/api-extractor.current.json index 6ae39a96d271..3b513b5dc87a 100644 --- a/packages/runtime/runtime-definitions/api-extractor/api-extractor.current.json +++ b/packages/runtime/runtime-definitions/api-extractor/api-extractor.current.json @@ -1,5 +1,5 @@ { "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json", "extends": "/../../../common/build/build-common/api-extractor-report.esm.current.json", - "mainEntryPointFilePath": "/lib/public.d.ts" + "mainEntryPointFilePath": "/lib/beta.d.ts" } diff --git a/packages/runtime/runtime-definitions/api-report/runtime-definitions.beta.api.md b/packages/runtime/runtime-definitions/api-report/runtime-definitions.beta.api.md index 58964cc8f162..d20a3e70d70d 100644 --- a/packages/runtime/runtime-definitions/api-report/runtime-definitions.beta.api.md +++ b/packages/runtime/runtime-definitions/api-report/runtime-definitions.beta.api.md @@ -4,6 +4,9 @@ ```ts +// @beta @input +export type MinimumVersionForCollab = `${1 | 2}.${bigint}.${bigint}` | `${1 | 2}.${bigint}.${bigint}-${string}`; + // (No @packageDocumentation comment for this package) ``` diff --git a/packages/runtime/runtime-definitions/api-report/runtime-definitions.legacy.alpha.api.md b/packages/runtime/runtime-definitions/api-report/runtime-definitions.legacy.alpha.api.md index ea5818ca651d..7a370ae49d76 100644 --- a/packages/runtime/runtime-definitions/api-report/runtime-definitions.legacy.alpha.api.md +++ b/packages/runtime/runtime-definitions/api-report/runtime-definitions.legacy.alpha.api.md @@ -397,7 +397,7 @@ export interface LocalAttributionKey { type: "local"; } -// @beta @legacy @input +// @beta @input export type MinimumVersionForCollab = `${1 | 2}.${bigint}.${bigint}` | `${1 | 2}.${bigint}.${bigint}-${string}`; // @beta @legacy diff --git a/packages/runtime/runtime-definitions/api-report/runtime-definitions.legacy.beta.api.md b/packages/runtime/runtime-definitions/api-report/runtime-definitions.legacy.beta.api.md index 19c22eee4da3..c21343197b7a 100644 --- a/packages/runtime/runtime-definitions/api-report/runtime-definitions.legacy.beta.api.md +++ b/packages/runtime/runtime-definitions/api-report/runtime-definitions.legacy.beta.api.md @@ -388,7 +388,7 @@ export interface LocalAttributionKey { type: "local"; } -// @beta @legacy @input +// @beta @input export type MinimumVersionForCollab = `${1 | 2}.${bigint}.${bigint}` | `${1 | 2}.${bigint}.${bigint}-${string}`; // @beta @legacy diff --git a/packages/runtime/runtime-definitions/package.json b/packages/runtime/runtime-definitions/package.json index c56d70b805a2..ed1dae57baa4 100644 --- a/packages/runtime/runtime-definitions/package.json +++ b/packages/runtime/runtime-definitions/package.json @@ -23,6 +23,16 @@ "default": "./dist/index.js" } }, + "./beta": { + "import": { + "types": "./lib/beta.d.ts", + "default": "./lib/index.js" + }, + "require": { + "types": "./dist/beta.d.ts", + "default": "./dist/index.js" + } + }, "./legacy": { "import": { "types": "./lib/legacy.d.ts", @@ -74,9 +84,11 @@ "check:biome": "biome check .", "check:exports": "concurrently \"npm:check:exports:*\"", "check:exports:bundle-release-tags": "api-extractor run --config api-extractor/api-extractor-lint-bundle.json", + "check:exports:cjs:beta": "api-extractor run --config api-extractor/api-extractor-lint-beta.cjs.json", "check:exports:cjs:legacy": "api-extractor run --config api-extractor/api-extractor-lint-legacy.cjs.json", "check:exports:cjs:legacyAlpha": "api-extractor run --config api-extractor/api-extractor-lint-legacyAlpha.cjs.json", "check:exports:cjs:public": "api-extractor run --config api-extractor/api-extractor-lint-public.cjs.json", + "check:exports:esm:beta": "api-extractor run --config api-extractor/api-extractor-lint-beta.esm.json", "check:exports:esm:legacy": "api-extractor run --config api-extractor/api-extractor-lint-legacy.esm.json", "check:exports:esm:legacyAlpha": "api-extractor run --config api-extractor/api-extractor-lint-legacyAlpha.esm.json", "check:exports:esm:public": "api-extractor run --config api-extractor/api-extractor-lint-public.esm.json", diff --git a/packages/runtime/runtime-definitions/src/compatibilityDefinitions.ts b/packages/runtime/runtime-definitions/src/compatibilityDefinitions.ts index 85db85b85430..a8176b2ee323 100644 --- a/packages/runtime/runtime-definitions/src/compatibilityDefinitions.ts +++ b/packages/runtime/runtime-definitions/src/compatibilityDefinitions.ts @@ -26,7 +26,7 @@ * For example it might make sense to constrain this to something like `"1.4.0" | typeof defaultMinVersionForCollab | 2.${bigint}.0"`. * * @input - * @legacy @beta + * @beta */ export type MinimumVersionForCollab = | `${1 | 2}.${bigint}.${bigint}`