df-script 1.5.0 → 1.7.0

package/dist/dataframe/dataframe.d.ts

@@ -1,58 +1,988 @@
 import { GroupedData } from "./grouped/grouped";
 import type { IExpr, ColumnData, ColumnDict, DataFrameColumns, ConcatOptions, ConcatItem, HorizontalConcatOptions, RowRecord, DataFrameSchema, RegisteredDataType, ExplodeOptions, IntoExpr, FillNullOptions } from "../types";
 import type { LimitOptions, SortOptions, PivotOptions, JoinOptions, UnpivotOptions, TransposeOptions, WriteJSONOptions, WriteCSVOptions } from "./types";
+/**
+ * Two-dimensional columnar tabular data structure supporting expression execution and reshaping.
+ */
 export declare class DataFrame<T extends RowRecord = any> {
     _columns: DataFrameColumns<T>;
     private _height;
     private _schema;
     static _createDirect<U extends RowRecord = any>(columns: ColumnDict, schema: DataFrameSchema, height: number): DataFrame<U>;
+    /**
+     * Initializes a new DataFrame from row objects or a column dictionary.
+     * @param data Array of row objects or column data dictionary.
+     * @param schema Optional explicit DataFrame schema mapping.
+     * @param height Optional explicit height (row count).
+     * @namespace df
+     * @category DataFrame
+     * @syntax df.{symbol}(...)
+     * @example
+     * >>> const df = $df.data([{ a: 1, b: "x" }, { a: 2, b: "y" }])
+     * >>> df
+     * shape: (2, 2)
+     * ┌─────┬─────┐
+     * │ a   │ b   │
+     * ├─────┼─────┤
+     * │ 1   │ x   │
+     * │ 2   │ y   │
+     * └─────┴─────┘
+     */
     constructor(data: T[] | ColumnDict, schema?: DataFrameSchema, height?: number);
-    private inferSchema;
-    private applySchema;
+    private _inferSchema;
+    private _applySchema;
+    /**
+     * Gets array of column names in the DataFrame.
+     * @returns Array of column name strings.
+     * @example
+     * >>> const df = $df.data({ a: [1], b: [2] })
+     * >>> df
+     * shape: (1, 2)
+     * ┌───┬───┐
+     * │ a │ b │
+     * ├───┼───┤
+     * │ 1 │ 2 │
+     * └───┴───┘
+     * >>> df.columns
+     * ["a", "b"]
+     */
     get columns(): string[];
+    /**
+     * Concatenates items vertically, horizontally, or diagonally.
+     *
+     * @param items Single DataFrame or array of DataFrames/rows to concatenate.
+     * @param [options] Configuration options for concatenation layout and strictness.
+     * @param [options.how] Layout strategy: `"vertical"` (default, appends rows top-to-bottom), `"horizontal"` (joins unique columns side-by-side), or `"diagonal"` (concatenates mismatched columns with null padding).
+     * @param [options.horizontal.strict] When `true` (default), throws an error if row counts mismatch in horizontal concatenation. Set `false` to pad shorter DataFrames with `null`.
+     * @returns DataFrame
+     *
+     * @example
+     * // 1. Vertical Concatenation (default):
+     * >>> const df1 = $df.data({ a: [1] })
+     * >>> df1
+     * shape: (1, 1)
+     * ┌───┐
+     * │ a │
+     * ├───┤
+     * │ 1 │
+     * └───┘
+     * >>> const df2 = $df.data({ a: [2] })
+     * >>> df1.concat(df2, { how: "vertical" })
+     * shape: (2, 1)
+     * ┌───┐
+     * │ a │
+     * ├───┤
+     * │ 1 │
+     * │ 2 │
+     * └───┘
+     *
+     * @example
+     * // 2. Horizontal Concatenation:
+     * >>> const df1 = $df.data({ a: [1] })
+     * >>> const df2 = $df.data({ b: [2] })
+     * >>> df1.concat(df2, { how: "horizontal" })
+     * shape: (1, 2)
+     * ┌───┬───┐
+     * │ a │ b │
+     * ├───┼───┤
+     * │ 1 │ 2 │
+     * └───┴───┘
+     *
+     * @example
+     * // 3. Diagonal Concatenation (mismatched columns):
+     * >>> const df1 = $df.data({ a: [1] })
+     * >>> const df2 = $df.data({ b: [2] })
+     * >>> df1.concat(df2, { how: "diagonal" })
+     * shape: (2, 2)
+     * ┌──────┬──────┐
+     * │ a    │ b    │
+     * ├──────┼──────┤
+     * │ 1    │ null │
+     * │ null │ 2    │
+     * └──────┴──────┘
+     *
+     */
     concat<U extends RowRecord = any>(items: ConcatItem | ConcatItem[], options?: ConcatOptions): DataFrame<U>;
+    /**
+     * Drops specified columns from the DataFrame.
+     * @param args Column names or arrays of column names to remove.
+     * @returns DataFrame
+     * @example
+     * >>> const df = $df.data({ a: [1], b: [2] })
+     * >>> df
+     * shape: (1, 2)
+     * ┌───┬───┐
+     * │ a │ b │
+     * ├───┼───┤
+     * │ 1 │ 2 │
+     * └───┴───┘
+     * >>> df.drop("b")
+     * shape: (1, 1)
+     * ┌───┐
+     * │ a │
+     * ├───┤
+     * │ 1 │
+     * └───┘
+     */
     drop<K extends keyof T>(...args: (K | K[])[]): DataFrame<Omit<T, K>>;
+    /**
+     * Drops rows containing null or undefined values in specified subset columns.
+     * @param subset Column name or array of column names to check for nulls.
+     * @returns DataFrame
+     * @example
+     * >>> const df = $df.data({ a: [1, null, 3] })
+     * >>> df
+     * shape: (3, 1)
+     * ┌──────┐
+     * │ a    │
+     * ├──────┤
+     * │ 1    │
+     * │ null │
+     * │ 3    │
+     * └──────┘
+     * >>> df.drop_nulls()
+     * shape: (2, 1)
+     * ┌───┐
+     * │ a │
+     * ├───┤
+     * │ 1 │
+     * │ 3 │
+     * └───┘
+     */
     drop_nulls(subset?: string | string[]): DataFrame<T>;
+    /**
+     * Gets array of registered column DataTypes matching current schema order.
+     * @returns Array of RegisteredDataType definitions.
+     * @example
+     * >>> const df = $df.data({ a: [1], b: ["text"] })
+     * >>> df
+     * shape: (1, 2)
+     * ┌───┬──────┐
+     * │ a │ b    │
+     * ├───┼──────┤
+     * │ 1 │ text │
+     * └───┴──────┘
+     * >>> df.dtypes
+     * [Float64, Utf8]
+     */
     get dtypes(): RegisteredDataType[];
+    /**
+     * Explodes an array column into multiple rows, replicating non-target row attributes.
+     * @param columns Target column expression or array column name to explode.
+     * @param [options] Configuration options for empty array and null handling.
+     * @param [options.empty_as_null] When `true`, converts empty arrays to `null` rows.
+     * @param [options.keep_nulls] When `true`, retains `null` array values during explosion.
+     * @returns DataFrame
+     * @example
+     * >>> const df = $df.data({ group: ["A"], values: [[1, 2]] })
+     * >>> df
+     * shape: (1, 2)
+     * ┌───────┬────────┐
+     * │ group │ values │
+     * ├───────┼────────┤
+     * │ A     │ [1, 2] │
+     * └───────┴────────┘
+     * >>> df.explode("values")
+     * shape: (2, 2)
+     * ┌───────┬────────┐
+     * │ group │ values │
+     * ├───────┼────────┤
+     * │ A     │ 1      │
+     * │ A     │ 2      │
+     * └───────┴────────┘
+     */
     explode(columns: IntoExpr | IntoExpr[], options?: ExplodeOptions): DataFrame<any>;
+    /**
+     * Fills null values across columns using scalar values or statistical strategies.
+     * @param [options] Configuration options for null replacement.
+     * @param [options.value] Scalar replacement value or dict mapping column names to values.
+     * @param [options.strategy] Statistical filling strategy (`"zero"`, `"mean"`, `"min"`, `"max"`, `"forward"`, `"backward"`).
+     * @param [options.limit] Maximum consecutive nulls to fill when using propagation strategies.
+     * @returns DataFrame
+     * @example
+     * >>> const df = $df.data({ a: [1, null, 3] })
+     * >>> df
+     * shape: (3, 1)
+     * ┌──────┐
+     * │ a    │
+     * ├──────┤
+     * │ 1    │
+     * │ null │
+     * │ 3    │
+     * └──────┘
+     * >>> df.fill_null({ value: 0 })
+     * shape: (3, 1)
+     * ┌───┐
+     * │ a │
+     * ├───┤
+     * │ 1 │
+     * │ 0 │
+     * │ 3 │
+     * └───┘
+     */
     fill_null(options?: FillNullOptions): DataFrame<T>;
+    /**
+     * Filters rows matching boolean column expressions or predicate callbacks.
+     * @param exprs Expressions or predicate functions evaluated per row.
+     * @returns DataFrame
+     * @example
+     * >>> const df = $df.data({ a: [1, 2, 3] })
+     * >>> df
+     * shape: (3, 1)
+     * ┌───┐
+     * │ a │
+     * ├───┤
+     * │ 1 │
+     * │ 2 │
+     * │ 3 │
+     * └───┘
+     * >>> df.filter($df.col("a").gt(1))
+     * shape: (2, 1)
+     * ┌───┐
+     * │ a │
+     * ├───┤
+     * │ 2 │
+     * │ 3 │
+     * └───┘
+     */
     filter(...exprs: (IExpr | ((row: T) => any))[]): DataFrame<T>;
+    /**
+     * Returns the mapping dictionary of column names to DataType.
+     * @returns DataFrameSchema
+     * @example
+     * >>> const df = $df.data({ a: [1], b: ["text"] })
+     * >>> df
+     * shape: (1, 2)
+     * ┌───┬──────┐
+     * │ a │ b    │
+     * ├───┼──────┤
+     * │ 1 │ text │
+     * └───┴──────┘
+     * >>> df.get_schema()
+     * { a: Float64, b: Utf8 }
+     */
     get_schema(): DataFrameSchema;
+    /**
+     * Groups rows by key columns to prepare for aggregations.
+     * @param keys Column name or array of key column names.
+     * @returns GroupedData
+     * @example
+     * >>> const df = $df.data({ cat: ["A", "A", "B"], val: [10, 20, 30] })
+     * >>> df
+     * shape: (3, 2)
+     * ┌─────┬─────┐
+     * │ cat │ val │
+     * ├─────┼─────┤
+     * │ A   │ 10  │
+     * │ A   │ 20  │
+     * │ B   │ 30  │
+     * └─────┴─────┘
+     * >>> df.groupby("cat").agg($df.col("val").sum().alias("sum"))
+     * shape: (2, 2)
+     * ┌─────┬─────┐
+     * │ cat │ sum │
+     * ├─────┼─────┤
+     * │ A   │ 30  │
+     * │ B   │ 30  │
+     * └─────┴─────┘
+     */
     groupby<K extends keyof T>(keys: K | K[]): GroupedData<T, K>;
+    /**
+     * Returns the first N rows as a new DataFrame.
+     * @param n Number of leading rows to slice (default 10).
+     * @returns DataFrame
+     * @example
+     * >>> const df = $df.data({ a: [1, 2, 3, 4] })
+     * >>> df
+     * shape: (4, 1)
+     * ┌───┐
+     * │ a │
+     * ├───┤
+     * │ 1 │
+     * │ 2 │
+     * │ 3 │
+     * │ 4 │
+     * └───┘
+     * >>> df.head(2)
+     * shape: (2, 1)
+     * ┌───┐
+     * │ a │
+     * ├───┤
+     * │ 1 │
+     * │ 2 │
+     * └───┘
+     */
     head(n?: number): DataFrame<T>;
+    /**
+     * Gets height (total row count) of the DataFrame.
+     * @returns Number of rows.
+     * @example
+     * >>> const df = $df.data({ a: [10, 20, 30] })
+     * >>> df
+     * shape: (3, 1)
+     * ┌────┐
+     * │ a  │
+     * ├────┤
+     * │ 10 │
+     * │ 20 │
+     * │ 30 │
+     * └────┘
+     * >>> df.height
+     * 3
+     */
     get height(): number;
+    /**
+     * Concatenates columns horizontally to the current DataFrame.
+     * @param other DataFrame or array of DataFrames to append side-by-side.
+     * @param [options] Horizontal concat configuration options.
+     * @param [options.strict] When `true` (default), throws an error if row counts mismatch. Set `false` to allow null padding.
+     * @returns DataFrame
+     * @example
+     * >>> const df1 = $df.data({ a: [1, 2] })
+     * >>> df1
+     * shape: (2, 1)
+     * ┌───┐
+     * │ a │
+     * ├───┤
+     * │ 1 │
+     * │ 2 │
+     * └───┘
+     * >>> const df2 = $df.data({ b: [10, 20] })
+     * >>> df1.hstack(df2)
+     * shape: (2, 2)
+     * ┌───┬────┐
+     * │ a │ b  │
+     * ├───┼────┤
+     * │ 1 │ 10 │
+     * │ 2 │ 20 │
+     * └───┴────┘
+     */
     hstack<U extends RowRecord = any>(other: ConcatItem | ConcatItem[], options?: HorizontalConcatOptions): DataFrame<U>;
+    /**
+     * Inserts a new column at a specific ordinal index position.
+     * @param index Target column index position.
+     * @param name Name of the inserted column.
+     * @param expr Value expression or column definition.
+     * @returns DataFrame
+     * @example
+     * >>> const df = $df.data({ a: [1], c: [3] })
+     * >>> df
+     * shape: (1, 2)
+     * ┌───┬───┐
+     * │ a │ c │
+     * ├───┼───┤
+     * │ 1 │ 3 │
+     * └───┴───┘
+     * >>> df.insert_column(1, "b", 2)
+     * shape: (1, 3)
+     * ┌───┬───┬───┐
+     * │ a │ b │ c │
+     * ├───┼───┼───┤
+     * │ 1 │ 2 │ 3 │
+     * └───┴───┴───┘
+     */
     insert_column(index: number, name: string, expr: IntoExpr): DataFrame<any>;
+    /**
+     * Retrieves a single scalar cell value by row and column position or name.
+     * @param row Row index position.
+     * @param column Column index or column name string.
+     * @returns Cell scalar value.
+     * @throws {DataFrameError} If shape is not (1, 1) when called without arguments.
+     * @throws {ShapeError} If row or column index is out of bounds.
+     * @example
+     * >>> const df = $df.data({ val: [42] })
+     * >>> df
+     * shape: (1, 1)
+     * ┌─────┐
+     * │ val │
+     * ├─────┤
+     * │ 42  │
+     * └─────┘
+     * >>> df.item(0, "val")
+     * 42
+     */
     item(row?: number, column?: number | string): any;
+    /**
+     * Yields a generator iterating over raw column arrays.
+     * @returns Generator of ColumnData arrays.
+     * @example
+     * >>> const df = $df.data({ a: [1, 2], b: [3, 4] })
+     * >>> df
+     * shape: (2, 2)
+     * ┌───┬───┐
+     * │ a │ b │
+     * ├───┼───┤
+     * │ 1 │ 3 │
+     * │ 2 │ 4 │
+     * └───┴───┘
+     * >>> for (const col of df.iter_columns()) { console.log(col); }
+     * Float64Array([1, 2])
+     * Float64Array([3, 4])
+     */
     iter_columns(): Generator<ColumnData>;
+    /**
+     * Yields a generator iterating over rows as tuples or named objects.
+     * @param [config] Iteration format configuration.
+     * @param [config.named] When `true`, yields row objects with column keys (`{ col: val }`). When `false` (default), yields positional arrays (`[val1, val2]`).
+     * @returns Generator of rows.
+     * @example
+     * >>> const df = $df.data({ a: [1, 2], b: ["x", "y"] })
+     * >>> df
+     * shape: (2, 2)
+     * ┌───┬───┐
+     * │ a │ b │
+     * ├───┼───┤
+     * │ 1 │ x │
+     * │ 2 │ y │
+     * └───┴───┘
+     * >>> for (const row of df.iter_rows({ named: true })) { console.log(row); }
+     * { a: 1, b: "x" }
+     * { a: 2, b: "y" }
+     */
     iter_rows({ named }?: {
         named?: boolean;
     }): Generator<any[] | Record<string, any>>;
+    /**
+     * Joins two DataFrames on key columns using inner, left, right, or outer join strategy.
+     * @param config Join configuration object.
+     * @param config.other Right DataFrame to join with left DataFrame.
+     * @param config.on Join key column name or array of key column names.
+     * @param [config.how] Join strategy (`"inner"`, `"left"`, `"right"`, or `"outer"`). Default `"inner"`.
+     * @param [config.suffixes] Custom column name suffix tuple `[leftSuffix, rightSuffix]` for overlapping non-key columns (default `["", "_right"]`).
+     * @returns DataFrame
+     * @example
+     * >>> const df1 = $df.data({ id: [1, 2], val: ["a", "b"] })
+     * >>> df1
+     * shape: (2, 2)
+     * ┌────┬─────┐
+     * │ id │ val │
+     * ├────┼─────┤
+     * │ 1  │ a   │
+     * │ 2  │ b   │
+     * └────┴─────┘
+     * >>> const df2 = $df.data({ id: [1, 2], num: [100, 200] })
+     * >>> df1.join({ other: df2, on: "id" })
+     * shape: (2, 3)
+     * ┌────┬─────┬─────┐
+     * │ id │ val │ num │
+     * ├────┼─────┼─────┤
+     * │ 1  │ a   │ 100 │
+     * │ 2  │ b   │ 200 │
+     * └────┴─────┴─────┘
+     */
     join<U extends RowRecord = any, R extends RowRecord = any>(config: JoinOptions<T, U>): DataFrame<R>;
+    /**
+     * Limits the output to N rows starting from offset.
+     * @param n Maximum number of rows to take.
+     * @param [options] Offset and slice direction options.
+     * @param [options.offset] Number of rows to skip before taking `n` rows (default 0).
+     * @param [options.from] Slice direction starting point (`"start"` or `"end"`). Default `"start"`.
+     * @returns DataFrame
+     * @example
+     * >>> const df = $df.data({ a: [10, 20, 30, 40] })
+     * >>> df
+     * shape: (4, 1)
+     * ┌────┐
+     * │ a  │
+     * ├────┤
+     * │ 10 │
+     * │ 20 │
+     * │ 30 │
+     * │ 40 │
+     * └────┘
+     * >>> df.limit(2, { offset: 1 })
+     * shape: (2, 1)
+     * ┌────┐
+     * │ a  │
+     * ├────┤
+     * │ 20 │
+     * │ 30 │
+     * └────┘
+     */
     limit(n: number, { offset, from }?: LimitOptions): DataFrame<T>;
+    /**
+     * Pivots columns from long format to a wide datagrid structure.
+     * @param config Pivot table configuration options.
+     * @param {string | string[]} config.index Key column(s) to use as new DataFrame rows.
+     * @param {string} config.columns Column whose distinct values become new wide column headers.
+     * @param {string} config.values Column whose cell values populate the pivoted grid cells.
+     * @param {AggFn | string} [config.agg] Aggregation function to apply when multiple values exist for a cell.
+     * @returns DataFrame
+     * @example
+     * >>> const df = $df.data({
+     * ...   year: [2020, 2020, 2021, 2021],
+     * ...   month: ["Jan", "Feb", "Jan", "Feb"],
+     * ...   revenue: [100, 150, 120, 180]
+     * ... })
+     * >>> df
+     * shape: (4, 3)
+     * ┌──────┬───────┬─────────┐
+     * │ year │ month │ revenue │
+     * ├──────┼───────┼─────────┤
+     * │ 2020 │ Jan   │ 100     │
+     * │ 2020 │ Feb   │ 150     │
+     * │ 2021 │ Jan   │ 120     │
+     * │ 2021 │ Feb   │ 180     │
+     * └──────┴───────┴─────────┘
+     * >>> df.pivot({ index: "year", columns: "month", values: "revenue" })
+     * shape: (2, 3)
+     * ┌──────┬─────┬─────┐
+     * │ year │ Jan │ Feb │
+     * ├──────┼─────┼─────┤
+     * │ 2020 │ 100 │ 150 │
+     * │ 2021 │ 120 │ 180 │
+     * └──────┴─────┴─────┘
+     */
     pivot<U extends RowRecord = any>(config: PivotOptions<T>): DataFrame<U>;
+    /**
+     * Renames columns based on a key-value mapping dictionary.
+     * @param mapping Dictionary mapping old column names to new names.
+     * @returns DataFrame
+     * @example
+     * >>> const df = $df.data({ old_name: [1] })
+     * >>> df
+     * shape: (1, 1)
+     * ┌──────────┐
+     * │ old_name │
+     * ├──────────┤
+     * │ 1        │
+     * └──────────┘
+     * >>> df.rename({ old_name: "new_name" })
+     * shape: (1, 1)
+     * ┌──────────┐
+     * │ new_name │
+     * ├──────────┤
+     * │ 1        │
+     * └──────────┘
+     */
     rename(mapping?: Partial<Record<keyof T, string>>): DataFrame<any>;
+    /**
+     * Reverses the row ordering of the DataFrame.
+     * @returns DataFrame
+     * @example
+     * >>> const df = $df.data({ a: [1, 2, 3] })
+     * >>> df
+     * shape: (3, 1)
+     * ┌───┐
+     * │ a │
+     * ├───┤
+     * │ 1 │
+     * │ 2 │
+     * │ 3 │
+     * └───┘
+     * >>> df.reverse()
+     * shape: (3, 1)
+     * ┌───┐
+     * │ a │
+     * ├───┤
+     * │ 3 │
+     * │ 2 │
+     * │ 1 │
+     * └───┘
+     */
     reverse(): DataFrame<T>;
+    /**
+     * Gets current DataFrameSchema dictionary mapping column names to DataType.
+     * @returns DataFrameSchema mapping.
+     * @example
+     * >>> const df = $df.data({ a: [1], b: ["text"] })
+     * >>> df
+     * shape: (1, 2)
+     * ┌───┬──────┐
+     * │ a │ b    │
+     * ├───┼──────┤
+     * │ 1 │ text │
+     * └───┴──────┘
+     * >>> df.schema
+     * { a: Float64, b: Utf8 }
+     */
     get schema(): DataFrameSchema;
+    /**
+     * Selects specific columns or evaluates column expressions.
+     * @param args Column names, column expressions, or object maps to evaluate.
+     * @returns DataFrame
+     * @example
+     * >>> const df = $df.data({ a: [1, 2], b: [10, 20] })
+     * >>> df
+     * shape: (2, 2)
+     * ┌───┬────┐
+     * │ a │ b  │
+     * ├───┼────┤
+     * │ 1 │ 10 │
+     * │ 2 │ 20 │
+     * └───┴────┘
+     * >>> df.select("a", $df.col("b").add(100).alias("b_plus"))
+     * shape: (2, 2)
+     * ┌───┬────────┐
+     * │ a │ b_plus │
+     * ├───┼────────┤
+     * │ 1 │ 110    │
+     * │ 2 │ 120    │
+     * └───┴────────┘
+     */
     select<U extends RowRecord = any>(...args: (string | IExpr | Record<string, any> | (string | IExpr | Record<string, any>)[])[]): DataFrame<U>;
+    /**
+     * Gets DataFrame dimensions as [height, width] tuple.
+     * @returns Tuple [height, width].
+     * @example
+     * >>> const df = $df.data({ a: [1, 2], b: ["x", "y"] })
+     * >>> df
+     * shape: (2, 2)
+     * ┌───┬───┐
+     * │ a │ b │
+     * ├───┼───┤
+     * │ 1 │ x │
+     * │ 2 │ y │
+     * └───┴───┘
+     * >>> df.shape
+     * [2, 2]
+     */
     get shape(): [number, number];
+    /**
+     * Slices a subset range of rows between start and end index.
+     * @param start Starting row index.
+     * @param end Optional ending row index (exclusive).
+     * @returns DataFrame
+     * @example
+     * >>> const df = $df.data({ a: [10, 20, 30, 40] })
+     * >>> df
+     * shape: (4, 1)
+     * ┌────┐
+     * │ a  │
+     * ├────┤
+     * │ 10 │
+     * │ 20 │
+     * │ 30 │
+     * │ 40 │
+     * └────┘
+     * >>> df.slice(1, 3)
+     * shape: (2, 1)
+     * ┌────┐
+     * │ a  │
+     * ├────┤
+     * │ 20 │
+     * │ 30 │
+     * └────┘
+     */
     slice(start: number, end?: number): DataFrame<T>;
+    /**
+     * Sorts DataFrame rows by one or more column expressions or custom sorters.
+     * @param config Sort configuration options.
+     * @param config.by Column name(s) or expression(s) to sort by.
+     * @param [config.descending] Sort order boolean or array of booleans per key (default `false`).
+     * @param [config.nullsLast] When `true` (default), places nulls at the end of sorted output.
+     * @param [config.custom] Optional dictionary mapping column names to custom comparator functions.
+     * @returns DataFrame
+     * @example
+     * >>> const df = $df.data({ val: [3, 1, 2] })
+     * >>> df
+     * shape: (3, 1)
+     * ┌─────┐
+     * │ val │
+     * ├─────┤
+     * │ 3   │
+     * │ 1   │
+     * │ 2   │
+     * └─────┘
+     * >>> df.sort({ by: "val" })
+     * shape: (3, 1)
+     * ┌─────┐
+     * │ val │
+     * ├─────┤
+     * │ 1   │
+     * │ 2   │
+     * │ 3   │
+     * └─────┘
+     */
     sort(config?: SortOptions<T>): DataFrame<T>;
+    /**
+     * Returns the last N rows as a new DataFrame.
+     * @param n Number of trailing rows to take (default 10).
+     * @returns DataFrame
+     * @example
+     * >>> const df = $df.data({ a: [1, 2, 3, 4] })
+     * >>> df
+     * shape: (4, 1)
+     * ┌───┐
+     * │ a │
+     * ├───┤
+     * │ 1 │
+     * │ 2 │
+     * │ 3 │
+     * │ 4 │
+     * └───┘
+     * >>> df.tail(2)
+     * shape: (2, 1)
+     * ┌───┐
+     * │ a │
+     * ├───┤
+     * │ 3 │
+     * │ 4 │
+     * └───┘
+     */
     tail(n?: number): DataFrame<T>;
+    /**
+     * Converts columns into a JavaScript dictionary mapping column keys to raw arrays.
+     * @returns Column dictionary map.
+     * @example
+     * >>> const df = $df.data({ a: [1, 2], b: ["x", "y"] })
+     * >>> df
+     * shape: (2, 2)
+     * ┌───┬───┐
+     * │ a │ b │
+     * ├───┼───┤
+     * │ 1 │ x │
+     * │ 2 │ y │
+     * └───┴───┘
+     * >>> df.to_dict()
+     * { a: Float64Array([1, 2]), b: ["x", "y"] }
+     */
     to_dict(): DataFrameColumns<T>;
+    /**
+     * Converts rows into an array of JavaScript objects.
+     * @returns Array of row record objects.
+     * @example
+     * >>> const df = $df.data({ a: [1], b: ["x"] })
+     * >>> df
+     * shape: (1, 2)
+     * ┌───┬───┐
+     * │ a │ b │
+     * ├───┼───┤
+     * │ 1 │ x │
+     * └───┴───┘
+     * >>> df.to_dicts()
+     * [{ a: 1, b: "x" }]
+     */
     to_dicts(): T[];
-    to_list<K extends keyof T>(nameOrExpr: K | IExpr): any[];
+    /**
+     * Evaluates a column expression or retrieves column values as a raw JavaScript array.
+     * @param nameOrExpr Target column name or column expression.
+     * @returns Array of column scalar values.
+     * @example
+     * >>> const df = $df.data({ a: [10, 20] })
+     * >>> df
+     * shape: (2, 1)
+     * ┌────┐
+     * │ a  │
+     * ├────┤
+     * │ 10 │
+     * │ 20 │
+     * └────┘
+     * >>> df.to_array("a")
+     * [10, 20]
+     */
+    to_array<K extends keyof T>(nameOrExpr: K | IExpr): any[];
+    /**
+     * Transposes rows into columns and columns into rows.
+     * @param [options] Transpose layout options.
+     * @param [options.include_header] When `true`, includes original column names as a new header column (default `false`).
+     * @param [options.header_name] Name of the header column when `include_header` is `true` (default `"column"`).
+     * @param [options.column_names] Column name or iterable of strings to use as transposed column headers.
+     * @returns DataFrame
+     * @example
+     * >>> const df = $df.data({ metric: ["sales", "clicks"], q1: [100, 500], q2: [120, 600] })
+     * >>> df
+     * shape: (2, 3)
+     * ┌────────┬─────┬─────┐
+     * │ metric │ q1  │ q2  │
+     * ├────────┼─────┼─────┤
+     * │ sales  │ 100 │ 120 │
+     * │ clicks │ 500 │ 600 │
+     * └────────┴─────┴─────┘
+     * >>> df.transpose({ include_header: true, header_name: "metric" })
+     * shape: (2, 3)
+     * ┌────────┬──────────┬──────────┐
+     * │ metric │ column_0 │ column_1 │
+     * ├────────┼──────────┼──────────┤
+     * │ q1     │ 100      │ 500      │
+     * │ q2     │ 120      │ 600      │
+     * └────────┴──────────┴──────────┘
+     */
     transpose({ include_header: includeHeader, header_name: headerName, column_names: colNamesOpt }?: TransposeOptions): DataFrame<any>;
+    /**
+     * Filters distinct unique rows matching target key columns.
+     * @param columns Target column or array of column names to evaluate uniqueness.
+     * @returns DataFrame
+     * @example
+     * >>> const df = $df.data({ a: [1, 2, 2], b: ["x", "y", "y"] })
+     * >>> df
+     * shape: (3, 2)
+     * ┌───┬───┐
+     * │ a │ b │
+     * ├───┼───┤
+     * │ 1 │ x │
+     * │ 2 │ y │
+     * │ 2 │ y │
+     * └───┴───┘
+     * >>> df.unique()
+     * shape: (2, 2)
+     * ┌───┬───┐
+     * │ a │ b │
+     * ├───┼───┤
+     * │ 1 │ x │
+     * │ 2 │ y │
+     * └───┴───┘
+     */
     unique<K extends keyof T>(columns?: K | K[]): DataFrame<T>;
+    /**
+     * Unpivots a wide DataFrame into a long format structure.
+     * @param config Unpivot configuration options.
+     * @param config.idVars Key column(s) to retain as identifier variables.
+     * @param config.valueVars Column(s) to unpivot into variable-value pairs.
+     * @param [config.varName] Name for the new variable column holding old column headers (default `"variable"`).
+     * @param [config.valueName] Name for the new value column holding cell values (default `"value"`).
+     * @returns DataFrame
+     * @example
+     * >>> const df = $df.data({ year: [2020], Jan: [100], Feb: [150] })
+     * >>> df
+     * shape: (1, 3)
+     * ┌──────┬─────┬─────┐
+     * │ year │ Jan │ Feb │
+     * ├──────┼─────┼─────┤
+     * │ 2020 │ 100 │ 150 │
+     * └──────┴─────┴─────┘
+     * >>> df.unpivot({ idVars: "year", valueVars: ["Jan", "Feb"], varName: "month", valueName: "revenue" })
+     * shape: (2, 3)
+     * ┌──────┬───────┬─────────┐
+     * │ year │ month │ revenue │
+     * ├──────┼───────┼─────────┤
+     * │ 2020 │ Jan   │ 100     │
+     * │ 2020 │ Feb   │ 150     │
+     * └──────┴───────┴─────────┘
+     */
     unpivot<U extends RowRecord = any>(config: UnpivotOptions<T>): DataFrame<U>;
+    /**
+     * Concatenates DataFrames vertically. Alias for concat({ how: "vertical" }).
+     * @param other Single DataFrame or array of DataFrames to append vertically.
+     * @returns DataFrame
+     * @example
+     * >>> const df1 = $df.data({ a: [1] })
+     * >>> df1
+     * shape: (1, 1)
+     * ┌───┐
+     * │ a │
+     * ├───┤
+     * │ 1 │
+     * └───┘
+     * >>> const df2 = $df.data({ a: [2] })
+     * >>> df1.vstack(df2)
+     * shape: (2, 1)
+     * ┌───┐
+     * │ a │
+     * ├───┤
+     * │ 1 │
+     * │ 2 │
+     * └───┘
+     */
     vstack<U extends RowRecord = any>(other: ConcatItem | ConcatItem[]): DataFrame<U>;
+    /**
+     * Gets width (total column count) of the DataFrame.
+     * @returns Number of columns.
+     * @example
+     * >>> const df = $df.data({ a: [1], b: [2] })
+     * >>> df
+     * shape: (1, 2)
+     * ┌───┬───┐
+     * │ a │ b │
+     * ├───┼───┤
+     * │ 1 │ 2 │
+     * └───┴───┘
+     * >>> df.width
+     * 2
+     */
     get width(): number;
     private _normalizeArgs;
+    /**
+     * Adds new columns or updates existing ones using column expressions.
+     * @param args Expressions or field objects defining column calculations.
+     * @returns DataFrame
+     * @example
+     * >>> const df = $df.data({ a: [1, 2] })
+     * >>> df
+     * shape: (2, 1)
+     * ┌───┐
+     * │ a │
+     * ├───┤
+     * │ 1 │
+     * │ 2 │
+     * └───┘
+     * >>> df.with_columns($df.col("a").add(10).alias("b"))
+     * shape: (2, 2)
+     * ┌───┬────┐
+     * │ a │ b  │
+     * ├───┼────┤
+     * │ 1 │ 11 │
+     * │ 2 │ 12 │
+     * └───┴────┘
+     */
     with_columns(...args: (string | IExpr | Record<string, any> | (string | IExpr | Record<string, any>)[])[]): DataFrame<any>;
+    /**
+     * Appends an incremental index column.
+     * @param name Name of index column (default "index").
+     * @param offset Starting numeric index offset (default 0).
+     * @returns DataFrame
+     * @example
+     * >>> const df = $df.data({ val: ["a", "b"] })
+     * >>> df
+     * shape: (2, 1)
+     * ┌─────┐
+     * │ val │
+     * ├─────┤
+     * │ a   │
+     * │ b   │
+     * └─────┘
+     * >>> df.with_row_index("idx")
+     * shape: (2, 2)
+     * ┌─────┬─────┐
+     * │ idx │ val │
+     * ├─────┼─────┤
+     * │ 0   │ a   │
+     * │ 1   │ b   │
+     * └─────┴─────┘
+     */
     with_row_index(name?: string, offset?: number): DataFrame<any>;
+    /**
+     * Writes DataFrame rows to JSON format string or file/stream target.
+     * @param [file] Target file path or writable stream target (optional).
+     * @param [options] JSON formatting and replacer options.
+     * @param [options.format] JSON output format structure (`"json"` or `"ndjson"`). Default `"json"`.
+     * @param [options.replacerOptions] Serialization options including custom `replacer` function or replacer array.
+     * @returns JSON string representation.
+     * @example
+     * >>> const df = $df.data({ a: [1], b: ["x"] })
+     * >>> df
+     * shape: (1, 2)
+     * ┌───┬───┐
+     * │ a │ b │
+     * ├───┼───┤
+     * │ 1 │ x │
+     * └───┴───┘
+     * >>> df.write_json()
+     * '[{"a":1,"b":"x"}]'
+     */
     write_json(file?: string | {
         write: (str: string) => void;
     }, { format, replacerOptions }?: WriteJSONOptions): string;
+    /**
+     * Writes DataFrame to CSV format string or file/stream target.
+     * @param [file] Target file path or writable stream target (optional).
+     * @param [options] CSV formatting options.
+     * @param [options.delimiter] Column delimiter character (default `","`).
+     * @param [options.header] When `true` (default), includes column header row.
+     * @param [options.quoteChar] Character used to enclose fields containing special characters (default `'"'`).
+     * @returns CSV string output.
+     * @example
+     * >>> const df = $df.data({ a: [1], b: ["x"] })
+     * >>> df
+     * shape: (1, 2)
+     * ┌───┬───┐
+     * │ a │ b │
+     * ├───┼───┤
+     * │ 1 │ x │
+     * └───┴───┘
+     * >>> df.write_csv()
+     * "a,b\n1,x"
+     */
     write_csv(file?: string | {
         write: (str: string) => void;
     }, options?: WriteCSVOptions): string;