tinybase 5.0.0-beta.24 → 5.0.0-beta.26

package/@types/persisters/persister-file/index.d.cts

@@ -6,8 +6,8 @@
  * @module persister-file
  */
 
+import type {Persister, Persists} from '../index.d.cts';
 import type {MergeableStore} from '../../mergeable-store/index.d.cts';
-import type {Persister} from '../index.d.cts';
 import type {Store} from '../../store/index.d.cts';
 
 /**
@@ -21,7 +21,8 @@ import type {Store} from '../../store/index.d.cts';
  * @category Persister
  * @since v4.3.14
  */
-export interface FilePersister extends Persister<3> {
+export interface FilePersister
+  extends Persister<Persists.StoreOrMergeableStore> {
   /**
    * The getFilePath method returns the location of the local file the Store is
    * being persisted to.

package/@types/persisters/persister-file/index.d.ts

@@ -6,8 +6,8 @@
  * @module persister-file
  */
 
+import type {Persister, Persists} from '../index.d.ts';
 import type {MergeableStore} from '../../mergeable-store/index.d.ts';
-import type {Persister} from '../index.d.ts';
 import type {Store} from '../../store/index.d.ts';
 
 /**
@@ -21,7 +21,8 @@ import type {Store} from '../../store/index.d.ts';
  * @category Persister
  * @since v4.3.14
  */
-export interface FilePersister extends Persister<3> {
+export interface FilePersister
+  extends Persister<Persists.StoreOrMergeableStore> {
   /**
    * The getFilePath method returns the location of the local file the Store is
    * being persisted to.

package/@types/persisters/persister-file/with-schemas/index.d.cts

@@ -10,8 +10,8 @@ import type {
   OptionalSchemas,
   Store,
 } from '../../../store/with-schemas/index.d.cts';
+import type {Persister, Persists} from '../../with-schemas/index.d.cts';
 import type {MergeableStore} from '../../../mergeable-store/with-schemas/index.d.cts';
-import type {Persister} from '../../with-schemas/index.d.cts';
 
 /**
  * The FilePersister interface is a minor extension to the Persister interface.
@@ -25,7 +25,7 @@ import type {Persister} from '../../with-schemas/index.d.cts';
  * @since v4.3.14
  */
 export interface FilePersister<Schemas extends OptionalSchemas>
-  extends Persister<Schemas, 3> {
+  extends Persister<Schemas, Persists.StoreOrMergeableStore> {
   /**
    * The getFilePath method returns the location of the local file the Store is
    * being persisted to.

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

@@ -10,8 +10,8 @@ import type {
   OptionalSchemas,
   Store,
 } from '../../../store/with-schemas/index.d.ts';
+import type {Persister, Persists} from '../../with-schemas/index.d.ts';
 import type {MergeableStore} from '../../../mergeable-store/with-schemas/index.d.ts';
-import type {Persister} from '../../with-schemas/index.d.ts';
 
 /**
  * The FilePersister interface is a minor extension to the Persister interface.
@@ -25,7 +25,7 @@ import type {Persister} from '../../with-schemas/index.d.ts';
  * @since v4.3.14
  */
 export interface FilePersister<Schemas extends OptionalSchemas>
-  extends Persister<Schemas, 3> {
+  extends Persister<Schemas, Persists.StoreOrMergeableStore> {
   /**
    * The getFilePath method returns the location of the local file the Store is
    * being persisted to.

package/@types/persisters/persister-partykit-server/index.d.cts

@@ -88,7 +88,7 @@ export type TinyBasePartyKitServerConfig = {
   storagePrefix?: string;
   /**
    * An object containing the extra HTTP(S) headers returned to the client from
-   * this server. This defaults to the following three headers to allow CORS:
+   * this server. This defaults to the following three headers to allow CORS.
    *
    * ```
    * Access-Control-Allow-Origin: *
@@ -174,7 +174,7 @@ export class TinyBasePartyKitServer implements Server {
    *
    * 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:
+   * synchronization stays supported.
    *
    * ```js
    * import {TinyBasePartyKitServer} from 'tinybase/persisters/persister-partykit-server';
@@ -200,7 +200,7 @@ export class TinyBasePartyKitServer implements Server {
    *
    * 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:
+   * synchronization stays supported.
    *
    * ```js
    * import {TinyBasePartyKitServer} from 'tinybase/persisters/persister-partykit-server';

package/@types/persisters/persister-partykit-server/index.d.ts

@@ -88,7 +88,7 @@ export type TinyBasePartyKitServerConfig = {
   storagePrefix?: string;
   /**
    * An object containing the extra HTTP(S) headers returned to the client from
-   * this server. This defaults to the following three headers to allow CORS:
+   * this server. This defaults to the following three headers to allow CORS.
    *
    * ```
    * Access-Control-Allow-Origin: *
@@ -174,7 +174,7 @@ export class TinyBasePartyKitServer implements Server {
    *
    * 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:
+   * synchronization stays supported.
    *
    * ```js
    * import {TinyBasePartyKitServer} from 'tinybase/persisters/persister-partykit-server';
@@ -200,7 +200,7 @@ export class TinyBasePartyKitServer implements Server {
    *
    * 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:
+   * synchronization stays supported.
    *
    * ```js
    * import {TinyBasePartyKitServer} from 'tinybase/persisters/persister-partykit-server';

package/@types/persisters/persister-partykit-server/with-schemas/index.d.cts

@@ -85,7 +85,7 @@ export type TinyBasePartyKitServerConfig = {
   storagePrefix?: string;
   /**
    * An object containing the extra HTTP(S) headers returned to the client from
-   * this server. This defaults to the following three headers to allow CORS:
+   * this server. This defaults to the following three headers to allow CORS.
    *
    * ```
    * Access-Control-Allow-Origin: *
@@ -171,7 +171,7 @@ export class TinyBasePartyKitServer implements Server {
    *
    * 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:
+   * synchronization stays supported.
    *
    * ```js
    * import {TinyBasePartyKitServer} from 'tinybase/persisters/persister-partykit-server';
@@ -197,7 +197,7 @@ export class TinyBasePartyKitServer implements Server {
    *
    * 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:
+   * synchronization stays supported.
    *
    * ```js
    * import {TinyBasePartyKitServer} from 'tinybase/persisters/persister-partykit-server';

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

@@ -85,7 +85,7 @@ export type TinyBasePartyKitServerConfig = {
   storagePrefix?: string;
   /**
    * An object containing the extra HTTP(S) headers returned to the client from
-   * this server. This defaults to the following three headers to allow CORS:
+   * this server. This defaults to the following three headers to allow CORS.
    *
    * ```
    * Access-Control-Allow-Origin: *
@@ -171,7 +171,7 @@ export class TinyBasePartyKitServer implements Server {
    *
    * 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:
+   * synchronization stays supported.
    *
    * ```js
    * import {TinyBasePartyKitServer} from 'tinybase/persisters/persister-partykit-server';
@@ -197,7 +197,7 @@ export class TinyBasePartyKitServer implements Server {
    *
    * 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:
+   * synchronization stays supported.
    *
    * ```js
    * import {TinyBasePartyKitServer} from 'tinybase/persisters/persister-partykit-server';

package/@types/persisters/persister-sqlite-wasm/index.d.cts

@@ -8,7 +8,7 @@
  * @since v4.0.0
  */
 
-import type {DatabasePersisterConfig, Persister} from '../index.d.cts';
+import type {DatabasePersisterConfig, Persister, Persists} from '../index.d.cts';
 import type {MergeableStore} from '../../mergeable-store/index.d.cts';
 import type {Store} from '../../store/index.d.cts';
 
@@ -24,7 +24,8 @@ import type {Store} from '../../store/index.d.cts';
  * @category Persister
  * @since v4.3.14
  */
-export interface SqliteWasmPersister extends Persister<3> {
+export interface SqliteWasmPersister
+  extends Persister<Persists.StoreOrMergeableStore> {
   /**
    * The getDb method returns a reference to the database instance the Store is
    * being persisted to.

package/@types/persisters/persister-sqlite-wasm/index.d.ts

@@ -8,7 +8,7 @@
  * @since v4.0.0
  */
 
-import type {DatabasePersisterConfig, Persister} from '../index.d.ts';
+import type {DatabasePersisterConfig, Persister, Persists} from '../index.d.ts';
 import type {MergeableStore} from '../../mergeable-store/index.d.ts';
 import type {Store} from '../../store/index.d.ts';
 
@@ -24,7 +24,8 @@ import type {Store} from '../../store/index.d.ts';
  * @category Persister
  * @since v4.3.14
  */
-export interface SqliteWasmPersister extends Persister<3> {
+export interface SqliteWasmPersister
+  extends Persister<Persists.StoreOrMergeableStore> {
   /**
    * The getDb method returns a reference to the database instance the Store is
    * being persisted to.

package/@types/persisters/persister-sqlite-wasm/with-schemas/index.d.cts

@@ -11,6 +11,7 @@
 import type {
   DatabasePersisterConfig,
   Persister,
+  Persists,
 } from '../../with-schemas/index.d.cts';
 import type {
   OptionalSchemas,
@@ -31,7 +32,7 @@ import type {MergeableStore} from '../../../mergeable-store/with-schemas/index.d
  * @since v4.3.14
  */
 export interface SqliteWasmPersister<Schemas extends OptionalSchemas>
-  extends Persister<Schemas, 3> {
+  extends Persister<Schemas, Persists.StoreOrMergeableStore> {
   /**
    * The getDb method returns a reference to the database instance the Store is
    * being persisted to.

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

@@ -11,6 +11,7 @@
 import type {
   DatabasePersisterConfig,
   Persister,
+  Persists,
 } from '../../with-schemas/index.d.ts';
 import type {
   OptionalSchemas,
@@ -31,7 +32,7 @@ import type {MergeableStore} from '../../../mergeable-store/with-schemas/index.d
  * @since v4.3.14
  */
 export interface SqliteWasmPersister<Schemas extends OptionalSchemas>
-  extends Persister<Schemas, 3> {
+  extends Persister<Schemas, Persists.StoreOrMergeableStore> {
   /**
    * The getDb method returns a reference to the database instance the Store is
    * being persisted to.

package/@types/persisters/persister-sqlite3/index.d.cts

@@ -8,7 +8,7 @@
  * @since v4.0.0
  */
 
-import type {DatabasePersisterConfig, Persister} from '../index.d.cts';
+import type {DatabasePersisterConfig, Persister, Persists} from '../index.d.cts';
 import type {Database} from 'sqlite3';
 import type {MergeableStore} from '../../mergeable-store/index.d.cts';
 import type {Store} from '../../store/index.d.cts';
@@ -25,7 +25,8 @@ import type {Store} from '../../store/index.d.cts';
  * @category Persister
  * @since v4.3.14
  */
-export interface Sqlite3Persister extends Persister<3> {
+export interface Sqlite3Persister
+  extends Persister<Persists.StoreOrMergeableStore> {
   /**
    * The getDb method returns a reference to the database instance the Store is
    * being persisted to.

package/@types/persisters/persister-sqlite3/index.d.ts

@@ -8,7 +8,7 @@
  * @since v4.0.0
  */
 
-import type {DatabasePersisterConfig, Persister} from '../index.d.ts';
+import type {DatabasePersisterConfig, Persister, Persists} from '../index.d.ts';
 import type {Database} from 'sqlite3';
 import type {MergeableStore} from '../../mergeable-store/index.d.ts';
 import type {Store} from '../../store/index.d.ts';
@@ -25,7 +25,8 @@ import type {Store} from '../../store/index.d.ts';
  * @category Persister
  * @since v4.3.14
  */
-export interface Sqlite3Persister extends Persister<3> {
+export interface Sqlite3Persister
+  extends Persister<Persists.StoreOrMergeableStore> {
   /**
    * The getDb method returns a reference to the database instance the Store is
    * being persisted to.

package/@types/persisters/persister-sqlite3/with-schemas/index.d.cts

@@ -11,6 +11,7 @@
 import type {
   DatabasePersisterConfig,
   Persister,
+  Persists,
 } from '../../with-schemas/index.d.cts';
 import type {
   OptionalSchemas,
@@ -32,7 +33,7 @@ import type {MergeableStore} from '../../../mergeable-store/with-schemas/index.d
  * @since v4.3.14
  */
 export interface Sqlite3Persister<Schemas extends OptionalSchemas>
-  extends Persister<Schemas, 3> {
+  extends Persister<Schemas, Persists.StoreOrMergeableStore> {
   /**
    * The getDb method returns a reference to the database instance the Store is
    * being persisted to.

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

@@ -11,6 +11,7 @@
 import type {
   DatabasePersisterConfig,
   Persister,
+  Persists,
 } from '../../with-schemas/index.d.ts';
 import type {
   OptionalSchemas,
@@ -32,7 +33,7 @@ import type {MergeableStore} from '../../../mergeable-store/with-schemas/index.d
  * @since v4.3.14
  */
 export interface Sqlite3Persister<Schemas extends OptionalSchemas>
-  extends Persister<Schemas, 3> {
+  extends Persister<Schemas, Persists.StoreOrMergeableStore> {
   /**
    * The getDb method returns a reference to the database instance the Store is
    * being persisted to.

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

@@ -54,46 +54,66 @@ import type {
 import type {TableIdFromSchema} from '../../_internal/store/with-schemas/index.d.cts';
 
 /**
- * The StoreTypes type
+ * The Persists enum.
+ *
+ * This is used to indicate what types of Store a Persister can support.
+ * @category Mergeable
+ * @since v5.0.0
  */
-export type StoreTypes =
-  | 1 // Store only
-  | 2 // MergeableStore only
-  | 3; // Store and MergeableStore
+export const enum Persists {
+  /**
+   * The StoreOnly enum value.
+   */
+  StoreOnly = 1,
+  /**
+   * The MergeableStoreOnly enum value.
+   */
+  MergeableStoreOnly = 2,
+  /**
+   * The StoreOrMergeableStore enum value.
+   */
+  StoreOrMergeableStore = 3,
+}
 
 /**
- * The PersistedStore type
+ * The PersistedStore type.
+ * @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.
+ * @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.
+ * @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>;
 
@@ -104,9 +124,9 @@ export type PersistedChanges<
  * 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;
  * ```
  *
@@ -125,18 +145,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 +251,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;
@@ -307,7 +326,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';
@@ -751,7 +770,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
@@ -1165,7 +1184,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 +1203,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 +1245,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 +1293,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>;
+ *   persistable?: Persist,
+ * ): Persister<Persist>;
  * ```
  *
  * As well as providing a reference to the Store to persist, you must provide
@@ -1328,9 +1345,9 @@ 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`
+ * @param persistable 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.
  * @returns A reference to the new Persister object.
  * @example
@@ -1375,18 +1392,18 @@ export interface Persister<
 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>;
+  persistable?: Persist,
+): Persister<Schemas, Persist>;