tinybase 3.1.0-beta.5 → 3.1.0

package/lib/types/with-schemas/persisters.d.ts

@@ -150,6 +150,12 @@ 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
@@ -216,6 +222,15 @@ export interface Persister<in out Schemas extends OptionalSchemas> {
    * 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
@@ -274,6 +289,12 @@ export interface Persister<in out Schemas extends OptionalSchemas> {
    * 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<in out Schemas extends OptionalSchemas> {
    * 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<in out Schemas extends OptionalSchemas> {
    * 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<in out Schemas extends OptionalSchemas> {
    * 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<in out Schemas extends OptionalSchemas> {
    * 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<in out Schemas extends OptionalSchemas> {
    * 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<in out Schemas extends OptionalSchemas> {
  * 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.

package/lib/types/with-schemas/queries.d.ts

@@ -266,6 +266,16 @@ export type ResultCellCallback = (cellId: Id, cell: ResultCell) => void;
  * The ResultTableListener type describes a function that is used to listen to
  * changes to a query's ResultTable.
  *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * (
+ *   queries: Queries,
+ *   tableId: Id,
+ *   getCellChange: GetCellResultChange,
+ * ) => void;
+ * ```
+ *
  * A ResultTableListener is provided when using the addResultTableListener
  * method. See that method for specific examples.
  *
@@ -292,6 +302,12 @@ export type ResultTableListener<Schemas extends OptionalSchemas> = (
  * The ResultRowIdsListener type describes a function that is used to listen to
  * changes to the ResultRow Ids in a query's ResultTable.
  *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * (queries: Queries, tableId: Id) => void;
+ * ```
+ *
  * A ResultRowIdsListener is provided when using the addResultRowIdsListener
  * method. See that method for specific examples.
  *
@@ -314,6 +330,20 @@ export type ResultRowIdsListener<Schemas extends OptionalSchemas> = (
  * The ResultSortedRowIdsListener type describes a function that is used to
  * listen to changes to the sorted ResultRow Ids in a query's ResultTable.
  *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * (
+ *   queries: Queries,
+ *   tableId: Id,
+ *   cellId: Id | undefined,
+ *   descending: boolean,
+ *   offset: number,
+ *   limit: number | undefined,
+ *   sortedRowIds: Ids,
+ * ) => void;
+ * ```
+ *
  * A ResultSortedRowIdsListener is provided when using the
  * addResultSortedRowIdsListener method. See that method for specific examples.
  *
@@ -351,6 +381,17 @@ export type ResultSortedRowIdsListener<Schemas extends OptionalSchemas> = (
  * The ResultRowListener type describes a function that is used to listen to
  * changes to a ResultRow in a query's ResultTable.
  *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * (
+ *   queries: Queries,
+ *   tableId: Id,
+ *   rowId: Id,
+ *   getCellChange: GetCellResultChange,
+ * ) => void;
+ * ```
+ *
  * A ResultRowListener is provided when using the addResultRowListener method.
  * See that method for specific examples.
  *
@@ -379,6 +420,16 @@ export type ResultRowListener<Schemas extends OptionalSchemas> = (
  * The ResultCellIdsListener type describes a function that is used to listen to
  * changes to the ResultCell Ids in a ResultRow in a query's ResultTable.
  *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * (
+ *   queries: Queries,
+ *   tableId: Id,
+ *   rowId: Id,
+ * ) => void;
+ * ```
+ *
  * A ResultCellIdsListener is provided when using the addResultCellIdsListener
  * method. See that method for specific examples.
  *
@@ -403,6 +454,20 @@ export type ResultCellIdsListener<Schemas extends OptionalSchemas> = (
  * The ResultCellListener type describes a function that is used to listen to
  * changes to a ResultCell in a query's ResultTable.
  *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * (
+ *   queries: Queries,
+ *   tableId: Id,
+ *   rowId: Id,
+ *   cellId: Id,
+ *   newCell: ResultCell,
+ *   oldCell: ResultCell,
+ *   getCellChange: GetCellResultChange,
+ * ) => void;
+ * ```
+ *
  * A ResultCellListener is provided when using the addResultCellListener method.
  * See that method for specific examples.
  *
@@ -527,6 +592,12 @@ export type GetTableCell<
    * the specified Cell from the query's root Table for the Row being selected
    * or filtered.
    *
+   * This has schema-based typing. The following is a simplified representation:
+   *
+   * ```ts override
+   * (cellId: Id): CellOrUndefined;
+   * ```
+   *
    * @param cellId The Id of the Cell to fetch the value for.
    * @returns A Cell value or `undefined`.
    */
@@ -538,6 +609,13 @@ export type GetTableCell<
    * the specified Cell from a Table that has been joined in the query, for
    * the Row being selected or filtered.
    *
+   * This has schema-based typing. The following is a simplified representation:
+   *
+   * ```ts override
+   * (joinedTableId: Id, joinedCellId: Id): CellOrUndefined;
+};
+   * ```
+   *
    * @param joinedTableId The Id of the Table to fetch the value from. If the
    * underlying Table was joined 'as' a different Id, that should instead be
    * used.
@@ -665,6 +743,12 @@ export type Select<
    * Calling this function with one Id parameter will indicate that the query
    * should select the value of the specified Cell from the query's root Table.
    *
+   * This has schema-based typing. The following is a simplified representation:
+   *
+   * ```ts override
+   * (cellId: Id): SelectedAs;
+   * ```
+   *
    * @param cellId The Id of the Cell to fetch the value for.
    * @returns A SelectedAs object so that the selected Cell Id can be optionally
    * aliased.
@@ -677,6 +761,12 @@ export type Select<
    * should select the value of the specified Cell from a Table that has been
    * joined in the query.
    *
+   * This has schema-based typing. The following is a simplified representation:
+   *
+   * ```ts override
+   * (joinedTableId: Id, joinedCellId: Id): SelectedAs;
+   * ```
+   *
    * @param joinedTableId The Id of the Table to fetch the value from. If the
    * underlying Table was joined 'as' a different Id, that should instead be
    * used.
@@ -693,6 +783,15 @@ export type Select<
    * query should select a calculated value, based on one or more Cell values in
    * the root Table or a joined Table, or on the root Table's Row Id.
    *
+   * This has schema-based typing. The following is a simplified representation:
+   *
+   * ```ts override
+   * (
+   *   getCell: (getTableCell: GetTableCell, rowId: Id) => ResultCellOrUndefined,
+   * ): SelectedAs;
+};
+   * ```
+   *
    * @param getCell A callback that takes a GetTableCell function and the main
    * Table's Row Id. These can be used to programmatically create a calculated
    * value from multiple Cell values and the Row Id.
@@ -936,6 +1035,12 @@ export type Join<
    * a Row in an adjacent Table is made by finding its Id in a Cell of the
    * query's root Table.
    *
+   * This has schema-based typing. The following is a simplified representation:
+   *
+   * ```ts override
+   * (joinedTableId: Id, on: Id): JoinedAs;
+   * ```
+   *
    * @param joinedTableId The Id of the Table to join to.
    * @param on The Id of the Cell in the root Table that contains the joined
    * Table's Row Id.
@@ -951,6 +1056,15 @@ export type Join<
    * will indicate that the join to a Row in an adjacent Table is made by
    * calculating its Id from the Cells and the Row Id of the query's root Table.
    *
+   * This has schema-based typing. The following is a simplified representation:
+   *
+   * ```ts override
+   * (
+   *   joinedTableId: Id,
+   *   on: (getCell: GetCell, rowId: Id) => Id | undefined,
+   * ): JoinedAs;
+   * ```
+   *
    * @param joinedTableId The Id of the Table to join to.
    * @param on A callback that takes a GetCell function and the root Table's Row
    * Id. These can be used to programmatically calculate the joined Table's Row
@@ -967,6 +1081,12 @@ export type Join<
    * to a Row in distant Table is made by finding its Id in a Cell of an
    * intermediately joined Table.
    *
+   * This has schema-based typing. The following is a simplified representation:
+   *
+   * ```ts override
+   * (joinedTableId: Id, fromIntermediateJoinedTableId: Id, on: Id): JoinedAs;
+   * ```
+   *
    * @param joinedTableId The Id of the distant Table to join to.
    * @param fromIntermediateJoinedTableId The Id of an intermediate Table (which
    * should have been in turn joined to the main query table via other Join
@@ -995,6 +1115,20 @@ export type Join<
    * calculating its Id from the Cells and the Row Id of an intermediately
    * joined Table.
    *
+   * This has schema-based typing. The following is a simplified representation:
+   *
+   * ```ts override
+   * (
+   *   joinedTableId: Id,
+   *   fromIntermediateJoinedTableId: Id,
+   *   on: (
+   *     getIntermediateJoinedCell: GetCell,
+   *     intermediateJoinedRowId: Id,
+   *   ) => Id | undefined,
+   * ): JoinedAs;
+};
+   * ```
+   *
    * @param joinedTableId The Id of the Table to join to.
    * @param fromIntermediateJoinedTableId The Id of an intermediate Table (which
    * should have been in turn joined to the main query table via other Join
@@ -1203,6 +1337,12 @@ export type Where<
    * Rows for which a specified Cell in the query's root Table has a specified
    * value.
    *
+   * This has schema-based typing. The following is a simplified representation:
+   *
+   * ```ts override
+   * (cellId: Id, equals: Cell): void;
+   * ```
+   *
    * @param cellId The Id of the Cell in the query's root Table to test.
    * @param equals The value that the Cell has to have for the Row to be
    * included in the result.
@@ -1215,6 +1355,12 @@ export type Where<
    * Calling this function with three parameters is used to include only those
    * Rows for which a specified Cell in a joined Table has a specified value.
    *
+   * This has schema-based typing. The following is a simplified representation:
+   *
+   * ```ts override
+   * (joinedTableId: Id, joinedCellId: Id, equals: Cell): void;
+   * ```
+   *
    * @param joinedTableId The Id of the joined Table to test a value in. If the
    * underlying Table was joined 'as' a different Id, that should instead be
    * used.
@@ -1243,6 +1389,13 @@ export type Where<
    * those Rows which meet a calculated boolean condition, based on values in
    * the main and (optionally) joined Tables.
    *
+   * This has schema-based typing. The following is a simplified representation:
+   *
+   * ```ts override
+   * (condition: (getTableCell: GetTableCell) => boolean): void;
+};
+   * ```
+   *
    * @param condition A callback that takes a GetTableCell function and that
    * should return `true` for the Row to be included in the result.
    */
@@ -1686,6 +1839,22 @@ export interface Queries<in out Schemas extends OptionalSchemas> {
   /**
    * The setQueryDefinition method lets you set the definition of a query.
    *
+   * This has schema-based typing. The following is a simplified representation:
+   *
+   * ```ts override
+   * setQueryDefinition(
+   *   queryId: Id,
+   *   tableId: Id,
+   *   query: (keywords: {
+   *     select: Select;
+   *     join: Join;
+   *     where: Where;
+   *     group: Group;
+   *     having: Having;
+   *   }) => void,
+   * ): Queries;
+   * ```
+   *
    * Every query definition is identified by a unique Id, and if you re-use an
    * existing Id with this method, the previous definition is overwritten.
    *
@@ -1761,6 +1930,12 @@ export interface Queries<in out Schemas extends OptionalSchemas> {
   /**
    * The delQueryDefinition method removes an existing query definition.
    *
+   * This has schema-based typing. The following is a simplified representation:
+   *
+   * ```ts override
+   * delQueryDefinition(queryId: Id): Queries;
+   * ```
+   *
    * @param queryId The Id of the query to remove.
    * @returns A reference to the Queries object.
    * @example
@@ -1795,6 +1970,12 @@ export interface Queries<in out Schemas extends OptionalSchemas> {
    * The getStore method returns a reference to the underlying Store that is
    * backing this Queries 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 Queries object against a newly-created Store and
@@ -1912,6 +2093,12 @@ export interface Queries<in out Schemas extends OptionalSchemas> {
    * The getTableId method returns the Id of the underlying Table that is
    * backing a query.
    *
+   * This has schema-based typing. The following is a simplified representation:
+   *
+   * ```ts override
+   * getTableId(queryId: Id): Id | undefined;
+   * ```
+   *
    * If the query Id is invalid, the method returns `undefined`.
    *
    * @param queryId The Id of a query.
@@ -2487,6 +2674,12 @@ export interface Queries<in out Schemas extends OptionalSchemas> {
    * The addResultTableListener method registers a listener function with the
    * Queries object that will be called whenever data in a ResultTable changes.
    *
+   * This has schema-based typing. The following is a simplified representation:
+   *
+   * ```ts override
+   * addResultTableListener(queryId: IdOrNull, listener: ResultTableListener): Id;
+   * ```
+   *
    * The provided listener is a ResultTableListener function, and will be called
    * with a reference to the Queries object, the Id of the ResultTable that
    * changed (which is also the query Id), and a GetCellResultChange function in
@@ -2582,6 +2775,15 @@ export interface Queries<in out Schemas extends OptionalSchemas> {
    * Queries object that will be called whenever the ResultRow Ids in a
    * ResultTable change.
    *
+   * This has schema-based typing. The following is a simplified representation:
+   *
+   * ```ts override
+   * addResultRowIdsListener(
+   *   queryId: IdOrNull,
+   *   listener: ResultRowIdsListener,
+   * ): Id;
+   * ```
+   *
    * The provided listener is a ResultRowIdsListener function, and will be
    * called with a reference to the Queries object and the Id of the ResultTable
    * that changed (which is also the query Id).
@@ -2680,6 +2882,19 @@ export interface Queries<in out Schemas extends OptionalSchemas> {
    * the Queries object that will be called whenever sorted (and optionally,
    * paginated) ResultRow Ids in a ResultTable change.
    *
+   * This has schema-based typing. The following is a simplified representation:
+   *
+   * ```ts override
+   * addResultSortedRowIdsListener(
+   *   queryId: Id,
+   *   cellId: Id | undefined,
+   *   descending: boolean,
+   *   offset: number,
+   *   limit: number | undefined,
+   *   listener: ResultSortedRowIdsListener,
+   * ): Id;
+   * ```
+   *
    * The provided listener is a ResultSortedRowIdsListener function, and will be
    * called with a reference to the Queries object, the Id of the ResultTable
    * whose ResultRow Ids sorting changed (which is also the query Id), the
@@ -2810,6 +3025,16 @@ export interface Queries<in out Schemas extends OptionalSchemas> {
    * The addResultRowListener method registers a listener function with the
    * Queries object that will be called whenever data in a ResultRow changes.
    *
+   * This has schema-based typing. The following is a simplified representation:
+   *
+   * ```ts override
+   * addResultRowListener(
+   *   queryId: IdOrNull,
+   *   rowId: IdOrNull,
+   *   listener: ResultRowListener,
+   * ): Id;
+   * ```
+   *
    * The provided listener is a ResultRowListener function, and will be called
    * with a reference to the Queries object, the Id of the ResultTable that
    * changed (which is also the query Id), and a GetCellResultChange function in
@@ -2914,6 +3139,16 @@ export interface Queries<in out Schemas extends OptionalSchemas> {
    * Queries object that will be called whenever the ResultCell Ids in a
    * ResultRow change.
    *
+   * This has schema-based typing. The following is a simplified representation:
+   *
+   * ```ts override
+   * addResultCellIdsListener(
+   *   queryId: IdOrNull,
+   *   rowId: IdOrNull,
+   *   listener: ResultCellIdsListener,
+   * ): Id;
+   * ```
+   *
    * The provided listener is a ResultCellIdsListener function, and will be
    * called with a reference to the Queries object, the Id of the ResultTable
    * (which is also the query Id), and the Id of the ResultRow that changed.
@@ -3025,6 +3260,17 @@ export interface Queries<in out Schemas extends OptionalSchemas> {
    * The addResultCellListener method registers a listener function with the
    * Queries object that will be called whenever data in a ResultCell changes.
    *
+   * This has schema-based typing. The following is a simplified representation:
+   *
+   * ```ts override
+   * addResultCellListener(
+   *   queryId: IdOrNull,
+   *   rowId: IdOrNull,
+   *   cellId: IdOrNull,
+   *   listener: ResultCellListener,
+   * ): Id;
+   * ```
+   *
    * The provided listener is a ResultCellListener function, and will be called
    * with a reference to the Queries object, the Id of the ResultTable that
    * changed (which is also the query Id), the Id of the ResultRow that changed,
@@ -3142,6 +3388,12 @@ export interface Queries<in out Schemas extends OptionalSchemas> {
    * The delListener method removes a listener that was previously added to the
    * Queries object.
    *
+   * This has schema-based typing. The following is a simplified representation:
+   *
+   * ```ts override
+   * delListener(listenerId: Id): Queries;
+   * ```
+   *
    * Use the Id returned by the addMetricListener method. Note that the Queries
    * object may re-use this Id for future listeners added to it.
    *
@@ -3255,6 +3507,12 @@ export interface Queries<in out Schemas extends OptionalSchemas> {
  * The createQueries function creates a Queries object, and is the main entry
  * point into the queries module.
  *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * createQueries(store: Store): Queries;
+ * ```
+ *
  * A given Store can only have one Queries object associated with it. If you
  * call this function twice on the same Store, your second call will return a
  * reference to the Queries object created by the first.