tinybase 4.3.10 → 4.3.12

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

@@ -18,7 +18,9 @@
  * @since 4.3.0
  */
 
+import {Cell, Value} 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 {
+ * ```js
+ * class MyServer extends TinyBasePartyKitServer {
  *   readonly config: TinyBasePartyKitServerConfig = {
  *     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
@@ -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,7 +181,7 @@ export class TinyBasePartyKitServer implements Server {
    * synchronization stays supported:
    *
    * ```js
-   * export default class extends TinyBasePartyServer {
+   * class MyServer extends TinyBasePartyKitServer {
    *   async onMessage(message, client) {
    *     await super.onMessage(message, client);
    *     // custom onMessage code
@@ -176,6 +192,318 @@ 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, client: 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 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 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,
+  ): 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 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 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,
+  ): 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-dom.d.ts

@@ -1476,6 +1476,10 @@ export function ResultSortedTableInHtmlTable(
  * A Cell contains a string, number, or boolean, so the value is rendered in an
  * appropriate <input> tag and a button lets the user change type, if possible.
  *
+ * Set the `showType` prop to false to remove the ability for the user to see or
+ * change the Cell type. They will also not be able to change the type if there
+ * is a TablesSchema applied to the Store.
+ *
  * This component uses the useCell hook under the covers, which means that any
  * changes to the specified Cell outside of this component will cause a
  * re-render.
@@ -1516,7 +1520,7 @@ export function ResultSortedTableInHtmlTable(
  * @since v4.1.0
  */
 export function EditableCellView(
-  props: CellProps & {readonly className?: string},
+  props: CellProps & {readonly className?: string; readonly showType?: boolean},
 ): ComponentReturnType;
 
 /**
@@ -1533,6 +1537,10 @@ export function EditableCellView(
  * A Value contains a string, number, or boolean, so the value is rendered in an
  * appropriate <input> tag and a button lets the user change type, if possible.
  *
+ * Set the `showType` prop to false to remove the ability for the user to see or
+ * change the Value type. They will also not be able to change the type if there
+ * is a ValuesSchema applied to the Store.
+ *
  * This component uses the useValue hook under the covers, which means that any
  * changes to the specified Value outside of this component will cause a
  * re-render.
@@ -1571,7 +1579,10 @@ export function EditableCellView(
  * @since v4.1.0
  */
 export function EditableValueView(
-  props: ValueProps & {readonly className?: string},
+  props: ValueProps & {
+    readonly className?: string;
+    readonly showType?: boolean;
+  },
 ): ComponentReturnType;
 
 /**

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

@@ -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();