@fluidframework/register-collection

A consensus register collection is a distributed data structure (DDS), which holds a set of registers and their versions generated during concurrent updates. In the simplest definition, two updates on a single register are concurrent if there is no causal relationship between them (i.e., neither knows about the other). On such cases of concurrent updates, a register internally stores all possible versions of a value.

Using Fluid Framework libraries

For a dependency on a Fluid Framework library's public APIs, we recommend a ^ (caret) version range. For example, use ^1.3.4.

For a dependency on an unstable API, such as a beta API, we recommend a more restrictive version range. For example, use a ~ version range.

Installation

Run this command to install the package:

npm i @fluidframework/register-collection

Importing from this package

This package uses package.json exports to separate APIs by support level. For information about the support guarantees, read API Support Levels.

Import the public APIs from @fluidframework/register-collection.

Import the legacy APIs from @fluidframework/register-collection/legacy.

API Documentation

Read the @fluidframework/register-collection API documentation at https://fluidframework.com/docs/apis/register-collection.

Creation and instance types

Use ConsensusRegisterCollection.create(runtime) to create a collection. Use ConsensusRegisterCollection.getFactory() to register its factory. For instance annotations, the ConsensusRegisterCollection type is an alias for IConsensusRegisterCollection.

import {
    ConsensusRegisterCollection,
    type IConsensusRegisterCollection,
} from "@fluidframework/register-collection/legacy";

const registers: IConsensusRegisterCollection<string> =
    ConsensusRegisterCollection.create(runtime);

Detecting concurrency in Fluid

In distributed systems literature, detecting concurrency requires some form of logical/physical clock. A popular technique used in replicated databases such as dynamodb is called version vectors where each key stores a collection of [time, value] tuples. time is essentially a reference clock used to decide concurrency amongst updates. Each update to a key includes the time, essentially to indicate how caught up the replica was during that update.

In Fluid, each operation contains a referenceSequenceNumber (refSeq), which essentially refers to how caught up the client was (in terms of sequence number) during that update. We can use this property to implement a similar concurrency model. Mathematically, if an update has a refSeq N, it can overwrite/discard any other prior values with sequenceNumber (seq) <= N. It is safe to do so because the client must have seen all those updates before posting its own update. Hence this update is not concurrent with those overwritten updates. However, the update is still concurrent with any other update with seq > N. Therefore those versions are still kept.

Conflict resolution policies

Below are the policies that the DDS implements:

• Versions: Returns all stored concurrent versions. App is responsible for conflict resolution. Amazon's shopping cart policy based on dynamodb is a popular example of this policy.

• LWW: The last write to a key always overwrites any prior writes (aka last write win policy). This is exactly same as Fluid's Shared Map policy.

• Atomic: The policy follows the same semantics of a shared distributed lock. Amongst all concurrent updates, only the first writer wins. In distributed systems literature, the register update policy is called Atomic. This behavior requires a linearizable register. A linearizable register behaves as if there is only a single copy of the data, and that every operation appears to take effect atomically at one point in time. This definition implies that operations are executed in an well-defined order. On a concurrent update, we perform a compare-and-set operation, where we compare a register's stored seq with the incoming refSeq. The earliest operation overwriting the stored seq wins since every client reaches to an agreement on the value. Hence we can safely return the first value.

Minimum Client Requirements

Fluid Framework client libraries support the platforms in this document. These requirements are intentionally restrictive. Within a major version series, we can relax these requirements, but we cannot make them stricter. For a Long Term Support (LTS) version, we might need to support these platforms for several years.

Other configurations can work, but Fluid Framework does not support them. If an unsupported configuration stops working, we do not classify this as a bug. To request support for a configuration that is not listed, file an issue. The product team will evaluate your request. In the issue, specify the current status of the configuration:

• The configuration works but needs official support.
• The configuration does not work and requires changes.

Supported Runtimes

• Fluid Framework supports Node.js versions 22 and 24 while they receive upstream support.
  • Fluid Framework will stop support for version 22 when upstream support ends on 2027-04-30.
  • Fluid Framework does not support Node.js with the --no-experimental-fetch flag.
• Fluid Framework supports modern browsers that support the ES2022 standard library.

Supported Tools

• TypeScript 6.0:
  • Fluid Framework supports all strict options.
  • Set the build targets (lib, target) to ES2022 or later.
  • Enable strictNullChecks.
  • Fluid Framework does not support configuration options deprecated in TypeScript 6.0.
  • Fluid Framework does not fully support exactOptionalPropertyTypes. If you enable this option, do not use in, Reflect.has, Object.hasOwn, or Object.prototype.hasOwnProperty to narrow members of Fluid Framework types. These methods can incorrectly exclude undefined from the possible values.
• webpack 5
  • We do not require a specific bundler. Other bundlers that handle ES Modules can work, but we actively test only webpack.

Module Resolution

In TypeScript compilerOptions, use Node16, Node20, NodeNext, or Bundler module resolution. These settings follow the Node.js v12+ ESM Resolution and Loading algorithm.

Do not use Node10 module resolution.

Module Formats

• ES Modules: Use ES Modules to consume Fluid Framework client packages, including in Node.js.
• CommonJS: Fluid Framework does not officially support CommonJS in version 3.0 or later.

Contribution Guidelines

You can contribute to Fluid Framework in these ways:

• Answer questions in GitHub Discussions.
• Submit bug reports and help verify fixes.
• Review source code changes.
• Contribute bug fixes.

For detailed instructions, read the repo documentation.

This project follows the Microsoft Open Source Code of Conduct. For more information, read the Code of Conduct frequently asked questions. For questions or comments, contact [email protected].

This project may contain Microsoft trademarks or logos for Microsoft projects, products, or services. Use of these trademarks or logos must follow Microsoft’s Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship.

Help

Read the Fluid Framework documentation for information about Fluid Framework concepts and APIs.

To request information that the documentation does not contain, create an issue.

Trademark

This project may contain Microsoft trademarks or logos for Microsoft projects, products, or services.

Use of these trademarks or logos must follow Microsoft's Trademark & Brand Guidelines.

Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship.