@fluidframework/local-driver 3.1.0 → 3.3.0

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # @fluidframework/local-driver
 
+## 3.3.0
+
+Dependency updates only.
+
+## 3.2.0
+
+### Minor Changes
+
+- Collect container telemetry through ServiceClient ([#28259](https://github.com/microsoft/FluidFramework/pull/28259)) [11261004291](https://github.com/microsoft/FluidFramework/commit/11261004291599575a23483fbaf8b20f4ff1afc1)
+
+  The alpha [ServiceOptions](https://fluidframework.com/docs/api/driver-definitions/serviceoptions-interface) interface now accepts an optional `logger`.
+  Session, ephemeral, and Tinylicious clients forward telemetry from containers they create or load to this logger.
+  Existing callers can omit the option without changing their behavior.
+
+  ```typescript
+  import { startEphemeralService } from "@fluidframework/local-driver/alpha";
+
+  const service = startEphemeralService();
+  const client = service.newClient({
+    oldestSupportedClient: "2.100.0",
+    logger: {
+      send(event) {
+        console.log(event);
+      },
+    },
+  });
+  ```
+
+  The same `logger` option is supported by `getSessionService().newClient(...)` and `createTinyliciousServiceClient(...)`.
+
+- Add session-storage-backed local services ([#27902](https://github.com/microsoft/FluidFramework/pull/27902)) [da0dd40c087](https://github.com/microsoft/FluidFramework/commit/da0dd40c087b075822f0a9be723e1879f25d23b5)
+
+  The new alpha [`getSessionService`](https://fluidframework.com/docs/api/local-driver/getsessionservice-function) API provides a [`ServiceClient`](https://fluidframework.com/docs/api/driver-definitions/serviceclient-interface) compatible way to use the browser-local Fluid service that retains attached documents across page reloads in the same browser tab. Calls within one JavaScript realm share a lazily created service for the lifetime of that realm. Local services also expose APIs to list and delete their stored documents.
+
+  Session storage can be shared by separate same-origin JavaScript realms or applications loading separate copies of the package. Such instances run independent local servers, so concurrently editing the same stored document across them is unsupported.
+
+  The alpha `EphemeralServiceClient` type has been replaced by the more general [`LocalServiceClient`](https://fluidframework.com/docs/api/local-driver/localserviceclient-interface) type. Update type imports and annotations to use [`LocalServiceClient`](https://fluidframework.com/docs/api/local-driver/localserviceclient-interface)<[`EphemeralService`](https://fluidframework.com/docs/api/local-driver/ephemeralservice-interface)>.
+
 ## 3.1.0
 
 Dependency updates only.

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

@@ -8,20 +8,34 @@
 export function cleanupEphemeralService(service?: EphemeralService): Promise<void>;
 
 // @alpha @sealed
-export interface EphemeralService extends ErasedBaseType<readonly ["EphemeralService"]> {
+export interface EphemeralService extends LocalService<LocalServiceClient<EphemeralService>> {
     close(): Promise<void>;
-    readonly defaultClient: EphemeralServiceClient;
-    newClient(options: ServiceOptions): EphemeralServiceClient;
+}
+
+// @alpha
+export function getDefaultEphemeralService(): EphemeralService;
+
+// @alpha
+export function getSessionService(): SessionService;
+
+// @alpha @sealed
+export interface LocalService<out TClient extends ServiceClient = LocalServiceClient> extends ErasedBaseType<readonly ["LocalService", TClient]> {
+    readonly defaultClient: TClient;
+    deleteAllDocuments(): Promise<void>;
+    deleteDocument(id: string): Promise<void>;
+    listDocumentIds(): Promise<readonly string[]>;
+    newClient(options: ServiceOptions): TClient;
     synchronize(timeoutMilliseconds?: number): Promise<void>;
 }
 
 // @alpha @sealed
-export interface EphemeralServiceClient extends ServiceClient {
-    readonly service: EphemeralService;
+export interface LocalServiceClient<out TService extends LocalService<ServiceClient> = LocalService<ServiceClient>> extends ServiceClient {
+    readonly service: TService;
 }
 
-// @alpha
-export function getDefaultEphemeralService(): EphemeralService;
+// @alpha @sealed
+export interface SessionService extends LocalService<LocalServiceClient<SessionService>> {
+}
 
 // @alpha
 export function startEphemeralService(isDefault?: boolean): EphemeralService;

package/dist/alpha.d.ts

@@ -11,9 +11,12 @@
 export {
 	// #region @alpha APIs
 	EphemeralService, 
-	EphemeralServiceClient, 
+	LocalService, 
+	LocalServiceClient, 
+	SessionService, 
 	cleanupEphemeralService, 
 	getDefaultEphemeralService, 
+	getSessionService, 
 	startEphemeralService
 	// #endregion
 } from "./index.js";

package/dist/ephemeralService.d.ts

@@ -4,7 +4,7 @@
  */
 import type { IRequest } from "@fluidframework/core-interfaces";
 import { type ErasedBaseType } from "@fluidframework/core-interfaces/internal";
-import { type DataStoreKind, type DataStoreRegistry, type FluidContainerAttached, type FluidContainerWithService, type OldestSupportedServiceClientVersion, type ServiceClient, type ServiceOptions } from "@fluidframework/driver-definitions/internal";
+import { type DataStoreKind, type DataStoreRegistry, type FluidContainerAttached, type FluidContainerWithService, type ServiceClient, type ServiceOptions } from "@fluidframework/driver-definitions/internal";
 import { ServiceContainerBase } from "@fluidframework/runtime-utils/internal";
 /**
  * Starts and returns a new {@link EphemeralService}.
@@ -18,6 +18,20 @@ import { ServiceContainerBase } from "@fluidframework/runtime-utils/internal";
  * @alpha
  */
 export declare function startEphemeralService(isDefault?: boolean): EphemeralService;
+/**
+ * Gets the session-storage-backed local Fluid service for the current JavaScript realm, creating it on first use.
+ *
+ * @remarks
+ * Attached documents remain available after a page reload within the same browser tab. Repeated calls return
+ * the same service instance within the current JavaScript realm.
+ *
+ * This service is only available in browser environments that provide `sessionStorage`.
+ * @returns A local service backed by browser session storage.
+ * @alpha
+ */
+export declare function getSessionService(): SessionService;
+/** Closes and clears the current session service for test isolation. */
+export declare function resetSessionServiceForTesting(): Promise<void>;
 /**
  * Cleans up the service passed in {@link startEphemeralService}, or the {@link getDefaultEphemeralService|default} if none is passed.
  * @remarks
@@ -34,23 +48,91 @@ export declare function cleanupEphemeralService(service?: EphemeralService): Pro
  */
 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.
+ * Internal options for creating a local service client, extending
+ * {@link @fluidframework/driver-definitions#ServiceOptions} with the service the client should connect to.
  * @input
  * @internal
  */
-export interface EphemeralServiceOptions extends ServiceOptions {
+export interface LocalServiceOptions<TService extends LocalService = LocalService> extends ServiceOptions {
     /**
-     * {@inheritdoc @fluidframework/driver-definitions#ServiceOptions.oldestSupportedClient}
+     * The service instance to connect to.
      */
-    readonly oldestSupportedClient: OldestSupportedServiceClientVersion;
+    readonly service: TService;
+}
+/**
+ * Internal options for creating a {@link LocalServiceClient} connected to an {@link EphemeralService}.
+ * @input
+ * @internal
+ */
+export interface EphemeralServiceOptions extends LocalServiceOptions<EphemeralService> {
+}
+/**
+ * A local Fluid service with an explicitly managed lifecycle.
+ * @remarks
+ * There are two implementations of this interface with different document lifetimes:
+ * {@link EphemeralService} and {@link SessionService}.
+ *
+ * @typeParam TClient - The type of client this service creates.
+ * @alpha @sealed
+ */
+export interface LocalService<out TClient extends ServiceClient = LocalServiceClient> extends ErasedBaseType<readonly ["LocalService", TClient]> {
     /**
-     * The service instance to connect to.
+     * Lists the IDs of documents currently stored by this service.
+     */
+    listDocumentIds(): Promise<readonly string[]>;
+    /**
+     * Deletes a stored document.
+     *
+     * @remarks
+     * Deletion is only allowed when this service has no open containers because resetting the local
+     * server invalidates all of its active connections. Content-addressed summary data shared with other
+     * documents may be retained until {@link LocalService.deleteAllDocuments} is called.
+     * Only one call to {@link LocalService.deleteDocument} or {@link LocalService.deleteAllDocuments}
+     * may be in progress at a time.
+     *
+     * @param id - The ID of the document to delete.
+     * @throws A `UsageError` if the service is closed, another document deletion is in progress, or the
+     * service has open containers.
+     */
+    deleteDocument(id: string): Promise<void>;
+    /**
+     * Deletes all documents stored by this service.
+     *
+     * @remarks
+     * Deletion is only allowed when this service has no open containers because resetting the local
+     * server invalidates all of its active connections.
+     * Only one call to {@link LocalService.deleteDocument} or {@link LocalService.deleteAllDocuments}
+     * may be in progress at a time.
+     * @throws A `UsageError` if the service is closed, another document deletion is in progress, or the
+     * service has open containers.
+     */
+    deleteAllDocuments(): 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.
+     * @throws A `UsageError` if the containers do not quiesce before the timeout expires.
+     *
+     * @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.
+     */
+    synchronize(timeoutMilliseconds?: number): Promise<void>;
+    /**
+     * Creates a client connected to this service.
+     *
+     * @param options - Collaboration options for the client.
+     */
+    newClient(options: ServiceOptions): TClient;
+    /**
+     * A client connected to this service using the default options.
      */
-    readonly service: EphemeralService;
+    readonly defaultClient: TClient;
 }
 /**
- * An in-memory Fluid service that can produce connected {@link EphemeralServiceClient}s.
+ * An in-memory Fluid service that can produce connected {@link LocalServiceClient}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
@@ -68,20 +150,20 @@ export interface EphemeralServiceOptions extends ServiceOptions {
  * document with different `oldestSupportedClient` 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
+ * This is an erased type: its only implementation is the module-private `LocalServiceImplementation`, 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.
+ * 1. Open: accepts connections from {@link LocalServiceClient}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.
+ * 3. Closed: no longer accepts connections from {@link LocalServiceClient}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.)
  *
@@ -90,75 +172,45 @@ export interface EphemeralServiceOptions extends ServiceOptions {
  *
  * @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>;
+export interface EphemeralService extends LocalService<LocalServiceClient<EphemeralService>> {
     /**
-     * Creates and returns a {@link EphemeralServiceClient} for an in-memory, ephemeral Fluid service.
-     *
-     * @param options - Options for the client. `oldestSupportedClient` may be omitted because all
-     * clients are in the same process, so 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.
+     * Closes all containers connected to this service and releases its active resources.
      *
      * @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.
+     * Closing is idempotent. Closing an ephemeral service permanently discards all documents it holds,
+     * so their IDs can no longer be loaded.
      */
-    readonly defaultClient: EphemeralServiceClient;
+    close(): Promise<void>;
+}
+/**
+ * A browser-local Fluid service that persists documents in session storage.
+ *
+ * @remarks
+ * Its attached documents remain available after a page reload within the same browser tab. The service is
+ * shared within the current JavaScript realm and intentionally has no close operation: its active resources
+ * live until the realm is unloaded.
+ *
+ * Session storage is shared more broadly than JavaScript module state. Separate same-origin realms, such as
+ * same-origin frames, or applications that load separate copies of this package can access the same stored
+ * documents while running independent local servers. Concurrently editing the same document from such realms
+ * is unsupported and may produce inconsistent stored state.
+ *
+ * Create one with {@link getSessionService}.
+ * @alpha @sealed
+ */
+export interface SessionService extends LocalService<LocalServiceClient<SessionService>> {
 }
 /**
- * A {@link @fluidframework/driver-definitions#ServiceClient} connected to a specific {@link EphemeralService}.
+ * A {@link @fluidframework/driver-definitions#ServiceClient} connected to a specific {@link LocalService}.
+ *
+ * @typeParam TService - The type of local service this client is connected to.
  * @alpha @sealed
  */
-export interface EphemeralServiceClient extends ServiceClient {
+export interface LocalServiceClient<out TService extends LocalService<ServiceClient> = LocalService<ServiceClient>> extends ServiceClient {
     /**
      * The service instance this client is connected to.
      */
-    readonly service: EphemeralService;
+    readonly service: TService;
 }
 /**
  * A Fluid container backed by an ephemeral (in-memory) local service, implementing
@@ -170,10 +222,10 @@ export interface EphemeralServiceClient extends ServiceClient {
  *
  * @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>>;
+export declare class EphemeralServiceContainer<TData> extends ServiceContainerBase<TData, LocalServiceOptions> implements FluidContainerWithService<TData> {
+    readonly service: LocalService;
+    static createDetached<T>(registry: DataStoreRegistry<T>, options: LocalServiceOptions, root: DataStoreKind<T>): Promise<EphemeralServiceContainer<T>>;
+    static load<T>(registry: DataStoreRegistry<T>, options: LocalServiceOptions, id: string): Promise<EphemeralServiceContainer<T> & FluidContainerAttached<T>>;
     private constructor();
     close(): void;
     protected createAttachRequest(): IRequest;

package/dist/ephemeralService.d.ts.map

@@ -1 +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,EAEN,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACtB,KAAK,sBAAsB,EAC3B,KAAK,yBAAyB,EAC9B,KAAK,mCAAmC,EAExC,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,MAAM,6CAA6C,CAAC;AACrD,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,qBAAqB,EAAE,mCAAmC,CAAC;IACpE;;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;AAyKD;;;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"}
+{"version":3,"file":"ephemeralService.d.ts","sourceRoot":"","sources":["../src/ephemeralService.ts"],"names":[],"mappings":"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"}

package/dist/ephemeralService.js

@@ -6,6 +6,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.EphemeralServiceContainer = void 0;
 exports.startEphemeralService = startEphemeralService;
+exports.getSessionService = getSessionService;
+exports.resetSessionServiceForTesting = resetSessionServiceForTesting;
 exports.cleanupEphemeralService = cleanupEphemeralService;
 exports.getDefaultEphemeralService = getDefaultEphemeralService;
 const internal_1 = require("@fluidframework/container-definitions/internal");
@@ -17,8 +19,10 @@ 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 uuid_1 = require("uuid");
 const localDocumentServiceFactory_js_1 = require("./localDocumentServiceFactory.js");
 const localResolver_js_1 = require("./localResolver.js");
+const localSessionStorageDb_js_1 = require("./localSessionStorageDb.js");
 const packageVersion_js_1 = require("./packageVersion.js");
 /**
  * Starts and returns a new {@link EphemeralService}.
@@ -35,12 +39,34 @@ function startEphemeralService(isDefault = true) {
     if (isDefault && defaultEphemeralService) {
         throw new internal_8.UsageError("A default EphemeralService is already running");
     }
-    const service = new EphemeralServiceImplementation();
+    const service = new LocalServiceImplementation();
     if (isDefault) {
         defaultEphemeralService = service;
     }
     return service;
 }
+/**
+ * Gets the session-storage-backed local Fluid service for the current JavaScript realm, creating it on first use.
+ *
+ * @remarks
+ * Attached documents remain available after a page reload within the same browser tab. Repeated calls return
+ * the same service instance within the current JavaScript realm.
+ *
+ * This service is only available in browser environments that provide `sessionStorage`.
+ * @returns A local service backed by browser session storage.
+ * @alpha
+ */
+function getSessionService() {
+    if (typeof sessionStorage === "undefined") {
+        throw new internal_8.UsageError("SessionService requires browser session storage");
+    }
+    return (sessionService ??= new LocalServiceImplementation(new localSessionStorageDb_js_1.LocalSessionStorageDbFactory()));
+}
+/** Closes and clears the current session service for test isolation. */
+async function resetSessionServiceForTesting() {
+    await sessionService?.close();
+    sessionService = undefined;
+}
 /**
  * Cleans up the service passed in {@link startEphemeralService}, or the {@link getDefaultEphemeralService|default} if none is passed.
  * @remarks
@@ -75,31 +101,59 @@ function getDefaultEphemeralService() {
  */
 let defaultEphemeralService;
 /**
- * The concrete implementation of {@link EphemeralService}.
+ * The lazily created session service for this JavaScript realm.
+ */
+let sessionService;
+/**
+ * The concrete implementation of local services.
  * @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`.
+ * Narrow a {@link LocalService} to it with `LocalServiceImplementation.narrow`.
  */
-class EphemeralServiceImplementation extends internal_4.ErasedTypeImplementation {
-    // A single server is shared by all containers connected to this service so they can communicate with each other.
-    server = server_local_server_1.LocalDeltaConnectionServer.create(
-    // new LocalSessionStorageDbFactory(),
-    );
-    documentServiceFactory = new localDocumentServiceFactory_js_1.LocalDocumentServiceFactory(this.server);
+class LocalServiceImplementation extends internal_4.ErasedTypeImplementation {
+    /**
+     * The active in-memory server shared by this service's containers so they can communicate.
+     * Replaced after document maintenance resets the server.
+     */
+    server;
+    /** The document service factory bound to the active {@link LocalServiceImplementation.server}. */
+    documentServiceFactory;
+    /** The persistent database factory retained when the active server is replaced. */
+    databaseFactory;
+    /** The open containers connected to this service. */
     containers = new Set();
+    /** Whether this service has been permanently closed. */
     closed = false;
-    constructor() {
+    /** Whether document deletion is temporarily preventing other service operations. */
+    maintenanceInProgress = false;
+    constructor(databaseFactory) {
         super();
+        this.server = server_local_server_1.LocalDeltaConnectionServer.create(databaseFactory);
+        this.databaseFactory = this.server.testDbFactory;
+        this.documentServiceFactory = new localDocumentServiceFactory_js_1.LocalDocumentServiceFactory(this.server);
         this.defaultClient = this.newClient();
     }
     newClient(options) {
         const finalOptions = {
+            ...options,
             oldestSupportedClient: options?.oldestSupportedClient ?? (0, internal_6.featureVersion)(packageVersion_js_1.pkgVersion),
             service: this,
         };
-        return new EphemeralServiceClientImplementation(finalOptions);
+        return new LocalServiceClientImplementation(finalOptions);
     }
     defaultClient;
+    async listDocumentIds() {
+        this.ensureAvailable();
+        const documentCollection = await this.server.databaseManager.getDocumentCollection();
+        const documents = await documentCollection.findAll();
+        return documents.map((document) => document.documentId);
+    }
+    async deleteDocument(id) {
+        await this.deleteDocuments(id);
+    }
+    async deleteAllDocuments() {
+        await this.deleteDocuments();
+    }
     async close() {
         if (this.closed) {
             return;
@@ -116,6 +170,57 @@ class EphemeralServiceImplementation extends internal_4.ErasedTypeImplementation
         // server rather than any container, so closing containers alone would leave them running.
         await this.server.close();
     }
+    ensureAvailable() {
+        if (this.closed) {
+            throw new internal_8.UsageError("Local service is closed");
+        }
+        if (this.maintenanceInProgress) {
+            throw new internal_8.UsageError("Local service document maintenance is already in progress");
+        }
+    }
+    /**
+     * Delete all documents unless `id` is specified, in which case only that document is deleted.
+     */
+    async deleteDocuments(id) {
+        this.ensureAvailable();
+        if (this.containers.size > 0) {
+            throw new internal_8.UsageError("Close all containers before deleting local service documents");
+        }
+        this.maintenanceInProgress = true;
+        let serverClosed = false;
+        try {
+            await this.server.close();
+            serverClosed = true;
+            const databaseManager = this.server.databaseManager;
+            const filter = id === undefined ? {} : { documentId: id };
+            const historianDatabase = this.databaseFactory.testDatabase;
+            const documentCollection = await databaseManager.getDocumentCollection();
+            const checkpointCollection = await databaseManager.getCheckpointCollection();
+            const deltaCollection = await databaseManager.getDeltaCollection(undefined, id);
+            const scribeDeltaCollection = await databaseManager.getScribeDeltaCollection(undefined, id);
+            const deletions = [
+                documentCollection.deleteMany(filter),
+                checkpointCollection.deleteMany(filter),
+                deltaCollection.deleteMany(filter),
+                scribeDeltaCollection.deleteMany(filter),
+                historianDatabase
+                    .collection("refs")
+                    .deleteMany(id === undefined ? {} : { _id: `heads/${id}` }),
+            ];
+            if (id === undefined) {
+                const nodeCollection = await databaseManager.getNodeCollection();
+                deletions.push(nodeCollection.deleteMany({}), historianDatabase.collection("blobs").deleteMany({}), historianDatabase.collection("commits").deleteMany({}), historianDatabase.collection("trees").deleteMany({}));
+            }
+            await Promise.all(deletions);
+        }
+        finally {
+            if (serverClosed) {
+                this.server = server_local_server_1.LocalDeltaConnectionServer.create(this.databaseFactory);
+                this.documentServiceFactory = new localDocumentServiceFactory_js_1.LocalDocumentServiceFactory(this.server);
+            }
+            this.maintenanceInProgress = false;
+        }
+    }
     async synchronize(timeoutMilliseconds = 30_000) {
         // Timeout to allow for better errors in the case of hangs.
         let timedOut = false;
@@ -188,6 +293,7 @@ class EphemeralServiceImplementation extends internal_4.ErasedTypeImplementation
      * @remarks Internal helper for {@link EphemeralServiceContainer}; not part of the public {@link EphemeralService} API.
      */
     getDocumentServiceFactory() {
+        this.ensureAvailable();
         (0, internal_5.assert)(!this.closed, 0xd11 /* Cannot create or load containers on a closed EphemeralService */);
         return this.documentServiceFactory;
     }
@@ -206,7 +312,7 @@ class EphemeralServiceImplementation extends internal_4.ErasedTypeImplementation
         this.containers.delete(container);
     }
 }
-class EphemeralServiceClientImplementation extends internal_7.ServiceClientImplementation {
+class LocalServiceClientImplementation extends internal_7.ServiceClientImplementation {
     service;
     constructor(options) {
         super(options, EphemeralServiceContainer);
@@ -242,7 +348,6 @@ const urlResolver = new localResolver_js_1.LocalResolver();
 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}.
@@ -256,9 +361,10 @@ let documentIdCounter = 0;
 class EphemeralServiceContainer extends internal_7.ServiceContainerBase {
     service;
     static async createDetached(registry, options, root) {
-        EphemeralServiceImplementation.narrow(options.service);
+        LocalServiceImplementation.narrow(options.service);
         const container = await (0, internal_2.createDetachedContainer)({
             codeDetails: { package: "1.0" },
+            logger: options.logger,
             urlResolver,
             documentServiceFactory: options.service.getDocumentServiceFactory(),
             codeLoader: (0, internal_7.makeCodeLoader)(registry, options.oldestSupportedClient, containerRuntimeLoader, root),
@@ -266,9 +372,10 @@ class EphemeralServiceContainer extends internal_7.ServiceContainerBase {
         return new EphemeralServiceContainer(registry, options, container, (await container.getEntryPoint()), undefined);
     }
     static async load(registry, options, id) {
-        EphemeralServiceImplementation.narrow(options.service);
+        LocalServiceImplementation.narrow(options.service);
         const containerInner = await (0, internal_2.loadExistingContainer)({
             request: createLoadExistingRequest(id),
+            logger: options.logger,
             urlResolver,
             documentServiceFactory: options.service.getDocumentServiceFactory(),
             codeLoader: (0, internal_7.makeCodeLoader)(registry, options.oldestSupportedClient, containerRuntimeLoader),
@@ -280,18 +387,17 @@ class EphemeralServiceContainer extends internal_7.ServiceContainerBase {
     constructor(registry, options, container, data, id) {
         super(registry, options, container, data, id);
         this.service = options.service;
-        EphemeralServiceImplementation.narrow(this.service);
+        LocalServiceImplementation.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);
+        LocalServiceImplementation.narrow(this.service);
         this.service.removeContainer(this);
     }
     createAttachRequest() {
-        const documentId = (documentIdCounter++).toString();
-        return (0, localResolver_js_1.createLocalResolverCreateNewRequest)(documentId);
+        return (0, localResolver_js_1.createLocalResolverCreateNewRequest)((0, uuid_1.v4)());
     }
 }
 exports.EphemeralServiceContainer = EphemeralServiceContainer;