tinybase 8.3.0-beta.0 → 8.3.0-beta.1

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

@@ -759,6 +759,20 @@ export type GetTableCell = {
    * @since v2.0.0
    */
   (joinedTableId: Id, joinedCellId: Id): CellOrUndefined;
+  /**
+   * Calling this function with three parameters (where the first is `true`)
+   * will return the value of the specified Cell from a query result that has
+   * been joined in the query, for the Row being selected or filtered.
+   * @param asQuery A flag indicating that the next Id is a query Id.
+   * @param joinedQueryId The Id of the query result to fetch the value from. If
+   * the underlying query result was joined 'as' a different Id, that should
+   * instead be used.
+   * @param joinedCellId The Id of the Cell to fetch the value for.
+   * @returns A Cell value or `undefined`.
+   * @category Callback
+   * @since v8.3.0
+   */
+  (asQuery: true, joinedQueryId: Id, joinedCellId: Id): CellOrUndefined;
 };
 
 /**
@@ -967,6 +981,21 @@ export type Select = {
    * @since v2.0.0
    */
   (joinedTableId: Id, joinedCellId: Id): SelectedAs;
+  /**
+   * Calling this function with three parameters (where the first is `true`)
+   * will indicate that the query should select the value of the specified Cell
+   * from a query result that has been joined in the query.
+   * @param asQuery A flag indicating that the next Id is a query Id.
+   * @param joinedQueryId The Id of the query result to fetch the value from. If
+   * the underlying query result was joined 'as' a different Id, that should
+   * instead be used.
+   * @param joinedCellId The Id of the Cell to fetch the value for.
+   * @returns A SelectedAs object so that the selected Cell Id can be optionally
+   * aliased.
+   * @category Definition
+   * @since v8.3.0
+   */
+  (asQuery: true, joinedQueryId: Id, joinedCellId: Id): SelectedAs;
   /**
    * Calling this function with one callback parameter will indicate that the
    * query should select a calculated value, based on one or more Cell values in
@@ -1228,6 +1257,20 @@ export type Join = {
    * @since v2.0.0
    */
   (joinedTableId: Id, on: Id): JoinedAs;
+  /**
+   * Calling this function with three parameters (where the first is `true`)
+   * will indicate that the join to a Row in an adjacent query result is made
+   * by finding its Id in a Cell of the query's root Table.
+   * @param asQuery A flag indicating that the next Id is a query Id.
+   * @param joinedQueryId The Id of the query result to join to.
+   * @param on The Id of the Cell in the root Table that contains the joined
+   * query result's Row Id.
+   * @returns A JoinedAs object so that the joined Table Id can be optionally
+   * aliased.
+   * @category Definition
+   * @since v8.3.0
+   */
+  (asQuery: true, joinedQueryId: Id, on: Id): JoinedAs;
   /**
    * Calling this function with two parameters (where the second is a function)
    * will indicate that the join to a Row in an adjacent Table is made by
@@ -1245,6 +1288,26 @@ export type Join = {
     joinedTableId: Id,
     on: (getCell: GetCell, rowId: Id) => Id | undefined,
   ): JoinedAs;
+  /**
+   * Calling this function with three parameters (where the first is `true` and
+   * the third is a function) will indicate that the join to a Row in an
+   * adjacent query result is made by calculating its Id from the Cells and the
+   * Row Id of the query's root Table.
+   * @param asQuery A flag indicating that the next Id is a query Id.
+   * @param joinedQueryId The Id of the query result 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 query
+   * result's Row Id.
+   * @returns A JoinedAs object so that the joined Table Id can be optionally
+   * aliased.
+   * @category Definition
+   * @since v8.3.0
+   */
+  (
+    asQuery: true,
+    joinedQueryId: Id,
+    on: (getCell: GetCell, rowId: Id) => Id | undefined,
+  ): JoinedAs;
   /**
    * Calling this function with three Id parameters will indicate that the join
    * to a Row in distant Table is made by finding its Id in a Cell of an
@@ -1261,6 +1324,28 @@ export type Join = {
    * @since v2.0.0
    */
   (joinedTableId: Id, fromIntermediateJoinedTableId: Id, on: Id): JoinedAs;
+  /**
+   * Calling this function with four parameters (where the first is `true`)
+   * will indicate that the join to a Row in a distant query result is made by
+   * finding its Id in a Cell of an intermediately joined Table.
+   * @param asQuery A flag indicating that the next Id is a query Id.
+   * @param joinedQueryId The Id of the distant query result 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
+   * clauses).
+   * @param on The Id of the Cell in the intermediate Table that contains the
+   * joined query result's Row Id.
+   * @returns A JoinedAs object so that the joined Table Id can be optionally
+   * aliased.
+   * @category Definition
+   * @since v8.3.0
+   */
+  (
+    asQuery: true,
+    joinedQueryId: Id,
+    fromIntermediateJoinedTableId: Id,
+    on: Id,
+  ): JoinedAs;
   /**
    * Calling this function with three parameters (where the third is a function)
    * will indicate that the join to a Row in distant Table is made by
@@ -1286,6 +1371,33 @@ export type Join = {
       intermediateJoinedRowId: Id,
     ) => Id | undefined,
   ): JoinedAs;
+  /**
+   * Calling this function with four parameters (where the first is `true` and
+   * the fourth is a function) will indicate that the join to a Row in a
+   * distant query result is made by calculating its Id from the Cells and the
+   * Row Id of an intermediately joined Table.
+   * @param asQuery A flag indicating that the next Id is a query Id.
+   * @param joinedQueryId The Id of the query result 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
+   * clauses).
+   * @param on A callback that takes a GetCell function and the intermediate
+   * Table's Row Id. These can be used to programmatically calculate the joined
+   * query result's Row Id.
+   * @returns A JoinedAs object so that the joined Table Id can be optionally
+   * aliased.
+   * @category Definition
+   * @since v8.3.0
+   */
+  (
+    asQuery: true,
+    joinedQueryId: Id,
+    fromIntermediateJoinedTableId: Id,
+    on: (
+      getIntermediateJoinedCell: GetCell,
+      intermediateJoinedRowId: Id,
+    ) => Id | undefined,
+  ): JoinedAs;
 };
 
 /**
@@ -1492,6 +1604,21 @@ export type Where = {
    * @since v2.0.0
    */
   (joinedTableId: Id, joinedCellId: Id, equals: Cell): void;
+  /**
+   * Calling this function with four parameters (where the first is `true`) is
+   * used to include only those Rows for which a specified Cell in a joined
+   * query result has a specified value.
+   * @param asQuery A flag indicating that the next Id is a query Id.
+   * @param joinedQueryId The Id of the joined query result to test a value in.
+   * If the underlying query result was joined 'as' a different Id, that should
+   * instead be used.
+   * @param joinedCellId The Id of the Cell in the joined query result to test.
+   * @param equals The value that the Cell has to have for the Row to be
+   * included in the result.
+   * @category Definition
+   * @since v8.3.0
+   */
+  (asQuery: true, joinedQueryId: Id, joinedCellId: Id, equals: Cell): void;
   /**
    * Calling this function with one callback parameter is used to include only
    * those Rows which meet a calculated boolean condition, based on values in
@@ -1985,6 +2112,20 @@ export interface Queries {
     }) => void,
     paramValues?: ParamValues,
   ): Queries;
+  setQueryDefinition(
+    queryId: Id,
+    asQuery: true,
+    rootQueryId: Id,
+    query: (keywords: {
+      select: Select;
+      join: Join;
+      where: Where;
+      group: Group;
+      having: Having;
+      param: Param;
+    }) => void,
+    paramValues?: ParamValues,
+  ): Queries;
 
   /**
    * The delQueryDefinition method removes an existing query definition.

package/@types/queries/with-schemas/index.d.ts

@@ -891,6 +891,24 @@ export type GetTableCell<
         ? Cell<Schema, JoinedTableId, JoinedCellId>
         : Cell<any, any, any>)
     | undefined;
+  /**
+   * Calling this function with three parameters (where the first is `true`)
+   * will return the value of the specified Cell from a query result that has
+   * been joined in the query, for the Row being selected or filtered.
+   * @param asQuery A flag indicating that the next Id is a query Id.
+   * @param joinedQueryId The Id of the query result to fetch the value from. If
+   * the underlying query result was joined 'as' a different Id, that should
+   * instead be used.
+   * @param joinedCellId The Id of the Cell to fetch the value for.
+   * @returns A Cell value or `undefined`.
+   * @category Callback
+   * @since v8.3.0
+   */
+  (
+    asQuery: true,
+    joinedQueryId: Id,
+    joinedCellId: Id,
+  ): Cell<any, any, any> | undefined;
 };
 
 /**
@@ -1107,6 +1125,21 @@ export type Select<
     joinedTableId: JoinedTableId,
     joinedCellId: JoinedCellIdOrId<Schema, JoinedTableId>,
   ): SelectedAs;
+  /**
+   * Calling this function with three parameters (where the first is `true`)
+   * will indicate that the query should select the value of the specified Cell
+   * from a query result that has been joined in the query.
+   * @param asQuery A flag indicating that the next Id is a query Id.
+   * @param joinedQueryId The Id of the query result to fetch the value from. If
+   * the underlying query result was joined 'as' a different Id, that should
+   * instead be used.
+   * @param joinedCellId The Id of the Cell to fetch the value for.
+   * @returns A SelectedAs object so that the selected Cell Id can be optionally
+   * aliased.
+   * @category Definition
+   * @since v8.3.0
+   */
+  (asQuery: true, joinedQueryId: Id, joinedCellId: Id): SelectedAs;
   /**
    * Calling this function with one callback parameter will indicate that the
    * query should select a calculated value, based on one or more Cell values in
@@ -1377,6 +1410,24 @@ export type Join<
     joinedTableId: TableIdFromSchema<Schema>,
     on: CellIdFromSchema<Schema, RootTableId>,
   ): JoinedAs;
+  /**
+   * Calling this function with three parameters (where the first is `true`)
+   * will indicate that the join to a Row in an adjacent query result is made
+   * by finding its Id in a Cell of the query's root Table.
+   * @param asQuery A flag indicating that the next Id is a query Id.
+   * @param joinedQueryId The Id of the query result to join to.
+   * @param on The Id of the Cell in the root Table that contains the joined
+   * query result's Row Id.
+   * @returns A JoinedAs object so that the joined Table Id can be optionally
+   * aliased.
+   * @category Definition
+   * @since v8.3.0
+   */
+  (
+    asQuery: true,
+    joinedQueryId: Id,
+    on: CellIdFromSchema<Schema, RootTableId>,
+  ): JoinedAs;
   /**
    * Calling this function with two parameters (where the second is a function)
    * will indicate that the join to a Row in an adjacent Table is made by
@@ -1394,6 +1445,26 @@ export type Join<
     joinedTableId: TableIdFromSchema<Schema>,
     on: (getCell: GetCell<Schema, RootTableId>, rowId: Id) => Id | undefined,
   ): JoinedAs;
+  /**
+   * Calling this function with three parameters (where the first is `true` and
+   * the third is a function) will indicate that the join to a Row in an
+   * adjacent query result is made by calculating its Id from the Cells and the
+   * Row Id of the query's root Table.
+   * @param asQuery A flag indicating that the next Id is a query Id.
+   * @param joinedQueryId The Id of the query result 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 query
+   * result's Row Id.
+   * @returns A JoinedAs object so that the joined Table Id can be optionally
+   * aliased.
+   * @category Definition
+   * @since v8.3.0
+   */
+  (
+    asQuery: true,
+    joinedQueryId: Id,
+    on: (getCell: GetCell<Schema, RootTableId>, rowId: Id) => Id | undefined,
+  ): JoinedAs;
   /**
    * Calling this function with three Id parameters will indicate that the join
    * to a Row in distant Table is made by finding its Id in a Cell of an
@@ -1422,6 +1493,36 @@ export type Join<
     fromIntermediateJoinedTableId: IntermediateJoinedTableId,
     on: IntermediateJoinedCellId,
   ): JoinedAs;
+  /**
+   * Calling this function with four parameters (where the first is `true`)
+   * will indicate that the join to a Row in a distant query result is made by
+   * finding its Id in a Cell of an intermediately joined Table.
+   * @param asQuery A flag indicating that the next Id is a query Id.
+   * @param joinedQueryId The Id of the distant query result 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
+   * clauses).
+   * @param on The Id of the Cell in the intermediate Table that contains the
+   * joined query result's Row Id.
+   * @returns A JoinedAs object so that the joined Table Id can be optionally
+   * aliased.
+   * @category Definition
+   * @since v8.3.0
+   */
+  <
+    IntermediateJoinedTableId extends TableIdFromSchema<Schema> | Id =
+      | TableIdFromSchema<Schema>
+      | Id,
+    IntermediateJoinedCellId extends JoinedCellIdOrId<
+      Schema,
+      IntermediateJoinedTableId
+    > = JoinedCellIdOrId<Schema, IntermediateJoinedTableId>,
+  >(
+    asQuery: true,
+    joinedQueryId: Id,
+    fromIntermediateJoinedTableId: IntermediateJoinedTableId,
+    on: IntermediateJoinedCellId,
+  ): JoinedAs;
   /**
    * Calling this function with three parameters (where the third is a function)
    * will indicate that the join to a Row in distant Table is made by
@@ -1455,6 +1556,41 @@ export type Join<
       intermediateJoinedRowId: Id,
     ) => Id | undefined,
   ): JoinedAs;
+  /**
+   * Calling this function with four parameters (where the first is `true` and
+   * the fourth is a function) will indicate that the join to a Row in a
+   * distant query result is made by calculating its Id from the Cells and the
+   * Row Id of an intermediately joined Table.
+   * @param asQuery A flag indicating that the next Id is a query Id.
+   * @param joinedQueryId The Id of the query result 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
+   * clauses).
+   * @param on A callback that takes a GetCell function and the intermediate
+   * Table's Row Id. These can be used to programmatically calculate the joined
+   * query result's Row Id.
+   * @returns A JoinedAs object so that the joined Table Id can be optionally
+   * aliased.
+   * @category Definition
+   * @since v8.3.0
+   */
+  <
+    IntermediateJoinedTableId extends TableIdFromSchema<Schema> | Id =
+      | TableIdFromSchema<Schema>
+      | Id,
+  >(
+    asQuery: true,
+    joinedQueryId: Id,
+    fromIntermediateJoinedTableId: IntermediateJoinedTableId,
+    on: (
+      // prettier-ignore
+      getIntermediateJoinedCell:
+        IntermediateJoinedTableId extends TableIdFromSchema<Schema>
+          ? GetCell<Schema, IntermediateJoinedTableId>
+          : GetCell<NoTablesSchema, Id>,
+      intermediateJoinedRowId: Id,
+    ) => Id | undefined,
+  ): JoinedAs;
 };
 
 /**
@@ -1680,6 +1816,26 @@ export type Where<
     joinedCellId: JoinedCellId,
     equals: JoinedCell,
   ): void;
+  /**
+   * Calling this function with four parameters (where the first is `true`) is
+   * used to include only those Rows for which a specified Cell in a joined
+   * query result has a specified value.
+   * @param asQuery A flag indicating that the next Id is a query Id.
+   * @param joinedQueryId The Id of the joined query result to test a value in.
+   * If the underlying query result was joined 'as' a different Id, that should
+   * instead be used.
+   * @param joinedCellId The Id of the Cell in the joined query result to test.
+   * @param equals The value that the Cell has to have for the Row to be
+   * included in the result.
+   * @category Definition
+   * @since v8.3.0
+   */
+  (
+    asQuery: true,
+    joinedQueryId: Id,
+    joinedCellId: Id,
+    equals: Cell<any, any, any>,
+  ): void;
   /**
    * Calling this function with one callback parameter is used to include only
    * those Rows which meet a calculated boolean condition, based on values in
@@ -2114,6 +2270,20 @@ export interface Queries<in out Schemas extends OptionalSchemas> {
    *   }) => void,
    *   paramValues?: ParamValues,
    * ): Queries;
+   * setQueryDefinition(
+   *   queryId: Id,
+   *   asQuery: true,
+   *   rootQueryId: Id,
+   *   query: (keywords: {
+   *     select: Select;
+   *     join: Join;
+   *     where: Where;
+   *     group: Group;
+   *     having: Having;
+   *     param: Param;
+   *   }) => void,
+   *   paramValues?: ParamValues,
+   * ): Queries;
    * ```
    *
    * Every query definition is identified by a unique Id, and if you re-use an
@@ -2192,6 +2362,20 @@ export interface Queries<in out Schemas extends OptionalSchemas> {
     }) => void,
     paramValues?: ParamValues,
   ): Queries<Schemas>;
+  setQueryDefinition(
+    queryId: Id,
+    asQuery: true,
+    rootQueryId: Id,
+    query: (keywords: {
+      select: Select<any, any>;
+      join: Join<any, any>;
+      where: Where<any, any>;
+      group: Group;
+      having: Having;
+      param: Param;
+    }) => void,
+    paramValues?: ParamValues,
+  ): Queries<Schemas>;
 
   /**
    * The delQueryDefinition method removes an existing query definition.