tinybase 0.9.2 → 1.0.1

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2022-
+Copyright (c) James Pearce, 2021-
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/lib/checkpoints.d.ts

@@ -43,6 +43,7 @@ export type CheckpointIds = [Ids, Id | undefined, Ids];
  * When called, a CheckpointIdsListener is given a reference to the Checkpoints
  * object.
  *
+ * @param checkpoints A reference to the Checkpoints object that changed.
  * @category Listener
  */
 export type CheckpointIdsListener = (checkpoints: Checkpoints) => void;
@@ -57,6 +58,8 @@ export type CheckpointIdsListener = (checkpoints: Checkpoints) => void;
  * When called, a CheckpointListener is given a reference to the Checkpoints
  * object, and the Id of the checkpoint whose label changed.
  *
+ * @param checkpoints A reference to the Checkpoints object that changed.
+ * @param checkpointId The Id of the checkpoint that changed.
  * @category Listener
  */
 export type CheckpointListener = (
@@ -75,7 +78,14 @@ export type CheckpointListener = (
  * @category Development
  */
 export type CheckpointsListenerStats = {
+  /**
+   * The number of CheckpointIdsListeners registered with the Checkpoints
+   * object.
+   */
   checkpointIds?: number;
+  /**
+   * The number of CheckpointListeners registered with the Checkpoints object.
+   */
   checkpoint?: number;
 };
 
@@ -101,7 +111,7 @@ export type CheckpointsListenerStats = {
  * to adding a checkpoint, getting the list of available checkpoints, and then
  * registering and removing a listener for them.
  *
- * ```tsx
+ * ```js
  * const store = createStore().setTables({pets: {fido: {sold: false}}});
  *
  * const checkpoints = createCheckpoints(store);
@@ -132,6 +142,10 @@ export type CheckpointsListenerStats = {
  * checkpoints.delListener(listenerId);
  * checkpoints.destroy();
  * ```
+ * @see Relationships And Checkpoints guides
+ * @see Todo App demos
+ * @see TinyDraw demo
+ * @category Checkpoints
  */
 export interface Checkpoints {
   /**
@@ -151,7 +165,7 @@ export interface Checkpoints {
    * of the Checkpoints object dramatically and then creates more than that
    * number of checkpoints to demonstrate the oldest being pruned.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({pets: {fido: {views: 0}}});
    *
    * const checkpoints = createCheckpoints(store);
@@ -196,7 +210,7 @@ export interface Checkpoints {
    * This example creates a Store, adds a Checkpoints object, and adds two
    * checkpoints, one with a label.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({pets: {fido: {sold: false}}});
    *
    * const checkpoints = createCheckpoints(store);
@@ -245,7 +259,7 @@ export interface Checkpoints {
    * This example creates a Store, adds a Checkpoints object, and sets two
    * checkpoints, one with a label, which are both then re-labelled.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({pets: {fido: {sold: false}}});
    *
    * const checkpoints = createCheckpoints(store);
@@ -288,7 +302,7 @@ export interface Checkpoints {
    * and then gets its reference in order to update its data and set a
    * checkpoint.
    *
-   * ```tsx
+   * ```js
    * const checkpoints = createCheckpoints(createStore());
    * checkpoints.getStore().setCell('pets', 'fido', 'species', 'dog');
    * checkpoints.addCheckpoint();
@@ -315,7 +329,7 @@ export interface Checkpoints {
    * This example creates a Store, adds a Checkpoints object, and then gets the
    * Ids of the checkpoints as it sets them and moves around the stack.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({pets: {fido: {sold: false}}});
    *
    * const checkpoints = createCheckpoints(store);
@@ -354,7 +368,7 @@ export interface Checkpoints {
    * This example creates a Store, adds a Checkpoints object, and sets a
    * checkpoint with a label, before retrieving it again.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({pets: {fido: {sold: false}}});
    *
    * const checkpoints = createCheckpoints(store);
@@ -370,7 +384,7 @@ export interface Checkpoints {
    * checkpoint without a label, setting it subsequently. A non-existent
    * checkpoint return an `undefined` label.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({pets: {fido: {sold: false}}});
    *
    * const checkpoints = createCheckpoints(store);
@@ -405,7 +419,7 @@ export interface Checkpoints {
    * This example creates a Store, a Checkpoints object, and then registers a
    * listener that responds to any changes to the checkpoints.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({pets: {fido: {sold: false}}});
    *
    * const checkpoints = createCheckpoints(store);
@@ -463,7 +477,7 @@ export interface Checkpoints {
    * listener that responds to any changes to a specific checkpoint label,
    * including when the checkpoint no longer exists.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
    *
    * const checkpoints = createCheckpoints(store);
@@ -516,7 +530,7 @@ export interface Checkpoints {
    * This example creates a Store, a Checkpoints object, registers a listener,
    * and then removes it.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({pets: {fido: {sold: false}}});
    *
    * const checkpoints = createCheckpoints(store);
@@ -554,7 +568,7 @@ export interface Checkpoints {
    * This example creates a Store, a Checkpoints object, makes a change and then
    * goes backward to the state of the Store before the change.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({pets: {fido: {sold: false}}});
    *
    * const checkpoints = createCheckpoints(store);
@@ -572,6 +586,7 @@ export interface Checkpoints {
    * console.log(checkpoints.getCheckpointIds());
    * // -> [[], '0', ['1']]
    * ```
+   * @category Movement
    */
   goBackward(): Checkpoints;
 
@@ -592,7 +607,7 @@ export interface Checkpoints {
    * goes backward to the state of the Store before the change. It then goes
    * forward again to restore the state with the changes.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({pets: {fido: {sold: false}}});
    *
    * const checkpoints = createCheckpoints(store);
@@ -622,7 +637,7 @@ export interface Checkpoints {
    * change, the redo stack disappears, and then the attempt to forward again
    * has no effect.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({pets: {fido: {sold: false}}});
    *
    * const checkpoints = createCheckpoints(store);
@@ -651,6 +666,7 @@ export interface Checkpoints {
    * // -> [['0'], undefined, []]
    * // The original change cannot be redone.
    * ```
+   * @category Movement
    */
   goForward(): Checkpoints;
 
@@ -668,7 +684,7 @@ export interface Checkpoints {
    * then goes forward again one change, also using the goTo method. Finally it
    * tries to go to a checkpoint that does not exist.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({pets: {fido: {sold: false}}});
    *
    * const checkpoints = createCheckpoints(store);
@@ -700,6 +716,7 @@ export interface Checkpoints {
    * console.log(checkpoints.getCheckpointIds());
    * // -> [['0'], '1', ['2']]
    * ```
+   * @category Movement
    */
   goTo(checkpointId: Id): Checkpoints;
 
@@ -724,7 +741,7 @@ export interface Checkpoints {
    * This example creates a Store, a Checkpoints object, adds a listener, makes
    * a change and then clears the checkpoints.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({pets: {fido: {sold: false}}});
    *
    * const checkpoints = createCheckpoints(store);
@@ -773,7 +790,7 @@ export interface Checkpoints {
    * CellListener with the underlying Store), and then destroys it again,
    * removing the listener.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({pets: {fido: {sold: false}}});
    *
    * const checkpoints = createCheckpoints(store);
@@ -807,7 +824,7 @@ export interface Checkpoints {
    * @example
    * This example gets the listener statistics of a Checkpoints object.
    *
-   * ```tsx
+   * ```js
    * const store = createStore();
    * const checkpoints = createCheckpoints(store);
    * checkpoints.addCheckpointIdsListener(() => {
@@ -840,7 +857,7 @@ export interface Checkpoints {
  * @example
  * This example creates a Checkpoints object.
  *
- * ```tsx
+ * ```js
  * const store = createStore();
  * const checkpoints = createCheckpoints(store);
  * console.log(checkpoints.getCheckpointIds());
@@ -850,12 +867,13 @@ export interface Checkpoints {
  * This example creates a Checkpoints object, and calls the method a second
  * time for the same Store to return the same object.
  *
- * ```tsx
+ * ```js
  * const store = createStore();
  * const checkpoints1 = createCheckpoints(store);
  * const checkpoints2 = createCheckpoints(store);
  * console.log(checkpoints1 === checkpoints2);
  * // -> true
  * ```
+ * @category Creation
  */
 export function createCheckpoints(store: Store): Checkpoints;

package/lib/common.d.ts

@@ -57,3 +57,59 @@ export type ParameterizedCallback<Parameter> = (parameter?: Parameter) => void;
  * @category Callback
  */
 export type Callback = () => void;
+
+/**
+ * The SortKey type represents a value that can be used by a sort function.
+ *
+ * @category Parameter
+ */
+export type SortKey = string | number | boolean;
+
+/**
+ * The defaultSorter function is provided as a convenience to sort keys
+ * alphanumerically, and can be provided to the `sliceIdSorter` and
+ * `rowIdSorter` parameters of the setIndexDefinition method in the indexes
+ * module, for example.
+ *
+ * @param sortKey1 The first item of the pair to compare.
+ * @param sortKey2 The second item of the pair to compare.
+ * @returns A number indicating how to sort the pair.
+ * @example
+ * This example creates an Indexes object.
+ *
+ * ```js
+ * const store = createStore();
+ * const indexes = createIndexes(store);
+ * console.log(indexes.getIndexIds());
+ * // -> []
+ * ```
+ * @example
+ * This example creates a Store, creates an Indexes object, and defines an
+ * Index based on the first letter of the pets' names. The Slice Ids (and Row
+ * Ids within them) are alphabetically sorted using the defaultSorter function.
+ *
+ * ```js
+ * const store = createStore().setTable('pets', {
+ *   fido: {species: 'dog'},
+ *   felix: {species: 'cat'},
+ *   cujo: {species: 'dog'},
+ * });
+ *
+ * const indexes = createIndexes(store);
+ * indexes.setIndexDefinition(
+ *   'byFirst', //              indexId
+ *   'pets', //                 tableId
+ *   (_, rowId) => rowId[0], // each Row's Slice Id
+ *   (_, rowId) => rowId, //    each Row's sort key
+ *   defaultSorter, //          sort Slice Ids
+ *   defaultSorter, //          sort Row Ids by sort key
+ * );
+ *
+ * console.log(indexes.getSliceIds('byFirst'));
+ * // -> ['c', 'f']
+ * console.log(indexes.getSliceRowIds('byFirst', 'f'));
+ * // -> ['felix', 'fido']
+ * ```
+ * @category Convenience
+ */
+export function defaultSorter(sortKey1: SortKey, sortKey2: SortKey): number;

package/lib/common.js

@@ -0,0 +1 @@
+const o=(o,t)=>o<t?-1:1;export{o as defaultSorter};

package/lib/debug/checkpoints.d.ts

@@ -43,6 +43,7 @@ export type CheckpointIds = [Ids, Id | undefined, Ids];
  * When called, a CheckpointIdsListener is given a reference to the Checkpoints
  * object.
  *
+ * @param checkpoints A reference to the Checkpoints object that changed.
  * @category Listener
  */
 export type CheckpointIdsListener = (checkpoints: Checkpoints) => void;
@@ -57,6 +58,8 @@ export type CheckpointIdsListener = (checkpoints: Checkpoints) => void;
  * When called, a CheckpointListener is given a reference to the Checkpoints
  * object, and the Id of the checkpoint whose label changed.
  *
+ * @param checkpoints A reference to the Checkpoints object that changed.
+ * @param checkpointId The Id of the checkpoint that changed.
  * @category Listener
  */
 export type CheckpointListener = (
@@ -75,7 +78,14 @@ export type CheckpointListener = (
  * @category Development
  */
 export type CheckpointsListenerStats = {
+  /**
+   * The number of CheckpointIdsListeners registered with the Checkpoints
+   * object.
+   */
   checkpointIds?: number;
+  /**
+   * The number of CheckpointListeners registered with the Checkpoints object.
+   */
   checkpoint?: number;
 };
 
@@ -101,7 +111,7 @@ export type CheckpointsListenerStats = {
  * to adding a checkpoint, getting the list of available checkpoints, and then
  * registering and removing a listener for them.
  *
- * ```tsx
+ * ```js
  * const store = createStore().setTables({pets: {fido: {sold: false}}});
  *
  * const checkpoints = createCheckpoints(store);
@@ -132,6 +142,10 @@ export type CheckpointsListenerStats = {
  * checkpoints.delListener(listenerId);
  * checkpoints.destroy();
  * ```
+ * @see Relationships And Checkpoints guides
+ * @see Todo App demos
+ * @see TinyDraw demo
+ * @category Checkpoints
  */
 export interface Checkpoints {
   /**
@@ -151,7 +165,7 @@ export interface Checkpoints {
    * of the Checkpoints object dramatically and then creates more than that
    * number of checkpoints to demonstrate the oldest being pruned.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({pets: {fido: {views: 0}}});
    *
    * const checkpoints = createCheckpoints(store);
@@ -196,7 +210,7 @@ export interface Checkpoints {
    * This example creates a Store, adds a Checkpoints object, and adds two
    * checkpoints, one with a label.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({pets: {fido: {sold: false}}});
    *
    * const checkpoints = createCheckpoints(store);
@@ -245,7 +259,7 @@ export interface Checkpoints {
    * This example creates a Store, adds a Checkpoints object, and sets two
    * checkpoints, one with a label, which are both then re-labelled.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({pets: {fido: {sold: false}}});
    *
    * const checkpoints = createCheckpoints(store);
@@ -288,7 +302,7 @@ export interface Checkpoints {
    * and then gets its reference in order to update its data and set a
    * checkpoint.
    *
-   * ```tsx
+   * ```js
    * const checkpoints = createCheckpoints(createStore());
    * checkpoints.getStore().setCell('pets', 'fido', 'species', 'dog');
    * checkpoints.addCheckpoint();
@@ -315,7 +329,7 @@ export interface Checkpoints {
    * This example creates a Store, adds a Checkpoints object, and then gets the
    * Ids of the checkpoints as it sets them and moves around the stack.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({pets: {fido: {sold: false}}});
    *
    * const checkpoints = createCheckpoints(store);
@@ -354,7 +368,7 @@ export interface Checkpoints {
    * This example creates a Store, adds a Checkpoints object, and sets a
    * checkpoint with a label, before retrieving it again.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({pets: {fido: {sold: false}}});
    *
    * const checkpoints = createCheckpoints(store);
@@ -370,7 +384,7 @@ export interface Checkpoints {
    * checkpoint without a label, setting it subsequently. A non-existent
    * checkpoint return an `undefined` label.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({pets: {fido: {sold: false}}});
    *
    * const checkpoints = createCheckpoints(store);
@@ -405,7 +419,7 @@ export interface Checkpoints {
    * This example creates a Store, a Checkpoints object, and then registers a
    * listener that responds to any changes to the checkpoints.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({pets: {fido: {sold: false}}});
    *
    * const checkpoints = createCheckpoints(store);
@@ -463,7 +477,7 @@ export interface Checkpoints {
    * listener that responds to any changes to a specific checkpoint label,
    * including when the checkpoint no longer exists.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
    *
    * const checkpoints = createCheckpoints(store);
@@ -516,7 +530,7 @@ export interface Checkpoints {
    * This example creates a Store, a Checkpoints object, registers a listener,
    * and then removes it.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({pets: {fido: {sold: false}}});
    *
    * const checkpoints = createCheckpoints(store);
@@ -554,7 +568,7 @@ export interface Checkpoints {
    * This example creates a Store, a Checkpoints object, makes a change and then
    * goes backward to the state of the Store before the change.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({pets: {fido: {sold: false}}});
    *
    * const checkpoints = createCheckpoints(store);
@@ -572,6 +586,7 @@ export interface Checkpoints {
    * console.log(checkpoints.getCheckpointIds());
    * // -> [[], '0', ['1']]
    * ```
+   * @category Movement
    */
   goBackward(): Checkpoints;
 
@@ -592,7 +607,7 @@ export interface Checkpoints {
    * goes backward to the state of the Store before the change. It then goes
    * forward again to restore the state with the changes.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({pets: {fido: {sold: false}}});
    *
    * const checkpoints = createCheckpoints(store);
@@ -622,7 +637,7 @@ export interface Checkpoints {
    * change, the redo stack disappears, and then the attempt to forward again
    * has no effect.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({pets: {fido: {sold: false}}});
    *
    * const checkpoints = createCheckpoints(store);
@@ -651,6 +666,7 @@ export interface Checkpoints {
    * // -> [['0'], undefined, []]
    * // The original change cannot be redone.
    * ```
+   * @category Movement
    */
   goForward(): Checkpoints;
 
@@ -668,7 +684,7 @@ export interface Checkpoints {
    * then goes forward again one change, also using the goTo method. Finally it
    * tries to go to a checkpoint that does not exist.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({pets: {fido: {sold: false}}});
    *
    * const checkpoints = createCheckpoints(store);
@@ -700,6 +716,7 @@ export interface Checkpoints {
    * console.log(checkpoints.getCheckpointIds());
    * // -> [['0'], '1', ['2']]
    * ```
+   * @category Movement
    */
   goTo(checkpointId: Id): Checkpoints;
 
@@ -724,7 +741,7 @@ export interface Checkpoints {
    * This example creates a Store, a Checkpoints object, adds a listener, makes
    * a change and then clears the checkpoints.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({pets: {fido: {sold: false}}});
    *
    * const checkpoints = createCheckpoints(store);
@@ -773,7 +790,7 @@ export interface Checkpoints {
    * CellListener with the underlying Store), and then destroys it again,
    * removing the listener.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({pets: {fido: {sold: false}}});
    *
    * const checkpoints = createCheckpoints(store);
@@ -807,7 +824,7 @@ export interface Checkpoints {
    * @example
    * This example gets the listener statistics of a Checkpoints object.
    *
-   * ```tsx
+   * ```js
    * const store = createStore();
    * const checkpoints = createCheckpoints(store);
    * checkpoints.addCheckpointIdsListener(() => {
@@ -840,7 +857,7 @@ export interface Checkpoints {
  * @example
  * This example creates a Checkpoints object.
  *
- * ```tsx
+ * ```js
  * const store = createStore();
  * const checkpoints = createCheckpoints(store);
  * console.log(checkpoints.getCheckpointIds());
@@ -850,12 +867,13 @@ export interface Checkpoints {
  * This example creates a Checkpoints object, and calls the method a second
  * time for the same Store to return the same object.
  *
- * ```tsx
+ * ```js
  * const store = createStore();
  * const checkpoints1 = createCheckpoints(store);
  * const checkpoints2 = createCheckpoints(store);
  * console.log(checkpoints1 === checkpoints2);
  * // -> true
  * ```
+ * @category Creation
  */
 export function createCheckpoints(store: Store): Checkpoints;

package/lib/debug/common.d.ts

@@ -57,3 +57,59 @@ export type ParameterizedCallback<Parameter> = (parameter?: Parameter) => void;
  * @category Callback
  */
 export type Callback = () => void;
+
+/**
+ * The SortKey type represents a value that can be used by a sort function.
+ *
+ * @category Parameter
+ */
+export type SortKey = string | number | boolean;
+
+/**
+ * The defaultSorter function is provided as a convenience to sort keys
+ * alphanumerically, and can be provided to the `sliceIdSorter` and
+ * `rowIdSorter` parameters of the setIndexDefinition method in the indexes
+ * module, for example.
+ *
+ * @param sortKey1 The first item of the pair to compare.
+ * @param sortKey2 The second item of the pair to compare.
+ * @returns A number indicating how to sort the pair.
+ * @example
+ * This example creates an Indexes object.
+ *
+ * ```js
+ * const store = createStore();
+ * const indexes = createIndexes(store);
+ * console.log(indexes.getIndexIds());
+ * // -> []
+ * ```
+ * @example
+ * This example creates a Store, creates an Indexes object, and defines an
+ * Index based on the first letter of the pets' names. The Slice Ids (and Row
+ * Ids within them) are alphabetically sorted using the defaultSorter function.
+ *
+ * ```js
+ * const store = createStore().setTable('pets', {
+ *   fido: {species: 'dog'},
+ *   felix: {species: 'cat'},
+ *   cujo: {species: 'dog'},
+ * });
+ *
+ * const indexes = createIndexes(store);
+ * indexes.setIndexDefinition(
+ *   'byFirst', //              indexId
+ *   'pets', //                 tableId
+ *   (_, rowId) => rowId[0], // each Row's Slice Id
+ *   (_, rowId) => rowId, //    each Row's sort key
+ *   defaultSorter, //          sort Slice Ids
+ *   defaultSorter, //          sort Row Ids by sort key
+ * );
+ *
+ * console.log(indexes.getSliceIds('byFirst'));
+ * // -> ['c', 'f']
+ * console.log(indexes.getSliceRowIds('byFirst', 'f'));
+ * // -> ['felix', 'fido']
+ * ```
+ * @category Convenience
+ */
+export function defaultSorter(sortKey1: SortKey, sortKey2: SortKey): number;

package/lib/debug/common.js

@@ -0,0 +1,3 @@
+const defaultSorter = (sortKey1, sortKey2) => (sortKey1 < sortKey2 ? -1 : 1);
+
+export {defaultSorter};