tinybase 5.0.0-beta.25 → 5.0.0-beta.27

package/@types/persisters/with-schemas/index.d.ts

@@ -1,30 +1,34 @@
 /**
  * The persisters module of the TinyBase project provides a simple framework for
- * saving and loading Store data, to and from different destinations, or
- * underlying storage types.
+ * saving and loading Store and MergeableStore data, to and from different
+ * destinations, or underlying storage types.
  *
  * Several entry points are provided (in separately installed modules), each of
  * which returns a new Persister object that can load and save a Store. Between
  * them, these allow you to store your TinyBase data locally, remotely, to
  * SQLite databases, and across synchronization boundaries with CRDT frameworks.
  *
- * |Module|Function|Storage|
- * |-|-|-|
- * |persister-browser|createSessionPersister|Browser session storage|
- * |persister-browser|createLocalPersister|Browser local storage|
- * |persister-indexed-db|createIndexedDbPersister|Browser IndexedDB|
- * |persister-remote|createRemotePersister|Remote server|
- * |persister-file|createFilePersister|Local file (where possible)|
- * |persister-partykit-client|createPartyKitPersister|PartyKit with the persister-partykit-server module|
- * |persister-sqlite3|createSqlite3Persister|SQLite in Node, via [sqlite3](https://github.com/TryGhost/node-sqlite3)|
- * |persister-sqlite-wasm|createSqliteWasmPersister|SQLite in a browser, via [sqlite-wasm](https://github.com/tomayac/sqlite-wasm)|
- * |persister-cr-sqlite-wasm|createCrSqliteWasmPersister|SQLite CRDTs, via [cr-sqlite-wasm](https://github.com/vlcn-io/cr-sqlite)|
- * |persister-expo-sqlite|createExpoSqlitePersister|SQLite in React Native, via [expo-sqlite](https://github.com/expo/expo/tree/main/packages/expo-sqlite)|
- * |persister-electric-sql|createElectricSqlPersister|Electric SQL, via [electric-sql](https://github.com/electric-sql/electric)|
- * |persister-libsql|createLibSqlPersister|LibSQL for Turso, via [libsql-client](https://github.com/tursodatabase/libsql-client-ts)|
- * |persister-powersync|createPowerSyncPersister|PowerSync, via [powersync-sdk](https://github.com/powersync-ja/powersync-js)|
- * |persister-yjs|createYjsPersister|Yjs CRDTs, via [yjs](https://github.com/yjs/yjs)|
- * |persister-automerge|createSqliteWasmPersister|Automerge CRDTs, via [automerge-repo](https://github.com/automerge/automerge-repo)|
+ * |Module|Function|Storage|Store|MergeableStore
+ * |-|-|-|-|-|
+ * |persister-browser|createSessionPersister|Browser session storage|Yes|Yes
+ * |persister-browser|createLocalPersister|Browser local storage|Yes|Yes
+ * |persister-file|createFilePersister|Local file (where possible)|Yes|Yes
+ * |persister-sqlite3|createSqlite3Persister|SQLite in Node, via [sqlite3](https://github.com/TryGhost/node-sqlite3)|Yes|Yes*
+ * |persister-sqlite-wasm|createSqliteWasmPersister|SQLite in a browser, via [sqlite-wasm](https://github.com/tomayac/sqlite-wasm)|Yes|Yes*
+ * |persister-expo-sqlite|createExpoSqlitePersister|SQLite in React Native, via [expo-sqlite](https://github.com/expo/expo/tree/main/packages/expo-sqlite)|Yes|Yes*
+ * |persister-indexed-db|createIndexedDbPersister|Browser IndexedDB|Yes|No
+ * |persister-remote|createRemotePersister|Remote server|Yes|No
+ * |persister-partykit-client|createPartyKitPersister|PartyKit with the persister-partykit-server module|Yes|No
+ * |persister-cr-sqlite-wasm|createCrSqliteWasmPersister|SQLite CRDTs, via [cr-sqlite-wasm](https://github.com/vlcn-io/cr-sqlite)|Yes|No
+ * |persister-electric-sql|createElectricSqlPersister|Electric SQL, via [electric-sql](https://github.com/electric-sql/electric)|Yes|No
+ * |persister-libsql|createLibSqlPersister|LibSQL for Turso, via [libsql-client](https://github.com/tursodatabase/libsql-client-ts)|Yes|No
+ * |persister-powersync|createPowerSyncPersister|PowerSync, via [powersync-sdk](https://github.com/powersync-ja/powersync-js)|Yes|No
+ * |persister-yjs|createYjsPersister|Yjs CRDTs, via [yjs](https://github.com/yjs/yjs)|Yes|No
+ * |persister-automerge|createSqliteWasmPersister|Automerge CRDTs, via [automerge-repo](https://github.com/automerge/automerge-repo)|Yes|No|
+ *
+ * (*) Note that SQLite-based Persisters can currently only persist
+ * MergeableStore data when using the JSON-based DpcJson mode, and not in a
+ * tabular fashion.
  *
  * Since persistence requirements can be different for every app, the
  * createCustomPersister function in this module can also be used to easily
@@ -54,67 +58,155 @@ import type {
 import type {TableIdFromSchema} from '../../_internal/store/with-schemas/index.d.ts';
 
 /**
- * The StoreTypes type
+ * The Persists enum is used to indicate whether a Persister can support a
+ * regular Store, a MergeableStore, or both.
+ *
+ * The enum is intended to be used by the author of a Persister to indicate
+ * which types of store can be persisted. If you discover type errors when
+ * trying to instantiate a Persister, it is most likely that you are passing in
+ * an unsupported type of store.
+ *
+ * See the createCustomPersister method for an example of this enum being used.
+ * @category Mergeable
+ * @since v5.0.0
  */
-export type StoreTypes =
-  | 1 // Store only
-  | 2 // MergeableStore only
-  | 3; // Store and MergeableStore
+export const enum Persists {
+  /**
+   * Indicates that only a regular Store can be supported by a Persister.
+   */
+  StoreOnly = 1,
+  /**
+   * Indicates that only a MergeableStore can be supported by a Persister.
+   */
+  MergeableStoreOnly = 2,
+  /**
+   * Indicates that either a regular Store or a MergeableStore can be supported
+   * by a Persister.
+   */
+  StoreOrMergeableStore = 3,
+}
 
 /**
- * The PersistedStore type
+ * The PersistedStore type is a generic representation of the type of store
+ * being handled by a Persister.
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * export type PersistedStore<Persist extends Persists = Persists.StoreOnly> =
+ *   Persist extends Persists.StoreOrMergeableStore
+ *     ? Store | MergeableStore
+ *     : Persist extends Persists.MergeableStoreOnly
+ *       ? MergeableStore
+ *       : Store;
+ * ```
+ *
+ * Using the values of the Persists enum, the generic parameter indicates
+ * whether the Persister is handling a regular Store, a MergeableStore, or
+ * either.
+ *
+ * If the generic parameter is unspecified, the StoreOnly enum value is used,
+ * meaning that PersistedStore is equivalent to a regular Store.
+ * @category Mergeable
+ * @since v5.0.0
  */
 export type PersistedStore<
   Schemas extends OptionalSchemas,
-  StoreType extends StoreTypes = 1,
-> = StoreType extends 3
+  Persist extends Persists = Persists.StoreOnly,
+> = Persist extends Persists.StoreOrMergeableStore
   ? Store<Schemas> | MergeableStore<Schemas>
-  : StoreType extends 2
+  : Persist extends Persists.MergeableStoreOnly
     ? MergeableStore<Schemas>
     : Store<Schemas>;
 
 /**
- * The PersistedContent type
+ * The PersistedContent type is a generic representation of the content in the
+ * type of store being handled by a Persister.
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * export type PersistedContent<Persist extends Persists = Persists.StoreOnly> =
+ *   Persist extends Persists.StoreOrMergeableStore
+ *     ? Content | MergeableContent
+ *     : Persist extends Persists.MergeableStoreOnly
+ *       ? MergeableContent
+ *       : Content;
+ * ```
+ *
+ * Using the values of the Persists enum, the generic parameter indicates
+ * whether the Persister is handling content from a regular Store (the Content
+ * type), a MergeableStore (the MergeableContent type), or either (the union of
+ * the two).
+ *
+ * If the generic parameter is unspecified, the StoreOnly enum value is used,
+ * meaning that PersistedContent is equivalent to the Content type.
+ * @category Mergeable
+ * @since v5.0.0
  */
 export type PersistedContent<
   Schemas extends OptionalSchemas,
-  StoreType extends StoreTypes = 1,
-> = StoreType extends 3
+  Persist extends Persists = Persists.StoreOnly,
+> = Persist extends Persists.StoreOrMergeableStore
   ? Content<Schemas> | MergeableContent<Schemas>
-  : StoreType extends 2
+  : Persist extends Persists.MergeableStoreOnly
     ? MergeableContent<Schemas>
     : Content<Schemas>;
 
 /**
- * The PersistedChanges type
+ * The PersistedChanges type is a generic representation of changes made to the
+ * type of store being handled by a Persister.
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * export type PersistedChanges<Persist extends Persists = Persists.StoreOnly> =
+ *   Persist extends Persists.StoreOrMergeableStore
+ *     ? Changes | MergeableChanges
+ *     : Persist extends Persists.MergeableStoreOnly
+ *       ? MergeableChanges
+ *       : Changes;
+ * ```
+ *
+ * Using the values of the Persists enum, the generic parameter indicates
+ * whether the Persister is handling changes for a regular Store (the Changes
+ * type), a MergeableStore (the MergeableChanges type), or either (the union of
+ * the two).
+ * @category Mergeable
+ * @since v5.0.0
  */
 export type PersistedChanges<
   Schemas extends OptionalSchemas,
-  StoreType extends StoreTypes = 1,
-> = StoreType extends 3
+  Persist extends Persists = Persists.StoreOnly,
+> = Persist extends Persists.StoreOrMergeableStore
   ? Changes<Schemas> | MergeableChanges<Schemas>
-  : StoreType extends 2
+  : Persist extends Persists.MergeableStoreOnly
     ? MergeableChanges<Schemas>
     : Changes<Schemas>;
 
 /**
- * A PersisterListener is a callback that lets a Persister inform the Store that
- * a change has happened to the underlying data.
+ * A PersisterListener is a generic representation of the callback that lets a
+ * Persister inform the store that a change has happened to the underlying data.
  *
  * This has schema-based typing. The following is a simplified representation:
  *
  * ```ts override
- * export type PersisterListener<StoreType extends StoreTypes = 1> = (
- *   content?: PersistedContent<StoreType>,
- *   changes?: PersistedChanges<StoreType>,
+ * export type PersisterListener<Persist extends Persists = Persists.StoreOnly> = (
+ *   content?: PersistedContent<Persist>,
+ *   changes?: PersistedChanges<Persist>,
  * ) => void;
  * ```
  *
+ * Using the values of the Persists enum, the generic parameter indicates
+ * whether the Persister is handling content and changes from a regular Store, a
+ * MergeableStore, or either.
+ *
  * If the listener is called with the `changes` parameter, it will be used to
  * make an incremental change to the Store. If not, but the `content` parameter
  * is available, that will be used to make a wholesale change to the Store. If
  * neither are present, the content will be loaded using the Persister's load
- * method. Prior to v5.0, these parameters were callbacks.
+ * method. Prior to v5.0, these parameters were callbacks and the overall type
+ * was non-generic.
  * @param content If provided, this is a Content object from the the Persister
  * that will be used to immediately wholesale update the Store.
  * @param changes If provided, this is a Changes object from the the Persister
@@ -125,18 +217,17 @@ export type PersistedChanges<
  */
 export type PersisterListener<
   Schemas extends OptionalSchemas,
-  StoreType extends StoreTypes = 1,
+  Persist extends Persists = Persists.StoreOnly,
 > = (
-  content?: PersistedContent<Schemas, StoreType>,
-  changes?: PersistedChanges<Schemas, StoreType>,
+  content?: PersistedContent<Schemas, Persist>,
+  changes?: PersistedChanges<Schemas, Persist>,
 ) => void;
 
 /**
  * The PersisterStats type describes the number of times a Persister object has
  * loaded or saved data.
  *
- * A PersisterStats object is returned from the getStats method, and is only
- * populated in a debug build.
+ * A PersisterStats object is returned from the getStats method.
  * @category Development
  */
 export type PersisterStats = {
@@ -232,7 +323,7 @@ export type DatabasePersisterConfig<Schemas extends OptionalSchemas> =
  * called `_id`, and one called `store`. (These column names can be changed
  * using the `rowIdColumnName` and `storeColumnName` settings). The Persister
  * will place a single row in this table with `_` in the `_id` column, and the
- * JSON serialization in the `store` column, something like:
+ * JSON serialization in the `store` column, something like the following.
  *
  * ```
  * > SELECT * FROM tinybase;
@@ -294,6 +385,11 @@ export type DpcJson = {
  * The DpcTabular type describes the configuration of a database-oriented
  * Persister that is operating in tabular mapping mode.
  *
+ * This configuration can only be used when the Persister is persisting a
+ * regular Store. For those database-oriented Persister types that support
+ * MergeableStore data, you will need to use JSON-serialization, es described
+ * in the DpcJson section.
+ *
  * It is important to note that both the tabular mapping in ('save') and out
  * ('load') of an underlying database are disabled by default. This is to ensure
  * that if you pass in an existing populated database you don't run the
@@ -307,7 +403,7 @@ export type DpcJson = {
  *
  * Note that if you are planning to both load from and save to a database, it is
  * important to make sure that the load and save table mappings are symmetrical.
- * For example:
+ * For example, consider the following.
  *
  * ```js
  * import type {DatabasePersisterConfig} from 'tinybase';
@@ -588,8 +684,8 @@ export type DpcTabularSave<Schema extends OptionalTablesSchema> = {
          */
         deleteEmptyColumns?: boolean;
         /**
-         * Whether tables in the database will be removed if the Store Table
-         * is empty, defaulting to false.
+         * Whether tables in the database will be removed if the Store Table is
+         * empty, defaulting to false.
          */
         deleteEmptyTable?: boolean;
       }
@@ -645,15 +741,22 @@ export type DpcTabularValues = {
  * A Persister object lets you save and load Store data to and from different
  * locations, or underlying storage types.
  *
- * This is useful for preserving Store data between browser sessions or reloads,
- * saving or loading browser state to or from a server, or saving Store data to
- * disk in a environment with filesystem access.
+ * This is useful for preserving Store or MergeableStore data between browser
+ * sessions or reloads, saving or loading browser state to or from a server, or
+ * saving Store data to disk in a environment with filesystem access.
  *
  * Creating a Persister depends on the choice of underlying storage where the
  * data is to be stored. Options include the createSessionPersister function,
  * the createLocalPersister function, the createRemotePersister function, and
- * the createFilePersister function. The createCustomPersister function can also
- * be used to easily create a fully customized way to save and load Store data.
+ * the createFilePersister function, as just simple examples. The
+ * createCustomPersister function can also be used to easily create a fully
+ * customized way to save and load Store data.
+ *
+ * Using the values of the Persists enum, the generic parameter to the Persister
+ * indicates whether it can handle a regular Store, a MergeableStore, or either.
+ * Consult the table in the overall persisters module documentation to see
+ * current support for each. The different levels of support are also described
+ * for each of the types of Persister themselves.
  *
  * A Persister lets you explicit save or load data, with the save method and the
  * load method respectively. These methods are both asynchronous (since the
@@ -751,7 +854,7 @@ export type DpcTabularValues = {
  */
 export interface Persister<
   in out Schemas extends OptionalSchemas,
-  StoreType extends StoreTypes = 1,
+  Persist extends Persists = Persists.StoreOnly,
 > {
   /**
    * The load method gets persisted data from storage, and loads it into the
@@ -1155,9 +1258,9 @@ export interface Persister<
   schedule(...actions: Promise<any>[]): Promise<this>;
 
   /**
-   * The getStore method returns a reference to the underlying Store that is
-   * backing this Persister object.
-   * @returns A reference to the Store.
+   * The getStore method returns a reference to the underlying Store or
+   * MergeableStore that is backing this Persister object.
+   * @returns A reference to the Store or MergeableStore.
    * @example
    * This example creates a Persister object against a newly-created Store and
    * then gets its reference in order to update its data.
@@ -1165,7 +1268,7 @@ export interface Persister<
    * This has schema-based typing. The following is a simplified representation:
    *
    * ```ts override
-   * getStore(): PersistedStore<StoreType>;
+   * getStore(): PersistedStore<Persist>;
    * ```
    *
    * ```js
@@ -1184,7 +1287,7 @@ export interface Persister<
    * ```
    * @category Getter
    */
-  getStore(): PersistedStore<Schemas, StoreType>;
+  getStore(): PersistedStore<Schemas, Persist>;
 
   /**
    * The destroy method should be called when this Persister object is no longer
@@ -1226,10 +1329,8 @@ export interface Persister<
    * The PersisterStats object contains a count of the number of times the
    * Persister has loaded and saved data.
    *
-   * The statistics are only populated in a debug build: production builds
-   * return an empty object. The method is intended to be used during
-   * development to ensure your persistence layer is acting as expected, for
-   * example.
+   * The method is intended to be used during development to ensure your
+   * persistence layer is acting as expected, for example.
    * @returns A PersisterStats object containing Persister load and save
    * statistics.
    * @example
@@ -1276,21 +1377,21 @@ export interface Persister<
  * ```ts override
  * createCustomPersister<
  *   ListeningHandle,
- *   StoreType extends StoreTypes = 1,
+ *   Persist extends Persists = Persists.StoreOnly,
  * >(
- *   store: PersistedStore<StoreType>,
- *   getPersisted: () => Promise<PersistedContent<StoreType> | undefined>,
+ *   store: PersistedStore<Persist>,
+ *   getPersisted: () => Promise<PersistedContent<Persist> | undefined>,
  *   setPersisted: (
- *     getContent: () => PersistedContent<StoreType>,
- *     changes?: PersistedChanges<StoreType>,
+ *     getContent: () => PersistedContent<Persist>,
+ *     changes?: PersistedChanges<Persist>,
  *   ) => Promise<void>,
  *   addPersisterListener: (
- *     listener: PersisterListener<StoreType>,
+ *     listener: PersisterListener<Persist>,
  *   ) => ListeningHandle,
  *   delPersisterListener: (listeningHandle: ListeningHandle) => void,
  *   onIgnoredError?: (error: any) => void,
- *   supportedStoreType?: StoreType,
- * ): Persister<StoreType>;
+ *   persist?: Persist,
+ * ): Persister<Persist>;
  * ```
  *
  * As well as providing a reference to the Store to persist, you must provide
@@ -1328,41 +1429,43 @@ export interface Persister<
  * @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, since v4.0.4.
- * @param supportedStoreType Since v5.0, an optional integer to indicate which
- * types of Store are supported by this Persister: `1` indicates only a regular
- * Store is supported, `2` indicates only a MergeableStore is supported, and `3`
- * indicates that both Store and MergeableStore are supported.
+ * @param persist Since v5.0, an optional integer from the Persists enum to
+ * indicate which types of Store are supported by this Persister: `1` indicates
+ * only a regular Store is supported, `2` indicates only a MergeableStore is
+ * supported, and `3` indicates that both Store and MergeableStore are
+ * supported.
  * @returns A reference to the new Persister object.
  * @example
- * This example creates a custom Persister object and persists the Store to a
- * local string called `storeJson` and which would automatically load by polling
- * for changes every second.
+ * This example creates a custom Persister object and persists a Store to a
+ * local string called `persistedJson` and which would automatically load by
+ * polling for changes every second. It implicitly supports only a regular
+ * Store.
  *
  * ```js
  * import {createCustomPersister, createStore} from 'tinybase';
  *
  * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
- * let storeJson;
+ * let persistedJson;
  *
  * const persister = createCustomPersister(
  *   store,
  *   async () => {
  *     // getPersisted
- *     return JSON.parse(storeJson);
+ *     return JSON.parse(persistedJson);
  *   },
  *   async (getContent) => {
  *     // setPersisted
- *     storeJson = JSON.stringify(getContent());
+ *     persistedJson = JSON.stringify(getContent());
  *   },
  *   (listener) => setInterval(listener, 1000),
  *   (interval) => clearInterval(interval),
  * );
  *
  * await persister.save();
- * console.log(storeJson);
+ * console.log(persistedJson);
  * // -> '[{"pets":{"fido":{"species":"dog"}}},{}]'
  *
- * storeJson = '[{"pets":{"fido":{"species":"dog","color":"brown"}}},{}]';
+ * persistedJson = '[{"pets":{"fido":{"species":"dog","color":"brown"}}},{}]';
  * await persister.load();
  *
  * console.log(store.getTables());
@@ -1370,23 +1473,92 @@ export interface Persister<
  *
  * persister.destroy();
  * ```
+ * @example
+ * This example demonstrates a Persister creation function which returns a
+ * Persister. This can persists a store to a local string called `persistedJson`
+ * and which would automatically load by polling for changes every second.
+ * It emits warnings to the console and explicitly supports either a Store or a
+ * MergeableStore.
+ *
+ * ```js
+ * import {
+ *   Persists,
+ *   createCustomPersister,
+ *   createMergeableStore,
+ *   createStore,
+ * } from 'tinybase';
+ *
+ * let persistedJson;
+ * const createJsonPersister = (storeOrMergeableStore) =>
+ *   createCustomPersister(
+ *     storeOrMergeableStore,
+ *     async () => {
+ *       // getPersisted
+ *       return JSON.parse(persistedJson);
+ *     },
+ *     async (getContent) => {
+ *       // setPersisted
+ *       persistedJson = JSON.stringify(getContent());
+ *     },
+ *     (listener) => setInterval(listener, 1000),
+ *     (interval) => clearInterval(interval),
+ *     console.warn,
+ *     Persists.StoreOrMergeableStore,
+ *   );
+ *
+ * const store = createStore();
+ * store.setTables({pets: {fido: {species: 'dog'}}});
+ * const storePersister = createJsonPersister(store);
+ * await storePersister.save();
+ * console.log(persistedJson);
+ * // -> '[{"pets":{"fido":{"species":"dog"}}},{}]'
+ * storePersister.destroy();
+ *
+ * const mergeableStore = createMergeableStore('mergeableStore1'); // !resetHlc
+ * mergeableStore.setTables({pets: {fido: {species: 'dog'}}});
+ * const mergeableStorePersister = createJsonPersister(mergeableStore);
+ * await mergeableStorePersister.save();
+ * console.log(JSON.parse(persistedJson));
+ * // ->
+ * [
+ *   [
+ *     {
+ *       pets: [
+ *         {
+ *           fido: [
+ *             {species: ['dog', 'Nn1JUF-----Zjl0M', 4176151067]},
+ *             '',
+ *             2722999044,
+ *           ],
+ *         },
+ *         '',
+ *         3367164653,
+ *       ],
+ *     },
+ *     '',
+ *     30627183,
+ *   ],
+ *   [{}, '', 0],
+ * ];
+ * mergeableStorePersister.destroy();
+ * ```
  * @category Creation
  */
 export function createCustomPersister<
   Schemas extends OptionalSchemas,
   ListeningHandle,
-  StoreType extends StoreTypes = 1,
+  Persist extends Persists = Persists.StoreOnly,
 >(
-  store: PersistedStore<Schemas, StoreType>,
-  getPersisted: () => Promise<PersistedContent<Schemas, StoreType> | undefined>,
+  store: PersistedStore<Schemas, Persist>,
+  getPersisted: () => Promise<PersistedContent<Schemas, Persist> | undefined>,
   setPersisted: (
-    getContent: () => PersistedContent<Schemas, StoreType>,
-    changes?: PersistedChanges<Schemas, StoreType>,
+    getContent: () => PersistedContent<Schemas, Persist>,
+    changes?: PersistedChanges<Schemas, Persist>,
   ) => Promise<void>,
   addPersisterListener: (
-    listener: PersisterListener<Schemas, StoreType>,
+    listener: PersisterListener<Schemas, Persist>,
   ) => ListeningHandle,
   delPersisterListener: (listeningHandle: ListeningHandle) => void,
   onIgnoredError?: (error: any) => void,
-  supportedStoreType?: StoreType,
-): Persister<Schemas, StoreType>;
+  persist?: Persist,
+): Persister<Schemas, Persist>;

package/@types/queries/index.d.cts

@@ -335,7 +335,7 @@ export type ResultTableCellIdsListener = (
  * @param queries A reference to the Queries object that changed.
  * @param tableId The Id of the ResultTable that changed, which is also the
  * query Id.
- * @param count The number of ResultRow objects in the ResultTable
+ * @param count The number of ResultRow objects in the ResultTable.
  * @category Listener
  * @since v4.1.0
  */
@@ -545,8 +545,7 @@ export type ResultCellChange = [
  * The QueriesListenerStats type describes the number of listeners registered
  * with the Queries object, and can be used for debugging purposes.
  *
- * A QueriesListenerStats object is returned from the getListenerStats method,
- * and is only populated in a debug build.
+ * A QueriesListenerStats object is returned from the getListenerStats method.
  * @category Development
  * @since v2.0.0
  */
@@ -1938,7 +1937,6 @@ export interface Queries {
    * @param queryId The Id of a query.
    * @returns An object containing the entire data of the ResultTable of the
    * query.
-   * @returns The result of the query, structured as a ResultTable.
    * @example
    * This example creates a Queries object, a single query definition, and then
    * calls this method on it (as well as a non-existent definition) to get the
@@ -3020,8 +3018,8 @@ export interface Queries {
    * ResultCell Id being used to sort them, whether descending or not, and the
    * offset and limit of the number of Ids returned, for pagination purposes. It
    * also receives the sorted array of Ids itself, so that you can use them in
-   * the listener without the additional cost of an explicit call to
-   * getResultSortedRowIds
+   * the listener without the additional cost of an explicit call to the
+   * getResultSortedRowIds method.
    *
    * Such a listener is called when a ResultRow is added or removed, but also
    * when a value in the specified ResultCell (somewhere in the ResultTable) has
@@ -3573,10 +3571,8 @@ export interface Queries {
    * listeners registered with the Queries object, and is used for debugging
    * purposes.
    *
-   * The statistics are only populated in a debug build: production builds
-   * return an empty object. The method is intended to be used during
-   * development to ensure your application is not leaking listener
-   * registrations, for example.
+   * The method is intended to be used during development to ensure your
+   * application is not leaking listener registrations, for example.
    * @returns A QueriesListenerStats object containing Queries listener
    * statistics.
    * @example

package/@types/queries/index.d.ts

@@ -335,7 +335,7 @@ export type ResultTableCellIdsListener = (
  * @param queries A reference to the Queries object that changed.
  * @param tableId The Id of the ResultTable that changed, which is also the
  * query Id.
- * @param count The number of ResultRow objects in the ResultTable
+ * @param count The number of ResultRow objects in the ResultTable.
  * @category Listener
  * @since v4.1.0
  */
@@ -545,8 +545,7 @@ export type ResultCellChange = [
  * The QueriesListenerStats type describes the number of listeners registered
  * with the Queries object, and can be used for debugging purposes.
  *
- * A QueriesListenerStats object is returned from the getListenerStats method,
- * and is only populated in a debug build.
+ * A QueriesListenerStats object is returned from the getListenerStats method.
  * @category Development
  * @since v2.0.0
  */
@@ -1938,7 +1937,6 @@ export interface Queries {
    * @param queryId The Id of a query.
    * @returns An object containing the entire data of the ResultTable of the
    * query.
-   * @returns The result of the query, structured as a ResultTable.
    * @example
    * This example creates a Queries object, a single query definition, and then
    * calls this method on it (as well as a non-existent definition) to get the
@@ -3020,8 +3018,8 @@ export interface Queries {
    * ResultCell Id being used to sort them, whether descending or not, and the
    * offset and limit of the number of Ids returned, for pagination purposes. It
    * also receives the sorted array of Ids itself, so that you can use them in
-   * the listener without the additional cost of an explicit call to
-   * getResultSortedRowIds
+   * the listener without the additional cost of an explicit call to the
+   * getResultSortedRowIds method.
    *
    * Such a listener is called when a ResultRow is added or removed, but also
    * when a value in the specified ResultCell (somewhere in the ResultTable) has
@@ -3573,10 +3571,8 @@ export interface Queries {
    * listeners registered with the Queries object, and is used for debugging
    * purposes.
    *
-   * The statistics are only populated in a debug build: production builds
-   * return an empty object. The method is intended to be used during
-   * development to ensure your application is not leaking listener
-   * registrations, for example.
+   * The method is intended to be used during development to ensure your
+   * application is not leaking listener registrations, for example.
    * @returns A QueriesListenerStats object containing Queries listener
    * statistics.
    * @example