tinybase 7.0.0-beta.1 → 7.0.0-beta.3

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

@@ -32,8 +32,7 @@ import type {DatabasePersisterConfig, Persister, Persists} from '../index.d.ts';
  * @category Persister
  * @since v4.5.0
  */
-export interface ExpoSqlitePersister
-  extends Persister<Persists.StoreOrMergeableStore> {
+export interface ExpoSqlitePersister extends Persister<Persists.StoreOrMergeableStore> {
   /**
    * The getDb method returns a reference to the database instance the Store is
    * being persisted to.
@@ -87,6 +86,10 @@ export interface ExpoSqlitePersister
  *
  * See the documentation for the DpcJson and DpcTabular types for more
  * information on how both of those modes can be configured.
+ *
+ * Note: When using tabular mode, SQL NULL values are loaded as TinyBase null
+ * values, making tables dense (every Row has every Cell). See the Database
+ * Persistence guide for details.
  * @param store The Store or MergeableStore to persist.
  * @param db The database instance that was returned from
  * `SQLite.openDatabase(...)`.

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

@@ -39,8 +39,9 @@ import type {
  * @category Persister
  * @since v4.5.0
  */
-export interface ExpoSqlitePersister<Schemas extends OptionalSchemas>
-  extends Persister<Schemas, Persists.StoreOrMergeableStore> {
+export interface ExpoSqlitePersister<
+  Schemas extends OptionalSchemas,
+> extends Persister<Schemas, Persists.StoreOrMergeableStore> {
   /**
    * The getDb method returns a reference to the database instance the Store is
    * being persisted to.
@@ -106,6 +107,10 @@ export interface ExpoSqlitePersister<Schemas extends OptionalSchemas>
  *
  * See the documentation for the DpcJson and DpcTabular types for more
  * information on how both of those modes can be configured.
+ *
+ * Note: When using tabular mode, SQL NULL values are loaded as TinyBase null
+ * values, making tables dense (every Row has every Cell). See the Database
+ * Persistence guide for details.
  * @param store The Store or MergeableStore to persist.
  * @param db The database instance that was returned from
  * `SQLite.openDatabase(...)`.

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

@@ -23,8 +23,7 @@ import type {Persister, Persists} from '../index.d.ts';
  * @category Persister
  * @since v4.3.14
  */
-export interface FilePersister
-  extends Persister<Persists.StoreOrMergeableStore> {
+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.ts

@@ -26,8 +26,9 @@ import type {Persister, Persists} from '../../with-schemas/index.d.ts';
  * @category Persister
  * @since v4.3.14
  */
-export interface FilePersister<Schemas extends OptionalSchemas>
-  extends Persister<Schemas, Persists.StoreOrMergeableStore> {
+export interface FilePersister<
+  Schemas extends OptionalSchemas,
+> 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-indexed-db/with-schemas/index.d.ts

@@ -25,8 +25,9 @@ import type {Persister} from '../../with-schemas/index.d.ts';
  * @category Persister
  * @since v4.3.14
  */
-export interface IndexedDbPersister<Schemas extends OptionalSchemas>
-  extends Persister<Schemas> {
+export interface IndexedDbPersister<
+  Schemas extends OptionalSchemas,
+> extends Persister<Schemas> {
   /**
    * The getDbName method returns the unique key of the IndexedDB the Store is
    * being persisted to.

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

@@ -74,6 +74,10 @@ export interface LibSqlPersister extends Persister {
  *
  * See the documentation for the DpcJson and DpcTabular types for more
  * information on how both of those modes can be configured.
+ *
+ * Note: When using tabular mode, SQL NULL values are loaded as TinyBase null
+ * values, making tables dense (every Row has every Cell). See the Database
+ * Persistence guide for details.
  * @param store The Store to persist.
  * @param client The database client that was returned from `createClient(...)`.
  * @param configOrStoreTableName A DatabasePersisterConfig to configure the

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

@@ -30,8 +30,9 @@ import type {
  * @category Persister
  * @since v4.7.0
  */
-export interface LibSqlPersister<Schemas extends OptionalSchemas>
-  extends Persister<Schemas> {
+export interface LibSqlPersister<
+  Schemas extends OptionalSchemas,
+> extends Persister<Schemas> {
   /**
    * The getClient method returns a reference to the database client the Store
    * is being persisted to.
@@ -93,6 +94,10 @@ export interface LibSqlPersister<Schemas extends OptionalSchemas>
  *
  * See the documentation for the DpcJson and DpcTabular types for more
  * information on how both of those modes can be configured.
+ *
+ * Note: When using tabular mode, SQL NULL values are loaded as TinyBase null
+ * values, making tables dense (every Row has every Cell). See the Database
+ * Persistence guide for details.
  * @param store The Store to persist.
  * @param client The database client that was returned from `createClient(...)`.
  * @param configOrStoreTableName A DatabasePersisterConfig to configure the

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

@@ -38,8 +38,9 @@ import type {Persister} from '../../with-schemas/index.d.ts';
  * @category Persister
  * @since v4.3.14
  */
-export interface PartyKitPersister<Schemas extends OptionalSchemas>
-  extends Persister<Schemas> {
+export interface PartyKitPersister<
+  Schemas extends OptionalSchemas,
+> extends Persister<Schemas> {
   /**
    * The getConnection method returns the PartySocket the Store is being
    * persisted to.

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

@@ -24,8 +24,7 @@ import type {DatabasePersisterConfig, Persister, Persists} from '../index.d.ts';
  * @category Persister
  * @since 5.2.0
  */
-export interface PglitePersister
-  extends Persister<Persists.StoreOrMergeableStore> {
+export interface PglitePersister extends Persister<Persists.StoreOrMergeableStore> {
   /**
    * The getPglite method returns a reference to the database connection the
    * Store is being persisted to.
@@ -82,7 +81,11 @@ export interface PglitePersister
  * See the documentation for the DpcJson and DpcTabular types for more
  * information on how both of those modes can be configured.
  *
- * This method is asynchronous because it will await the creation of dedicated
+ * Note: When using tabular mode, SQL NULL values are loaded as TinyBase null
+ * values, making tables dense (every Row has every Cell). See the Database
+ * Persistence guide for details.
+ *
+ * This method is asynchronous because it will await the completion of the
  * new connections to the database. You will need to `await` a call to this
  * function or handle the return type natively as a Promise.
  * @param store The Store or MergeableStore to persist.
@@ -166,6 +169,7 @@ export interface PglitePersister
  * await pglite.close();
  * ```
  * @category Creation
+ * @essential Persisting stores
  * @since 5.2.0
  */
 export function createPglitePersister(

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

@@ -31,8 +31,9 @@ import type {
  * @category Persister
  * @since 5.2.0
  */
-export interface PglitePersister<Schemas extends OptionalSchemas>
-  extends Persister<Schemas, Persists.StoreOrMergeableStore> {
+export interface PglitePersister<
+  Schemas extends OptionalSchemas,
+> extends Persister<Schemas, Persists.StoreOrMergeableStore> {
   /**
    * The getPglite method returns a reference to the database connection the
    * Store is being persisted to.
@@ -101,7 +102,11 @@ export interface PglitePersister<Schemas extends OptionalSchemas>
  * See the documentation for the DpcJson and DpcTabular types for more
  * information on how both of those modes can be configured.
  *
- * This method is asynchronous because it will await the creation of dedicated
+ * Note: When using tabular mode, SQL NULL values are loaded as TinyBase null
+ * values, making tables dense (every Row has every Cell). See the Database
+ * Persistence guide for details.
+ *
+ * This method is asynchronous because it will await the completion of the
  * new connections to the database. You will need to `await` a call to this
  * function or handle the return type natively as a Promise.
  * @param store The Store or MergeableStore to persist.
@@ -185,6 +190,7 @@ export interface PglitePersister<Schemas extends OptionalSchemas>
  * await pglite.close();
  * ```
  * @category Creation
+ * @essential Persisting stores
  * @since 5.2.0
  */
 export function createPglitePersister<Schemas extends OptionalSchemas>(

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

@@ -24,8 +24,7 @@ import type {DatabasePersisterConfig, Persister, Persists} from '../index.d.ts';
  * @category Persister
  * @since 5.2.0
  */
-export interface PostgresPersister
-  extends Persister<Persists.StoreOrMergeableStore> {
+export interface PostgresPersister extends Persister<Persists.StoreOrMergeableStore> {
   /**
    * The getSql method returns a reference to the database connection the Store
    * is being persisted to.
@@ -78,6 +77,10 @@ export interface PostgresPersister
  * See the documentation for the DpcJson and DpcTabular types for more
  * information on how both of those modes can be configured.
  *
+ * Note: When using tabular mode, SQL NULL values are loaded as TinyBase null
+ * values, making tables dense (every Row has every Cell). See the Database
+ * Persistence guide for details.
+ *
  * This method is asynchronous because it will await the creation of dedicated
  * new connections to the database. You will need to `await` a call to this
  * function or handle the return type natively as a Promise.

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

@@ -31,8 +31,9 @@ import type {
  * @category Persister
  * @since 5.2.0
  */
-export interface PostgresPersister<Schemas extends OptionalSchemas>
-  extends Persister<Schemas, Persists.StoreOrMergeableStore> {
+export interface PostgresPersister<
+  Schemas extends OptionalSchemas,
+> extends Persister<Schemas, Persists.StoreOrMergeableStore> {
   /**
    * The getSql method returns a reference to the database connection the Store
    * is being persisted to.
@@ -97,6 +98,10 @@ export interface PostgresPersister<Schemas extends OptionalSchemas>
  * See the documentation for the DpcJson and DpcTabular types for more
  * information on how both of those modes can be configured.
  *
+ * Note: When using tabular mode, SQL NULL values are loaded as TinyBase null
+ * values, making tables dense (every Row has every Cell). See the Database
+ * Persistence guide for details.
+ *
  * This method is asynchronous because it will await the creation of dedicated
  * new connections to the database. You will need to `await` a call to this
  * function or handle the return type natively as a Promise.

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

@@ -76,6 +76,10 @@ export interface PowerSyncPersister extends Persister {
  *
  * See the documentation for the DpcJson and DpcTabular types for more
  * information on how both of those modes can be configured.
+ *
+ * Note: When using tabular mode, SQL NULL values are loaded as TinyBase null
+ * values, making tables dense (every Row has every Cell). See the Database
+ * Persistence guide for details.
  * @param store The Store to persist.
  * @param powerSync The PowerSync instance.
  * @param configOrStoreTableName A DatabasePersisterConfig to configure the

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

@@ -31,8 +31,9 @@ import type {
  * @category Persister
  * @since v4.8.0
  */
-export interface PowerSyncPersister<Schemas extends OptionalSchemas>
-  extends Persister<Schemas> {
+export interface PowerSyncPersister<
+  Schemas extends OptionalSchemas,
+> extends Persister<Schemas> {
   /**
    * The getPowerSync method returns a reference to the PowerSync instance the
    * Store is being persisted to.
@@ -95,6 +96,10 @@ export interface PowerSyncPersister<Schemas extends OptionalSchemas>
  *
  * See the documentation for the DpcJson and DpcTabular types for more
  * information on how both of those modes can be configured.
+ *
+ * Note: When using tabular mode, SQL NULL values are loaded as TinyBase null
+ * values, making tables dense (every Row has every Cell). See the Database
+ * Persistence guide for details.
  * @param store The Store to persist.
  * @param powerSync The PowerSync instance.
  * @param configOrStoreTableName A DatabasePersisterConfig to configure the

package/@types/persisters/persister-react-native-mmkv/index.d.ts

@@ -0,0 +1,117 @@
+/**
+ * The persister-react-native-mmkv module of the TinyBase project lets you save
+ * and load Store data to and from a MMKV storage using the
+ * [`react-native-mmkv`](https://github.com/mrousavy/react-native-mmkv) module
+ * (in an appropriate React Native environment).
+ * @see Database Persistence guide
+ * @packageDocumentation
+ * @module persister-react-native-mmkv
+ * @since v6.5.0
+ */
+import type {MMKV} from 'react-native-mmkv';
+import type {MergeableStore} from '../../mergeable-store/index.d.ts';
+import type {Store} from '../../store/index.d.ts';
+import type {Persister, Persists} from '../index.d.ts';
+
+/**
+ * The ReactNativeMmkvPersister interface represents a Persister that lets you
+ * save and load Store data to and from a `react-native-mmkv` storage.
+ *
+ * You should use the createReactNativeMmkvPersister function to create a
+ * ReactNativeMmkvPersister object.
+ *
+ * It is a minor extension to the Persister interface and simply provides an
+ * extra getStorageName method for accessing the unique key of the storage
+ * location the Store is being persisted to.
+ * @category Persister
+ * @since v6.5.0
+ */
+export interface ReactNativeMmkvPersister extends Persister<Persists.StoreOrMergeableStore> {
+  /**
+ * The getStorageName method returns the unique key of the storage location the
+ * Store is being persisted to.
+ * @returns The unique key of the storage location.
+ * @example
+ * This example creates a Persister object against a newly-created Store and
+ * then gets the unique key of the storage location back out again.
+ *
+ * ```js yolo
+ * import {createMMKV} from 'react-native-mmkv';
+ * import {createStore} from 'tinybase';
+ * import {createReactNativeMmkvPersister} from 'tinybase/persisters/persister-react-native-mmkv';
+ *
+ * const storage = createMMKV();
+ * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
+ * const persister = createReactNativeMmkvPersister(
+ *   store,
+ *   storage,
+ *   'my_tinybase',
+ * );
+ * console.log(persister.getStorageName() == 'my_tinybase');
+ * // -> true
+ *
+ * await persister.destroy();
+ * ```
+ * @category Getter
+ * @since v6.5.0
+ */
+  getStorageName(): string;
+}
+
+/**
+ * The createReactNativeMmkvPersister function creates a
+ * ReactNativeMmkvPersister object that can persist the Store to a local
+ * `react-native-mmkv` storage.
+ *
+ * A ReactNativeMmkvPersister supports both regular Store and MergeableStore
+ * objects.
+ *
+ * As well as providing a reference to the Store to persist, you must provide a
+ * `storage` parameter which identifies the MMKV storage instance.
+ *
+ * The third argument is a `storageName` string that configures which key to use
+ * for the storage key.
+ * @param store The Store or MergeableStore to persist.
+ * @param storage The MMKV storage instance.
+ * @param storageName The unique key to identify the storage location.
+ * @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 ReactNativeMmkvPersister object.
+ * @example
+ * This example creates a ReactNativeMmkvPersister object and persists the
+ * Store to a MMKV storage instance as a JSON serialization into the
+ * `my_tinybase` key. It makes a change to the storage directly and then
+ * reloads it back into the Store.
+ *
+ * ```js yolo
+ * import {createMMKV} from 'react-native-mmkv';
+ * import {createStore} from 'tinybase';
+ * import {createReactNativeMmkvPersister} from 'tinybase/persisters/persister-react-native-mmkv';
+ *
+ * const storage = createMMKV();
+ * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
+ * const persister = createReactNativeMmkvPersister(
+ *   store,
+ *   storage,
+ *   'my_tinybase',
+ * );
+ *
+ * await persister.save();
+ * // Store will be saved to the MMKV storage.
+ *
+ * console.log(storage.getString('my_tinybase'));
+ * // -> '[{"pets":{"fido":{"species":"dog"}}},{}]'
+ *
+ * await persister.destroy();
+ * storage.delete('my_tinybase');
+ * ```
+ * @category Creation
+ * @since v6.5.0
+ */
+export function createReactNativeMmkvPersister(
+  store: Store | MergeableStore,
+  storage: MMKV,
+  storageName?: string,
+  onIgnoredError?: (error: any) => void,
+): ReactNativeMmkvPersister;

package/@types/persisters/persister-react-native-mmkv/with-schemas/index.d.ts

@@ -0,0 +1,133 @@
+/**
+ * The persister-react-native-mmkv module of the TinyBase project lets you save
+ * and load Store data to and from a MMKV storage using the
+ * [`react-native-mmkv`](https://github.com/mrousavy/react-native-mmkv) module
+ * (in an appropriate React Native environment).
+ * @see Database Persistence guide
+ * @packageDocumentation
+ * @module persister-react-native-mmkv
+ * @since v6.5.0
+ */
+import type {MMKV} from 'react-native-mmkv';
+import type {MergeableStore} from '../../../mergeable-store/with-schemas/index.d.ts';
+import type {
+  OptionalSchemas,
+  Store,
+} from '../../../store/with-schemas/index.d.ts';
+import type {Persister, Persists} from '../../with-schemas/index.d.ts';
+
+/**
+ * The ReactNativeMmkvPersister interface represents a Persister that lets you
+ * save and load Store data to and from a `react-native-mmkv` storage.
+ *
+ * You should use the createReactNativeMmkvPersister function to create a
+ * ReactNativeMmkvPersister object.
+ *
+ * It is a minor extension to the Persister interface and simply provides an
+ * extra getStorageName method for accessing the unique key of the storage
+ * location the Store is being persisted to.
+ * @category Persister
+ * @since v6.5.0
+ */
+export interface ReactNativeMmkvPersister<
+  Schemas extends OptionalSchemas,
+> extends Persister<Schemas, Persists.StoreOrMergeableStore> {
+  /**
+ * The getStorageName method returns the unique key of the storage location the
+ * Store is being persisted to.
+ * @returns The unique key of the storage location.
+ * @example
+ * This example creates a Persister object against a newly-created Store and
+ * then gets the unique key of the storage location back out again.
+ *
+ * ```js yolo
+ * import {createMMKV} from 'react-native-mmkv';
+ * import {createStore} from 'tinybase';
+ * import {createReactNativeMmkvPersister} from 'tinybase/persisters/persister-react-native-mmkv';
+ *
+ * const storage = createMMKV();
+ * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
+ * const persister = createReactNativeMmkvPersister(
+ *   store,
+ *   storage,
+ *   'my_tinybase',
+ * );
+ * console.log(persister.getStorageName() == 'my_tinybase');
+ * // -> true
+ *
+ * await persister.destroy();
+ * ```
+ * @category Getter
+ * @since v6.5.0
+ */
+  getStorageName(): string;
+}
+
+/**
+ * The createReactNativeMmkvPersister function creates a
+ * ReactNativeMmkvPersister object that can persist the Store to a local
+ * `react-native-mmkv` storage.
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * createReactNativeMmkvPersister(
+ *   store: Store | MergeableStore,
+ *   storage: MMKV,
+ *   storageName?: string,
+ *   onIgnoredError?: (error: any) => void,
+ * ): ReactNativeMmkvPersister;
+ * ```
+ *
+ * A ReactNativeMmkvPersister supports both regular Store and MergeableStore
+ * objects.
+ *
+ * As well as providing a reference to the Store to persist, you must provide a
+ * `storage` parameter which identifies the MMKV storage instance.
+ *
+ * The third argument is a `storageName` string that configures which key to use
+ * for the storage key.
+ * @param store The Store or MergeableStore to persist.
+ * @param storage The MMKV storage instance.
+ * @param storageName The unique key to identify the storage location.
+ * @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 ReactNativeMmkvPersister object.
+ * @example
+ * This example creates a ReactNativeMmkvPersister object and persists the
+ * Store to a MMKV storage instance as a JSON serialization into the
+ * `my_tinybase` key. It makes a change to the storage directly and then
+ * reloads it back into the Store.
+ *
+ * ```js yolo
+ * import {createMMKV} from 'react-native-mmkv';
+ * import {createStore} from 'tinybase';
+ * import {createReactNativeMmkvPersister} from 'tinybase/persisters/persister-react-native-mmkv';
+ *
+ * const storage = createMMKV();
+ * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
+ * const persister = createReactNativeMmkvPersister(
+ *   store,
+ *   storage,
+ *   'my_tinybase',
+ * );
+ *
+ * await persister.save();
+ * // Store will be saved to the MMKV storage.
+ *
+ * console.log(storage.getString('my_tinybase'));
+ * // -> '[{"pets":{"fido":{"species":"dog"}}},{}]'
+ *
+ * await persister.destroy();
+ * storage.delete('my_tinybase');
+ * ```
+ * @category Creation
+ * @since v6.5.0
+ */
+export function createReactNativeMmkvPersister<Schemas extends OptionalSchemas>(
+  store: Store<Schemas> | MergeableStore<Schemas>,
+  storage: MMKV,
+  storageName?: string,
+  onIgnoredError?: (error: any) => void,
+): ReactNativeMmkvPersister<Schemas>;