[middleware] Module skeleton

Author: jamesgpearce

gulpfile.mjs

@@ -20,6 +20,7 @@ const ALL_MODULES = [
   'indexes',
   'mergeable-store',
   'metrics',
+  'middleware',
   'persisters',
   'persisters/persister-automerge',
   'persisters/persister-browser',

src/@types/middleware/docs.js

@@ -0,0 +1,117 @@
+/**
+ * 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
+ */
+/// middleware
+/**
+ * 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
+ */
+/// Middleware
+{
+  /**
+   * 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.
+   *
+   * ```js
+   * import {createMiddleware, createStore} from 'tinybase';
+   *
+   * const middleware = createMiddleware(createStore());
+   * console.log(middleware.getStore().getTables());
+   * // -> {}
+   * middleware.destroy();
+   * ```
+   * @category Getter
+   * @since v8.0.0
+   */
+  /// Middleware.getStore
+  /**
+   * 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
+   */
+  /// Middleware.destroy
+}
+/**
+ * The createMiddleware function creates a Middleware object, and is the main
+ * entry point into the middleware module.
+ *
+ * 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
+ */
+/// createMiddleware

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

@@ -0,0 +1,14 @@
+/// middleware
+import type {Store} from '../store/index.d.ts';
+
+/// Middleware
+export interface Middleware {
+  /// Middleware.getStore
+  getStore(): Store;
+
+  /// Middleware.destroy
+  destroy(): void;
+}
+
+/// createMiddleware
+export function createMiddleware(store: Store): Middleware;

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

@@ -0,0 +1,19 @@
+/// middleware
+import type {
+  OptionalSchemas,
+  Store,
+} from '../../store/with-schemas/index.d.ts';
+
+/// Middleware
+export interface Middleware<in out Schemas extends OptionalSchemas> {
+  /// Middleware.getStore
+  getStore(): Store<Schemas>;
+
+  /// Middleware.destroy
+  destroy(): void;
+}
+
+/// createMiddleware
+export function createMiddleware<Schemas extends OptionalSchemas>(
+  store: Store<Schemas>,
+): Middleware<Schemas>;

src/common/definable.ts

@@ -2,6 +2,7 @@ import type {Checkpoints} from '../@types/checkpoints/index.d.ts';
 import type {Id, Ids, SortKey} from '../@types/common/index.d.ts';
 import type {Indexes} from '../@types/indexes/index.d.ts';
 import type {Metrics} from '../@types/metrics/index.d.ts';
+import type {Middleware} from '../@types/middleware/index.d.ts';
 import type {Queries} from '../@types/queries/index.d.ts';
 import type {Relationships} from '../@types/relationships/index.d.ts';
 import type {Cell, GetCell, Store} from '../@types/store/index.d.ts';
@@ -255,7 +256,13 @@ export const getRowCellFunction = <RowValue>(
       ((): RowValue => defaultCellValue ?? (EMPTY_STRING as any as RowValue)));
 
 export const getCreateFunction = <
-  Thing extends Metrics | Indexes | Relationships | Checkpoints | Queries,
+  Thing extends
+    | Metrics
+    | Middleware
+    | Indexes
+    | Relationships
+    | Checkpoints
+    | Queries,
 >(
   getFunction: (store: Store) => Thing,
   initFunction?: (thing: Thing) => void,

src/index.ts

@@ -3,6 +3,7 @@ export * from './common/index.ts';
 export * from './indexes/index.ts';
 export * from './mergeable-store/index.ts';
 export * from './metrics/index.ts';
+export * from './middleware/index.ts';
 export * from './queries/index.ts';
 export * from './relationships/index.ts';
 export * from './store/index.ts';

src/middleware/index.ts

@@ -0,0 +1,22 @@
+import type {
+  Middleware,
+  createMiddleware as createMiddlewareDecl,
+} from '../@types/middleware/index.d.ts';
+import type {Store} from '../@types/store/index.d.ts';
+import {getCreateFunction} from '../common/definable.ts';
+import {objFreeze} from '../common/obj.ts';
+
+export const createMiddleware = getCreateFunction(
+  (store: Store): Middleware => {
+    const getStore = (): Store => store;
+
+    const destroy = (): void => {};
+
+    const middleware: any = {
+      getStore,
+      destroy,
+    };
+
+    return objFreeze(middleware as Middleware);
+  },
+) as typeof createMiddlewareDecl;

src/tsconfig.tsbuildinfo

@@ -0,0 +1,32 @@
+import {beforeEach, describe, expect, test} from 'vitest';
+
+import type {Middleware, Store} from 'tinybase';
+import {createMiddleware, createStore} from 'tinybase';
+
+let store: Store;
+let middleware: Middleware;
+
+beforeEach(() => {
+  store = createStore();
+  middleware = createMiddleware(store);
+});
+
+describe('Creates', () => {
+  test('basic', () => {
+    expect(middleware).toBeDefined();
+  });
+
+  test('getStore', () => {
+    expect(middleware.getStore()).toBe(store);
+  });
+
+  test('same middleware for same store', () => {
+    expect(createMiddleware(store)).toBe(middleware);
+  });
+});
+
+describe('Destroys', () => {
+  test('basic', () => {
+    middleware.destroy();
+  });
+});