tinybase 3.1.0-beta.4 → 3.1.0

package/lib/{cjs → types/with-schemas}/metrics.d.ts

@@ -1,6 +1,6 @@
 /**
- * The metrics module of the TinyBase project provides the ability to create
- * and track metrics and aggregates of the data in Store objects.
+ * The metrics module of the TinyBase project provides the ability to create and
+ * track metrics and aggregates of the data in Store objects.
  *
  * The main entry point to this module is the createMetrics function, which
  * returns a new Metrics object. From there, you can create new Metric
@@ -11,7 +11,8 @@
  * @module metrics
  */
 
-import {GetCell, NoSchemas, OptionalSchemas, Store} from './store.d';
+import {CellIdFromSchema, TableIdFromSchema} from './internal/store';
+import {GetCell, OptionalSchemas, Store} from './store.d';
 import {Id, IdOrNull, Ids} from './common.d';
 
 /**
@@ -37,8 +38,8 @@ export type Metric = number;
 export type MetricCallback = (metricId: Id, metric?: Metric) => void;
 
 /**
- * The Aggregate type describes a custom function that takes an array of numbers
- * and returns an aggregate that is used as a Metric.
+ * The MetricAggregate type describes a custom function that takes an array of
+ * numbers and returns an aggregate that is used as a Metric.
  *
  * There are a number of common predefined aggregators, such as for counting,
  * summing, and averaging values. This type is instead used for when you wish to
@@ -50,12 +51,12 @@ export type MetricCallback = (metricId: Id, metric?: Metric) => void;
  * @returns The value of the Metric.
  * @category Aggregators
  */
-export type Aggregate = (numbers: number[], length: number) => Metric;
+export type MetricAggregate = (numbers: number[], length: number) => Metric;
 
 /**
- * The AggregateAdd type describes a function that can be used to optimize a
- * custom Aggregate by providing a shortcut for when a single value is added to
- * the input values.
+ * The MetricAggregateAdd type describes a function that can be used to optimize
+ * a custom MetricAggregate by providing a shortcut for when a single value is
+ * added to the input values.
  *
  * Some aggregation functions do not need to recalculate the aggregation of the
  * whole set when one value changes. For example, when adding a new number to a
@@ -65,10 +66,10 @@ export type Aggregate = (numbers: number[], length: number) => Metric;
  * being added, return `undefined` and the Metric will be completely
  * recalculated.
  *
- * Where possible, if you are providing a custom Aggregate, seek an
- * implementation of an AggregateAdd function that can reduce the complexity
- * cost of growing the input data set. See the setMetricDefinition method for
- * more examples.
+ * Where possible, if you are providing a custom MetricAggregate, seek an
+ * implementation of an MetricAggregateAdd function that can reduce the
+ * complexity cost of growing the input data set. See the setMetricDefinition
+ * method for more examples.
  *
  * @param metric The current value of the Metric.
  * @param add The number being added to the Metric's aggregation.
@@ -76,16 +77,16 @@ export type Aggregate = (numbers: number[], length: number) => Metric;
  * @returns The new value of the Metric.
  * @category Aggregators
  */
-export type AggregateAdd = (
+export type MetricAggregateAdd = (
   metric: Metric,
   add: number,
   length: number,
 ) => Metric | undefined;
 
 /**
- * The AggregateRemove type describes a function that can be used to optimize a
- * custom Aggregate by providing a shortcut for when a single value is removed
- * from the input values.
+ * The MetricAggregateRemove type describes a function that can be used to
+ * optimize a custom MetricAggregate by providing a shortcut for when a single
+ * value is removed from the input values.
  *
  * Some aggregation functions do not need to recalculate the aggregation of the
  * whole set when one value changes. For example, when removing a number from a
@@ -98,10 +99,10 @@ export type AggregateAdd = (
  * values, and the previous minimum is being removed. The whole of the rest of
  * the list will need to be re-scanned to find a new minimum.
  *
- * Where possible, if you are providing a custom Aggregate, seek an
- * implementation of an AggregateRemove function that can reduce the complexity
- * cost of shrinking the input data set. See the setMetricDefinition method for
- * more examples.
+ * Where possible, if you are providing a custom MetricAggregate, seek an
+ * implementation of an MetricAggregateRemove function that can reduce the
+ * complexity cost of shrinking the input data set. See the setMetricDefinition
+ * method for more examples.
  *
  * @param metric The current value of the Metric.
  * @param remove The number being removed from the Metric's aggregation.
@@ -109,16 +110,16 @@ export type AggregateAdd = (
  * @returns The new value of the Metric.
  * @category Aggregators
  */
-export type AggregateRemove = (
+export type MetricAggregateRemove = (
   metric: Metric,
   remove: number,
   length: number,
 ) => Metric | undefined;
 
 /**
- * The AggregateReplace type describes a function that can be used to optimize a
- * custom Aggregate by providing a shortcut for when a single value in the input
- * values is replaced with another.
+ * The MetricAggregateReplace type describes a function that can be used to
+ * optimize a custom MetricAggregate by providing a shortcut for when a single
+ * value in the input values is replaced with another.
  *
  * Some aggregation functions do not need to recalculate the aggregation of the
  * whole set when one value changes. For example, when replacing a number in a
@@ -126,13 +127,12 @@ export type AggregateRemove = (
  * minus the old value.
  *
  * If it is not possible to shortcut the aggregation based on just one value
- * changing, return `undefined` and the Metric will be completely
- * recalculated.
+ * changing, return `undefined` and the Metric will be completely recalculated.
  *
- * Where possible, if you are providing a custom Aggregate, seek an
- * implementation of an AggregateReplace function that can reduce the complexity
- * cost of changing the input data set in place. See the setMetricDefinition
- * method for more examples.
+ * Where possible, if you are providing a custom MetricAggregate, seek an
+ * implementation of an MetricAggregateReplace function that can reduce the
+ * complexity cost of changing the input data set in place. See the
+ * setMetricDefinition method for more examples.
  *
  * @param metric The current value of the Metric.
  * @param add The number being added to the Metric's aggregation.
@@ -141,7 +141,7 @@ export type AggregateRemove = (
  * @returns The new value of the Metric.
  * @category Aggregators
  */
-export type AggregateReplace = (
+export type MetricAggregateReplace = (
   metric: Metric,
   add: number,
   remove: number,
@@ -152,6 +152,17 @@ export type AggregateReplace = (
  * The MetricListener type describes a function that is used to listen to
  * changes to a Metric.
  *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * (
+ *   metrics: Metrics,
+ *   metricId: Id,
+ *   newMetric: Metric | undefined,
+ *   oldMetric: Metric | undefined,
+ * ) => void;
+ * ```
+ *
  * A MetricListener is provided when using the addMetricListener method. See
  * that method for specific examples.
  *
@@ -168,8 +179,8 @@ export type AggregateReplace = (
  * @param oldMetric The old value of the Metric that changed.
  * @category Listener
  */
-export type MetricListener = (
-  metrics: Metrics,
+export type MetricListener<Schemas extends OptionalSchemas> = (
+  metrics: Metrics<Schemas>,
   metricId: Id,
   newMetric: Metric | undefined,
   oldMetric: Metric | undefined,
@@ -246,10 +257,24 @@ export type MetricsListenerStats = {
  * @see Todo App demos
  * @category Metrics
  */
-export interface Metrics<Schemas extends OptionalSchemas = NoSchemas> {
+export interface Metrics<in out Schemas extends OptionalSchemas> {
   /**
    * The setMetricDefinition method lets you set the definition of a Metric.
    *
+   * This has schema-based typing. The following is a simplified representation:
+   *
+   * ```ts override
+   * setMetricDefinition(
+   *   metricId: Id,
+   *   tableId: Id,
+   *   aggregate?: 'sum' | 'avg' | 'min' | 'max' | MetricAggregate,
+   *   getNumber?: Id | ((getCell: GetCell, rowId: Id) => number),
+   *   aggregateAdd?: MetricAggregateAdd,
+   *   aggregateRemove?: MetricAggregateRemove,
+   *   aggregateReplace?: MetricAggregateReplace,
+   * ): Metrics;
+   * ```
+   *
    * Every Metric definition is identified by a unique Id, and if you re-use an
    * existing Id with this method, the previous definition is overwritten.
    *
@@ -287,14 +312,14 @@ export interface Metrics<Schemas extends OptionalSchemas = NoSchemas> {
    * that if the `aggregate` and `getNumber` parameters are both omitted, the
    * Metric will simply be a count of the Row objects in the Table).
    * @param aggregateAdd A function that can be used to optimize a custom
-   * Aggregate by providing a shortcut for when a single value is added to the
-   * input values - for example, when a Row is added to the Table.
+   * MetricAggregate by providing a shortcut for when a single value is added to
+   * the input values - for example, when a Row is added to the Table.
    * @param aggregateRemove A function that can be used to optimize a custom
-   * Aggregate by providing a shortcut for when a single value is removed from
-   * the input values - for example ,when a Row is removed from the Table.
+   * MetricAggregate by providing a shortcut for when a single value is removed
+   * from the input values - for example ,when a Row is removed from the Table.
    * @param aggregateReplace A function that can be used to optimize a custom
-   * Aggregate by providing a shortcut for when a single value in the input
-   * values is replaced with another - for example, when a Row is updated.
+   * MetricAggregate by providing a shortcut for when a single value in the
+   * input values is replaced with another - for example, when a Row is updated.
    * @returns A reference to the Metrics object.
    * @example
    * This example creates a Store, creates a Metrics object, and defines a
@@ -412,19 +437,27 @@ export interface Metrics<Schemas extends OptionalSchemas = NoSchemas> {
    * ```
    * @category Configuration
    */
-  setMetricDefinition(
+  setMetricDefinition<TableId extends TableIdFromSchema<Schemas[0]>>(
     metricId: Id,
-    tableId: Id,
-    aggregate?: 'sum' | 'avg' | 'min' | 'max' | Aggregate,
-    getNumber?: Id | ((getCell: GetCell, rowId: Id) => number),
-    aggregateAdd?: AggregateAdd,
-    aggregateRemove?: AggregateRemove,
-    aggregateReplace?: AggregateReplace,
+    tableId: TableId,
+    aggregate?: 'sum' | 'avg' | 'min' | 'max' | MetricAggregate,
+    getNumber?:
+      | CellIdFromSchema<Schemas[0], TableId>
+      | ((getCell: GetCell<Schemas[0], TableId>, rowId: Id) => number),
+    aggregateAdd?: MetricAggregateAdd,
+    aggregateRemove?: MetricAggregateRemove,
+    aggregateReplace?: MetricAggregateReplace,
   ): Metrics<Schemas>;
 
   /**
    * The delMetricDefinition method removes an existing Metric definition.
    *
+   * This has schema-based typing. The following is a simplified representation:
+   *
+   * ```ts override
+   * delMetricDefinition(metricId: Id): Metrics;
+   * ```
+   *
    * @param metricId The Id of the Metric to remove.
    * @returns A reference to the Metrics object.
    * @example
@@ -455,6 +488,12 @@ export interface Metrics<Schemas extends OptionalSchemas = NoSchemas> {
    * The getStore method returns a reference to the underlying Store that is
    * backing this Metrics object.
    *
+   * This has schema-based typing. The following is a simplified representation:
+   *
+   * ```ts override
+   * getStore(): Store;
+   * ```
+   *
    * @returns A reference to the Store.
    * @example
    * This example creates a Metrics object against a newly-created Store and
@@ -554,6 +593,12 @@ export interface Metrics<Schemas extends OptionalSchemas = NoSchemas> {
    * The getTableId method returns the Id of the underlying Table that is
    * backing a Metric.
    *
+   * This has schema-based typing. The following is a simplified representation:
+   *
+   * ```ts override
+   * getTableId(metricId: Id): Id | undefined;
+   * ```
+   *
    * If the Metric Id is invalid, the method returns `undefined`.
    *
    * @param metricId The Id of a Metric.
@@ -573,7 +618,9 @@ export interface Metrics<Schemas extends OptionalSchemas = NoSchemas> {
    * ```
    * @category Getter
    */
-  getTableId(metricId: Id): Id | undefined;
+  getTableId<TableId extends TableIdFromSchema<Schemas[0]>>(
+    metricId: Id,
+  ): TableId | undefined;
 
   /**
    * The getMetric method gets the current value of a Metric.
@@ -613,6 +660,12 @@ export interface Metrics<Schemas extends OptionalSchemas = NoSchemas> {
    * object that will be called whenever the value of a specified Metric
    * changes.
    *
+   * This has schema-based typing. The following is a simplified representation:
+   *
+   * ```ts override
+   * addMetricListener(metricId: IdOrNull, listener: MetricListener): Id;
+   * ```
+   *
    * You can either listen to a single Metric (by specifying the Metric Id as
    * the method's first parameter), or changes to any Metric (by providing a
    * `null` wildcard).
@@ -686,12 +739,18 @@ export interface Metrics<Schemas extends OptionalSchemas = NoSchemas> {
    * ```
    * @category Listener
    */
-  addMetricListener(metricId: IdOrNull, listener: MetricListener): Id;
+  addMetricListener(metricId: IdOrNull, listener: MetricListener<Schemas>): Id;
 
   /**
    * The delListener method removes a listener that was previously added to the
    * Metrics object.
    *
+   * This has schema-based typing. The following is a simplified representation:
+   *
+   * ```ts override
+   * delListener(listenerId: Id): Metrics;
+   * ```
+   *
    * Use the Id returned by the addMetricListener method. Note that the Metrics
    * object may re-use this Id for future listeners added to it.
    *
@@ -796,6 +855,12 @@ export interface Metrics<Schemas extends OptionalSchemas = NoSchemas> {
  * The createMetrics function creates a Metrics object, and is the main entry
  * point into the metrics module.
  *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * createMetrics(store: Store): Metrics;
+ * ```
+ *
  * A given Store can only have one Metrics object associated with it. If you
  * call this function twice on the same Store, your second call will return a
  * reference to the Metrics object created by the first.

package/lib/{cjs → types/with-schemas}/persisters.d.ts

@@ -27,7 +27,7 @@
  * @module persisters
  */
 
-import {NoSchemas, OptionalSchemas, Store, Tables, Values} from './store.d';
+import {OptionalSchemas, Store, Tables, Values} from './store.d';
 import {Callback} from './common.d';
 
 /**
@@ -145,11 +145,17 @@ export type PersisterStats = {
  * ```
  * @category Persister
  */
-export interface Persister<Schemas extends OptionalSchemas = NoSchemas> {
+export interface Persister<in out Schemas extends OptionalSchemas> {
   /**
    * The load method gets persisted data from storage, and loads it into the
    * Store with which the Persister is associated, once.
    *
+   * This has schema-based typing. The following is a simplified representation:
+   *
+   * ```ts override
+   * load(initialTables?: Tables, initialValues?: Values): Promise<Persister>;
+   * ```
+   *
    * The optional parameter allows you to specify what the initial Tables object
    * for the Store will be if there is nothing currently persisted. Using this
    * instead of the `initialTables` parameter in the regular createStore
@@ -208,7 +214,7 @@ export interface Persister<Schemas extends OptionalSchemas = NoSchemas> {
    */
   load(
     initialTables?: Tables<Schemas[0], true>,
-    initialValues?: Values,
+    initialValues?: Values<Schemas[1], true>,
   ): Promise<Persister<Schemas>>;
 
   /**
@@ -216,6 +222,15 @@ export interface Persister<Schemas extends OptionalSchemas = NoSchemas> {
    * into the Store with which the Persister is associated, once, and then
    * continuously.
    *
+   * This has schema-based typing. The following is a simplified representation:
+   *
+   * ```ts override
+   * startAutoLoad(
+   *   initialTables?: Tables,
+   *   initialValues?: Values,
+   * ): Promise<Persister>;
+   * ```
+   *
    * The optional parameter allows you to specify what the initial Tables object
    * for the Store will be if there is nothing at first persisted. Using this
    * instead of the `initialTables` parameter in the regular createStore
@@ -267,13 +282,19 @@ export interface Persister<Schemas extends OptionalSchemas = NoSchemas> {
    */
   startAutoLoad(
     initialTables?: Tables<Schemas[0], true>,
-    initialValues?: Values,
+    initialValues?: Values<Schemas[1], true>,
   ): Promise<Persister<Schemas>>;
 
   /**
    * The stopAutoLoad method stops the automatic loading of data from storage
    * previously started with the startAutoLoad method.
    *
+   * This has schema-based typing. The following is a simplified representation:
+   *
+   * ```ts override
+   * stopAutoLoad(): Persister;
+   * ```
+   *
    * If the Persister is not currently set to automatically load, this method
    * has no effect.
    *
@@ -319,6 +340,12 @@ export interface Persister<Schemas extends OptionalSchemas = NoSchemas> {
    * The save method takes data from the Store with which the Persister is
    * associated and persists it into storage, once.
    *
+   * This has schema-based typing. The following is a simplified representation:
+   *
+   * ```ts override
+   * save(): Promise<Persister>;
+   * ```
+   *
    * This method is asynchronous because the persisted data may be on a remote
    * machine or a filesystem. Even for those storage types that are synchronous
    * (like browser storage) it is still recommended that you `await` calls to
@@ -348,6 +375,12 @@ export interface Persister<Schemas extends OptionalSchemas = NoSchemas> {
    * The save method takes data from the Store with which the Persister is
    * associated and persists it into storage, once, and then continuously.
    *
+   * This has schema-based typing. The following is a simplified representation:
+   *
+   * ```ts override
+   * startAutoSave(): Promise<Persister>;
+   * ```
+   *
    * This method first runs a single call to the save method to ensure the data
    * is in sync with the persisted storage. It then continues to watch for
    * changes to the Store, automatically saving the data to storage.
@@ -386,6 +419,12 @@ export interface Persister<Schemas extends OptionalSchemas = NoSchemas> {
    * The stopAutoSave method stops the automatic save of data to storage
    * previously started with the startAutoSave method.
    *
+   * This has schema-based typing. The following is a simplified representation:
+   *
+   * ```ts override
+   * stopAutoSave(): Persister;
+   * ```
+   *
    * If the Persister is not currently set to automatically save, this method
    * has no effect.
    *
@@ -424,6 +463,12 @@ export interface Persister<Schemas extends OptionalSchemas = NoSchemas> {
    * The getStore method returns a reference to the underlying Store that is
    * backing this Persister object.
    *
+   * This has schema-based typing. The following is a simplified representation:
+   *
+   * ```ts override
+   * getStore(): Store;
+   * ```
+   *
    * @returns A reference to the Store.
    * @example
    * This example creates a Persister object against a newly-created Store and
@@ -448,6 +493,12 @@ export interface Persister<Schemas extends OptionalSchemas = NoSchemas> {
    * The destroy method should be called when this Persister object is no longer
    * used.
    *
+   * This has schema-based typing. The following is a simplified representation:
+   *
+   * ```ts override
+   * destroy(): Persister;
+   * ```
+   *
    * This guarantees that all of the listeners that the object registered with
    * the underlying Store and storage are removed and it can be correctly
    * garbage collected. It is equivalent to running the stopAutoLoad method and
@@ -525,6 +576,15 @@ export interface Persister<Schemas extends OptionalSchemas = NoSchemas> {
  * The createSessionPersister function creates a Persister object that can
  * persist the Store to the browser's session storage.
  *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * createSessionPersister(
+ *   store: Store,
+ *   storageName: string,
+ * ): Persister;
+ * ```
+ *
  * As well as providing a reference to the Store to persist, you must provide a
  * `storageName` parameter which is unique to your application. This is the key
  * that the browser uses to identify the storage location.
@@ -558,6 +618,15 @@ export function createSessionPersister<Schemas extends OptionalSchemas>(
  * The createLocalPersister function creates a Persister object that can
  * persist the Store to the browser's local storage.
  *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * createLocalPersister(
+ *   store: Store,
+ *   storageName: string,
+ * ): Persister;
+ * ```
+ *
  * As well as providing a reference to the Store to persist, you must provide a
  * `storageName` parameter which is unique to your application. This is the key
  * that the browser uses to identify the storage location.
@@ -591,6 +660,17 @@ export function createLocalPersister<Schemas extends OptionalSchemas>(
  * The createRemotePersister function creates a Persister object that can
  * persist the Store to a remote server.
  *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * createRemotePersister(
+ *   store: Store,
+ *   loadUrl: string,
+ *   saveUrl: string,
+ *   autoLoadIntervalSeconds: number,
+ * ): Persister;
+ * ```
+ *
  * As well as providing a reference to the Store to persist, you must provide
  * `loadUrl` and `saveUrl` parameters. These identify the endpoints of the
  * server that support the `GET` method (to fetch the Store JSON to load) and
@@ -640,6 +720,12 @@ export function createRemotePersister<Schemas extends OptionalSchemas>(
  * The createFilePersister function creates a Persister object that can persist
  * the Store to a local file (in an appropriate environment).
  *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * createFilePersister(store: Store, filePath: string): Persister;
+ * ```
+ *
  * As well as providing a reference to the Store to persist, you must provide
  * `filePath` parameter which identifies the file to persist it to.
  *
@@ -673,6 +759,18 @@ export function createFilePersister<Schemas extends OptionalSchemas>(
  * The createCustomPersister function creates a Persister object that you can
  * configure to persist the Store in any way you wish.
  *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * createCustomPersister(
+ *   store: Store,
+ *   getPersisted: () => Promise<string | null | undefined>,
+ *   setPersisted: (json: string) => Promise<void>,
+ *   startListeningToPersisted: (didChange: Callback) => void,
+ *   stopListeningToPersisted: Callback,
+ * ): Persister;
+ * ```
+ *
  * As well as providing a reference to the Store to persist, you must provide
  * functions that handle how to fetch, write, and listen to, the persistence
  * layer.