tinybase 4.3.11 → 4.3.13

package/lib/types/persisters/persister-indexed-db.d.ts

@@ -40,11 +40,10 @@ import {Store} from '../store';
  * browser's IndexedDB storage.
  *
  * ```js
- * const store =
- *   createStore()
- *     .setTable('pets', {fido: {species: 'dog'}})
- *     .setTable('species', {dog: {price: 5}})
- *     .setValues({open: true});
+ * const store = createStore()
+ *   .setTable('pets', {fido: {species: 'dog'}})
+ *   .setTable('species', {dog: {price: 5}})
+ *   .setValues({open: true});
  * const persister = createIndexedDbPersister(store, 'petStore');
  *
  * await persister.save();

package/lib/types/persisters/persister-partykit-client.d.ts

@@ -39,7 +39,7 @@ import {Store} from '../store';
  * to the TinyBasePartyKitServerConfig on the server side.
  *
  * ```js
- * const partyKitPersisterConfig: PartyKitPersisterConfig = {
+ * const partyKitPersisterConfig = {
  *   storeProtocol: 'http',
  *   storePath: '/my_tinybase',
  * };
@@ -57,9 +57,18 @@ export type PartyKitPersisterConfig = {
   /**
    * The path used to set and get the whole Store over HTTP(S) on the server.
    * This must match the storePath property of the TinyBasePartyKitServerConfig
-   * object on the server. Both default to '/store'.
+   * object used on the server. Both default to '/store'.
    */
   storePath?: string;
+  /**
+   * The prefix at the beginning of the web socket messages sent between the
+   * client and the server when synchronizing the Store. Use this to make sure
+   * they do not collide with any other message syntax that your room is using.
+   * This must match the messagePrefix property of the
+   * TinyBasePartyKitServerConfig object used on the server. Both default to an
+   * empty string.
+   */
+  messagePrefix?: string;
 };
 
 /**
@@ -103,12 +112,14 @@ export type PartyKitPersisterConfig = {
  * browser's IndexedDB storage.
  *
  * ```js yolo
- * const store =
- *   createStore()
- *     .setTable('pets', {fido: {species: 'dog'}})
- *     .setTable('species', {dog: {price: 5}})
- *     .setValues({open: true});
- * const partySocket = new PartySocket({host: PARTYKIT_HOST, room: 'my_room'});
+ * const store = createStore()
+ *   .setTable('pets', {fido: {species: 'dog'}})
+ *   .setTable('species', {dog: {price: 5}})
+ *   .setValues({open: true});
+ * const partySocket = new PartySocket({
+ *   host: PARTYKIT_HOST,
+ *   room: 'my_room',
+ * });
  * const persister = createPartyKitPersister(store, partySocket);
  * await persister.startAutoLoad();
  * await persister.startAutoSave();

package/lib/types/persisters/persister-partykit-server.d.ts

@@ -18,7 +18,9 @@
  * @since 4.3.0
  */
 
+import {Cell, CellOrUndefined, Value, ValueOrUndefined} from '../store';
 import {Connection, Party, Request, Server} from 'partykit/server';
+import {Id} from '../common';
 
 /**
  * The TinyBasePartyKitServerConfig type describes the configuration of a
@@ -38,13 +40,13 @@ import {Connection, Party, Request, Server} from 'partykit/server';
  * 'tinybase_' in case you are worried about colliding with other data stored
  * in the room.
  *
- * ```js yolo
- * export default class extends TinyBasePartyServer {
- *   readonly config: TinyBasePartyKitServerConfig = {
+ * ```js
+ * class MyServer extends TinyBasePartyKitServer {
+ *   readonly config = {
  *     storePath: '/my_tinybase',
  *     storagePrefix: 'tinybase_',
  *   };
- * };
+ * }
  * ```
  * @category Configuration
  * @since v4.3.9
@@ -56,6 +58,14 @@ export type TinyBasePartyKitServerConfig = {
    * on the client. Both default to '/store'.
    */
   storePath?: string;
+  /**
+   * The prefix at the beginning of the web socket messages between the client
+   * and the server when synchronizing the Store. Use this to make sure they do
+   * not collide with any other message syntax that your room is using. This
+   * must match the messagePrefix property of the PartyKitPersisterConfig object
+   * used on the client. Both default to an empty string.
+   */
+  messagePrefix?: string;
   /**
    * The prefix used before all the keys in the server's durable storage. Use
    * this in case you are worried about the Store data colliding with other data
@@ -98,7 +108,7 @@ export type TinyBasePartyKitServerConfig = {
  * ```js
  * // This is your PartyKit server entry point.
  *
- * export default class extends TinyBasePartyServer {
+ * class MyServer extends TinyBasePartyKitServer {
  *   constructor(party) {
  *     super(party);
  *     // custom constructor code
@@ -109,8 +119,8 @@ export type TinyBasePartyKitServerConfig = {
  *     console.log('Server started');
  *   }
  *
- *   async onMessage(message, client) {
- *     await super.onMessage(message, client);
+ *   async onMessage(message, connection) {
+ *     await super.onMessage(message, connection);
  *     // custom onMessage code
  *   }
  *
@@ -124,6 +134,8 @@ export type TinyBasePartyKitServerConfig = {
  * See the [PartyKit server API
  * documentation](https://docs.partykit.io/reference/partyserver-api/) for
  * more details.
+ * @category Creation
+ * @since v4.3.0
  */
 export class TinyBasePartyKitServer implements Server {
   constructor(party: Party);
@@ -132,6 +144,8 @@ export class TinyBasePartyKitServer implements Server {
    * object of the TinyBasePartyKitServerConfig type.
    *
    * See the documentation for that type for more details.
+   * @category Configuration
+   * @since v4.3.9
    */
   readonly config: TinyBasePartyKitServerConfig;
   /**
@@ -143,7 +157,7 @@ export class TinyBasePartyKitServer implements Server {
    * synchronization stays supported:
    *
    * ```js
-   * export default class extends TinyBasePartyServer {
+   * class MyServer extends TinyBasePartyKitServer {
    *   async onRequest(request) {
    *     // custom onRequest code, else:
    *     return await super.onRequest(request);
@@ -154,6 +168,8 @@ export class TinyBasePartyKitServer implements Server {
    * See the [PartyKit server API
    * documentation](https://docs.partykit.io/reference/partyserver-api/) for
    * more details.
+   * @category Connection
+   * @since v4.3.0
    */
   onRequest(request: Request): Promise<Response>;
   /**
@@ -165,9 +181,9 @@ export class TinyBasePartyKitServer implements Server {
    * synchronization stays supported:
    *
    * ```js
-   * export default class extends TinyBasePartyServer {
-   *   async onMessage(message, client) {
-   *     await super.onMessage(message, client);
+   * class MyServer extends TinyBasePartyKitServer {
+   *   async onMessage(message, connection) {
+   *     await super.onMessage(message, connection);
    *     // custom onMessage code
    *   }
    * }
@@ -176,6 +192,328 @@ export class TinyBasePartyKitServer implements Server {
    * See the [PartyKit server API
    * documentation](https://docs.partykit.io/reference/partyserver-api/) for
    * more details.
+   * @category Connection
+   * @since v4.3.0
+   */
+  onMessage(message: string, connection: Connection): Promise<void>;
+  /**
+   * The canSetTable method lets you allow or disallow any changes to a Table
+   * stored on the server, as sent from a client.
+   *
+   * This is one of the functions use to sanitize the data that is being sent
+   * from a client. Perhaps you might want to make sure the server-stored data
+   * adheres to a particular schema, or you might want to make certain data
+   * read-only. Remember that you cannot trust the client to only send data that
+   * the server considers valid or safe.
+   *
+   * This method is passed the Table Id that the client is trying to change. The
+   * `initialSave` parameter distinguishes between the first bulk save of the
+   * Store to the PartyKit room over HTTP (`true`), and subsequent incremental
+   * updates over a web sockets (`false`).
+   *
+   * The `requestOrConnection` parameter will either be the HTTP(S) request or
+   * the web socket connection, in those two cases respectively. You can, for
+   * instance, use this to distinguish between different users.
+   *
+   * Since v4.3.13, the final parameter is the Cell previously stored on the
+   * server, if any. Use this to distinguish between the addition of a new Cell
+   * (in which case it will be undefined) and the updating of an existing one.
+   *
+   * Return `false` from this method to disallow changes to this Table on the
+   * server, or `true` to allow them (subject to subsequent canSetRow method,
+   * canDelRow method, canSetCell method, and canSetCell method checks). The
+   * default implementation returns `true` to allow all changes.
+   * @example
+   * The following implementation will strip out any attempts by the client to
+   * update any 'user' tabular data after the initial save:
+   *
+   * ```js
+   * class MyServer extends TinyBasePartyKitServer {
+   *   canSetTable(tableId, initialSave) {
+   *     return initialSave || tableId != 'user';
+   *   }
+   * }
+   * ```
+   * @category Sanitization
+   * @since v4.3.12
+   */
+  canSetTable(
+    tableId: Id,
+    initialSave: boolean,
+    requestOrConnection: Request | Connection,
+  ): boolean;
+  /**
+   * The canDelTable method lets you allow or disallow deletions of a Table
+   * stored on the server, as sent from a client.
+   *
+   * This is one of the functions use to sanitize the data that is being sent
+   * from a client. Perhaps you might want to make sure the server-stored data
+   * adheres to a particular schema, or you might want to make certain data
+   * read-only. Remember that you cannot trust the client to only send data that
+   * the server considers valid or safe.
+   *
+   * This method is passed the Table Id that the client is trying to delete. The
+   * `connection` parameter will be the web socket connection of that client.
+   * You can, for instance, use this to distinguish between different users.
+   *
+   * Return `false` from this method to disallow this Table from being deleted
+   * on the server, or `true` to allow it. The default implementation returns
+   * `true` to allow deletion.
+   * @example
+   * The following implementation will strip out any attempts by the client to
+   * delete the 'user' Table:
+   *
+   * ```js
+   * class MyServer extends TinyBasePartyKitServer {
+   *   canDelTable(tableId) {
+   *     return tableId != 'user';
+   *   }
+   * }
+   * ```
+   * @category Sanitization
+   * @since v4.3.12
+   */
+  canDelTable(tableId: Id, connection: Connection): boolean;
+  /**
+   * The canSetRow method lets you allow or disallow any changes to a Row stored
+   * on the server, as sent from a client.
+   *
+   * This is one of the functions use to sanitize the data that is being sent
+   * from a client. Perhaps you might want to make sure the server-stored data
+   * adheres to a particular schema, or you might want to make certain data
+   * read-only. Remember that you cannot trust the client to only send data that
+   * the server considers valid or safe.
+   *
+   * This method is passed the Table Id and Row Id that the client is trying to
+   * change. The `initialSave` parameter distinguishes between the first bulk
+   * save of the Store to the PartyKit room over HTTP (`true`), and subsequent
+   * incremental updates over a web sockets (`false`).
+   *
+   * The final `requestOrConnection` parameter will either be the HTTP(S)
+   * request or the web socket connection, in those two cases respectively. You
+   * can, for instance, use this to distinguish between different users.
+   *
+   * Return `false` from this method to disallow changes to this Row on the
+   * server, or `true` to allow them (subject to subsequent canSetCell method
+   * and canSetCell method checks). The default implementation returns `true` to
+   * allow all changes.
+   * @example
+   * The following implementation will strip out any attempts by the client to
+   * update the 'me' Row of the 'user' Table after the initial save:
+   *
+   * ```js
+   * class MyServer extends TinyBasePartyKitServer {
+   *   canSetRow(tableId, rowId, initialSave) {
+   *     return initialSave || tableId != 'user' || rowId != 'me';
+   *   }
+   * }
+   * ```
+   * @category Sanitization
+   * @since v4.3.12
+   */
+  canSetRow(
+    tableId: Id,
+    rowId: Id,
+    initialSave: boolean,
+    requestOrConnection: Request | Connection,
+  ): boolean;
+  /**
+   * The canDelRow method lets you allow or disallow deletions of a Row stored
+   * on the server, as sent from a client.
+   *
+   * This is one of the functions use to sanitize the data that is being sent
+   * from a client. Perhaps you might want to make sure the server-stored data
+   * adheres to a particular schema, or you might want to make certain data
+   * read-only. Remember that you cannot trust the client to only send data that
+   * the server considers valid or safe.
+   *
+   * This method is passed the Table Id and Row Id that the client is trying to
+   * delete. The `connection` parameter will be the web socket connection of
+   * that client. You can, for instance, use this to distinguish between
+   * different users.
+   *
+   * Return `false` from this method to disallow this Row from being deleted
+   * on the server, or `true` to allow it. The default implementation returns
+   * `true` to allow deletion.
+   * @example
+   * The following implementation will strip out any attempts by the client to
+   * delete the 'me' Row of the 'user' Table:
+   *
+   * ```js
+   * class MyServer extends TinyBasePartyKitServer {
+   *   canDelRow(tableId, rowId) {
+   *     return tableId != 'user' || rowId != 'me';
+   *   }
+   * }
+   * ```
+   * @category Sanitization
+   * @since v4.3.12
+   */
+  canDelRow(tableId: Id, rowId: Id, connection: Connection): boolean;
+  /**
+   * The canSetCell method lets you allow or disallow any changes to a Cell
+   * stored on the server, as sent from a client.
+   *
+   * This is one of the functions use to sanitize the data that is being sent
+   * from a client. Perhaps you might want to make sure the server-stored data
+   * adheres to a particular schema, or you might want to make certain data
+   * read-only. Remember that you cannot trust the client to only send data that
+   * the server considers valid or safe.
+   *
+   * This method is passed the Table Id, Row Id, and Cell Id that the client is
+   * trying to change - as well as the Cell value itself. The `initialSave`
+   * parameter distinguishes between the first bulk save of the Store to the
+   * PartyKit room over HTTP (`true`), and subsequent incremental updates over a
+   * web sockets (`false`).
+   *
+   * The final `requestOrConnection` parameter will either be the HTTP(S)
+   * request or the web socket connection, in those two cases respectively. You
+   * can, for instance, use this to distinguish between different users.
+   *
+   * Return `false` from this method to disallow changes to this Cell on the
+   * server, or `true` to allow them. The default implementation returns `true`
+   * to allow all changes.
+   * @example
+   * The following implementation will strip out any attempts by the client to
+   * update the 'name' Cell of the 'me' Row of the 'user' Table after the
+   * initial save:
+   *
+   * ```js
+   * class MyServer extends TinyBasePartyKitServer {
+   *   canSetCell(tableId, rowId, cellId, cell, initialSave) {
+   *     return (
+   *       initialSave || tableId != 'user' || rowId != 'me' || cellId != 'name'
+   *     );
+   *   }
+   * }
+   * ```
+   * @category Sanitization
+   * @since v4.3.12
+   */
+  canSetCell(
+    tableId: Id,
+    rowId: Id,
+    cellId: Id,
+    cell: Cell,
+    initialSave: boolean,
+    requestOrConnection: Request | Connection,
+    oldCell: CellOrUndefined,
+  ): boolean;
+  /**
+   * The canDelCell method lets you allow or disallow deletions of a Cell stored
+   * on the server, as sent from a client.
+   *
+   * This is one of the functions use to sanitize the data that is being sent
+   * from a client. Perhaps you might want to make sure the server-stored data
+   * adheres to a particular schema, or you might want to make certain data
+   * read-only. Remember that you cannot trust the client to only send data that
+   * the server considers valid or safe.
+   *
+   * This method is passed the Table Id, Row Id, and Cell Id that the client is
+   * trying to delete. The `connection` parameter will be the web socket
+   * connection of that client. You can, for instance, use this to distinguish
+   * between different users.
+   *
+   * Return `false` from this method to disallow this Cell from being deleted on
+   * the server, or `true` to allow it. The default implementation returns
+   * `true` to allow deletion.
+   * @example
+   * The following implementation will strip out any attempts by the client to
+   * delete the 'name' Cell of the 'me' Row of the 'user' Table:
+   *
+   * ```js
+   * class MyServer extends TinyBasePartyKitServer {
+   *   canDelCell(tableId, rowId, cellId) {
+   *     return tableId != 'user' || rowId != 'me' || cellId != 'name';
+   *   }
+   * }
+   * ```
+   * @category Sanitization
+   * @since v4.3.12
+   */
+  canDelCell(
+    tableId: Id,
+    rowId: Id,
+    cellId: Id,
+    connection: Connection,
+  ): boolean;
+  /**
+   * The canSetValue method lets you allow or disallow any changes to a Value
+   * stored on the server, as sent from a client.
+   *
+   * This is one of the functions use to sanitize the data that is being sent
+   * from a client. Perhaps you might want to make sure the server-stored data
+   * adheres to a particular schema, or you might want to make certain data
+   * read-only. Remember that you cannot trust the client to only send data that
+   * the server considers valid or safe.
+   *
+   * This method is passed the Value Id that the client is trying to change - as
+   * well as the Value itself. The `initialSave` parameter distinguishes between
+   * the first bulk save of the Store to the PartyKit room over HTTP (`true`),
+   * and subsequent incremental updates over a web sockets (`false`).
+   *
+   * The `requestOrConnection` parameter will either be the HTTP(S) request or
+   * the web socket connection, in those two cases respectively. You can, for
+   * instance, use this to distinguish between different users.
+   *
+   * Since v4.3.13, the final parameter is the Value previously stored on the
+   * server, if any. Use this to distinguish between the addition of a new Value
+   * (in which case it will be undefined) and the updating of an existing one.
+   *
+   * Return `false` from this method to disallow changes to this Value on the
+   * server, or `true` to allow them. The default implementation returns `true`
+   * to allow all changes.
+   * @example
+   * The following implementation will strip out any attempts by the client to
+   * update the 'userId' Value after the initial save:
+   *
+   * ```js
+   * class MyServer extends TinyBasePartyKitServer {
+   *   canSetValue(valueId, value, initialSave) {
+   *     return initialSave || userId != 'userId';
+   *   }
+   * }
+   * ```
+   * @category Sanitization
+   * @since v4.3.12
+   */
+  canSetValue(
+    valueId: Id,
+    value: Value,
+    initialSave: boolean,
+    requestOrConnection: Request | Connection,
+    oldValue: ValueOrUndefined,
+  ): boolean;
+  /**
+   * The canDelValue method lets you allow or disallow deletions of a Value
+   * stored on the server, as sent from a client.
+   *
+   * This is one of the functions use to sanitize the data that is being sent
+   * from a client. Perhaps you might want to make sure the server-stored data
+   * adheres to a particular schema, or you might want to make certain data
+   * read-only. Remember that you cannot trust the client to only send data that
+   * the server considers valid or safe.
+   *
+   * This method is passed the Value Id that the client is trying to delete. The
+   * `connection` parameter will be the web socket connection of that client.
+   * You can, for instance, use this to distinguish between different users.
+   *
+   * Return `false` from this method to disallow this Value from being deleted
+   * on the server, or `true` to allow it. The default implementation returns
+   * `true` to allow deletion.
+   * @example
+   * The following implementation will strip out any attempts by the client to
+   * delete the 'userId' Value:
+   *
+   * ```js
+   * class MyServer extends TinyBasePartyKitServer {
+   *   canDelValue(valueId) {
+   *     return valueId != 'userId';
+   *   }
+   * }
+   * ```
+   * @category Sanitization
+   * @since v4.3.12
    */
-  onMessage(message: string, client: Connection): void;
+  canDelValue(valueId: Id, connection: Connection): boolean;
 }

package/lib/types/tools.d.ts

@@ -413,9 +413,8 @@ export interface Tools {
    *   },
    * });
    * const tools = createTools(store);
-   * const [dTs, ts, uiReactDTs, uiReactTsx] = await createTools(
-   *   store,
-   * ).getPrettyStoreApi('shop');
+   * const [dTs, ts, uiReactDTs, uiReactTsx] =
+   *   await createTools(store).getPrettyStoreApi('shop');
    *
    * const dTsLines = dTs.split('\n');
    * console.log(dTsLines[17]);
@@ -434,9 +433,8 @@ export interface Tools {
    *   felix: {price: 4},
    * });
    * const tools = createTools(store);
-   * const [dTs, ts, uiReactDTs, uiReactTsx] = await createTools(
-   *   store,
-   * ).getPrettyStoreApi('shop');
+   * const [dTs, ts, uiReactDTs, uiReactTsx] =
+   *   await createTools(store).getPrettyStoreApi('shop');
    *
    * const dTsLines = dTs.split('\n');
    * console.log(dTsLines[17]);

package/lib/types/ui-react.d.ts

@@ -3708,8 +3708,8 @@ export function useStartTransactionListener(
  *   </Provider>
  * );
  * const Pane = () => {
- *   useWillFinishTransactionListener(
- *     () => console.log('Will finish transaction'),
+ *   useWillFinishTransactionListener(() =>
+ *     console.log('Will finish transaction'),
  *   );
  *   return <span>App</span>;
  * };
@@ -3767,8 +3767,8 @@ export function useWillFinishTransactionListener(
  *   </Provider>
  * );
  * const Pane = () => {
- *   useDidFinishTransactionListener(
- *     () => console.log('Did finish transaction'),
+ *   useDidFinishTransactionListener(() =>
+ *     console.log('Did finish transaction'),
  *   );
  *   return <span>App</span>;
  * };

package/lib/types/with-schemas/persisters/persister-indexed-db.d.ts

@@ -51,11 +51,10 @@ import {Persister} from '../persisters';
  * browser's IndexedDB storage.
  *
  * ```js
- * const store =
- *   createStore()
- *     .setTable('pets', {fido: {species: 'dog'}})
- *     .setTable('species', {dog: {price: 5}})
- *     .setValues({open: true});
+ * const store = createStore()
+ *   .setTable('pets', {fido: {species: 'dog'}})
+ *   .setTable('species', {dog: {price: 5}})
+ *   .setValues({open: true});
  * const persister = createIndexedDbPersister(store, 'petStore');
  *
  * await persister.save();

package/lib/types/with-schemas/persisters/persister-partykit-client.d.ts

@@ -39,7 +39,7 @@ import {Persister} from '../persisters';
  * to the TinyBasePartyKitServerConfig on the server side.
  *
  * ```js
- * const partyKitPersisterConfig: PartyKitPersisterConfig = {
+ * const partyKitPersisterConfig = {
  *   storeProtocol: 'http',
  *   storePath: '/my_tinybase',
  * };
@@ -57,9 +57,18 @@ export type PartyKitPersisterConfig = {
   /**
    * The path used to set and get the whole Store over HTTP(S) on the server.
    * This must match the storePath property of the TinyBasePartyKitServerConfig
-   * object on the server. Both default to '/store'.
+   * object used on the server. Both default to '/store'.
    */
   storePath?: string;
+  /**
+   * The prefix at the beginning of the web socket messages sent between the
+   * client and the server when synchronizing the Store. Use this to make sure
+   * they do not collide with any other message syntax that your room is using.
+   * This must match the messagePrefix property of the
+   * TinyBasePartyKitServerConfig object used on the server. Both default to an
+   * empty string.
+   */
+  messagePrefix?: string;
 };
 
 /**
@@ -114,12 +123,14 @@ export type PartyKitPersisterConfig = {
  * browser's IndexedDB storage.
  *
  * ```js yolo
- * const store =
- *   createStore()
- *     .setTable('pets', {fido: {species: 'dog'}})
- *     .setTable('species', {dog: {price: 5}})
- *     .setValues({open: true});
- * const partySocket = new PartySocket({host: PARTYKIT_HOST, room: 'my_room'});
+ * const store = createStore()
+ *   .setTable('pets', {fido: {species: 'dog'}})
+ *   .setTable('species', {dog: {price: 5}})
+ *   .setValues({open: true});
+ * const partySocket = new PartySocket({
+ *   host: PARTYKIT_HOST,
+ *   room: 'my_room',
+ * });
  * const persister = createPartyKitPersister(store, partySocket);
  * await persister.startAutoLoad();
  * await persister.startAutoSave();