tinybase 6.1.0-beta.1 → 6.1.0-beta.3

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.
Files changed (108) hide show
  1. package/@types/common/index.d.ts +4 -4
  2. package/@types/common/with-schemas/index.d.ts +4 -4
  3. package/@types/mergeable-store/index.d.ts +45 -20
  4. package/@types/mergeable-store/with-schemas/index.d.ts +49 -21
  5. package/@types/persisters/index.d.ts +1 -1
  6. package/@types/persisters/with-schemas/index.d.ts +1 -1
  7. package/index.js +19 -11
  8. package/indexes/index.js +15 -3
  9. package/indexes/with-schemas/index.js +15 -3
  10. package/mergeable-store/index.js +4 -8
  11. package/mergeable-store/with-schemas/index.js +4 -8
  12. package/min/index.js +1 -1
  13. package/min/index.js.gz +0 -0
  14. package/min/indexes/index.js +1 -1
  15. package/min/indexes/index.js.gz +0 -0
  16. package/min/indexes/with-schemas/index.js +1 -1
  17. package/min/indexes/with-schemas/index.js.gz +0 -0
  18. package/min/mergeable-store/index.js +1 -1
  19. package/min/mergeable-store/index.js.gz +0 -0
  20. package/min/mergeable-store/with-schemas/index.js +1 -1
  21. package/min/mergeable-store/with-schemas/index.js.gz +0 -0
  22. package/min/with-schemas/index.js +1 -1
  23. package/min/with-schemas/index.js.gz +0 -0
  24. package/package.json +9 -9
  25. package/readme.md +2 -2
  26. package/with-schemas/index.js +19 -11
  27. package/@types/_internal/queries/index.d.cts +0 -0
  28. package/@types/_internal/queries/with-schemas/index.d.cts +0 -22
  29. package/@types/_internal/store/index.d.cts +0 -3
  30. package/@types/_internal/store/with-schemas/index.d.cts +0 -106
  31. package/@types/_internal/ui-react/index.d.cts +0 -0
  32. package/@types/_internal/ui-react/with-schemas/index.d.cts +0 -1130
  33. package/@types/checkpoints/index.d.cts +0 -1059
  34. package/@types/checkpoints/with-schemas/index.d.cts +0 -1151
  35. package/@types/common/index.d.cts +0 -158
  36. package/@types/common/with-schemas/index.d.cts +0 -158
  37. package/@types/index.d.cts +0 -17
  38. package/@types/indexes/index.d.cts +0 -1064
  39. package/@types/indexes/with-schemas/index.d.cts +0 -1210
  40. package/@types/mergeable-store/index.d.cts +0 -1139
  41. package/@types/mergeable-store/with-schemas/index.d.cts +0 -1628
  42. package/@types/metrics/index.d.cts +0 -917
  43. package/@types/metrics/with-schemas/index.d.cts +0 -1004
  44. package/@types/persisters/index.d.cts +0 -1877
  45. package/@types/persisters/persister-automerge/index.d.cts +0 -165
  46. package/@types/persisters/persister-automerge/with-schemas/index.d.cts +0 -180
  47. package/@types/persisters/persister-browser/index.d.cts +0 -185
  48. package/@types/persisters/persister-browser/with-schemas/index.d.cts +0 -208
  49. package/@types/persisters/persister-cr-sqlite-wasm/index.d.cts +0 -159
  50. package/@types/persisters/persister-cr-sqlite-wasm/with-schemas/index.d.cts +0 -178
  51. package/@types/persisters/persister-durable-object-storage/index.d.cts +0 -122
  52. package/@types/persisters/persister-durable-object-storage/with-schemas/index.d.cts +0 -136
  53. package/@types/persisters/persister-electric-sql/index.d.cts +0 -185
  54. package/@types/persisters/persister-electric-sql/with-schemas/index.d.cts +0 -204
  55. package/@types/persisters/persister-expo-sqlite/index.d.cts +0 -186
  56. package/@types/persisters/persister-expo-sqlite/with-schemas/index.d.cts +0 -205
  57. package/@types/persisters/persister-file/index.d.cts +0 -94
  58. package/@types/persisters/persister-file/with-schemas/index.d.cts +0 -107
  59. package/@types/persisters/persister-indexed-db/index.d.cts +0 -120
  60. package/@types/persisters/persister-indexed-db/with-schemas/index.d.cts +0 -135
  61. package/@types/persisters/persister-libsql/index.d.cts +0 -158
  62. package/@types/persisters/persister-libsql/with-schemas/index.d.cts +0 -177
  63. package/@types/persisters/persister-partykit-client/index.d.cts +0 -195
  64. package/@types/persisters/persister-partykit-client/with-schemas/index.d.cts +0 -210
  65. package/@types/persisters/persister-partykit-server/index.d.cts +0 -650
  66. package/@types/persisters/persister-partykit-server/with-schemas/index.d.cts +0 -695
  67. package/@types/persisters/persister-pglite/index.d.cts +0 -177
  68. package/@types/persisters/persister-pglite/with-schemas/index.d.cts +0 -196
  69. package/@types/persisters/persister-postgres/index.d.cts +0 -166
  70. package/@types/persisters/persister-postgres/with-schemas/index.d.cts +0 -185
  71. package/@types/persisters/persister-powersync/index.d.cts +0 -174
  72. package/@types/persisters/persister-powersync/with-schemas/index.d.cts +0 -193
  73. package/@types/persisters/persister-remote/index.d.cts +0 -117
  74. package/@types/persisters/persister-remote/with-schemas/index.d.cts +0 -133
  75. package/@types/persisters/persister-sqlite-wasm/index.d.cts +0 -175
  76. package/@types/persisters/persister-sqlite-wasm/with-schemas/index.d.cts +0 -195
  77. package/@types/persisters/persister-sqlite3/index.d.cts +0 -176
  78. package/@types/persisters/persister-sqlite3/with-schemas/index.d.cts +0 -195
  79. package/@types/persisters/persister-yjs/index.d.cts +0 -161
  80. package/@types/persisters/persister-yjs/with-schemas/index.d.cts +0 -176
  81. package/@types/persisters/with-schemas/index.d.cts +0 -2054
  82. package/@types/queries/index.d.cts +0 -3695
  83. package/@types/queries/with-schemas/index.d.cts +0 -4016
  84. package/@types/relationships/index.d.cts +0 -1320
  85. package/@types/relationships/with-schemas/index.d.cts +0 -1474
  86. package/@types/store/index.d.cts +0 -7598
  87. package/@types/store/with-schemas/index.d.cts +0 -9278
  88. package/@types/synchronizers/index.d.cts +0 -485
  89. package/@types/synchronizers/synchronizer-broadcast-channel/index.d.cts +0 -121
  90. package/@types/synchronizers/synchronizer-broadcast-channel/with-schemas/index.d.cts +0 -137
  91. package/@types/synchronizers/synchronizer-local/index.d.cts +0 -95
  92. package/@types/synchronizers/synchronizer-local/with-schemas/index.d.cts +0 -114
  93. package/@types/synchronizers/synchronizer-ws-client/index.d.cts +0 -160
  94. package/@types/synchronizers/synchronizer-ws-client/with-schemas/index.d.cts +0 -179
  95. package/@types/synchronizers/synchronizer-ws-server/index.d.cts +0 -736
  96. package/@types/synchronizers/synchronizer-ws-server/with-schemas/index.d.cts +0 -765
  97. package/@types/synchronizers/synchronizer-ws-server-durable-object/index.d.cts +0 -311
  98. package/@types/synchronizers/synchronizer-ws-server-durable-object/with-schemas/index.d.cts +0 -349
  99. package/@types/synchronizers/synchronizer-ws-server-simple/index.d.cts +0 -144
  100. package/@types/synchronizers/synchronizer-ws-server-simple/with-schemas/index.d.cts +0 -144
  101. package/@types/synchronizers/with-schemas/index.d.cts +0 -503
  102. package/@types/ui-react/index.d.cts +0 -16640
  103. package/@types/ui-react/with-schemas/index.d.cts +0 -17281
  104. package/@types/ui-react-dom/index.d.cts +0 -1862
  105. package/@types/ui-react-dom/with-schemas/index.d.cts +0 -1994
  106. package/@types/ui-react-inspector/index.d.cts +0 -79
  107. package/@types/ui-react-inspector/with-schemas/index.d.cts +0 -1985
  108. package/@types/with-schemas/index.d.cts +0 -17
@@ -1,311 +0,0 @@
1
- /**
2
- * The synchronizer-ws-server-durable-object module of the TinyBase project lets
3
- * you create a server that facilitates synchronization between clients, running
4
- * as a Cloudflare Durable Object.
5
- * @see Cloudflare Durable Objects guide
6
- * @see Synchronization guide
7
- * @see Todo App v6 (collaboration) demo
8
- * @packageDocumentation
9
- * @module synchronizer-ws-server-durable-object
10
- * @since v5.4.0
11
- */
12
- import {DurableObject} from 'cloudflare:workers';
13
- import type {Id, IdAddedOrRemoved, Ids} from '../../index.d.cts';
14
- import type {Persister, Persists} from '../../persisters/index.d.cts';
15
-
16
- /**
17
- * A WsServerDurableObject is the server component (running as a Cloudflare
18
- * Durable Object) for synchronization between clients that are using
19
- * WsSynchronizer instances.
20
- *
21
- * The WsServerDurableObject is an overridden implementation of the
22
- * DurableObject class, so you can have access to its members as well as the
23
- * TinyBase-specific methods. If you are using the storage for other data, you
24
- * may want to configure a `prefix` parameter to ensure you don't accidentally
25
- * collide with TinyBase data.
26
- *
27
- * Always remember to call the `super` implementations of the methods that
28
- * TinyBase uses (the constructor, `fetch`, `webSocketMessage`, and
29
- * `webSocketClose`) if you further override them.
30
- * @category Creation
31
- * @since v5.4.0
32
- */
33
- export class WsServerDurableObject<Env = unknown> extends DurableObject<Env> {
34
- /**
35
- * The constructor is used to create the Durable Object that will synchronize
36
- * the TinyBase clients.
37
- *
38
- * For basic TinyBase synchronization and persistence, you don't need to
39
- * override this method, but if you do, ensure you call the `super`
40
- * constructor
41
- * with the two parameters.
42
- * @param ctx The DurableObjectState context.
43
- * @param env The DurableObjectState environment.
44
- * @returns A new instance of the WsServerDurableObject.
45
- * @category Creation
46
- * @since v5.4.0
47
- */
48
- constructor(ctx: DurableObjectState, env: Env);
49
-
50
- /**
51
- * The createPersister method is used to return a persister for the Durable
52
- * Object to preserve Store data when clients are not connected.
53
- *
54
- * In other words, override this method to enable persistence of the Store
55
- * data that the Durable Object is synchronizing between clients.
56
- *
57
- * This should almost certainly return a DurableObjectStoragePersister,
58
- * created with the createDurableObjectStoragePersister function. This will
59
- * ensure that the Store is serialized to the Durable Object KV-based storage.
60
- *
61
- * Returning `undefined` from this method will disable persistence.
62
- * @example
63
- * This example enables Durable Object persistence by creating a Persister
64
- * object within the createPersister method of a WsServerDurableObject.
65
- *
66
- * ```js yolo
67
- * import {createMergeableStore} from 'tinybase';
68
- * import {createDurableObjectStoragePersister} from 'tinybase/persisters/persister-durable-object-storage';
69
- * import {WsServerDurableObject} from 'tinybase/synchronizers/synchronizer-ws-server-durable-object';
70
- *
71
- * export class MyDurableObject extends WsServerDurableObject {
72
- * createPersister() {
73
- * const store = createMergeableStore();
74
- * const persister = createDurableObjectStoragePersister(
75
- * store,
76
- * this.ctx.storage,
77
- * );
78
- * return persister;
79
- * }
80
- * }
81
- * ```
82
- * @returns A new instance of a DurableObjectStoragePersister (or a promise to
83
- * resolve one) that will be used to persist data to the Durable Object.
84
- * Return `undefined` if that functionality is not required.
85
- * @category Creation
86
- * @since v5.4.0
87
- */
88
- createPersister():
89
- | Persister<Persists.MergeableStoreOnly>
90
- | Promise<Persister<Persists.MergeableStoreOnly>>
91
- | undefined;
92
-
93
- /**
94
- * The getPathId method is used to get the Id of the path that is being
95
- * served.
96
- *
97
- * This is useful for when you want to know which path the current Durable
98
- * Object is serving - for the purposes of logging, for example.
99
- * @returns The Id of the path being served by the Durable Object.
100
- * @example
101
- * This example logs the path being served by the Durable Object every time a
102
- * synchronization method is handled.
103
- *
104
- * ```js yolo
105
- * import {WsServerDurableObject} from 'tinybase/synchronizers/synchronizer-ws-server-durable-object';
106
- *
107
- * export class MyDurableObject extends WsServerDurableObject {
108
- * onMessage() {
109
- * console.info('Message received on path: ', this.getPathId());
110
- * }
111
- * }
112
- * ```
113
- * @category Getter
114
- * @since v5.4.0
115
- */
116
- getPathId(): Id;
117
-
118
- /**
119
- * The getClientIds method is used to access a list of all the connected
120
- * clients on the path.
121
- *
122
- * Note that if you call this method from within the onClientId method as a
123
- * client is getting removed, it will still be returned in the list of client
124
- * Ids.
125
- * @returns The Ids of the clients being served by the Durable Object.
126
- * @example
127
- * This example logs the list of clients being served by the Durable Object
128
- * every time a synchronization method is handled.
129
- *
130
- * ```js yolo
131
- * import {WsServerDurableObject} from 'tinybase/synchronizers/synchronizer-ws-server-durable-object';
132
- *
133
- * export class MyDurableObject extends WsServerDurableObject {
134
- * onMessage() {
135
- * console.info('Clients on path: ', this.getClientIds());
136
- * }
137
- * }
138
- * ```
139
- * @category Getter
140
- * @since v5.4.0
141
- */
142
- getClientIds(): Ids;
143
-
144
- /**
145
- * The onPathId method is called when the first client connects to, or the
146
- * last client disconnects from, the server with a given path Id.
147
- *
148
- * This method is called with the path Id and an IdAddedOrRemoved flag
149
- * indicating whether it this is being triggered by the first client joining
150
- * (`1`) or the last client leaving (`-1`).
151
- * @param pathId The Id of the path being served by the Durable Object.
152
- * @param addedOrRemoved Whether the path had the first joiner, or the last
153
- * leaver.
154
- * @example
155
- * This example logs the Id of the path being served by the Durable Object
156
- * when the first client joins (the path Id is 'added'), and when the last
157
- * client leaves (the path Id is 'removed').
158
- *
159
- * ```js yolo
160
- * import {WsServerDurableObject} from 'tinybase/synchronizers/synchronizer-ws-server-durable-object';
161
- *
162
- * export class MyDurableObject extends WsServerDurableObject {
163
- * onPathId(pathId, addedOrRemoved) {
164
- * console.info(
165
- * (addedOrRemoved == 1 ? 'Added' : 'Removed') + ` path ${pathId}`,
166
- * );
167
- * }
168
- * }
169
- * ```
170
- * @category Event
171
- * @since v5.4.0
172
- */
173
- onPathId(pathId: Id, addedOrRemoved: IdAddedOrRemoved): void;
174
-
175
- /**
176
- * The onClientId method is called when a client connects to, or disconnects
177
- * from, the server.
178
- *
179
- * This method is called with the path Id, the client Id, and an
180
- * IdAddedOrRemoved flag indicating whether it this is being triggered by
181
- * the client joining (`1`) or the client leaving (`-1`).
182
- *
183
- * Note that if you call the getClientIds method from within this method as a
184
- * client is getting removed, it will still be returned in the list of client
185
- * Ids.
186
- * @param pathId The Id of the path being served by the Durable Object.
187
- * @param clientId The Id of the client joining or leaving.
188
- * @param addedOrRemoved Whether the client is joining or leaving.
189
- * @example
190
- * This example logs every client that joins (the client Id is 'added') or
191
- * leaves (the client Id is 'removed') on the path being served by the Durable
192
- * Object.
193
- *
194
- * ```js yolo
195
- * import {WsServerDurableObject} from 'tinybase/synchronizers/synchronizer-ws-server-durable-object';
196
- *
197
- * export class MyDurableObject extends WsServerDurableObject {
198
- * onClientId(pathId, clientId, addedOrRemoved) {
199
- * console.info(
200
- * (addedOrRemoved == 1 ? 'Added' : 'Removed') +
201
- * ` client ${clientId} on path ${pathId}`,
202
- * );
203
- * }
204
- * }
205
- * ```
206
- * @category Event
207
- * @since v5.4.0
208
- */
209
- onClientId(pathId: Id, clientId: Id, addedOrRemoved: IdAddedOrRemoved): void;
210
-
211
- /**
212
- * The onMessage method is called when a message is handled by the server.
213
- *
214
- * This is useful if you want to debug the synchronization process, though be
215
- * aware that this method is called very frequently. It is called with the Id
216
- * of the client the message came _from_, the the Id of the client the message
217
- * is to be forwarded _to_, and the remainder of the message itself.
218
- *
219
- * Since this method is called often, it should be performant. The path Id is
220
- * not passed as an argument, since it has a small cost to provide by default.
221
- * You can use the getPathId method yourself if that information is needed.
222
- * @param fromClientId The Id of the client that send the message.
223
- * @param toClientId The Id of the client to receive the message (or empty for
224
- * a broadcast).
225
- * @param remainder The remainder of the body of the message.
226
- * @example
227
- * This example logs every message routed by the Durable Object between
228
- * clients.
229
- *
230
- * ```js yolo
231
- * import {WsServerDurableObject} from 'tinybase/synchronizers/synchronizer-ws-server-durable-object';
232
- *
233
- * export class MyDurableObject extends WsServerDurableObject {
234
- * onMessage(fromClientId, toClientId, remainder) {
235
- * console.info(
236
- * `Message from '${fromClientId}' to '${toClientId}': ${remainder}`,
237
- * );
238
- * }
239
- * }
240
- * ```
241
- * @category Event
242
- * @since v5.4.0
243
- */
244
- onMessage(fromClientId: Id, toClientId: Id, remainder: string): void;
245
- }
246
-
247
- /**
248
- * The getWsServerDurableObjectFetch function returns a convenient handler for a
249
- * Cloudflare worker to route requests to the fetch handler of a
250
- * WsServerDurableObject for the given namespace.
251
- *
252
- * The implementation of the function that this returns requires the request to
253
- * be a WebSocket 'Upgrade' request, and for the client to have provided a
254
- * `sec-websocket-key` header that the server can use as a unique key for the
255
- * client.
256
- *
257
- * It then takes the path of the HTTP request and routes the upgrade request to
258
- * a Durable Object (in the given namespace) for that path. From then on, the
259
- * Durable Object handles all the WebSocket communication.
260
- *
261
- * Note that you'll need to have a Wrangler configuration that connects your
262
- * Durable Object class to the namespace. In other words, you'll have something
263
- * like this in your `wrangler.toml` file.
264
- *
265
- * ```toml
266
- * [[durable_objects.bindings]]
267
- * name = "MyDurableObjects"
268
- * class_name = "MyDurableObject"
269
- * ```
270
- *
271
- * Note that it is not required to use this handler to route TinyBase client
272
- * requests in your Cloudflare app. If you have your own custom routing logic,
273
- * path scheme, or authentication, for example, you can easily implement that in
274
- * the worker's fetch method yourself. See the [Durable Objects
275
- * documentation](https://developers.cloudflare.com/durable-objects/best-practices/create-durable-object-stubs-and-send-requests/#invoking-the-fetch-handler)
276
- * for examples.
277
- *
278
- * You can also pass a newly created request to the Durable Object's `fetch`
279
- * method. For example, you can overwrite the 'path' that the Durable Object
280
- * thinks it is serving, perhaps to inject a unique authenticated user Id that
281
- * wasn't actually provided by the client WebSocket.
282
- * @param namespace A string for the namespace of the Durable Objects that you
283
- * want this worker to route requests to.
284
- * @returns A fetch handler that routes WebSocket upgrade requests to a Durable
285
- * Object.
286
- * @example
287
- * This example sets up default routing of the WebSocket upgrade request to a
288
- * Durable Object in the `MyDurableObjects` namespace. This would require the
289
- * `wrangler.toml` configuration shown above.
290
- *
291
- * ```js yolo
292
- * import {
293
- * WsServerDurableObject,
294
- * getWsServerDurableObjectFetch,
295
- * } from 'tinybase/synchronizers/synchronizer-ws-server-durable-object';
296
- *
297
- * export class MyDurableObject extends WsServerDurableObject {}
298
- *
299
- * export default {fetch: getWsServerDurableObjectFetch('MyDurableObjects')};
300
- * ```
301
- * @category Creation
302
- * @since v5.4.0
303
- */
304
- export function getWsServerDurableObjectFetch<Namespace extends string>(
305
- namespace: Namespace,
306
- ): (
307
- request: Request,
308
- env: {
309
- [namespace in Namespace]: DurableObjectNamespace<WsServerDurableObject>;
310
- },
311
- ) => Response;
@@ -1,349 +0,0 @@
1
- /**
2
- * The synchronizer-ws-server-durable-object module of the TinyBase project lets
3
- * you create a server that facilitates synchronization between clients, running
4
- * as a Cloudflare Durable Object.
5
- * @see Cloudflare Durable Objects guide
6
- * @see Synchronization guide
7
- * @see Todo App v6 (collaboration) demo
8
- * @packageDocumentation
9
- * @module synchronizer-ws-server-durable-object
10
- * @since v5.4.0
11
- */
12
- import {DurableObject} from 'cloudflare:workers';
13
- import type {
14
- Persister,
15
- Persists,
16
- } from '../../../persisters/with-schemas/index.d.cts';
17
- import type {
18
- Id,
19
- IdAddedOrRemoved,
20
- Ids,
21
- OptionalSchemas,
22
- } from '../../../with-schemas/index.d.cts';
23
-
24
- /**
25
- * A WsServerDurableObject is the server component (running as a Cloudflare
26
- * Durable Object) for synchronization between clients that are using
27
- * WsSynchronizer instances.
28
- *
29
- * The WsServerDurableObject is an overridden implementation of the
30
- * DurableObject class, so you can have access to its members as well as the
31
- * TinyBase-specific methods. If you are using the storage for other data, you
32
- * may want to configure a `prefix` parameter to ensure you don't accidentally
33
- * collide with TinyBase data.
34
- *
35
- * Always remember to call the `super` implementations of the methods that
36
- * TinyBase uses (the constructor, `fetch`, `webSocketMessage`, and
37
- * `webSocketClose`) if you further override them.
38
- * @category Creation
39
- * @since v5.4.0
40
- */
41
- export class WsServerDurableObject<
42
- Schemas extends OptionalSchemas,
43
- Env = unknown,
44
- > extends DurableObject<Env> {
45
- /**
46
- * The constructor is used to create the Durable Object that will synchronize
47
- * the TinyBase clients.
48
- *
49
- * For basic TinyBase synchronization and persistence, you don't need to
50
- * override this method, but if you do, ensure you call the `super`
51
- * constructor
52
- * with the two parameters.
53
- * @param ctx The DurableObjectState context.
54
- * @param env The DurableObjectState environment.
55
- * @returns A new instance of the WsServerDurableObject.
56
- * @category Creation
57
- * @since v5.4.0
58
- */
59
- constructor(ctx: DurableObjectState, env: Env);
60
-
61
- /**
62
- * The createPersister method is used to return a persister for the Durable
63
- * Object to preserve Store data when clients are not connected.
64
- *
65
- * This has schema-based typing. The following is a simplified representation:
66
- *
67
- * ```ts override
68
- * createPersister():
69
- * | Persister<Persists.MergeableStoreOnly>
70
- * | Promise<Persister<Persists.MergeableStoreOnly>>
71
- * | undefined;
72
- * ```
73
- *
74
- * In other words, override this method to enable persistence of the Store
75
- * data that the Durable Object is synchronizing between clients.
76
- *
77
- * This should almost certainly return a DurableObjectStoragePersister,
78
- * created with the createDurableObjectStoragePersister function. This will
79
- * ensure that the Store is serialized to the Durable Object KV-based storage.
80
- *
81
- * Returning `undefined` from this method will disable persistence.
82
- * @example
83
- * This example enables Durable Object persistence by creating a Persister
84
- * object within the createPersister method of a WsServerDurableObject.
85
- *
86
- * ```js yolo
87
- * import {createMergeableStore} from 'tinybase';
88
- * import {createDurableObjectStoragePersister} from 'tinybase/persisters/persister-durable-object-storage';
89
- * import {WsServerDurableObject} from 'tinybase/synchronizers/synchronizer-ws-server-durable-object';
90
- *
91
- * export class MyDurableObject extends WsServerDurableObject {
92
- * createPersister() {
93
- * const store = createMergeableStore();
94
- * const persister = createDurableObjectStoragePersister(
95
- * store,
96
- * this.ctx.storage,
97
- * );
98
- * return persister;
99
- * }
100
- * }
101
- * ```
102
- * @returns A new instance of a DurableObjectStoragePersister (or a promise to
103
- * resolve one) that will be used to persist data to the Durable Object.
104
- * Return `undefined` if that functionality is not required.
105
- * @category Creation
106
- * @since v5.4.0
107
- */
108
- createPersister():
109
- | Persister<Schemas, Persists.MergeableStoreOnly>
110
- | Promise<Persister<Schemas, Persists.MergeableStoreOnly>>
111
- | undefined;
112
-
113
- /**
114
- * The getPathId method is used to get the Id of the path that is being
115
- * served.
116
- *
117
- * This is useful for when you want to know which path the current Durable
118
- * Object is serving - for the purposes of logging, for example.
119
- * @returns The Id of the path being served by the Durable Object.
120
- * @example
121
- * This example logs the path being served by the Durable Object every time a
122
- * synchronization method is handled.
123
- *
124
- * ```js yolo
125
- * import {WsServerDurableObject} from 'tinybase/synchronizers/synchronizer-ws-server-durable-object';
126
- *
127
- * export class MyDurableObject extends WsServerDurableObject {
128
- * onMessage() {
129
- * console.info('Message received on path: ', this.getPathId());
130
- * }
131
- * }
132
- * ```
133
- * @category Getter
134
- * @since v5.4.0
135
- */
136
- getPathId(): Id;
137
-
138
- /**
139
- * The getClientIds method is used to access a list of all the connected
140
- * clients on the path.
141
- *
142
- * Note that if you call this method from within the onClientId method as a
143
- * client is getting removed, it will still be returned in the list of client
144
- * Ids.
145
- * @returns The Ids of the clients being served by the Durable Object.
146
- * @example
147
- * This example logs the list of clients being served by the Durable Object
148
- * every time a synchronization method is handled.
149
- *
150
- * ```js yolo
151
- * import {WsServerDurableObject} from 'tinybase/synchronizers/synchronizer-ws-server-durable-object';
152
- *
153
- * export class MyDurableObject extends WsServerDurableObject {
154
- * onMessage() {
155
- * console.info('Clients on path: ', this.getClientIds());
156
- * }
157
- * }
158
- * ```
159
- * @category Getter
160
- * @since v5.4.0
161
- */
162
- getClientIds(): Ids;
163
-
164
- /**
165
- * The onPathId method is called when the first client connects to, or the
166
- * last client disconnects from, the server with a given path Id.
167
- *
168
- * This method is called with the path Id and an IdAddedOrRemoved flag
169
- * indicating whether it this is being triggered by the first client joining
170
- * (`1`) or the last client leaving (`-1`).
171
- * @param pathId The Id of the path being served by the Durable Object.
172
- * @param addedOrRemoved Whether the path had the first joiner, or the last
173
- * leaver.
174
- * @example
175
- * This example logs the Id of the path being served by the Durable Object
176
- * when the first client joins (the path Id is 'added'), and when the last
177
- * client leaves (the path Id is 'removed').
178
- *
179
- * ```js yolo
180
- * import {WsServerDurableObject} from 'tinybase/synchronizers/synchronizer-ws-server-durable-object';
181
- *
182
- * export class MyDurableObject extends WsServerDurableObject {
183
- * onPathId(pathId, addedOrRemoved) {
184
- * console.info(
185
- * (addedOrRemoved == 1 ? 'Added' : 'Removed') + ` path ${pathId}`,
186
- * );
187
- * }
188
- * }
189
- * ```
190
- * @category Event
191
- * @since v5.4.0
192
- */
193
- onPathId(pathId: Id, addedOrRemoved: IdAddedOrRemoved): void;
194
-
195
- /**
196
- * The onClientId method is called when a client connects to, or disconnects
197
- * from, the server.
198
- *
199
- * This method is called with the path Id, the client Id, and an
200
- * IdAddedOrRemoved flag indicating whether it this is being triggered by
201
- * the client joining (`1`) or the client leaving (`-1`).
202
- *
203
- * Note that if you call the getClientIds method from within this method as a
204
- * client is getting removed, it will still be returned in the list of client
205
- * Ids.
206
- * @param pathId The Id of the path being served by the Durable Object.
207
- * @param clientId The Id of the client joining or leaving.
208
- * @param addedOrRemoved Whether the client is joining or leaving.
209
- * @example
210
- * This example logs every client that joins (the client Id is 'added') or
211
- * leaves (the client Id is 'removed') on the path being served by the Durable
212
- * Object.
213
- *
214
- * ```js yolo
215
- * import {WsServerDurableObject} from 'tinybase/synchronizers/synchronizer-ws-server-durable-object';
216
- *
217
- * export class MyDurableObject extends WsServerDurableObject {
218
- * onClientId(pathId, clientId, addedOrRemoved) {
219
- * console.info(
220
- * (addedOrRemoved == 1 ? 'Added' : 'Removed') +
221
- * ` client ${clientId} on path ${pathId}`,
222
- * );
223
- * }
224
- * }
225
- * ```
226
- * @category Event
227
- * @since v5.4.0
228
- */
229
- onClientId(pathId: Id, clientId: Id, addedOrRemoved: IdAddedOrRemoved): void;
230
-
231
- /**
232
- * The onMessage method is called when a message is handled by the server.
233
- *
234
- * This is useful if you want to debug the synchronization process, though be
235
- * aware that this method is called very frequently. It is called with the Id
236
- * of the client the message came _from_, the the Id of the client the message
237
- * is to be forwarded _to_, and the remainder of the message itself.
238
- *
239
- * Since this method is called often, it should be performant. The path Id is
240
- * not passed as an argument, since it has a small cost to provide by default.
241
- * You can use the getPathId method yourself if that information is needed.
242
- * @param fromClientId The Id of the client that send the message.
243
- * @param toClientId The Id of the client to receive the message (or empty for
244
- * a broadcast).
245
- * @param remainder The remainder of the body of the message.
246
- * @example
247
- * This example logs every message routed by the Durable Object between
248
- * clients.
249
- *
250
- * ```js yolo
251
- * import {WsServerDurableObject} from 'tinybase/synchronizers/synchronizer-ws-server-durable-object';
252
- *
253
- * export class MyDurableObject extends WsServerDurableObject {
254
- * onMessage(fromClientId, toClientId, remainder) {
255
- * console.info(
256
- * `Message from '${fromClientId}' to '${toClientId}': ${remainder}`,
257
- * );
258
- * }
259
- * }
260
- * ```
261
- * @category Event
262
- * @since v5.4.0
263
- */
264
- onMessage(fromClientId: Id, toClientId: Id, remainder: string): void;
265
- }
266
-
267
- /**
268
- * The getWsServerDurableObjectFetch function returns a convenient handler for a
269
- * Cloudflare worker to route requests to the fetch handler of a
270
- * WsServerDurableObject for the given namespace.
271
- *
272
- * This has schema-based typing. The following is a simplified representation:
273
- *
274
- * ```ts override
275
- * getWsServerDurableObjectFetch<Namespace extends string>(
276
- * namespace: Namespace,
277
- * ): (
278
- * request: Request,
279
- * env: {
280
- * [namespace in Namespace]: DurableObjectNamespace<WsServerDurableObject>;
281
- * },
282
- * ) => Response;
283
- * ```
284
- *
285
- * The implementation of the function that this returns requires the request to
286
- * be a WebSocket 'Upgrade' request, and for the client to have provided a
287
- * `sec-websocket-key` header that the server can use as a unique key for the
288
- * client.
289
- *
290
- * It then takes the path of the HTTP request and routes the upgrade request to
291
- * a Durable Object (in the given namespace) for that path. From then on, the
292
- * Durable Object handles all the WebSocket communication.
293
- *
294
- * Note that you'll need to have a Wrangler configuration that connects your
295
- * Durable Object class to the namespace. In other words, you'll have something
296
- * like this in your `wrangler.toml` file.
297
- *
298
- * ```toml
299
- * [[durable_objects.bindings]]
300
- * name = "MyDurableObjects"
301
- * class_name = "MyDurableObject"
302
- * ```
303
- *
304
- * Note that it is not required to use this handler to route TinyBase client
305
- * requests in your Cloudflare app. If you have your own custom routing logic,
306
- * path scheme, or authentication, for example, you can easily implement that in
307
- * the worker's fetch method yourself. See the [Durable Objects
308
- * documentation](https://developers.cloudflare.com/durable-objects/best-practices/create-durable-object-stubs-and-send-requests/#invoking-the-fetch-handler)
309
- * for examples.
310
- *
311
- * You can also pass a newly created request to the Durable Object's `fetch`
312
- * method. For example, you can overwrite the 'path' that the Durable Object
313
- * thinks it is serving, perhaps to inject a unique authenticated user Id that
314
- * wasn't actually provided by the client WebSocket.
315
- * @param namespace A string for the namespace of the Durable Objects that you
316
- * want this worker to route requests to.
317
- * @returns A fetch handler that routes WebSocket upgrade requests to a Durable
318
- * Object.
319
- * @example
320
- * This example sets up default routing of the WebSocket upgrade request to a
321
- * Durable Object in the `MyDurableObjects` namespace. This would require the
322
- * `wrangler.toml` configuration shown above.
323
- *
324
- * ```js yolo
325
- * import {
326
- * WsServerDurableObject,
327
- * getWsServerDurableObjectFetch,
328
- * } from 'tinybase/synchronizers/synchronizer-ws-server-durable-object';
329
- *
330
- * export class MyDurableObject extends WsServerDurableObject {}
331
- *
332
- * export default {fetch: getWsServerDurableObjectFetch('MyDurableObjects')};
333
- * ```
334
- * @category Creation
335
- * @since v5.4.0
336
- */
337
- export function getWsServerDurableObjectFetch<
338
- Schemas extends OptionalSchemas,
339
- Namespace extends string,
340
- >(
341
- namespace: Namespace,
342
- ): (
343
- request: Request,
344
- env: {
345
- [namespace in Namespace]: DurableObjectNamespace<
346
- WsServerDurableObject<Schemas>
347
- >;
348
- },
349
- ) => Response;