@fluidframework/local-driver 3.0.2 → 3.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,43 @@
1
1
  # @fluidframework/local-driver
2
2
 
3
+ ## 3.2.0
4
+
5
+ ### Minor Changes
6
+
7
+ - Collect container telemetry through ServiceClient ([#28259](https://github.com/microsoft/FluidFramework/pull/28259)) [11261004291](https://github.com/microsoft/FluidFramework/commit/11261004291599575a23483fbaf8b20f4ff1afc1)
8
+
9
+ The alpha [ServiceOptions](https://fluidframework.com/docs/api/driver-definitions/serviceoptions-interface) interface now accepts an optional `logger`.
10
+ Session, ephemeral, and Tinylicious clients forward telemetry from containers they create or load to this logger.
11
+ Existing callers can omit the option without changing their behavior.
12
+
13
+ ```typescript
14
+ import { startEphemeralService } from "@fluidframework/local-driver/alpha";
15
+
16
+ const service = startEphemeralService();
17
+ const client = service.newClient({
18
+ oldestSupportedClient: "2.100.0",
19
+ logger: {
20
+ send(event) {
21
+ console.log(event);
22
+ },
23
+ },
24
+ });
25
+ ```
26
+
27
+ The same `logger` option is supported by `getSessionService().newClient(...)` and `createTinyliciousServiceClient(...)`.
28
+
29
+ - Add session-storage-backed local services ([#27902](https://github.com/microsoft/FluidFramework/pull/27902)) [da0dd40c087](https://github.com/microsoft/FluidFramework/commit/da0dd40c087b075822f0a9be723e1879f25d23b5)
30
+
31
+ 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.
32
+
33
+ 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.
34
+
35
+ 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)>.
36
+
37
+ ## 3.1.0
38
+
39
+ Dependency updates only.
40
+
3
41
  ## 3.0.0
4
42
 
5
43
  ### Minor Changes
package/README.md CHANGED
@@ -2,8 +2,7 @@
2
2
 
3
3
  TODO: document this package
4
4
 
5
- <!-- AUTO-GENERATED-CONTENT:START (LIBRARY_README_HEADER) -->
6
-
5
+ <!-- markdown-magic:begin {"transform":"library-readme-header","headingLevel":2} -->
7
6
  <!-- prettier-ignore-start -->
8
7
  <!-- NOTE: This section is automatically generated using @fluid-tools/markdown-magic. Do not update these generated contents directly. -->
9
8
 
@@ -39,11 +38,9 @@ Import the `legacy` APIs from `@fluidframework/local-driver/legacy`.
39
38
  Read the **@fluidframework/local-driver** API documentation at <https://fluidframework.com/docs/apis/local-driver>.
40
39
 
41
40
  <!-- prettier-ignore-end -->
41
+ <!-- markdown-magic:end -->
42
42
 
43
- <!-- AUTO-GENERATED-CONTENT:END -->
44
-
45
- <!-- AUTO-GENERATED-CONTENT:START (README_FOOTER) -->
46
-
43
+ <!-- markdown-magic:begin {"transform":"readme-footer","headingLevel":2} -->
47
44
  <!-- prettier-ignore-start -->
48
45
  <!-- NOTE: This section is automatically generated using @fluid-tools/markdown-magic. Do not update these generated contents directly. -->
49
46
 
@@ -60,29 +57,29 @@ To request support for a configuration that is not listed, file an issue.
60
57
  The product team will evaluate your request.
61
58
  In the issue, specify the current status of the configuration:
62
59
 
63
- - The configuration works but needs official support.
64
- - The configuration does not work and requires changes.
60
+ - The configuration works but needs official support.
61
+ - The configuration does not work and requires changes.
65
62
 
66
63
  ### Supported Runtimes
67
64
 
68
- - Fluid Framework supports Node.js versions 22 and 24 while they receive [upstream support](https://nodejs.org/en/about/previous-releases).
69
- - Fluid Framework will stop support for version 22 [when upstream support ends on 2027-04-30](https://github.com/nodejs/release#release-schedule).
70
- - Fluid Framework does not support Node.js with the `--no-experimental-fetch` flag.
71
- - Fluid Framework supports modern browsers that support the ES2022 standard library.
65
+ - Fluid Framework supports Node.js versions 22 and 24 while they receive [upstream support](https://nodejs.org/en/about/previous-releases).
66
+ - Fluid Framework will stop support for version 22 [when upstream support ends on 2027-04-30](https://github.com/nodejs/release#release-schedule).
67
+ - Fluid Framework does not support Node.js with the `--no-experimental-fetch` flag.
68
+ - Fluid Framework supports modern browsers that support the ES2022 standard library.
72
69
 
73
70
  ### Supported Tools
74
71
 
75
- - [TypeScript 6.0](https://typescriptdocs.com/release-notes/TypeScript%206.0):
76
- - Fluid Framework supports all [`strict`](https://www.typescriptlang.org/tsconfig) options.
77
- - Set the build targets (`lib`, `target`) to `ES2022` or later.
78
- - Enable [`strictNullChecks`](https://www.typescriptlang.org/tsconfig).
79
- - Fluid Framework does not support [configuration options deprecated in TypeScript 6.0](https://typescriptdocs.com/release-notes/TypeScript%206.0#breaking-changes-and-deprecations-in-typescript-6-0).
80
- - Fluid Framework does not fully support `exactOptionalPropertyTypes`.
81
- If you enable this option, do not use `in`, `Reflect.has`, `Object.hasOwn`, or `Object.prototype.hasOwnProperty` to narrow members of Fluid Framework types.
82
- These methods can incorrectly exclude `undefined` from the possible values.
83
- - [webpack](https://webpack.js.org/) 5
84
- - We do not require a specific bundler.
85
- Other bundlers that handle ES Modules can work, but we actively test only webpack.
72
+ - [TypeScript 6.0](https://typescriptdocs.com/release-notes/TypeScript%206.0):
73
+ - Fluid Framework supports all [`strict`](https://www.typescriptlang.org/tsconfig) options.
74
+ - Set the build targets (`lib`, `target`) to `ES2022` or later.
75
+ - Enable [`strictNullChecks`](https://www.typescriptlang.org/tsconfig).
76
+ - Fluid Framework does not support [configuration options deprecated in TypeScript 6.0](https://typescriptdocs.com/release-notes/TypeScript%206.0#breaking-changes-and-deprecations-in-typescript-6-0).
77
+ - Fluid Framework does not fully support `exactOptionalPropertyTypes`.
78
+ If you enable this option, do not use `in`, `Reflect.has`, `Object.hasOwn`, or `Object.prototype.hasOwnProperty` to narrow members of Fluid Framework types.
79
+ These methods can incorrectly exclude `undefined` from the possible values.
80
+ - [webpack](https://webpack.js.org/) 5
81
+ - We do not require a specific bundler.
82
+ Other bundlers that handle ES Modules can work, but we actively test only webpack.
86
83
 
87
84
  ### Module Resolution
88
85
 
@@ -93,25 +90,25 @@ Do not use `Node10` module resolution.
93
90
 
94
91
  ### Module Formats
95
92
 
96
- - ES Modules:
97
- Use ES Modules to consume Fluid Framework client packages, including in Node.js.
98
- - CommonJS:
99
- Fluid Framework does not officially support CommonJS in version 3.0 or later.
93
+ - ES Modules:
94
+ Use ES Modules to consume Fluid Framework client packages, including in Node.js.
95
+ - CommonJS:
96
+ Fluid Framework does not officially support CommonJS in version 3.0 or later.
100
97
 
101
98
  ## Contribution Guidelines
102
99
 
103
100
  You can [contribute](https://github.com/microsoft/FluidFramework/blob/main/CONTRIBUTING.md) to Fluid Framework in these ways:
104
101
 
105
- - Answer questions in [GitHub Discussions](https://github.com/microsoft/FluidFramework/discussions).
106
- - [Submit bug reports](https://github.com/microsoft/FluidFramework/issues) and help verify fixes.
107
- - Review [source code changes](https://github.com/microsoft/FluidFramework/pulls).
108
- - [Contribute bug fixes](https://github.com/microsoft/FluidFramework/blob/main/CONTRIBUTING.md).
102
+ - Answer questions in [GitHub Discussions](https://github.com/microsoft/FluidFramework/discussions).
103
+ - [Submit bug reports](https://github.com/microsoft/FluidFramework/issues) and help verify fixes.
104
+ - Review [source code changes](https://github.com/microsoft/FluidFramework/pulls).
105
+ - [Contribute bug fixes](https://github.com/microsoft/FluidFramework/blob/main/CONTRIBUTING.md).
109
106
 
110
107
  For detailed instructions, read the [repo documentation](https://github.com/microsoft/FluidFramework/blob/main/docs/content/Home.md).
111
108
 
112
109
  This project follows the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
113
110
  For more information, read the [Code of Conduct frequently asked questions](https://opensource.microsoft.com/codeofconduct/faq/).
114
- For questions or comments, contact [opencode@microsoft.com](mailto:opencode@microsoft.com).
111
+ For questions or comments, contact <opencode@microsoft.com>.
115
112
 
116
113
  This project may contain Microsoft trademarks or logos for Microsoft projects, products, or services.
117
114
  Use of these trademarks or logos must follow Microsoft’s [Trademark & Brand Guidelines](https://www.microsoft.com/trademarks).
@@ -132,5 +129,4 @@ Use of these trademarks or logos must follow Microsoft's [Trademark & Brand Guid
132
129
  Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship.
133
130
 
134
131
  <!-- prettier-ignore-end -->
135
-
136
- <!-- AUTO-GENERATED-CONTENT:END -->
132
+ <!-- markdown-magic:end -->
@@ -8,20 +8,34 @@
8
8
  export function cleanupEphemeralService(service?: EphemeralService): Promise<void>;
9
9
 
10
10
  // @alpha @sealed
11
- export interface EphemeralService extends ErasedBaseType<readonly ["EphemeralService"]> {
11
+ export interface EphemeralService extends LocalService<LocalServiceClient<EphemeralService>> {
12
12
  close(): Promise<void>;
13
- readonly defaultClient: EphemeralServiceClient;
14
- newClient(options: ServiceOptions): EphemeralServiceClient;
13
+ }
14
+
15
+ // @alpha
16
+ export function getDefaultEphemeralService(): EphemeralService;
17
+
18
+ // @alpha
19
+ export function getSessionService(): SessionService;
20
+
21
+ // @alpha @sealed
22
+ export interface LocalService<out TClient extends ServiceClient = LocalServiceClient> extends ErasedBaseType<readonly ["LocalService", TClient]> {
23
+ readonly defaultClient: TClient;
24
+ deleteAllDocuments(): Promise<void>;
25
+ deleteDocument(id: string): Promise<void>;
26
+ listDocumentIds(): Promise<readonly string[]>;
27
+ newClient(options: ServiceOptions): TClient;
15
28
  synchronize(timeoutMilliseconds?: number): Promise<void>;
16
29
  }
17
30
 
18
31
  // @alpha @sealed
19
- export interface EphemeralServiceClient extends ServiceClient {
20
- readonly service: EphemeralService;
32
+ export interface LocalServiceClient<out TService extends LocalService<ServiceClient> = LocalService<ServiceClient>> extends ServiceClient {
33
+ readonly service: TService;
21
34
  }
22
35
 
23
- // @alpha
24
- export function getDefaultEphemeralService(): EphemeralService;
36
+ // @alpha @sealed
37
+ export interface SessionService extends LocalService<LocalServiceClient<SessionService>> {
38
+ }
25
39
 
26
40
  // @alpha
27
41
  export function startEphemeralService(isDefault?: boolean): EphemeralService;
package/dist/alpha.d.ts CHANGED
@@ -11,9 +11,12 @@
11
11
  export {
12
12
  // #region @alpha APIs
13
13
  EphemeralService,
14
- EphemeralServiceClient,
14
+ LocalService,
15
+ LocalServiceClient,
16
+ SessionService,
15
17
  cleanupEphemeralService,
16
18
  getDefaultEphemeralService,
19
+ getSessionService,
17
20
  startEphemeralService
18
21
  // #endregion
19
22
  } from "./index.js";
@@ -4,7 +4,7 @@
4
4
  */
5
5
  import type { IRequest } from "@fluidframework/core-interfaces";
6
6
  import { type ErasedBaseType } from "@fluidframework/core-interfaces/internal";
7
- import { type DataStoreKind, type DataStoreRegistry, type FluidContainerAttached, type FluidContainerWithService, type OldestSupportedServiceClientVersion, type ServiceClient, type ServiceOptions } from "@fluidframework/driver-definitions/internal";
7
+ import { type DataStoreKind, type DataStoreRegistry, type FluidContainerAttached, type FluidContainerWithService, type ServiceClient, type ServiceOptions } from "@fluidframework/driver-definitions/internal";
8
8
  import { ServiceContainerBase } from "@fluidframework/runtime-utils/internal";
9
9
  /**
10
10
  * Starts and returns a new {@link EphemeralService}.
@@ -18,6 +18,20 @@ import { ServiceContainerBase } from "@fluidframework/runtime-utils/internal";
18
18
  * @alpha
19
19
  */
20
20
  export declare function startEphemeralService(isDefault?: boolean): EphemeralService;
21
+ /**
22
+ * Gets the session-storage-backed local Fluid service for the current JavaScript realm, creating it on first use.
23
+ *
24
+ * @remarks
25
+ * Attached documents remain available after a page reload within the same browser tab. Repeated calls return
26
+ * the same service instance within the current JavaScript realm.
27
+ *
28
+ * This service is only available in browser environments that provide `sessionStorage`.
29
+ * @returns A local service backed by browser session storage.
30
+ * @alpha
31
+ */
32
+ export declare function getSessionService(): SessionService;
33
+ /** Closes and clears the current session service for test isolation. */
34
+ export declare function resetSessionServiceForTesting(): Promise<void>;
21
35
  /**
22
36
  * Cleans up the service passed in {@link startEphemeralService}, or the {@link getDefaultEphemeralService|default} if none is passed.
23
37
  * @remarks
@@ -34,23 +48,91 @@ export declare function cleanupEphemeralService(service?: EphemeralService): Pro
34
48
  */
35
49
  export declare function getDefaultEphemeralService(): EphemeralService;
36
50
  /**
37
- * Internal Options for creating an {@link EphemeralServiceClient}, extending {@link @fluidframework/driver-definitions#ServiceOptions}
38
- * with the {@link EphemeralService} the client should connect to.
51
+ * Internal options for creating a local service client, extending
52
+ * {@link @fluidframework/driver-definitions#ServiceOptions} with the service the client should connect to.
39
53
  * @input
40
54
  * @internal
41
55
  */
42
- export interface EphemeralServiceOptions extends ServiceOptions {
56
+ export interface LocalServiceOptions<TService extends LocalService = LocalService> extends ServiceOptions {
43
57
  /**
44
- * {@inheritdoc @fluidframework/driver-definitions#ServiceOptions.oldestSupportedClient}
58
+ * The service instance to connect to.
45
59
  */
46
- readonly oldestSupportedClient: OldestSupportedServiceClientVersion;
60
+ readonly service: TService;
61
+ }
62
+ /**
63
+ * Internal options for creating a {@link LocalServiceClient} connected to an {@link EphemeralService}.
64
+ * @input
65
+ * @internal
66
+ */
67
+ export interface EphemeralServiceOptions extends LocalServiceOptions<EphemeralService> {
68
+ }
69
+ /**
70
+ * A local Fluid service with an explicitly managed lifecycle.
71
+ * @remarks
72
+ * There are two implementations of this interface with different document lifetimes:
73
+ * {@link EphemeralService} and {@link SessionService}.
74
+ *
75
+ * @typeParam TClient - The type of client this service creates.
76
+ * @alpha @sealed
77
+ */
78
+ export interface LocalService<out TClient extends ServiceClient = LocalServiceClient> extends ErasedBaseType<readonly ["LocalService", TClient]> {
47
79
  /**
48
- * The service instance to connect to.
80
+ * Lists the IDs of documents currently stored by this service.
81
+ */
82
+ listDocumentIds(): Promise<readonly string[]>;
83
+ /**
84
+ * Deletes a stored document.
85
+ *
86
+ * @remarks
87
+ * Deletion is only allowed when this service has no open containers because resetting the local
88
+ * server invalidates all of its active connections. Content-addressed summary data shared with other
89
+ * documents may be retained until {@link LocalService.deleteAllDocuments} is called.
90
+ * Only one call to {@link LocalService.deleteDocument} or {@link LocalService.deleteAllDocuments}
91
+ * may be in progress at a time.
92
+ *
93
+ * @param id - The ID of the document to delete.
94
+ * @throws A `UsageError` if the service is closed, another document deletion is in progress, or the
95
+ * service has open containers.
96
+ */
97
+ deleteDocument(id: string): Promise<void>;
98
+ /**
99
+ * Deletes all documents stored by this service.
100
+ *
101
+ * @remarks
102
+ * Deletion is only allowed when this service has no open containers because resetting the local
103
+ * server invalidates all of its active connections.
104
+ * Only one call to {@link LocalService.deleteDocument} or {@link LocalService.deleteAllDocuments}
105
+ * may be in progress at a time.
106
+ * @throws A `UsageError` if the service is closed, another document deletion is in progress, or the
107
+ * service has open containers.
108
+ */
109
+ deleteAllDocuments(): Promise<void>;
110
+ /**
111
+ * Drives all containers connected to this service toward convergence, processing pending operations and
112
+ * waiting for all dirty containers to save.
113
+ *
114
+ * @param timeoutMilliseconds - The maximum time to wait for containers to quiesce, in milliseconds. Defaults to 30_000.
115
+ * @throws A `UsageError` if the containers do not quiesce before the timeout expires.
116
+ *
117
+ * @privateRemarks
118
+ * This is a best-effort implementation simplified from `LoaderContainerTracker.ensureSynchronized`.
119
+ * Currently it does not perform receiver-side sequence-number quiescence or wait for join/leave (audience) ops.
120
+ * See `LoaderContainerTracker.ensureSynchronized` for the fuller version this is based on.
121
+ */
122
+ synchronize(timeoutMilliseconds?: number): Promise<void>;
123
+ /**
124
+ * Creates a client connected to this service.
125
+ *
126
+ * @param options - Collaboration options for the client.
127
+ */
128
+ newClient(options: ServiceOptions): TClient;
129
+ /**
130
+ * A client connected to this service using the default options.
49
131
  */
50
- readonly service: EphemeralService;
132
+ readonly defaultClient: TClient;
51
133
  }
52
134
  /**
53
- * An in-memory Fluid service that can produce connected {@link EphemeralServiceClient}s.
135
+ * An in-memory Fluid service that can produce connected {@link LocalServiceClient}s.
54
136
  * @remarks
55
137
  * All documents created through clients connected to a given `EphemeralService` are held in-memory by that service.
56
138
  * Closing the service (via {@link EphemeralService.close} or {@link cleanupEphemeralService}) closes the connections
@@ -68,20 +150,20 @@ export interface EphemeralServiceOptions extends ServiceOptions {
68
150
  * document with different `oldestSupportedClient` values.
69
151
  * This also exposes a place to put APIs for preloading and exporting document contents in the future.
70
152
  *
71
- * This is an erased type: its only implementation is the module-private {@link EphemeralServiceImplementation}, which holds
153
+ * This is an erased type: its only implementation is the module-private `LocalServiceImplementation`, which holds
72
154
  * the mutable server and container state so it does not appear on this public type.
73
155
  *
74
156
  * TODO: formalize this lifecycle with an interface which documents these stages.
75
157
  * Lifecycle:
76
158
  * The intended lifecycle of an {@link EphemeralService} follows roughly the same pattern as containers:
77
159
  *
78
- * 1. Open: accepts connections from {@link EphemeralServiceClient}s, which can create and load containers.
160
+ * 1. Open: accepts connections from {@link LocalServiceClient}s, which can create and load containers.
79
161
  * Might have timers and event registrations which can trigger asynchronous work, and retain the object in memory.
80
162
  *
81
163
  * 2. Closing: asynchronous transition from open to closed. New use should behave as it closed, but may be cleaning up or saving resources asynchronously.
82
164
  * Timers and event registrations may still be active, but should be cleaned up by the time the transition to closed completes.
83
165
  *
84
- * 3. Closed: no longer accepts connections from {@link EphemeralServiceClient}s, and all containers connected to it are closed.
166
+ * 3. Closed: no longer accepts connections from {@link LocalServiceClient}s, and all containers connected to it are closed.
85
167
  * Should have no subscriptions to events or timers which could retain it in memory or trigger asynchronous work.
86
168
  * 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.)
87
169
  *
@@ -90,75 +172,45 @@ export interface EphemeralServiceOptions extends ServiceOptions {
90
172
  *
91
173
  * @alpha @sealed
92
174
  */
93
- export interface EphemeralService extends ErasedBaseType<readonly ["EphemeralService"]> {
94
- /**
95
- * Close this service, which closes all containers connected to it and releases its resources.
96
- * @remarks
97
- * All documents held by this service are discarded, and any timers it (or its containers) were keeping alive
98
- * are cleaned up.
99
- * The returned promise resolves once all asynchronous cleanup (including shutting down the in-memory server)
100
- * has completed.
101
- * Closing is idempotent: calling it again after the service is closed resolves without doing anything.
102
- */
103
- close(): Promise<void>;
104
- /**
105
- * Drives all containers connected to this service toward convergence, processing pending operations and
106
- * waiting for all dirty containers to save.
107
- *
108
- * @param timeoutMilliseconds - The maximum time to wait for containers to quiesce, in milliseconds. Defaults to 30_000.
109
- *
110
- * @privateRemarks
111
- * This is a best-effort implementation simplified from `LoaderContainerTracker.ensureSynchronized`.
112
- * Currently it does not perform receiver-side sequence-number quiescence or wait for join/leave (audience) ops.
113
- * See `LoaderContainerTracker.ensureSynchronized` for the fuller version this is based on.
114
- * For the currently exposed API surface, this should be sufficient,
115
- * but users down casting to internal types might run into some limitations.
116
- */
117
- synchronize(timeoutMilliseconds?: number): Promise<void>;
175
+ export interface EphemeralService extends LocalService<LocalServiceClient<EphemeralService>> {
118
176
  /**
119
- * Creates and returns a {@link EphemeralServiceClient} for an in-memory, ephemeral Fluid service.
120
- *
121
- * @param options - Options for the client. `oldestSupportedClient` may be omitted because all
122
- * clients are in the same process, so it defaults to the current version. `service` may be omitted to allocate a new
123
- * {@link EphemeralService} dedicated to this client, or provided to connect the client to an existing service instance.
177
+ * Closes all containers connected to this service and releases its active resources.
124
178
  *
125
179
  * @remarks
126
- * The service is ephemeral and in-memory: all documents are held by the {@link EphemeralService} the client is
127
- * connected to, and live for as long as that service is open — independent of whether any container for them is open.
128
- * A document created and attached (obtaining an `id`) can be loaded by `id` for as long as its service remains open,
129
- * even after every container for it has been closed.
130
- * Closing the service (via {@link EphemeralService.close} or {@link cleanupEphemeralService}) discards all of its
131
- * documents and releases its resources; afterwards those `id`s can no longer be loaded.
132
- *
133
- * When no `service` is provided, a new one is allocated for this client (accessible via {@link EphemeralServiceClient.service}).
134
- * Provide the same {@link EphemeralService} to multiple clients (via `options.service`) to have them collaborate on the
135
- * same documents, and control that service's lifetime explicitly.
136
- *
137
- * Since a service holds timers while open, tests should close the services they use (e.g. via
138
- * {@link cleanupEphemeralService} in an `afterEach`) to avoid lingering timers that can hang test runners.
139
- *
140
- * @privateRemarks
141
- * TODO: We should provide a way to extract (for potential serialization as test data) and load documents into a service.
142
- * This is needed to use this API surface for testing reference documents.
143
- * Ideally we would provide a service agnostic way to do the export, but likely only support loading them into the local service.
144
- * This can be done via an API on FluidContainer (or a free function taking one) to do the export, then adding a
145
- * service specific API (on {@link EphemeralService}) to load from the export format and return the ID of the loaded document.
146
- */
147
- newClient(options: ServiceOptions): EphemeralServiceClient;
148
- /**
149
- * A client connected to this service using the default options.
180
+ * Closing is idempotent. Closing an ephemeral service permanently discards all documents it holds,
181
+ * so their IDs can no longer be loaded.
150
182
  */
151
- readonly defaultClient: EphemeralServiceClient;
183
+ close(): Promise<void>;
184
+ }
185
+ /**
186
+ * A browser-local Fluid service that persists documents in session storage.
187
+ *
188
+ * @remarks
189
+ * Its attached documents remain available after a page reload within the same browser tab. The service is
190
+ * shared within the current JavaScript realm and intentionally has no close operation: its active resources
191
+ * live until the realm is unloaded.
192
+ *
193
+ * Session storage is shared more broadly than JavaScript module state. Separate same-origin realms, such as
194
+ * same-origin frames, or applications that load separate copies of this package can access the same stored
195
+ * documents while running independent local servers. Concurrently editing the same document from such realms
196
+ * is unsupported and may produce inconsistent stored state.
197
+ *
198
+ * Create one with {@link getSessionService}.
199
+ * @alpha @sealed
200
+ */
201
+ export interface SessionService extends LocalService<LocalServiceClient<SessionService>> {
152
202
  }
153
203
  /**
154
- * A {@link @fluidframework/driver-definitions#ServiceClient} connected to a specific {@link EphemeralService}.
204
+ * A {@link @fluidframework/driver-definitions#ServiceClient} connected to a specific {@link LocalService}.
205
+ *
206
+ * @typeParam TService - The type of local service this client is connected to.
155
207
  * @alpha @sealed
156
208
  */
157
- export interface EphemeralServiceClient extends ServiceClient {
209
+ export interface LocalServiceClient<out TService extends LocalService<ServiceClient> = LocalService<ServiceClient>> extends ServiceClient {
158
210
  /**
159
211
  * The service instance this client is connected to.
160
212
  */
161
- readonly service: EphemeralService;
213
+ readonly service: TService;
162
214
  }
163
215
  /**
164
216
  * A Fluid container backed by an ephemeral (in-memory) local service, implementing
@@ -170,10 +222,10 @@ export interface EphemeralServiceClient extends ServiceClient {
170
222
  *
171
223
  * @internal
172
224
  */
173
- export declare class EphemeralServiceContainer<TData> extends ServiceContainerBase<TData, EphemeralServiceOptions> implements FluidContainerWithService<TData> {
174
- readonly service: EphemeralService;
175
- static createDetached<T>(registry: DataStoreRegistry<T>, options: EphemeralServiceOptions, root: DataStoreKind<T>): Promise<EphemeralServiceContainer<T>>;
176
- static load<T>(registry: DataStoreRegistry<T>, options: EphemeralServiceOptions, id: string): Promise<EphemeralServiceContainer<T> & FluidContainerAttached<T>>;
225
+ export declare class EphemeralServiceContainer<TData> extends ServiceContainerBase<TData, LocalServiceOptions> implements FluidContainerWithService<TData> {
226
+ readonly service: LocalService;
227
+ static createDetached<T>(registry: DataStoreRegistry<T>, options: LocalServiceOptions, root: DataStoreKind<T>): Promise<EphemeralServiceContainer<T>>;
228
+ static load<T>(registry: DataStoreRegistry<T>, options: LocalServiceOptions, id: string): Promise<EphemeralServiceContainer<T> & FluidContainerAttached<T>>;
177
229
  private constructor();
178
230
  close(): void;
179
231
  protected createAttachRequest(): IRequest;
@@ -1 +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"}
1
+ {"version":3,"file":"ephemeralService.d.ts","sourceRoot":"","sources":["../src/ephemeralService.ts"],"names":[],"mappings":"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"}