tinybase 4.0.0-beta.4 → 4.0.0-beta.5.1

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

@@ -6,7 +6,6 @@
  * which returns a new Relationships object. From there, you can create new
  * Relationship definitions, access the associations within those Relationships
  * directly, and register listeners for when they change.
- *
  * @packageDocumentation
  * @module relationships
  */
@@ -37,7 +36,6 @@ import {Id, IdOrNull, Ids} from './common.d';
  * Note that the Relationship type is not actually used in the API, and you
  * instead enumerate and access its structure with the getRemoteRowId method,
  * the getLocalRowIds method, and the getLinkedRowIds method.
- *
  * @category Concept
  */
 export type Relationship = {
@@ -62,7 +60,6 @@ export type Relationship = {
  * A RelationshipCallback is provided when using the forEachRelationship method,
  * so that you can do something based on every Relationship in the Relationships
  * object. See that method for specific examples.
- *
  * @param relationshipId The Id of the Relationship that the callback can
  * operate on.
  * @param forEachRow A function that will let you iterate over the local Row
@@ -94,7 +91,6 @@ export type RelationshipCallback<Schema extends OptionalTablesSchema> = (
  * When called, a RemoteRowIdListener is given a reference to the Relationships
  * object, the Id of the Relationship that changed, and the Id of the local Row
  * whose remote Row Id changed.
- *
  * @param relationships A reference to the Relationships object that changed.
  * @param relationshipId The Id of the Relationship that changed.
  * @param localRowId The Id of the local Row whose remote Row Id changed.
@@ -126,7 +122,6 @@ export type RemoteRowIdListener<Schemas extends OptionalSchemas> = (
  * When called, a LocalRowIdsListener is given a reference to the Relationships
  * object, the Id of the Relationship that changed, and the Id of the remote Row
  * whose local Row Ids changed.
- *
  * @param relationships A reference to the Relationships object that changed.
  * @param relationshipId The Id of the Relationship that changed.
  * @param remoteRowId The Id of the remote Row whose local Row Ids changed.
@@ -158,7 +153,6 @@ export type LocalRowIdsListener<Schemas extends OptionalSchemas> = (
  * When called, a LinkedRowIdsListener is given a reference to the Relationships
  * object, the Id of the Relationship that changed, and the Id of the first Row
  * of the the linked list whose members changed.
- *
  * @param relationships A reference to the Relationships object that changed.
  * @param relationshipId The Id of the Relationship that changed.
  * @param firstRowId The Id of the first Row of the the linked list whose
@@ -178,7 +172,6 @@ export type LinkedRowIdsListener<Schemas extends OptionalSchemas> = (
  *
  * A RelationshipsListenerStats object is returned from the getListenerStats
  * method, and is only populated in a debug build.
- *
  * @category Development
  */
 export type RelationshipsListenerStats = {
@@ -218,7 +211,6 @@ export type RelationshipsListenerStats = {
  * This module defaults to creating relationships between Row objects by using
  * one of their Cell values. However, far more complex relationships can be
  * configured with a custom function.
- *
  * @example
  * This example shows a very simple lifecycle of a Relationships object: from
  * creation, to adding definitions (both local/remote table and linked list),
@@ -327,7 +319,6 @@ export interface Relationships<in out Schemas extends OptionalSchemas> {
    * Cell values contains the (remote) Row Id, using the `getRemoteRowId`
    * parameter. Alternatively, a custom function can be provided that produces
    * your own remote Row Id from the local Row as a whole.
-   *
    * @param relationshipId The Id of the Relationship to define.
    * @param localTableId The Id of the local Table for the Relationship.
    * @param remoteTableId The Id of the remote Table for the Relationship (or
@@ -403,6 +394,11 @@ export interface Relationships<in out Schemas extends OptionalSchemas> {
   /**
    * The delRelationshipDefinition method removes an existing Relationship
    * definition.
+   * @param relationshipId The Id of the Relationship to remove.
+   * @returns A reference to the Relationships object.
+   * @example
+   * This example creates a Store, creates a Relationships object, defines a
+   * simple Relationship, and then removes it.
    *
    * This has schema-based typing. The following is a simplified representation:
    *
@@ -410,12 +406,6 @@ export interface Relationships<in out Schemas extends OptionalSchemas> {
    * delRelationshipDefinition(relationshipId: Id): Relationships;
    * ```
    *
-   * @param relationshipId The Id of the Relationship to remove.
-   * @returns A reference to the Relationships object.
-   * @example
-   * This example creates a Store, creates a Relationships object, defines a
-   * simple Relationship, and then removes it.
-   *
    * ```js
    * const store = createStore()
    *   .setTable('pets', {
@@ -449,6 +439,10 @@ export interface Relationships<in out Schemas extends OptionalSchemas> {
   /**
    * The getStore method returns a reference to the underlying Store that is
    * backing this Relationships object.
+   * @returns A reference to the Store.
+   * @example
+   * This example creates a Relationships object against a newly-created Store
+   * and then gets its reference in order to update its data.
    *
    * This has schema-based typing. The following is a simplified representation:
    *
@@ -456,11 +450,6 @@ export interface Relationships<in out Schemas extends OptionalSchemas> {
    * getStore(): Store;
    * ```
    *
-   * @returns A reference to the Store.
-   * @example
-   * This example creates a Relationships object against a newly-created Store
-   * and then gets its reference in order to update its data.
-   *
    * ```js
    * const relationships = createRelationships(createStore());
    * relationships.setRelationshipDefinition(
@@ -480,7 +469,6 @@ export interface Relationships<in out Schemas extends OptionalSchemas> {
   /**
    * The getRelationshipIds method returns an array of the Relationship Ids
    * registered with this Relationships object.
-   *
    * @returns An array of Ids.
    * @example
    * This example creates a Relationships object with two definitions, and then
@@ -512,7 +500,6 @@ export interface Relationships<in out Schemas extends OptionalSchemas> {
    * RelationshipCallback function that will be called with the Id of each
    * Relationship, and with a function that can then be used to iterate over
    * each local Row involved in the Relationship.
-   *
    * @param relationshipCallback The function that should be called for every
    * Relationship.
    * @example
@@ -551,7 +538,6 @@ export interface Relationships<in out Schemas extends OptionalSchemas> {
   /**
    * The hasRelationship method returns a boolean indicating whether a given
    * Relationship exists in the Relationships object.
-   *
    * @param relationshipId The Id of a possible Relationship in the
    * Relationships object.
    * @returns Whether a Relationship with that Id exists.
@@ -582,7 +568,6 @@ export interface Relationships<in out Schemas extends OptionalSchemas> {
    * ```
    *
    * If the Relationship Id is invalid, the method returns `undefined`.
-   *
    * @param relationshipId The Id of a Relationship.
    * @returns The Id of the local Table backing the Relationship, or
    * `undefined`.
@@ -622,7 +607,6 @@ export interface Relationships<in out Schemas extends OptionalSchemas> {
    * ```
    *
    * If the Relationship Id is invalid, the method returns `undefined`.
-   *
    * @param relationshipId The Id of a Relationship.
    * @returns The Id of the remote Table backing the Relationship, or
    * `undefined`.
@@ -657,7 +641,6 @@ export interface Relationships<in out Schemas extends OptionalSchemas> {
    *
    * If the identified Relationship or Row does not exist (or if the definition
    * references a Table that does not exist) then `undefined` is returned.
-   *
    * @param relationshipId The Id of the Relationship.
    * @param localRowId The Id of the local Row in the Relationship.
    * @returns The remote Row Id in the Relationship, or `undefined`.
@@ -704,7 +687,6 @@ export interface Relationships<in out Schemas extends OptionalSchemas> {
    *
    * If the identified Relationship or Row does not exist (or if the definition
    * references a Table that does not exist) then an empty array is returned.
-   *
    * @param relationshipId The Id of the Relationship.
    * @param remoteRowId The Id of the remote Row in the Relationship.
    * @returns The local Row Ids in the Relationship, or an empty array.
@@ -756,7 +738,6 @@ export interface Relationships<in out Schemas extends OptionalSchemas> {
    * If the identified Relationship or Row does not exist (or if the definition
    * references a Table that does not exist) then an array containing just the
    * first Row Id is returned.
-   *
    * @param relationshipId The Id of the Relationship.
    * @param firstRowId The Id of the first Row in the linked list Relationship.
    * @returns The linked Row Ids in the Relationship.
@@ -822,7 +803,6 @@ export interface Relationships<in out Schemas extends OptionalSchemas> {
    * The provided listener is a RemoteRowIdListener function, and will be called
    * with a reference to the Relationships object, the Id of the Relationship,
    * and the Id of the local Row that had its remote Row change.
-   *
    * @param relationshipId The Id of the Relationship to listen to, or `null` as
    * a wildcard.
    * @param localRowId The Id of the local Row to listen to, or `null` as a
@@ -963,7 +943,6 @@ export interface Relationships<in out Schemas extends OptionalSchemas> {
    * The provided listener is a LocalRowIdsListener function, and will be called
    * with a reference to the Relationships object, the Id of the Relationship,
    * and the Id of the remote Row that had its local Row objects change.
-   *
    * @param relationshipId The Id of the Relationship to listen to, or `null` as
    * a wildcard.
    * @param remoteRowId The Id of the remote Row to listen to, or `null` as a
@@ -1102,7 +1081,6 @@ export interface Relationships<in out Schemas extends OptionalSchemas> {
    * The provided listener is a LinkedRowIdsListener function, and will be
    * called with a reference to the Relationships object, the Id of the
    * Relationship, and the Id of the first Row that had its linked list change.
-   *
    * @param relationshipId The Id of the Relationship to listen to.
    * @param firstRowId The Id of the first Row of the linked list to listen to.
    * @param listener The function that will be called whenever the linked Row
@@ -1165,7 +1143,6 @@ export interface Relationships<in out Schemas extends OptionalSchemas> {
    * Use the Id returned by whichever method was used to add the listener. Note
    * that the Relationships object may re-use this Id for future listeners added
    * to it.
-   *
    * @param listenerId The Id of the listener to remove.
    * @returns A reference to the Relationships object.
    * @example
@@ -1220,7 +1197,6 @@ export interface Relationships<in out Schemas extends OptionalSchemas> {
    *
    * This guarantees that all of the listeners that the object registered with
    * the underlying Store are removed and it can be correctly garbage collected.
-   *
    * @example
    * This example creates a Store, adds a Relationships object with a
    * definition (that registers a RowListener with the underlying Store),
@@ -1270,7 +1246,6 @@ export interface Relationships<in out Schemas extends OptionalSchemas> {
    * return an empty object. The method is intended to be used during
    * development to ensure your application is not leaking listener
    * registrations, for example.
-   *
    * @returns A RelationshipsListenerStats object containing Relationships
    * listener statistics.
    * @example
@@ -1310,7 +1285,6 @@ export interface Relationships<in out Schemas extends OptionalSchemas> {
  * A given Store can only have one Relationships object associated with it. If
  * you call this function twice on the same Store, your second call will return
  * a reference to the Relationships object created by the first.
- *
  * @param store The Store for which to register Relationships.
  * @returns A reference to the new Relationships object.
  * @example