@uwdata/mosaic-sql 0.13.0 → 0.14.0

package/src/functions/operators.js

@@ -1,3 +1,6 @@
+/**
+ * @import { ExprValue, ExprVarArgs } from '../types.js'
+ */
 import { BetweenOpNode, NotBetweenOpNode } from '../ast/between-op.js';
 import { BinaryOpNode } from '../ast/binary-op.js';
 import { InOpNode } from '../ast/in-op.js';
@@ -25,7 +28,7 @@ function betweenOp(expr, extent, negate = false) {
 
 /**
  * Logical and (AND) operator.
- * @param {...import('../types.js').ExprVarArgs} clauses The input expressions.
+ * @param {...ExprVarArgs} clauses The input expressions.
  * @returns {AndNode}
  */
 export function and(...clauses) {
@@ -34,7 +37,7 @@ export function and(...clauses) {
 
 /**
  * Logical or (OR) operator.
- * @param {...import('../types.js').ExprVarArgs} clauses The input expressions.
+ * @param {...ExprVarArgs} clauses The input expressions.
  * @returns {OrNode}
  */
 export function or(...clauses) {
@@ -43,7 +46,7 @@ export function or(...clauses) {
 
 /**
  * Logical not (NOT) operator.
- * @param {import('../types.js').ExprValue} expr The expression to negate.
+ * @param {ExprValue} expr The expression to negate.
  * @returns {UnaryOpNode}
  */
 export function not(expr) {
@@ -52,7 +55,7 @@ export function not(expr) {
 
 /**
  * Null check (IS NULL) operator.
- * @param {import('../types.js').ExprValue} expr The expression to test.
+ * @param {ExprValue} expr The expression to test.
  * @returns {UnaryPosftixOpNode}
  */
 export function isNull(expr) {
@@ -61,7 +64,7 @@ export function isNull(expr) {
 
 /**
  * Non-null check (IS NOT NULL) operator.
- * @param {import('../types.js').ExprValue} expr The expression to test.
+ * @param {ExprValue} expr The expression to test.
  * @returns {UnaryPosftixOpNode}
  */
 export function isNotNull(expr) {
@@ -70,7 +73,7 @@ export function isNotNull(expr) {
 
 /**
  * Bitwise not (~) operator.
- * @param {import('../types.js').ExprValue} expr The input expression.
+ * @param {ExprValue} expr The input expression.
  * @returns {UnaryOpNode}
  */
 export function bitNot(expr) {
@@ -79,8 +82,8 @@ export function bitNot(expr) {
 
 /**
  * Bitwise and (&) operator.
- * @param {import('../types.js').ExprValue} left The left argument.
- * @param {import('../types.js').ExprValue} right The right argument.
+ * @param {ExprValue} left The left argument.
+ * @param {ExprValue} right The right argument.
  * @returns {BinaryOpNode}
  */
 export function bitAnd(left, right) {
@@ -89,8 +92,8 @@ export function bitAnd(left, right) {
 
 /**
  * Bitwise or (|) operator.
- * @param {import('../types.js').ExprValue} left The left argument.
- * @param {import('../types.js').ExprValue} right The right argument.
+ * @param {ExprValue} left The left argument.
+ * @param {ExprValue} right The right argument.
  * @returns {BinaryOpNode}
  */
 export function bitOr(left, right) {
@@ -99,8 +102,8 @@ export function bitOr(left, right) {
 
 /**
  * Bit shift left (<<) operator.
- * @param {import('../types.js').ExprValue} left The left argument.
- * @param {import('../types.js').ExprValue} right The right argument.
+ * @param {ExprValue} left The left argument.
+ * @param {ExprValue} right The right argument.
  * @returns {BinaryOpNode}
  */
 export function bitLeft(left, right) {
@@ -109,8 +112,8 @@ export function bitLeft(left, right) {
 
 /**
  * Bit shift right (>>) operator.
- * @param {import('../types.js').ExprValue} left The left argument.
- * @param {import('../types.js').ExprValue} right The right argument.
+ * @param {ExprValue} left The left argument.
+ * @param {ExprValue} right The right argument.
  * @returns {BinaryOpNode}
  */
 export function bitRight(left, right) {
@@ -119,8 +122,8 @@ export function bitRight(left, right) {
 
 /**
  * Addition (+) operator.
- * @param {import('../types.js').ExprValue} left The left argument.
- * @param {import('../types.js').ExprValue} right The right argument.
+ * @param {ExprValue} left The left argument.
+ * @param {ExprValue} right The right argument.
  * @returns {BinaryOpNode}
  */
 export function add(left, right) {
@@ -129,8 +132,8 @@ export function add(left, right) {
 
 /**
  * Subtraction (-) operator.
- * @param {import('../types.js').ExprValue} left The left argument.
- * @param {import('../types.js').ExprValue} right The right argument.
+ * @param {ExprValue} left The left argument.
+ * @param {ExprValue} right The right argument.
  * @returns {BinaryOpNode}
  */
 export function sub(left, right) {
@@ -139,8 +142,8 @@ export function sub(left, right) {
 
 /**
  * Multiplication (*) operator.
- * @param {import('../types.js').ExprValue} left The left argument.
- * @param {import('../types.js').ExprValue} right The right argument.
+ * @param {ExprValue} left The left argument.
+ * @param {ExprValue} right The right argument.
  * @returns {BinaryOpNode}
  */
 export function mul(left, right) {
@@ -149,8 +152,8 @@ export function mul(left, right) {
 
 /**
  * Division (/) operator.
- * @param {import('../types.js').ExprValue} left The left argument.
- * @param {import('../types.js').ExprValue} right The right argument.
+ * @param {ExprValue} left The left argument.
+ * @param {ExprValue} right The right argument.
  * @returns {BinaryOpNode}
  */
 export function div(left, right) {
@@ -159,8 +162,8 @@ export function div(left, right) {
 
 /**
  * Integer division (//) operator.
- * @param {import('../types.js').ExprValue} left The left argument.
- * @param {import('../types.js').ExprValue} right The right argument.
+ * @param {ExprValue} left The left argument.
+ * @param {ExprValue} right The right argument.
  * @returns {BinaryOpNode}
  */
 export function idiv(left, right) {
@@ -169,8 +172,8 @@ export function idiv(left, right) {
 
 /**
  * Modulo (%) operator.
- * @param {import('../types.js').ExprValue} left The left argument.
- * @param {import('../types.js').ExprValue} right The right argument.
+ * @param {ExprValue} left The left argument.
+ * @param {ExprValue} right The right argument.
  * @returns {BinaryOpNode}
  */
 export function mod(left, right) {
@@ -179,8 +182,8 @@ export function mod(left, right) {
 
 /**
  * Exponentiation (**) operator.
- * @param {import('../types.js').ExprValue} left The left argument.
- * @param {import('../types.js').ExprValue} right The right argument.
+ * @param {ExprValue} left The left argument.
+ * @param {ExprValue} right The right argument.
  * @returns {BinaryOpNode}
  */
 export function pow(left, right) {
@@ -189,8 +192,8 @@ export function pow(left, right) {
 
 /**
  * Equality comparision (=) operator.
- * @param {import('../types.js').ExprValue} left The left argument.
- * @param {import('../types.js').ExprValue} right The right argument.
+ * @param {ExprValue} left The left argument.
+ * @param {ExprValue} right The right argument.
  * @returns {BinaryOpNode}
  */
 export function eq(left, right) {
@@ -199,8 +202,8 @@ export function eq(left, right) {
 
 /**
  * Non-equality comparision (<>) operator.
- * @param {import('../types.js').ExprValue} left The left argument.
- * @param {import('../types.js').ExprValue} right The right argument.
+ * @param {ExprValue} left The left argument.
+ * @param {ExprValue} right The right argument.
  * @returns {BinaryOpNode}
  */
 export function neq(left, right) {
@@ -209,8 +212,8 @@ export function neq(left, right) {
 
 /**
  * Less-than comparision (<) operator.
- * @param {import('../types.js').ExprValue} left The left argument.
- * @param {import('../types.js').ExprValue} right The right argument.
+ * @param {ExprValue} left The left argument.
+ * @param {ExprValue} right The right argument.
  * @returns {BinaryOpNode}
  */
 export function lt(left, right) {
@@ -219,8 +222,8 @@ export function lt(left, right) {
 
 /**
  * Greater-than comparision (>) operator.
- * @param {import('../types.js').ExprValue} left The left argument.
- * @param {import('../types.js').ExprValue} right The right argument.
+ * @param {ExprValue} left The left argument.
+ * @param {ExprValue} right The right argument.
  * @returns {BinaryOpNode}
  */
 export function gt(left, right) {
@@ -229,8 +232,8 @@ export function gt(left, right) {
 
 /**
  * Less-than or equal comparision (<=) operator.
- * @param {import('../types.js').ExprValue} left The left argument.
- * @param {import('../types.js').ExprValue} right The right argument.
+ * @param {ExprValue} left The left argument.
+ * @param {ExprValue} right The right argument.
  * @returns {BinaryOpNode}
  */
 export function lte(left, right) {
@@ -239,8 +242,8 @@ export function lte(left, right) {
 
 /**
  * Greater-than or equal comparision (>=) operator.
- * @param {import('../types.js').ExprValue} left The left argument.
- * @param {import('../types.js').ExprValue} right The right argument.
+ * @param {ExprValue} left The left argument.
+ * @param {ExprValue} right The right argument.
  * @returns {BinaryOpNode}
  */
 export function gte(left, right) {
@@ -249,8 +252,8 @@ export function gte(left, right) {
 
 /**
  * Null-inclusive non-equality (IS DISTINCT FROM) operator.
- * @param {import('../types.js').ExprValue} left The left argument.
- * @param {import('../types.js').ExprValue} right The right argument.
+ * @param {ExprValue} left The left argument.
+ * @param {ExprValue} right The right argument.
  * @returns {BinaryOpNode}
  */
 export function isDistinct(left, right) {
@@ -259,8 +262,8 @@ export function isDistinct(left, right) {
 
 /**
  * Null-inclusive equality (IS NOT DISTINCT FROM) operator.
- * @param {import('../types.js').ExprValue} left The left argument.
- * @param {import('../types.js').ExprValue} right The right argument.
+ * @param {ExprValue} left The left argument.
+ * @param {ExprValue} right The right argument.
  * @returns {BinaryOpNode}
  */
 export function isNotDistinct(left, right) {
@@ -269,8 +272,8 @@ export function isNotDistinct(left, right) {
 
 /**
  * Range inclusion (BETWEEN) operator.
- * @param {import('../types.js').ExprValue} expr The expression to test.
- * @param {import('../types.js').ExprValue[]} extent The range extent.
+ * @param {ExprValue} expr The expression to test.
+ * @param {ExprValue[]} extent The range extent.
  * @returns {BetweenOpNode}
  */
 export function isBetween(expr, extent) {
@@ -279,8 +282,8 @@ export function isBetween(expr, extent) {
 
 /**
  * Range exclusion (NOT BETWEEN) operator.
- * @param {import('../types.js').ExprValue} expr The expression to test.
- * @param {import('../types.js').ExprValue[]} extent The range extent.
+ * @param {ExprValue} expr The expression to test.
+ * @param {ExprValue[]} extent The range extent.
  * @returns {NotBetweenOpNode}
  */
 export function isNotBetween(expr, extent) {
@@ -289,8 +292,8 @@ export function isNotBetween(expr, extent) {
 
 /**
  * Set inclusion (IN) operator.
- * @param {import('../types.js').ExprValue} expr The expression to test.
- * @param {import('../types.js').ExprValue[]} values The included values.
+ * @param {ExprValue} expr The expression to test.
+ * @param {ExprValue[]} values The included values.
  * @returns {InOpNode}
  */
 export function isIn(expr, values) {

package/src/functions/order-by.js

@@ -1,9 +1,12 @@
+/**
+ * @import { ExprValue } from '../types.js'
+ */
 import { OrderByNode } from '../ast/order-by.js';
 import { asNode } from '../util/ast.js';
 
 /**
  * Indicate ascending sort order for an expression.
- * @param {import('../types.js').ExprValue} expr An expression to order by.
+ * @param {ExprValue} expr An expression to order by.
  * @param {boolean | undefined} [nullsFirst] Flag indicating if null values
  *  should be sorted first.
  * @returns {OrderByNode}
@@ -14,7 +17,7 @@ export function asc(expr, nullsFirst) {
 
 /**
  * Indicate descending sort order for an expression.
- * @param {import('../types.js').ExprValue} expr An expression to order by.
+ * @param {ExprValue} expr An expression to order by.
  * @param {boolean | undefined} [nullsFirst] Flag indicating if null values
  *  should be sorted first.
  * @returns {OrderByNode}

package/src/functions/spatial.js

@@ -1,9 +1,12 @@
-import { FunctionNode } from '../ast/function.js';
+/**
+ * @import { FunctionNode } from '../ast/function.js'
+ * @import { ExprValue } from '../types.js'
+ */
 import { fn } from '../util/function.js';
 
 /**
  * Function that converts geometry data to GeoJSON format.
- * @param {import('../types.js').ExprValue} expr The input expression.
+ * @param {ExprValue} expr The input expression.
  * @returns {FunctionNode}
  */
 export function geojson(expr) {
@@ -12,7 +15,7 @@ export function geojson(expr) {
 
 /**
  * Function that returns a spatial x position (using ST_X).
- * @param {import('../types.js').ExprValue} expr The input expression.
+ * @param {ExprValue} expr The input expression.
  * @returns {FunctionNode}
  */
 export function x(expr) {
@@ -21,7 +24,7 @@ export function x(expr) {
 
 /**
  * Function that returns a spatial y position (using ST_Y).
- * @param {import('../types.js').ExprValue} expr The input expression.
+ * @param {ExprValue} expr The input expression.
  * @returns {FunctionNode}
  */
 export function y(expr) {
@@ -30,7 +33,7 @@ export function y(expr) {
 
 /**
  * Function that returns the centroid point for geometry data.
- * @param {import('../types.js').ExprValue} expr The input expression.
+ * @param {ExprValue} expr The input expression.
  * @returns {FunctionNode}
  */
 export function centroid(expr) {
@@ -39,7 +42,7 @@ export function centroid(expr) {
 
 /**
  * Function that returns the centroid x-coordinate for geometry data.
- * @param {import('../types.js').ExprValue} expr The input expression.
+ * @param {ExprValue} expr The input expression.
  * @returns {FunctionNode}
  */
 export function centroidX(expr) {
@@ -48,7 +51,7 @@ export function centroidX(expr) {
 
 /**
  * Function that returns yhe centroid y-coordinate for geometry data.
- * @param {import('../types.js').ExprValue} expr The input expression.
+ * @param {ExprValue} expr The input expression.
  * @returns {FunctionNode}
  */
 export function centroidY(expr) {

package/src/functions/sql-template-tag.js

@@ -1,4 +1,7 @@
-/* eslint-disable jsdoc/no-undefined-types */
+/**
+ * @import { ExprNode } from '../ast/node.js'
+ * @import { ParamLike } from '../types.js'
+ */
 import { FragmentNode } from '../ast/fragment.js';
 import { isNode } from '../ast/node.js';
 import { ParamNode } from '../ast/param.js';
@@ -7,10 +10,7 @@ import { isParamLike, isString } from '../util/type-check.js';
 import { literal } from './literal.js';
 
 /**
- * @typedef {import('../ast/node.js').ExprNode
- *  | import('../types.js').ParamLike
- *  | string | number | boolean | Date
- * } TemplateValue
+ * @typedef { ExprNode | ParamLike | string | number | boolean | Date } TemplateValue
  */
 
 /**

package/src/functions/string.js

@@ -1,4 +1,7 @@
-import { FunctionNode } from '../ast/function.js';
+/**
+ * @import { FunctionNode } from '../ast/function.js'
+ * @import { ExprValue, StringValue } from '../types.js'
+ */
 import { asLiteral } from '../util/ast.js';
 import { argsList, fn } from '../util/function.js';
 
@@ -9,9 +12,9 @@ function strFn(name, expr, ...args) {
 /**
  * Function that returns true if a string contains a regexp pattern,
  * false otherwise.
- * @param {import('../types.js').ExprValue} string The string match against.
- * @param {import('../types.js').StringValue} pattern The regular expression pattern to match.
- * @param {import('../types.js').StringValue} [options] Regular expression options:
+ * @param {ExprValue} string The string match against.
+ * @param {StringValue} pattern The regular expression pattern to match.
+ * @param {StringValue} [options] Regular expression options:
  *  'c': case-sensitive matching
  *  'i': case-insensitive matching
  *  'l': match literals instead of regular expression tokens
@@ -26,8 +29,8 @@ export function regexp_matches(string, pattern, options) {
 
 /**
  * Function that returns true if search_string is found within string.
- * @param {import('../types.js').ExprValue} string The string to match against.
- * @param {import('../types.js').StringValue} search_string The substring to search for.
+ * @param {ExprValue} string The string to match against.
+ * @param {StringValue} search_string The substring to search for.
  * @returns {FunctionNode}
  */
 export function contains(string, search_string) {
@@ -36,8 +39,8 @@ export function contains(string, search_string) {
 
 /**
  * Function that returns true if string begins with search_string.
- * @param {import('../types.js').ExprValue} string The string to match against.
- * @param {import('../types.js').StringValue} search_string The substring to search for.
+ * @param {ExprValue} string The string to match against.
+ * @param {StringValue} search_string The substring to search for.
  * @returns {FunctionNode}
  */
 export function prefix(string, search_string) {
@@ -46,8 +49,8 @@ export function prefix(string, search_string) {
 
 /**
  * Function that returns true if string ends with search_string.
- * @param {import('../types.js').ExprValue} string The string to match against.
- * @param {import('../types.js').StringValue} search_string The substring to search for.
+ * @param {ExprValue} string The string to match against.
+ * @param {StringValue} search_string The substring to search for.
  * @returns {FunctionNode}
  */
 export function suffix(string, search_string) {
@@ -56,7 +59,7 @@ export function suffix(string, search_string) {
 
 /**
  * Function that converts string to lower case.
- * @param {import('../types.js').ExprValue} string The string to convert.
+ * @param {ExprValue} string The string to convert.
  * @returns {FunctionNode}
  */
 export function lower(string) {
@@ -65,7 +68,7 @@ export function lower(string) {
 
 /**
  * Function that converts string to upper case.
- * @param {import('../types.js').ExprValue} string The string to convert.
+ * @param {ExprValue} string The string to convert.
  * @returns {FunctionNode}
  */
 export function upper(string) {
@@ -74,7 +77,7 @@ export function upper(string) {
 
 /**
  * Function that returns the number of characters in string.
- * @param {import('../types.js').ExprValue} value The string to measure.
+ * @param {ExprValue} value The string to measure.
  * @returns {FunctionNode}
  */
 export function length(value) {

package/src/functions/util.js

@@ -0,0 +1,14 @@
+/**
+ * @import { FunctionNode } from '../ast/function.js'
+ * @import { ExprValue } from '../types.js'
+ */
+import { fn } from '../util/function.js';
+
+/**
+ * Returns the first non-null argument.
+ * @param {...ExprValue} expr The input expressions.
+ * @returns {FunctionNode}
+ */
+export function coalesce(...expr) {
+  return fn('coalesce', ...expr);
+}

package/src/functions/window.js

@@ -1,4 +1,7 @@
-import { WindowNode } from '../ast/window.js';
+/**
+ * @import { WindowNode } from '../ast/window.js'
+ * @import { ExprValue, NumberValue } from '../types.js'
+ */
 import { winFn } from '../util/function.js';
 
 /**
@@ -49,7 +52,7 @@ export function cume_dist() {
 /**
  * Create a window function that returns an integer ranging from 1 to the
  * argument value, dividing the partition as equally as possible.
- * @param {import('../types.js').NumberValue} num_buckets The number of
+ * @param {NumberValue} num_buckets The number of
  *  quantile buckets.
  * @returns {WindowNode}
  */
@@ -63,8 +66,8 @@ export function ntile(num_buckets) {
  * If there is no such row, instead return default (which must be of the same
  * type as the expression). Both offset and default are evaluated with respect
  * to the current row. If omitted, offset defaults to 1 and default to null.
- * @param {import('../types.js').ExprValue} expr The expression to evaluate.
- * @param {import('../types.js').NumberValue} [offset] The row offset
+ * @param {ExprValue} expr The expression to evaluate.
+ * @param {NumberValue} [offset] The row offset
  *  (default `1`).
  * @param {*} [defaultValue] The default value (default `null`).
  * @returns {WindowNode}
@@ -79,8 +82,8 @@ export function lag(expr, offset, defaultValue){
  * If there is no such row, instead return default (which must be of the same
  * type as the expression). Both offset and default are evaluated with respect
  * to the current row. If omitted, offset defaults to 1 and default to null.
- * @param {import('../types.js').ExprValue} expr The expression to evaluate.
- * @param {import('../types.js').NumberValue} [offset] The row offset
+ * @param {ExprValue} expr The expression to evaluate.
+ * @param {NumberValue} [offset] The row offset
  *  (default `1`).
  * @param {*} [defaultValue] The default value (default `null`).
  * @returns {WindowNode}
@@ -92,7 +95,7 @@ export function lead(expr, offset, defaultValue){
 /**
  * Create a window function that returns the expression evaluated at the row
  * that is the first row of the window frame.
- * @param {import('../types.js').ExprValue} expr The expression to evaluate.
+ * @param {ExprValue} expr The expression to evaluate.
  * @returns {WindowNode}
  */
 export function first_value(expr) {
@@ -102,7 +105,7 @@ export function first_value(expr) {
 /**
  * Create a window function that returns the expression evaluated at the row
  * that is the last row of the window frame.
- * @param {import('../types.js').ExprValue} expr The expression to evaluate.
+ * @param {ExprValue} expr The expression to evaluate.
  * @returns {WindowNode}
  */
 export function last_value(expr) {
@@ -112,8 +115,8 @@ export function last_value(expr) {
 /**
  * Create a window function that returns the expression evaluated at the
  * nth row of the window frame (counting from 1), or null if no such row.
- * @param {import('../types.js').ExprValue} expr The expression to evaluate.
- * @param {import('../types.js').NumberValue} nth The 1-based window frame index.
+ * @param {ExprValue} expr The expression to evaluate.
+ * @param {NumberValue} nth The 1-based window frame index.
  * @returns {WindowNode}
  */
 export function nth_value(expr, nth) {

package/src/index.js

@@ -37,6 +37,7 @@ export { asc, desc } from './functions/order-by.js';
 export { geojson, x, y, centroid, centroidX, centroidY } from './functions/spatial.js';
 export { sql } from './functions/sql-template-tag.js';
 export { regexp_matches, contains, prefix, suffix, lower, upper, length } from './functions/string.js';
+export { coalesce } from './functions/util.js';
 export { cume_dist, dense_rank, first_value, lag, last_value, lead, nth_value, ntile, percent_rank, rank, row_number } from './functions/window.js';
 
 export { rewrite } from './visit/rewrite.js';
@@ -49,6 +50,8 @@ export { loadCSV, loadJSON, loadObjects, loadParquet, loadSpatial } from './load
 
 export { bin1d } from './transforms/bin-1d.js';
 export { bin2d } from './transforms/bin-2d.js';
+export { binDate } from './transforms/bin-date.js';
+export { binHistogram } from './transforms/bin-histogram.js';
 export { binLinear1d } from './transforms/bin-linear-1d.js';
 export { binLinear2d } from './transforms/bin-linear-2d.js';
 export { lineDensity } from './transforms/line-density.js';

package/src/transforms/bin-1d.js

@@ -1,9 +1,12 @@
+/**
+ * @import { ExprValue } from '../types.js'
+ */
 import { float64 } from '../functions/cast.js';
 import { mul, sub } from '../functions/operators.js';
 
 /**
  * Compute binned values over a one-dimensional extent.
- * @param {import('../types.js').ExprValue} x The expression to bin.
+ * @param {ExprValue} x The expression to bin.
  *  The expression must return numeric values. For example, to bin
  *  datetime values, the input expression might map them to numeric
  *  values such as milliseconds since the epoch.

package/src/transforms/bin-2d.js

@@ -1,4 +1,7 @@
-import { SelectQuery } from '../ast/query.js';
+/**
+ * @import { SelectQuery } from '../ast/query.js'
+ * @import { ExprValue } from '../types.js'
+ */
 import { int32 } from '../functions/cast.js';
 import { floor } from '../functions/numeric.js';
 import { add, mul } from '../functions/operators.js';
@@ -11,9 +14,9 @@ import { add, mul } from '../functions/operators.js';
  * and uses a 2D integer bin index of the form (xbin + num_xbins * ybin).
  * @param {SelectQuery} q The input query. The FROM and WHERE clauses should
  *  be added to the query separately, either before or after this method.
- * @param {import('../types.js').ExprValue} xp The x bin expression.
- * @param {import('../types.js').ExprValue} yp The y bin expression.
- * @param {Record<string, import('../types.js').ExprValue>} aggs Named
+ * @param {ExprValue} xp The x bin expression.
+ * @param {ExprValue} yp The y bin expression.
+ * @param {Record<string, ExprValue>} aggs Named
  *  aggregate expressions over bins.
  * @param {number} xn The number of bins along the x dimension
  * @param {string[]} groupby Group by expressions.

package/src/transforms/bin-date.js

@@ -0,0 +1,37 @@
+/**
+ * @import { ExprNode } from '../ast/node.js'
+ * @import { ExprValue, TimeUnit } from '../types.js'
+ */
+import { dateBin, interval } from '../functions/datetime.js';
+import { add } from '../functions/operators.js';
+import { timeInterval } from './util/time-interval.js';
+
+/**
+ * @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, extent, options = {}) {
+  const { offset = 0 } = options;
+
+  // use interval if provided, otherwise determine from extent
+  const { unit, step = 1 } = options.interval
+    ? { unit: options.interval, step: options.step }
+    : timeInterval(extent[0], extent[1], options.steps || 40);
+  const bin = dateBin(field, unit, step);
+  return offset ? add(bin, interval(unit, offset * step)) : bin;
+}