df-script 1.6.0 → 1.8.0

package/dist/columnExpressions/mixins/WindowExpr.d.ts

@@ -1,28 +1,339 @@
 import type { IExpr } from "../../types";
 import { ExprBase } from "../ExprBase";
+/**
+ * @namespace $df.col
+ * @category ColumnExpression
+ * @syntax $df.col(<column_name>).{symbol}(...)
+ */
 export declare class WindowExpr extends ExprBase {
-    partitionBy: (string | IExpr)[] | null;
+    _partitionBy: (string | IExpr)[] | null;
     _window(evaluateWindow: (this: IExpr, groupPreValues: any[], partitionIndices: number[], currentIndex: number) => any): this;
     _rolling(windowSize: number, aggFn: (vals: any[]) => any): this;
     _cum(reverse: boolean, initialVal: any, stepFn: (acc: any, val: any) => any, postFn?: (acc: any, hasValid: boolean) => any): this;
-    get isWindow(): boolean;
+    get _isWindow(): boolean;
+    /**
+     * Window: Computes cumulative count.
+     * @param reverse Flag indicating whether to compute from reverse direction.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ val: [10, 20, 30] })
+     * >>> df.with_columns($df.col("val").cum_count().alias("c_count"))
+     * shape: (3, 2)
+     * ┌─────┬─────────┐
+     * │ val │ c_count │
+     * ├─────┼─────────┤
+     * │ 10  │ 1       │
+     * │ 20  │ 2       │
+     * │ 30  │ 3       │
+     * └─────┴─────────┘
+     */
     cum_count(reverse?: boolean): this;
+    /**
+     * Window: Computes cumulative maximum value.
+     * @param reverse Flag indicating whether to compute in reverse direction.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ val: [1, 3, 2] })
+     * >>> df.with_columns($df.col("val").cum_max().alias("c_max"))
+     * shape: (3, 2)
+     * ┌─────┬───────┐
+     * │ val │ c_max │
+     * ├─────┼───────┤
+     * │ 1   │ 1     │
+     * │ 3   │ 3     │
+     * │ 2   │ 3     │
+     * └─────┴───────┘
+     */
     cum_max(reverse?: boolean): this;
+    /**
+     * Window: Computes cumulative minimum value.
+     * @param reverse Flag indicating whether to compute in reverse direction.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ val: [3, 1, 2] })
+     * >>> df.with_columns($df.col("val").cum_min().alias("c_min"))
+     * shape: (3, 2)
+     * ┌─────┬───────┐
+     * │ val │ c_min │
+     * ├─────┼───────┤
+     * │ 3   │ 3     │
+     * │ 1   │ 1     │
+     * │ 2   │ 1     │
+     * └─────┴───────┘
+     */
     cum_min(reverse?: boolean): this;
+    /**
+     * Window: Computes cumulative product of values.
+     * @param reverse Flag indicating whether to compute in reverse direction.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ val: [1, 2, 3, 4] })
+     * >>> df.with_columns($df.col("val").cum_prod().alias("c_prod"))
+     * shape: (4, 2)
+     * ┌─────┬────────┐
+     * │ val │ c_prod │
+     * ├─────┼────────┤
+     * │ 1   │ 1      │
+     * │ 2   │ 2      │
+     * │ 3   │ 6      │
+     * │ 4   │ 24     │
+     * └─────┴────────┘
+     */
     cum_prod(reverse?: boolean): this;
+    /**
+     * Window: Computes cumulative sum of values.
+     * @param reverse Flag indicating whether to compute in reverse direction.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ val: [10, 20, 30] })
+     * >>> df.with_columns($df.col("val").cum_sum().alias("c_sum"))
+     * shape: (3, 2)
+     * ┌─────┬───────┐
+     * │ val │ c_sum │
+     * ├─────┼───────┤
+     * │ 10  │ 10    │
+     * │ 20  │ 30    │
+     * │ 30  │ 60    │
+     * └─────┴───────┘
+     */
     cum_sum(reverse?: boolean): this;
+    /**
+     * Window: Computes dense rank (ranks without gaps) within group partition.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ score: [100, 100, 90] })
+     * >>> df.with_columns($df.col("score").dense_rank().alias("dr"))
+     * shape: (3, 2)
+     * ┌───────┬────┐
+     * │ score │ dr │
+     * ├───────┼────┤
+     * │ 100   │ 2  │
+     * │ 100   │ 2  │
+     * │ 90    │ 1  │
+     * └───────┴────┘
+     */
     dense_rank(): this;
+    /**
+     * Window: Shifts values down by offset, filling missing slots with default value.
+     * @param offset Number of rows to shift down (default 1).
+     * @param defaultVal Fallback fill value for empty slots (default null).
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ val: [10, 20, 30] })
+     * >>> df.with_columns($df.col("val").lag(1, 0).alias("prev"))
+     * shape: (3, 2)
+     * ┌─────┬──────┐
+     * │ val │ prev │
+     * ├─────┼──────┤
+     * │ 10  │ 0    │
+     * │ 20  │ 10   │
+     * │ 30  │ 20   │
+     * └─────┴──────┘
+     */
     lag(offset?: number, defaultVal?: any): this;
+    /**
+     * Window: Shifts values up by offset, filling missing slots with default value.
+     * @param offset Number of rows to shift up (default 1).
+     * @param defaultVal Fallback fill value for empty slots (default null).
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ val: [10, 20, 30] })
+     * >>> df.with_columns($df.col("val").lead(1, 0).alias("next"))
+     * shape: (3, 2)
+     * ┌─────┬──────┐
+     * │ val │ next │
+     * ├─────┼──────┤
+     * │ 10  │ 20   │
+     * │ 20  │ 30   │
+     * │ 30  │ 0    │
+     * └─────┴──────┘
+     */
     lead(offset?: number, defaultVal?: any): this;
+    /**
+     * Executes a window aggregation partitioned by column keys.
+     * @param columns Column expression or array of columns to partition by.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ cat: ["A", "A", "B"], val: [10, 20, 30] })
+     * >>> df.with_columns($df.col("val").sum().over("cat").alias("cat_sum"))
+     * shape: (3, 3)
+     * ┌─────┬─────┬─────────┐
+     * │ cat │ val │ cat_sum │
+     * ├─────┼─────┼─────────┤
+     * │ A   │ 10  │ 30      │
+     * │ A   │ 20  │ 30      │
+     * │ B   │ 30  │ 30      │
+     * └─────┴─────┴─────────┘
+     */
     over(columns: string | IExpr | (string | IExpr)[]): this;
+    /**
+     * Window: Computes rank within group partition.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ score: [100, 80, 90] })
+     * >>> df.with_columns($df.col("score").rank().alias("rank"))
+     * shape: (3, 2)
+     * ┌───────┬──────┐
+     * │ score │ rank │
+     * ├───────┼──────┤
+     * │ 100   │ 3    │
+     * │ 80    │ 1    │
+     * │ 90    │ 2    │
+     * └───────┴──────┘
+     */
     rank(): this;
+    /**
+     * Window: Computes rolling window maximum value.
+     * @param windowSize Size of rolling window.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ val: [1, 5, 2, 8] })
+     * >>> df.with_columns($df.col("val").rolling_max(2).alias("r_max"))
+     * shape: (4, 2)
+     * ┌─────┬───────┐
+     * │ val │ r_max │
+     * ├─────┼───────┤
+     * │ 1   │ 1     │
+     * │ 5   │ 5     │
+     * │ 2   │ 5     │
+     * │ 8   │ 8     │
+     * └─────┴───────┘
+     */
     rolling_max(windowSize: number): this;
+    /**
+     * Window: Computes rolling window mean average.
+     * @param windowSize Size of rolling window.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ val: [10, 20, 30] })
+     * >>> df.with_columns($df.col("val").rolling_mean(2).alias("r_mean"))
+     * shape: (3, 2)
+     * ┌─────┬────────┐
+     * │ val │ r_mean │
+     * ├─────┼────────┤
+     * │ 10  │ 10     │
+     * │ 20  │ 15     │
+     * │ 30  │ 25     │
+     * └─────┴────────┘
+     */
     rolling_mean(windowSize: number): this;
+    /**
+     * Window: Computes rolling window median value.
+     * @param windowSize Size of rolling window.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ val: [10, 30, 20] })
+     * >>> df.with_columns($df.col("val").rolling_median(2).alias("r_med"))
+     * shape: (3, 2)
+     * ┌─────┬───────┐
+     * │ val │ r_med │
+     * ├─────┼───────┤
+     * │ 10  │ 10    │
+     * │ 30  │ 20    │
+     * │ 20  │ 25    │
+     * └─────┴───────┘
+     */
     rolling_median(windowSize: number): this;
+    /**
+     * Window: Computes rolling window minimum value.
+     * @param windowSize Size of rolling window.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ val: [10, 5, 20] })
+     * >>> df.with_columns($df.col("val").rolling_min(2).alias("r_min"))
+     * shape: (3, 2)
+     * ┌─────┬───────┐
+     * │ val │ r_min │
+     * ├─────┼───────┤
+     * │ 10  │ 10    │
+     * │ 5   │ 5     │
+     * │ 20  │ 5     │
+     * └─────┴───────┘
+     */
     rolling_min(windowSize: number): this;
+    /**
+     * Window: Computes rolling window quantile value.
+     * @param quantile Quantile boundary between 0.0 and 1.0.
+     * @param windowSize Size of rolling window.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ val: [10, 20, 30] })
+     * >>> df.with_columns($df.col("val").rolling_quantile(0.5, 2).alias("r_quant"))
+     * shape: (3, 2)
+     * ┌─────┬─────────┐
+     * │ val │ r_quant │
+     * ├─────┼─────────┤
+     * │ 10  │ 10      │
+     * │ 20  │ 15      │
+     * │ 30  │ 25      │
+     * └─────┴─────────┘
+     */
     rolling_quantile(quantile: number, windowSize: number): this;
+    /**
+     * Window: Computes rolling window rank.
+     * @param windowSize Size of rolling window.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ val: [10, 20, 15] })
+     * >>> df.with_columns($df.col("val").rolling_rank(2).alias("r_rank"))
+     * shape: (3, 2)
+     * ┌─────┬────────┐
+     * │ val │ r_rank │
+     * ├─────┼────────┤
+     * │ 10  │ 1      │
+     * │ 20  │ 2      │
+     * │ 15  │ 1      │
+     * └─────┴────────┘
+     */
     rolling_rank(windowSize: number): this;
+    /**
+     * Window: Computes rolling window standard deviation.
+     * @param windowSize Size of rolling window.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ val: [10, 20, 30] })
+     * >>> df.with_columns($df.col("val").rolling_std(2).alias("r_std"))
+     * shape: (3, 2)
+     * ┌─────┬────────┐
+     * │ val │ r_std  │
+     * ├─────┼────────┤
+     * │ 10  │ 0      │
+     * │ 20  │ 7.071  │
+     * │ 30  │ 7.071  │
+     * └─────┴────────┘
+     */
     rolling_std(windowSize: number): this;
+    /**
+     * Window: Computes rolling window sum.
+     * @param windowSize Size of rolling window.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ val: [10, 20, 30] })
+     * >>> df.with_columns($df.col("val").rolling_sum(2).alias("r_sum"))
+     * shape: (3, 2)
+     * ┌─────┬───────┐
+     * │ val │ r_sum │
+     * ├─────┼───────┤
+     * │ 10  │ 10    │
+     * │ 20  │ 30    │
+     * │ 30  │ 50    │
+     * └─────┴───────┘
+     */
     rolling_sum(windowSize: number): this;
+    /**
+     * Window: Computes 1-indexed row number count within group partitions.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ cat: ["A", "A", "B"] })
+     * >>> df.with_columns($df.col("cat").row_number().over("cat").alias("rn"))
+     * shape: (3, 2)
+     * ┌─────┬────┐
+     * │ cat │ rn │
+     * ├─────┼────┤
+     * │ A   │ 1  │
+     * │ A   │ 2  │
+     * │ B   │ 1  │
+     * └─────┴────┘
+     */
     row_number(): this;
 }

package/dist/columnExpressions/types.d.ts

@@ -1,3 +1,4 @@
+/** @typefile */
 import type { IExpr } from "../types";
 export type ExprConstructor = new (...args: any[]) => IExpr;
 export interface RandomOptions {

package/dist/columnExpressions/utils.d.ts

@@ -1,4 +1,14 @@
 import type { IExpr, ColumnData, ColumnDict } from "../types";
+/**
+ * Normalizes a single unary value (coercing Date instances to getTime if valid)
+ * and executes the operation callback.
+ */
+export declare function evalUnaryOp(v: any, fn: (a: any) => any): any;
+/**
+ * Normalizes binary values (coercing Date instances to getTime if valid)
+ * and executes the operation callback.
+ */
+export declare function evalBinaryOp(v: any, r: any, fn: (a: any, b: any) => any): any;
 export declare const kleeneUnary: (fn: (v: any) => any) => (vArray: ColumnData) => any[];
 export declare const kleeneBinary: (expr: IExpr, other: any, fn: (v: any, r: any) => any) => (vArray: ColumnData, columns: ColumnDict) => any[];
 export declare function evaluateExpression(expr: IExpr, columns: ColumnDict, height: number): ColumnData;

package/dist/constants.d.ts

@@ -1,11 +1,23 @@
 export declare const NEWLINE = "\n";
 export declare const CARRIAGE_RETURN = "\r";
 export declare const UTF8_BOM = "\uFEFF";
-export declare const MS_PER_SECOND = 1000;
-export declare const MS_PER_MINUTE = 60000;
-export declare const MS_PER_HOUR = 3600000;
+export declare const MS_PER_WEEK = 604800000;
 export declare const MS_PER_DAY = 86400000;
+export declare const MS_PER_HOUR = 3600000;
+export declare const MS_PER_MINUTE = 60000;
+export declare const MS_PER_SECOND = 1000;
+export declare const MS_PER_MILLISECOND = 1;
+export declare const MS_PER_MICROSECOND = 0.001;
+export declare const MS_PER_NANOSECOND = 0.000001;
 export declare const US_PER_MS = 1000;
 export declare const NS_PER_MS = 1000000;
 export declare const US_PER_MS_BI = 1000n;
 export declare const NS_PER_MS_BI = 1000000n;
+/** Separates composite key segments within a single row hash (e.g. multi-column join keys). */
+export declare const KEY_SEPARATOR = "\0";
+/** Separates key-value pairs within a serialized object or map canonical hash. */
+export declare const KEY_PAIR_SEPARATOR = "\u0001";
+/** Sentinel value used in join left-index arrays to indicate a right-only (unmatched) row. */
+export declare const UNMATCHED_ROW_INDEX = -1;
+/** Maximum allowable length for a single JavaScript array (2^32 - 1). */
+export declare const MAX_JS_ARRAY_LENGTH = 4294967295;