flowerbi 3.8.2 → 3.9.0

package/src/executeQuery.ts

@@ -1,11 +1,24 @@
-import { Query, QuerySelect, ExpandedQueryRecord, AggregateValuesOnly, getAggregatePropsOnly, getColumnPropsOnly } from "./queryModel";
-import { QueryJson, AggregationJson } from "./QueryJson";
+import {
+    Query,
+    QuerySelect,
+    ExpandedQueryRecord,
+    AggregateValuesOnly,
+    getAggregatePropsOnly,
+    getColumnPropsOnly,
+    Calculation,
+    AggregatePropsOnly,
+    QueryCalculations,
+    Ordering,
+    CalculationValues,
+} from "./queryModel";
+import { QueryJson, AggregationJson, CalculationJson, OrderingJson } from "./QueryJson";
 import { QueryColumn } from "./QueryColumn";
+import { keysOf } from "./arrayHelpers";
 
 /**
  * The allowed data types for plain columns.
  */
-export type QuerySelectValue = number|string|Date|boolean;
+export type QuerySelectValue = number | string | Date | boolean;
 
 /**
  * The JSON format of a record returned from the API when executing a query.
@@ -22,7 +35,7 @@ export interface QueryRecordJson {
 }
 
 /**
- * The JSON format of the whole payload returned from the API when 
+ * The JSON format of the whole payload returned from the API when
  * executing a query.
  */
 export interface QueryResultJson {
@@ -47,24 +60,91 @@ export interface QueryResultJson {
  */
 export type QueryFetch = (queryJson: QueryJson) => Promise<QueryResultJson>;
 
+function jsonifyCalculation<S extends QuerySelect>(calculation: Calculation<S>, props: AggregatePropsOnly<S>[]): CalculationJson {
+    if (typeof calculation === "string") {
+        const aggregation = props.indexOf(calculation);
+        if (aggregation === -1) {
+            throw new Error(`Not a valid aggregation name: ${calculation}`);
+        }
+        return { aggregation };
+    }
+    if (typeof calculation === "number") {
+        return {
+            value: calculation,
+        };
+    }
+    if (calculation instanceof Array) {
+        return {
+            first: jsonifyCalculation(calculation[0], props),
+            operator: calculation[1],
+            second: jsonifyCalculation(calculation[2], props),
+        };
+    }
+    throw new Error("Invalid calculation");
+}
+
+function jsonifyOrdering<S extends QuerySelect, C extends QueryCalculations<S>>(
+    ordering: OrderingJson | Ordering<S, C>,
+    selects: string[],
+    values: string[],
+    calculations: string[]
+): OrderingJson {
+    if ("select" in ordering) {
+        let index = selects.indexOf(ordering.select as string);
+        if (index !== -1) {
+            return {
+                type: "Select",
+                index,
+                descending: ordering.descending,
+            };
+        }
+        index = values.indexOf(ordering.select as string);
+        if (index !== -1) {
+            return {
+                type: "Value",
+                index,
+                descending: ordering.descending,
+            };
+        }
+        throw new Error(`Invalid ordering select key: ${String(ordering.select)}`);
+    }
+    if ("calculation" in ordering) {
+        let index = calculations.indexOf(ordering.calculation as string);
+        if (index !== -1) {
+            return {
+                type: "Calculation",
+                index,
+                descending: ordering.descending,
+            };
+        }
+        throw new Error(`Invalid ordering calculation key: ${String(ordering.calculation)}`);
+    }
+    return ordering;
+}
+
 /**
  * Converts a statically-typed {@link Query} into the {@link QueryJson}
  * format, ready to be sent to your API.
- * @param query 
+ * @param query
  */
-export function jsonifyQuery<S extends QuerySelect>(query: Query<S>): QueryJson {
-    const { select, filters, orderBy, totals, take, skip, comment, allowDuplicates } = query;
+export function jsonifyQuery<S extends QuerySelect, C extends QueryCalculations<S>>(query: Query<S, C>): QueryJson {
+    const { select, filters, calculations, orderBy, totals, take, skip, comment, allowDuplicates } = query;
+
+    const columnProps = getColumnPropsOnly(select);
+    const aggregationProps = getAggregatePropsOnly(select);
+    const calculationProps = calculations ? keysOf(calculations) : [];
 
-    return {        
-        select: getColumnPropsOnly(select).map(key => (select[key] as QueryColumn<never>).name),
-        aggregations: getAggregatePropsOnly(select).map(key => select[key] as AggregationJson),
+    return {
+        select: columnProps.map((key) => (select[key] as QueryColumn<never>).name),
+        aggregations: aggregationProps.map((key) => select[key] as AggregationJson),
+        calculations: calculations ? calculationProps.map((key) => jsonifyCalculation(calculations[key] as Calculation<S>, aggregationProps)) : undefined,
         filters: filters ?? [],
-        orderBy: orderBy ?? [],
+        orderBy: orderBy?.map((o) => jsonifyOrdering(o, columnProps as string[], aggregationProps as string[], calculationProps as string[])) ?? [],
         totals: totals ?? false,
         skip: skip ?? 0,
         take: take ?? 100,
         comment,
-        allowDuplicates
+        allowDuplicates,
     };
 }
 
@@ -75,11 +155,11 @@ export function jsonifyQuery<S extends QuerySelect>(query: Query<S>): QueryJson
  * @param select The {@link Query.select} property from the query.
  * @param record The record returned from your API.
  */
-export function expandQueryRecord<S extends QuerySelect>(
+export function expandQueryRecord<S extends QuerySelect, C extends QueryCalculations<S>>(
     select: S,
-    record: QueryRecordJson
-): ExpandedQueryRecord<S> {
-    
+    record: QueryRecordJson,
+    calcs?: C
+): ExpandedQueryRecord<S, C> {
     const result: any = {};
 
     let n = 0;
@@ -87,6 +167,11 @@ export function expandQueryRecord<S extends QuerySelect>(
         result[key] = record.aggregated[n++];
     }
 
+    const calculationProps = calcs ? keysOf(calcs) : [];
+    for (const key of calculationProps) {
+        result[key] = record.aggregated[n++];
+    }
+
     n = 0;
     for (const key of getColumnPropsOnly(select)) {
         result[key] = record.selected[n++];
@@ -96,18 +181,18 @@ export function expandQueryRecord<S extends QuerySelect>(
 }
 
 /**
- * Converts the `QueryRecordJson` from the `totals` record into a strongly-typed 
+ * Converts the `QueryRecordJson` from the `totals` record into a strongly-typed
  * record named properties for the aggregated values only, using the
  * {@link Query.select} from the query to perform the necessary mapping.
- * 
+ *
  * @param select The {@link Query.select} property from the query.
  * @param record The {@link QueryResultJson.totals} record returned from your API.
  */
-export function getAggregateValuesOnly<S extends QuerySelect>(
+export function getAggregateValuesOnly<S extends QuerySelect, C extends QueryCalculations<S>>(
     select: S,
-    record: QueryRecordJson
-): AggregateValuesOnly<S> {
-
+    record: QueryRecordJson,
+    calcs?: C
+): AggregateValuesOnly<S> & CalculationValues<C> {
     const result: any = {};
 
     let n = 0;
@@ -115,25 +200,30 @@ export function getAggregateValuesOnly<S extends QuerySelect>(
         result[key] = record.aggregated[n++];
     }
 
+    const calculationProps = calcs ? keysOf(calcs) : [];
+    for (const key of calculationProps) {
+        result[key] = record.aggregated[n++];
+    }
+
     return result;
 }
 
 /**
  * The statically-typed result of a {@link Query}.
  */
-export interface ExpandedQueryResult<S extends QuerySelect> {
+export interface ExpandedQueryResult<S extends QuerySelect, C extends QueryCalculations<S>> {
     /**
      * The set of records returned, each having named properties
      * corresponding to the plain and aggregated columns selected
      * in the query.
      */
-    records: ExpandedQueryRecord<S>[];
+    records: ExpandedQueryRecord<S, C>[];
     /**
      * Optional extra record, only available if {@link QueryJson.totals}
      * was specified as `true` in the query, containing the aggregation
      * totals.
      */
-    totals?: AggregateValuesOnly<S>;
+    totals?: AggregateValuesOnly<S> & CalculationValues<C>;
 }
 
 /**
@@ -142,13 +232,13 @@ export interface ExpandedQueryResult<S extends QuerySelect> {
  * @param select The {@link Query.select} property from the query.
  * @param result The response payload from the API call.
  */
-export function expandQueryResult<S extends QuerySelect>(
+export function expandQueryResult<S extends QuerySelect, C extends QueryCalculations<S>>(
     select: S,
-    result: QueryResultJson
-): ExpandedQueryResult<S> {
-
+    result: QueryResultJson,
+    calcs?: C
+): ExpandedQueryResult<S, C> {
     return {
-        records: result.records.map(r => expandQueryRecord(select, r)),
-        totals: result.totals && getAggregateValuesOnly(select, result.totals)
+        records: result.records.map((r) => expandQueryRecord(select, r, calcs)),
+        totals: result.totals && getAggregateValuesOnly(select, result.totals, calcs),
     };
 }

package/src/queryModel.ts

@@ -3,7 +3,7 @@ import { QueryColumn } from "./QueryColumn";
 import { AggregationJson, FilterJson, OrderingJson } from "./QueryJson";
 
 /**
- * Defines the kinds of member that can appear in the `select` object of a query. 
+ * Defines the kinds of member that can appear in the `select` object of a query.
  * Queries can select plain columns, or aggregation functions on columns.
  */
 export type SelectMember = QueryColumn<any> | AggregationJson;
@@ -21,19 +21,23 @@ export type QueryColumnType<T> = T extends QueryColumn<infer C> ? C : never;
 /**
  * Defines the shape of a record returned from a query, based on its `select` object.
  * Each selected property appears as a property in the record with the same name. For
- * plain columns the data type depends on the column definition, but for aggregates
- * the data type is always `number`.
+ * plain columns the data type depends on the column definition, but for aggregations
+ * and calculations the data type is always `number`.
  */
-export type ExpandedQueryRecord<S extends QuerySelect> = { 
+export type ExpandedQueryRecord<S extends QuerySelect, C extends QueryCalculations<S>> = {
     [P in keyof S]: S[P] extends QueryColumn<any> ? QueryColumnType<S[P]> : number;
+} & {
+    [P in keyof C]: number;
 };
 
 /**
  * Similar to {@link ExpandedQueryRecord} but the plain columns are optional, so they
- * may be `undefined`. Aggregations are not optional.
+ * may be `undefined`. Aggregations/calculations are not optional.
  */
-export type ExpandedQueryRecordWithOptionalColumns<S extends QuerySelect> = { 
-    [P in keyof S]: S[P] extends QueryColumn<any> ? (QueryColumnType<S[P]> | undefined) : number;
+export type ExpandedQueryRecordWithOptionalColumns<S extends QuerySelect, C extends QueryCalculations<S>> = {
+    [P in keyof S]: S[P] extends QueryColumn<any> ? QueryColumnType<S[P]> | undefined : number;
+} & {
+    [P in keyof C]: number;
 };
 
 /**
@@ -50,25 +54,25 @@ export type AggregatePropsOnlyHelper<T extends QuerySelect> = {
 export type AggregatePropsOnly<T extends QuerySelect> = AggregatePropsOnlyHelper<T>[keyof AggregatePropsOnlyHelper<T>];
 
 /**
- * Returns the names of properties in a query that refer to aggregated columns. 
+ * Returns the names of properties in a query that refer to aggregated columns.
  * The result is an array of strings, but type-constrained to string literal types:
- * 
+ *
  * ```ts
- * getAggregatePropsOnly({ 
+ * getAggregatePropsOnly({
  *    customer: Customer.Name,
  *    spend: Invoice.Amount.sum()
  * }) // ["spend"]
  * ```
- * 
+ *
  * @param select the `select` object from a query
  */
 export function getAggregatePropsOnly<T extends QuerySelect>(select: T) {
-    const keys = keysOf(select).filter(x => !(select[x] instanceof QueryColumn))
+    const keys = keysOf(select).filter((x) => !(select[x] instanceof QueryColumn));
     return keys as AggregatePropsOnly<T>[];
 }
 
 /**
- * An object that contains a subset of the the named properties from a query's 
+ * An object that contains a subset of the the named properties from a query's
  * `select` object, those that refer to aggregated values (hence all are of
  * type `number`.)
  */
@@ -76,6 +80,10 @@ export type AggregateValuesOnly<T extends QuerySelect> = {
     [K in AggregatePropsOnly<T>]: number;
 };
 
+export type CalculationValues<C extends QueryCalculations<any>> = {
+    [K in keyof C]: number;
+};
+
 /**
  * A helper type used in the definition of {@link ColumnPropsOnly}.
  */
@@ -92,18 +100,18 @@ export type ColumnPropsOnly<T extends QuerySelect> = ColumnPropsOnlyHelper<T>[ke
 /**
  * Returns the names of properties in a query that refer to plain columns. The
  * result is an array of strings, but type-constrained to string literal types:
- * 
+ *
  * ```ts
- * getColumnPropsOnly({ 
+ * getColumnPropsOnly({
  *    customer: Customer.Name,
- *    spend: Invoice.Amount.sum() 
+ *    spend: Invoice.Amount.sum()
  * }) // ["customer"]
  * ```
- * 
+ *
  * @param select the `select` object from a query
  */
 export function getColumnPropsOnly<T extends QuerySelect>(select: T) {
-    const keys = keysOf(select).filter(x => select[x] instanceof QueryColumn)
+    const keys = keysOf(select).filter((x) => select[x] instanceof QueryColumn);
     return keys as ColumnPropsOnly<T>[];
 }
 
@@ -114,37 +122,54 @@ export function getColumnPropsOnly<T extends QuerySelect>(select: T) {
  */
 export function getColumnsOnly(select: QuerySelect) {
     return keysOf(select)
-        .map(k => select[k])
-        .filter(x => x instanceof QueryColumn)
-        .map(x => (x as QueryColumn<any>));
+        .map((k) => select[k])
+        .filter((x) => x instanceof QueryColumn)
+        .map((x) => x as QueryColumn<any>);
 }
 
+export type Calculation<S extends QuerySelect> = number | AggregatePropsOnly<S> | [Calculation<S>, "+" | "-" | "*" | "/", Calculation<S>];
+
+/**
+ * The `select` object of a query has named properties of type {@link SelectMember}.
+ */
+export type QueryCalculations<S extends QuerySelect> = Record<string, Calculation<S>>;
+
+export type Ordering<S extends QuerySelect, C extends QueryCalculations<S>> = { descending?: boolean } & (
+    | {
+          select: keyof S;
+      }
+    | {
+          calculation: keyof C;
+      }
+);
+
 /**
- * Strongly-typed query definition: use {@link jsonifyQuery} to convert to the JSON format 
+ * Strongly-typed query definition: use {@link jsonifyQuery} to convert to the JSON format
  * and {@link expandQueryResult} to generate corresponding output records.
  */
-export interface Query<S extends QuerySelect> {
+export interface Query<S extends QuerySelect, C extends QueryCalculations<S>> {
     select: S;
     filters?: FilterJson[];
+    calculations?: C;
     /**
      * Ordering criteria to apply.
      */
-    orderBy?: OrderingJson[];
+    orderBy?: (OrderingJson | Ordering<S, C>)[];
     /**
-     * Specifies whether to return a `totals` property containing the 
+     * Specifies whether to return a `totals` property containing the
      * aggregation values across the whole dataset, e.g. if the `select`
      * object is:
-     * 
+     *
      * ```ts
-     * { 
+     * {
      *    customer: Customer.Name,
      *    spend: Invoice.Amount.sum()
      * }
      * ```
-     * 
+     *
      * the returned `records` will have properties `customer` and `spend`,
-     * one per customer. Specify `totals: true` to also get a `totals` object 
-     * with only a `spend` property, containing the total spend across all 
+     * one per customer. Specify `totals: true` to also get a `totals` object
+     * with only a `spend` property, containing the total spend across all
      * customers.
      */
     totals?: boolean;
@@ -157,10 +182,10 @@ export interface Query<S extends QuerySelect> {
      */
     take?: number;
     /**
-     * A string to insert in a comment at the start of the generated SQL. 
-     * 
-     * This will be aggressively processed to remove the danger of injection 
-     * attacks, so anything other than alpha, numeric, new line or CR 
+     * A string to insert in a comment at the start of the generated SQL.
+     *
+     * This will be aggressively processed to remove the danger of injection
+     * attacks, so anything other than alpha, numeric, new line or CR
      * characters will be replaced with space.
      */
     comment?: string;