@uwdata/mosaic-sql 0.13.0 → 0.14.1

package/dist/types/transforms/bin-date.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @typedef {object} BinDateOptions
+ * @property {TimeUnit} [interval] A string indicating a time interval
+ *  unit, such as 'year', 'day', or 'hour'.
+ * @property {number} [step] The number of time interval steps to
+ *  take, such as 2 years or 3 months.
+ * @property {number} [offset] The number of bin steps (default 0) by
+ *  which to offset the result.
+ * @property {number} [steps] The desired number of binning steps.
+ *  This value is a hint, it does not guarantee an exact number of steps.
+ */
+/**
+ * Return a SQL expression for date/time bins.
+ * @param {ExprValue} field The column or expression to bin.
+ * @param {[Date|number, Date|number]} extent The min/max extent over which to bin.
+ * @param {BinDateOptions} [options] Datetime binning options.
+ * @returns {ExprNode}
+ */
+export function binDate(field: ExprValue, extent: [Date | number, Date | number], options?: BinDateOptions): ExprNode;
+export type BinDateOptions = {
+    /**
+     * A string indicating a time interval
+     * unit, such as 'year', 'day', or 'hour'.
+     */
+    interval?: TimeUnit;
+    /**
+     * The number of time interval steps to
+     * take, such as 2 years or 3 months.
+     */
+    step?: number;
+    /**
+     * The number of bin steps (default 0) by
+     * which to offset the result.
+     */
+    offset?: number;
+    /**
+     * The desired number of binning steps.
+     * This value is a hint, it does not guarantee an exact number of steps.
+     */
+    steps?: number;
+};
+import type { ExprValue } from '../types.js';
+import type { ExprNode } from '../ast/node.js';
+import type { TimeUnit } from '../types.js';

package/dist/types/transforms/bin-histogram.d.ts

@@ -0,0 +1,51 @@
+/**
+ * @typedef {object} BinHistogramOptions
+ * @property {number} [step] An exact binning step to use.
+ * @property {number} [steps] The desired number of binning steps.
+ *  This value is a hint, it does not guarantee an exact number of steps.
+ * @property {number} [minstep] A minimum binning step value. No generated
+ *  step can be less than this value.
+ * @property {boolean} [nice] A boolean flag (default true) indicating if bin
+ *  extents should be snapped to "nice" numbers such as multiples of 5 or 10.
+ * @property {number} [offset] The number of bin steps (default 0) by
+ *  which to offset the result.
+ */
+/**
+ * Return a SQL expression for histogram bins.
+ * @param {ExprValue} field The column or expression to bin.
+ * @param {[number, number]} extent The min/max extent over which to bin.
+ * @param {BinHistogramOptions} [options] Binning options.
+ * @param {ReturnType<typeof scaleTransform>} [transform] Scale transforms to
+ *  apply to create (potentially non-linear) binning intervals.
+ * @returns {ExprNode} The resulting SQL expression
+ */
+export function binHistogram(field: ExprValue, extent: [number, number], options?: BinHistogramOptions, transform?: ReturnType<typeof scaleTransform>): ExprNode;
+export type BinHistogramOptions = {
+    /**
+     * An exact binning step to use.
+     */
+    step?: number;
+    /**
+     * The desired number of binning steps.
+     * This value is a hint, it does not guarantee an exact number of steps.
+     */
+    steps?: number;
+    /**
+     * A minimum binning step value. No generated
+     * step can be less than this value.
+     */
+    minstep?: number;
+    /**
+     * A boolean flag (default true) indicating if bin
+     * extents should be snapped to "nice" numbers such as multiples of 5 or 10.
+     */
+    nice?: boolean;
+    /**
+     * The number of bin steps (default 0) by
+     * which to offset the result.
+     */
+    offset?: number;
+};
+import type { ExprValue } from '../types.js';
+import { scaleTransform } from './scales.js';
+import type { ExprNode } from '../ast/node.js';

package/dist/types/transforms/bin-linear-1d.d.ts

@@ -1,10 +1,12 @@
 /**
  * Perform linear binning in one dimension.
- * @param {import('../ast/query.js').SelectQuery} query The base query to bin.
- * @param {import('../types.js').ExprValue} x The expression to bin.
- * @param {import('../types.js').ExprValue} [weight] The expression to weight by.
+ * @param {SelectQuery} query The base query to bin.
+ * @param {ExprValue} x The expression to bin.
+ * @param {ExprValue} [weight] The expression to weight by.
  * @param {string[]} [groupby] Group by expressions.
  * @returns {Query}
  */
-export function binLinear1d(query: import("../ast/query.js").SelectQuery, x: import("../types.js").ExprValue, weight?: import("../types.js").ExprValue, groupby?: string[]): Query;
+export function binLinear1d(query: SelectQuery, x: ExprValue, weight?: ExprValue, groupby?: string[]): Query;
+import type { SelectQuery } from '../ast/query.js';
+import type { ExprValue } from '../types.js';
 import { Query } from '../ast/query.js';

package/dist/types/transforms/bin-linear-2d.d.ts

@@ -6,13 +6,14 @@
  * should be in units of grid indices, but can contain fractional components.
  * @param {SelectQuery} q The input query. The FROM and WHERE clauses should
  *  be added to the query separately, before this method is invoked.
- * @param {import('../types.js').ExprValue} xp The x grid bin expression
- * @param {import('../types.js').ExprValue} yp The y grid bin expression
- * @param {import('../types.js').ExprValue | undefined} weight Point weights.
+ * @param {ExprValue} xp The x grid bin expression
+ * @param {ExprValue} yp The y grid bin expression
+ * @param {ExprValue | undefined} weight Point weights.
  * @param {number} xn The number of x grid bins.
  * @param {string[]} [groupby] Group by expressions.
  * @returns {SelectQuery} A linear binning query for bin `index` and
  *  aggregate `density` columns, in addition to any group by expressions.
  */
-export function binLinear2d(q: SelectQuery, xp: import("../types.js").ExprValue, yp: import("../types.js").ExprValue, weight: import("../types.js").ExprValue | undefined, xn: number, groupby?: string[]): SelectQuery;
-import { SelectQuery } from '../ast/query.js';
+export function binLinear2d(q: SelectQuery, xp: ExprValue, yp: ExprValue, weight: ExprValue | undefined, xn: number, groupby?: string[]): SelectQuery;
+import type { SelectQuery } from '../ast/query.js';
+import type { ExprValue } from '../types.js';

package/dist/types/transforms/line-density.d.ts

@@ -5,9 +5,9 @@
  * and then sum results for all line series to produce a density map.
  * Based on Moritz and Fisher's work: https://arxiv.org/abs/1808.06019
  * @param {SelectQuery} q The base query over the data.
- * @param {import('../types.js').ExprValue} x Bin expression for x dimension.
+ * @param {ExprValue} x Bin expression for x dimension.
  *  Provides gridded x coordinates, potentially with a fractional component.
- * @param {import('../types.js').ExprValue} y Bin expression for x dimension.
+ * @param {ExprValue} y Bin expression for x dimension.
  *  Provides gridded y coordinates, potentially with a fractional component.
  * @param {string[]} z Group by columns that segment data into individual line
  *  series. An empty array indicates there is only a single line series.
@@ -19,5 +19,6 @@
  *  normalization to improve accuracy and reduce artifacts (default `true`).
  * @returns {SelectQuery}
  */
-export function lineDensity(q: SelectQuery, x: import("../types.js").ExprValue, y: import("../types.js").ExprValue, z: string[], xn: number, yn: number, groupby?: string[], normalize?: boolean): SelectQuery;
-import { SelectQuery } from '../ast/query.js';
+export function lineDensity(q: SelectQuery, x: ExprValue, y: ExprValue, z: string[], xn: number, yn: number, groupby?: string[], normalize?: boolean): SelectQuery;
+import type { SelectQuery } from '../ast/query.js';
+import type { ExprValue } from '../types.js';

package/dist/types/transforms/m4.d.ts

@@ -5,14 +5,17 @@
  * argmin and argmax, following https://arxiv.org/pdf/2306.03714.pdf.
  * This method can bin along either the *x* or *y* dimension, as determined
  * by the caller-provided *bin* expression.
- * @param {import('../types.js').FromExpr} input The base query or table.
- * @param {import('../types.js').ExprValue} bin An expression that maps
+ * @param {FromExpr} input The base query or table.
+ * @param {ExprValue} bin An expression that maps
  *  time-series values to fractional pixel positions.
  * @param {string} x The x dimension column name.
  * @param {string} y The y dimension column name.
- * @param {import('../ast/node.js').ExprNode[]} [groups] Additional
+ * @param {ExprNode[]} [groups] Additional
  *  groupby columns, for example for faceted charts.
  * @returns {Query} The resulting M4 query.
  */
-export function m4(input: import("../types.js").FromExpr, bin: import("../types.js").ExprValue, x: string, y: string, groups?: import("../ast/node.js").ExprNode[]): Query;
+export function m4(input: FromExpr, bin: ExprValue, x: string, y: string, groups?: ExprNode[]): Query;
+import type { FromExpr } from '../types.js';
+import type { ExprValue } from '../types.js';
+import type { ExprNode } from '../ast/node.js';
 import { Query } from '../ast/query.js';

package/dist/types/transforms/util/bin-step.d.ts

@@ -0,0 +1,61 @@
+/**
+ * @typedef {object} BinOptions
+ * @property {number} [step] An exact binning step to use.
+ * @property {number} [steps] The desired number of binning steps.
+ *  This value is a hint, it does not guarantee an exact number of steps.
+ * @property {number} [minstep] A minimum binning step value. No generated
+ *  step can be less than this value.
+ * @property {boolean} [nice] A boolean flag (default true) indicating if bin
+ *  extents should be snapped to "nice" numbers such as multiples of 5 or 10.
+ * @property {number} [base] A number indicating the the logarithm base to
+ *  use for automatic step size determination. Defaults to base 10.
+ */
+/**
+ * Generate a numeric binning scheme suitable for a histogram.
+ * @param {number} min The minimum value of the extent to bin.
+ * @param {number} max The maximum value of the extent to bin.
+ * @param {BinOptions} options Binning scheme options.
+ */
+export function binSpec(min: number, max: number, options: BinOptions): {
+    min: number;
+    max: number;
+    steps: number;
+};
+/**
+ * Determine a bin step interval.
+ * @param {number} span The span from maximum to minimum value.
+ * @param {number} steps The approximate number of desired bins.
+ * @param {number} [minstep=0] The minimum acceptable bin step size.
+ * @param {number} [logb=Math.LN10] The log base for determining
+ *  orders of magnitude for step sizes. Defaults to log base 10
+ *  (`Math.LN10`). For example to use log base 2, provide the
+ *  argument `Math.LN2` instead.
+ * @returns {number} The bin step interval (bin size).
+ */
+export function binStep(span: number, steps: number, minstep?: number, logb?: number): number;
+export type BinOptions = {
+    /**
+     * An exact binning step to use.
+     */
+    step?: number;
+    /**
+     * The desired number of binning steps.
+     * This value is a hint, it does not guarantee an exact number of steps.
+     */
+    steps?: number;
+    /**
+     * A minimum binning step value. No generated
+     * step can be less than this value.
+     */
+    minstep?: number;
+    /**
+     * A boolean flag (default true) indicating if bin
+     * extents should be snapped to "nice" numbers such as multiples of 5 or 10.
+     */
+    nice?: boolean;
+    /**
+     * A number indicating the the logarithm base to
+     * use for automatic step size determination. Defaults to base 10.
+     */
+    base?: number;
+};

package/dist/types/transforms/util/time-interval.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Determine a time interval for binning based on provided min
+ * and max timestamps and approximate step count.
+ * @param {Date|number} min The minimum timestamp value.
+ * @param {Date|number} max The maximum timestamp value.
+ * @param {number} steps The approximate number of bins desired.
+ * @returns {{ unit: TimeUnit, step: number }}
+ */
+export function timeInterval(min: Date | number, max: Date | number, steps: number): {
+    unit: TimeUnit;
+    step: number;
+};
+import type { TimeUnit } from '../../types.js';

package/dist/types/types.d.ts

@@ -59,3 +59,4 @@ export type FromExpr = MaybeArray<FromEntry>;
 export type FilterExpr = MaybeArray<string | ExprNode>;
 export type GroupByExpr = MaybeArray<string | ExprNode>;
 export type OrderByExpr = MaybeArray<string | ExprNode>;
+export type TimeUnit = 'year' | 'quarter' | 'month' | 'day' | 'hour' | 'minute' | 'second' | 'millisecond' | 'microsecond';

package/dist/types/util/ast.d.ts

@@ -38,16 +38,16 @@ export function asTableRef(value: string | string[] | TableRefNode): TableRefNod
  * Parse a string as a column reference, potentially with
  * dot ('.') delimited table, schema, and database references.
  * @param {string} ref The column reference string.
- * @returns {import('../ast/column-ref.js').ColumnRefNode}
+ * @returns {ColumnRefNode}
  */
-export function parseColumnRef(ref: string): import("../ast/column-ref.js").ColumnRefNode;
+export function parseColumnRef(ref: string): ColumnRefNode;
 /**
  * Parse a string as a table reference, potentially with
  * dot ('.') delimited schema and database references.
  * @param {string} ref The table reference string.
- * @returns {import('../ast/table-ref.js').TableRefNode}
+ * @returns {TableRefNode}
  */
-export function parseTableRef(ref: string): import("../ast/table-ref.js").TableRefNode;
+export function parseTableRef(ref: string): TableRefNode;
 /**
  * Create a new window definition node. The return value is an empty
  * window definition. Use chained calls such as `partitionby` and `orderby`
@@ -56,5 +56,6 @@ export function parseTableRef(ref: string): import("../ast/table-ref.js").TableR
  */
 export function over(): WindowDefNode;
 import { ExprNode } from '../ast/node.js';
-import { TableRefNode } from '../ast/table-ref.js';
+import type { TableRefNode } from '../ast/table-ref.js';
+import type { ColumnRefNode } from '../ast/column-ref.js';
 import { WindowDefNode } from '../ast/window.js';

package/dist/types/util/function.d.ts

@@ -1,10 +1,10 @@
 /**
  * Test if an AST node is a specific function call.
- * @param {import('../ast/node.js').SQLNode} node The SQL AST node to test.
+ * @param {SQLNode} node The SQL AST node to test.
  * @param {string} name The function name.
  * @returns {node is FunctionNode}
  */
-export function isFunctionCall(node: import("../ast/node.js").SQLNode, name: string): node is FunctionNode;
+export function isFunctionCall(node: SQLNode, name: string): node is FunctionNode;
 /**
  * Create a new function call AST node.
  * @param {string} name The function name.
@@ -23,11 +23,11 @@ export function aggFn(name: string, ...args: any[]): AggregateNode;
  * Create a new window AST node. The output node has an empty window
  * definition. Use chained calls such as `partitionby` and `orderby`
  * to specify the window settings.
- * @param {import('../types.js').WindowFunctionName} name The function name.
+ * @param {WindowFunctionName} name The function name.
  * @param  {...any} args The function arguments.
  * @returns {WindowNode}
  */
-export function winFn(name: import("../types.js").WindowFunctionName, ...args: any[]): WindowNode;
+export function winFn(name: WindowFunctionName, ...args: any[]): WindowNode;
 /**
  * Process a list of expression inputs. Nested arrays are flattened,
  * null results are removed, and each input is cast (as needed) to
@@ -49,6 +49,8 @@ export function exprList(list: any[], cast?: Function): ReturnType<Function>[];
  * @returns {T[]} The prepared argument list.
  */
 export function argsList<T>(list: T[]): T[];
+import type { SQLNode } from '../ast/node.js';
 import { FunctionNode } from '../ast/function.js';
 import { AggregateNode } from '../ast/aggregate.js';
+import type { WindowFunctionName } from '../types.js';
 import { WindowNode } from '../ast/window.js';

package/dist/types/util/type-check.d.ts

@@ -1,3 +1,6 @@
+/**
+ * @import { ParamLike } from '../types.js'
+ */
 /**
  * Check if a value is a string.
  * @param {*} value The value to check.
@@ -13,6 +16,7 @@ export function isArray(value: any): value is any[];
 /**
  * Check if a value is a dynamic parameter.
  * @param {*} value The value to check.
- * @returns {value is import('../types.js').ParamLike}
+ * @returns {value is ParamLike}
  */
-export function isParamLike(value: any): value is import("../types.js").ParamLike;
+export function isParamLike(value: any): value is ParamLike;
+import type { ParamLike } from '../types.js';

package/dist/types/visit/visitors.d.ts

@@ -25,9 +25,10 @@ export function collectColumns(root: SQLNode): ColumnRefNode[];
 /**
  * Collect all unique dynamic parameter instances.
  * @param {SQLNode} root The root of the AST to search.
- * @returns {import('../types.js').ParamLike[]}
+ * @returns {ParamLike[]}
  */
-export function collectParams(root: SQLNode): import("../types.js").ParamLike[];
+export function collectParams(root: SQLNode): ParamLike[];
 import { SQLNode } from '../ast/node.js';
 import { AggregateNode } from '../ast/aggregate.js';
 import { ColumnRefNode } from '../ast/column-ref.js';
+import type { ParamLike } from '../types.js';

package/dist/types/visit/walk.d.ts

@@ -1,7 +1,10 @@
 /**
  * Perform a traversal of a SQL expression AST.
- * @param {import('../ast/node.js').SQLNode} node Root node for AST traversal.
- * @param {import('../types.js').VisitorCallback} visit Visitor callback function.
- * @return {import('../types.js').VisitorResult}
+ * @param {SQLNode} node Root node for AST traversal.
+ * @param {VisitorCallback} visit Visitor callback function.
+ * @return {VisitorResult}
  */
-export function walk(node: import("../ast/node.js").SQLNode, visit: import("../types.js").VisitorCallback): import("../types.js").VisitorResult;
+export function walk(node: SQLNode, visit: VisitorCallback): VisitorResult;
+import type { SQLNode } from '../ast/node.js';
+import type { VisitorCallback } from '../types.js';
+import type { VisitorResult } from '../types.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uwdata/mosaic-sql",
-  "version": "0.13.0",
+  "version": "0.14.1",
   "description": "SQL query construction and analysis.",
   "keywords": [
     "sql",
@@ -27,5 +27,5 @@
     "tsc": "tsc -p jsconfig.json",
     "prepublishOnly": "npm run test && npm run lint && npm run build"
   },
-  "gitHead": "b5a0e03e200c0f04c46562a288f084ffc9f6ad55"
+  "gitHead": "5959cb169e95bd8467e1e5d7a9b98954f09474f3"
 }

package/src/ast/aggregate.js

@@ -1,3 +1,6 @@
+/**
+ * @import { ExprVarArgs } from '../types.js'
+ */
 import { AGGREGATE } from '../constants.js';
 import { asVerbatim } from '../util/ast.js';
 import { isString } from '../util/type-check.js';
@@ -69,7 +72,7 @@ export class AggregateNode extends ExprNode {
 
   /**
    * Return a new window function over this aggregate with the given partitions.
-   * @param {...import('../types.js').ExprVarArgs} expr The partition by criteria.
+   * @param {...ExprVarArgs} expr The partition by criteria.
    * @returns {WindowNode} A new window node.
    */
   partitionby(...expr) {
@@ -78,7 +81,7 @@ export class AggregateNode extends ExprNode {
 
   /**
    * Return a new window function over this aggregate with the given ordering.
-   * @param {...import('../types.js').ExprVarArgs} expr The order by criteria.
+   * @param {...ExprVarArgs} expr The order by criteria.
    * @returns {WindowNode} A new window node.
    */
   orderby(...expr) {

package/src/ast/case.js

@@ -1,3 +1,6 @@
+/**
+ * @import { ExprValue } from '../types.js'
+ */
 import { CASE, WHEN } from '../constants.js';
 import { asNode } from '../util/ast.js';
 import { ExprNode, SQLNode } from './node.js';
@@ -37,10 +40,8 @@ export class CaseNode extends ExprNode {
   /**
    * Return a new case node with the given conditional added as
    * the last WHEN / THEN pair.
-   * @param {import('../types.js').ExprValue} cond
-   *  The WHEN condition expression.
-   * @param {import('../types.js').ExprValue} value
-   *  The THEN value expression.
+   * @param {ExprValue} cond The WHEN condition expression.
+   * @param {ExprValue} value The THEN value expression.
    * @returns {CaseNode}
    */
   when(cond, value) {
@@ -53,7 +54,7 @@ export class CaseNode extends ExprNode {
 
   /**
    * Return a new case node with the given ELSE expression.
-   * @param {import('../types.js').ExprValue} expr The ELSE expression.
+   * @param {ExprValue} expr The ELSE expression.
    * @returns {CaseNode}
    */
   else(expr) {

package/src/ast/column-param.js

@@ -1,3 +1,7 @@
+/**
+ * @import { ParamNode } from './param.js'
+ * @import { TableRefNode } from './table-ref.js'
+ */
 import { COLUMN_PARAM } from '../constants.js';
 import { ColumnRefNode } from './column-ref.js';
 
@@ -13,16 +17,14 @@ export function isColumnParam(value) {
 export class ColumnParamNode extends ColumnRefNode {
   /**
    * Instantiate a column param node.
-   * @param {import('./param.js').ParamNode} param The column name as a
-   *  parameter node.
-   * @param {import('./table-ref.js').TableRefNode} [table] The table
-   *  reference.
+   * @param {ParamNode} param The column name as a parameter node.
+   * @param {TableRefNode} [table] The table reference.
    */
   constructor(param, table) {
     super(COLUMN_PARAM, table);
     /**
      * The column name as a parameter node.
-     * @type {import('./param.js').ParamNode}
+     * @type {ParamNode}
      * @readonly
      */
     this.param = param;

package/src/ast/column-ref.js

@@ -1,3 +1,6 @@
+/**
+ * @import { TableRefNode } from './table-ref.js'
+ */
 import { COLUMN_REF } from '../constants.js';
 import { quoteIdentifier } from '../util/string.js';
 import { ExprNode } from './node.js';
@@ -14,13 +17,13 @@ export function isColumnRef(value) {
 export class ColumnRefNode extends ExprNode {
   /**
    * Instantiate a column reference node.
-   * @param {import('./table-ref.js').TableRefNode} [table] The table reference.
+   * @param {TableRefNode} [table] The table reference.
    */
   constructor(type, table) {
     super(type);
     /**
      * The table reference.
-     * @type {import('./table-ref.js').TableRefNode}
+     * @type {TableRefNode}
      * @readonly
      */
     this.table = table;
@@ -50,7 +53,7 @@ export class ColumnNameRefNode extends ColumnRefNode {
   /**
    * Instantiate a column reference node.
    * @param {string} name The column name.
-   * @param {import('./table-ref.js').TableRefNode} [table] The table reference.
+   * @param {TableRefNode} [table] The table reference.
    */
   constructor(name, table) {
     super(COLUMN_REF, table);

package/src/ast/param.js

@@ -1,3 +1,6 @@
+/**
+ * @import { ParamLike } from '../types.js'
+ */
 import { PARAM } from '../constants.js';
 import { literalToSQL } from './literal.js';
 import { ExprNode } from './node.js';
@@ -5,13 +8,13 @@ import { ExprNode } from './node.js';
 export class ParamNode extends ExprNode {
   /**
    * Instantiate a param node with a dynamic parameter.
-   * @param {import('../types.js').ParamLike} param The dynamic parameter.
+   * @param {ParamLike} param The dynamic parameter.
    */
   constructor(param) {
     super(PARAM);
     /**
      * The dynamic parameter.
-     * @type {import('../types.js').ParamLike}
+     * @type {ParamLike}
      * @readonly
      */
     this.param = param;