tinybase 4.3.0-beta.0 → 4.3.0

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

@@ -42,6 +42,7 @@ import {
   TableListener,
   Tables,
   TablesListener,
+  TransactionListener,
   Value,
   ValueIdsListener,
   ValueListener,
@@ -3621,6 +3622,180 @@ export function useValueListener(
   storeOrStoreId?: StoreOrStoreId,
 ): void;
 
+/**
+ * The useStartTransactionListener hook registers a listener function with the
+ * Store that will be called at the start of a transaction.
+ *
+ * Unlike the addStartTransactionListener method, which returns a listener Id
+ * and requires you to remove it manually, the useStartTransactionListener hook
+ * manages this lifecycle for you: when the listener changes (per its
+ * `listenerDeps` dependencies) or the component unmounts, the listener on the
+ * underlying Store will be deleted.
+ * @param listener The function that will be called at the start of a
+ * transaction.
+ * @param listenerDeps An optional array of dependencies for the `listener`
+ * function, which, if any change, result in the re-registration of the
+ * listener. This parameter defaults to an empty array.
+ * @param storeOrStoreId The Store to register the listener with: omit for the
+ * default context Store, provide an Id for a named context Store, or provide an
+ * explicit reference.
+ * @example
+ * This example uses the useStartTransactionListener hook to create a listener
+ * that is scoped to a single component. When the component is unmounted, the
+ * listener is removed from the Store.
+ *
+ * ```jsx
+ * const App = ({store}) => (
+ *   <Provider store={store}>
+ *     <Pane />
+ *   </Provider>
+ * );
+ * const Pane = () => {
+ *   useStartTransactionListener(() => console.log('Start transaction'));
+ *   return <span>App</span>;
+ * };
+ *
+ * const store = createStore();
+ * const app = document.createElement('div');
+ * const root = ReactDOMClient.createRoot(app);
+ * root.render(<App store={store} />); // !act
+ * console.log(store.getListenerStats().transaction);
+ * // -> 1
+ *
+ * store.setValue('open', false); // !act
+ * // -> 'Start transaction'
+ *
+ * root.unmount(); // !act
+ * console.log(store.getListenerStats().transaction);
+ * // -> 0
+ * ```
+ * @category Store hooks
+ * @since v4.2.2
+ */
+export function useStartTransactionListener(
+  listener: TransactionListener,
+  listenerDeps?: React.DependencyList,
+  storeOrStoreId?: StoreOrStoreId,
+): void;
+
+/**
+ * The useWillFinishTransactionListener hook registers a listener function with
+ * a Store that will be called just before other non-mutating listeners are
+ * called at the end of the transaction.
+ *
+ * Unlike the addWillFinisTransactionListener method, which returns a listener
+ * Id and requires you to remove it manually, the
+ * useWillFinishTransactionListener hook manages this lifecycle for you: when
+ * the listener changes (per its `listenerDeps` dependencies) or the component
+ * unmounts, the listener on the underlying Store will be deleted.
+ * @param listener The function that will be called before the end of a
+ * transaction.
+ * @param listenerDeps An optional array of dependencies for the `listener`
+ * function, which, if any change, result in the re-registration of the
+ * listener. This parameter defaults to an empty array.
+ * @param storeOrStoreId The Store to register the listener with: omit for the
+ * default context Store, provide an Id for a named context Store, or provide an
+ * explicit reference.
+ * @example
+ * This example uses the useWillFinishTransactionListener hook to create a
+ * listener that is scoped to a single component. When the component is
+ * unmounted, the listener is removed from the Store.
+ *
+ * ```jsx
+ * const App = ({store}) => (
+ *   <Provider store={store}>
+ *     <Pane />
+ *   </Provider>
+ * );
+ * const Pane = () => {
+ *   useWillFinishTransactionListener(
+ *     () => console.log('Will finish transaction'),
+ *   );
+ *   return <span>App</span>;
+ * };
+ *
+ * const store = createStore();
+ * const app = document.createElement('div');
+ * const root = ReactDOMClient.createRoot(app);
+ * root.render(<App store={store} />); // !act
+ * console.log(store.getListenerStats().transaction);
+ * // -> 1
+ *
+ * store.setValue('open', false); // !act
+ * // -> 'Will finish transaction'
+ *
+ * root.unmount(); // !act
+ * console.log(store.getListenerStats().transaction);
+ * // -> 0
+ * ```
+ * @category Store hooks
+ * @since v4.2.2
+ */
+export function useWillFinishTransactionListener(
+  listener: TransactionListener,
+  listenerDeps?: React.DependencyList,
+  storeOrStoreId?: StoreOrStoreId,
+): void;
+
+/**
+ * The useDidFinishTransactionListener hook registers a listener function with a
+ * Store that will be called just after other non-mutating listeners are called
+ * at the end of the transaction.
+ *
+ * Unlike the addDidFinishTransactionListener method, which returns a listener
+ * Id and requires you to remove it manually, the
+ * useDidFinishTransactionListener hook manages this lifecycle for you: when the
+ * listener changes (per its `listenerDeps` dependencies) or the component
+ * unmounts, the listener on the underlying Store will be deleted.
+ * @param listener The function that will be called after the end of a
+ * transaction.
+ * @param listenerDeps An optional array of dependencies for the `listener`
+ * function, which, if any change, result in the re-registration of the
+ * listener. This parameter defaults to an empty array.
+ * @param storeOrStoreId The Store to register the listener with: omit for the
+ * default context Store, provide an Id for a named context Store, or provide an
+ * explicit reference.
+ * @example
+ * This example uses the useDidFinishTransactionListener hook to create a
+ * listener that is scoped to a single component. When the component is
+ * unmounted, the listener is removed from the Store.
+ *
+ * ```jsx
+ * const App = ({store}) => (
+ *   <Provider store={store}>
+ *     <Pane />
+ *   </Provider>
+ * );
+ * const Pane = () => {
+ *   useDidFinishTransactionListener(
+ *     () => console.log('Did finish transaction'),
+ *   );
+ *   return <span>App</span>;
+ * };
+ *
+ * const store = createStore();
+ * const app = document.createElement('div');
+ * const root = ReactDOMClient.createRoot(app);
+ * root.render(<App store={store} />); // !act
+ * console.log(store.getListenerStats().transaction);
+ * // -> 1
+ *
+ * store.setValue('open', false); // !act
+ * // -> 'Did finish transaction'
+ *
+ * root.unmount(); // !act
+ * console.log(store.getListenerStats().transaction);
+ * // -> 0
+ * ```
+ * @category Store hooks
+ * @since v4.2.2
+ */
+export function useDidFinishTransactionListener(
+  listener: TransactionListener,
+  listenerDeps?: React.DependencyList,
+  storeOrStoreId?: StoreOrStoreId,
+): void;
+
 /**
  * The useCreateMetrics hook is used to create a Metrics object within a React
  * application with convenient memoization.
@@ -8715,6 +8890,12 @@ export function useCheckpointListener(
  * an array in the fifth parameter. The Persister itself is used as a dependency
  * by default.
  *
+ * Since v4.3.0, the `create` function can return undefined, meaning that you
+ * can enable or disable persistence conditionally within this hook. This is
+ * useful for applications which might turn on or off their cloud persistence or
+ * collaboration features. As a result, the `then` callback may also get passed
+ * undefined, which you should handle accordingly.
+ *
  * This hook ensures the Persister object is destroyed whenever a new one is
  * created or the component is unmounted.
  * @param store A reference to the Store for which to create a new Persister
@@ -8825,13 +9006,15 @@ export function useCheckpointListener(
  * ```
  *  @category Persister hooks
  */
-export function useCreatePersister(
+export function useCreatePersister<
+  PersisterOrUndefined extends Persister | undefined,
+>(
   store: Store,
-  create: (store: Store) => Persister,
+  create: (store: Store) => PersisterOrUndefined,
   createDeps?: React.DependencyList,
-  then?: (persister: Persister) => Promise<void>,
+  then?: (persister: PersisterOrUndefined) => Promise<void>,
   thenDeps?: React.DependencyList,
-): Persister;
+): PersisterOrUndefined;
 
 /**
  * The ExtraProps type represents a set of arbitrary additional props.

package/lib/types/with-schemas/persisters/persister-cr-sqlite-wasm.d.ts

@@ -5,6 +5,7 @@
  * @see Persisting Data guide
  * @packageDocumentation
  * @module persister-cr-sqlite-wasm
+ * @since v4.0.0
  */
 
 import {DatabasePersisterConfig, Persister} from '../persisters';
@@ -107,6 +108,7 @@ import {DB} from '@vlcn.io/crsqlite-wasm';
  * persister.destroy();
  * ```
  * @category Creation
+ * @since v4.0.0
  */
 export function createCrSqliteWasmPersister<Schemas extends OptionalSchemas>(
   store: Store<Schemas>,

package/lib/types/with-schemas/persisters/persister-expo-sqlite.d.ts

@@ -8,6 +8,7 @@
  * @see Persisting Data guide
  * @packageDocumentation
  * @module persister-expo-sqlite
+ * @since v4.0.3
  */
 
 import {DatabasePersisterConfig, Persister} from '../persisters';
@@ -128,6 +129,7 @@ import {SQLiteDatabase} from 'expo-sqlite';
  * persister.destroy();
  * ```
  * @category Creation
+ * @since v4.0.3
  */
 export function createExpoSqlitePersister<Schemas extends OptionalSchemas>(
   store: Store<Schemas>,

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

@@ -0,0 +1,99 @@
+/**
+ * The persister-partykit-client module of the TinyBase project contains the
+ * client portion of the PartyKit integration.
+ *
+ * It contains a Persister which, when run in a PartyKit client environment,
+ * lets you save and load Store data from the client to durable PartyKit cloud
+ * storage of a server (that is using the complementary
+ * persister-partykit-server module).
+ *
+ * This enables synchronization of the same Store across multiple clients in a
+ * PartyKit party room.
+ *
+ * Note that both the client and server parts of this Persister are currently
+ * experimental as PartyKit is new and still maturing.
+ * @see Persisting Data guide
+ * @see Todo App v6 (collaboration) demo
+ * @packageDocumentation
+ * @module persister-partykit-client
+ * @since 4.3.0
+ */
+
+import {OptionalSchemas, Store} from '../store';
+import PartySocket from 'partysocket';
+import {Persister} from '../persisters';
+
+/**
+ * The createPartyKitPersister function creates a Persister object that can
+ * persist the Store to durable PartyKit storage, enabling synchronization of
+ * the same Store across multiple clients.
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * createPartyKitPersister(
+ *   store: Store,
+ *   connection: PartySocket,
+ *   storeUrlProtocol?: 'http' | 'https',
+ *   onIgnoredError?: (error: any) => void,
+ * ): Persister;
+ * ```
+ *
+ * As well as providing a reference to the Store to persist, you must provide a
+ * `connection` parameter which is a PartyKit PartySocket that you have already
+ * instantiated with details of the host and room.
+ *
+ * All suitably-equipped TinyBase clients connecting to that room will get to
+ * share synchronized Store state.
+ *
+ * The server room's Store is considered the source of truth. If it is a
+ * newly-created room, then calling the save method on this Persister will
+ * initiate it. If, however, there is already a Store present on the server, the
+ * save method will fail gracefully.
+ *
+ * In general, you are strongly recommended to use the auto-save and auto-load
+ * functionality to stay in sync incrementally with the server, as per the
+ * example below. This pattern will handle newly-created servers and
+ * newly-created clients - and the synchronization involved in joining rooms,
+ * leaving them, or temporarily going offline.
+ *
+ * See the [PartyKit client socket API
+ * documentation](https://docs.partykit.io/reference/partysocket-api/) for more
+ * details.
+ * @param store The Store to persist.
+ * @param connection The PartySocket to use for participating in the PartyKit
+ * room.
+ * @param storeUrlProtocol The HTTP protocol to use (in addition to the
+ * websocket channel). This defaults to 'https' but you may wish to use 'http'
+ * for local PartyKit development.
+ * @param onIgnoredError An optional handler for the errors that the Persister
+ * would otherwise ignore when trying to save or load data. This is suitable for
+ * debugging persistence issues in a development environment.
+ * @returns A reference to the new Persister object.
+ * @example
+ * This example creates a Persister object and persists the Store to the
+ * 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 persister = createPartyKitPersister(store, partySocket);
+ * await persister.startAutoLoad();
+ * await persister.startAutoSave();
+ * // Store will now be synchronized with the room.
+ *
+ * persister.destroy();
+ * ```
+ * @category Creation
+ * @since 4.3.0
+ */
+export function createPartyKitPersister<Schemas extends OptionalSchemas>(
+  store: Store<Schemas>,
+  connection: PartySocket,
+  storeUrlProtocol?: 'http' | 'https',
+  onIgnoredError?: (error: any) => void,
+): Persister<Schemas>;

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

@@ -0,0 +1,114 @@
+/**
+ * The persister-partykit-server module of the TinyBase project contains the
+ * server portion of the PartyKit integration.
+ *
+ * It contains a class which, when run in a PartyKit server environment, lets
+ * you save and load Store data from a client (that is using the complementary
+ * persister-partykit-client module) to durable PartyKit cloud storage.
+ *
+ * This enables synchronization of the same Store across multiple clients in a
+ * PartyKit party room.
+ *
+ * Note that both the client and server parts of this Persister are currently
+ * experimental as PartyKit is new and still maturing.
+ * @see Persisting Data guide
+ * @see Todo App v6 (collaboration) demo
+ * @packageDocumentation
+ * @module persister-partykit-server
+ * @since 4.3.0
+ */
+
+import {Connection, Request, Server} from 'partykit/server';
+
+/**
+ * A TinyBasePartyKitServer is the server component for persisting the Store to
+ * durable PartyKit storage, enabling synchronization of the same Store across
+ * multiple clients.
+ *
+ * This extends the PartyKit Server class, which provides a selection of methods
+ * you are expected to implement. The TinyBasePartyKitServer implements only two
+ * of them, the onMessage method and the onRequest method, as well as the
+ * constructor.
+ *
+ * If you wish to use TinyBasePartyKitServer as a general PartyKit server, you
+ * can implement other methods. But you must remember to call the super
+ * implementations of those methods to ensure the TinyBase synchronization stays
+ * supported in addition to your own custom functionality. The same applies to
+ * the constructor if you choose to implement that.
+ *
+ * ```js
+ * // This is your PartyKit server entry point.
+ *
+ * export default class extends TinyBasePartyServer {
+ *   constructor(party) {
+ *     super(party);
+ *     // custom constructor code
+ *   }
+ *
+ *   async onStart() {
+ *     // no need to call super.onStart()
+ *     console.log('Server started');
+ *   }
+ *
+ *   async onMessage(message, client) {
+ *     await super.onMessage(message, client);
+ *     // custom onMessage code
+ *   }
+ *
+ *   async onRequest(request) {
+ *     // custom onRequest code, else:
+ *     return await super.onRequest(request);
+ *   }
+ * }
+ * ```
+ *
+ * See the [PartyKit server API
+ * documentation](https://docs.partykit.io/reference/partyserver-api/) for
+ * more details.
+ */
+export class TinyBasePartyKitServer implements Server {
+  /**
+   * The onRequest method is called when a HTTP request is made to the party
+   * URL.
+   *
+   * If you choose to implement additional functionality in this method, you
+   * must remember to call the super implementation to ensure the TinyBase
+   * synchronization stays supported:
+   *
+   * ```js
+   * export default class extends TinyBasePartyServer {
+   *   async onRequest(request) {
+   *     // custom onRequest code, else:
+   *     return await super.onRequest(request);
+   *   }
+   * }
+   * ```
+   *
+   * See the [PartyKit server API
+   * documentation](https://docs.partykit.io/reference/partyserver-api/) for
+   * more details.
+   */
+  onRequest(request: Request): Promise<Response>;
+  /**
+   * The onMessage method is called when the server receives a message from a
+   * client.
+   *
+   * If you choose to implement additional functionality in this method, you
+   * must remember to call the super implementation to ensure the TinyBase
+   * synchronization stays supported:
+   *
+   * ```js
+   * export default class extends TinyBasePartyServer {
+   *   async onMessage(message, client) {
+   *     await super.onMessage(message, client);
+   *     // custom onMessage code
+   *   }
+   * }
+   * ```
+   *
+   * See the [PartyKit server API
+   * documentation](https://docs.partykit.io/reference/partyserver-api/) for
+   * more details.
+   */
+  onMessage(message: string, client: Connection): void;
+}

package/lib/types/with-schemas/persisters/persister-sqlite-wasm.d.ts

@@ -5,6 +5,7 @@
  * @see Persisting Data guide
  * @packageDocumentation
  * @module persister-sqlite-wasm
+ * @since v4.0.0
  */
 
 import {DatabasePersisterConfig, Persister} from '../persisters';
@@ -114,6 +115,7 @@ import {OptionalSchemas, Store} from '../store';
  * persister.destroy();
  * ```
  * @category Creation
+ * @since v4.0.0
  */
 export function createSqliteWasmPersister<Schemas extends OptionalSchemas>(
   store: Store<Schemas>,

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

@@ -5,6 +5,7 @@
  * @see Persisting Data guide
  * @packageDocumentation
  * @module persister-sqlite3
+ * @since v4.0.0
  */
 
 import {DatabasePersisterConfig, Persister} from '../persisters';
@@ -121,6 +122,7 @@ import {Database} from 'sqlite3';
  * persister.destroy();
  * ```
  * @category Creation
+ * @since v4.0.0
  */
 export function createSqlite3Persister<Schemas extends OptionalSchemas>(
   store: Store<Schemas>,

package/lib/types/with-schemas/store.d.ts

@@ -6949,6 +6949,8 @@ export interface Store<in out Schemas extends OptionalSchemas> {
    * Note that a TransactionListener added to the Store with this method can
    * mutate the Store, and its changes will be treated as part of the
    * transaction that is starting.
+   * @param listener The function that will be called at the start of a
+   * transaction.
    * @returns A unique Id for the listener that can later be used to remove it.
    * @example
    * This example registers a listener that is called at start end of the
@@ -7011,6 +7013,8 @@ export interface Store<in out Schemas extends OptionalSchemas> {
    * mutate the Store itself, and its changes will be treated as part of the
    * transaction that is starting (and may fire non-mutating listeners after
    * this).
+   * @param listener The function that will be called before the end of a
+   * transaction.
    * @returns A unique Id for the listener that can later be used to remove it.
    * @example
    * This example registers a listener that is called at the end of the
@@ -7113,6 +7117,8 @@ export interface Store<in out Schemas extends OptionalSchemas> {
    *
    * Note that a TransactionListener added to the Store with this method
    * _cannot_ mutate the Store itself, and attempts to do so will fail silently.
+   * @param listener The function that will be called after the end of a
+   * transaction.
    * @returns A unique Id for the listener that can later be used to remove it.
    * @example
    * This example registers a listener that is called at the end of the