flowerbi 3.8.3 → 3.9.0

package/dist/queryModel.d.ts

@@ -16,18 +16,22 @@ export declare type QueryColumnType<T> = T extends QueryColumn<infer C> ? C : ne
 /**
  * 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 declare type ExpandedQueryRecord<S extends QuerySelect> = {
+export declare 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 declare type ExpandedQueryRecordWithOptionalColumns<S extends QuerySelect> = {
-    [P in keyof S]: S[P] extends QueryColumn<any> ? (QueryColumnType<S[P]> | undefined) : number;
+export declare 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;
 };
 /**
  * A helper type used in the definition of {@link AggregatePropsOnly}.
@@ -62,6 +66,9 @@ export declare function getAggregatePropsOnly<T extends QuerySelect>(select: T):
 export declare type AggregateValuesOnly<T extends QuerySelect> = {
     [K in AggregatePropsOnly<T>]: number;
 };
+export declare type CalculationValues<C extends QueryCalculations<any>> = {
+    [K in keyof C]: number;
+};
 /**
  * A helper type used in the definition of {@link ColumnPropsOnly}.
  */
@@ -93,17 +100,30 @@ export declare function getColumnPropsOnly<T extends QuerySelect>(select: T): Co
  * @param select the `select` object from a query
  */
 export declare function getColumnsOnly(select: QuerySelect): QueryColumn<any>[];
+export declare 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 declare type QueryCalculations<S extends QuerySelect> = Record<string, Calculation<S>>;
+export declare 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
  * 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
      * aggregation values across the whole dataset, e.g. if the `select`

package/dist/queryModel.js.map

@@ -1 +1 @@
-{"version":3,"file":"queryModel.js","sourceRoot":"","sources":["../src/queryModel.ts"],"names":[],"mappings":";;;AAAA,+CAAwC;AACxC,6CAA4C;AAkD5C;;;;;;;;;;;;GAYG;AACH,SAAgB,qBAAqB,CAAwB,MAAS;IAClE,IAAM,IAAI,GAAG,IAAA,qBAAM,EAAC,MAAM,CAAC,CAAC,MAAM,CAAC,UAAA,CAAC,IAAI,OAAA,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,YAAY,yBAAW,CAAC,EAAnC,CAAmC,CAAC,CAAA;IAC5E,OAAO,IAA+B,CAAC;AAC3C,CAAC;AAHD,sDAGC;AAwBD;;;;;;;;;;;;GAYG;AACH,SAAgB,kBAAkB,CAAwB,MAAS;IAC/D,IAAM,IAAI,GAAG,IAAA,qBAAM,EAAC,MAAM,CAAC,CAAC,MAAM,CAAC,UAAA,CAAC,IAAI,OAAA,MAAM,CAAC,CAAC,CAAC,YAAY,yBAAW,EAAhC,CAAgC,CAAC,CAAA;IACzE,OAAO,IAA4B,CAAC;AACxC,CAAC;AAHD,gDAGC;AAED;;;;GAIG;AACH,SAAgB,cAAc,CAAC,MAAmB;IAC9C,OAAO,IAAA,qBAAM,EAAC,MAAM,CAAC;SAChB,GAAG,CAAC,UAAA,CAAC,IAAI,OAAA,MAAM,CAAC,CAAC,CAAC,EAAT,CAAS,CAAC;SACnB,MAAM,CAAC,UAAA,CAAC,IAAI,OAAA,CAAC,YAAY,yBAAW,EAAxB,CAAwB,CAAC;SACrC,GAAG,CAAC,UAAA,CAAC,IAAI,OAAC,CAAsB,EAAvB,CAAuB,CAAC,CAAC;AAC3C,CAAC;AALD,wCAKC"}
+{"version":3,"file":"queryModel.js","sourceRoot":"","sources":["../src/queryModel.ts"],"names":[],"mappings":";;;AAAA,+CAAwC;AACxC,6CAA4C;AAsD5C;;;;;;;;;;;;GAYG;AACH,SAAgB,qBAAqB,CAAwB,MAAS;IAClE,IAAM,IAAI,GAAG,IAAA,qBAAM,EAAC,MAAM,CAAC,CAAC,MAAM,CAAC,UAAC,CAAC,IAAK,OAAA,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,YAAY,yBAAW,CAAC,EAAnC,CAAmC,CAAC,CAAC;IAC/E,OAAO,IAA+B,CAAC;AAC3C,CAAC;AAHD,sDAGC;AA4BD;;;;;;;;;;;;GAYG;AACH,SAAgB,kBAAkB,CAAwB,MAAS;IAC/D,IAAM,IAAI,GAAG,IAAA,qBAAM,EAAC,MAAM,CAAC,CAAC,MAAM,CAAC,UAAC,CAAC,IAAK,OAAA,MAAM,CAAC,CAAC,CAAC,YAAY,yBAAW,EAAhC,CAAgC,CAAC,CAAC;IAC5E,OAAO,IAA4B,CAAC;AACxC,CAAC;AAHD,gDAGC;AAED;;;;GAIG;AACH,SAAgB,cAAc,CAAC,MAAmB;IAC9C,OAAO,IAAA,qBAAM,EAAC,MAAM,CAAC;SAChB,GAAG,CAAC,UAAC,CAAC,IAAK,OAAA,MAAM,CAAC,CAAC,CAAC,EAAT,CAAS,CAAC;SACrB,MAAM,CAAC,UAAC,CAAC,IAAK,OAAA,CAAC,YAAY,yBAAW,EAAxB,CAAwB,CAAC;SACvC,GAAG,CAAC,UAAC,CAAC,IAAK,OAAA,CAAqB,EAArB,CAAqB,CAAC,CAAC;AAC3C,CAAC;AALD,wCAKC"}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "flowerbi",
-    "version": "3.8.3",
+    "version": "3.9.0",
     "author": "Daniel Earwicker <dan@earwicker.com>",
     "license": "MIT",
     "description": "FlowerBI: ultra-minimal BI analytics query and UI tools",

package/src/QueryJson.ts

@@ -37,13 +37,36 @@ export interface AggregationJson {
 
 /**
  * Specifies an ordering criteria: which column to sort by, and optionally
- * whether it is descending (the default is ascending). The column is
- * specified by a string of the form `table.column`.
+ * whether it is descending (the default is ascending). The column can be
+ * specified by a string of the form `table.column`, though this can only
+ * target one of the columns specified in select. More flexibly, specify
+ * a type of column (the type 'Value' refers to aggregations) and its
+ * zero-based position.
  */
-export interface OrderingJson {
-    column: string;
+export type OrderingJson = {
     descending?: boolean;
-}
+} & (
+    | {
+          column: string;
+      }
+    | {
+          type: "Select" | "Value" | "Calculation";
+          index: number;
+      }
+);
+
+/**
+ * Specifies an expression for calculating a derived value based on
+ * the values of aggregations, specified by zero-based position.
+ */
+export type CalculationJson =
+    | { value: number }
+    | { aggregation: number }
+    | {
+          first: CalculationJson;
+          operator: "+" | "-" | "*" | "/";
+          second: CalculationJson;
+      };
 
 /**
  * Specifies an entire query.
@@ -57,6 +80,10 @@ export interface QueryJson {
      * The aggregated values to fetch.
      */
     aggregations: AggregationJson[];
+    /**
+     * The calculations to perform.
+     */
+    calculations?: CalculationJson[];
     /**
      * Filters to apply. They are always combined with AND.
      */

package/src/QueryValues.ts

@@ -1,29 +1,29 @@
-import { 
-    QuerySelect, 
-    ExpandedQueryRecord, 
-    AggregateValuesOnly, 
-    AggregatePropsOnly, 
-    ExpandedQueryRecordWithOptionalColumns 
+import {
+    QuerySelect,
+    ExpandedQueryRecord,
+    AggregateValuesOnly,
+    AggregatePropsOnly,
+    ExpandedQueryRecordWithOptionalColumns,
+    QueryCalculations,
+    CalculationValues,
 } from "./queryModel";
 
 /**
  * An abstract interface representing either a row from a dataset or
- * the {@link ExpandedQueryResult.totals} row, so that generic code can 
+ * the {@link ExpandedQueryResult.totals} row, so that generic code can
  * format either of them in a consistent way.
  */
-export interface QueryValues<S extends QuerySelect> {
+export interface QueryValues<S extends QuerySelect, C extends QueryCalculations<S>> {
     /**
      * The plain values of columns, which may be `undefined` if this
      * refers to the {@link ExpandedQueryResult.totals} record.
      */
-    values: ExpandedQueryRecordWithOptionalColumns<S>;
+    values: ExpandedQueryRecordWithOptionalColumns<S, C>;
     percentage<K extends AggregatePropsOnly<S>>(key: K): number;
 }
 
-export class QueryValuesRow<S extends QuerySelect> implements QueryValues<S> {
-    constructor(
-        public readonly values: ExpandedQueryRecord<S>, 
-        public readonly totals: AggregateValuesOnly<S> | undefined) {}
+export class QueryValuesRow<S extends QuerySelect, C extends QueryCalculations<S>> implements QueryValues<S, C> {
+    constructor(public readonly values: ExpandedQueryRecord<S, C>, public readonly totals: (AggregateValuesOnly<S> & CalculationValues<C>) | undefined) {}
 
     percentage<K extends AggregatePropsOnly<S>>(key: K) {
         if (!this.totals) return 0;
@@ -35,11 +35,11 @@ export class QueryValuesRow<S extends QuerySelect> implements QueryValues<S> {
     }
 }
 
-export class QueryValuesTotal<S extends QuerySelect> implements QueryValues<S> {
-    public readonly values: ExpandedQueryRecordWithOptionalColumns<S>;
+export class QueryValuesTotal<S extends QuerySelect, C extends QueryCalculations<S>> implements QueryValues<S, C> {
+    public readonly values: ExpandedQueryRecordWithOptionalColumns<S, C>;
 
-    constructor(totals: AggregateValuesOnly<S>) {
-        this.values = totals as ExpandedQueryRecordWithOptionalColumns<S>;
+    constructor(totals: AggregateValuesOnly<S> & CalculationValues<C>) {
+        this.values = totals as ExpandedQueryRecordWithOptionalColumns<S, C>;
     }
 
     percentage() {

package/src/executeQuery.test.ts

@@ -1,5 +1,6 @@
-import { jsonifyQuery } from "./executeQuery";
+import { expandQueryResult, jsonifyQuery, QueryResultJson } from "./executeQuery";
 import { QueryColumn } from "./QueryColumn";
+import { Query, QueryCalculations, QuerySelect } from "./queryModel";
 
 export const Customer = {
     Id: new QueryColumn<number>("Customer.Id"),
@@ -8,22 +9,28 @@ export const Customer = {
 
 export const Bug = {
     Id: new QueryColumn<number>("Bug.Id"),
-    CustomerId: new QueryColumn<number>("Bug.CustomerId"),    
+    CustomerId: new QueryColumn<number>("Bug.CustomerId"),
+    Fixed: new QueryColumn<boolean>("Bug.Fixed"),
 };
 
-test("jsonifies mixed columns", () => {    
-    expect(jsonifyQuery({
-        select: {
-            customer: Customer.CustomerName,
-            bugCount: Bug.Id.count()
-        }
-    })).toStrictEqual({
+test("jsonifies mixed columns", () => {
+    expect(
+        jsonifyQuery({
+            select: {
+                customer: Customer.CustomerName,
+                bugCount: Bug.Id.count(),
+            },
+        })
+    ).toStrictEqual({
         select: ["Customer.CustomerName"],
-        aggregations: [{
-            column: "Bug.Id",
-            function: "Count",
-            filters: undefined
-        }],
+        aggregations: [
+            {
+                column: "Bug.Id",
+                function: "Count",
+                filters: undefined,
+            },
+        ],
+        calculations: undefined,
         filters: [],
         orderBy: [],
         skip: 0,
@@ -34,14 +41,17 @@ test("jsonifies mixed columns", () => {
     });
 });
 
-test("jsonifies select", () => {    
-    expect(jsonifyQuery({
-        select: {
-            customer: Customer.CustomerName,
-        }
-    })).toStrictEqual({
+test("jsonifies select", () => {
+    expect(
+        jsonifyQuery({
+            select: {
+                customer: Customer.CustomerName,
+            },
+        })
+    ).toStrictEqual({
         select: ["Customer.CustomerName"],
         aggregations: [],
+        calculations: undefined,
         filters: [],
         orderBy: [],
         skip: 0,
@@ -53,16 +63,19 @@ test("jsonifies select", () => {
 });
 
 test("jsonifies params", () => {
-    expect(jsonifyQuery({
-        select: {},
-        skip: 3,
-        take: 42,
-        totals: true,
-        allowDuplicates: true,
-        comment: "a comment",
-    })).toStrictEqual({
+    expect(
+        jsonifyQuery({
+            select: {},
+            skip: 3,
+            take: 42,
+            totals: true,
+            allowDuplicates: true,
+            comment: "a comment",
+        })
+    ).toStrictEqual({
         select: [],
         aggregations: [],
+        calculations: undefined,
         filters: [],
         orderBy: [],
         skip: 3,
@@ -74,32 +87,36 @@ test("jsonifies params", () => {
 });
 
 test("jsonifies filters", () => {
-    expect(jsonifyQuery({
-        select: {
-            bugCount: Bug.Id.count([
-                Customer.CustomerName.lessThan("z")
-            ])
-        },
-        filters: [
-            Customer.CustomerName.greaterThan("a")
-        ]
-        
-    })).toStrictEqual({
+    expect(
+        jsonifyQuery({
+            select: {
+                bugCount: Bug.Id.count([Customer.CustomerName.lessThan("z")]),
+            },
+            filters: [Customer.CustomerName.greaterThan("a")],
+        })
+    ).toStrictEqual({
         select: [],
-        aggregations: [{
-            column: "Bug.Id",
-            function: "Count",
-            filters: [{
+        aggregations: [
+            {
+                column: "Bug.Id",
+                function: "Count",
+                filters: [
+                    {
+                        column: "Customer.CustomerName",
+                        operator: "<",
+                        value: "z",
+                    },
+                ],
+            },
+        ],
+        calculations: undefined,
+        filters: [
+            {
                 column: "Customer.CustomerName",
-                operator: "<",
-                value: "z",
-            }]
-        }],
-        filters: [{
-            column: "Customer.CustomerName",
-            operator: ">",
-            value: "a",
-        }],
+                operator: ">",
+                value: "a",
+            },
+        ],
         orderBy: [],
         skip: 0,
         take: 100,
@@ -109,20 +126,126 @@ test("jsonifies filters", () => {
     });
 });
 
-test("jsonifies orderBy", () => {    
-    expect(jsonifyQuery({
-        select: {},
+test("jsonifies orderBy", () => {
+    expect(
+        jsonifyQuery({
+            select: {},
+            orderBy: [Customer.CustomerName.descending()],
+        })
+    ).toStrictEqual({
+        select: [],
+        aggregations: [],
+        calculations: undefined,
+        filters: [],
+        orderBy: [
+            {
+                column: "Customer.CustomerName",
+                descending: true,
+            },
+        ],
+        skip: 0,
+        take: 100,
+        totals: false,
+        allowDuplicates: undefined,
+        comment: undefined,
+    });
+});
+
+test("jsonifies calculations and ordering by keys", () => {
+    expect(
+        jsonifyQuery({
+            select: {
+                customer: Customer.CustomerName,
+                bugCount: Bug.Id.count(),
+                bugsFixed: Bug.Id.count([Bug.Fixed.equalTo(true)]),
+            },
+            calculations: {
+                successRate: [100, "*", ["bugsFixed", "/", "bugCount"]],
+                failureRate: [100, "-", [100, "*", ["bugsFixed", "/", "bugCount"]]],
+            },
+            orderBy: [
+                { select: "customer" },
+                { select: "bugsFixed", descending: true },
+                { calculation: "successRate" },
+                { calculation: "failureRate", descending: true },
+            ],
+        })
+    ).toStrictEqual({
+        select: ["Customer.CustomerName"],
+        aggregations: [
+            {
+                column: "Bug.Id",
+                function: "Count",
+                filters: undefined,
+            },
+            {
+                column: "Bug.Id",
+                function: "Count",
+                filters: [
+                    {
+                        column: "Bug.Fixed",
+                        operator: "=",
+                        value: true,
+                    },
+                ],
+            },
+        ],
+        calculations: [
+            {
+                first: { value: 100 },
+                operator: "*",
+                second: {
+                    first: { aggregation: 1 },
+                    operator: "/",
+                    second: { aggregation: 0 },
+                },
+            },
+            {
+                first: { value: 100 },
+                operator: "-",
+                second: {
+                    first: { value: 100 },
+                    operator: "*",
+                    second: {
+                        first: { aggregation: 1 },
+                        operator: "/",
+                        second: { aggregation: 0 },
+                    },
+                },
+            },
+        ],
+        filters: [],
         orderBy: [
-            Customer.CustomerName.descending()
-        ]
-    })).toStrictEqual({
+            { type: "Select", index: 0, descending: undefined },
+            { type: "Value", index: 1, descending: true },
+            { type: "Calculation", index: 0, descending: undefined },
+            { type: "Calculation", index: 1, descending: true },
+        ],
+        skip: 0,
+        take: 100,
+        totals: false,
+        allowDuplicates: undefined,
+        comment: undefined,
+    });
+});
+
+test("passes through JSON orderBy", () => {
+    expect(
+        jsonifyQuery({
+            select: {},
+            orderBy: [Customer.CustomerName.descending()],
+        })
+    ).toStrictEqual({
         select: [],
         aggregations: [],
+        calculations: undefined,
         filters: [],
-        orderBy: [{
-            column: "Customer.CustomerName",
-            descending: true,
-        }],
+        orderBy: [
+            {
+                column: "Customer.CustomerName",
+                descending: true,
+            },
+        ],
         skip: 0,
         take: 100,
         totals: false,
@@ -130,3 +253,81 @@ test("jsonifies orderBy", () => {
         comment: undefined,
     });
 });
+
+function formatResultsFromQuery<S extends QuerySelect, C extends QueryCalculations<S>>(query: Query<S, C>, result: QueryResultJson) {
+    return expandQueryResult<S, C>(query.select, result, query.calculations);
+}
+
+test("generates typed results", () => {
+    const result = formatResultsFromQuery(
+        {
+            select: {
+                customer: Customer.CustomerName,
+                bugCount: Bug.Id.count(),
+                bugsFixed: Bug.Id.count([Bug.Fixed.equalTo(true)]),
+            },
+            calculations: {
+                successRate: [100, "*", ["bugsFixed", "/", "bugCount"]],
+                failureRate: [100, "-", [100, "*", ["bugsFixed", "/", "bugCount"]]],
+            },
+            orderBy: [
+                { select: "customer" },
+                { select: "bugsFixed", descending: true },
+                { calculation: "successRate" },
+                { calculation: "failureRate", descending: true },
+            ],
+        },
+        {
+            records: [
+                {
+                    selected: ["woolworths"],
+                    aggregated: [3, 1, 33.33, 66.67],
+                },
+            ],
+        }
+    );
+
+    expect(result).toStrictEqual({
+        records: [{ customer: "woolworths", bugCount: 3, bugsFixed: 1, successRate: 33.33, failureRate: 66.67 }],
+        totals: undefined,
+    });
+});
+
+test("generates typed results with totals", () => {
+    const result = formatResultsFromQuery(
+        {
+            select: {
+                customer: Customer.CustomerName,
+                bugCount: Bug.Id.count(),
+                bugsFixed: Bug.Id.count([Bug.Fixed.equalTo(true)]),
+            },
+            calculations: {
+                successRate: [100, "*", ["bugsFixed", "/", "bugCount"]],
+                failureRate: [100, "-", [100, "*", ["bugsFixed", "/", "bugCount"]]],
+            },
+            orderBy: [
+                { select: "customer" },
+                { select: "bugsFixed", descending: true },
+                { calculation: "successRate" },
+                { calculation: "failureRate", descending: true },
+            ],
+        },
+        {
+            records: [
+                {
+                    selected: ["woolworths"],
+                    aggregated: [3, 1, 33.33, 66.67],
+                },
+            ],
+            totals: {
+                selected: [""],
+                aggregated: [4, 2, 50, 50],
+            },
+        }
+    );
+
+    expect(result).toStrictEqual({
+        records: [{ customer: "woolworths", bugCount: 3, bugsFixed: 1, successRate: 33.33, failureRate: 66.67 }],
+        totals: { bugCount: 4, bugsFixed: 2, successRate: 50, failureRate: 50 },
+    });
+});