df-script 1.5.0 → 1.7.0

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

@@ -1,31 +1,384 @@
 import { ExprBase } from "../ExprBase";
+/**
+ * @namespace $df.col
+ * @category ColumnExpression
+ * @syntax $df.col(<column_name>).{symbol}(...)
+ */
 export declare class ComparisonExpr extends ExprBase {
+    /**
+     * Checks if values fall inside lower and upper boundaries (inclusive).
+     * @param lower The lower boundary value or expression.
+     * @param upper The upper boundary value or expression.
+     * @param closed Control boundary inclusivity: "both", "left", "right", or "none" (default: "both").
+     * @returns ColumnExpression
+     * @example
+     * >>> df.with_columns($df.col("a").between(1, 2).alias("in_range"))
+     * shape: (3, 3)
+     * ┌───┬───┬──────────┐
+     * │ a │ b │ in_range │
+     * ├───┼───┼──────────┤
+     * │ 1 │ x │ true     │
+     * │ 2 │ y │ true     │
+     * │ 3 │ z │ false    │
+     * └───┴───┴──────────┘
+     */
     between(lower: any, upper: any, closed?: "both" | "left" | "right" | "none"): this;
+    /**
+     * Boolean comparison: Returns true if column values match the specified value exactly.
+     * @param val The value or column expression to compare against.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({
+     * ...   a: [1, 2, 3]
+     * ... })
+     * shape: (3, 1)
+     * ┌───┐
+     * │ a │
+     * ├───┤
+     * │ 1 │
+     * │ 2 │
+     * │ 3 │
+     * └───┘
+     *
+     * >>> df.with_columns($df.col("a").eq(2).alias("is_two"))
+     * shape: (3, 2)
+     * ┌───┬────────┐
+     * │ a │ is_two │
+     * ├───┼────────┤
+     * │ 1 │ false  │
+     * │ 2 │ true   │
+     * │ 3 │ false  │
+     * └───┴────────┘
+     */
     eq(val: any): this;
+    /**
+     * Equivalence check that treats null values as equal to each other.
+     * @param val The value or column expression to compare against.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ a: [1, null, 3] })
+     * >>> df.with_columns($df.col("a").eq_missing(null).alias("is_missing"))
+     * shape: (3, 2)
+     * ┌──────┬────────────┐
+     * │ a    │ is_missing │
+     * ├──────┼────────────┤
+     * │ 1    │ false      │
+     * │ null │ true       │
+     * │ 3    │ false      │
+     * └──────┴────────────┘
+     */
     eq_missing(val: any): this;
+    /**
+     * Boolean comparison: Returns true if greater than or equal to argument.
+     * @param val The value or column expression to compare against.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ price: [90, 100, 110] })
+     * >>> df.with_columns($df.col("price").ge(100).alias("ge_100"))
+     * shape: (3, 2)
+     * ┌───────┬────────┐
+     * │ price │ ge_100 │
+     * ├───────┼────────┤
+     * │ 90    │ false  │
+     * │ 100   │ true   │
+     * │ 110   │ true   │
+     * └───────┴────────┘
+     */
     ge(val: any): this;
+    /**
+     * Boolean comparison: Returns true if column value is greater than argument.
+     * @param val The value or column expression to compare against.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ price: [90, 100, 110] })
+     * >>> df.with_columns($df.col("price").gt(100).alias("gt_100"))
+     * shape: (3, 2)
+     * ┌───────┬────────┐
+     * │ price │ gt_100 │
+     * ├───────┼────────┤
+     * │ 90    │ false  │
+     * │ 100   │ false  │
+     * │ 110   │ true   │
+     * └───────┴────────┘
+     */
     gt(val: any): this;
+    /**
+     * Aggregation: Checks if any value in the group is null.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ group: ["A", "A"], val: [10, null] })
+     * >>> df.group_by("group").agg($df.col("val").has_nulls().alias("has_nulls"))
+     * shape: (1, 2)
+     * ┌───────┬───────────┐
+     * │ group │ has_nulls │
+     * ├───────┼───────────┤
+     * │ "A"   │ true      │
+     * └───────┴───────────┘
+     */
     has_nulls(): any;
+    /**
+     * Determines if floating-point values are approximately equal within tolerances.
+     * @param other The value or expression to compare against.
+     * @param options Tolerance values absolute (abs_tol) and relative (rel_tol), and NaN options.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ a: [1.000000001, 2.0] })
+     * >>> df.with_columns($df.col("a").is_close(1.0).alias("close"))
+     * shape: (2, 2)
+     * ┌─────────────┬───────┐
+     * │ a           │ close │
+     * ├─────────────┼───────┤
+     * │ 1.000000001 │ true  │
+     * │ 2.0         │ false │
+     * └─────────────┴───────┘
+     */
     is_close(other: any, { abs_tol, rel_tol, nans_equal }?: {
         abs_tol?: number;
         rel_tol?: number;
         nans_equal?: boolean;
     }): this;
+    /**
+     * Checks if values occur more than once in the column.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ a: [1, 2, 2] })
+     * >>> df.with_columns($df.col("a").is_duplicated().alias("dup"))
+     * shape: (3, 2)
+     * ┌───┬───────┐
+     * │ a │ dup   │
+     * ├───┼───────┤
+     * │ 1 │ false │
+     * │ 2 │ true  │
+     * │ 2 │ true  │
+     * └───┴───────┘
+     */
     is_duplicated(): this;
+    /**
+     * Checks if strings or nested arrays have length 0.
+     * @param options Config options including whether to ignore nulls inside arrays.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ a: ["", "hello", []] })
+     * >>> df.with_columns($df.col("a").is_empty().alias("empty"))
+     * shape: (3, 2)
+     * ┌─────────┬───────┐
+     * │ a       │ empty │
+     * ├─────────┼───────┤
+     * │ ""      │ true  │
+     * │ "hello" │ false │
+     * │ []      │ true  │
+     * └─────────┴───────┘
+     */
     is_empty({ ignoreNulls }?: {
         ignoreNulls?: boolean;
     }): this;
+    /**
+     * Checks if values are finite numbers (not NaN or Infinity).
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ a: [1.5, Infinity, NaN] })
+     * >>> df.with_columns($df.col("a").is_finite().alias("finite"))
+     * shape: (3, 2)
+     * ┌──────────┬────────┐
+     * │ a        │ finite │
+     * ├──────────┼────────┤
+     * │ 1.5      │ true   │
+     * │ Infinity │ false  │
+     * │ NaN      │ false  │
+     * └──────────┴────────┘
+     */
     is_finite(): this;
+    /**
+     * Checks if column values are members of a specified array or list.
+     * @param values An array of candidate values or a single value to match against.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ category: ["toys", "books", "food"] })
+     * >>> df.with_columns($df.col("category").is_in(["toys", "books"]).alias("in_list"))
+     * shape: (3, 2)
+     * ┌──────────┬─────────┐
+     * │ category │ in_list │
+     * ├──────────┼─────────┤
+     * │ "toys"   │ true    │
+     * │ "books"  │ true    │
+     * │ "food"   │ false   │
+     * └──────────┴─────────┘
+     */
     is_in(values: any[] | any): this;
+    /**
+     * Checks if values are positive or negative Infinity.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ a: [1.5, Infinity, -Infinity] })
+     * >>> df.with_columns($df.col("a").is_infinite().alias("inf"))
+     * shape: (3, 2)
+     * ┌───────────┬───────┐
+     * │ a         │ inf   │
+     * ├───────────┼───────┤
+     * │ 1.5       │ false │
+     * │ Infinity  │ true  │
+     * │ -Infinity │ true  │
+     * └───────────┴───────┘
+     */
     is_infinite(): this;
+    /**
+     * Checks if values are NaN.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ a: [1.5, NaN] })
+     * >>> df.with_columns($df.col("a").is_nan().alias("nan"))
+     * shape: (2, 2)
+     * ┌─────┬───────┐
+     * │ a   │ nan   │
+     * ├─────┼───────┤
+     * │ 1.5 │ false │
+     * │ NaN │ true  │
+     * └─────┴───────┘
+     */
     is_nan(): this;
+    /**
+     * Checks if values are not NaN.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ a: [1.5, NaN] })
+     * >>> df.with_columns($df.col("a").is_not_nan().alias("not_nan"))
+     * shape: (2, 2)
+     * ┌─────┬─────────┐
+     * │ a   │ not_nan │
+     * ├─────┼─────────┤
+     * │ 1.5 │ true    │
+     * │ NaN │ false   │
+     * └─────┴─────────┘
+     */
     is_not_nan(): this;
+    /**
+     * Checks if column values are non-null and valid (not null, undefined, or missing).
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ email: ["alice@example.com", null] })
+     * >>> df.with_columns($df.col("email").is_not_null().alias("valid"))
+     * shape: (2, 2)
+     * ┌───────────────────┬───────┐
+     * │ email             │ valid │
+     * ├───────────────────┼───────┤
+     * │ alice@example.com │ true  │
+     * │ null              │ false │
+     * └───────────────────┴───────┘
+     */
     is_not_null(): this;
+    /**
+     * Checks if column values are null, undefined, or missing.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ email: ["alice@example.com", null] })
+     * >>> df.with_columns($df.col("email").is_null().alias("missing"))
+     * shape: (2, 2)
+     * ┌───────────────────┬─────────┐
+     * │ email             │ missing │
+     * ├───────────────────┼─────────┤
+     * │ alice@example.com │ false   │
+     * │ null              │ true    │
+     * └───────────────────┴─────────┘
+     */
     is_null(): this;
+    /**
+     * Checks if values occur exactly once in the column.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ a: [1, 2, 2] })
+     * >>> df.with_columns($df.col("a").is_unique().alias("uniq"))
+     * shape: (3, 2)
+     * ┌───┬───────┐
+     * │ a │ uniq  │
+     * ├───┼───────┤
+     * │ 1 │ true  │
+     * │ 2 │ false │
+     * │ 2 │ false │
+     * └───┴───────┘
+     */
     is_unique(): this;
+    /**
+     * Boolean comparison: Returns true if less than or equal to argument.
+     * @param val The value or column expression to compare against.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ price: [40, 50, 60] })
+     * >>> df.with_columns($df.col("price").le(50).alias("le_50"))
+     * shape: (3, 2)
+     * ┌───────┬───────┐
+     * │ price │ le_50 │
+     * ├───────┼───────┤
+     * │ 40    │ true  │
+     * │ 50    │ true  │
+     * │ 60    │ false │
+     * └───────┴───────┘
+     */
     le(val: any): this;
+    /**
+     * Boolean comparison: Returns true if less than argument.
+     * @param val The value or column expression to compare against.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ price: [40, 50, 60] })
+     * >>> df.with_columns($df.col("price").lt(50).alias("lt_50"))
+     * shape: (3, 2)
+     * ┌───────┬───────┐
+     * │ price │ lt_50 │
+     * ├───────┼───────┤
+     * │ 40    │ true  │
+     * │ 50    │ false │
+     * │ 60    │ false │
+     * └───────┴───────┘
+     */
     lt(val: any): this;
+    /**
+     * Boolean comparison: Returns true if values do not match.
+     * @param val The value or column expression to compare against.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ category: ["electronics", "toys"] })
+     * >>> df.with_columns($df.col("category").ne("electronics").alias("not_elec"))
+     * shape: (2, 2)
+     * ┌─────────────┬──────────┐
+     * │ category    │ not_elec │
+     * ├─────────────┼──────────┤
+     * │ electronics │ false    │
+     * │ toys        │ true     │
+     * └─────────────┴──────────┘
+     */
     ne(val: any): this;
+    /**
+     * Difference check that treats null values as equal to each other.
+     * @param val The value or column expression to compare against.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ a: [1, null, 3] })
+     * >>> df.with_columns($df.col("a").ne_missing(null).alias("not_missing"))
+     * shape: (3, 2)
+     * ┌──────┬─────────────┐
+     * │ a    │ not_missing │
+     * ├──────┼─────────────┤
+     * │ 1    │ true        │
+     * │ null │ false       │
+     * │ 3    │ true        │
+     * └──────┴─────────────┘
+     */
     ne_missing(val: any): this;
+    /**
+     * Checks if values are not elements of a specific array or set list.
+     * @param values An array of candidate values or a single value to match against.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ category: ["toys", "books", "food"] })
+     * >>> df.with_columns($df.col("category").not_in(["toys", "books"]).alias("not_in"))
+     * shape: (3, 2)
+     * ┌──────────┬────────┐
+     * │ category │ not_in │
+     * ├──────────┼────────┤
+     * │ toys     │ false  │
+     * │ books    │ false  │
+     * │ food     │ true   │
+     * └──────────┴────────┘
+     */
     not_in(values: any[] | any): this;
 }

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

@@ -1,7 +1,89 @@
 import { ExprBase } from "../ExprBase";
+/**
+ * @namespace $df.col
+ * @category ColumnExpression
+ * @syntax $df.col(<column_name>).{symbol}(...)
+ */
 export declare class LogicalExpr extends ExprBase {
+    /**
+     * Logical AND check supporting Kleene logic.
+     * @param other The other boolean column expression or literal value to compare.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({
+     * ...   a: [true, true, false, null],
+     * ...   b: [true, false, false, true]
+     * ... })
+     * >>> df.with_columns($df.col("a").and($df.col("b")).alias("and_res"))
+     * shape: (4, 3)
+     * ┌───────┬───────┬─────────┐
+     * │ a     │ b     │ and_res │
+     * ├───────┼───────┼─────────┤
+     * │ true  │ true  │ true    │
+     * │ true  │ false │ false   │
+     * │ false │ false │ false   │
+     * │ null  │ true  │ null    │
+     * └───────┴───────┴─────────┘
+     */
     and(other: any): this;
+    /**
+     * Logical negation.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({
+     * ...   is_active: [true, false, null]
+     * ... })
+     * >>> df.with_columns($df.col("is_active").not().alias("is_inactive"))
+     * shape: (3, 2)
+     * ┌───────────┬─────────────┐
+     * │ is_active │ is_inactive │
+     * ├───────────┼─────────────┤
+     * │ true      │ false       │
+     * │ false     │ true        │
+     * │ null      │ null        │
+     * └───────────┴─────────────┘
+     */
     not(): this;
+    /**
+     * Logical OR check supporting Kleene logic.
+     * @param other The other boolean column expression or literal value to compare.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({
+     * ...   a: [true, false, false, null],
+     * ...   b: [false, false, true, false]
+     * ... })
+     * >>> df.with_columns($df.col("a").or($df.col("b")).alias("or_res"))
+     * shape: (4, 3)
+     * ┌───────┬───────┬────────┐
+     * │ a     │ b     │ or_res │
+     * ├───────┼───────┼────────┤
+     * │ true  │ false │ true   │
+     * │ false │ false │ false  │
+     * │ false │ true  │ true   │
+     * │ null  │ false │ null   │
+     * └───────┴───────┴────────┘
+     */
     or(other: any): this;
+    /**
+     * Logical XOR check.
+     * @param other The other boolean column expression or literal value to compare.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({
+     * ...   a: [true, true, false, false],
+     * ...   b: [true, false, true, false]
+     * ... })
+     * >>> df.with_columns($df.col("a").xor($df.col("b")).alias("xor_res"))
+     * shape: (4, 3)
+     * ┌───────┬───────┬─────────┐
+     * │ a     │ b     │ xor_res │
+     * ├───────┼───────┼─────────┤
+     * │ true  │ true  │ false   │
+     * │ true  │ false │ true    │
+     * │ false │ true  │ true    │
+     * │ false │ false │ false   │
+     * └───────┴───────┴─────────┘
+     */
     xor(other: any): this;
 }

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

@@ -1,6 +1,46 @@
 import { ExprBase } from "../ExprBase";
 import type { FillNullOptions } from "../../types";
+/**
+ * @namespace $df.col
+ * @category ColumnExpression
+ * @syntax $df.col(<column_name>).{symbol}(...)
+ */
 export declare class ManipulationExpr extends ExprBase {
+    /**
+     * Replaces null, undefined, or missing values with a specified value or strategy.
+     * @param options Configuration options including fill value, strategy ("forward", "backward", "zero", "one", "mean", "min", "max"), and optional limit.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({
+     * ...   a: [1, null, 3]
+     * ... })
+     * >>> df.with_columns($df.col("a").fill_null({ value: 0 }).alias("filled"))
+     * shape: (3, 2)
+     * ┌──────┬────────┐
+     * │ a    │ filled │
+     * ├──────┼────────┤
+     * │ 1    │ 1      │
+     * │ null │ 0      │
+     * │ 3    │ 3      │
+     * └──────┴────────┘
+     */
     fill_null({ value, strategy, limit }?: FillNullOptions): this;
+    /**
+     * Reverses the order of values in the column.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({
+     * ...   a: [1, 2, 3]
+     * ... })
+     * >>> df.with_columns($df.col("a").reverse().alias("reversed"))
+     * shape: (3, 2)
+     * ┌───┬──────────┐
+     * │ a │ reversed │
+     * ├───┼──────────┤
+     * │ 1 │ 3        │
+     * │ 2 │ 2        │
+     * │ 3 │ 1        │
+     * └───┴──────────┘
+     */
     reverse(): this;
 }