tinybase 7.3.5 → 8.0.0-beta.1

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

@@ -0,0 +1,1355 @@
+/**
+ * The middleware module of the TinyBase project provides the ability to
+ * intercept and validate incoming writes to Store objects.
+ *
+ * The main entry point to this module is the createMiddleware function, which
+ * returns a new Middleware object. From there, you can register hooks that are
+ * called before data is written to the Store.
+ * @packageDocumentation
+ * @module middleware
+ * @since v8.0.0
+ */
+import type {
+  CellIdFromSchema,
+  TableIdFromSchema,
+  ValueIdFromSchema,
+} from '../../_internal/store/with-schemas/index.d.ts';
+import type {Id} from '../../common/with-schemas/index.d.ts';
+import type {
+  Cell,
+  Changes,
+  Content,
+  OptionalSchemas,
+  OptionalTablesSchema,
+  OptionalValuesSchema,
+  Row,
+  Store,
+  Table,
+  Tables,
+  Value,
+  Values,
+} from '../../store/with-schemas/index.d.ts';
+
+/**
+ * The WillSetContentCallback type describes a function that is called before
+ * Content is set in the Store.
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * (content: Content) => Content | undefined;
+ * ```
+ *
+ * The callback receives the Content (a [Tables, Values] tuple) that is about
+ * to be set. It can return the Content (possibly transformed) to allow the
+ * write, or `undefined` to prevent the Content from being set.
+ *
+ * Multiple WillSetContentCallback functions can be registered and they will be
+ * called sequentially, the Content being updated successively. If any callback
+ * returns `undefined`, the chain short-circuits and the Content will not be
+ * set.
+ * @param content The Content about to be set.
+ * @returns The Content to use (possibly transformed), or `undefined` to
+ * prevent the write.
+ * @category Callback
+ * @since v8.0.0
+ */
+export type WillSetContentCallback<Schemas extends OptionalSchemas> = (
+  content: Content<Schemas>,
+) => Content<Schemas> | undefined;
+
+/**
+ * The WillSetTablesCallback type describes a function that is called before
+ * Tables are set in the Store.
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * (tables: Tables) => Tables | undefined;
+ * ```
+ *
+ * The callback receives the Tables object that is about to be set. It can
+ * return the Tables (possibly transformed) to allow the write, or `undefined`
+ * to prevent the Tables from being set.
+ *
+ * Multiple WillSetTablesCallback functions can be registered and they will be
+ * called sequentially, the Tables being updated successively. If any callback
+ * returns `undefined`, the chain short-circuits and the Tables will not be
+ * set.
+ * @param tables The Tables object about to be set.
+ * @returns The Tables to use (possibly transformed), or `undefined` to prevent
+ * the write.
+ * @category Callback
+ * @since v8.0.0
+ */
+export type WillSetTablesCallback<Schema extends OptionalTablesSchema> = (
+  tables: Tables<Schema>,
+) => Tables<Schema> | undefined;
+
+/**
+ * The WillSetTableCallback type describes a function that is called before a
+ * Table is set in the Store.
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * (
+ *   tableId: Id,
+ *   table: Table,
+ * ) => Table | undefined;
+ * ```
+ *
+ * The callback receives the table Id and the Table object that is about to be
+ * set. It can return the Table (possibly transformed) to allow the write, or
+ * `undefined` to prevent the Table from being set.
+ *
+ * Multiple WillSetTableCallback functions can be registered and they will be
+ * called sequentially, the Table being updated successively. If any callback
+ * returns `undefined`, the chain short-circuits and the Table will not be set.
+ * @param tableId The Id of the Table being set.
+ * @param table The Table object about to be set.
+ * @returns The Table to use (possibly transformed), or `undefined` to prevent
+ * the write.
+ * @category Callback
+ * @since v8.0.0
+ */
+export type WillSetTableCallback<
+  Schema extends OptionalTablesSchema,
+  Params extends any[] = TableIdFromSchema<Schema> extends infer TableId
+    ? TableId extends TableIdFromSchema<Schema>
+      ? [tableId: TableId, table: Table<Schema, TableId>]
+      : never
+    : never,
+> = (
+  ...params: Params | [tableId: never, table: never]
+) => Params[1] | undefined;
+
+/**
+ * The WillSetRowCallback type describes a function that is called before a Row
+ * is set in the Store.
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * (
+ *   tableId: Id,
+ *   rowId: Id,
+ *   row: Row,
+ * ) => Row | undefined;
+ * ```
+ *
+ * The callback receives the table Id, row Id, and the Row object that is about
+ * to be set. It can return the Row (possibly transformed) to allow the write,
+ * or `undefined` to prevent the Row from being set.
+ *
+ * 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.
+ * @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.
+ * @returns The Row to use (possibly transformed), or `undefined` to prevent the
+ * write.
+ * @category Callback
+ * @since v8.0.0
+ */
+export type WillSetRowCallback<
+  Schema extends OptionalTablesSchema,
+  Params extends any[] = TableIdFromSchema<Schema> extends infer TableId
+    ? TableId extends TableIdFromSchema<Schema>
+      ? [tableId: TableId, rowId: Id, row: Row<Schema, TableId>]
+      : never
+    : never,
+> = (
+  ...params: Params | [tableId: never, rowId: never, row: never]
+) => Params[2] | undefined;
+
+/**
+ * The WillSetCellCallback type describes a function that is called before a
+ * Cell is set in the Store.
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * (
+ *   tableId: Id,
+ *   rowId: Id,
+ *   cellId: Id,
+ *   cell: Cell,
+ * ) => CellOrUndefined;
+ * ```
+ *
+ * The callback receives the table Id, row Id, cell Id, and the Cell value that
+ * is about to be set. It can return the Cell value (possibly transformed) to
+ * allow the write, or `undefined` to prevent the Cell from being set.
+ *
+ * Multiple WillSetCellCallback functions can be registered and they will be
+ * called sequentially, the Cell value being updated successively. If any
+ * callback returns `undefined`, the chain short-circuits and the Cell will not
+ * be set.
+ * @param tableId The Id of the Table being written to.
+ * @param rowId The Id of the Row being written to.
+ * @param cellId The Id of the Cell being set.
+ * @param cell The Cell value about to be set.
+ * @returns The Cell value to use (possibly transformed), or `undefined` to
+ * prevent the write.
+ * @category Callback
+ * @since v8.0.0
+ */
+export type WillSetCellCallback<
+  Schema extends OptionalTablesSchema,
+  Params extends any[] = TableIdFromSchema<Schema> extends infer TableId
+    ? TableId extends TableIdFromSchema<Schema>
+      ? CellIdFromSchema<Schema, TableId> extends infer CellId
+        ? CellId extends CellIdFromSchema<Schema, TableId>
+          ? [
+              tableId: TableId,
+              rowId: Id,
+              cellId: CellId,
+              cell: Cell<Schema, TableId, CellId>,
+            ]
+          : never
+        : never
+      : never
+    : never,
+> = (
+  ...params: Params | [tableId: never, rowId: never, cellId: never, cell: never]
+) => Params[3] | undefined;
+
+/**
+ * The WillSetValuesCallback type describes a function that is called before
+ * Values are set in the Store.
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * (values: Values) => Values | undefined;
+ * ```
+ *
+ * The callback receives the Values object that is about to be set. It can
+ * return the Values (possibly transformed) to allow the write, or `undefined`
+ * to prevent the Values from being set.
+ *
+ * Multiple WillSetValuesCallback functions can be registered and they will be
+ * called sequentially, the Values being updated successively. If any callback
+ * returns `undefined`, the chain short-circuits and the Values will not be set.
+ * @param values The Values object about to be set.
+ * @returns The Values to use (possibly transformed), or `undefined` to prevent
+ * the write.
+ * @category Callback
+ * @since v8.0.0
+ */
+export type WillSetValuesCallback<Schema extends OptionalValuesSchema> = (
+  values: Values<Schema>,
+) => Values<Schema> | undefined;
+
+/**
+ * The WillSetValueCallback type describes a function that is called before a
+ * Value is set in the Store.
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * (
+ *   valueId: Id,
+ *   value: Value,
+ * ) => ValueOrUndefined;
+ * ```
+ *
+ * The callback receives the value Id and the Value that is about to be set. It
+ * can return the Value (possibly transformed) to allow the write, or
+ * `undefined` to prevent the Value from being set.
+ *
+ * Multiple WillSetValueCallback functions can be registered and they will be
+ * called sequentially, the Value being updated successively. If any callback
+ * returns `undefined`, the chain short-circuits and the Value will not be set.
+ * @param valueId The Id of the Value being set.
+ * @param value The Value about to be set.
+ * @returns The Value to use (possibly transformed), or `undefined` to prevent
+ * the write.
+ * @category Callback
+ * @since v8.0.0
+ */
+export type WillSetValueCallback<
+  Schema extends OptionalValuesSchema,
+  Params extends any[] = ValueIdFromSchema<Schema> extends infer ValueId
+    ? ValueId extends ValueIdFromSchema<Schema>
+      ? [valueId: ValueId, value: Value<Schema, ValueId>]
+      : never
+    : never,
+> = (
+  ...params: Params | [valueId: never, value: never]
+) => Params[1] | undefined;
+
+/**
+ * The WillDelTablesCallback type describes a function that is called before all
+ * Tables are deleted from the Store.
+ *
+ * The callback takes no parameters. It returns `true` to allow the deletion, or
+ * `false` to prevent it.
+ *
+ * Multiple WillDelTablesCallback functions can be registered and they will be
+ * called sequentially. If any callback returns `false`, the chain
+ * short-circuits and the Tables will not be deleted.
+ * @returns `true` to allow the deletion, `false` to prevent it.
+ * @category Callback
+ * @since v8.0.0
+ */
+export type WillDelTablesCallback = () => boolean;
+
+/**
+ * The WillDelTableCallback type describes a function that is called before a
+ * Table is deleted from the Store.
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * (tableId: Id) => boolean;
+ * ```
+ *
+ * The callback receives the table Id of the Table about to be deleted. It
+ * returns `true` to allow the deletion, or `false` to prevent it.
+ *
+ * Multiple WillDelTableCallback functions can be registered and they will be
+ * called sequentially. If any callback returns `false`, the chain
+ * short-circuits and the Table will not be deleted.
+ * @param tableId The Id of the Table being deleted.
+ * @returns `true` to allow the deletion, `false` to prevent it.
+ * @category Callback
+ * @since v8.0.0
+ */
+export type WillDelTableCallback<
+  Schema extends OptionalTablesSchema,
+  Params extends any[] = TableIdFromSchema<Schema> extends infer TableId
+    ? TableId extends TableIdFromSchema<Schema>
+      ? [tableId: TableId]
+      : never
+    : never,
+> = (...params: Params | [tableId: never]) => boolean;
+
+/**
+ * The WillDelRowCallback type describes a function that is called before a
+ * Row is deleted from the Store.
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * (tableId: Id, rowId: Id) => boolean;
+ * ```
+ *
+ * The callback receives the table Id and row Id of the Row about to be
+ * deleted. It returns `true` to allow the deletion, or `false` to prevent it.
+ *
+ * Multiple WillDelRowCallback functions can be registered and they will be
+ * called sequentially. If any callback returns `false`, the chain
+ * short-circuits and the Row will not be deleted.
+ * @param tableId The Id of the Table containing the Row.
+ * @param rowId The Id of the Row being deleted.
+ * @returns `true` to allow the deletion, `false` to prevent it.
+ * @category Callback
+ * @since v8.0.0
+ */
+export type WillDelRowCallback<
+  Schema extends OptionalTablesSchema,
+  Params extends any[] = TableIdFromSchema<Schema> extends infer TableId
+    ? TableId extends TableIdFromSchema<Schema>
+      ? [tableId: TableId, rowId: Id]
+      : never
+    : never,
+> = (...params: Params | [tableId: never, rowId: never]) => boolean;
+
+/**
+ * The WillDelCellCallback type describes a function that is called before a
+ * Cell is deleted from the Store.
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * (
+ *   tableId: Id,
+ *   rowId: Id,
+ *   cellId: Id,
+ * ) => boolean;
+ * ```
+ *
+ * The callback receives the table Id, row Id, and cell Id of the Cell about to
+ * be deleted. It returns `true` to allow the deletion, or `false` to prevent
+ * it.
+ *
+ * Multiple WillDelCellCallback functions can be registered and they will be
+ * called sequentially. If any callback returns `false`, the chain
+ * short-circuits and the Cell will not be deleted.
+ * @param tableId The Id of the Table containing the Cell.
+ * @param rowId The Id of the Row containing the Cell.
+ * @param cellId The Id of the Cell being deleted.
+ * @returns `true` to allow the deletion, `false` to prevent it.
+ * @category Callback
+ * @since v8.0.0
+ */
+export type WillDelCellCallback<
+  Schema extends OptionalTablesSchema,
+  Params extends any[] = TableIdFromSchema<Schema> extends infer TableId
+    ? TableId extends TableIdFromSchema<Schema>
+      ? CellIdFromSchema<Schema, TableId> extends infer CellId
+        ? CellId extends CellIdFromSchema<Schema, TableId>
+          ? [tableId: TableId, rowId: Id, cellId: CellId]
+          : never
+        : never
+      : never
+    : never,
+> = (
+  ...params: Params | [tableId: never, rowId: never, cellId: never]
+) => boolean;
+
+/**
+ * The WillDelValuesCallback type describes a function that is called before all
+ * Values are deleted from the Store.
+ *
+ * The callback takes no parameters. It returns `true` to allow the deletion, or
+ * `false` to prevent it.
+ *
+ * Multiple WillDelValuesCallback functions can be registered and they will be
+ * called sequentially. If any callback returns `false`, the chain
+ * short-circuits and the Values will not be deleted.
+ * @returns `true` to allow the deletion, `false` to prevent it.
+ * @category Callback
+ * @since v8.0.0
+ */
+export type WillDelValuesCallback = () => boolean;
+
+/**
+ * The WillDelValueCallback type describes a function that is called before a
+ * Value is deleted from the Store.
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * (valueId: Id) => boolean;
+ * ```
+ *
+ * The callback receives the value Id of the Value about to be deleted. It
+ * returns `true` to allow the deletion, or `false` to prevent it.
+ *
+ * Multiple WillDelValueCallback functions can be registered and they will be
+ * called sequentially. If any callback returns `false`, the chain
+ * short-circuits and the Value will not be deleted.
+ * @param valueId The Id of the Value being deleted.
+ * @returns `true` to allow the deletion, `false` to prevent it.
+ * @category Callback
+ * @since v8.0.0
+ */
+export type WillDelValueCallback<
+  Schema extends OptionalValuesSchema,
+  Params extends any[] = ValueIdFromSchema<Schema> extends infer ValueId
+    ? ValueId extends ValueIdFromSchema<Schema>
+      ? [valueId: ValueId]
+      : never
+    : never,
+> = (...params: Params | [valueId: never]) => boolean;
+
+/**
+ * The WillApplyChangesCallback type describes a function that is called before
+ * Changes are applied to the Store.
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * (
+ *   changes: Changes,
+ * ) => Changes | undefined;
+ * ```
+ *
+ * The callback receives the Changes object that is about to be applied. It can
+ * return the Changes (possibly transformed) to allow the write, or `undefined`
+ * to prevent the Changes from being applied.
+ *
+ * Multiple WillApplyChangesCallback functions can be registered and they will
+ * be called sequentially, the Changes being updated successively. If any
+ * callback returns `undefined`, the chain short-circuits and the Changes will
+ * not be applied.
+ * @param changes The Changes about to be applied.
+ * @returns The Changes to use (possibly transformed), or `undefined` to
+ * prevent the write.
+ * @category Callback
+ * @since v8.0.0
+ */
+export type WillApplyChangesCallback<Schemas extends OptionalSchemas> = (
+  changes: Changes<Schemas>,
+) => Changes<Schemas> | undefined;
+
+/**
+ * A Middleware object lets you intercept and validate writes to a Store.
+ *
+ * This is useful for enforcing business rules, data validation, or
+ * transformation logic before data is persisted in the Store.
+ *
+ * Create a Middleware object easily with the createMiddleware function.
+ * @example
+ * This example shows a very simple lifecycle of a Middleware object: from
+ * creation, to getting the Store reference, and then destroying it.
+ *
+ * ```js
+ * import {createMiddleware, createStore} from 'tinybase';
+ *
+ * const store = createStore();
+ * const middleware = createMiddleware(store);
+ *
+ * console.log(middleware.getStore() == store);
+ * // -> true
+ *
+ * middleware.destroy();
+ * ```
+ * @category Middleware
+ * @since v8.0.0
+ */
+export interface Middleware<in out Schemas extends OptionalSchemas> {
+  /**
+   * The getStore method returns a reference to the underlying Store that is
+   * backing this Middleware object.
+   * @returns A reference to the Store.
+   * @example
+   * This example creates a Middleware object against a newly-created Store and
+   * then gets its reference in order to update its data.
+   *
+   * This has schema-based typing. The following is a simplified representation:
+   *
+   * ```ts override
+   * getStore(): Store;
+   * ```
+   *
+   * ```js
+   * import {createMiddleware, createStore} from 'tinybase';
+   *
+   * const middleware = createMiddleware(createStore());
+   * console.log(middleware.getStore().getTables());
+   * // -> {}
+   * middleware.destroy();
+   * ```
+   * @category Getter
+   * @since v8.0.0
+   */
+  getStore(): Store<Schemas>;
+
+  /**
+   * The addWillSetContentCallback method registers a
+   * WillSetContentCallback that will be called before Content is set in the
+   * Store.
+   *
+   * This has schema-based typing. The following is a simplified representation:
+   *
+   * ```ts override
+   * addWillSetContentCallback(callback: WillSetContentCallback): Middleware;
+   * ```
+   *
+   * The callback can transform the Content or return `undefined` to prevent
+   * the write. Multiple callbacks can be registered and they are called
+   * sequentially, each receiving the (possibly transformed) Content from
+   * the previous callback.
+   * @param callback The WillSetContentCallback to register.
+   * @returns A reference to the Middleware object, for chaining.
+   * @example
+   * This example registers a callback that prevents setting Content with
+   * empty Tables in the pet store.
+   *
+   * ```js
+   * import {createMiddleware, createStore} from 'tinybase';
+   *
+   * const store = createStore();
+   * const middleware = createMiddleware(store);
+   *
+   * middleware.addWillSetContentCallback(([tables, values]) =>
+   *   Object.keys(tables).length > 0 ? [tables, values] : undefined,
+   * );
+   *
+   * store.setContent([{}, {open: true}]);
+   * console.log(store.getContent());
+   * // -> [{}, {}]
+   *
+   * store.setContent([{pets: {fido: {species: 'dog'}}}, {}]);
+   * console.log(store.getContent());
+   * // -> [{pets: {fido: {species: 'dog'}}}, {}]
+   *
+   * middleware.destroy();
+   * ```
+   * @category Configuration
+   * @since v8.0.0
+   */
+  addWillSetContentCallback(
+    callback: WillSetContentCallback<Schemas>,
+  ): Middleware<Schemas>;
+
+  /**
+   * The addWillSetTablesCallback method registers a WillSetTablesCallback that
+   * will be called before Tables are set in the Store.
+   *
+   * This has schema-based typing. The following is a simplified representation:
+   *
+   * ```ts override
+   * addWillSetTablesCallback(callback: WillSetTablesCallback): Middleware;
+   * ```
+   *
+   * The callback can transform the Tables or return `undefined` to prevent the
+   * write. Multiple callbacks can be registered and they are called
+   * sequentially, each receiving the (possibly transformed) tables from the
+   * previous callback.
+   * @param callback The WillSetTablesCallback to register.
+   * @returns A reference to the Middleware object, for chaining.
+   * @example
+   * This example registers a callback that upper-cases all string Cell values
+   * when entire Tables are set in the pet store.
+   *
+   * ```js
+   * import {createMiddleware, createStore} from 'tinybase';
+   *
+   * const store = createStore();
+   * const middleware = createMiddleware(store);
+   *
+   * middleware.addWillSetTablesCallback((tables) =>
+   *   Object.fromEntries(
+   *     Object.entries(tables).map(([tableId, table]) => [
+   *       tableId,
+   *       Object.fromEntries(
+   *         Object.entries(table).map(([rowId, row]) => [
+   *           rowId,
+   *           Object.fromEntries(
+   *             Object.entries(row).map(([k, v]) => [
+   *               k,
+   *               typeof v === 'string' ? v.toUpperCase() : v,
+   *             ]),
+   *           ),
+   *         ]),
+   *       ),
+   *     ]),
+   *   ),
+   * );
+   *
+   * store.setTables({pets: {fido: {species: 'dog'}, felix: {species: 'cat'}}});
+   * console.log(store.getTables());
+   * // -> {pets: {fido: {species: 'DOG'}, felix: {species: 'CAT'}}}
+   *
+   * middleware.destroy();
+   * ```
+   * @example
+   * This example registers a callback that prevents setting any Tables that
+   * include a 'banned' table.
+   *
+   * ```js
+   * import {createMiddleware, createStore} from 'tinybase';
+   *
+   * const store = createStore();
+   * const middleware = createMiddleware(store);
+   *
+   * middleware.addWillSetTablesCallback((tables) =>
+   *   'banned' in tables ? undefined : tables,
+   * );
+   *
+   * store.setTables({banned: {r1: {c1: 1}}, pets: {fido: {species: 'dog'}}});
+   * console.log(store.getTables());
+   * // -> {}
+   *
+   * middleware.destroy();
+   * ```
+   * @category Configuration
+   * @since v8.0.0
+   */
+  addWillSetTablesCallback(
+    callback: WillSetTablesCallback<Schemas[0]>,
+  ): Middleware<Schemas>;
+
+  /**
+   * The addWillSetTableCallback method registers a WillSetTableCallback that
+   * will be called before any Table is set in the Store.
+   *
+   * This has schema-based typing. The following is a simplified representation:
+   *
+   * ```ts override
+   * addWillSetTableCallback(callback: WillSetTableCallback): Middleware;
+   * ```
+   *
+   * The callback can transform the Table or return `undefined` to prevent the
+   * write. Multiple callbacks can be registered and they are called
+   * sequentially, each receiving the (possibly transformed) table from the
+   * previous callback.
+   * @param callback The WillSetTableCallback to register.
+   * @returns A reference to the Middleware object, for chaining.
+   * @example
+   * This example registers a callback that upper-cases string Cell values in
+   * rows set to the 'pets' table.
+   *
+   * ```js
+   * import {createMiddleware, createStore} from 'tinybase';
+   *
+   * const store = createStore();
+   * const middleware = createMiddleware(store);
+   *
+   * middleware.addWillSetTableCallback((tableId, table) =>
+   *   tableId === 'pets'
+   *     ? Object.fromEntries(
+   *         Object.entries(table).map(([rowId, row]) => [
+   *           rowId,
+   *           Object.fromEntries(
+   *             Object.entries(row).map(([k, v]) => [
+   *               k,
+   *               typeof v === 'string' ? v.toUpperCase() : v,
+   *             ]),
+   *           ),
+   *         ]),
+   *       )
+   *     : table,
+   * );
+   *
+   * store.setTable('pets', {fido: {species: 'dog'}, felix: {species: 'cat'}});
+   * console.log(store.getTable('pets'));
+   * // -> {fido: {species: 'DOG'}, felix: {species: 'CAT'}}
+   *
+   * middleware.destroy();
+   * ```
+   * @example
+   * This example registers a callback that prevents writes to the 'species'
+   * table.
+   *
+   * ```js
+   * import {createMiddleware, createStore} from 'tinybase';
+   *
+   * const store = createStore();
+   * const middleware = createMiddleware(store);
+   *
+   * middleware.addWillSetTableCallback((tableId, table) =>
+   *   tableId === 'species' ? undefined : table,
+   * );
+   *
+   * store.setTable('species', {dog: {legs: 4, sound: 'woof'}});
+   * console.log(store.getTables());
+   * // -> {}
+   *
+   * middleware.destroy();
+   * ```
+   * @category Configuration
+   * @since v8.0.0
+   */
+  addWillSetTableCallback(
+    callback: WillSetTableCallback<Schemas[0]>,
+  ): Middleware<Schemas>;
+
+  /**
+   * The addWillSetRowCallback method registers a WillSetRowCallback that will
+   * be called before any Row is set in the Store.
+   *
+   * This has schema-based typing. The following is a simplified representation:
+   *
+   * ```ts override
+   * addWillSetRowCallback(callback: WillSetRowCallback): Middleware;
+   * ```
+   *
+   * The callback can transform the Row or return `undefined` to prevent the
+   * write. Multiple callbacks can be registered and they are called
+   * sequentially, each receiving the (possibly transformed) row from the
+   * previous callback.
+   * @param callback The WillSetRowCallback to register.
+   * @returns A reference to the Middleware object, for chaining.
+   * @example
+   * This example registers a callback that upper-cases string Cell values in
+   * rows set to the 'pets' table.
+   *
+   * ```js
+   * import {createMiddleware, createStore} from 'tinybase';
+   *
+   * const store = createStore();
+   * const middleware = createMiddleware(store);
+   *
+   * middleware.addWillSetRowCallback((tableId, _rowId, row) =>
+   *   tableId === 'pets'
+   *     ? Object.fromEntries(
+   *         Object.entries(row).map(([k, v]) => [
+   *           k,
+   *           typeof v === 'string' ? v.toUpperCase() : v,
+   *         ]),
+   *       )
+   *     : row,
+   * );
+   *
+   * store.setRow('pets', 'fido', {species: 'dog', legs: 4});
+   * console.log(store.getRow('pets', 'fido'));
+   * // -> {species: 'DOG', legs: 4}
+   *
+   * middleware.destroy();
+   * ```
+   * @example
+   * This example registers a callback that prevents writes to the 'species'
+   * table.
+   *
+   * ```js
+   * import {createMiddleware, createStore} from 'tinybase';
+   *
+   * const store = createStore();
+   * const middleware = createMiddleware(store);
+   *
+   * middleware.addWillSetRowCallback((tableId, _rowId, row) =>
+   *   tableId === 'species' ? undefined : row,
+   * );
+   *
+   * store.setRow('species', 'dog', {legs: 4, sound: 'woof'});
+   * console.log(store.getTables());
+   * // -> {}
+   *
+   * middleware.destroy();
+   * ```
+   * @category Configuration
+   * @since v8.0.0
+   */
+  addWillSetRowCallback(
+    callback: WillSetRowCallback<Schemas[0]>,
+  ): Middleware<Schemas>;
+
+  /**
+   * The addWillSetCellCallback method registers a WillSetCellCallback that will
+   * be called before any Cell is set in the Store.
+   *
+   * This has schema-based typing. The following is a simplified representation:
+   *
+   * ```ts override
+   * addWillSetCellCallback(callback: WillSetCellCallback): Middleware;
+   * ```
+   *
+   * The callback can transform the Cell value or return `undefined` to prevent
+   * the write. Multiple callbacks can be registered and they are called
+   * sequentially, each receiving the (possibly transformed) value from the
+   * previous callback.
+   * @param callback The WillSetCellCallback to register.
+   * @returns A reference to the Middleware object, for chaining.
+   * @example
+   * This example registers a callback that upper-cases string Cell values in
+   * the 'pets' table.
+   *
+   * ```js
+   * import {createMiddleware, createStore} from 'tinybase';
+   *
+   * const store = createStore();
+   * const middleware = createMiddleware(store);
+   *
+   * middleware.addWillSetCellCallback((tableId, rowId, cellId, cell) =>
+   *   tableId === 'pets' && typeof cell === 'string'
+   *     ? cell.toUpperCase()
+   *     : cell,
+   * );
+   *
+   * store.setCell('pets', 'fido', 'species', 'dog');
+   * console.log(store.getCell('pets', 'fido', 'species'));
+   * // -> 'DOG'
+   *
+   * middleware.destroy();
+   * ```
+   * @example
+   * This example registers a callback that prevents writes to the 'species'
+   * table.
+   *
+   * ```js
+   * import {createMiddleware, createStore} from 'tinybase';
+   *
+   * const store = createStore();
+   * const middleware = createMiddleware(store);
+   *
+   * middleware.addWillSetCellCallback((tableId, _rowId, _cellId, cell) =>
+   *   tableId === 'species' ? undefined : cell,
+   * );
+   *
+   * store.setCell('species', 'dog', 'legs', 4);
+   * console.log(store.getTables());
+   * // -> {}
+   *
+   * middleware.destroy();
+   * ```
+   * @category Configuration
+   * @since v8.0.0
+   */
+  addWillSetCellCallback(
+    callback: WillSetCellCallback<Schemas[0]>,
+  ): Middleware<Schemas>;
+
+  /**
+   * The addWillSetValuesCallback method registers a WillSetValuesCallback that
+   * will be called before Values are set in the Store.
+   *
+   * This has schema-based typing. The following is a simplified representation:
+   *
+   * ```ts override
+   * addWillSetValuesCallback(callback: WillSetValuesCallback): Middleware;
+   * ```
+   *
+   * The callback can transform the Values or return `undefined` to prevent the
+   * write. Multiple callbacks can be registered and they are called
+   * sequentially, each receiving the (possibly transformed) values from the
+   * previous callback.
+   * @param callback The WillSetValuesCallback to register.
+   * @returns A reference to the Middleware object, for chaining.
+   * @example
+   * This example registers a callback that upper-cases all string Values in the
+   * pet store's settings.
+   *
+   * ```js
+   * import {createMiddleware, createStore} from 'tinybase';
+   *
+   * const store = createStore();
+   * const middleware = createMiddleware(store);
+   *
+   * middleware.addWillSetValuesCallback((values) =>
+   *   Object.fromEntries(
+   *     Object.entries(values).map(([k, v]) => [
+   *       k,
+   *       typeof v === 'string' ? v.toUpperCase() : v,
+   *     ]),
+   *   ),
+   * );
+   *
+   * store.setValues({storeName: 'happy pets', limit: 50});
+   * console.log(store.getValues());
+   * // -> {storeName: 'HAPPY PETS', limit: 50}
+   *
+   * middleware.destroy();
+   * ```
+   * @example
+   * This example registers a callback that prevents setting Values when the pet
+   * store is 'closed'.
+   *
+   * ```js
+   * import {createMiddleware, createStore} from 'tinybase';
+   *
+   * const store = createStore();
+   * const middleware = createMiddleware(store);
+   *
+   * middleware.addWillSetValuesCallback((values) =>
+   *   'closed' in values ? undefined : values,
+   * );
+   *
+   * store.setValues({closed: true, storeName: 'happy pets'});
+   * console.log(store.getValues());
+   * // -> {}
+   *
+   * middleware.destroy();
+   * ```
+   * @category Configuration
+   * @since v8.0.0
+   */
+  addWillSetValuesCallback(
+    callback: WillSetValuesCallback<Schemas[1]>,
+  ): Middleware<Schemas>;
+
+  /**
+   * The addWillSetValueCallback method registers a WillSetValueCallback that
+   * will be called before any Value is set in the Store.
+   *
+   * This has schema-based typing. The following is a simplified representation:
+   *
+   * ```ts override
+   * addWillSetValueCallback(callback: WillSetValueCallback): Middleware;
+   * ```
+   *
+   * The callback can transform the Value or return `undefined` to prevent the
+   * write. Multiple callbacks can be registered and they are called
+   * sequentially, each receiving the (possibly transformed) value from the
+   * previous callback.
+   * @param callback The WillSetValueCallback to register.
+   * @returns A reference to the Middleware object, for chaining.
+   * @example
+   * This example registers a callback that clamps the 'limit' Value to the
+   * maximum capacity of the pet store.
+   *
+   * ```js
+   * import {createMiddleware, createStore} from 'tinybase';
+   *
+   * const store = createStore();
+   * const middleware = createMiddleware(store);
+   *
+   * middleware.addWillSetValueCallback((valueId, value) =>
+   *   valueId === 'limit' && typeof value === 'number'
+   *     ? Math.min(50, Math.max(0, value))
+   *     : value,
+   * );
+   *
+   * store.setValue('limit', 100);
+   * console.log(store.getValue('limit'));
+   * // -> 50
+   *
+   * middleware.destroy();
+   * ```
+   * @category Configuration
+   * @since v8.0.0
+   */
+  addWillSetValueCallback(
+    callback: WillSetValueCallback<Schemas[1]>,
+  ): Middleware<Schemas>;
+
+  /**
+   * The addWillDelTablesCallback method registers a WillDelTablesCallback that
+   * will be called before all Tables are deleted from the Store.
+   *
+   * This has schema-based typing. The following is a simplified representation:
+   *
+   * ```ts override
+   * addWillDelTablesCallback(callback: WillDelTablesCallback): Middleware;
+   * ```
+   *
+   * The callback returns `true` to allow the deletion or `false` to prevent
+   * it. Multiple callbacks can be registered and they are called sequentially.
+   * If any callback returns `false`, the deletion is prevented.
+   * @param callback The WillDelTablesCallback to register.
+   * @returns A reference to the Middleware object, for chaining.
+   * @example
+   * This example registers a callback that prevents deleting all Tables from
+   * the pet store.
+   *
+   * ```js
+   * import {createMiddleware, createStore} from 'tinybase';
+   *
+   * const store = createStore();
+   * const middleware = createMiddleware(store);
+   *
+   * store.setTables({pets: {fido: {species: 'dog'}, felix: {species: 'cat'}}});
+   *
+   * middleware.addWillDelTablesCallback(() => false);
+   *
+   * store.delTables();
+   * console.log(store.getTables());
+   * // -> {pets: {fido: {species: 'dog'}, felix: {species: 'cat'}}}
+   *
+   * middleware.destroy();
+   * ```
+   * @category Configuration
+   * @since v8.0.0
+   */
+  addWillDelTablesCallback(
+    callback: WillDelTablesCallback,
+  ): Middleware<Schemas>;
+
+  /**
+   * The addWillDelTableCallback method registers a WillDelTableCallback that
+   * will be called before any Table is deleted from the Store.
+   *
+   * This has schema-based typing. The following is a simplified representation:
+   *
+   * ```ts override
+   * addWillDelTableCallback(callback: WillDelTableCallback): Middleware;
+   * ```
+   *
+   * The callback returns `true` to allow the deletion or `false` to prevent
+   * it. Multiple callbacks can be registered and they are called sequentially.
+   * If any callback returns `false`, the deletion is prevented.
+   * @param callback The WillDelTableCallback to register.
+   * @returns A reference to the Middleware object, for chaining.
+   * @example
+   * This example registers a callback that prevents deleting the 'pets' table
+   * from the pet store.
+   *
+   * ```js
+   * import {createMiddleware, createStore} from 'tinybase';
+   *
+   * const store = createStore();
+   * const middleware = createMiddleware(store);
+   *
+   * store.setTable('pets', {fido: {species: 'dog'}, felix: {species: 'cat'}});
+   *
+   * middleware.addWillDelTableCallback((tableId) => tableId !== 'pets');
+   *
+   * store.delTable('pets');
+   * console.log(store.getTable('pets'));
+   * // -> {fido: {species: 'dog'}, felix: {species: 'cat'}}
+   *
+   * middleware.destroy();
+   * ```
+   * @category Configuration
+   * @since v8.0.0
+   */
+  addWillDelTableCallback(
+    callback: WillDelTableCallback<Schemas[0]>,
+  ): Middleware<Schemas>;
+
+  /**
+   * The addWillDelRowCallback method registers a WillDelRowCallback that will
+   * be called before any Row is deleted from the Store.
+   *
+   * This has schema-based typing. The following is a simplified representation:
+   *
+   * ```ts override
+   * addWillDelRowCallback(callback: WillDelRowCallback): Middleware;
+   * ```
+   *
+   * The callback returns `true` to allow the deletion or `false` to prevent it.
+   * Multiple callbacks can be registered and they are called sequentially. If
+   * any callback returns `false`, the deletion is prevented.
+   * @param callback The WillDelRowCallback to register.
+   * @returns A reference to the Middleware object, for chaining.
+   * @example
+   * This example registers a callback that prevents deleting rows from the
+   * 'pets' table.
+   *
+   * ```js
+   * import {createMiddleware, createStore} from 'tinybase';
+   *
+   * const store = createStore();
+   * const middleware = createMiddleware(store);
+   *
+   * store.setRow('pets', 'fido', {species: 'dog', legs: 4});
+   *
+   * middleware.addWillDelRowCallback((tableId) => tableId !== 'pets');
+   *
+   * store.delRow('pets', 'fido');
+   * console.log(store.getRow('pets', 'fido'));
+   * // -> {species: 'dog', legs: 4}
+   *
+   * middleware.destroy();
+   * ```
+   * @category Configuration
+   * @since v8.0.0
+   */
+  addWillDelRowCallback(
+    callback: WillDelRowCallback<Schemas[0]>,
+  ): Middleware<Schemas>;
+
+  /**
+   * The addWillDelCellCallback method registers a WillDelCellCallback that will
+   * be called before any Cell is deleted from the Store.
+   *
+   * This has schema-based typing. The following is a simplified representation:
+   *
+   * ```ts override
+   * addWillDelCellCallback(callback: WillDelCellCallback): Middleware;
+   * ```
+   *
+   * The callback returns `true` to allow the deletion or `false` to prevent it.
+   * Multiple callbacks can be registered and they are called sequentially. If
+   * any callback returns `false`, the deletion is prevented.
+   * @param callback The WillDelCellCallback to register.
+   * @returns A reference to the Middleware object, for chaining.
+   * @example
+   * This example registers a callback that prevents deleting cells from the
+   * 'pets' table.
+   *
+   * ```js
+   * import {createMiddleware, createStore} from 'tinybase';
+   *
+   * const store = createStore();
+   * const middleware = createMiddleware(store);
+   *
+   * store.setCell('pets', 'fido', 'species', 'dog');
+   *
+   * middleware.addWillDelCellCallback((tableId) => tableId !== 'pets');
+   *
+   * store.delCell('pets', 'fido', 'species', true);
+   * console.log(store.getCell('pets', 'fido', 'species'));
+   * // -> 'dog'
+   *
+   * middleware.destroy();
+   * ```
+   * @category Configuration
+   * @since v8.0.0
+   */
+  addWillDelCellCallback(
+    callback: WillDelCellCallback<Schemas[0]>,
+  ): Middleware<Schemas>;
+
+  /**
+   * The addWillDelValuesCallback method registers a WillDelValuesCallback that
+   * will be called before all Values are deleted from the Store.
+   *
+   * This has schema-based typing. The following is a simplified representation:
+   *
+   * ```ts override
+   * addWillDelValuesCallback(callback: WillDelValuesCallback): Middleware;
+   * ```
+   *
+   * The callback returns `true` to allow the deletion or `false` to prevent it.
+   * Multiple callbacks can be registered and they are called sequentially. If
+   * any callback returns `false`, the deletion is prevented.
+   * @param callback The WillDelValuesCallback to register.
+   * @returns A reference to the Middleware object, for chaining.
+   * @example
+   * This example registers a callback that prevents deleting all Values from
+   * the pet store.
+   *
+   * ```js
+   * import {createMiddleware, createStore} from 'tinybase';
+   *
+   * const store = createStore();
+   * const middleware = createMiddleware(store);
+   *
+   * store.setValues({storeName: 'happy pets', limit: 50});
+   *
+   * middleware.addWillDelValuesCallback(() => false);
+   *
+   * store.delValues();
+   * console.log(store.getValues());
+   * // -> {storeName: 'happy pets', limit: 50}
+   *
+   * middleware.destroy();
+   * ```
+   * @category Configuration
+   * @since v8.0.0
+   */
+  addWillDelValuesCallback(
+    callback: WillDelValuesCallback,
+  ): Middleware<Schemas>;
+
+  /**
+   * The addWillDelValueCallback method registers a WillDelValueCallback that
+   * will be called before any Value is deleted from the Store.
+   *
+   * This has schema-based typing. The following is a simplified representation:
+   *
+   * ```ts override
+   * addWillDelValueCallback(callback: WillDelValueCallback): Middleware;
+   * ```
+   *
+   * The callback returns `true` to allow the deletion or `false` to prevent it.
+   * Multiple callbacks can be registered and they are called sequentially. If
+   * any callback returns `false`, the deletion is prevented.
+   * @param callback The WillDelValueCallback to register.
+   * @returns A reference to the Middleware object, for chaining.
+   * @example
+   * This example registers a callback that prevents deleting the 'storeName'
+   * Value from the pet store.
+   *
+   * ```js
+   * import {createMiddleware, createStore} from 'tinybase';
+   *
+   * const store = createStore();
+   * const middleware = createMiddleware(store);
+   *
+   * store.setValue('storeName', 'happy pets');
+   *
+   * middleware.addWillDelValueCallback((valueId) => valueId !== 'storeName');
+   *
+   * store.delValue('storeName');
+   * console.log(store.getValue('storeName'));
+   * // -> 'happy pets'
+   *
+   * middleware.destroy();
+   * ```
+   * @category Configuration
+   * @since v8.0.0
+   */
+  addWillDelValueCallback(
+    callback: WillDelValueCallback<Schemas[1]>,
+  ): Middleware<Schemas>;
+
+  /**
+   * The addWillApplyChangesCallback method registers a
+   * WillApplyChangesCallback that will be called before Changes are applied to
+   * the Store via the applyChanges method.
+   *
+   * This has schema-based typing. The following is a simplified representation:
+   *
+   * ```ts override
+   * addWillApplyChangesCallback(callback: WillApplyChangesCallback): Middleware;
+   * ```
+   *
+   * This callback receives the Changes object and can return it (to allow),
+   * return a modified Changes object (to transform), or return `undefined` (to
+   * reject). Multiple callbacks can be registered and they are called
+   * sequentially, each receiving the output of the previous. If any callback
+   * returns `undefined`, all remaining callbacks are skipped and the changes
+   * are rejected.
+   *
+   * This fires when applyChanges is called directly, or indirectly via
+   * applyMergeableChanges, setMergeableContent, or merge on a MergeableStore.
+   * @param callback The WillApplyChangesCallback to register.
+   * @returns A reference to the Middleware object, for chaining.
+   * @example
+   * This example registers a callback that rejects changes containing a
+   * 'secret' table.
+   *
+   * ```js
+   * import {createMiddleware, createStore} from 'tinybase';
+   *
+   * const store = createStore();
+   * const middleware = createMiddleware(store);
+   *
+   * middleware.addWillApplyChangesCallback(([changedTables, changedValues]) =>
+   *   changedTables['secret'] != null
+   *     ? undefined
+   *     : [changedTables, changedValues, 1],
+   * );
+   *
+   * store.applyChanges([{pets: {fido: {species: 'dog'}}}, {}, 1]);
+   * console.log(store.getRow('pets', 'fido'));
+   * // -> {species: 'dog'}
+   *
+   * store.applyChanges([{secret: {r1: {c1: 'v1'}}}, {}, 1]);
+   * console.log(store.getTable('secret'));
+   * // -> {}
+   *
+   * middleware.destroy();
+   * ```
+   * @category Configuration
+   * @since v8.0.0
+   */
+  addWillApplyChangesCallback(
+    callback: WillApplyChangesCallback<Schemas>,
+  ): 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
+   * unregisters the Middleware from the Store.
+   * @example
+   * This example creates a Middleware object against a newly-created Store and
+   * then destroys it.
+   *
+   * ```js
+   * import {createMiddleware, createStore} from 'tinybase';
+   *
+   * const store = createStore();
+   * const middleware = createMiddleware(store);
+   * middleware.destroy();
+   * ```
+   * @category Lifecycle
+   * @since v8.0.0
+   */
+  destroy(): void;
+}
+
+/**
+ * The createMiddleware function creates a Middleware object, and is the main
+ * entry point into the middleware module.
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * createMiddleware(store: Store): Middleware;
+ * ```
+ *
+ * A given Store can only have one Middleware object associated with it. If you
+ * call this function twice on the same Store, your second call will return a
+ * reference to the Middleware object created by the first.
+ * @param store The Store for which to register the Middleware.
+ * @returns A reference to the new Middleware object.
+ * @example
+ * This example creates a Middleware object.
+ *
+ * ```js
+ * import {createMiddleware, createStore} from 'tinybase';
+ *
+ * const store = createStore();
+ * const middleware = createMiddleware(store);
+ * console.log(middleware.getStore() == store);
+ * // -> true
+ * middleware.destroy();
+ * ```
+ * @example
+ * This example creates a Middleware object, and calls the method a second time
+ * for the same Store to return the same object.
+ *
+ * ```js
+ * import {createMiddleware, createStore} from 'tinybase';
+ *
+ * const store = createStore();
+ * const middleware = createMiddleware(store);
+ * console.log(middleware === createMiddleware(store));
+ * // -> true
+ * middleware.destroy();
+ * ```
+ * @category Creation
+ * @since v8.0.0
+ */
+export function createMiddleware<Schemas extends OptionalSchemas>(
+  store: Store<Schemas>,
+): Middleware<Schemas>;