df-script 1.5.0 → 1.7.0

package/dist/columnExpressions/ColumnExpr.d.ts

@@ -6,24 +6,31 @@ import { WindowExpr } from "./mixins/WindowExpr";
 import { StringExpr } from "./mixins/StringExpr";
 import { LogicalExpr } from "./mixins/LogicalExpr";
 import { TemporalExpr } from "./mixins/TemporalExpr";
-import { ListExpr } from "./mixins/ListExpr";
+import { ArrayExpr } from "./mixins/ArrayExpr";
 import { StructExpr } from "./mixins/StructExpr";
 import { ManipulationExpr } from "./mixins/ManipulationExpr";
 import { DataType } from "../datatypes";
 import type { IntoExpr, IExpr, DataFrameSchema, ColumnDict } from "../types";
 export declare class ColumnExpr<T> extends ExprBase {
-    colName: string;
-    colNames?: string[];
-    excludedCols: string[];
-    targetType?: any;
-    targetTypes?: any[];
+    _colName: string;
+    _colNames?: string[];
+    _excludedCols: string[];
+    _targetType?: any;
+    _targetTypes?: any[];
     static isColExpr(v: unknown): v is ColumnExpr<any>;
     static toColExpr(col: IntoExpr | IntoExpr[]): ColumnExpr<any>;
+    /**
+     * Creates a column expression representing a column or a raw expression value.
+     * @namespace $df.col
+     * @category ColumnExpression
+     * @syntax $df.col(<column_name>).{symbol}(...)
+     */
     constructor(colName: keyof T | string | (keyof T | string)[] | DataType | Function | (DataType | Function)[]);
 }
-export interface ColumnExpr<T> extends ArithmeticExpr, ComparisonExpr, AggregationExpr, WindowExpr, StringExpr, LogicalExpr, TemporalExpr, ListExpr, StructExpr, ManipulationExpr {
+export interface ColumnExpr<T> extends ArithmeticExpr, ComparisonExpr, AggregationExpr, WindowExpr, StringExpr, LogicalExpr, TemporalExpr, ArrayExpr, StructExpr, ManipulationExpr {
 }
 /**
+ * @internal
  * Resolves column selectors, expanding wildcards, datatypes, and arrays of columns/types
  * into concrete ColumnExpr instances.
  */

package/dist/columnExpressions/ExprBase.d.ts

@@ -1,21 +1,35 @@
 import type { IExpr, OpFn, AggFn, ColumnData, ColumnDict, RegisteredDataType } from "../types";
 export declare const derive: <T extends IExpr>(instance: T, nextOp?: OpFn) => T;
+/**
+ * @namespace $df.col
+ * @category ColumnExpression
+ * @syntax $df.col(<column_name>).{symbol}(...)
+ */
 export declare class ExprBase implements IExpr {
-    ops: OpFn[];
-    outputName: string;
-    isLiteral?: boolean;
-    literalValue?: any;
-    aggFn?: AggFn<any> | null;
-    groupingOpsIndex?: number;
-    partitionOpsIndex?: number;
-    partitionBy: (string | IExpr)[] | null;
-    evaluateWindow?: (groupPreValues: any[], partitionIndices: number[], currentIndex: number) => any;
+    _ops: OpFn[];
+    _outputName: string;
+    _isLiteral?: boolean;
+    _literalValue?: any;
+    _aggFn?: AggFn<any> | null;
+    _groupingOpsIndex?: number;
+    _partitionOpsIndex?: number;
+    _partitionBy: (string | IExpr)[] | null;
+    _evaluateWindow?: (groupPreValues: any[], partitionIndices: number[], currentIndex: number) => any;
+    _evaluatePost(opsIndex: number | undefined, aggregatedArray: any[], columns: ColumnDict): ColumnData;
+    _evaluatePre(opsIndex: number | undefined, columns: ColumnDict, height: number): ColumnData;
+    _getInitialValue(columns: ColumnDict, height: number): ColumnData;
     _resolve(val: any, columns: ColumnDict, height: number): any;
+    /**
+     * Renames the output expression column key.
+     */
     alias(name: string): this;
+    /**
+     * Coerces the column data type to another type.
+     */
     cast(dataType: RegisteredDataType): this;
+    /**
+     * Prints the current evaluation intermediate array to console for debugging.
+     */
     debug(label?: string): this;
-    private _getInitialValue;
     evaluate(columns: ColumnDict, height: number): ColumnData;
-    evaluatePre(opsIndex: number | undefined, columns: ColumnDict, height: number): ColumnData;
-    evaluatePost(opsIndex: number | undefined, aggregatedArray: any[], columns: ColumnDict): ColumnData;
 }

package/dist/columnExpressions/constants.d.ts

@@ -2,3 +2,4 @@ export declare const ALL_COLUMNS_MARKER = "*";
 export declare const LITERAL_MARKER = "*literal*";
 export declare const COALESCE_MARKER = "*coalesce*";
 export declare const ELEMENT_MARKER = "*element*";
+export declare const STRUCT_MARKER = "*struct*";

package/dist/columnExpressions/functions/all.d.ts

@@ -1,5 +1,28 @@
 import { ColumnExpr } from "../ColumnExpr";
 /**
  * Creates an expression targeting all columns in the DataFrame.
+ *
+ * @returns {ColumnExpr<any>} A column expression targeting all columns.
+ * @namespace $df
+ * @category ColumnExpression
+ * @syntax $df.{symbol}(...)
+ * @example
+ * >>> const df = $df.data({ a: [1, 2], b: [3, 4] })
+ * >>> df
+ * shape: (2, 2)
+ * ┌─────┬─────┐
+ * │ a   │ b   │
+ * ├─────┼─────┤
+ * │ 1   │ 3   │
+ * │ 2   │ 4   │
+ * └─────┴─────┘
+ * >>> df.select($df.all())
+ * shape: (2, 2)
+ * ┌─────┬─────┐
+ * │ a   │ b   │
+ * ├─────┼─────┤
+ * │ 1   │ 3   │
+ * │ 2   │ 4   │
+ * └─────┴─────┘
  */
 export declare function all(): ColumnExpr<any>;

package/dist/columnExpressions/functions/coalesce.d.ts

@@ -1,3 +1,32 @@
 import { ColumnExpr } from "../ColumnExpr";
-import type { IExpr, Scalar } from "../../types";
-export declare function coalesce(...exprs: (IExpr | Scalar | (IExpr | Scalar)[])[]): ColumnExpr<any>;
+import type { IExpr, ValidScalarTypes } from "../../types";
+/**
+ * Returns the first non-null value among the specified expressions.
+ *
+ * @param {...(IExpr | ValidScalarTypes | (IExpr | ValidScalarTypes)[])[]} exprs The list of expressions or columns to coalesce.
+ * @returns {ColumnExpr<any>} A column expression resolving to the first non-null value.
+ * @namespace $df
+ * @category ColumnExpression
+ * @syntax $df.{symbol}(...)
+ * @example
+ * >>> const df = $df.data({ a: [1, null, null], b: [null, 2, null] })
+ * >>> df
+ * shape: (3, 2)
+ * ┌──────┬──────┐
+ * │ a    │ b    │
+ * ├──────┼──────┤
+ * │ 1    │ null │
+ * │ null │ 2    │
+ * │ null │ null │
+ * └──────┴──────┘
+ * >>> df.select($df.coalesce($df.col("a"), $df.col("b"), $df.lit(3)).alias("coalesced"))
+ * shape: (3, 1)
+ * ┌───────────┐
+ * │ coalesced │
+ * ├───────────┤
+ * │ 1         │
+ * │ 2         │
+ * │ 3         │
+ * └───────────┘
+ */
+export declare function coalesce(...exprs: (IExpr | ValidScalarTypes | (IExpr | ValidScalarTypes)[])[]): ColumnExpr<any>;

package/dist/columnExpressions/functions/element.d.ts

@@ -1,5 +1,30 @@
 import { ColumnExpr } from "../ColumnExpr";
 /**
- * Creates an expression referencing the current element(s) of a list during evaluation.
+ * Creates an expression referencing the current element(s) of an array during evaluation.
+ * Primarily used inside array operations like `filter`, `map`, or `eval`.
+ *
+ * @template T The type of the element.
+ * @returns {ColumnExpr<T>} A column expression referencing the array element.
+ * @namespace $df
+ * @category ColumnExpression
+ * @syntax $df.{symbol}(...)
+ * @example
+ * >>> const df = $df.data({ a: [[1, 5, 10], [2, 8]] })
+ * >>> df
+ * shape: (2, 1)
+ * ┌────────────┐
+ * │ a          │
+ * ├────────────┤
+ * │ [1, 5, 10] │
+ * │ [2, 8]     │
+ * └────────────┘
+ * >>> df.select($df.col("a").arr.filter($df.element().gt(5)).alias("filtered"))
+ * shape: (2, 1)
+ * ┌──────────┐
+ * │ filtered │
+ * ├──────────┤
+ * │ [10]     │
+ * │ [8]      │
+ * └──────────┘
  */
 export declare function element<T = any>(): ColumnExpr<T>;

package/dist/columnExpressions/functions/exclude.d.ts

@@ -1,5 +1,29 @@
 import { ColumnExpr } from "../ColumnExpr";
 /**
  * Creates an expression targeting all columns except the specified ones.
+ *
+ * @param {string | string[]} columns The name or names of columns to exclude.
+ * @returns {ColumnExpr<any>} A column expression targeting all columns except the specified ones.
+ * @namespace $df
+ * @category ColumnExpression
+ * @syntax $df.{symbol}(...)
+ * @example
+ * >>> const df = $df.data({ id: [101, 102], val: [10, 20] })
+ * >>> df
+ * shape: (2, 2)
+ * ┌─────┬─────┐
+ * │ id  │ val │
+ * ├─────┼─────┤
+ * │ 101 │ 10  │
+ * │ 102 │ 20  │
+ * └─────┴─────┘
+ * >>> df.select($df.exclude("id"))
+ * shape: (2, 1)
+ * ┌─────┐
+ * │ val │
+ * ├─────┤
+ * │ 10  │
+ * │ 20  │
+ * └─────┘
  */
 export declare function exclude(columns: string | string[]): ColumnExpr<any>;

package/dist/columnExpressions/functions/implode.d.ts

@@ -1,3 +1,31 @@
 import { ColumnExpr } from "../ColumnExpr";
 import type { IntoExpr } from "../../types";
+/**
+ * Aggregates values of a column into a list within each group.
+ *
+ * @param {IntoExpr | IntoExpr[]} column The column or expression to implode.
+ * @returns {ColumnExpr<any>} A column expression representing the list of values.
+ * @namespace $df
+ * @category ColumnExpression
+ * @syntax $df.{symbol}(...)
+ * @example
+ * >>> const df = $df.data({ group: ["A", "A", "B"], val: [1, 2, 3] })
+ * >>> df
+ * shape: (3, 2)
+ * ┌───────┬─────┐
+ * │ group │ val │
+ * ├───────┼─────┤
+ * │ A     │ 1   │
+ * │ A     │ 2   │
+ * │ B     │ 3   │
+ * └───────┴─────┘
+ * >>> df.group_by("group").agg($df.implode("val").alias("imploded"))
+ * shape: (2, 2)
+ * ┌───────┬──────────┐
+ * │ group │ imploded │
+ * ├───────┼──────────┤
+ * │ A     │ [1, 2]   │
+ * │ B     │ [3]      │
+ * └───────┴──────────┘
+ */
 export declare function implode(column: IntoExpr | IntoExpr[]): ColumnExpr<any>;

package/dist/columnExpressions/functions/lit.d.ts

@@ -3,5 +3,32 @@ import type { SeqRangeOptions } from "./seq_range";
 export type LitOptions = Pick<SeqRangeOptions, "dtype" | "name">;
 /**
  * Creates a literal column expression that repeats the given value for all rows.
+ *
+ * @param value The literal value (number, string, boolean, etc.).
+ * @param [options] Configuration options.
+ * @param [options.dtype] The data type to allocate for the literal values.
+ * @param [options.name] The name of the output column.
+ * @returns {ColumnExpr<any>} A column expression with the literal value.
+ * @namespace $df
+ * @category ColumnExpression
+ * @syntax $df.{symbol}(...)
+ * @example
+ * >>> const df = $df.data({ a: [1, 2] })
+ * >>> df
+ * shape: (2, 1)
+ * ┌───┐
+ * │ a │
+ * ├───┤
+ * │ 1 │
+ * │ 2 │
+ * └───┘
+ * >>> df.select($df.lit(42).alias("answer"))
+ * shape: (2, 1)
+ * ┌────────┐
+ * │ answer │
+ * ├────────┤
+ * │ 42     │
+ * │ 42     │
+ * └────────┘
  */
 export declare function lit(value: any, options?: LitOptions): ColumnExpr<any>;

package/dist/columnExpressions/functions/seq_range.d.ts

@@ -27,5 +27,41 @@ export type SeqRangeOptions = {
  * Creates a column expression that generates a range of values.
  * If mode is "cumulative" (default) or "independent", it generates a sequence.
  * If mode is "constant", it repeats the given value.
+ *
+ * @param value The initial value to start the sequence or the constant value to repeat.
+ * @param [options] Configuration options.
+ * @param [options.n] The number of values to generate. Defaults to the slice/DataFrame height.
+ * @param [options.dtype] The registered data type to coerce/allocate for the generated sequence.
+ * @param [options.name] The name of the output column.
+ * @param [options.mode] The sequence generation mode ("constant", "cumulative", or "independent").
+ * @param [options.step] The step value or function to compute the step at each row.
+ * @param [options.strict] If true, throws an error if the generated sequence height does not match the target height.
+ * @param [options.pad] In non-strict mode, pads the sequence with `padValue` if it is shorter than target range.
+ * @param [options.truncate] In non-strict mode, truncates the sequence if it exceeds target range.
+ * @param [options.padValue] The value to use for padding in non-strict mode.
+ * @param [options.startIndex] The starting index in the DataFrame to insert the sequence.
+ * @param [options.endIndex] The ending index in the DataFrame to insert the sequence.
+ * @returns {ColumnExpr<any>} A column expression generating the sequence.
+ * @namespace $df
+ * @category ColumnExpression
+ * @syntax $df.{symbol}(...)
+ * @example
+ * >>> const df = $df.data({ a: [10, 20] })
+ * >>> df
+ * shape: (2, 1)
+ * ┌────┐
+ * │ a  │
+ * ├────┤
+ * │ 10 │
+ * │ 20 │
+ * └────┘
+ * >>> df.select($df.seq_range(1, { step: 2 }).alias("odd"))
+ * shape: (2, 1)
+ * ┌─────┐
+ * │ odd │
+ * ├─────┤
+ * │ 1   │
+ * │ 3   │
+ * └─────┘
  */
 export declare function seq_range(value: any, options?: SeqRangeOptions): ColumnExpr<any>;

package/dist/columnExpressions/functions/struct.d.ts

@@ -0,0 +1,31 @@
+import { ColumnExpr } from "../ColumnExpr";
+import type { IntoExpr } from "../../types";
+/**
+ * Packages multiple expressions into a structured object column.
+ *
+ * @param {IntoExpr[] | Record<string, IntoExpr> | IntoExpr} fields An array of expressions, a record of field names to expressions, or a single expression.
+ * @param {...IntoExpr[]} moreFields Additional fields when a single expression is passed as the first parameter.
+ * @returns {ColumnExpr<any>} A column expression packaging the specified fields.
+ * @namespace $df
+ * @category ColumnExpression
+ * @syntax $df.{symbol}(...)
+ * @example
+ * >>> const df = $df.data({ a: [1, 2], b: ["x", "y"] })
+ * >>> df
+ * shape: (2, 2)
+ * ┌─────┬─────┐
+ * │ a   │ b   │
+ * ├─────┼─────┤
+ * │ 1   │ x   │
+ * │ 2   │ y   │
+ * └─────┴─────┘
+ * >>> df.select($df.struct({ x: "a", y: "b" }).alias("coord"))
+ * shape: (2, 1)
+ * ┌──────────────────┐
+ * │ coord            │
+ * ├──────────────────┤
+ * │ { x: 1, y: "x" } │
+ * │ { x: 2, y: "y" } │
+ * └──────────────────┘
+ */
+export declare function struct(fields: IntoExpr[] | Record<string, IntoExpr> | IntoExpr, ...moreFields: IntoExpr[]): ColumnExpr<any>;

package/dist/columnExpressions/functions/when.d.ts

@@ -1,24 +1,54 @@
 import { ColumnExpr } from "../ColumnExpr";
-import type { IExpr, Scalar } from "../../types";
-type WhenArg = IExpr | Scalar;
+import type { IExpr, ValidScalarTypes } from "../../types";
+type WhenArg = IExpr | ValidScalarTypes;
 export declare class WhenThenChain {
-    private predicates;
-    private values;
+    private _predicates;
+    private _values;
     constructor(predicates: WhenArg[], values: WhenArg[]);
     then(value: WhenArg): WhenThen;
 }
 export declare class When {
-    private predicates;
+    private _predicates;
     constructor(predicate: WhenArg);
     then(value: WhenArg): WhenThen;
 }
 export declare class WhenThen extends ColumnExpr<any> {
-    private predicates;
-    private values;
-    private otherwiseValue;
+    private _predicates;
+    private _values;
+    private _otherwiseValue;
     constructor(predicates: WhenArg[] | string, values?: WhenArg[], otherwiseValue?: WhenArg);
     when(predicate: WhenArg): WhenThenChain;
     otherwise(value: WhenArg): ColumnExpr<any>;
 }
+/**
+ * Provides conditional branch evaluations inside column expressions.
+ *
+ * @param {WhenArg} predicate The boolean condition or expression.
+ * @returns {When} A When object builder to chain `.then()` and `.otherwise()`/`.when()`.
+ * @namespace $df
+ * @category ColumnExpression
+ * @syntax $df.{symbol}(...)
+ * @example
+ * >>> const df = $df.data({ score: [75, 95] })
+ * >>> df
+ * shape: (2, 1)
+ * ┌───────┐
+ * │ score │
+ * ├───────┤
+ * │ 75    │
+ * │ 95    │
+ * └───────┘
+ * >>> df.select(
+ * ...   $df.when($df.col("score").gt(90)).then("A")
+ * ...     .otherwise("B").alias("grade")
+ * ... )
+ * shape: (2, 1)
+ * ┌───────┐
+ * │ grade │
+ * ├───────┤
+ * │ B     │
+ * │ A     │
+ * └───────┘
+ */
 export declare function when(predicate: WhenArg): When;
 export {};

package/dist/columnExpressions/index.d.ts

@@ -8,7 +8,7 @@ export * from "./mixins/StringExpr";
 export * from "./mixins/AggregationExpr";
 export * from "./mixins/WindowExpr";
 export * from "./mixins/TemporalExpr";
-export * from "./mixins/ListExpr";
+export * from "./mixins/ArrayExpr";
 export * from "./mixins/StructExpr";
 export * from "./ColumnExpr";
 export * from "./functions/lit";
@@ -19,4 +19,5 @@ export * from "./functions/when";
 export * from "./functions/implode";
 export * from "./functions/seq_range";
 export * from "./functions/element";
+export * from "./functions/struct";
 export * from "./utils";