tinybase 9.7.0-beta.0 → 9.7.0-beta.1

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

@@ -43,6 +43,7 @@ export * from '../persisters/persister-react-native-mmkv/index.d.ts';
 export * from '../persisters/persister-react-native-sqlite/index.d.ts';
 export * from '../persisters/persister-remote/index.d.ts';
 export * from '../persisters/persister-sqlite-bun/index.d.ts';
+export * from '../persisters/persister-sqlite-node/index.d.ts';
 export * from '../persisters/persister-sqlite-wasm/index.d.ts';
 export * from '../persisters/persister-sqlite3/index.d.ts';
 export * from '../persisters/persister-supabase/index.d.ts';

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

@@ -42,6 +42,7 @@ export * from '../../persisters/persister-react-native-mmkv/with-schemas/index.d
 export * from '../../persisters/persister-react-native-sqlite/with-schemas/index.d.ts';
 export * from '../../persisters/persister-remote/with-schemas/index.d.ts';
 export * from '../../persisters/persister-sqlite-bun/with-schemas/index.d.ts';
+export * from '../../persisters/persister-sqlite-node/with-schemas/index.d.ts';
 export * from '../../persisters/persister-sqlite-wasm/with-schemas/index.d.ts';
 export * from '../../persisters/persister-sqlite3/with-schemas/index.d.ts';
 export * from '../../persisters/persister-supabase/with-schemas/index.d.ts';

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

@@ -0,0 +1,184 @@
+/**
+ * The persister-sqlite-node module of the TinyBase project lets you save and
+ * load Store data to and from a local SQLite database, via the synchronous
+ * [`node:sqlite`](https://nodejs.org/api/sqlite.html) module built into
+ * Node.js.
+ * @see Database Persistence guide
+ * @packageDocumentation
+ * @module persister-sqlite-node
+ * @since 9.7.0
+ */
+import type {DatabaseSync} from 'node:sqlite';
+import type {MergeableStore} from '../../mergeable-store/index.d.ts';
+import type {Store} from '../../store/index.d.ts';
+import type {
+  DatabasePersisterConfig,
+  DpcJson,
+  Persister,
+  Persists,
+} from '../index.d.ts';
+
+/**
+ * The SqliteNodePersister interface represents a Persister that lets you save
+ * and load Store data to and from a local SQLite database.
+ *
+ * You should use the createSqliteNodePersister function to create a
+ * SqliteNodePersister object.
+ *
+ * It is a minor extension to the Persister interface and simply provides an
+ * extra getDb method for accessing a reference to the database the Store is
+ * being persisted to.
+ * @category Persister
+ * @since 9.7.0
+ */
+export interface SqliteNodePersister extends Persister<Persists.StoreOrMergeableStore> {
+  /**
+   * The getDb method returns a reference to the database the Store is being
+   * persisted to.
+   * @returns A reference to the database.
+   * @example
+   * This example creates a Persister object against a newly-created Store and
+   * then gets the database back out again.
+   *
+   * ```js
+   * import {DatabaseSync} from 'node:sqlite';
+   * import {createStore} from 'tinybase';
+   * import {createSqliteNodePersister} from 'tinybase/persisters/persister-sqlite-node';
+   *
+   * const db = new DatabaseSync(':memory:');
+   * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
+   * const persister = createSqliteNodePersister(store, db, 'my_tinybase');
+   *
+   * console.log(persister.getDb() == db);
+   * // -> true
+   *
+   * await persister.destroy();
+   * db.close();
+   * ```
+   * @category Getter
+   * @since 9.7.0
+   */
+  getDb(): DatabaseSync;
+}
+
+/**
+ * The createSqliteNodePersister function creates a SqliteNodePersister object
+ * that can persist a Store to a local SQLite database.
+ *
+ * A SqliteNodePersister supports regular Store objects, and can also be used to
+ * persist the metadata of a MergeableStore when using the JSON serialization
+ * mode, as described below.
+ *
+ * As well as providing a reference to the Store to persist, you must provide a
+ * `db` parameter which is the database returned from `new DatabaseSync(...)`.
+ *
+ * Since the `node:sqlite` module is built into Node.js, this is the only
+ * SQLite-based Persister that requires no additional dependency at all. Note
+ * that the module is only available in newer versions of Node.js, and that it
+ * is still marked as experimental, so its API may change.
+ *
+ * A database Persister uses one of two modes: either a JSON serialization of
+ * the whole Store stored in a single row of a table (the default), or a tabular
+ * mapping of Table Ids to database table names and vice-versa).
+ *
+ * The third argument is a DatabasePersisterConfig object that configures which
+ * of those modes to use, and settings for each. If the third argument is simply
+ * a string, it is used as the `storeTableName` property of the JSON
+ * serialization.
+ *
+ * See the documentation for the DpcJson and DpcTabular types for more
+ * information on how both of those modes can be configured.
+ *
+ * Note that `node:sqlite` does not signal when the database changes, so if you
+ * enable automatic loading with the startAutoLoad method, it polls the database
+ * for changes. The Sqlite3Persister, which uses the asynchronous `sqlite3`
+ * module, is notified of changes as they happen, and may suit you better if
+ * that matters.
+ * @param store The Store or MergeableStore to persist.
+ * @param db The database that was returned from `new DatabaseSync(...)`.
+ * @param configOrStoreTableName A DatabasePersisterConfig to configure the
+ * persistence mode (or a string to set the `storeTableName` property of the
+ * JSON serialization).
+ * @param onSqlCommand An optional handler called every time the Persister
+ * executes a SQL command or query. This is suitable for logging persistence
+ * behavior in a development environment.
+ * @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 SqliteNodePersister object.
+ * @example
+ * This example creates a SqliteNodePersister object and persists the Store to a
+ * local SQLite database as a JSON serialization into the `my_tinybase` table.
+ * It makes a change to the database directly and then reloads it back into the
+ * Store.
+ *
+ * ```js
+ * import {DatabaseSync} from 'node:sqlite';
+ * import {createStore} from 'tinybase';
+ * import {createSqliteNodePersister} from 'tinybase/persisters/persister-sqlite-node';
+ *
+ * const db = new DatabaseSync(':memory:');
+ * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
+ * const persister = createSqliteNodePersister(store, db, 'my_tinybase');
+ *
+ * await persister.save();
+ * // Store will be saved to the database.
+ *
+ * console.log(db.prepare('SELECT * FROM my_tinybase;').all());
+ * // -> [{_id: '_', store: '[{"pets":{"fido":{"species":"dog"}}},{}]'}]
+ *
+ * db.prepare('UPDATE my_tinybase SET store = ? WHERE _id = ?;').run(
+ *   '[{"pets":{"felix":{"species":"cat"}}},{}]',
+ *   '_',
+ * );
+ * await persister.load();
+ * console.log(store.getTables());
+ * // -> {pets: {felix: {species: 'cat'}}}
+ *
+ * await persister.destroy();
+ * db.close();
+ * ```
+ * @example
+ * This example creates a SqliteNodePersister object and persists the Store to a
+ * local SQLite database with tabular mapping.
+ *
+ * ```js
+ * import {DatabaseSync} from 'node:sqlite';
+ * import {createStore} from 'tinybase';
+ * import {createSqliteNodePersister} from 'tinybase/persisters/persister-sqlite-node';
+ *
+ * const db = new DatabaseSync(':memory:');
+ * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
+ * const persister = createSqliteNodePersister(store, db, {
+ *   mode: 'tabular',
+ *   tables: {load: {pets: 'pets'}, save: {pets: 'pets'}},
+ * });
+ *
+ * await persister.save();
+ * console.log(db.prepare('SELECT * FROM pets;').all());
+ * // -> [{_id: 'fido', species: 'dog'}]
+ *
+ * db.prepare(
+ *   `INSERT INTO pets (_id, species) VALUES ('felix', 'cat')`,
+ * ).run();
+ * await persister.load();
+ * console.log(store.getTables());
+ * // -> {pets: {fido: {species: 'dog'}, felix: {species: 'cat'}}}
+ *
+ * await persister.destroy();
+ * db.close();
+ * ```
+ * @category Creation
+ * @since 9.7.0
+ */
+export function createSqliteNodePersister<StoreType extends Store>(
+  store: StoreType,
+  db: DatabaseSync,
+  configOrStoreTableName?:
+    | (NoInfer<StoreType> extends MergeableStore
+        ? DpcJson
+        : DatabasePersisterConfig)
+    | string,
+  onSqlCommand?: (sql: string, params?: any[]) => void,
+  onIgnoredError?: (error: any) => void,
+): SqliteNodePersister;

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

@@ -0,0 +1,208 @@
+/**
+ * The persister-sqlite-node module of the TinyBase project lets you save and
+ * load Store data to and from a local SQLite database, via the synchronous
+ * [`node:sqlite`](https://nodejs.org/api/sqlite.html) module built into
+ * Node.js.
+ * @see Database Persistence guide
+ * @packageDocumentation
+ * @module persister-sqlite-node
+ * @since 9.7.0
+ */
+import type {DatabaseSync} from 'node:sqlite';
+import type {MergeableStore} from '../../../mergeable-store/with-schemas/index.d.ts';
+import type {
+  OptionalSchemas,
+  Store,
+} from '../../../store/with-schemas/index.d.ts';
+import type {
+  DatabasePersisterConfig,
+  DpcJson,
+  Persister,
+  Persists,
+} from '../../with-schemas/index.d.ts';
+
+/**
+ * The SqliteNodePersister interface represents a Persister that lets you save
+ * and load Store data to and from a local SQLite database.
+ *
+ * You should use the createSqliteNodePersister function to create a
+ * SqliteNodePersister object.
+ *
+ * It is a minor extension to the Persister interface and simply provides an
+ * extra getDb method for accessing a reference to the database the Store is
+ * being persisted to.
+ * @category Persister
+ * @since 9.7.0
+ */
+export interface SqliteNodePersister<
+  Schemas extends OptionalSchemas,
+> extends Persister<Schemas, Persists.StoreOrMergeableStore> {
+  /**
+   * The getDb method returns a reference to the database the Store is being
+   * persisted to.
+   * @returns A reference to the database.
+   * @example
+   * This example creates a Persister object against a newly-created Store and
+   * then gets the database back out again.
+   *
+   * ```js
+   * import {DatabaseSync} from 'node:sqlite';
+   * import {createStore} from 'tinybase';
+   * import {createSqliteNodePersister} from 'tinybase/persisters/persister-sqlite-node';
+   *
+   * const db = new DatabaseSync(':memory:');
+   * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
+   * const persister = createSqliteNodePersister(store, db, 'my_tinybase');
+   *
+   * console.log(persister.getDb() == db);
+   * // -> true
+   *
+   * await persister.destroy();
+   * db.close();
+   * ```
+   * @category Getter
+   * @since 9.7.0
+   */
+  getDb(): DatabaseSync;
+}
+
+/**
+ * The createSqliteNodePersister function creates a SqliteNodePersister object
+ * that can persist a Store to a local SQLite database.
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * createSqliteNodePersister<StoreType extends Store>(
+ *   store: StoreType,
+ *   db: DatabaseSync,
+ *   configOrStoreTableName?:
+ *     | (NoInfer<StoreType> extends MergeableStore
+ *         ? DpcJson
+ *         : DatabasePersisterConfig)
+ *     | string,
+ *   onSqlCommand?: (sql: string, params?: any[]) => void,
+ *   onIgnoredError?: (error: any) => void,
+ * ): SqliteNodePersister;
+ * ```
+ *
+ * A SqliteNodePersister supports regular Store objects, and can also be used to
+ * persist the metadata of a MergeableStore when using the JSON serialization
+ * mode, as described below.
+ *
+ * As well as providing a reference to the Store to persist, you must provide a
+ * `db` parameter which is the database returned from `new DatabaseSync(...)`.
+ *
+ * Since the `node:sqlite` module is built into Node.js, this is the only
+ * SQLite-based Persister that requires no additional dependency at all. Note
+ * that the module is only available in newer versions of Node.js, and that it
+ * is still marked as experimental, so its API may change.
+ *
+ * A database Persister uses one of two modes: either a JSON serialization of
+ * the whole Store stored in a single row of a table (the default), or a tabular
+ * mapping of Table Ids to database table names and vice-versa).
+ *
+ * The third argument is a DatabasePersisterConfig object that configures which
+ * of those modes to use, and settings for each. If the third argument is simply
+ * a string, it is used as the `storeTableName` property of the JSON
+ * serialization.
+ *
+ * See the documentation for the DpcJson and DpcTabular types for more
+ * information on how both of those modes can be configured.
+ *
+ * Note that `node:sqlite` does not signal when the database changes, so if you
+ * enable automatic loading with the startAutoLoad method, it polls the database
+ * for changes. The Sqlite3Persister, which uses the asynchronous `sqlite3`
+ * module, is notified of changes as they happen, and may suit you better if
+ * that matters.
+ * @param store The Store or MergeableStore to persist.
+ * @param db The database that was returned from `new DatabaseSync(...)`.
+ * @param configOrStoreTableName A DatabasePersisterConfig to configure the
+ * persistence mode (or a string to set the `storeTableName` property of the
+ * JSON serialization).
+ * @param onSqlCommand An optional handler called every time the Persister
+ * executes a SQL command or query. This is suitable for logging persistence
+ * behavior in a development environment.
+ * @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 SqliteNodePersister object.
+ * @example
+ * This example creates a SqliteNodePersister object and persists the Store to a
+ * local SQLite database as a JSON serialization into the `my_tinybase` table.
+ * It makes a change to the database directly and then reloads it back into the
+ * Store.
+ *
+ * ```js
+ * import {DatabaseSync} from 'node:sqlite';
+ * import {createStore} from 'tinybase';
+ * import {createSqliteNodePersister} from 'tinybase/persisters/persister-sqlite-node';
+ *
+ * const db = new DatabaseSync(':memory:');
+ * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
+ * const persister = createSqliteNodePersister(store, db, 'my_tinybase');
+ *
+ * await persister.save();
+ * // Store will be saved to the database.
+ *
+ * console.log(db.prepare('SELECT * FROM my_tinybase;').all());
+ * // -> [{_id: '_', store: '[{"pets":{"fido":{"species":"dog"}}},{}]'}]
+ *
+ * db.prepare('UPDATE my_tinybase SET store = ? WHERE _id = ?;').run(
+ *   '[{"pets":{"felix":{"species":"cat"}}},{}]',
+ *   '_',
+ * );
+ * await persister.load();
+ * console.log(store.getTables());
+ * // -> {pets: {felix: {species: 'cat'}}}
+ *
+ * await persister.destroy();
+ * db.close();
+ * ```
+ * @example
+ * This example creates a SqliteNodePersister object and persists the Store to a
+ * local SQLite database with tabular mapping.
+ *
+ * ```js
+ * import {DatabaseSync} from 'node:sqlite';
+ * import {createStore} from 'tinybase';
+ * import {createSqliteNodePersister} from 'tinybase/persisters/persister-sqlite-node';
+ *
+ * const db = new DatabaseSync(':memory:');
+ * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
+ * const persister = createSqliteNodePersister(store, db, {
+ *   mode: 'tabular',
+ *   tables: {load: {pets: 'pets'}, save: {pets: 'pets'}},
+ * });
+ *
+ * await persister.save();
+ * console.log(db.prepare('SELECT * FROM pets;').all());
+ * // -> [{_id: 'fido', species: 'dog'}]
+ *
+ * db.prepare(
+ *   `INSERT INTO pets (_id, species) VALUES ('felix', 'cat')`,
+ * ).run();
+ * await persister.load();
+ * console.log(store.getTables());
+ * // -> {pets: {fido: {species: 'dog'}, felix: {species: 'cat'}}}
+ *
+ * await persister.destroy();
+ * db.close();
+ * ```
+ * @category Creation
+ * @since 9.7.0
+ */
+export function createSqliteNodePersister<Schemas extends OptionalSchemas>(
+  store: MergeableStore<Schemas>,
+  db: DatabaseSync,
+  configOrStoreTableName?: DpcJson | string,
+  onSqlCommand?: (sql: string, params?: any[]) => void,
+  onIgnoredError?: (error: any) => void,
+): SqliteNodePersister<Schemas>;
+export function createSqliteNodePersister<Schemas extends OptionalSchemas>(
+  store: Store<Schemas> & {getMergeableContent?: never},
+  db: DatabaseSync,
+  configOrStoreTableName?: DatabasePersisterConfig<Schemas> | string,
+  onSqlCommand?: (sql: string, params?: any[]) => void,
+  onIgnoredError?: (error: any) => void,
+): SqliteNodePersister<Schemas>;

package/agents.md

@@ -234,6 +234,32 @@ npm run serveDocs           # Preview documentation locally
 - **Types**: Unit, performance, end-to-end, production
 - **Environment**: happy-dom (unit), puppeteer (e2e)
 
+Coverage is measured over four bundles only - `dist/index.js` and the three UI
+entry points - so Persister and Synchronizer modules do not appear in that
+figure. Their correctness comes from the database matrix in
+`test/unit/persisters/common/databases.ts` instead, which every new Persister
+should be added to.
+
+`npm run testPerf` asserts against absolute microsecond budgets with roughly
+40% headroom, and swings by more than 2x under scheduling contention. It needs
+a real foreground terminal, and it does not run in CI, so a failure there is
+not evidence of a regression until it has been reproduced that way.
+
+Never pipe a long gulp task through `tail`: the pipeline reports `tail`'s exit
+code rather than gulp's, so a failed `preCommit` or `prePublishPackage` looks
+like a success. Redirect to a file and check `$?`.
+
+### Dependencies
+
+- Lift the version for **both** the devDependency and the peerDependency
+  together whenever a package appears in both.
+- Use `ncu -u --dep=peer,dev`. Plain `ncu` omits peers, which hides peer-only
+  entries entirely.
+- `ncu` keeps the two sections in step only when their ranges are written
+  identically. Where the forms differ it updates one and silently leaves the
+  other, so use carets consistently and diff both sections after a bump rather
+  than trusting the `ncu` summary, which prints one line per package.
+
 ### Code Style
 
 - **ESLint**: Enforced with strict rules
@@ -243,6 +269,18 @@ npm run serveDocs           # Preview documentation locally
 - **Semicolons**: Required
 - **Object spacing**: No spaces in braces `{key: value}`
 
+### Git Conventions
+
+- **Never add attribution trailers to commit messages.** No `Co-Authored-By:`,
+  no "Generated with" lines, no tool or model attribution of any kind. The
+  history contains no trailers, and it should stay that way.
+- Commit messages are a **single line** with no body, in the form
+  `[topic] Sentence case subject`. The topic is the area of work, usually the
+  module or dependency being changed, as in `[hygiene] Dependencies` or
+  `[sqlite-node] Test across the database matrix`.
+- A new Persister lands as a sequence of commits in this order: dependency (if
+  any), boilerplate (implementation, types and registration), tests, then docs.
+
 ## Project Structure
 
 ```