tinybase 3.1.0-beta.4 → 3.1.0

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

@@ -11,10 +11,11 @@
  * @module relationships
  */
 
+import {CellIdFromSchema, TableIdFromSchema} from './internal/store';
 import {
   GetCell,
-  NoSchemas,
   OptionalSchemas,
+  OptionalTablesSchema,
   RowCallback,
   Store,
 } from './store.d';
@@ -49,6 +50,15 @@ export type Relationship = {
  * The RelationshipCallback type describes a function that takes a
  * Relationship's Id and a callback to loop over each local Row within it.
  *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * (
+ *   relationshipId: Id,
+ *   forEachRow: (rowCallback: RowCallback) => void,
+ * ) => void;
+ * ```
+ *
  * 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.
@@ -59,15 +69,25 @@ export type Relationship = {
  * objects in this Relationship.
  * @category Callback
  */
-export type RelationshipCallback = (
+export type RelationshipCallback<Schema extends OptionalTablesSchema> = (
   relationshipId: Id,
-  forEachRow: (rowCallback: RowCallback) => void,
+  forEachRow: (rowCallback: RowCallback<Schema>) => void,
 ) => void;
 
 /**
  * The RemoteRowIdListener type describes a function that is used to listen to
  * changes to the remote Row Id end of a Relationship.
  *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * (
+ *   relationships: Relationships,
+ *   relationshipId: Id,
+ *   localRowId: Id,
+ * ) => void;
+ * ```
+ *
  * A RemoteRowIdListener is provided when using the addRemoteRowIdListener
  * method. See that method for specific examples.
  *
@@ -80,8 +100,8 @@ export type RelationshipCallback = (
  * @param localRowId The Id of the local Row whose remote Row Id changed.
  * @category Listener
  */
-export type RemoteRowIdListener = (
-  relationships: Relationships,
+export type RemoteRowIdListener<Schemas extends OptionalSchemas> = (
+  relationships: Relationships<Schemas>,
   relationshipId: Id,
   localRowId: Id,
 ) => void;
@@ -90,6 +110,16 @@ export type RemoteRowIdListener = (
  * The LocalRowIdsListener type describes a function that is used to listen to
  * changes to the local Row Id ends of a Relationship.
  *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * (
+ *   relationships: Relationships,
+ *   relationshipId: Id,
+ *   remoteRowId: Id,
+ * ) => void;
+ * ```
+ *
  * A LocalRowIdsListener is provided when using the addLocalRowIdsListener
  * method. See that method for specific examples.
  *
@@ -102,8 +132,8 @@ export type RemoteRowIdListener = (
  * @param remoteRowId The Id of the remote Row whose local Row Ids changed.
  * @category Listener
  */
-export type LocalRowIdsListener = (
-  relationships: Relationships,
+export type LocalRowIdsListener<Schemas extends OptionalSchemas> = (
+  relationships: Relationships<Schemas>,
   relationshipId: Id,
   remoteRowId: Id,
 ) => void;
@@ -112,6 +142,16 @@ export type LocalRowIdsListener = (
  * The LinkedRowIdsListener type describes a function that is used to listen to
  * changes to the local Row Id ends of a Relationship.
  *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * (
+ *   relationships: Relationships,
+ *   relationshipId: Id,
+ *   firstRowId: Id,
+ * ) => void;
+ * ```
+ *
  * A LinkedRowIdsListener is provided when using the addLinkedRowIdsListener
  * method. See that method for specific examples.
  *
@@ -125,8 +165,8 @@ export type LocalRowIdsListener = (
  * members changed.
  * @category Listener
  */
-export type LinkedRowIdsListener = (
-  relationships: Relationships,
+export type LinkedRowIdsListener<Schemas extends OptionalSchemas> = (
+  relationships: Relationships<Schemas>,
   relationshipId: Id,
   firstRowId: Id,
 ) => void;
@@ -253,11 +293,22 @@ export type RelationshipsListenerStats = {
  * @see Drawing demo
  * @category Relationships
  */
-export interface Relationships<Schemas extends OptionalSchemas = NoSchemas> {
+export interface Relationships<in out Schemas extends OptionalSchemas> {
   /**
    * The setRelationshipDefinition method lets you set the definition of a
    * Relationship.
    *
+   * This has schema-based typing. The following is a simplified representation:
+   *
+   * ```ts override
+   * setRelationshipDefinition(
+   *   relationshipId: Id,
+   *   localTableId: Id,
+   *   remoteTableId: Id,
+   *   getRemoteRowId: Id | ((getCell: GetCell, localRowId: Id) => Id),
+   * ): Relationships;
+   * ```
+   *
    * Every Relationship definition is identified by a unique Id, and if you
    * re-use an existing Id with this method, the previous definition is
    * overwritten.
@@ -340,17 +391,25 @@ export interface Relationships<Schemas extends OptionalSchemas = NoSchemas> {
    * ```
    * @category Configuration
    */
-  setRelationshipDefinition(
+  setRelationshipDefinition<LocalTableId extends TableIdFromSchema<Schemas[0]>>(
     relationshipId: Id,
-    localTableId: Id,
-    remoteTableId: Id,
-    getRemoteRowId: Id | ((getCell: GetCell, localRowId: Id) => Id),
+    localTableId: LocalTableId,
+    remoteTableId: TableIdFromSchema<Schemas[0]>,
+    getRemoteRowId:
+      | CellIdFromSchema<Schemas[0], LocalTableId>
+      | ((getCell: GetCell<Schemas[0], LocalTableId>, localRowId: Id) => Id),
   ): Relationships<Schemas>;
 
   /**
    * The delRelationshipDefinition method removes an existing Relationship
    * definition.
    *
+   * This has schema-based typing. The following is a simplified representation:
+   *
+   * ```ts override
+   * delRelationshipDefinition(relationshipId: Id): Relationships;
+   * ```
+   *
    * @param relationshipId The Id of the Relationship to remove.
    * @returns A reference to the Relationships object.
    * @example
@@ -391,6 +450,12 @@ export interface Relationships<Schemas extends OptionalSchemas = NoSchemas> {
    * The getStore method returns a reference to the underlying Store that is
    * backing this Relationships 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 Relationships object against a newly-created Store
@@ -436,6 +501,12 @@ export interface Relationships<Schemas extends OptionalSchemas = NoSchemas> {
    * The forEachRelationship method takes a function that it will then call for
    * each Relationship in a specified Relationships object.
    *
+   * This has schema-based typing. The following is a simplified representation:
+   *
+   * ```ts override
+   * forEachRelationship(relationshipCallback: RelationshipCallback): void;
+   * ```
+   *
    * This method is useful for iterating over the structure of the Relationships
    * object in a functional style. The `relationshipCallback` parameter is a
    * RelationshipCallback function that will be called with the Id of each
@@ -473,7 +544,9 @@ export interface Relationships<Schemas extends OptionalSchemas = NoSchemas> {
    * ```
    * @category Iterator
    */
-  forEachRelationship(relationshipCallback: RelationshipCallback): void;
+  forEachRelationship(
+    relationshipCallback: RelationshipCallback<Schemas[0]>,
+  ): void;
 
   /**
    * The hasRelationship method returns a boolean indicating whether a given
@@ -502,6 +575,12 @@ export interface Relationships<Schemas extends OptionalSchemas = NoSchemas> {
    * The getLocalTableId method returns the Id of the underlying local Table
    * that is used in the Relationship.
    *
+   * This has schema-based typing. The following is a simplified representation:
+   *
+   * ```ts override
+   * getLocalTableId(relationshipId: Id): Id | undefined;
+   * ```
+   *
    * If the Relationship Id is invalid, the method returns `undefined`.
    *
    * @param relationshipId The Id of a Relationship.
@@ -528,12 +607,20 @@ export interface Relationships<Schemas extends OptionalSchemas = NoSchemas> {
    * ```
    * @category Getter
    */
-  getLocalTableId(relationshipId: Id): Id;
+  getLocalTableId<TableId extends TableIdFromSchema<Schemas[0]>>(
+    relationshipId: Id,
+  ): TableId | undefined;
 
   /**
    * The getRemoteTableId method returns the Id of the underlying remote Table
    * that is used in the Relationship.
    *
+   * This has schema-based typing. The following is a simplified representation:
+   *
+   * ```ts override
+   * getRemoteTableId(relationshipId: Id): Id | undefined;
+   * ```
+   *
    * If the Relationship Id is invalid, the method returns `undefined`.
    *
    * @param relationshipId The Id of a Relationship.
@@ -560,7 +647,9 @@ export interface Relationships<Schemas extends OptionalSchemas = NoSchemas> {
    * ```
    * @category Getter
    */
-  getRemoteTableId(relationshipId: Id): Id;
+  getRemoteTableId<TableId extends TableIdFromSchema<Schemas[0]>>(
+    relationshipId: Id,
+  ): TableId | undefined;
 
   /**
    * The getRemoteRowId method gets the remote Row Id for a given local Row in a
@@ -710,6 +799,16 @@ export interface Relationships<Schemas extends OptionalSchemas = NoSchemas> {
    * Relationships object that will be called whenever a remote Row Id in a
    * Relationship changes.
    *
+   * This has schema-based typing. The following is a simplified representation:
+   *
+   * ```ts override
+   * addRemoteRowIdListener(
+   *   relationshipId: IdOrNull,
+   *   localRowId: IdOrNull,
+   *   listener: RemoteRowIdListener,
+   * ): Id;
+   * ```
+   *
    * You can either listen to a single local Row (by specifying the Relationship
    * Id and local Row Id as the method's first two parameters), or changes to
    * any local Row (by providing a `null` wildcards).
@@ -833,7 +932,7 @@ export interface Relationships<Schemas extends OptionalSchemas = NoSchemas> {
   addRemoteRowIdListener(
     relationshipId: IdOrNull,
     localRowId: IdOrNull,
-    listener: RemoteRowIdListener,
+    listener: RemoteRowIdListener<Schemas>,
   ): Id;
 
   /**
@@ -841,6 +940,16 @@ export interface Relationships<Schemas extends OptionalSchemas = NoSchemas> {
    * Relationships object that will be called whenever the local Row Ids in
    * a Relationship change.
    *
+   * This has schema-based typing. The following is a simplified representation:
+   *
+   * ```ts override
+   * addLocalRowIdsListener(
+   *   relationshipId: IdOrNull,
+   *   remoteRowId: IdOrNull,
+   *   listener: LocalRowIdsListener,
+   * ): Id;
+   * ```
+   *
    * You can either listen to a single local Row (by specifying the Relationship
    * Id and local Row Id as the method's first two parameters), or changes to
    * any local Row (by providing a `null` wildcards).
@@ -959,7 +1068,7 @@ export interface Relationships<Schemas extends OptionalSchemas = NoSchemas> {
   addLocalRowIdsListener(
     relationshipId: IdOrNull,
     remoteRowId: IdOrNull,
-    listener: LocalRowIdsListener,
+    listener: LocalRowIdsListener<Schemas>,
   ): Id;
 
   /**
@@ -967,6 +1076,16 @@ export interface Relationships<Schemas extends OptionalSchemas = NoSchemas> {
    * Relationships object that will be called whenever the linked Row Ids in a
    * linked list Relationship change.
    *
+   * This has schema-based typing. The following is a simplified representation:
+   *
+   * ```ts override
+   * addLinkedRowIdsListener(
+   *   relationshipId: Id,
+   *   firstRowId: Id,
+   *   listener: LinkedRowIdsListener,
+   * ): Id;
+   * ```
+   *
    * A linked list Relationship is one that has the same Table specified as both
    * local Table Id and remote Table Id, allowing you to create a sequence of
    * Row objects within that one Table.
@@ -1030,13 +1149,19 @@ export interface Relationships<Schemas extends OptionalSchemas = NoSchemas> {
   addLinkedRowIdsListener(
     relationshipId: Id,
     firstRowId: Id,
-    listener: LinkedRowIdsListener,
+    listener: LinkedRowIdsListener<Schemas>,
   ): Id;
 
   /**
    * The delListener method removes a listener that was previously added to the
    * Relationships object.
    *
+   * This has schema-based typing. The following is a simplified representation:
+   *
+   * ```ts override
+   * delListener(listenerId: Id): Relationships;
+   * ```
+   *
    * 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.
@@ -1176,6 +1301,12 @@ export interface Relationships<Schemas extends OptionalSchemas = NoSchemas> {
  * The createRelationships function creates a Relationships object, and is the
  * main entry point into the relationships module.
  *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * createRelationships(store: Store): Relationships;
+ * ```
+ *
  * 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.