@fluidframework/local-driver 2.113.1 → 2.114.0

package/CHANGELOG.md

@@ -1,5 +1,74 @@
 # @fluidframework/local-driver
 
+## 2.114.0
+
+### Minor Changes
+
+- Add new @alpha ServiceClient API for creating and loading Fluid containers ([#27693](https://github.com/microsoft/FluidFramework/pull/27693)) [ee47192d4a](https://github.com/microsoft/FluidFramework/commit/ee47192d4ae91bc28f9154c4d1ead2acad762f3c)
+
+  This introduces an experimental (`@alpha`), service-agnostic API for working with Fluid containers whose root is an arbitrary data store, along with an in-memory implementation for testing.
+
+  The new surface is made up of:
+  - `ServiceClient` (`@fluidframework/driver-definitions`): the entry point for creating and loading containers. Along with it come the supporting container types (`FluidContainer`, `FluidContainerWithService`, `FluidContainerAttached`), the data store model (`DataStoreKind`, `DataStoreKey`, `DataStoreRegistry`, `DataStoreCreator`), and the generic registry primitives (`Registry`, `RegistryKey`, `lookupInRegistry`, `createBasicRegistryKey`).
+  - `defineDataStore` and `sharedObjectRegistryFromIterable` (`@fluidframework/shared-object-base`): build a `DataStoreKind` from a root shared object and a registry of shared object kinds.
+  - `defineTreeDataStore` and `instantiateTreeFirstTime` (`@fluidframework/tree`): a SharedTree-specific convenience wrapper that produces a `DataStoreKind` backed by a `TreeView`.
+  - `startEphemeralService` (`@fluidframework/local-driver`): starts an in-memory `EphemeralService` for tests. The service owns the lifetime of the in-memory documents and resources, and produces `ServiceClient`s connected to it (via `EphemeralService.newClient` or `EphemeralService.defaultClient`). The helpers `cleanupEphemeralService` and `getDefaultEphemeralService` manage an optional default service instance.
+
+  Apart from the `@fluidframework/local-driver` helpers (which come from `@fluidframework/local-driver/alpha`), these APIs are also re-exported from `fluid-framework`. None reference any `@legacy` types.
+
+  Example:
+
+  ```typescript
+  import { startEphemeralService } from "@fluidframework/local-driver/alpha";
+  import {
+    ServiceClient,
+    defineTreeDataStore,
+    TreeViewConfiguration,
+    SchemaFactory,
+  } from "fluid-framework/alpha";
+  import { strict as assert } from "node:assert";
+
+  // Start an ephemeral in-memory service and get a ServiceClient connected to it.
+  const service = startEphemeralService();
+  const client: ServiceClient = service.defaultClient;
+  // Define a DataStoreKind which uses a SharedTree.
+  // In this case the schema is for a single number with an initializer that starts the it at 1.
+  // This schema is captures in the type allowing for strongly typed access to the data in the tree,
+  // where the type matches the schema based runtime enforcement of the schema.
+  const numberStore = defineTreeDataStore({
+    type: "my-app-root",
+    config: new TreeViewConfiguration({ schema: SchemaFactory.number }),
+    initializer: () => 1,
+  });
+
+  // Create a container in the service with the above DataStoreKind.
+  // Ideally this creation would use a service independent API, and only the attach call would be service dependent,
+  // but that is not supported yet.
+  const detachedContainer1 = await client.createContainer(numberStore);
+  const container1 = await detachedContainer1.attach();
+
+  // We now have easy and type safe access to the data in the tree, which will be synced over the service.
+  assert.equal(container1.data.root, 1);
+
+  // A second client can load the same container from the service, and will see the same data.
+  const container2 = await client.loadContainer(container1.id, numberStore);
+  assert.equal(container2.data.root, 1);
+
+  // Both clients can modify the data, and the changes will be synced over the service.
+  container2.data.root = 2;
+  // Since we are using an ephemeral service, we can await the synchronization using service.synchronize.
+  await service.synchronize();
+
+  // And now the changes are visible for all clients.
+  assert.equal(container1.data.root, 2);
+  assert.equal(container2.data.root, 2);
+  ```
+
+  Note that this example does a couple of things which are difficult to do with the other API surfaces:
+  1. It creates a container, then loads a second copy of it, allowing for collaboration. There is currently no non-legacy API surface which allows this without spawning a server process. This is also cleaner than the exacting legacy API options, and can replace the test specific APIs for this as well.
+  2. It creates a container which has a SharedTree at the root, and nothing else. This avoids depending on legacy DDS implementations, which is great for long-term document support and bundle size. This is currently impossible using `fluid-static`, which forces a special root data store. It is also impossible if using `aqueduct`, which forces a root directory in every data store. It can be done using the low level legacy APIs directly, but this new API for it is much simpler.
+  3. There is a common interface all services implement (`ServiceClient`), making the container creation part of the code work for any service implementation.
+
 ## 2.113.0
 
 Dependency updates only.

package/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/local-driver` like normal.
 
+To access the `alpha` APIs, import via `@fluidframework/local-driver/alpha`.
+
 To access the `legacy` APIs, import via `@fluidframework/local-driver/legacy`.
 
 ## API Documentation

package/alpha.d.ts

@@ -0,0 +1,11 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/*
+ * THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY.
+ * Generated by "flub generate entrypoints --outFileLegacyBeta legacy --outDir ./lib --node10TypeCompat" in @fluid-tools/build-cli.
+ */
+
+export * from "./lib/alpha.js";

package/api-extractor/api-extractor-lint-alpha.cjs.json

@@ -0,0 +1,5 @@
+{
+	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+	"extends": "<projectFolder>/../../../common/build/build-common/api-extractor-lint.entrypoint.json",
+	"mainEntryPointFilePath": "<projectFolder>/dist/alpha.d.ts"
+}

package/api-extractor/api-extractor-lint-alpha.esm.json

@@ -0,0 +1,5 @@
+{
+	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+	"extends": "<projectFolder>/../../../common/build/build-common/api-extractor-lint.entrypoint.json",
+	"mainEntryPointFilePath": "<projectFolder>/lib/alpha.d.ts"
+}

package/api-extractor/api-extractor.current.json

@@ -1,7 +1,10 @@
 {
 	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
 	"extends": "<projectFolder>/../../../common/build/build-common/api-extractor-report.esm.current.json",
-	"mainEntryPointFilePath": "<projectFolder>/lib/public.d.ts",
+	"mainEntryPointFilePath": "<projectFolder>/lib/alpha.d.ts",
+	"apiReport": {
+		"reportVariants": ["public", "beta", "alpha"]
+	},
 	// Note: excluding server packages until we can update their tags (and release new server versions)
 	// TODO: remove this override once server dependencies have been updated.
 	"bundledPackages": [

package/api-report/local-driver.alpha.api.md

@@ -0,0 +1,31 @@
+## Alpha API Report File for "@fluidframework/local-driver"
+
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+
+```ts
+
+// @alpha
+export function cleanupEphemeralService(service?: EphemeralService): Promise<void>;
+
+// @alpha @sealed
+export interface EphemeralService extends ErasedBaseType<readonly ["EphemeralService"]> {
+    close(): Promise<void>;
+    readonly defaultClient: EphemeralServiceClient;
+    newClient(options: ServiceOptions): EphemeralServiceClient;
+    synchronize(timeoutMilliseconds?: number): Promise<void>;
+}
+
+// @alpha @sealed
+export interface EphemeralServiceClient extends ServiceClient {
+    readonly service: EphemeralService;
+}
+
+// @alpha
+export function getDefaultEphemeralService(): EphemeralService;
+
+// @alpha
+export function startEphemeralService(isDefault?: boolean): EphemeralService;
+
+// (No @packageDocumentation comment for this package)
+
+```

package/dist/alpha.d.ts

@@ -0,0 +1,19 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/*
+ * THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY.
+ * Generated by "flub generate entrypoints --resolutionConditions require --outFileLegacyBeta legacy --outDir ./dist" in @fluid-tools/build-cli.
+ */
+
+export {
+	// #region @alpha APIs
+	EphemeralService, 
+	EphemeralServiceClient, 
+	cleanupEphemeralService, 
+	getDefaultEphemeralService, 
+	startEphemeralService
+	// #endregion
+} from "./index.js";

package/dist/ephemeralService.d.ts

@@ -0,0 +1,177 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import type { IRequest } from "@fluidframework/core-interfaces";
+import { type ErasedBaseType } from "@fluidframework/core-interfaces/internal";
+import type { DataStoreKind, DataStoreRegistry, FluidContainerAttached, FluidContainerWithService, ServiceClient, ServiceOptions } from "@fluidframework/driver-definitions/internal";
+import { ServiceContainerBase } from "@fluidframework/runtime-utils/internal";
+/**
+ * Starts and returns a new {@link EphemeralService}.
+ * @param isDefault - Whether this service should saved as the default service for {@link cleanupEphemeralService} to cleanup.
+ * Defaults to true.
+ * @remarks
+ * The returned service owns an in-memory server and holds the documents created through clients connected to it.
+ * {@link cleanupEphemeralService} can be used to ensure the service is properly cleaned up (a no-op if stopped/closed already).
+ *
+ * As a service, it may start timers which may require an explicit `close` to fully free.
+ * @alpha
+ */
+export declare function startEphemeralService(isDefault?: boolean): EphemeralService;
+/**
+ * Cleans up the service passed in {@link startEphemeralService}, or the {@link getDefaultEphemeralService|default} if none is passed.
+ * @remarks
+ * This closes the service, and all its containers.
+ * This is a good way to ensure the service and its containers leave no lingering timers
+ * which could leak memory, trigger asynchronous work or prevent a clean process exit.
+ * @alpha
+ */
+export declare function cleanupEphemeralService(service?: EphemeralService): Promise<void>;
+/**
+ * Get the default {@link EphemeralService} if one has been {@link startEphemeralService|started}.
+ * @throws If no default service is running.
+ * @alpha
+ */
+export declare function getDefaultEphemeralService(): EphemeralService;
+/**
+ * Internal Options for creating an {@link EphemeralServiceClient}, extending {@link @fluidframework/driver-definitions#ServiceOptions}
+ * with the {@link EphemeralService} the client should connect to.
+ * @input
+ * @internal
+ */
+export interface EphemeralServiceOptions extends ServiceOptions {
+    /**
+     * The service instance to connect to.
+     */
+    readonly service: EphemeralService;
+}
+/**
+ * An in-memory Fluid service that can produce connected {@link EphemeralServiceClient}s.
+ * @remarks
+ * All documents created through clients connected to a given `EphemeralService` are held in-memory by that service.
+ * Closing the service (via {@link EphemeralService.close} or {@link cleanupEphemeralService}) closes the connections
+ * to any remaining open containers, and cleans up the service's timers.
+ *
+ * Create one with {@link startEphemeralService}.
+ *
+ * Most {@link @fluidframework/driver-definitions#ServiceClient} implementations would take in a URL and credentials to connect to a service,
+ * but that is not needed for the ephemeral in-memory service.
+ * Instead this object representing the actual service instance is provided.
+ * @privateRemarks
+ * This is separated out from the actual {@link @fluidframework/driver-definitions#ServiceClient} object so that it's possible to create multiple service clients
+ * connected to the same service.
+ * Doing so is rarely necessary, but would be needed to test multiple clients collaborating on the same
+ * document with different minVersionForCollaboration values.
+ * This also exposes a place to put APIs for preloading and exporting document contents in the future.
+ *
+ * This is an erased type: its only implementation is the module-private {@link EphemeralServiceImplementation}, which holds
+ * the mutable server and container state so it does not appear on this public type.
+ *
+ * TODO: formalize this lifecycle with an interface which documents these stages.
+ * Lifecycle:
+ * The intended lifecycle of an {@link EphemeralService} follows roughly the same pattern as containers:
+ *
+ * 1. Open: accepts connections from {@link EphemeralServiceClient}s, which can create and load containers.
+ * Might have timers and event registrations which can trigger asynchronous work, and retain the object in memory.
+ *
+ * 2. Closing: asynchronous transition from open to closed. New use should behave as it closed, but may be cleaning up or saving resources asynchronously.
+ * Timers and event registrations may still be active, but should be cleaned up by the time the transition to closed completes.
+ *
+ * 3. Closed: no longer accepts connections from {@link EphemeralServiceClient}s, and all containers connected to it are closed.
+ * Should have no subscriptions to events or timers which could retain it in memory or trigger asynchronous work.
+ * The object can still be used in a limited capacity (typically just to inspect its status (e.g. `isClosed`), and to view (but not edit) the final state of any containers which were connected to it before it closed.)
+ *
+ * Events or errors can cause an open to closing transition. Any nonfunctional state, including error states, should be considered as closed (or closing which will transition to closed),
+ * and meet the requirements of closed with regards to timers and events.
+ *
+ * @alpha @sealed
+ */
+export interface EphemeralService extends ErasedBaseType<readonly ["EphemeralService"]> {
+    /**
+     * Close this service, which closes all containers connected to it and releases its resources.
+     * @remarks
+     * All documents held by this service are discarded, and any timers it (or its containers) were keeping alive
+     * are cleaned up.
+     * The returned promise resolves once all asynchronous cleanup (including shutting down the in-memory server)
+     * has completed.
+     * Closing is idempotent: calling it again after the service is closed resolves without doing anything.
+     */
+    close(): Promise<void>;
+    /**
+     * Drives all containers connected to this service toward convergence, processing pending operations and
+     * waiting for all dirty containers to save.
+     *
+     * @param timeoutMilliseconds - The maximum time to wait for containers to quiesce, in milliseconds. Defaults to 30_000.
+     *
+     * @privateRemarks
+     * This is a best-effort implementation simplified from `LoaderContainerTracker.ensureSynchronized`.
+     * Currently it does not perform receiver-side sequence-number quiescence or wait for join/leave (audience) ops.
+     * See `LoaderContainerTracker.ensureSynchronized` for the fuller version this is based on.
+     * For the currently exposed API surface, this should be sufficient,
+     * but users down casting to internal types might run into some limitations.
+     */
+    synchronize(timeoutMilliseconds?: number): Promise<void>;
+    /**
+     * Creates and returns a {@link EphemeralServiceClient} for an in-memory, ephemeral Fluid service.
+     *
+     * @param options - Options for the client. `minVersionForCollaboration` may be omitted (since all collaborators
+     * are in the same process, it defaults to the current version). `service` may be omitted to allocate a new
+     * {@link EphemeralService} dedicated to this client, or provided to connect the client to an existing service instance.
+     *
+     * @remarks
+     * The service is ephemeral and in-memory: all documents are held by the {@link EphemeralService} the client is
+     * connected to, and live for as long as that service is open — independent of whether any container for them is open.
+     * A document created and attached (obtaining an `id`) can be loaded by `id` for as long as its service remains open,
+     * even after every container for it has been closed.
+     * Closing the service (via {@link EphemeralService.close} or {@link cleanupEphemeralService}) discards all of its
+     * documents and releases its resources; afterwards those `id`s can no longer be loaded.
+     *
+     * When no `service` is provided, a new one is allocated for this client (accessible via {@link EphemeralServiceClient.service}).
+     * Provide the same {@link EphemeralService} to multiple clients (via `options.service`) to have them collaborate on the
+     * same documents, and control that service's lifetime explicitly.
+     *
+     * Since a service holds timers while open, tests should close the services they use (e.g. via
+     * {@link cleanupEphemeralService} in an `afterEach`) to avoid lingering timers that can hang test runners.
+     *
+     * @privateRemarks
+     * TODO: We should provide a way to extract (for potential serialization as test data) and load documents into a service.
+     * This is needed to use this API surface for testing reference documents.
+     * Ideally we would provide a service agnostic way to do the export, but likely only support loading them into the local service.
+     * This can be done via an API on FluidContainer (or a free function taking one) to do the export, then adding a
+     * service specific API (on {@link EphemeralService}) to load from the export format and return the ID of the loaded document.
+     */
+    newClient(options: ServiceOptions): EphemeralServiceClient;
+    /**
+     * A client connected to this service using the default options.
+     */
+    readonly defaultClient: EphemeralServiceClient;
+}
+/**
+ * A {@link @fluidframework/driver-definitions#ServiceClient} connected to a specific {@link EphemeralService}.
+ * @alpha @sealed
+ */
+export interface EphemeralServiceClient extends ServiceClient {
+    /**
+     * The service instance this client is connected to.
+     */
+    readonly service: EphemeralService;
+}
+/**
+ * A Fluid container backed by an ephemeral (in-memory) local service, implementing
+ * {@link @fluidframework/driver-definitions#FluidContainerWithService}.
+ *
+ * @remarks
+ * Data is stored in-memory by the {@link EphemeralService} the container's client is connected to (see
+ * {@link EphemeralServiceContainer.service}), enabling side-by-side collaboration testing without a real server.
+ *
+ * @internal
+ */
+export declare class EphemeralServiceContainer<TData> extends ServiceContainerBase<TData, EphemeralServiceOptions> implements FluidContainerWithService<TData> {
+    readonly service: EphemeralService;
+    static createDetached<T>(registry: DataStoreRegistry<T>, options: EphemeralServiceOptions, root: DataStoreKind<T>): Promise<EphemeralServiceContainer<T>>;
+    static load<T>(registry: DataStoreRegistry<T>, options: EphemeralServiceOptions, id: string): Promise<EphemeralServiceContainer<T> & FluidContainerAttached<T>>;
+    private constructor();
+    close(): void;
+    protected createAttachRequest(): IRequest;
+}
+//# sourceMappingURL=ephemeralService.d.ts.map

package/dist/ephemeralService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ephemeralService.d.ts","sourceRoot":"","sources":["../src/ephemeralService.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAWH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iCAAiC,CAAC;AAChE,OAAO,EAEN,KAAK,cAAc,EACnB,MAAM,0CAA0C,CAAC;AAElD,OAAO,KAAK,EACX,aAAa,EACb,iBAAiB,EACjB,sBAAsB,EACtB,yBAAyB,EAEzB,aAAa,EACb,cAAc,EACd,MAAM,6CAA6C,CAAC;AAErD,OAAO,EAMN,oBAAoB,EACpB,MAAM,wCAAwC,CAAC;AAWhD;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,UAAO,GAAG,gBAAgB,CAUxE;AAED;;;;;;;GAOG;AACH,wBAAsB,uBAAuB,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CASvF;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,IAAI,gBAAgB,CAK7D;AAED;;;;;GAKG;AACH,MAAM,WAAW,uBAAwB,SAAQ,cAAc;IAC9D;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,gBAAgB,CAAC;CACnC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,MAAM,WAAW,gBAAiB,SAAQ,cAAc,CAAC,SAAS,CAAC,kBAAkB,CAAC,CAAC;IACtF;;;;;;;;OAQG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvB;;;;;;;;;;;;OAYG;IACH,WAAW,CAAC,mBAAmB,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEzD;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,SAAS,CAAC,OAAO,EAAE,cAAc,GAAG,sBAAsB,CAAC;IAE3D;;OAEG;IACH,QAAQ,CAAC,aAAa,EAAE,sBAAsB,CAAC;CAC/C;AA0KD;;;GAGG;AACH,MAAM,WAAW,sBAAuB,SAAQ,aAAa;IAC5D;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,gBAAgB,CAAC;CACnC;AAuDD;;;;;;;;;GASG;AACH,qBAAa,yBAAyB,CAAC,KAAK,CAC3C,SAAQ,oBAAoB,CAAC,KAAK,EAAE,uBAAuB,CAC3D,YAAW,yBAAyB,CAAC,KAAK,CAAC;IAE3C,SAAgB,OAAO,EAAE,gBAAgB,CAAC;WAEtB,cAAc,CAAC,CAAC,EACnC,QAAQ,EAAE,iBAAiB,CAAC,CAAC,CAAC,EAC9B,OAAO,EAAE,uBAAuB,EAChC,IAAI,EAAE,aAAa,CAAC,CAAC,CAAC,GACpB,OAAO,CAAC,yBAAyB,CAAC,CAAC,CAAC,CAAC;WAuBpB,IAAI,CAAC,CAAC,EACzB,QAAQ,EAAE,iBAAiB,CAAC,CAAC,CAAC,EAC9B,OAAO,EAAE,uBAAuB,EAChC,EAAE,EAAE,MAAM,GACR,OAAO,CAAC,yBAAyB,CAAC,CAAC,CAAC,GAAG,sBAAsB,CAAC,CAAC,CAAC,CAAC;IA2BpE,OAAO;IAaS,KAAK,IAAI,IAAI;IAO7B,SAAS,CAAC,mBAAmB,IAAI,QAAQ;CAIzC"}

package/dist/ephemeralService.js

@@ -0,0 +1,295 @@
+"use strict";
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EphemeralServiceContainer = exports.getDefaultEphemeralService = exports.cleanupEphemeralService = exports.startEphemeralService = void 0;
+const internal_1 = require("@fluidframework/container-definitions/internal");
+const internal_2 = require("@fluidframework/container-loader/internal");
+const internal_3 = require("@fluidframework/container-runtime/internal");
+const internal_4 = require("@fluidframework/core-interfaces/internal");
+const internal_5 = require("@fluidframework/core-utils/internal");
+const internal_6 = require("@fluidframework/driver-definitions/internal");
+const internal_7 = require("@fluidframework/runtime-utils/internal");
+const server_local_server_1 = require("@fluidframework/server-local-server");
+const internal_8 = require("@fluidframework/driver-utils/internal");
+const localDocumentServiceFactory_js_1 = require("./localDocumentServiceFactory.js");
+const localResolver_js_1 = require("./localResolver.js");
+const packageVersion_js_1 = require("./packageVersion.js");
+/**
+ * Starts and returns a new {@link EphemeralService}.
+ * @param isDefault - Whether this service should saved as the default service for {@link cleanupEphemeralService} to cleanup.
+ * Defaults to true.
+ * @remarks
+ * The returned service owns an in-memory server and holds the documents created through clients connected to it.
+ * {@link cleanupEphemeralService} can be used to ensure the service is properly cleaned up (a no-op if stopped/closed already).
+ *
+ * As a service, it may start timers which may require an explicit `close` to fully free.
+ * @alpha
+ */
+function startEphemeralService(isDefault = true) {
+    if (isDefault && defaultEphemeralService) {
+        throw new internal_8.UsageError("A default EphemeralService is already running");
+    }
+    const service = new EphemeralServiceImplementation();
+    if (isDefault) {
+        defaultEphemeralService = service;
+    }
+    return service;
+}
+exports.startEphemeralService = startEphemeralService;
+/**
+ * Cleans up the service passed in {@link startEphemeralService}, or the {@link getDefaultEphemeralService|default} if none is passed.
+ * @remarks
+ * This closes the service, and all its containers.
+ * This is a good way to ensure the service and its containers leave no lingering timers
+ * which could leak memory, trigger asynchronous work or prevent a clean process exit.
+ * @alpha
+ */
+async function cleanupEphemeralService(service) {
+    const toCleanup = service ?? defaultEphemeralService;
+    if (toCleanup) {
+        // TODO: we may want to make closing of containers a separate operation which is done here.
+        await toCleanup.close();
+    }
+    if (toCleanup === defaultEphemeralService) {
+        defaultEphemeralService = undefined;
+    }
+}
+exports.cleanupEphemeralService = cleanupEphemeralService;
+/**
+ * Get the default {@link EphemeralService} if one has been {@link startEphemeralService|started}.
+ * @throws If no default service is running.
+ * @alpha
+ */
+function getDefaultEphemeralService() {
+    if (defaultEphemeralService) {
+        return defaultEphemeralService;
+    }
+    throw new internal_8.UsageError("No default EphemeralService is running");
+}
+exports.getDefaultEphemeralService = getDefaultEphemeralService;
+/**
+ * The {@link defaultEphemeralService} if one has been {@link startEphemeralService|started}.
+ */
+let defaultEphemeralService;
+/**
+ * The concrete implementation of {@link EphemeralService}.
+ * @remarks
+ * Kept module-private so its mutable state and internal helpers are not part of the public API.
+ * Narrow an {@link EphemeralService} to it with `EphemeralServiceImplementation.narrow`.
+ */
+class EphemeralServiceImplementation extends internal_4.ErasedTypeImplementation {
+    constructor() {
+        super();
+        // A single server is shared by all containers connected to this service so they can communicate with each other.
+        this.server = server_local_server_1.LocalDeltaConnectionServer.create(
+        // new LocalSessionStorageDbFactory(),
+        );
+        this.documentServiceFactory = new localDocumentServiceFactory_js_1.LocalDocumentServiceFactory(this.server);
+        this.containers = new Set();
+        this.closed = false;
+        this.defaultClient = this.newClient();
+    }
+    newClient(options) {
+        const finalOptions = {
+            minVersionForCollaboration: options?.minVersionForCollaboration ?? (0, internal_6.featureVersion)(packageVersion_js_1.pkgVersion),
+            service: this,
+        };
+        return new EphemeralServiceClientImplementation(finalOptions);
+    }
+    async close() {
+        if (this.closed) {
+            return;
+        }
+        this.closed = true;
+        // Close every open container via the same public close() path a user would use.
+        // We might want to remove this.
+        const toClose = [...this.containers];
+        this.containers.clear();
+        for (const c of toClose) {
+            c.close();
+        }
+        // Shut down the in-memory server. Its timers (e.g. the Deli read-client idle `setInterval`) belong to the
+        // server rather than any container, so closing containers alone would leave them running.
+        await this.server.close();
+    }
+    async synchronize(timeoutMilliseconds = 30_000) {
+        // Timeout to allow for better errors in the case of hangs.
+        let timedOut = false;
+        let deadlineTimer;
+        const deadline = new Promise((resolve) => {
+            deadlineTimer = setTimeout(() => {
+                timedOut = true;
+                resolve(true);
+            }, timeoutMilliseconds);
+        });
+        try {
+            // Require two consecutive quiescent passes (no dirty containers and no pending server work),
+            // each separated by a macrotask turn, to give late side effects a chance to surface.
+            let clean = 0;
+            while (clean < 2) {
+                if (timedOut) {
+                    throw new internal_8.UsageError(`EphemeralService.synchronize timed out after ${timeoutMilliseconds}ms waiting for local containers to quiesce.`);
+                }
+                // Yield a macrotask turn *first*, so the local server's scheduled broadcast send and each
+                // container's inbound op processing can run before we sample their state below. Sampling
+                // hasPendingWork() in a tight `while (await ...)` loop instead would starve that scheduled
+                // send (it is a macrotask, while the await resolves on the microtask queue) and could hang.
+                await new Promise((resolve) => {
+                    setTimeout(resolve, 0);
+                });
+                // Prune any containers that have closed since the last pass.
+                for (const container of [...this.containers]) {
+                    if (container.container.closed) {
+                        this.containers.delete(container);
+                    }
+                }
+                const containersToApply = [...this.containers].map((container) => container.container);
+                // Ignore readonly/disconnected dirty containers: they can't send ops, so nothing can be done about them being dirty here.
+                // Neither state is reachable through the ephemeral service API today, but the checks are cheap and keep this robust to future changes.
+                const dirtyContainers = containersToApply.filter((c) => {
+                    const { deltaManager, isDirty, connectionState } = c;
+                    return (connectionState !== internal_1.ConnectionState.Disconnected &&
+                        deltaManager.readOnlyInfo.readonly !== true &&
+                        isDirty);
+                });
+                if (dirtyContainers.length > 0) {
+                    // Bound this wait by the shared deadline: a container that never saves (and never
+                    // closes) must not block past the overall timeout, since the top-of-loop check can't
+                    // run while we are awaiting here.
+                    await Promise.race([
+                        Promise.all(dirtyContainers.map(async (c) => Promise.race([
+                            new Promise((resolve) => c.once("saved", resolve)),
+                            new Promise((resolve) => c.once("closed", resolve)),
+                        ]))),
+                        deadline,
+                    ]);
+                    clean = 0;
+                    continue;
+                }
+                // Sample pending server work once per pass (the macrotask yield above gave the broadcaster's
+                // scheduled send a chance to run first).
+                if (await Promise.race([this.server.hasPendingWork(), deadline])) {
+                    clean = 0;
+                    continue;
+                }
+                clean++;
+            }
+        }
+        finally {
+            clearTimeout(deadlineTimer);
+        }
+    }
+    /**
+     * The document service factory for this service.
+     * @remarks Internal helper for {@link EphemeralServiceContainer}; not part of the public {@link EphemeralService} API.
+     */
+    getDocumentServiceFactory() {
+        (0, internal_5.assert)(!this.closed, 0xd11 /* Cannot create or load containers on a closed EphemeralService */);
+        return this.documentServiceFactory;
+    }
+    /**
+     * Registers a newly created container as connected to this service.
+     * @remarks Internal helper for {@link EphemeralServiceContainer}; not part of the public {@link EphemeralService} API.
+     */
+    addContainer(container) {
+        this.containers.add(container);
+    }
+    /**
+     * Removes a now-closed container from this service.
+     * @remarks Internal helper for {@link EphemeralServiceContainer}; not part of the public {@link EphemeralService} API.
+     */
+    removeContainer(container) {
+        this.containers.delete(container);
+    }
+}
+class EphemeralServiceClientImplementation extends internal_7.ServiceClientImplementation {
+    constructor(options) {
+        super(options, EphemeralServiceContainer);
+        this.service = options.service;
+    }
+}
+const containerRuntimeLoader = async (parameters) => {
+    const { runtime } = await internal_3.ContainerRuntime.loadRuntime2({
+        context: parameters.context,
+        registry: parameters.registry,
+        provideEntryPoint: parameters.provideEntryPoint,
+        existing: parameters.existing,
+        minVersionForCollab: parameters.minVersionForCollab,
+        runtimeOptions: { enableRuntimeIdCompressor: "on" },
+    });
+    if (!parameters.existing) {
+        (0, internal_5.assert)(parameters.newContainerRootType !== undefined, 0xd12 /* Root data store kind must be provided for new containers */);
+        const dataStore = await runtime.createDataStore(parameters.newContainerRootType);
+        const aliasResult = await dataStore.trySetAlias(internal_7.rootDataStoreId);
+        (0, internal_5.assert)(aliasResult === "Success", 0xd13 /* Should be able to set alias on new data store */);
+    }
+    return runtime;
+};
+const urlResolver = new localResolver_js_1.LocalResolver();
+/**
+ * Create a request to open an existing document.
+ *
+ * @param documentId - the existing document to open.
+ * @privateRemarks
+ * Like createLocalResolverCreateNewRequest, but without the option to create a new document.
+ * TODO: At some point we should avoid specifying the URL in so many places, but the current APIs don't accommodate it yet.
+ */
+const createLoadExistingRequest = (documentId) => {
+    return { url: `http://localhost:3000/${documentId}` };
+};
+let documentIdCounter = 0;
+/**
+ * A Fluid container backed by an ephemeral (in-memory) local service, implementing
+ * {@link @fluidframework/driver-definitions#FluidContainerWithService}.
+ *
+ * @remarks
+ * Data is stored in-memory by the {@link EphemeralService} the container's client is connected to (see
+ * {@link EphemeralServiceContainer.service}), enabling side-by-side collaboration testing without a real server.
+ *
+ * @internal
+ */
+class EphemeralServiceContainer extends internal_7.ServiceContainerBase {
+    static async createDetached(registry, options, root) {
+        EphemeralServiceImplementation.narrow(options.service);
+        const container = await (0, internal_2.createDetachedContainer)({
+            codeDetails: { package: "1.0" },
+            urlResolver,
+            documentServiceFactory: options.service.getDocumentServiceFactory(),
+            codeLoader: (0, internal_7.makeCodeLoader)(registry, options.minVersionForCollaboration, containerRuntimeLoader, root),
+        });
+        return new EphemeralServiceContainer(registry, options, container, (await container.getEntryPoint()), undefined);
+    }
+    static async load(registry, options, id) {
+        EphemeralServiceImplementation.narrow(options.service);
+        const containerInner = await (0, internal_2.loadExistingContainer)({
+            request: createLoadExistingRequest(id),
+            urlResolver,
+            documentServiceFactory: options.service.getDocumentServiceFactory(),
+            codeLoader: (0, internal_7.makeCodeLoader)(registry, options.minVersionForCollaboration, containerRuntimeLoader),
+        });
+        const container = new EphemeralServiceContainer(registry, options, containerInner, (await containerInner.getEntryPoint()), id);
+        (0, internal_5.assert)(container.id !== undefined, 0xd14 /* id should be defined when loading a container */);
+        return container;
+    }
+    constructor(registry, options, container, data, id) {
+        super(registry, options, container, data, id);
+        this.service = options.service;
+        EphemeralServiceImplementation.narrow(this.service);
+        this.service.addContainer(this);
+    }
+    close() {
+        super.close();
+        // Remove this now-closed container from its service's set of open containers.
+        EphemeralServiceImplementation.narrow(this.service);
+        this.service.removeContainer(this);
+    }
+    createAttachRequest() {
+        const documentId = (documentIdCounter++).toString();
+        return (0, localResolver_js_1.createLocalResolverCreateNewRequest)(documentId);
+    }
+}
+exports.EphemeralServiceContainer = EphemeralServiceContainer;
+//# sourceMappingURL=ephemeralService.js.map