tinybase 5.0.0-beta.27 → 5.0.0-beta.28

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

@@ -8,6 +8,7 @@
  * tabular data within.
  * @packageDocumentation
  * @module store
+ * @since v1.0.0
  */
 
 import type {Id, IdOrNull, Ids, Json} from '../common/index.d.ts';
@@ -36,6 +37,7 @@ import type {StoreAlias} from '../_internal/store/index.d.ts';
  * };
  * ```
  * @category Schema
+ * @since v1.0.0
  */
 export type TablesSchema = {[tableId: Id]: {[cellId: Id]: CellSchema}};
 
@@ -66,6 +68,7 @@ export type TablesSchema = {[tableId: Id]: {[cellId: Id]: CellSchema}};
  * };
  * ```
  * @category Schema
+ * @since v1.0.0
  */
 export type CellSchema =
   | {type: 'string'; default?: string}
@@ -132,6 +135,7 @@ export type ValueSchema =
  * The NoTablesSchema type is a TablesSchema-like type for when one has not been
  * provided.
  * @category Schema
+ * @since v1.0.0
  */
 export type NoTablesSchema = {[tableId: Id]: {[cellId: Id]: {type: 'any'}}};
 
@@ -139,6 +143,7 @@ export type NoTablesSchema = {[tableId: Id]: {[cellId: Id]: {type: 'any'}}};
  * The NoValuesSchema type is a ValuesSchema-like type for when one has not been
  * provided.
  * @category Schema
+ * @since v1.0.0
  */
 export type NoValuesSchema = {[valueId: Id]: {type: 'any'}};
 
@@ -146,6 +151,7 @@ export type NoValuesSchema = {[valueId: Id]: {type: 'any'}};
  * The OptionalTablesSchema type is used by generic types that can optionally
  * take a TablesSchema.
  * @category Schema
+ * @since v1.0.0
  */
 export type OptionalTablesSchema = TablesSchema | NoTablesSchema;
 
@@ -153,6 +159,7 @@ export type OptionalTablesSchema = TablesSchema | NoTablesSchema;
  * The OptionalValuesSchema type is used by generic types that can optionally
  * take a ValuesSchema.
  * @category Schema
+ * @since v1.0.0
  */
 export type OptionalValuesSchema = ValuesSchema | NoValuesSchema;
 
@@ -160,6 +167,7 @@ export type OptionalValuesSchema = ValuesSchema | NoValuesSchema;
  * The OptionalSchemas type is used by generic types that can optionally take
  * either or both of a TablesSchema and ValuesSchema.
  * @category Schema
+ * @since v1.0.0
  */
 export type OptionalSchemas = [OptionalTablesSchema, OptionalValuesSchema];
 
@@ -167,6 +175,7 @@ export type OptionalSchemas = [OptionalTablesSchema, OptionalValuesSchema];
  * The NoSchemas type is used as a default by generic types that can optionally
  * take either or both of a TablesSchema and ValuesSchema.
  * @category Schema
+ * @since v1.0.0
  */
 export type NoSchemas = [NoTablesSchema, NoValuesSchema];
 
@@ -225,6 +234,7 @@ export type Content = [Tables, Values];
  * };
  * ```
  * @category Store
+ * @since v1.0.0
  */
 export type Tables = {[tableId: Id]: Table};
 
@@ -245,6 +255,7 @@ export type Tables = {[tableId: Id]: Table};
  * };
  * ```
  * @category Store
+ * @since v1.0.0
  */
 export type Table = {[rowId: Id]: Row};
 
@@ -261,6 +272,7 @@ export type Table = {[rowId: Id]: Row};
  * export const row: Row = {species: 'dog', color: 'brown'};
  * ```
  * @category Store
+ * @since v1.0.0
  */
 export type Row = {[cellId: Id]: Cell};
 
@@ -277,6 +289,7 @@ export type Row = {[cellId: Id]: Cell};
  * export const cell: Cell = 'dog';
  * ```
  * @category Store
+ * @since v1.0.0
  */
 export type Cell = string | number | boolean;
 
@@ -288,6 +301,7 @@ export type Cell = string | number | boolean;
  * such as when it has been deleted, or when describing a previous state where
  * the Cell value has since been added.
  * @category Store
+ * @since v1.0.0
  */
 export type CellOrUndefined = Cell | undefined;
 
@@ -351,6 +365,7 @@ export type ValueOrUndefined = Value | undefined;
  * @param forEachRow A function that will let you iterate over the Row objects
  * in this Table.
  * @category Callback
+ * @since v1.0.0
  */
 export type TableCallback = (
   tableId: Id,
@@ -367,6 +382,7 @@ export type TableCallback = (
  * @param cellId The Id of the Cell that the callback can operate on.
  * @param count The number of times this Cell is used across a whole Table.
  * @category Callback
+ * @since v1.0.0
  */
 export type TableCellCallback = (cellId: Id, count: number) => void;
 
@@ -381,6 +397,7 @@ export type TableCellCallback = (cellId: Id, count: number) => void;
  * @param forEachRow A function that will let you iterate over the Cell values
  * in this Row.
  * @category Callback
+ * @since v1.0.0
  */
 export type RowCallback = (
   rowId: Id,
@@ -397,6 +414,7 @@ export type RowCallback = (
  * @param cellId The Id of the Cell that the callback can operate on.
  * @param cell The value of the Cell.
  * @category Callback
+ * @since v1.0.0
  */
 export type CellCallback = (cellId: Id, cell: Cell) => void;
 
@@ -423,6 +441,7 @@ export type ValueCallback = (valueId: Id, value: Value) => void;
  * examples.
  * @param cell The current value of the Cell to map to a new value.
  * @category Callback
+ * @since v1.0.0
  */
 export type MapCell = (cell: CellOrUndefined) => Cell;
 
@@ -448,6 +467,7 @@ export type MapValue = (value: ValueOrUndefined) => Value;
  * method of an Indexes object. See those methods for specific examples.
  * @param cellId The Id of the Cell to fetch the value for.
  * @category Callback
+ * @since v1.0.0
  */
 export type GetCell = (cellId: Id) => CellOrUndefined;
 
@@ -552,6 +572,7 @@ export type ChangedValueIds = {[valueId: Id]: IdAddedOrRemoved};
  * Store directly to decide whether to do the rollback.
  * @param store A reference to the Store that is completing a transaction.
  * @category Callback
+ * @since v1.0.0
  */
 export type DoRollback = (store: Store) => boolean;
 
@@ -569,6 +590,7 @@ export type DoRollback = (store: Store) => boolean;
  * transaction.
  * @param store A reference to the Store that is completing a transaction.
  * @category Listener
+ * @since v1.0.0
  */
 export type TransactionListener<Store extends StoreAlias = StoreAlias> = (
   store: Store,
@@ -612,6 +634,7 @@ export type HasTablesListener<Store extends StoreAlias = StoreAlias> = (
  * @param getCellChange A function that returns information about any Cell's
  * changes.
  * @category Listener
+ * @since v1.0.0
  */
 export type TablesListener<Store extends StoreAlias = StoreAlias> = (
   store: Store,
@@ -633,6 +656,7 @@ export type TablesListener<Store extends StoreAlias = StoreAlias> = (
  * @param getIdChanges A function that returns information about the Id changes,
  * since v3.3.
  * @category Listener
+ * @since v1.0.0
  */
 export type TableIdsListener<Store extends StoreAlias = StoreAlias> = (
   store: Store,
@@ -681,6 +705,7 @@ export type HasTableListener<Store extends StoreAlias = StoreAlias> = (
  * @param getCellChange A function that returns information about any Cell's
  * changes.
  * @category Listener
+ * @since v1.0.0
  */
 export type TableListener<Store extends StoreAlias = StoreAlias> = (
   store: Store,
@@ -773,6 +798,7 @@ export type RowCountListener<Store extends StoreAlias = StoreAlias> = (
  * @param getIdChanges A function that returns information about the Id changes,
  * since v3.3.
  * @category Listener
+ * @since v1.0.0
  */
 export type RowIdsListener<Store extends StoreAlias = StoreAlias> = (
   store: Store,
@@ -859,6 +885,7 @@ export type HasRowListener<Store extends StoreAlias = StoreAlias> = (
  * @param getCellChange A function that returns information about any Cell's
  * changes.
  * @category Listener
+ * @since v1.0.0
  */
 export type RowListener<Store extends StoreAlias = StoreAlias> = (
   store: Store,
@@ -885,6 +912,7 @@ export type RowListener<Store extends StoreAlias = StoreAlias> = (
  * @param getIdChanges A function that returns information about the Id changes,
  * since v3.3.
  * @category Listener
+ * @since v1.0.0
  */
 export type CellIdsListener<Store extends StoreAlias = StoreAlias> = (
   store: Store,
@@ -946,6 +974,7 @@ export type HasCellListener<Store extends StoreAlias = StoreAlias> = (
  * @param getCellChange A function that returns information about any Cell's
  * changes.
  * @category Listener
+ * @since v1.0.0
  */
 export type CellListener<Store extends StoreAlias = StoreAlias> = (
   store: Store,
@@ -995,6 +1024,7 @@ export type HasValuesListener<Store extends StoreAlias = StoreAlias> = (
  * @param getValueChange A function that returns information about any Value's
  * changes.
  * @category Listener
+ * @since v1.0.0
  */
 export type ValuesListener<Store extends StoreAlias = StoreAlias> = (
   store: Store,
@@ -1016,6 +1046,7 @@ export type ValuesListener<Store extends StoreAlias = StoreAlias> = (
  * @param getIdChanges A function that returns information about the Id changes,
  * since v3.3.
  * @category Listener
+ * @since v1.0.0
  */
 export type ValueIdsListener<Store extends StoreAlias = StoreAlias> = (
   store: Store,
@@ -1161,6 +1192,7 @@ export type GetIdChanges = () => {[id: Id]: 1 | -1};
  * @param cellId The Id of the Cell to inspect.
  * @returns A CellChange array containing information about the Cell's changes.
  * @category Listener
+ * @since v1.0.0
  */
 export type GetCellChange = (tableId: Id, rowId: Id, cellId: Id) => CellChange;
 
@@ -1172,6 +1204,7 @@ export type GetCellChange = (tableId: Id, rowId: Id, cellId: Id) => CellChange;
  * the current transaction, the new value after it, and a convenience flag that
  * indicates that the value has changed.
  * @category Listener
+ * @since v1.0.0
  */
 export type CellChange = [
   changed: boolean,
@@ -1191,6 +1224,7 @@ export type CellChange = [
  * @returns A ValueChange array containing information about the Value's
  * changes.
  * @category Listener
+ * @since v1.0.0
  */
 export type GetValueChange = (valueId: Id) => ValueChange;
 
@@ -1202,6 +1236,7 @@ export type GetValueChange = (valueId: Id) => ValueChange;
  * before the current transaction, the new value after it, and a convenience
  * flag that indicates that the value has changed.
  * @category Listener
+ * @since v1.0.0
  */
 export type ValueChange = [
   changed: boolean,
@@ -1453,111 +1488,158 @@ export type TransactionLog = [
  * listener. Totals include both mutator and non-mutator listeners. A
  * StoreListenerStats object is returned from the getListenerStats method.
  * @category Development
+ * @since v1.0.0
  */
 export type StoreListenerStats = {
   /**
    * The number of HasTablesListener functions registered with the Store, since
    * v4.4.
+   * @category Stat
+   * @since v1.0.0
    */
   hasTables: number;
   /**
    * The number of TablesListener functions registered with the Store.
+   * @category Stat
+   * @since v1.0.0
    */
   tables: number;
   /**
    * The number of TableIdsListener functions registered with the Store.
+   * @category Stat
+   * @since v1.0.0
    */
   tableIds: number;
   /**
    * The number of HasTableListener functions registered with the Store, since
    * v4.4.
+   * @category Stat
+   * @since v1.0.0
    */
   hasTable: number;
   /**
    * The number of TableListener functions registered with the Store.
+   * @category Stat
+   * @since v1.0.0
    */
   table: number;
   /**
    * The number of TableCellIdsListener functions registered with the Store,
    * since v3.3.
+   * @category Stat
+   * @since v1.0.0
    */
   tableCellIds: number;
   /**
    * The number of HasTableCellListener functions registered with the Store,
    * since v4.4.
+   * @category Stat
+   * @since v1.0.0
    */
   hasTableCell: number;
   /**
    * The number of RowCountListener functions registered with the Store, since
    * v4.1.0.
+   * @category Stat
+   * @since v1.0.0
    */
   rowCount: number;
   /**
    * The number of RowIdsListener functions registered with the Store.
+   * @category Stat
+   * @since v1.0.0
    */
   rowIds: number;
   /**
    * The number of SortedRowIdsListener functions registered with the Store.
+   * @category Stat
+   * @since v1.0.0
    */
   sortedRowIds: number;
   /**
    * The number of HasRowListener functions registered with the Store, since
    * v4.4.
+   * @category Stat
+   * @since v1.0.0
    */
   hasRow: number;
   /**
    * The number of RowListener functions registered with the Store.
+   * @category Stat
+   * @since v1.0.0
    */
   row: number;
   /**
    * The number of CellIdsListener functions registered with the Store.
+   * @category Stat
+   * @since v1.0.0
    */
   cellIds: number;
   /**
    * The number of HasCellListener functions registered with the Store, since
    * v4.4.
+   * @category Stat
+   * @since v1.0.0
    */
   hasCell: number;
   /**
    * The number of CellListener functions registered with the Store.
+   * @category Stat
+   * @since v1.0.0
    */
   cell: number;
   /**
    * The number of InvalidCellListener functions registered with the Store.
+   * @category Stat
+   * @since v1.0.0
    */
   invalidCell: number;
   /**
    * The number of HasValuesListener functions registered with the Store, since
    * v4.4.
+   * @category Stat
+   * @since v1.0.0
    */
   hasValues: number;
   /**
    * The number of ValuesListener functions registered with the Store, since
    * v3.0.
+   * @category Stat
+   * @since v1.0.0
    */
   values: number;
   /**
    * The number of ValueIdsListener functions registered with the Store, since
    * v3.0.
+   * @category Stat
+   * @since v1.0.0
    */
   valueIds: number;
   /**
    * The number of HasValueListener functions registered with the Store, since
    * v4.4.
+   * @category Stat
+   * @since v1.0.0
    */
   hasValue: number;
   /**
    * The number of ValueListener functions registered with the Store, since
    * v3.0.
+   * @category Stat
+   * @since v1.0.0
    */
   value: number;
   /**
    * The number of InvalidValueListener functions registered with the Store,
    * since v3.0.
+   * @category Stat
+   * @since v1.0.0
    */
   invalidValue: number;
   /**
    * The number of TransactionListener functions registered with the Store.
+   * @category Stat
+   * @since v1.0.0
    */
   transaction: number;
 };
@@ -1746,6 +1828,7 @@ export type StoreListenerStats = {
  * @see Hello World demos
  * @see Todo App demos
  * @category Store
+ * @since v1.0.0
  */
 export interface Store {
   //
@@ -1818,6 +1901,7 @@ export interface Store {
    * // -> {}
    * ```
    * @category Getter
+   * @since v1.0.0
    */
   getTables(): Tables;
 
@@ -1852,6 +1936,7 @@ export interface Store {
    * // -> []
    * ```
    * @category Getter
+   * @since v1.0.0
    */
   getTableIds(): Ids;
 
@@ -1889,6 +1974,7 @@ export interface Store {
    * // -> {}
    * ```
    * @category Getter
+   * @since v1.0.0
    */
   getTable(tableId: Id): Table;
 
@@ -2006,6 +2092,7 @@ export interface Store {
    * // -> []
    * ```
    * @category Getter
+   * @since v1.0.0
    */
   getRowIds(tableId: Id): Ids;
 
@@ -2162,6 +2249,7 @@ export interface Store {
    * // -> {}
    * ```
    * @category Getter
+   * @since v1.0.0
    */
   getRow(tableId: Id, rowId: Id): Row;
 
@@ -2200,6 +2288,7 @@ export interface Store {
    * // -> []
    * ```
    * @category Getter
+   * @since v1.0.0
    */
   getCellIds(tableId: Id, rowId: Id): Ids;
 
@@ -2233,6 +2322,7 @@ export interface Store {
    * // -> undefined
    * ```
    * @category Getter
+   * @since v1.0.0
    */
   getCell(tableId: Id, rowId: Id, cellId: Id): CellOrUndefined;
 
@@ -2349,6 +2439,7 @@ export interface Store {
    * // -> true
    * ```
    * @category Getter
+   * @since v1.0.0
    */
   hasTables(): boolean;
 
@@ -2370,6 +2461,7 @@ export interface Store {
    * // -> false
    * ```
    * @category Getter
+   * @since v1.0.0
    */
   hasTable(tableId: Id): boolean;
 
@@ -2419,6 +2511,7 @@ export interface Store {
    * // -> false
    * ```
    * @category Getter
+   * @since v1.0.0
    */
   hasRow(tableId: Id, rowId: Id): boolean;
 
@@ -2442,6 +2535,7 @@ export interface Store {
    * // -> false
    * ```
    * @category Getter
+   * @since v1.0.0
    */
   hasCell(tableId: Id, rowId: Id, cellId: Id): boolean;
 
@@ -2579,6 +2673,7 @@ export interface Store {
    * // -> '[{},{}]'
    * ```
    * @category Getter
+   * @since v1.0.0
    */
   getJson(): Json;
 
@@ -2695,6 +2790,7 @@ export interface Store {
    * // -> '[{},{}]'
    * ```
    * @category Getter
+   * @since v1.0.0
    */
   getSchemaJson(): Json;
 
@@ -2861,6 +2957,7 @@ export interface Store {
    * // -> {pets: {felix: {species: 'cat'}}}
    * ```
    * @category Setter
+   * @since v1.0.0
    */
   setTables(tables: Tables): this;
 
@@ -2916,6 +3013,7 @@ export interface Store {
    * // -> {pets: {felix: {species: 'cat'}}}
    * ```
    * @category Setter
+   * @since v1.0.0
    */
   setTable(tableId: Id, table: Table): this;
 
@@ -2969,6 +3067,7 @@ export interface Store {
    * // -> {pets: {fido: {color: 'brown'}}}
    * ```
    * @category Setter
+   * @since v1.0.0
    */
   setRow(tableId: Id, rowId: Id, row: Row): this;
 
@@ -3034,6 +3133,7 @@ export interface Store {
    * // -> {pets: {'0': {species: 'dog'}, '1': {species: 'cat'}}}
    * ```
    * @category Setter
+   * @since v1.0.0
    */
   addRow(tableId: Id, row: Row, reuseRowIds?: boolean): Id | undefined;
 
@@ -3089,6 +3189,7 @@ export interface Store {
    * // -> {pets: {fido: {species: 'dog', color: 'brown'}}}
    * ```
    * @category Setter
+   * @since v1.0.0
    */
   setPartialRow(tableId: Id, rowId: Id, partialRow: Row): this;
 
@@ -3152,6 +3253,7 @@ export interface Store {
    * // -> {pets: {fido: {species: 'dog'}}}
    * ```
    * @category Setter
+   * @since v1.0.0
    */
   setCell(tableId: Id, rowId: Id, cellId: Id, cell: Cell | MapCell): this;
 
@@ -3495,6 +3597,7 @@ export interface Store {
    * // -> {}
    * ```
    * @category Setter
+   * @since v1.0.0
    */
   setJson(tablesAndValuesJson: Json): this;
 
@@ -3622,6 +3725,7 @@ export interface Store {
    * // -> {pets: {0: {species: 'dog', sold: false}}}
    * ```
    * @category Setter
+   * @since v1.0.0
    */
   setSchema(tablesSchema: TablesSchema, valuesSchema?: ValuesSchema): this;
 
@@ -3641,6 +3745,7 @@ export interface Store {
    * // -> {}
    * ```
    * @category Deleter
+   * @since v1.0.0
    */
   delTables(): this;
 
@@ -3664,6 +3769,7 @@ export interface Store {
    * // -> {species: {dog: {price: 5}}}
    * ```
    * @category Deleter
+   * @since v1.0.0
    */
   delTable(tableId: Id): this;
 
@@ -3689,6 +3795,7 @@ export interface Store {
    * // -> {pets: {felix: {species: 'cat'}}}
    * ```
    * @category Deleter
+   * @since v1.0.0
    */
   delRow(tableId: Id, rowId: Id): this;
 
@@ -3778,6 +3885,7 @@ export interface Store {
    * // -> {pets: {felix: {species: 'cat', sold: false}}}
    * ```
    * @category Deleter
+   * @since v1.0.0
    */
   delCell(tableId: Id, rowId: Id, cellId: Id, forceDel?: boolean): this;
 
@@ -3883,6 +3991,7 @@ export interface Store {
    * // -> '{}'
    * ```
    * @category Deleter
+   * @since v1.0.0
    */
   delTablesSchema(): this;
 
@@ -4064,6 +4173,7 @@ export interface Store {
    * // -> {open: true}
    * ```
    * @category Transaction
+   * @since v1.0.0
    */
   transaction<Return>(actions: () => Return, doRollback?: DoRollback): Return;
 
@@ -4332,6 +4442,7 @@ export interface Store {
    * // -> '- dog'
    * ```
    * @category Iterator
+   * @since v1.0.0
    */
   forEachTable(tableCallback: TableCallback): void;
 
@@ -4399,6 +4510,7 @@ export interface Store {
    * // -> '- color'
    * ```
    * @category Iterator
+   * @since v1.0.0
    */
   forEachRow(tableId: Id, rowCallback: RowCallback): void;
 
@@ -4428,6 +4540,7 @@ export interface Store {
    * // -> 'color: brown'
    * ```
    * @category Iterator
+   * @since v1.0.0
    */
   forEachCell(tableId: Id, rowId: Id, cellCallback: CellCallback): void;
 
@@ -4593,6 +4706,7 @@ export interface Store {
    * store.delListener(listenerId);
    * ```
    * @category Listener
+   * @since v1.0.0
    */
   addTablesListener(listener: TablesListener<this>, mutator?: boolean): Id;
 
@@ -4659,6 +4773,7 @@ export interface Store {
    * store.delListener(listenerId);
    * ```
    * @category Listener
+   * @since v1.0.0
    */
   addTableIdsListener(listener: TableIdsListener<this>, mutator?: boolean): Id;
 
@@ -4864,6 +4979,7 @@ export interface Store {
    * store.delListener(listenerId);
    * ```
    * @category Listener
+   * @since v1.0.0
    */
   addTableListener(
     tableId: IdOrNull,
@@ -4974,6 +5090,7 @@ export interface Store {
    * store.delListener(listenerId);
    * ```
    * @category Listener
+   * @since v1.0.0
    */
   addTableCellIdsListener(
     tableId: IdOrNull,
@@ -5295,6 +5412,7 @@ export interface Store {
    * store.delListener(listenerId);
    * ```
    * @category Listener
+   * @since v1.0.0
    */
   addRowIdsListener(
     tableId: IdOrNull,
@@ -5767,6 +5885,7 @@ export interface Store {
    * store.delListener(listenerId);
    * ```
    * @category Listener
+   * @since v1.0.0
    */
   addRowListener(
     tableId: IdOrNull,
@@ -5878,6 +5997,7 @@ export interface Store {
    * store.delListener(listenerId);
    * ```
    * @category Listener
+   * @since v1.0.0
    */
   addCellIdsListener(
     tableId: IdOrNull,
@@ -6132,6 +6252,7 @@ export interface Store {
    * store.delListener(listenerId);
    * ```
    * @category Listener
+   * @since v1.0.0
    */
   addCellListener(
     tableId: IdOrNull,
@@ -7326,6 +7447,7 @@ export interface Store {
    * store.delListener(listenerId2);
    * ```
    * @category Listener
+   * @since v1.0.0
    */
   callListener(listenerId: Id): this;
 
@@ -7360,6 +7482,7 @@ export interface Store {
    * // The listener is not called.
    * ```
    * @category Listener
+   * @since v1.0.0
    */
   delListener(listenerId: Id): this;
 
@@ -7390,6 +7513,7 @@ export interface Store {
    * // -> 1
    * ```
    * @category Development
+   * @since v1.0.0
    */
   getListenerStats(): StoreListenerStats;
 
@@ -7450,5 +7574,6 @@ export interface Store {
  * ```
  * @see The Basics guides
  * @category Creation
+ * @since v1.0.0
  */
 export function createStore(): Store;