tinybase 8.0.0-beta.2 → 8.0.0-beta.4

package/@types/_internal/store/with-schemas/index.d.ts

@@ -48,7 +48,7 @@ export type CellIsDefaultedFromSchema<
   Then,
   Else,
 > = Schema[TableId][CellId] extends {
-  default: string | number | boolean;
+  default: infer _;
 }
   ? Then
   : Else;
@@ -83,7 +83,7 @@ export type ValueIsDefaultedFromSchema<
   Then,
   Else,
 > = Schema[ValueId] extends {
-  default: string | number | boolean;
+  default: infer _;
 }
   ? Then
   : Else;

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

@@ -16,6 +16,28 @@ import type {CellOrUndefined, ValueOrUndefined} from '../store/index.d.ts';
  */
 export type Json = string;
 
+/**
+ * The AnyObject type is a simple alias for a plain object with string keys and
+ * unknown values.
+ *
+ * It is used to indicate that the value should be considered to be a plain
+ * JavaScript object, as can be stored in a Cell or Value with the `object`
+ * schema type.
+ * @category General
+ * @since v8.0.0
+ */
+export type AnyObject = {[key: string]: unknown};
+
+/**
+ * The AnyArray type is a simple alias for an array with unknown values.
+ *
+ * It is used to indicate that the value should be considered to be a JavaScript
+ * array, as can be stored in a Cell or Value with the `array` schema type.
+ * @category General
+ * @since v8.0.0
+ */
+export type AnyArray = unknown[] | readonly unknown[];
+
 /**
  * The Ids type is a simple alias for an array of strings, but is used to
  * indicate that the strings should be considered to be the keys of objects

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

@@ -28,6 +28,28 @@ import type {
  */
 export type Json = string;
 
+/**
+ * The AnyObject type is a simple alias for a plain object with string keys and
+ * unknown values.
+ *
+ * It is used to indicate that the value should be considered to be a plain
+ * JavaScript object, as can be stored in a Cell or Value with the `object`
+ * schema type.
+ * @category General
+ * @since v8.0.0
+ */
+export type AnyObject = {[key: string]: unknown};
+
+/**
+ * The AnyArray type is a simple alias for an array with unknown values.
+ *
+ * It is used to indicate that the value should be considered to be a JavaScript
+ * array, as can be stored in a Cell or Value with the `array` schema type.
+ * @category General
+ * @since v8.0.0
+ */
+export type AnyArray = unknown[] | readonly unknown[];
+
 /**
  * The Ids type is a simple alias for an array of strings, but is used to
  * indicate that the strings should be considered to be the keys of objects

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

@@ -97,6 +97,15 @@ export type WillSetTableCallback = (
  * Multiple WillSetRowCallback functions can be registered and they will be
  * called sequentially, the Row being updated successively. If any callback
  * returns `undefined`, the chain short-circuits and the Row will not be set.
+ *
+ * This callback fires both when setRow is called with a whole Row, and when
+ * setCell is called for a single Cell. When fired from setCell, the Row passed
+ * to the callback is a prospective row containing the existing Cell values
+ * merged with the new Cell value. The entire returned Row is then applied as
+ * though setRow had been called with it: cells present in the returned Row are
+ * written (each also passing through willSetCell), and cells absent from the
+ * returned Row that were present in the existing Row will be deleted. Return
+ * `undefined` to cancel the operation entirely.
  * @param tableId The Id of the Table being written to.
  * @param rowId The Id of the Row being set.
  * @param row The Row object about to be set.
@@ -311,49 +320,6 @@ export type WillApplyChangesCallback = (
   changes: Changes,
 ) => Changes | undefined;
 
-/**
- * The DidSetRowCallback type describes a function called after a Row is changed
- * during a transaction, and after mutator listeners have fired.
- *
- * Unlike the `willSet*` callbacks, which intercept writes as they happen,
- * `didSetRow` fires once per touched Row after all cell writes in the
- * transaction have completed. This means multiple cell changes to the same Row
- * within a single transaction result in just one `didSetRow` call, with the
- * full before-transaction and after-transaction Row states.
- *
- * The callback receives the Table Id, Row Id, the Row as it was at the start of
- * the transaction (`oldRow`), and the Row as it is now (`newRow`). It must
- * return a Row:
- *
- * - `newRow` to accept the changes.
- * - a different `Row` to replace the final state.
- * - `oldRow` to revert all changes to the Row.
- * - an empty object to delete the Row.
- *
- * Multiple DidSetRowCallback functions can be registered for the same table and
- * they will be called sequentially, each receiving the Row returned by the
- * previous callback. The chain never short-circuits: all registered callbacks
- * always run.
- *
- * Note that `addDidSetRowCallback` is table-scoped: you must specify the table
- * Id when registering. Callbacks are only invoked for rows in the specified
- * table, keeping overhead to zero for other tables.
- * @param tableId The Id of the Table containing the changed Row.
- * @param rowId The Id of the Row that was changed.
- * @param oldRow The Row as it was at the start of the transaction.
- * @param newRow The Row as it is now, after all cell writes including those
- * made by mutating listeners.
- * @returns The Row to use as the final state.
- * @category Callback
- * @since v8.0.0
- */
-export type DidSetRowCallback = (
-  tableId: Id,
-  rowId: Id,
-  oldRow: Row,
-  newRow: Row,
-) => Row;
-
 /**
  * A Middleware object lets you intercept and validate writes to a Store.
  *
@@ -585,6 +551,15 @@ export interface Middleware {
    * write. Multiple callbacks can be registered and they are called
    * sequentially, each receiving the (possibly transformed) row from the
    * previous callback.
+   *
+   * This callback fires both when a whole Row is set with the setRow method,
+   * _and_ when a single Cell is set with the setCell method. When called from
+   * setCell, the callback receives a prospective row consisting of the existing
+   * Cell values merged with the new Cell value. The entire returned Row is then
+   * applied as though setRow had been called: all cells in the returned Row are
+   * written (each also passing through willSetCell), and any cells absent from
+   * the returned Row that existed before will be deleted. Return `undefined` to
+   * cancel the operation entirely.
    * @param callback The WillSetRowCallback to register.
    * @returns A reference to the Middleware object, for chaining.
    * @example
@@ -634,6 +609,32 @@ export interface Middleware {
    *
    * middleware.destroy();
    * ```
+   * @example
+   * This example shows the callback firing when setCell is called,
+   * automatically stamping an 'updated' timestamp onto the row each time any
+   * cell in it is written.
+   *
+   * ```js
+   * import {createMiddleware, createStore} from 'tinybase';
+   *
+   * const store = createStore();
+   * const middleware = createMiddleware(store);
+   *
+   * store.setRow('pets', 'fido', {species: 'dog'});
+   *
+   * middleware.addWillSetRowCallback((_tableId, _rowId, row) => ({
+   *   ...row,
+   *   updated: Date.now(),
+   * }));
+   *
+   * store.setCell('pets', 'fido', 'legs', 4);
+   * console.log(store.getCell('pets', 'fido', 'legs'));
+   * // -> 4
+   * console.log(typeof store.getCell('pets', 'fido', 'updated'));
+   * // -> 'number'
+   *
+   * middleware.destroy();
+   * ```
    * @category Configuration
    * @since v8.0.0
    */
@@ -1044,82 +1045,6 @@ export interface Middleware {
    */
   addWillApplyChangesCallback(callback: WillApplyChangesCallback): Middleware;
 
-  /**
-   * The addDidSetRowCallback method registers a DidSetRowCallback for a
-   * specific table that will be called after any Row in that table is changed
-   * during a transaction, after mutator listeners have fired.
-   *
-   * Unlike `willSetRow`, which fires synchronously during each write, this
-   * callback fires once per changed Row after all cell writes in the
-   * transaction have landed. Multiple cell changes to the same Row within a
-   * transaction produce a single callback with the full before/after Row
-   * states.
-   *
-   * The callback receives `oldRow` (the Row at the start of the transaction)
-   * and `newRow` (the Row after all writes). Return `newRow` to accept, a
-   * different `Row` to replace, `oldRow` to revert, or an empty object to
-   * delete.
-   * @param tableId The Id of the Table to watch.
-   * @param callback The DidSetRowCallback to register.
-   * @returns A reference to the Middleware object, for chaining.
-   * @example
-   * This example registers a callback that validates the 'pets' table,
-   * reverting any row that ends up without a required 'species' cell.
-   *
-   * ```js
-   * import {createMiddleware, createStore} from 'tinybase';
-   *
-   * const store = createStore();
-   * const middleware = createMiddleware(store);
-   *
-   * middleware.addDidSetRowCallback('pets', (_tableId, _rowId, oldRow, newRow) =>
-   *   'species' in newRow ? newRow : oldRow,
-   * );
-   *
-   * store.setRow('pets', 'fido', {species: 'dog', name: 'Fido'});
-   * console.log(store.getRow('pets', 'fido'));
-   * // -> {species: 'dog', name: 'Fido'}
-   *
-   * store.setRow('pets', 'nemo', {name: 'Nemo'});
-   * console.log(store.getRow('pets', 'nemo'));
-   * // -> {}
-   *
-   * middleware.destroy();
-   * ```
-   * @example
-   * This example shows that multiple cell changes in one transaction result in
-   * a single didSetRow callback with the full before/after row states.
-   *
-   * ```js
-   * import {createMiddleware, createStore} from 'tinybase';
-   *
-   * const store = createStore();
-   * const middleware = createMiddleware(store);
-   *
-   * const seen = [];
-   * middleware.addDidSetRowCallback('pets', (_tableId, rowId, oldRow, newRow) => {
-   *   seen.push({rowId, oldRow: {...oldRow}, newRow: {...newRow}});
-   *   return newRow;
-   * });
-   *
-   * store.transaction(() => {
-   *   store.setCell('pets', 'fido', 'name', 'Fido');
-   *   store.setCell('pets', 'fido', 'species', 'dog');
-   * });
-   * console.log(seen.length);
-   * // -> 1
-   * console.log(seen[0].rowId);
-   * // -> 'fido'
-   * console.log(seen[0].newRow);
-   * // -> {name: 'Fido', species: 'dog'}
-   *
-   * middleware.destroy();
-   * ```
-   * @category Configuration
-   * @since v8.0.0
-   */
-  addDidSetRowCallback(tableId: Id, callback: DidSetRowCallback): Middleware;
-
   /**
    * The destroy method should be called when this Middleware object is no
    * longer used. It removes all hooks and listeners from the Store, and

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

@@ -144,6 +144,15 @@ export type WillSetTableCallback<
  * Multiple WillSetRowCallback functions can be registered and they will be
  * called sequentially, the Row being updated successively. If any callback
  * returns `undefined`, the chain short-circuits and the Row will not be set.
+ *
+ * This callback fires both when setRow is called with a whole Row, and when
+ * setCell is called for a single Cell. When fired from setCell, the Row passed
+ * to the callback is a prospective row containing the existing Cell values
+ * merged with the new Cell value. The entire returned Row is then applied as
+ * though setRow had been called with it: cells present in the returned Row are
+ * written (each also passing through willSetCell), and cells absent from the
+ * returned Row that were present in the existing Row will be deleted. Return
+ * `undefined` to cancel the operation entirely.
  * @param tableId The Id of the Table being written to.
  * @param rowId The Id of the Row being set.
  * @param row The Row object about to be set.
@@ -476,63 +485,6 @@ export type WillApplyChangesCallback<Schemas extends OptionalSchemas> = (
   changes: Changes<Schemas>,
 ) => Changes<Schemas> | undefined;
 
-/**
- * The DidSetRowCallback type describes a function called after a Row is changed
- * during a transaction, and after mutator listeners have fired.
- *
- * This has schema-based typing. The following is a simplified representation:
- *
- * ```ts override
- * (
- *   tableId: Id,
- *   rowId: Id,
- *   oldRow: Row,
- *   newRow: Row,
- * ) => Row;
- * ```
- *
- * Unlike the `willSet*` callbacks, which intercept writes as they happen,
- * `didSetRow` fires once per touched Row after all cell writes in the
- * transaction have completed. This means multiple cell changes to the same Row
- * within a single transaction result in just one `didSetRow` call, with the
- * full before-transaction and after-transaction Row states.
- *
- * The callback receives the Table Id, Row Id, the Row as it was at the start of
- * the transaction (`oldRow`), and the Row as it is now (`newRow`). It must
- * return a Row:
- *
- * - `newRow` to accept the changes.
- * - a different `Row` to replace the final state.
- * - `oldRow` to revert all changes to the Row.
- * - an empty object to delete the Row.
- *
- * Multiple DidSetRowCallback functions can be registered for the same table and
- * they will be called sequentially, each receiving the Row returned by the
- * previous callback. The chain never short-circuits: all registered callbacks
- * always run.
- *
- * Note that `addDidSetRowCallback` is table-scoped: you must specify the table
- * Id when registering. Callbacks are only invoked for rows in the specified
- * table, keeping overhead to zero for other tables.
- * @param tableId The Id of the Table containing the changed Row.
- * @param rowId The Id of the Row that was changed.
- * @param oldRow The Row as it was at the start of the transaction.
- * @param newRow The Row as it is now, after all cell writes including those
- * made by mutating listeners.
- * @returns The Row to use as the final state.
- * @category Callback
- * @since v8.0.0
- */
-export type DidSetRowCallback<
-  Schema extends OptionalTablesSchema,
-  TableId extends TableIdFromSchema<Schema>,
-> = (
-  tableId: TableId,
-  rowId: Id,
-  oldRow: Row<Schema, TableId>,
-  newRow: Row<Schema, TableId>,
-) => Row<Schema, TableId>;
-
 /**
  * A Middleware object lets you intercept and validate writes to a Store.
  *
@@ -800,6 +752,15 @@ export interface Middleware<in out Schemas extends OptionalSchemas> {
    * write. Multiple callbacks can be registered and they are called
    * sequentially, each receiving the (possibly transformed) row from the
    * previous callback.
+   *
+   * This callback fires both when a whole Row is set with the setRow method,
+   * _and_ when a single Cell is set with the setCell method. When called from
+   * setCell, the callback receives a prospective row consisting of the existing
+   * Cell values merged with the new Cell value. The entire returned Row is then
+   * applied as though setRow had been called: all cells in the returned Row are
+   * written (each also passing through willSetCell), and any cells absent from
+   * the returned Row that existed before will be deleted. Return `undefined` to
+   * cancel the operation entirely.
    * @param callback The WillSetRowCallback to register.
    * @returns A reference to the Middleware object, for chaining.
    * @example
@@ -849,6 +810,32 @@ export interface Middleware<in out Schemas extends OptionalSchemas> {
    *
    * middleware.destroy();
    * ```
+   * @example
+   * This example shows the callback firing when setCell is called,
+   * automatically stamping an 'updated' timestamp onto the row each time any
+   * cell in it is written.
+   *
+   * ```js
+   * import {createMiddleware, createStore} from 'tinybase';
+   *
+   * const store = createStore();
+   * const middleware = createMiddleware(store);
+   *
+   * store.setRow('pets', 'fido', {species: 'dog'});
+   *
+   * middleware.addWillSetRowCallback((_tableId, _rowId, row) => ({
+   *   ...row,
+   *   updated: Date.now(),
+   * }));
+   *
+   * store.setCell('pets', 'fido', 'legs', 4);
+   * console.log(store.getCell('pets', 'fido', 'legs'));
+   * // -> 4
+   * console.log(typeof store.getCell('pets', 'fido', 'updated'));
+   * // -> 'number'
+   *
+   * middleware.destroy();
+   * ```
    * @category Configuration
    * @since v8.0.0
    */
@@ -1341,91 +1328,6 @@ export interface Middleware<in out Schemas extends OptionalSchemas> {
     callback: WillApplyChangesCallback<Schemas>,
   ): Middleware<Schemas>;
 
-  /**
-   * The addDidSetRowCallback method registers a DidSetRowCallback for a
-   * specific table that will be called after any Row in that table is changed
-   * during a transaction, after mutator listeners have fired.
-   *
-   * This has schema-based typing. The following is a simplified representation:
-   *
-   * ```ts override
-   * addDidSetRowCallback(tableId: Id, callback: DidSetRowCallback): Middleware;
-   * ```
-   *
-   * Unlike `willSetRow`, which fires synchronously during each write, this
-   * callback fires once per changed Row after all cell writes in the
-   * transaction have landed. Multiple cell changes to the same Row within a
-   * transaction produce a single callback with the full before/after Row
-   * states.
-   *
-   * The callback receives `oldRow` (the Row at the start of the transaction)
-   * and `newRow` (the Row after all writes). Return `newRow` to accept, a
-   * different `Row` to replace, `oldRow` to revert, or an empty object to
-   * delete.
-   * @param tableId The Id of the Table to watch.
-   * @param callback The DidSetRowCallback to register.
-   * @returns A reference to the Middleware object, for chaining.
-   * @example
-   * This example registers a callback that validates the 'pets' table,
-   * reverting any row that ends up without a required 'species' cell.
-   *
-   * ```js
-   * import {createMiddleware, createStore} from 'tinybase';
-   *
-   * const store = createStore();
-   * const middleware = createMiddleware(store);
-   *
-   * middleware.addDidSetRowCallback('pets', (_tableId, _rowId, oldRow, newRow) =>
-   *   'species' in newRow ? newRow : oldRow,
-   * );
-   *
-   * store.setRow('pets', 'fido', {species: 'dog', name: 'Fido'});
-   * console.log(store.getRow('pets', 'fido'));
-   * // -> {species: 'dog', name: 'Fido'}
-   *
-   * store.setRow('pets', 'nemo', {name: 'Nemo'});
-   * console.log(store.getRow('pets', 'nemo'));
-   * // -> {}
-   *
-   * middleware.destroy();
-   * ```
-   * @example
-   * This example shows that multiple cell changes in one transaction result in
-   * a single didSetRow callback with the full before/after row states.
-   *
-   * ```js
-   * import {createMiddleware, createStore} from 'tinybase';
-   *
-   * const store = createStore();
-   * const middleware = createMiddleware(store);
-   *
-   * const seen = [];
-   * middleware.addDidSetRowCallback('pets', (_tableId, rowId, oldRow, newRow) => {
-   *   seen.push({rowId, oldRow: {...oldRow}, newRow: {...newRow}});
-   *   return newRow;
-   * });
-   *
-   * store.transaction(() => {
-   *   store.setCell('pets', 'fido', 'name', 'Fido');
-   *   store.setCell('pets', 'fido', 'species', 'dog');
-   * });
-   * console.log(seen.length);
-   * // -> 1
-   * console.log(seen[0].rowId);
-   * // -> 'fido'
-   * console.log(seen[0].newRow);
-   * // -> {name: 'Fido', species: 'dog'}
-   *
-   * middleware.destroy();
-   * ```
-   * @category Configuration
-   * @since v8.0.0
-   */
-  addDidSetRowCallback<TableId extends TableIdFromSchema<Schemas[0]>>(
-    tableId: TableId,
-    callback: DidSetRowCallback<Schemas[0], TableId>,
-  ): Middleware<Schemas>;
-
   /**
    * The destroy method should be called when this Middleware object is no
    * longer used. It removes all hooks and listeners from the Store, and