df-script 1.8.0 → 1.9.0

package/README.md

@@ -142,6 +142,8 @@ DFScript uses the `$df` namespace to bootstrap DataFrames, refer to columns, bui
 - `$df.exclude(columns)`: Creates an expression matching all columns except the specified ones.
 - `$df.coalesce(...exprs)`: Returns the first non-null value among columns or literal expressions.
 - `$df.lit(val)`: Explicitly wraps a raw value into a literal expression.
+- `$df.duration(options)`: Constructs a `Duration` expression supporting days, hours, minutes, seconds, milliseconds, weeks, and timeUnit precision.
+- `$df.struct(fields)`: Constructs a nested `Struct` object column expression from an object of named expressions or sibling columns.
 - `$df.when(predicate).then(value)...otherwise(value)`: Constructs a conditional expression (when-then-otherwise chain).
 - `$df.implode(column)`: Aggregates a column's rows (or grouped values) into a list.
 - `$df.seq_range(value, options?)`: Generates a sequence range of values.
@@ -158,28 +160,38 @@ DFScript uses the `$df` namespace to bootstrap DataFrames, refer to columns, bui
 ## 🛠️ DataFrame API Reference
 
 ### 1. Transformations & Projection
-- **`select(...exprs)`**: Projects columns. Supports strings, raw column names, `$df.col(...)` expressions, and `$df.all()`.
+- **`select(...exprs)`**: Projects columns. Supports strings, raw column names, `$df.col(...)` expressions, `$df.all()`, and `$df.col("struct").struct.unnest()`.
 - **`with_columns(...exprs)`**: Adds or overrides columns. Accepts expressions, strings, or options objects mapping keys to values/expressions.
 - **`drop(...names)`**: Drops one or more columns from the DataFrame.
 - **`rename(mapping)`**: Renames columns using a `{ oldName: newName }` object.
+- **`explode(columns)`**: Unnests list-like columns into multiple rows, replicating other columns per list element.
+- **`implode(columns)`**: Groups values in specified columns back into a single list element per column.
 
 ### 2. Filtering & Row Selection
 - **`filter(...predicates)`**: Filters rows where all predicate expressions evaluate to `true` (or non-null truthy values).
+- **`find(predicate)`**: Evaluates a predicate expression and returns the first matching row record object (or `undefined` if no match is found).
 - **`unique(columns?)`**: Returns unique rows. If a subset of columns is provided, deduplicates based on those columns.
 - **`limit(n, options?)`**: Returns the first `n` rows. Options include `offset` and direction `from: "start" | "end"`.
 - **`head(n)`** / **`tail(n)`**: Shortcuts for `limit` from the start or end of the DataFrame.
 - **`slice(start, end?)`**: Extract a subset of rows using standard index slicing.
-- **`gather(indices, options?)`**: Gathers rows at specified indices. Supports single index, arrays of indices, and negative indexing. Options include `{ null_on_oob?: boolean }` (default: `false` which throws an error on out-of-bounds indices; if `true`, out-of-bounds indices result in `null` values).
+- **`gather(indices, options?)`**: Gathers rows at specified indices. Supports single index, arrays of indices, and negative indexing. Options include `{ null_on_oob?: boolean }`.
 
-### 3. Sorting
+### 3. Sorting & Structural Operations
 - **`sort({ by, descending?, nullsLast?, custom? })`**: Sorts rows. Supports single or multiple columns/expressions, custom descending configurations per column, custom null sorting rules, and custom comparator functions.
+- **`clone()`**: Performs a complete deep copy of the `DataFrame`, replicating all underlying column arrays and schema metadata.
 
 ### 4. Grouping & Aggregations
 - **`groupby(keys)`**: Groups the data by one or more columns, returning a `GroupedData` object.
 - **`GroupedData.agg(...exprs)`**: Run aggregations on grouped data (e.g. `$df.col("sales").sum()`).
 
 ### 5. Reshaping & Joining
-- **`join(other, on, how, suffixes?)`**: Merges two DataFrames on join keys. Supported join types: `"inner" | "left" | "right" | "outer"`.
+- **`join(other, onOrOptions, how?, suffixes?)`**: Merges two DataFrames. Supports:
+  - Join modes (`how`): `"inner" | "left" | "right" | "outer" | "semi" | "anti" | "cross"`.
+  - Heterogeneous key names (`leftOn`, `rightOn`).
+  - Key coalescing (`coalesce: boolean`).
+  - Row order preservation (`maintain_order: "none" | "left" | "right" | "left_right" | "right_left"`).
+- **`join_asof(other, options)`**: Performs inexact time-series or nearest-neighbor joins on sorted key columns.
+  - Parameters: `on`, `leftOn`, `rightOn`, grouping parameters (`by`, `leftBy`, `rightBy`), matching `strategy` (`"backward" | "forward" | "nearest"`), numeric/duration `tolerance`, and `allow_exact_matches`.
 - **`pivot(index, columns, values)`**: Pivots the table, converting unique values in `columns` into column headers.
 - **`unpivot(idVars, valueVars, varName?, valueName?)`**: Melts/unpivots the table, converting wide columns into long format name-value pairs.
 - **`concat(items, options?)`**: Concatenates multiple DataFrames. Supported concat strategies: `"vertical" | "horizontal" | "diagonal"`.
@@ -250,10 +262,13 @@ Chained mathematical functions execute cleanly with built-in null-safety (Kleene
 - `.is_in(arrayOrExpr)`, `.not_in(arrayOrExpr)`
 
 ### ⚡ Aggregations
-- `.sum()`, `.avg()` / `.mean()`, `.median()`, `.mode()`, `.std()`, `.min()`, `.max()`
+- `.sum()`, `.product()`, `.avg()` / `.mean()`, `.median()`, `.mode()`, `.variance()`, `.std()`, `.skew()`, `.kurtosis()`, `.entropy(base?, normalize?)`
+- `.min()`, `.max()`, `.nan_min()`, `.nan_max()`, `.min_by(by)`, `.max_by(by)`, `.arg_min()`, `.arg_max()`
 - `.count(options?)` — Option `{ includeNulls: boolean }`.
 - `.first()`, `.last()`
-- `.any()`, `.all()`, `.any_null()`, `.all_null()`, `.n_unique()`
+- `.any()`, `.all()`, `.any_null()`, `.all_null()`, `.n_unique()`, `.null_count()`
+- `.bitwise_and()`, `.bitwise_or()`, `.bitwise_xor()`
+
 
 ### 🔀 Control Flow & Conditionals
 Construct dynamic `CASE WHEN` branches using the `$df.when` API:
@@ -271,6 +286,7 @@ df.select(
 - `$df.when(predicate).then(value)`: Starts a conditional evaluation.
 - `.when(predicate).then(value)`: Chains additional conditions.
 - `.otherwise(value)`: Specifies the fallback value when no conditions match (returns a complete `ColumnExpr`).
+- `$df.coalesce(...exprs)`: Returns the first non-null value among the provided expressions or literals.
 
 ---
 
@@ -285,16 +301,16 @@ $df.col("name").str.lower()
 $df.col("code").str.starts_with("A")
 $df.col("description").str.replace(/foo/i, "bar")
 ```
-- **Methods**: `lower()`, `upper()`, `len()`, `len_bytes()`, `len_chars()`, `trim()`, `trim_start()`, `trim_end()`, `starts_with(prefix)`, `ends_with(suffix)`, `contains(pattern)`, `replace(pattern, repl)`, `replace_all(pattern, repl)`, `slice(offset, length?)`, `split(delimiter)`, `explode()`, `reverse()`, `lpad(w, f)`, `rpad(w, f)`, `zfill(w)`, `strip_chars(chars?)`, `strip_chars_start(chars?)`, `strip_chars_end(chars?)`, `strip_prefix(pfx)`, `strip_suffix(sfx)`, `to_titlecase()`, `strptime(format, strict?)`, `to_integer()`, `to_decimal(p, s)`, `to_date()`, `to_datetime()`, `to_time()`.
+- **Methods**: `lower()`, `upper()`, `to_titlecase()`, `len()`, `len_bytes()`, `len_chars()`, `trim()`, `trim_start()`, `trim_end()`, `starts_with(prefix)`, `ends_with(suffix)`, `contains(pattern)`, `contains_any(patterns)`, `count_matches(pattern)`, `find(pattern)`, `find_many(patterns)`, `replace(pattern, repl)`, `replace_all(pattern, repl)`, `replace_many(patterns, replacements)`, `slice(offset, length?)`, `split(delimiter, options?)`, `explode()`, `reverse()`, `lpad(w, f)`, `rpad(w, f)`, `zfill(w)`, `strip_chars(chars?)`, `strip_chars_start(chars?)`, `strip_chars_end(chars?)`, `strip_prefix(pfx)`, `strip_suffix(sfx)`, `escape_regex()`, `extract(pattern, groupIndex?)`, `extract_all(pattern)`, `extract_groups(pattern)`, `extract_many(patterns)`, `encode(encoding)`, `decode(encoding, strict?)`, `json_decode(options?)`, `json_path_match(jsonPath)`, `normalize(form?)`, `join(separator)`, `strptime(format, strict?)`, `to_integer()`, `to_decimal(p, s)`, `to_date()`, `to_datetime()`, `to_time()`.
 
 ### 📅 Temporal Operations (`.dt`)
 Available on datetime or duration values via `.dt`:
 ```typescript
 $df.col("timestamp").dt.year()
-$df.col("timestamp").dt.strftime("%Y-%m-%d %H:%M:%S")
+$df.col("timestamp").dt.convert_time_zone("America/New_York")
 $df.col("duration").dt.total_seconds()
 ```
-- **Datetime Methods**: `year()`, `month()`, `day()`, `hour()`, `minute()`, `second()`, `millisecond()`, `microsecond()`, `nanosecond()`, `weekday()`, `week()`, `quarter()`, `century()`, `millennium()`, `ordinal_day()`, `is_leap_year()`, `month_start()`, `month_end()`, `date()`, `time()`, `offset_day(n, options?)`, `offset_business_day(n, options?)`, `utc_offset(timeZone?, options?)`, `epoch(unit)`, `timestamp(unit)`, `strftime(format, locale?)`.
+- **Datetime Methods**: `year()`, `month()`, `day()`, `hour()`, `minute()`, `second()`, `millisecond()`, `microsecond()`, `nanosecond()`, `weekday()`, `week()`, `quarter()`, `century()`, `millennium()`, `ordinal_day()`, `is_leap_year()`, `month_start()`, `month_end()`, `date()`, `time()`, `offset_day(n, options?)`, `offset_business_day(n, options?)`, `convert_time_zone(tz)`, `cast_time_unit(unit)`, `with_time_unit(unit)`, `replace(options)`, `truncate(every)`, `utc_offset(timeZone?, options?)`, `epoch(unit)`, `timestamp(unit)`, `strftime(format, locale?)`.
 - **Duration Methods**: `total_days()`, `total_hours()`, `total_minutes()`, `total_seconds()`, `total_milliseconds()`, `total_microseconds()`, `total_nanoseconds()`.
 
 ### 📊 Array/List Operations (`.arr`)
@@ -307,7 +323,7 @@ $df.col("matrix").arr.get(2)
 $df.col("numbers").arr.eval(element().mul(2)).alias("numbers_doubled")
 $df.col("tags").arr.eval(element().str.to_uppercase()).alias("upper_tags")
 ```
-- **Methods**: `lengths()`, `len()`, `get(idx, null_on_oob?)`, `first(null_on_oob?)`, `last(null_on_oob?)`, `gather(indices, null_on_oob?)`, `gather_every(n, offset?)`, `slice(offset, length?)`, `contains(item)`, `count_matches(item)`, `join(separator)`, `sort(descending?)`, `reverse()`, `unique()`, `sum()`, `mean()`, `median()`, `mode()`, `min()`, `max()`, `eval(expr)`.
+- **Methods**: `lengths()`, `len()`, `get(idx, null_on_oob?)`, `first(null_on_oob?)`, `last(null_on_oob?)`, `gather(indices, null_on_oob?)`, `gather_every(n, offset?)`, `slice(offset, length?)`, `contains(item)`, `count_matches(item)`, `join(separator)`, `sort(descending?)`, `reverse()`, `unique()`, `sum()`, `mean()`, `median()`, `mode()`, `min()`, `max()`, `arg_min()`, `arg_max()`, `agg(expr)`, `eval(expr)`.
 
 ### 🗃️ Struct/Object Operations (`.struct`)
 Available on any struct or nested object column expression via `.struct`. You can access fields dynamically via properties or explicit methods:
@@ -315,8 +331,8 @@ Available on any struct or nested object column expression via `.struct`. You ca
 // Sibling fields access via Proxy
 $df.col("address").struct.city.alias("city")
 
-// Or using the explicit field method
-$df.col("address").struct.field("city")
+// Explicit struct field access or struct creation
+$df.struct({ city: $df.col("city"), state: $df.col("state") })
 ```
 - **Methods**:
   - `field(name)`: Accesses a field within the struct.
@@ -409,6 +425,27 @@ const df = $df.data(rawData, schema);
 const activeUsers = df.filter($df.col("is_active").eq(true));
 ```
 
+### ⚡ Post-Operation Schema Type Deduction
+
+DFScript features an intelligent post-operation schema inference engine that automatically determines the correct resulting `DataType` across complex expression trees without requiring manual `.cast()` calls:
+
+- **Temporal & Duration Arithmetic**:
+  - `Datetime - Datetime => Duration`
+  - `Datetime ± Duration => Datetime`
+  - `Time - Time => Duration`
+  - `Time ± Duration => Time`
+  - `Duration * / Numeric => Duration`
+- **Integer Promotion & Signedness Hierarchy**: Automatically preserves or promotes integer widths:
+  - Preserves exact unsigned/signed types (`UInt8 + UInt8 => UInt8`, `Int16 + Int16 => Int16`).
+  - Correctly promotes across sizes and signedness (`UInt16 + Int8 => Int16`, `UInt32 + Int32 => Int32`, `Int32 + Int64 => Int64`).
+- **Floating-Point & Decimal Resolution**:
+  - `Int + Float => Float64`
+  - `Float32 + Float32 => Float32`
+  - `Decimal + Int => Decimal`
+  - Evaluates non-integer operation results (e.g. division `10 / 3`) and promotes to `Float64`.
+- **Conditional Branch Widening**: Multi-branch expressions (`when().then().otherwise()`) progressively widen branch types to their common denominator.
+- **Statistical Aggregations**: `.mean()` and `.std()` promote integer columns to `Float64`, while non-numeric `.count()` operations resolve to `Int32`.
+
 ### Supported Data Types
 - **Integers**: `Int8`, `Int16`, `Int32`, `Int64`, `UInt8`, `UInt16`, `UInt32`, `UInt64`
 - **Floats & Decimals**: `Float32`, `Float64`, `Decimal(precision?, scale?)`

package/dist/columnExpressions/ExprBase.d.ts

@@ -12,10 +12,17 @@ export declare class ExprBase implements IExpr {
     _literalValue?: any;
     _aggFn?: AggFn<any> | null;
     _castType?: RegisteredDataType;
+    _binaryMeta?: {
+        left: any;
+        right: any;
+    };
     _groupingOpsIndex?: number;
     _partitionOpsIndex?: number;
     _partitionBy: (string | IExpr)[] | null;
     _evaluateWindow?: (groupPreValues: any[], partitionIndices: number[], currentIndex: number) => any;
+    _baseExpr?: IExpr;
+    _fieldName?: string;
+    _isUnnest?: boolean;
     _evaluatePost(opsIndex: number | undefined, aggregatedArray: any[], columns: ColumnDict): ColumnData;
     _evaluatePre(opsIndex: number | undefined, columns: ColumnDict, height: number): ColumnData;
     _getInitialValue(columns: ColumnDict, height: number): ColumnData;

package/dist/columnExpressions/constants.d.ts

@@ -4,3 +4,4 @@ export declare const COALESCE_MARKER = "*coalesce*";
 export declare const ELEMENT_MARKER = "*element*";
 export declare const STRUCT_MARKER = "*struct*";
 export declare const DURATION_MARKER = "*duration*";
+export declare const WHEN_MARKER = "*when*";

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

@@ -1,6 +1,6 @@
 import { ColumnExpr } from "../ColumnExpr";
 import type { IExpr, ValidScalarTypes } from "../../types";
-type WhenArg = IExpr | ValidScalarTypes;
+type WhenArg = IExpr | ValidScalarTypes | any[];
 export declare class WhenThenChain {
     private _predicates;
     private _values;
@@ -13,12 +13,14 @@ export declare class When {
     then(value: WhenArg): WhenThen;
 }
 export declare class WhenThen extends ColumnExpr<any> {
-    private _predicates;
-    private _values;
-    private _otherwiseValue;
-    constructor(predicates: WhenArg[] | string, values?: WhenArg[], otherwiseValue?: WhenArg);
+    _predicates: WhenArg[];
+    _values: WhenArg[];
+    _otherwise: WhenArg;
+    get _otherwiseValue(): WhenArg;
+    get _branchOperands(): WhenArg[];
+    constructor(predicates?: WhenArg[], values?: WhenArg[], otherwise?: WhenArg);
     when(predicate: WhenArg): WhenThenChain;
-    otherwise(value: WhenArg): ColumnExpr<any>;
+    otherwise(value: WhenArg): WhenThen;
 }
 /**
  * Provides conditional branch evaluations inside column expressions.

package/dist/columnExpressions/index.d.ts

@@ -21,4 +21,5 @@ export * from "./functions/seq_range";
 export * from "./functions/element";
 export * from "./functions/struct";
 export * from "./functions/duration";
+export * from "./typeInference";
 export * from "./utils";

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

@@ -1,4 +1,4 @@
-import type { AggFn, UniqueArrayStatsOptions } from "../../types";
+import type { AggFn, UniqueArrayStatsOptions, SkewOptions, KurtosisOptions, EntropyOptions } from "../../types";
 import { ExprBase } from "../ExprBase";
 /**
  * @namespace $df.col
@@ -66,6 +66,34 @@ export declare class AggregationExpr extends ExprBase {
      * └───────┴──────────┘
      */
     any_null(): this;
+    /**
+     * Aggregation: Finds the index of the maximum value in the group.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ val: [10, 50, 20] })
+     * >>> df.select($df.col("val").arg_max().alias("max_idx"))
+     * shape: (1, 1)
+     * ┌─────────┐
+     * │ max_idx │
+     * ├─────────┤
+     * │ 1       │
+     * └─────────┘
+     */
+    arg_max(): this;
+    /**
+     * Aggregation: Finds the index of the minimum value in the group.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ val: [10, 50, 20] })
+     * >>> df.select($df.col("val").arg_min().alias("min_idx"))
+     * shape: (1, 1)
+     * ┌─────────┐
+     * │ min_idx │
+     * ├─────────┤
+     * │ 0       │
+     * └─────────┘
+     */
+    arg_min(): this;
     /**
      * Aggregation: Computes the arithmetic mean of the group.
      * @returns ColumnExpression
@@ -80,6 +108,48 @@ export declare class AggregationExpr extends ExprBase {
      * └───────┴──────┘
      */
     avg(): this;
+    /**
+     * Aggregation: Computes bitwise AND across all elements in the group.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ val: [0b11, 0b10] })
+     * >>> df.select($df.col("val").bitwise_and().alias("res"))
+     * shape: (1, 1)
+     * ┌─────┐
+     * │ res │
+     * ├─────┤
+     * │ 2   │
+     * └─────┘
+     */
+    bitwise_and(): this;
+    /**
+     * Aggregation: Computes bitwise OR across all elements in the group.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ val: [0b01, 0b10] })
+     * >>> df.select($df.col("val").bitwise_or().alias("res"))
+     * shape: (1, 1)
+     * ┌─────┐
+     * │ res │
+     * ├─────┤
+     * │ 3   │
+     * └─────┘
+     */
+    bitwise_or(): this;
+    /**
+     * Aggregation: Computes bitwise XOR across all elements in the group.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ val: [0b11, 0b10] })
+     * >>> df.select($df.col("val").bitwise_xor().alias("res"))
+     * shape: (1, 1)
+     * ┌─────┐
+     * │ res │
+     * ├─────┤
+     * │ 1   │
+     * └─────┘
+     */
+    bitwise_xor(): this;
     /**
      * Aggregation: Computes the Pearson correlation coefficient between two columns.
      * @param other The target column expression to correlate with.
@@ -142,6 +212,21 @@ export declare class AggregationExpr extends ExprBase {
      * └─────────────┘
      */
     dot(other: any): this;
+    /**
+     * Aggregation: Computes the Shannon entropy of a column or group.
+     * @param options Entropy options ({ base?: number, normalize?: boolean }, default base=Math.E, normalize=true).
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ val: ["a", "b", "a", "c"] })
+     * >>> df.select($df.col("val").entropy().alias("h"))
+     * shape: (1, 1)
+     * ┌──────────┐
+     * │ h        │
+     * ├──────────┤
+     * │ 1.039721 │
+     * └──────────┘
+     */
+    entropy(options?: EntropyOptions): this;
     /**
      * Aggregation: Finds the first value in the group.
      * @returns ColumnExpression
@@ -170,6 +255,21 @@ export declare class AggregationExpr extends ExprBase {
      * └───────┴──────────┘
      */
     implode(): this;
+    /**
+     * Aggregation: Computes the kurtosis (peakedness/tailedness) of a numeric column.
+     * @param options Kurtosis calculation options ({ fisher?: boolean, bias?: boolean }, default fisher=true, bias=true).
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ val: [1, 2, 3, 4, 5] })
+     * >>> df.select($df.col("val").kurtosis().alias("kurt"))
+     * shape: (1, 1)
+     * ┌───────┐
+     * │ kurt  │
+     * ├───────┤
+     * │ -1.3  │
+     * └───────┘
+     */
+    kurtosis(options?: KurtosisOptions): this;
     /**
      * Aggregation: Finds the last value in the group.
      * @returns ColumnExpression
@@ -198,6 +298,21 @@ export declare class AggregationExpr extends ExprBase {
      * └───────┴─────────┘
      */
     max(): this;
+    /**
+     * Aggregation: Finds the value in this column corresponding to the maximum value in the `by` expression.
+     * @param by Column or expression to order by.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ name: ["a", "b", "c"], score: [10, 50, 20] })
+     * >>> df.select($df.col("name").max_by($df.col("score")).alias("top_scorer"))
+     * shape: (1, 1)
+     * ┌────────────┐
+     * │ top_scorer │
+     * ├────────────┤
+     * │ "b"        │
+     * └────────────┘
+     */
+    max_by(by: any): this;
     /**
      * Aggregation: Computes the arithmetic mean of elements in the group.
      * @returns ColumnExpression
@@ -240,6 +355,21 @@ export declare class AggregationExpr extends ExprBase {
      * └───────┴─────────┘
      */
     min(): this;
+    /**
+     * Aggregation: Finds the value in this column corresponding to the minimum value in the `by` expression.
+     * @param by Column or expression to order by.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ name: ["a", "b", "c"], score: [10, 50, 20] })
+     * >>> df.select($df.col("name").min_by($df.col("score")).alias("lowest_scorer"))
+     * shape: (1, 1)
+     * ┌──────────────┐
+     * │ lowest_scorer│
+     * ├──────────────┤
+     * │ "a"          │
+     * └──────────────┘
+     */
+    min_by(by: any): this;
     /**
      * Aggregation: Finds the statistical mode (most frequent value).
      * @returns ColumnExpression
@@ -269,6 +399,34 @@ export declare class AggregationExpr extends ExprBase {
      * └───────┴────────────┘
      */
     n_unique(options?: UniqueArrayStatsOptions): this;
+    /**
+     * Aggregation: Finds the maximum value in the group, taking NaN values into account (NaN propagates).
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ group: ["A", "A"], val: [10, NaN] })
+     * >>> df.group_by("group").agg($df.col("val").nan_max().alias("nan_max_val"))
+     * shape: (1, 2)
+     * ┌───────┬─────────────┐
+     * │ group │ nan_max_val │
+     * ├───────┼─────────────┤
+     * │ "A"   │ NaN         │
+     * └───────┴─────────────┘
+     */
+    nan_max(): this;
+    /**
+     * Aggregation: Finds the minimum value in the group, taking NaN values into account (NaN propagates).
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ group: ["A", "A"], val: [10, NaN] })
+     * >>> df.group_by("group").agg($df.col("val").nan_min().alias("nan_min_val"))
+     * shape: (1, 2)
+     * ┌───────┬─────────────┐
+     * │ group │ nan_min_val │
+     * ├───────┼─────────────┤
+     * │ "A"   │ NaN         │
+     * └───────┴─────────────┘
+     */
+    nan_min(): this;
     /**
      * Aggregation: Counts the number of null or missing records.
      * @returns ColumnExpression
@@ -298,8 +456,38 @@ export declare class AggregationExpr extends ExprBase {
      * └─────┘
      */
     quantile(q: number): this;
+    /**
+     * Aggregation: Computes the product of all elements in the group.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ group: ["A", "A"], val: [2, 5] })
+     * >>> df.group_by("group").agg($df.col("val").product().alias("p"))
+     * shape: (1, 2)
+     * ┌───────┬────┐
+     * │ group │ p  │
+     * ├───────┼────┤
+     * │ "A"   │ 10 │
+     * └───────┴────┘
+     */
+    product(): this;
+    /**
+     * Aggregation: Computes the sample skewness as the Fisher-Pearson coefficient of skewness.
+     * @param options Skew calculation options ({ bias?: boolean }, default bias=true).
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ val: [1, 2, 5, 10, 20] })
+     * >>> df.select($df.col("val").skew().alias("skewness"))
+     * shape: (1, 1)
+     * ┌──────────┐
+     * │ skewness │
+     * ├──────────┤
+     * │ 0.859427 │
+     * └──────────┘
+     */
+    skew(options?: SkewOptions): this;
     /**
      * Aggregation: Computes the Spearman rank correlation coefficient.
+
      * @param other The other column expression to correlate with.
      * @returns ColumnExpression
      * @example
@@ -341,6 +529,20 @@ export declare class AggregationExpr extends ExprBase {
      * └───────┴───────┘
      */
     sum(): this;
+    /**
+     * Aggregation: Computes sample variance.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ group: ["A", "A", "A"], val: [10, 20, 30] })
+     * >>> df.group_by("group").agg($df.col("val").variance().alias("v"))
+     * shape: (1, 2)
+     * ┌───────┬─────┐
+     * │ group │ v   │
+     * ├───────┼─────┤
+     * │ "A"   │ 100 │
+     * └───────┴─────┘
+     */
+    variance(): this;
     /**
      * Aggregation: Computes weighted average.
      * @param weights The weight values or column expression.

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

@@ -10,6 +10,22 @@ export declare class ArrayExprNamespace {
     expr: any;
     constructor(expr: any);
     _deriveArray(fn: (arr: any[] | AnyTypedArray) => any): any;
+    /**
+     * Applies an aggregation expression or element-wise calculation over each array cell.
+     * @param expr Aggregation expression (e.g. $df.element().sum() or $df.element().max())
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ a: [[1, 2, 3], [4, 5]] })
+     * >>> df.with_columns($df.col("a").arr.agg($df.element().sum()).alias("sum_a"))
+     * shape: (2, 2)
+     * ┌───────────┬───────┐
+     * │ a         │ sum_a │
+     * ├───────────┼───────┤
+     * │ [1, 2, 3] │ 6     │
+     * │ [4, 5]    │ 9     │
+     * └───────────┴───────┘
+     */
+    agg(expr: IExpr): any;
     /**
      * Returns true if all items in nested list cells are truthy.
      * @returns ColumnExpression
@@ -40,6 +56,36 @@ export declare class ArrayExprNamespace {
      * └────────────────┴──────────┘
      */
     any(): any;
+    /**
+     * Finds the index of the maximum value in each array.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ a: [[1, 5, 2], [10, 4]] })
+     * >>> df.with_columns($df.col("a").arr.arg_max().alias("max_idx"))
+     * shape: (2, 2)
+     * ┌───────────┬─────────┐
+     * │ a         │ max_idx │
+     * ├───────────┼─────────┤
+     * │ [1, 5, 2] │ 1       │
+     * │ [10, 4]   │ 0       │
+     * └───────────┴─────────┘
+     */
+    arg_max(): any;
+    /**
+     * Finds the index of the minimum value in each array.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ a: [[5, 1, 2], [10, 4]] })
+     * >>> df.with_columns($df.col("a").arr.arg_min().alias("min_idx"))
+     * shape: (2, 2)
+     * ┌───────────┬─────────┐
+     * │ a         │ min_idx │
+     * ├───────────┼─────────┤
+     * │ [5, 1, 2] │ 1       │
+     * │ [10, 4]   │ 1       │
+     * └───────────┴─────────┘
+     */
+    arg_min(): any;
     /**
      * Checks if nested lists contain item.
      * @param item The element to search for.
@@ -122,20 +168,20 @@ export declare class ArrayExprNamespace {
      */
     filter(expr: IExpr): any;
     /**
-     * Expands lists into row-wise records.
+     * Expands lists into row-wise elements and produces an index mapping for DataFrame unnesting.
      * @param options Config options including handling of empty arrays and nulls.
      * @returns ColumnExpression
      * @example
-     * >>> const df = $df.data({ a: [[1, 2], [3]] })
-     * >>> df.explode($df.col("a").arr.explode())
-     * shape: (3, 1)
-     * ┌───┐
-     * │ a │
-     * ├───┤
-     * │ 1 │
-     * │ 2 │
-     * │ 3 │
-     * └───┘
+     * >>> const df = $df.data({ id: [1, 2], values: [[10, 20], [30]] })
+     * >>> df.select([$df.col("id"), $df.col("values").arr.explode()])
+     * shape: (3, 2)
+     * ┌─────┬────────┐
+     * │ id  │ values │
+     * ├─────┼────────┤
+     * │ 1   │ 10     │
+     * │ 1   │ 20     │
+     * │ 2   │ 30     │
+     * └─────┴────────┘
      */
     explode({ empty_as_null, keep_nulls }?: ExplodeOptions): any;
     /**
@@ -271,21 +317,6 @@ export declare class ArrayExprNamespace {
      * └───────────┴───────┘
      */
     max(): any;
-    /**
-     * Returns the index of maximum value.
-     * @returns ColumnExpression
-     * @example
-     * >>> const df = $df.data({ a: [[1, 5, 2], [10, 4]] })
-     * >>> df.with_columns($df.col("a").arr.max_index().alias("max_idx"))
-     * shape: (2, 2)
-     * ┌───────────┬─────────┐
-     * │ a         │ max_idx │
-     * ├───────────┼─────────┤
-     * │ [1, 5, 2] │ 1       │
-     * │ [10, 4]   │ 0       │
-     * └───────────┴─────────┘
-     */
-    max_index(): any;
     /**
      * Returns average of elements inside each list.
      * @returns ColumnExpression
@@ -331,21 +362,6 @@ export declare class ArrayExprNamespace {
      * └───────────┴───────┘
      */
     min(): any;
-    /**
-     * Returns the index of minimum value.
-     * @returns ColumnExpression
-     * @example
-     * >>> const df = $df.data({ a: [[5, 1, 2], [10, 4]] })
-     * >>> df.with_columns($df.col("a").arr.min_index().alias("min_idx"))
-     * shape: (2, 2)
-     * ┌───────────┬─────────┐
-     * │ a         │ min_idx │
-     * ├───────────┼─────────┤
-     * │ [5, 1, 2] │ 1       │
-     * │ [10, 4]   │ 1       │
-     * └───────────┴─────────┘
-     */
-    min_index(): any;
     /**
      * Returns the mode value inside each list.
      * @returns ColumnExpression