Fluid Framework v2.32.0 (minor)

Contents

• ✨ New Features
  • Blobs in Detached Container Supported by Default (#24119)
  • Shorter IDs for DataStores and DDSes (#24231)
• 🌳 SharedTree DDS Changes
  • Cleanup of several tree and schema alpha APIs for content import and export (#24255)
  • Provide alpha APIs for accessing tree content and stored schema without requiring a compatible view schema (#24225)
• ⚠️ Deprecations
  • The containerPackageInfo parameter in createOdspCreateContainerRequest() is now deprecated (#23919)

✨ New Features

Blobs in Detached Container Supported by Default (#24119)

It is no longer necessary or supported to provide detachedBlobStorage to the Loader. This functionality is now provided by default, and the deprecated IDetachedBlobStorage will be removed in the 2.40.0 release. The new behavior can be disabled by setting Fluid.Container.MemoryBlobStorageEnabled to false. This flag will also be removed in the 2.40.0 release if no issues are reported.

Change details

Commit: fcf561a

Affected packages:

• @fluidframework/container-loader

⬆️ Table of contents

Shorter IDs for DataStores and DDSes (#24231)

Fluid Framework will now use shorter IDs for Datastores and DDSes when enableRuntimeIdCompressor:"on" is set in IContainerRuntimeOptions. This change should help reduce summary and snapshot sizes as well as improve runtime performance because of a smaller memory footprint.

Change details

Commit: 27bbb87

Affected packages:

• @fluidframework/container-runtime
• @fluidframework/datastore

⬆️ Table of contents

🌳 SharedTree DDS Changes

Cleanup of several tree and schema alpha APIs for content import and export (#24255)

A new TreeSchema type has been introduced which extends SimpleTreeSchema but contains TreeNodeSchema instead of SimpleNodeSchema.

TreeViewConfigurationAlpha is added which is just TreeViewConfiguration but implementing TreeSchema.

SimpleTreeSchema was modified to have a root property instead of implementing SimpleFieldSchema directly: this makes it possible for TreeViewConfigurationAlpha to implement TreeSchema which extends SimpleTreeSchema.

generateSchemaFromSimpleSchema now returns the new TreeSchema type.

EncodeOptions and ParseOptions have been unified as TreeEncodingOptions which covers both the encoding and parsing cases.

getJsonSchema now takes in ImplicitAllowedTypes instead of ImplicitFieldSchema since it can't handle optional roots. getJsonSchema also takes in the new TreeSchemaEncodingOptions to provide options for how to handle stored keys vs property keys, and fields with defaults.

Now that getJsonSchema takes in configuration options, its results are no longer cached.

Change details

Commit: c6563e5

Affected packages:

• fluid-framework
• @fluidframework/tree

⬆️ Table of contents

Provide alpha APIs for accessing tree content and stored schema without requiring a compatible view schema (#24225)

Adds an ITreeAlpha interface (which ITree can be down-casted to) that provides access to both the tree content and the schema. This allows inspecting the content saved in a SharedTree in a generic way that can work on any SharedTree.

This can be combined with the existing generateSchemaFromSimpleSchema to generate a schema that can be used with IIree.viewWith to allow constructing a TreeView for any SharedTree, regardless of its schema.

Note that the resulting TypeScript typing for such a view will not be friendly: the TreeView APIs are designed for statically known schema. Using them is possible with care and a lot of type casts but not recommended if it can be avoided: see disclaimer on generateSchemaFromSimpleSchema. Example using ITreeAlpha and generateSchemaFromSimpleSchema:

const viewAlpha = tree as ITreeAlpha;
const treeSchema = generateSchemaFromSimpleSchema(
  viewAlpha.exportSimpleSchema(),
);
const config = new TreeViewConfiguration({ schema: treeSchema.root });
const view = viewAlpha.viewWith(config);

getSimpleSchema is also added as an @alpha API to provide a way to clone schema into the simple schema formats. Note that when using (or copying) a view schema as a simple schema, more metadata will be preserved than when deriving one from the stored schema using ITreeAlpha.

Change details

Commit: 18b6e05

Affected packages:

• fluid-framework
• @fluidframework/tree

⬆️ Table of contents

⚠️ Deprecations

The containerPackageInfo parameter in createOdspCreateContainerRequest() is now deprecated (#23919)

The containerPackageInfo parameter in createOdspCreateContainerRequest() is now deprecated and will be removed in version 2.40.0.

The name of the containerPackage can no longer be sent through the request. Instead, it can be added in the constructor of OdspDriverUrlResolverForShareLink.

See issue #23882 for more details.

Change details

Commit: 42b26b7

Affected packages:

• @fluidframework/odsp-driver

⬆️ Table of contents

🛠️ Start Building Today!

Please continue to engage with us on GitHub Discussion and Issue pages as you adopt Fluid Framework!

build-tools v0.55.0 (minor)

This is a minor release.

Fluid Framework v2.31.1 (patch)

What's Changed

• Update handlecache.ts (#24233) #24256
• build(client): Bump to version 2.31.1 and update type test baselines #24241

Full Changelog: client_v2.31.0...client_v2.31.1

Fluid Framework v2.31.0 (minor)

Contents

• ✨ New Features
  • New alpha onAssertionFailure API (#24089)
• 🌳 SharedTree DDS Changes
  • Better type errors for invalid recursive schema (#24080)
  • Improve tree shaking for code which imports SharedTreeAttributes (#24135)
  • Improvements to typing of object node schema (#24143)
  • Improved type checking for recursive object schema Fields (#24113)
  • TreeAlpha.exportConcise now supports undefined (#24187)
  • Performance enhancements in SharedTree branch-related ops processing (#24093)
• Other Changes
  • Simplify experimental tree data object implementation (#23943)

✨ New Features

New alpha onAssertionFailure API (#24089)

A new @alpha API is added called onAssertionFailure which can be used to get a callback when an assertion fails indicating a bug in the Fluid Framework. This callback is invoked before the exception is thrown, reducing the chances of the exception being lost or replaced with a different exception before making it to a catch block which reports it. It can also be used to break into the debugger when the assertion occurs to aid in debugging the cause.

import { onAssertionFailure } from "fluid-framework/alpha";

let firstAssertion: Error | undefined;

onAssertionFailure((error: Error) => {
  const priorErrorNote =
    firstAssertion === undefined
      ? "Please report this bug."
      : `Might be caused due to prior error ${JSON.stringify(firstAssertion.message)} which should be investigated first.`;
  const message = `Encountered Bug in Fluid Framework: ${error.message}\n${priorErrorNote}\n${error.stack}`;
  console.error(message);

  debugger;
  firstAssertion ??= error;
});

Change details

Commit: 5e933c7

Affected packages:

• @fluidframework/core-utils

⬆️ Table of contents

🌳 SharedTree DDS Changes

Better type errors for invalid recursive schema (#24080)

Constraints have been added to *Recursive SchemaFactory methods to ensure correct use without relying on ValidateRecursiveSchema as much.

Change details

Commit: 8ae8d2c

Affected packages:

• fluid-framework
• @fluidframework/tree

⬆️ Table of contents

Improve tree shaking for code which imports SharedTreeAttributes (#24135)

Bundling code that imports SharedTreeAttributes from @fluidframework/tree/legacy should now better prune out the rest of the tree package's code. This change reduced the dependency on webpack's usedExports when tree shaking, but other bundlers should also benefit.

Change details

Commit: eb46f42

Affected packages:

• @fluidframework/tree

⬆️ Table of contents

Improvements to typing of object node schema (#24143)

Several tweaks to the typing of object node schema have been made to allow exposing an @alpha ObjectNodeSchema type.

SchemaFactoryAlpha's object and objectRecursive now return schema which are compatible with the new ObjectNodeSchema type. This new ObjectNodeSchema type exposes a fields: ReadonlyMap<string, FieldSchemaAlpha & SimpleObjectFieldSchema> property which provides an easy way to get information about the object's fields.

Additionally an alpha ObjectNodeSchema object is added to enable support for schema instanceof ObjectNodeSchema to safely narrow TreeNodeSchema to this new type.

In support of this work, several typing details were fixed including:

• info field of [typeSchemaSymbol] type brand on recursive object schema was specified to match non-recursive variants.
• Type of field metadata was correctly plumbed through optionalReclusive and requiredRecursive.
• When fields object provided to SchemaFactory.object is typed as RestrictiveStringRecord<ImplicitFieldSchema> the resulting TreeObjectNode no longer gets a Record<string, TreeNode | TreeLeafValue> signature which could incorrectly conflict with custom members added to the object. Instead {} is used to provide no information about felids on the type when the schema provides no information about them. Additionally this case is explicitly made non-constructable: the constructor takes in never instead of a Record<string,never> which could be erroneously satisfied with an empty object due to how TypeScript assignability rules consider records to have all allowed fields, but also allow objects missing those fields to be assigned to them.

Lastly, metadata on the various schema types has been made required instead of optional. This does not impact the APIs for constructing schema: when undefined is provided the schema now defaults to {} instead of undefined. This reduces the number of cases code reading metadata from schema has to handle.

Change details

Commit: 02ecf8d

Affected packages:

• fluid-framework
• @fluidframework/tree

⬆️ Table of contents

Improved type checking for recursive object schema Fields (#24113)

Most ways to provide incorrectly typed data for fields of recursive object schema now produce simpler type errors without relying on ValidateRecursiveSchema.

As a side effect of this work, some schema which violated the documented allowed patterns specified by SchemaFactory but used to work (as long as they were not package exported) no longer compile.

The specific case known to break is when:

1. An Object node schema is co-recursive with an Array node schema.
2. The Array does not declare a named subclass.
3. The schema reference from the Object to the Array is not using the lazy syntax.

For example:

class Foo extends sf.objectRecursive("Foo", {
  fooList: sf.arrayRecursive("FooList", [() => Foo]), // Bad
}) {}
{
  type _check = ValidateRecursiveSchema<typeof Foo>;
}

Such a schema is disallowed according to the documentation. See the "recursive schema must explicitly declare a named class" remarks. This restriction is necessary to avoid generated .d.ts files replacing recursive references with any. Fixing this code is now also necessary to avoid a compile error.

// Fixed
class FooList extends sf.arrayRecursive("FooList", [() => Foo]) {}
{
  type _check = ValidateRecursiveSchema<typeof FooList>;
}
class Foo extends sf.objectRecursive("Foo", {
  fooList: FooList,
}) {}
{
  type _check = ValidateRecursiveSchema<typeof Foo>;
}

This change will also result in much nicer IntelliSense and type errors while fixing the typing if the schema is exported.

There are still several cases which compile but violate this policy regarding recursive schema and can cause issues when exporting schema; these should be migrated to the above pattern as well. It is still valid to use non-recursive structurally named array and map schema inline; this change does not impact them.

Change details

Commit: 5b656f5

Affected packages:

• fluid-framework
• @FluidF...

Fluid Framework v2.30.0 (minor)

Contents

• 🌳 SharedTree DDS Changes
  • TreeBranchEvents now exposes the rootChanged event (#24014)
  • New SchemaFactoryAlpha.scopedFactory method (#23987)
  • Rules regarding how and when lazy schema references are resolved have been clarified (#24030)
  • Alpha APIs for replacing handles in export formats have been redesigned (#24061)
• ⚠️ Deprecations
  • IContainer.getContainerPackageInfo() is now deprecated (#23840)
• Legacy API Changes
  • Unnecessary exports are now removed from container-runtime (#23981)
  • The process and processDocumentSchemaOp functions have been removed (#24018)
  • Deprecated ILoaderOptions have been removed (#24046)
• Other Changes
  • The OrderedEditSet interface now has a getLocalEdits method (#23244)

🌳 SharedTree DDS Changes

TreeBranchEvents now exposes the rootChanged event (#24014)

TreeBranchEvents now includes the rootChanged event from TreeViewEvents.

Change details

Commit: 702a08a

Affected packages:

• fluid-framework
• @fluidframework/tree

⬆️ Table of contents

New SchemaFactoryAlpha.scopedFactory method (#23987)

The SchemaFactoryAlpha.scopedFactory method has been added, providing an easy way to create a new SchemaFactory with a nested scope string.

Change details

Commit: cddd513

Affected packages:

• fluid-framework
• @fluidframework/tree

⬆️ Table of contents

Rules regarding how and when lazy schema references are resolved have been clarified (#24030)

A lazy schema reference is a LazyItem referencing a TreeNodeSchema. They typically look like () => MySchema and are used when a forward reference from one schema to another is required (including but not limited to recursive and co-recursive schema).

TreeViewConfiguration now documents its significance with respect to lazy schema references. Additionally some implicit assumptions like no modifications of AllowedTypes after resolving of lazy schema references have been enforced (such modifications would previously cause undefined behavior in the future, and now an error is thrown when trying to modify them).

evaluateLazySchema has been added as an @alpha API that is now consistently used by all internal code when evaluating lazy schema references. This ensures consistent behavior and error reporting, but also adds caching. Therefore it is now supported for applications to have lazy schema references which compute the schema when invoked, without having to implement their own caching as long as those applications use evaluateLazySchema anytime they need to evaluate a lazy schema reference.

Change details

Commit: 23f3279

Affected packages:

• fluid-framework
• @fluidframework/tree

⬆️ Table of contents

Alpha APIs for replacing handles in export formats have been redesigned (#24061)

The various import and export VerboseTree and ConciseTree APIs no longer include valueConverter options. Instead the resulting tree can be further processed to do any desired replacements. The following @alpha APIs have been added to assist with this:

1. cloneWithReplacements
2. replaceHandles
3. replaceConciseTreeHandles
4. replaceVerboseTreeHandles

Change details

Commit: 34b319c

Affected packages:

• @fluidframework/tree
• fluid-framework

⬆️ Table of contents

⚠️ Deprecations

IContainer.getContainerPackageInfo() is now deprecated (#23840)

The IContainer.getContainerPackageInfo() function is now deprecated. This API will be removed in version 2.40.0. Use IFluidCodeDetails.package returned by IContainer.getLoadedCodeDetails() instead.

See issue #23898 for details.

Change details

Commit: 521be72

Affected packages:

• @fluidframework/container-definitions
• @fluidframework/container-loader

⬆️ Table of contents

Legacy API Changes

Unnecessary exports are now removed from container-runtime (#23981)

The following types in the @fluidframework/container-runtime are now removed. These types are unnecessary for external users of this package.

• currentDocumentVersionSchema
• DeletedResponseHeaderKey
• DocumentSchemaValueType
• DocumentsSchemaController
• GCFeatureMatrix
• GCNodeType
• GCVersion
• IBlobManagerLoadInfo
• ICancellableSummarizerController
• ICancellationToken
• IConnectableRuntime
• IContainerRuntimeMetadata
• ICreateContainerMetadata
• IDocumentSchema
• IDocumentSchemaChangeMessage
• IDocumentSchemaCurrent
• IDocumentSchemaFeatures
• IGCMetadata
• IGCStats
• IMarkPhaseStats
• IRefreshSummaryAckOptions
• ISerializedElection
• ISubmitSummaryOptions
• ISummarizerInternalsProvider
• ISummarizerRuntime
• ISummaryCancellationToken
• ISummaryMetadataMessage
• ISweepPhaseStats
• Summarizer

Change details

Commit: 74896b9

Affected packages:

• @fluidframework/container-runtime

⬆️ Table of contents

The process and processDocumentSchemaOp functions have been removed (#24018)

process has been replaced by processMessages from the following:

• FluidDataStoreRuntime
• IDeltaHandler
• IFluidDataStoreChannel
• MockFluidDataStoreRuntime
• MockDeltaConnection

processDocumentSchemaOp has been replaced by processDocumentSchemaMessages from DocumentsSchemaController.

See the deprecation release note for more details.

Change details

Commit: bc35d54

Affected packages:

• @fluidframework/container-runtime
• @fluidframework/datastore
• @fluidframework/datastore-definitions
• @fluidframework/runtime-definitions
• @fluidframework/test-runtime-utils

⬆️ Table of contents

Deprecated ILoaderOptions have been removed (#24046)

Previously ILoaderOptions exported from container-loader was extending the base ILoaderOptions defined in container-definitions to add an experimental summarizeProtocolTree property which was used to test single-commit summaries. The option is no longer required or in use, so...

Fluid Framework v2.23.0 (minor)

Contents

• ✨ New Features
  • Local value changes in presence now raise events (#23858)
• 🌳 SharedTree DDS Changes
  • Op bunching performance enhancements (#23732)
  • Invalid schema base classes in Tree.is now throw an error instead of returning false (#23938)
  • Creating large transactions and processing inbound changes is now faster (#23929)
  • Faster processing of events for large transactions (#23939)
• ⚠️ Deprecations
  • The FluidDataStoreRuntime.process function is now deprecated (#23866)

✨ New Features

Local value changes in presence now raise events (#23858)

The presence value managers now raise events for local value changes. The new events are as follows:

• LatestValueManager

  • localUpdated raised when local is assigned

• LatestMapValueManager

  • localItemUpdated raised when local.set is called
  • localItemRemoved raised when local.delete is called

Change details

Commit: 2896983

Affected packages:

• @fluidframework/presence

⬆️ Table of contents

🌳 SharedTree DDS Changes

Op bunching performance enhancements (#23732)

SharedTree now takes advantage of a new feature called "op bunching" where contiguous ops in a grouped batch are bunched and processed together. This improves the performance of processing ops asymptotically; as the number of local ops and incoming ops increase, the processing time will reduce.

For example, with 10 local ops + 10 incoming ops, the performance increases by 70%; with 100 local ops + 100 incoming ops, the performance increases by 94%.

This will help improve performance in the following scenarios:

• A client makes a large number of changes in a single JS turn. For example, copy pasting large data like a table.
• A client has a large number of local changes. For example, slow clients whose changes are slow to ack or clients with a local branch with large number of changes.

Change details

Commit: a98b04f

Affected packages:

• @fluidframework/tree
• fluid-framework

⬆️ Table of contents

Invalid schema base classes in Tree.is now throw an error instead of returning false (#23938)

As documented in TreeNodeSchemaClass, there are specific rules around sub-classing schema, mainly that only a single most derived class can be used. One place where it was easy to accidentally violate this rule and get hard-to-debug results was Tree.is. This has been mitigated by adding a check in Tree.is which detects this mistake (which used to result in false being returned) and instead throws a UsageError explaining the situation. The error will look something like:

Two schema classes were used (CustomObjectNode and Derived) which derived from the same SchemaFactory generated class ("com.example.Test"). This is invalid.

For applications wanting to test if a given TreeNode is an instance of some schema base class, this can be done using instanceof which includes base classes when doing the check.

Change details

Commit: 0099565

Affected packages:

• @fluidframework/tree
• fluid-framework

⬆️ Table of contents

Creating large transactions and processing inbound changes is now faster (#23929)

SharedTree sometimes composes several sequential changes into a single change. It does so whenever a transaction is created and when processing inbound changes.

Version 2.23.0 makes this composition process asymptotically faster. For example, creating a transaction that performs 1000 edits on a single array now takes 170ms instead of 1.5s (an 89% improvement).

See Change #23902 for more details.

Change details

Commit: 35847b5

Affected packages:

• @fluidframework/tree
• fluid-framework

⬆️ Table of contents

Faster processing of events for large transactions (#23939)

In versions prior to 2.23.0, event processing time could scale quadratically (O(N^2)) with the change count when processing a batch of changes.

This performance characteristic has been corrected. See change #23908 for more details.

Change details

Commit: 2a1e7e0

Affected packages:

• fluid-framework
• @fluidframework/tree

⬆️ Table of contents

⚠️ Deprecations

The FluidDataStoreRuntime.process function is now deprecated (#23866)

A new function processMessages has been added in place of process. The new function will be called to process multiple messages instead of a single one on the data store runtime. This is part of a feature called "op bunching" where contiguous ops of a given type and to a given data store / DDS are bunched and sent together for processing.

Note that process may still be called in scenarios where this data store runtime (Datastore layer) is running with an older version of data store context (Runtime layer) in the same client. This is to support Fluid layer compatibility.

Change details

Commit: 3f44d43

Affected packages:

• @fluidframework/datastore

⬆️ Table of contents

🛠️ Start Building Today!

Please continue to engage with us on GitHub Discussion and Issue pages as you adopt Fluid Framework!

Fluid Framework v2.22.1 (patch)

What's Changed

• [release/2.22] fix(merge-tree): Correctly bookkeep insert into local-only obliterate #23937
• build(client): Update typetests in release branch after minor release 2.22.0 #23896
• [bump] client: 2.22.0 => 2.22.1 (patch) #23891

Full Changelog: client_v2.22.0...client_v2.22.1

build-tools v0.54.0 (minor)

This is a minor release.

Fluid Framework v2.22.0 (minor)

Contents

• 🌳 SharedTree DDS Changes
  • Add leaves and statics to SchemaFactory. (#23787)
• ⚠️ Deprecations
  • Deprecate processCore on SharedObject and SharedObjectCore in favor of processMessagesCore (#23836)
• Other Changes
  • Target ES2021 (#23307)
  • odsp-driver no longer depends on node-fetch (#23796)
  • Change when the pre-op and op events on ISharedObjectEvents are emitted (#23836)

🌳 SharedTree DDS Changes

Add leaves and statics to SchemaFactory. (#23787)

SchemaFactory now has a leaves member that is an array of all leaf schema.

SchemaFactory now has static members to access leaf schema and create field schema.

Change details

Commit: efa90f6

Affected packages:

• fluid-framework
• @fluidframework/tree

⬆️ Table of contents

⚠️ Deprecations

Deprecate processCore on SharedObject and SharedObjectCore in favor of processMessagesCore (#23836)

A new function processMessagesCore has been added in place of processCore, which will be called to process multiple messages instead of a single one on the channel. This is part of a feature called "Op bunching" where contiguous ops in a grouped batch are bunched and processed together by the shared object.

Implementations of SharedObject and SharedObjectCore must now also implement processMessagesCore. A basic implementation could be to iterate over the messages' content and process them one by one as it happens now. Note that some DDS may be able to optimize processing by processing the messages together.

Change details

Commit: 5eb19a0

Affected packages:

• @fluidframework/shared-object-base

⬆️ Table of contents

Other Changes

Target ES2021 (#23307)

The TypeScript build for Fluid Framework packages has been updated to target ES2021 instead of ES2020. This may result in newer JavaScript language features being used. This does not change TypeScript types, nor the JavaScript libraries being used. We only support users which support ES2022, so updating to target ES2021 should not break any supported use-case. Any users which do not have at least ES2021 language feature support may need to transpile out some additional cases after this change.

This should result in slightly reduced bundle size and slightly improved performance for users not transpiling these features out. No major impact is expected.

Change details

Commit: 091b2df

Affected packages:

• fluid-framework

⬆️ Table of contents

odsp-driver no longer depends on node-fetch (#23796)

The @fluidframework/odsp-driver package had a dependency on node-fetch to provide consistent behavior of the Fetch API across Node.js and browsers. Since v18 of Node.js, the Node-native Fetch API implementation no longer requires extra flags to be enabled, so the Fetch API is effectively now natively available on all browsers and Node.js. This dependency removal should reduce Fluid Framework's contribution to application bundle sizes.

We expect this change to have no impact for Fluid Framework consumers. However, if you are running Fluid in a Node.js environment with the --no-experimental-fetch flag, this is no longer supported.

Change details

Commit: b17276c

Affected packages:

• @fluidframework/odsp-driver

⬆️ Table of contents

Change when the pre-op and op events on ISharedObjectEvents are emitted (#23836)

Previous behavior - pre-op was emitted immediately before an op was processed. Then the op was processed and op was emitted immediately after that.

New behavior - pre-op will still be emitted before an op is processed and op will still be emitted after an op is processed. However, these won't be immediate and other ops in a batch for the shared object may be processed in between.

Note that these events are for internal use only as mentioned in the @remarks section of their definition.

Change details

Commit: 5eb19a0

Affected packages:

• @fluidframework/shared-object-base

⬆️ Table of contents

🛠️ Start Building Today!

Please continue to engage with us on GitHub Discussion and Issue pages as you adopt Fluid Framework!

build-tools v0.53.0 (minor)

This is a minor release.