The API docs directories for the website contain a mix of generated and
manually authored files, so cleaning the API docs is not as simple as
just deleting the entire directory.
We previously had a sketchy workaround the cleaned all `.md` files, but
left any `.mdx` files alone, and had a script override in place to
ensure we ran `clean:api-documentation` before running
`build:api-documentation`.
This PR introduces a more wholistic solution to the fundamental problem,
which is that we want to clean up all of the git-ignored contents of the
API docs directories, while leaving the checked-in files alone.
[AB#24394](https://dev.azure.com/fluidframework/235294da-091d-4c29-84fc-cdfc3d90890b/_workitems/edit/24394)
## Description
This tightens the state machine space for `BranchCommitEnricher` and
makes various simplifications to the API and code.
* The API surface of `BranchCommitEnricher` is reduced to functions
that:
1. Process branch changes
2. Get enriched commits
3. Acknowledge transaction state transitions
Item (i) used to be made of a few different methods whose invocations
needed to be coordinated by `SharedTreeCore`. Now,
`BranchCommitEnricher` manages this internally. Previously, it needed to
know whether or not the commit being submitted was the commit of the
outermost transaction. This could be problematic for future refactors of
SharedTreeCore, so the enricher now derives that information from its
internals (since it already keeps track of ongoing transactions via the
`TransactionEnricher`.
* The map of processed commits stored in the enricher is now a WeakMap,
meaning that the enricher does not need to worry about accidentally
holding on to commits forever. The logic that "purges" map entries
between changes has been removed since the entries will now be dropped
automatically as the commits become unreferenced.
* TransactionEnricher no longer allows getting the enriched change in
the middle of a transaction.
* We now properly throw an error if a the SharedTree is attached in the
middle of a transaction - we do not and cannot currently support this
scenario.
* Various renames, conditional refactors, inlining, etc. to shorten
lines, improve code flow, simplify conditional logic, etc. and
additional documentation.
Docusaurus treats document files whose names start with `_` as "partial"
documents, which don't get included in site output. We have a couple of
API exports that start with `_`, and result in files that end up treated
as partials. To work around this, we now prepend "u" to any files that
would otherwise start with an underscore.
"u" is a pretty arbitrary choice. We can't simply remove the underscore,
as that would be much more likely to create filename collisions. While
it is technically possible that we could export an API item that starts
with "u_", doing so would violate our naming conventions, and seems
pretty unlikely. If such an API item is added, Docusaurus will start
failing on duplicate routes, at which point we can change strategies.
See https://docusaurus.io/docs/create-doc for more details on partial
documents.
[AB#23443](https://dev.azure.com/fluidframework/235294da-091d-4c29-84fc-cdfc3d90890b/_workitems/edit/23443)
## Description
Added a new page for the new Presence APIs and supported scenarios
---------
Co-authored-by: Rick Kirkham <Rick-Kirkham@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
## Overview
This feature introduces a new pattern for creating datastores
synchronously within the Fluid Framework. It allows for the synchronous
creation of a child datastore from an existing datastore, provided that
the child datastore is available synchronously via the existing
datastore's registry and that the child's factory supports synchronous
creation. This method also ensures strong typing for the consumer.
In this context, "child" refers specifically to the organization of
factories and registries, not to any hierarchical or hosting
relationship between datastores. The parent datastore does not control
the runtime behaviors of the child datastore beyond its creation.
The synchronous creation of child datastores enhances the flexibility of
datastore management within the Fluid Framework. It ensures type safety
and provides a different way to manage datastores within a container.
However, it is important to consider the overhead associated with
datastores, as they are stored, summarized, garbage collected, loaded,
and referenced independently. This overhead should be justified by the
scenario's requirements.
Datastores offer increased capabilities, such as the ability to
reference them via handles, allowing multiple references to exist and
enabling those references to be moved, swapped, or changed.
Additionally, datastores are garbage collected after becoming
unreferenced, which can simplify final cleanup across clients. This is
in contrast to subdirectories in a shared directory, which do not have
native capabilities for referencing or garbage collection but are very
low overhead to create.
Synchronous creation relies on both the factory and the datastore to
support it. This means that asynchronous operations, such as resolving
handles, some browser API calls, consensus-based operations, or other
asynchronous tasks, cannot be performed during the creation flow.
Therefore, synchronous child datastore creation is best limited to
scenarios where the existing asynchronous process cannot be used, such
as when a new datastore must be created in direct response to
synchronous user input.
## Key Benefits
- **Synchronous Creation**: Allows for the immediate creation of child
datastores without waiting for asynchronous operations.
- **Strong Typing**: Ensures type safety and better developer experience
by leveraging TypeScript's type system.
## Use Cases
### Example 1: Creating a Child Datastore
In this example, we demonstrate how to support creating a child
datastore synchronously from a parent datastore.
```typescript
/**
* This is the parent DataObject, which is also a datastore. It has a
* synchronous method to create child datastores, which could be called
* in response to synchronous user input, like a key press.
*/
class ParentDataObject extends DataObject {
get ParentDataObject() {
return this;
}
protected override async initializingFirstTime(): Promise<void> {
// create synchronously during initialization
this.createChild("parentCreation");
}
createChild(name: string): ChildDataStore {
assert(
this.context.createChildDataStore !== undefined,
"this.context.createChildDataStore",
);
// creates a detached context with a factory who's package path is the same
// as the current datastore, but with another copy of its own type.
const { entrypoint } = this.context.createChildDataStore(
ChildDataStoreFactory.instance,
);
const dir = this.root.createSubDirectory("children");
dir.set(name, entrypoint.handle);
entrypoint.setProperty("childValue", name);
return entrypoint;
}
getChild(name: string): IFluidHandle<ChildDataStore> | undefined {
const dir = this.root.getSubDirectory("children");
return dir?.get<IFluidHandle<ChildDataStore>>(name);
}
}
```
For a complete example see the follow test:
https://github.com/microsoft/FluidFramework/blob/main/packages/test/local-server-tests/src/test/synchronousDataStoreCreation.spec.ts
---------
Co-authored-by: jzaffiro <110866475+jzaffiro@users.noreply.github.com>
Co-authored-by: Joshua Smithrud <54606601+Josmithr@users.noreply.github.com>
## Description
Switches all dependencies in the simplemde example app to be
devDependencies.
The example apps in the repo are not production code and aren't
published or deployed anywhere. Having prod dependencies in them causes
our lockfiles to mark them as such, and consequently Component
Governance potentially flags them for prod-level security
vulnerabilities. We have one outstanding prod-level alert about the
simplemde package (which seems abandoned); this change should remove the
prod-level severity from it while we migrate to another package for this
example, or get rid of it altogether.
The [ai-collab sample app already showcases this
pattern](https://github.com/microsoft/FluidFramework/blob/main/examples/apps/ai-collab/package.json#L33).
Removes changelog entries for the reverted changes in #23133. Also
removes some lingering entries in the release notes from that same
change. Finally, also fixes up some heading levels in the release notes
and TOC that were missed in review.
#### Description
[22739](https://dev.azure.com/fluidframework/internal/_workitems/edit/22739)
This PR adds step by step instructions for:
- Adding a new rule to the `estlint-plugin-fluid`
- Bumping the `eslint-plugin-fluid` version
- Bumping the `eslint-config-fluid` version
---------
Co-authored-by: Alex Villarreal <716334+alexvy86@users.noreply.github.com>
Co-authored-by: Joshua Smithrud <54606601+Josmithr@users.noreply.github.com>
Current contents were copied from example boilerplate and were missed in
the initial Docusaurus PR.
This PR fixes the generated site title to be `Fluid Framework` instead
of `Fluid Framework | Hello from Fluid Framework!`.
Also removes the template page description.
Update to deployment and docs generation: adjustments to deploy v2
artifact instead of main artifacts. Note: while the update aims to
deploy artifacts from the latest release branches instead of main, the
actual website build is still done on the main branch. This will prevent
the pipeline from deploying docs which were generated with an outdated
version of the website.
Notable changes:
deploy-docs:
- shifted most of the stages from build-docs to deploy-docs
- build-docs now runs check_branch_version -> upload-json -> trigger
deploy
build-docs:
- shifted check_branch_version to the top since its output is required
to properly in the upload json step
upload-json-step:
- added a new upload step which uploads artifacts with the name
"latest-v*.tar.gz"
- takes in new parameters from check_branch_version to ensure it only
uploads with this name when the pipeline is running on the latest
release branch
latestVersions:
- since upload-json-step requires majorVersion, I figured it was best to
include it as an output variable for the function as it seems more
robust compared to relying on a string parsing script in the pipeline
itself
download-apis:
- update such that it only downloads "latest-v*.tar.gz" instead of the
main branch artifacts
This makes it so that changed events are not fired when rebases happen
on branches that are not the main branch and also adds a regression test
for this scenario. Rebases that happen on the main branch are remote
changes and therefore correct.
- `BroadcastControls` replace `LatestValueControls`
- `BroadcastControls` maybe specified on `PresenceStates` thru new
`controls` property as defaults for all value managers.
- `PresenceNotifications` redeclared apart from `PresenceStates` to
avoid `controls` exposure. Also yields better API documentation.
- `allowableUpdateLatencyMs` was renamed from `allowableUpdateLatency`
to clarify units are milliseconds. Specifying this value currently has
no effect.
- Unsupported `forcedRefreshInterval` has been removed until
implementation is closer.
## Overview
This feature introduces a new pattern for creating datastores
synchronously within the Fluid Framework. It allows for the synchronous
creation of a child datastore from an existing datastore, provided that
the child datastore is available synchronously via the existing
datastore's registry and that the child's factory supports synchronous
creation. This method also ensures strong typing for the consumer.
In this context, "child" refers specifically to the organization of
factories and registries, not to any hierarchical or hosting
relationship between datastores. The parent datastore does not control
the runtime behaviors of the child datastore beyond its creation.
The synchronous creation of child datastores enhances the flexibility of
datastore management within the Fluid Framework. It ensures type safety
and provides a different way to manage datastores within a container.
However, it is important to consider the overhead associated with
datastores, as they are stored, summarized, garbage collected, loaded,
and referenced independently. This overhead should be justified by the
scenario's requirements.
Datastores offer increased capabilities, such as the ability to
reference them via handles, allowing multiple references to exist and
enabling those references to be moved, swapped, or changed.
Additionally, datastores are garbage collected after becoming
unreferenced, which can simplify final cleanup across clients. This is
in contrast to subdirectories in a shared directory, which do not have
native capabilities for referencing or garbage collection but are very
low overhead to create.
Synchronous creation relies on both the factory and the datastore to
support it. This means that asynchronous operations, such as resolving
handles, some browser API calls, consensus-based operations, or other
asynchronous tasks, cannot be performed during the creation flow.
Therefore, synchronous child datastore creation is best limited to
scenarios where the existing asynchronous process cannot be used, such
as when a new datastore must be created in direct response to
synchronous user input.
## Key Benefits
- **Synchronous Creation**: Allows for the immediate creation of child
datastores without waiting for asynchronous operations.
- **Strong Typing**: Ensures type safety and better developer experience
by leveraging TypeScript's type system.
## Use Cases
### Example 1: Creating a Child Datastore
In this example, we demonstrate how to support creating a child
datastore synchronously from a parent datastore.
```typescript
/**
* This is the parent DataObject, which is also a datastore. It has a
* synchronous method to create child datastores, which could be called
* in response to synchronous user input, like a key press.
*/
class ParentDataObject extends DataObject {
get ParentDataObject() {
return this;
}
protected override async initializingFirstTime(): Promise<void> {
// create synchronously during initialization
this.createChild("parentCreation");
}
createChild(name: string): ChildDataStore {
assert(
this.context.createChildDataStore !== undefined,
"this.context.createChildDataStore",
);
// creates a detached context with a factory who's package path is the same
// as the current datastore, but with another copy of its own type.
const { entrypoint } = this.context.createChildDataStore(
ChildDataStoreFactory.instance,
);
const dir = this.root.createSubDirectory("children");
dir.set(name, entrypoint.handle);
entrypoint.setProperty("childValue", name);
return entrypoint;
}
getChild(name: string): IFluidHandle<ChildDataStore> | undefined {
const dir = this.root.getSubDirectory("children");
return dir?.get<IFluidHandle<ChildDataStore>>(name);
}
}
```
For a complete example see the follow test:
https://github.com/microsoft/FluidFramework/blob/main/packages/test/local-server-tests/src/test/synchronousDataStoreCreation.spec.ts
---------
Co-authored-by: Matt Rakow <ChumpChief@users.noreply.github.com>
Co-authored-by: Joshua Smithrud <54606601+Josmithr@users.noreply.github.com>
We've added a new data structure for tracking "recent" (based on MSN)
batchIds which are at risk for seeing a duplicate sequence batchID come
in. This data structure is consulted and modified on each incoming
batch.
Whenever we summarize, we need to include this state as of the given
sequence number, and when we load from a snapshot we need to repopulate
it as well.
Why? Because summaries can happen at any time, and a future container
loading from that point will need to know the recent batch IDs that may
possibly be followed by a sequenced duplicate.
---------
Co-authored-by: Kian Thompson <102998837+kian-thompson@users.noreply.github.com>
Publishing step needs this config to live in the build output directory.
Placing it under `static` ensures it is copied to the right place.
See https://github.com/Azure/static-web-apps/issues/1071 for more
details.
Confirmed that the swa-cli is able to find this when run locally. This
is also how the site was setup previously, I was just misled by the
documentation leading me to believe that moving it to the root was okay.
It also worked using the local swa-cli tooling 🤷♂️
This update introduces a new feature to the `SharedString` DDS, allowing
for the adjustment of properties over a specified range. The
`annotateAdjustRange` method enables users to apply adjustments to
properties within a given range, providing more flexibility and control
over property modifications.
An adjustment is a modification applied to a property value within a
specified range. Adjustments can be used to increment or decrement
property values dynamically. They are particularly useful in scenarios
where property values need to be updated based on user interactions or
other events. For example, in a rich text editor, adjustments can be
used for modifying indentation levels or font sizes, where multiple
users could apply differing numerical adjustments.
### Key Features and Use Cases:
- **Adjustments with Constraints**: Adjustments can include optional
minimum and maximum constraints to ensure the final value falls within
specified bounds. This is particularly useful for maintaining consistent
formatting in rich text editors.
- **Consistent Property Changes**: The feature ensures that property
changes are consistent, managing both local and remote changes
effectively. This is essential for collaborative rich text editing where
multiple users may be making adjustments simultaneously.
- **Rich Text Formatting**: Adjustments can be used to modify text
properties such as font size, indentation, or other formatting
attributes dynamically based on user actions.
### Configuration and Compatibility Requirements:
This feature is only available when the configuration
`Fluid.Sequence.mergeTreeEnableAnnotateAdjust` is set to `true`.
Additionally, all collaborating clients must have this feature enabled
to use it. If any client does not have this feature enabled, it will
lead to the client exiting collaboration. A future major version of
Fluid will enable this feature by default.
### Usage Example:
```typescript
sharedString.annotateAdjustRange(start, end, {
key: { value: 5, min: 0, max: 10 }
});
```
[AB#11819](https://dev.azure.com/fluidframework/235294da-091d-4c29-84fc-cdfc3d90890b/_workitems/edit/11819)
---------
Co-authored-by: Tyler Butler <tylerbu@microsoft.com>
# Docusaurus
Updates the website (/docs) to leverage
[Docusaurus](https://docusaurus.io/) in place of Hugo as its static site
generator.
## Functional changes
### Versioning
The existing Hugo-based site only has a partial versioning story.
The API docs are versioned, but the rest of the content isn't.
This creates a messy story where our hand-written docs likely only
discuss topics related to the current version, and we have no place to
put docs discussing earlier versions.
Or, even worse, we have a mixed bag of documentation for different
versions, creating a very unclear user story.
This prototype includes an end-to-end versioning story, [automated by
Docusaurus](https://docusaurus.io/docs/versioning).
Current (v2) docs live under `docs`.
Old (v1) docs live under `versioned_docs/version-1`.
Most of the documentation has been duplicated between the two versions,
but some minor changes have been made to make the docs better line up
with the corresponding version of the API.
These changes should be reviewed before being merged into main /
deploying the new website.
### Search
This branch includes an offline implementation of search.
An offline solution comes with some downsides (slower build, larger
bundle), and probably isn't what we want long term.
That said, it is much better than what our current website has (no
search whatsoever).
We should come back to this after v1 of our new website.
---------
Co-authored-by: Wayne Ferrao <wayneferrao@microsoft.com>
## Breaking Changes
[AB#22192](https://dev.azure.com/fluidframework/internal/_workitems/edit/22192)
Following up on this PR:
https://github.com/microsoft/FluidFramework/pull/23078 which we reverted
due to assert 0x245 due to the original change. The assert was caused
due to registering "disconnect" listener before the initialization.
In this change, I removed registering a listener as we already have
disconnectCore which is triggered on disconnection. So using that for
rejecting the promise.
---------
Co-authored-by: Jatin Garg <jatingarg@Jatins-MacBook-Pro-2.local>
Co-authored-by: Alex Villarreal <716334+alexvy86@users.noreply.github.com>
by explicitly specifying `getSelf` return type. Also remove the
incorrect undefined `client` property.
Enable `exactOptionalPropertyTypes` and fix errors to keep `IAudience`
implementation strictly checked.
## Description
We're moving our agent pools to the eastus2 region as part of a capacity
management initiative. This PR updates all pipelines to use the new
pools.
## Description
Presence has been promoted to alpha and is not experimental package
anymore. This PR removes the 'experimental package' usage in Presence
docs
1. Setup changeset to be used for all `Presence` changes
2. Add notes for rename
3. Update CHANGELOG to reflect 2.50 release notes and [vague] 2.4.0
history
This change fixes issue covered in PR
https://github.com/microsoft/FluidFramework/pull/22981
After several simplifications, I realized we could reuse
pendingStashedBlobs map to identify the bug scenario, which is
reuploading a stashed blob that was already processed. If while
onUploadResolve we don't see the blob in the pending list but it's on
the stashed one, then just ignore the new upload.
trackPendingStashedUploads is replaced with waitForStashedBlobs which
also implies there are further simplifications to the blob manager
logic, mainly we could also remove the stashedUpload property on the
PendingBlob type since now we keep track of stashed blobs separately .
Joshua Smithrud
Matt Rakow
Noah Encke
Craig Macomber (Microsoft)
Michael Zhen
Pranshu
Tony Murphy
WillieHabi
Alex Villarreal
Tyler Butler
Jason Hartman
Ji Kim
Jenn
daesunp
Mark Fields
Jatin Garg
Daniel Madrid