tinybase 9.4.0-beta.0 → 9.4.0-beta.1

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

@@ -1011,6 +1011,138 @@ export type Select = {
   ): SelectedAs;
 };
 
+/**
+ * The CellIdMapper type describes a function used by a SelectAll clause to map
+ * a source Cell Id to a Cell Id in the query result.
+ * @param cellId The Id of a Cell in the source Row.
+ * @returns The Id to use for that Cell in the result Row.
+ * @category Callback
+ * @since v9.4.0
+ */
+export type CellIdMapper = (cellId: Id) => Id;
+
+/**
+ * The SelectAll type describes a function that lets you select every Cell
+ * present in a source Row.
+ *
+ * The SelectAll function is provided to the third `query` parameter of the
+ * setQueryDefinition method. Different source Rows can contain different Cell
+ * Ids, and each result Row will contain only the Cells present in its
+ * corresponding source Row. The result Table's Cell Ids are therefore the union
+ * of the Cells in its result Rows.
+ *
+ * Source Cell Ids are processed in lexical order, and selection clauses are
+ * processed in the order they are declared. If multiple selected Cells map to
+ * the same result Cell Id, the later one wins.
+ *
+ * When used in a grouped query, the current table-wide union of source Cell Ids
+ * is expanded into individual selections. The query is rebuilt if this union
+ * changes, and any selected Cell that is not grouped becomes a grouping
+ * dimension as usual.
+ * @category Definition
+ * @since v9.4.0
+ */
+export type SelectAll = {
+  /**
+   * Calling this function with no parameters will select every Cell present in
+   * each Row of the query's root Table, retaining the source Cell Ids.
+   * @example
+   * This example selects all the Cells from heterogeneous root Rows:
+   *
+   * ```js
+   * import {createQueries, createStore} from 'tinybase';
+   *
+   * const store = createStore().setTable('pets', {
+   *   fido: {species: 'dog', color: 'brown'},
+   *   felix: {species: 'cat', indoor: true},
+   * });
+   * const queries = createQueries(store);
+   *
+   * queries.setQueryDefinition('query', 'pets', ({selectAll}) => selectAll());
+   *
+   * console.log(queries.getResultRow('query', 'fido'));
+   * // -> {color: 'brown', species: 'dog'}
+   * console.log(queries.getResultRow('query', 'felix'));
+   * // -> {indoor: true, species: 'cat'}
+   * ```
+   * @category Definition
+   * @since v9.4.0
+   */
+  (): void;
+  /**
+   * Calling this function with a joined Table Id will select every Cell present
+   * in the joined Row.
+   *
+   * An optional second parameter can map each Cell Id with a prefix or
+   * callback.
+   * @param joinedTableId The Id of the joined Table. If the Table was joined
+   * 'as' a different Id, that should instead be used.
+   * @param cellIdPrefixOrMapper An optional prefix to prepend to every Cell Id,
+   * or a CellIdMapper callback that returns each result Cell Id.
+   * @example
+   * This example selects all the Cells from a joined Table, retaining their
+   * Cell Ids:
+   *
+   * ```js
+   * import {createQueries, createStore} from 'tinybase';
+   *
+   * const store = createStore()
+   *   .setTable('pets', {fido: {ownerId: '1'}})
+   *   .setTable('owners', {'1': {name: 'Alice', city: 'London'}});
+   * const queries = createQueries(store);
+   *
+   * queries.setQueryDefinition('query', 'pets', ({selectAll, join}) => {
+   *   selectAll('owners');
+   *   join('owners', 'ownerId');
+   * });
+   *
+   * console.log(queries.getResultRow('query', 'fido'));
+   * // -> {city: 'London', name: 'Alice'}
+   * ```
+   * @category Definition
+   * @since v9.4.0
+   */
+  (joinedTableId: Id, cellIdPrefixOrMapper?: Id | CellIdMapper): void;
+  /**
+   * Calling this function with `true` and a joined query Id will select every
+   * Cell present in the joined result Row.
+   *
+   * An optional third parameter can map each Cell Id with a prefix or callback.
+   * @param asQuery A flag indicating that the next Id is a query Id.
+   * @param joinedQueryId The Id of the joined query result. If the query result
+   * was joined 'as' a different Id, that should instead be used.
+   * @param cellIdPrefixOrMapper An optional prefix to prepend to every Cell Id,
+   * or a CellIdMapper callback that returns each result Cell Id.
+   * @example
+   * This example selects all the Cells from a joined query result, prefixing
+   * each Cell Id:
+   *
+   * ```js
+   * import {createQueries, createStore} from 'tinybase';
+   *
+   * const store = createStore()
+   *   .setTable('pets', {fido: {ownerId: '1'}})
+   *   .setTable('owners', {'1': {name: 'Alice', city: 'London'}});
+   * const queries = createQueries(store)
+   *   .setQueryDefinition('owners', 'owners', ({selectAll}) => selectAll())
+   *   .setQueryDefinition('query', 'pets', ({selectAll, join}) => {
+   *     selectAll(true, 'owners', 'owner.');
+   *     join(true, 'owners', 'ownerId');
+   *   });
+   *
+   * console.log(queries.getResultRow('query', 'fido'));
+   * // -> {'owner.city': 'London', 'owner.name': 'Alice'}
+   * ```
+   * @category Definition
+   * @since v9.4.0
+   */
+  (
+    asQuery: true,
+    joinedQueryId: Id,
+    cellIdPrefixOrMapper?: Id | CellIdMapper,
+  ): void;
+};
+
 /**
  * The SelectedAs type describes an object returned from calling a Select
  * function so that the selected Cell Id can be optionally aliased.
@@ -1257,8 +1389,8 @@ export type Join = {
   (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.
+   * 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
@@ -1323,8 +1455,8 @@ export type Join = {
    */
   (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
+   * 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.
@@ -1371,9 +1503,9 @@ export type Join = {
   ): 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.
+   * 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
@@ -2102,6 +2234,7 @@ export interface Queries {
     tableId: Id,
     query: (keywords: {
       select: Select;
+      selectAll: SelectAll;
       join: Join;
       where: Where;
       group: Group;
@@ -2116,6 +2249,7 @@ export interface Queries {
     rootQueryId: Id,
     query: (keywords: {
       select: Select;
+      selectAll: SelectAll;
       join: Join;
       where: Where;
       group: Group;

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

@@ -1158,6 +1158,148 @@ export type Select<
   ): SelectedAs;
 };
 
+/**
+ * The CellIdMapper type describes a function used by a SelectAll clause to map
+ * a source Cell Id to a Cell Id in the query result.
+ * @param cellId The Id of a Cell in the source Row.
+ * @returns The Id to use for that Cell in the result Row.
+ * @category Callback
+ * @since v9.4.0
+ */
+export type CellIdMapper<CellId extends Id = Id> = (cellId: CellId) => Id;
+
+/**
+ * The SelectAll type describes a function that lets you select every Cell
+ * present in a source Row.
+ *
+ * The SelectAll function is provided to the third `query` parameter of the
+ * setQueryDefinition method. Different source Rows can contain different Cell
+ * Ids, and each result Row will contain only the Cells present in its
+ * corresponding source Row. The result Table's Cell Ids are therefore the union
+ * of the Cells in its result Rows.
+ *
+ * Source Cell Ids are processed in lexical order, and selection clauses are
+ * processed in the order they are declared. If multiple selected Cells map to
+ * the same result Cell Id, the later one wins.
+ *
+ * When used in a grouped query, the current table-wide union of source Cell Ids
+ * is expanded into individual selections. The query is rebuilt if this union
+ * changes, and any selected Cell that is not grouped becomes a grouping
+ * dimension as usual.
+ * @category Definition
+ * @since v9.4.0
+ */
+export type SelectAll<Schema extends OptionalTablesSchema> = {
+  /**
+   * Calling this function with no parameters will select every Cell present in
+   * each Row of the query's root Table, retaining the source Cell Ids.
+   * @example
+   * This example selects all the Cells from heterogeneous root Rows:
+   *
+   * ```js
+   * import {createQueries, createStore} from 'tinybase';
+   *
+   * const store = createStore().setTable('pets', {
+   *   fido: {species: 'dog', color: 'brown'},
+   *   felix: {species: 'cat', indoor: true},
+   * });
+   * const queries = createQueries(store);
+   *
+   * queries.setQueryDefinition('query', 'pets', ({selectAll}) => selectAll());
+   *
+   * console.log(queries.getResultRow('query', 'fido'));
+   * // -> {color: 'brown', species: 'dog'}
+   * console.log(queries.getResultRow('query', 'felix'));
+   * // -> {indoor: true, species: 'cat'}
+   * ```
+   * @category Definition
+   * @since v9.4.0
+   */
+  (): void;
+  /**
+   * Calling this function with a joined Table Id will select every Cell present
+   * in the joined Row.
+   *
+   * This has schema-based typing. The following is a simplified representation:
+   *
+   * ```ts override
+   * (joinedTableId: Id, cellIdPrefixOrMapper?: Id | CellIdMapper): void;
+   * ```
+   *
+   * An optional second parameter can map each Cell Id with a prefix or
+   * callback.
+   * @param joinedTableId The Id of the joined Table. If the Table was joined
+   * 'as' a different Id, that should instead be used.
+   * @param cellIdPrefixOrMapper An optional prefix to prepend to every Cell Id,
+   * or a CellIdMapper callback that returns each result Cell Id.
+   * @example
+   * This example selects all the Cells from a joined Table, retaining their
+   * Cell Ids:
+   *
+   * ```js
+   * import {createQueries, createStore} from 'tinybase';
+   *
+   * const store = createStore()
+   *   .setTable('pets', {fido: {ownerId: '1'}})
+   *   .setTable('owners', {'1': {name: 'Alice', city: 'London'}});
+   * const queries = createQueries(store);
+   *
+   * queries.setQueryDefinition('query', 'pets', ({selectAll, join}) => {
+   *   selectAll('owners');
+   *   join('owners', 'ownerId');
+   * });
+   *
+   * console.log(queries.getResultRow('query', 'fido'));
+   * // -> {city: 'London', name: 'Alice'}
+   * ```
+   * @category Definition
+   * @since v9.4.0
+   */
+  <JoinedTableId extends TableIdFromSchema<Schema> | Id>(
+    joinedTableId: JoinedTableId,
+    cellIdPrefixOrMapper?:
+      Id | CellIdMapper<JoinedCellIdOrId<Schema, JoinedTableId>>,
+  ): void;
+  /**
+   * Calling this function with `true` and a joined query Id will select every
+   * Cell present in the joined result Row.
+   *
+   * An optional third parameter can map each Cell Id with a prefix or callback.
+   * @param asQuery A flag indicating that the next Id is a query Id.
+   * @param joinedQueryId The Id of the joined query result. If the query result
+   * was joined 'as' a different Id, that should instead be used.
+   * @param cellIdPrefixOrMapper An optional prefix to prepend to every Cell Id,
+   * or a CellIdMapper callback that returns each result Cell Id.
+   * @example
+   * This example selects all the Cells from a joined query result, prefixing
+   * each Cell Id:
+   *
+   * ```js
+   * import {createQueries, createStore} from 'tinybase';
+   *
+   * const store = createStore()
+   *   .setTable('pets', {fido: {ownerId: '1'}})
+   *   .setTable('owners', {'1': {name: 'Alice', city: 'London'}});
+   * const queries = createQueries(store)
+   *   .setQueryDefinition('owners', 'owners', ({selectAll}) => selectAll())
+   *   .setQueryDefinition('query', 'pets', ({selectAll, join}) => {
+   *     selectAll(true, 'owners', 'owner.');
+   *     join(true, 'owners', 'ownerId');
+   *   });
+   *
+   * console.log(queries.getResultRow('query', 'fido'));
+   * // -> {'owner.city': 'London', 'owner.name': 'Alice'}
+   * ```
+   * @category Definition
+   * @since v9.4.0
+   */
+  (
+    asQuery: true,
+    joinedQueryId: Id,
+    cellIdPrefixOrMapper?: Id | CellIdMapper,
+  ): void;
+};
+
 /**
  * The SelectedAs type describes an object returned from calling a Select
  * function so that the selected Cell Id can be optionally aliased.
@@ -1410,8 +1552,8 @@ export type Join<
   ): 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.
+   * 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
@@ -1491,8 +1633,8 @@ export type Join<
     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
+   * 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.
@@ -1553,9 +1695,9 @@ export type Join<
   ): 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.
+   * 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
@@ -2256,6 +2398,7 @@ export interface Queries<in out Schemas extends OptionalSchemas> {
    *   tableId: Id,
    *   query: (keywords: {
    *     select: Select;
+   *     selectAll: SelectAll;
    *     join: Join;
    *     where: Where;
    *     group: Group;
@@ -2270,6 +2413,7 @@ export interface Queries<in out Schemas extends OptionalSchemas> {
    *   rootQueryId: Id,
    *   query: (keywords: {
    *     select: Select;
+   *     selectAll: SelectAll;
    *     join: Join;
    *     where: Where;
    *     group: Group;
@@ -2348,6 +2492,7 @@ export interface Queries<in out Schemas extends OptionalSchemas> {
     tableId: RootTableId,
     query: (keywords: {
       select: Select<Schemas[0], RootTableId>;
+      selectAll: SelectAll<Schemas[0]>;
       join: Join<Schemas[0], RootTableId>;
       where: Where<Schemas[0], RootTableId>;
       group: Group;
@@ -2362,6 +2507,7 @@ export interface Queries<in out Schemas extends OptionalSchemas> {
     rootQueryId: Id,
     query: (keywords: {
       select: Select<any, any>;
+      selectAll: SelectAll<any>;
       join: Join<any, any>;
       where: Where<any, any>;
       group: Group;