df-script 1.6.0 → 1.8.0

package/dist/dataframe/dataframe.d.ts

@@ -1,58 +1,1128 @@
 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";
+import type { LimitOptions, SortOptions, PivotOptions, JoinOptions, AsofJoinOptions, 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 {ConcatItem | ConcatItem[]} items Single DataFrame or array of DataFrames/rows to concatenate.
+     * @param {ConcatOptions} [options] Configuration options for concatenation layout and strictness.
+     * @param {ConcatHow} [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 {boolean} [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 {(K | K[])[]} 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 {string | string[]} [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 {IntoExpr | IntoExpr[]} columns Target column expression or array column name to explode.
+     * @param {ExplodeOptions} [options] Configuration options for empty array and null handling.
+     * @param {boolean} [options.empty_as_null] When `true`, converts empty arrays to `null` rows.
+     * @param {boolean} [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 {FillNullOptions} [options] Configuration options for null replacement.
+     * @param {any} [options.value] Scalar replacement value or dict mapping column names to values.
+     * @param {FillNullStrategy} [options.strategy] Statistical filling strategy (`"zero"`, `"mean"`, `"min"`, `"max"`, `"forward"`, `"backward"`).
+     * @param {number} [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 {(IExpr | ((row: T) => any))[]} 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 {K | K[]} 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>;
+    /**
+     * Creates a deep copy of the current DataFrame instance, duplicating all underlying column data arrays and schema metadata.
+     * Modifying columns or values in the cloned DataFrame will not mutate the original.
+     * @returns {DataFrame<T>}
+     * @example
+     * >>> // Example 1: Basic cloning and independence
+     * >>> const df1 = $df.data({ a: [10, 20], b: ["x", "y"] })
+     * >>> const copy1 = df1.clone()
+     * >>> copy1
+     * shape: (2, 2)
+     * ┌────┬───┐
+     * │ a  │ b │
+     * ├────┼───┤
+     * │ 10 │ x │
+     * │ 20 │ y │
+     * └────┴───┘
+     *
+     * >>> // Example 2: Verifying mutation isolation
+     * >>> copy1._columns.a[0] = 999
+     * >>> df1.to_dicts()[0].a
+     * 10
+     *
+     * >>> // Example 3: Cloning empty DataFrames
+     * >>> const emptyDf = $df.data({ x: [], y: [] })
+     * >>> const emptyCopy = emptyDf.clone()
+     * >>> emptyCopy.height
+     * 0
+     */
+    clone(): 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 {ConcatItem | ConcatItem[]} other DataFrame or array of DataFrames to append side-by-side.
+     * @param {HorizontalConcatOptions} [options] Horizontal concat configuration options.
+     * @param {boolean} [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 {number} index Target column index position.
+     * @param {string} name Name of the inserted column.
+     * @param {IntoExpr} 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 {number} [row] Row index position.
+     * @param {number | string} [column] Column index or column name string.
+     * @returns {any} 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 a specified join strategy.
+     * @param {JoinOptions} config Join configuration object.
+     * @param {DataFrame} config.other Right DataFrame to join with.
+     * @param {string | string[]} [config.on] Join key column name or array of key column names that exist in both DataFrames.
+     * @param {string | string[]} [config.leftOn] Join key column(s) in the left DataFrame when key names differ.
+     * @param {string | string[]} [config.rightOn] Join key column(s) in the right DataFrame when key names differ.
+     * @param {JoinType} [config.how] Join strategy. Default `"inner"`.
+     *   - `"inner"` — Only rows with matching keys in both DataFrames.
+     *   - `"left"` — All left rows; unmatched right values are `null`.
+     *   - `"right"` — All right rows; unmatched left values are `null`.
+     *   - `"outer"` — All rows from both sides; unmatched values are `null`.
+     *   - `"semi"` — Left rows that have a match in the right DataFrame (only left columns retained).
+     *   - `"anti"` — Left rows that have **no** match in the right DataFrame (only left columns retained).
+     *   - `"cross"` — Cartesian product pairing every left row with every right row (keyless).
+     * @param {[string, string]} [config.suffixes] Suffix tuple `[leftSuffix, rightSuffix]` appended to overlapping
+     *   non-key column names (default `["", "_right"]`). Ignored for `"semi"` and `"anti"` joins.
+     * @param {boolean} [config.join_nulls] If `true`, null key values are treated as equal and will match each other
+     *   across DataFrames. Default `false` (SQL-standard: `NULL != NULL`).
+     * @param {boolean} [config.coalesce] Coalescing behavior for join key columns. Default `true`. If `true`, coalesces join key values into left key columns and drops right key columns. If `false`, keeps join key columns separate.
+     * @param {JoinMaintainOrder | boolean} [config.maintain_order] Row order preservation strategy. Default `"none"`.
+     *   - `"none"` (or `false`) — No specific ordering is desired.
+     *   - `"left"` (or `true`) — Preserves the order of the left DataFrame.
+     *   - `"right"` — Preserves the order of the right DataFrame.
+     *   - `"left_right"` — Preserves the order of the left DataFrame first, then the right.
+     *   - `"right_left"` — Preserves the order of the right DataFrame first, then the left.
+     * @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>;
+    /**
+     * Performs an asof (as-of) join for inexact matching on ordered numeric or temporal key columns.
+     *
+     * Similar to a left join, but instead of exact key equality, matches the nearest key row from the right
+     * DataFrame according to the selected `strategy` ("backward", "forward", or "nearest") and optional `tolerance`.
+     * Both DataFrames must be sorted in ascending order on their respective `on` / `leftOn` / `rightOn` join keys.
+     *
+     * @param {AsofJoinOptions} options Asof join configuration options.
+     * @param {DataFrame} options.other The right DataFrame to join with.
+     * @param {string} [options.on] Column name to join on (must exist in both DataFrames and be sorted ascending).
+     * @param {string} [options.leftOn] Left DataFrame join key column name.
+     * @param {string} [options.rightOn] Right DataFrame join key column name.
+     * @param {string | string[]} [options.by] Optional exact-match group column(s) present in both DataFrames.
+     * @param {string | string[]} [options.leftBy] Group column(s) for exact key matching in left DataFrame.
+     * @param {string | string[]} [options.rightBy] Group column(s) for exact key matching in right DataFrame.
+     * @param {AsofJoinStrategy} [options.strategy] Match search strategy. Default `"backward"`.
+     *   - `"backward"` — Matches the latest right row where `rightKey <= leftKey`.
+     *   - `"forward"` — Matches the earliest right row where `rightKey >= leftKey`.
+     *   - `"nearest"` — Matches the right row with the absolute nearest key value to `leftKey`.
+     * @param {number | string} [options.tolerance] Maximum allowed distance between left key and right key.
+     * @param {boolean} [options.allow_exact_matches] Whether exact key matches are permitted. Default `true`.
+     * @param {[string, string]} [options.suffixes] Column name suffixes `[leftSuffix, rightSuffix]` to resolve name collisions. Default `["", "_right"]`.
+     * @param {boolean} [options.coalesce] Coalescing behavior for join key columns. Default `true`.
+     * @param {boolean} [options.check_sorted] Whether to verify that join keys are sorted ascending prior to matching. Default `true`.
+     * @returns A new DataFrame containing the joined results.
+     *
+     * @namespace df
+     * @category DataFrame
+     * @syntax
+     * df.join_asof({
+     *   other,
+     *   on,
+     *   leftOn,
+     *   rightOn,
+     *   by,
+     *   leftBy,
+     *   rightBy,
+     *   strategy,
+     *   tolerance,
+     *   allow_exact_matches,
+     *   suffixes,
+     *   coalesce,
+     *   check_sorted
+     * })
+     * @example
+     * >>> const trades = new DataFrame([
+     * ...   { time: 1000, ticker: "AAPL", price: 150.0 },
+     * ...   { time: 1005, ticker: "AAPL", price: 150.5 },
+     * ...   { time: 1015, ticker: "AAPL", price: 151.0 }
+     * ... ]);
+     * >>> const quotes = new DataFrame([
+     * ...   { time: 998, ticker: "AAPL", bid: 149.9 },
+     * ...   { time: 1004, ticker: "AAPL", bid: 150.4 },
+     * ...   { time: 1010, ticker: "AAPL", bid: 150.8 }
+     * ... ]);
+     * >>> const joined = trades.join_asof({
+     * ...   other: quotes,
+     * ...   on: "time",
+     * ...   by: "ticker",
+     * ...   strategy: "backward"
+     * ... });
+     * >>> joined
+     * shape: (3, 4)
+     * ┌──────┬────────┬───────┬──────┐
+     * │ time │ ticker │ price │ bid  │
+     * ├──────┼────────┼───────┼──────┤
+     * │ 1000 │ AAPL   │ 150.0 │ 149.9│
+     * │ 1005 │ AAPL   │ 150.5 │ 150.4│
+     * │ 1015 │ AAPL   │ 151.0 │ 150.8│
+     * └──────┴────────┴───────┴──────┘
+     */
+    join_asof<U extends RowRecord = any, R extends RowRecord = any>(options: AsofJoinOptions<T, U>): DataFrame<R>;
+    /**
+     * Limits the output to N rows starting from offset.
+     * @param {number} n Maximum number of rows to take.
+     * @param {LimitOptions} [options] Offset and slice direction options.
+     * @param {number} [options.offset] Number of rows to skip before taking `n` rows (default 0).
+     * @param {LimitPosition} [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 {Partial<Record<keyof T, string>>} [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 {(string | IExpr | Record<string, any> | (string | IExpr | Record<string, any>)[])[]} 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 {number} start Starting row index.
+     * @param {number} [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 {SortOptions<T>} [config] Sort configuration options.
+     * @param {keyof T | (keyof T)[] | IExpr | IExpr[]} config.by Column name(s) or expression(s) to sort by.
+     * @param {boolean | boolean[]} [config.descending] Sort order boolean or array of booleans per key (default `false`).
+     * @param {boolean} [config.nullsLast] When `true` (default), places nulls at the end of sorted output.
+     * @param {Partial<Record<keyof T, (a: any, b: any) => number>>} [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[];
+    /**
+     * Evaluates a column expression or retrieves column values as a raw JavaScript array.
+     * @param {K | IExpr} nameOrExpr Target column name or column expression.
+     * @returns {any[]} 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 {TransposeOptions} [options] Transpose layout options.
+     * @param {boolean} [options.include_header] When `true`, includes original column names as a new header column (default `false`).
+     * @param {string} [options.header_name] Name of the header column when `include_header` is `true` (default `"column"`).
+     * @param {string | Iterable<string>} [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 {K | K[]} [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 {UnpivotOptions<T>} config Unpivot configuration options.
+     * @param {keyof T | (keyof T)[]} config.idVars Key column(s) to retain as identifier variables.
+     * @param {keyof T | (keyof T)[]} config.valueVars Column(s) to unpivot into variable-value pairs.
+     * @param {string} [config.varName] Name for the new variable column holding old column headers (default `"variable"`).
+     * @param {string} [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 {ConcatItem | ConcatItem[]} 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 {(string | IExpr | Record<string, any> | (string | IExpr | Record<string, any>)[])[]} 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 {string} [name] Name of index column (default "index").
+     * @param {number} [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 {string | { write: (str: string) => void }} [file] Target file path or writable stream target (optional).
+     * @param {WriteJSONOptions} [options] JSON formatting and replacer options.
+     * @param {JSONFormat} [options.format] JSON output format structure (`"json"` or `"ndjson"`). Default `"json"`.
+     * @param {SafeJsonReplacerOptions} [options.replacerOptions] Serialization options for custom type handling.
+     * @param {(v: Date) => string} [options.replacerOptions.formatDate] Custom formatter function for Date objects. Ignored if `onDate` is specified.
+     * @param {"string" | "number"} [options.replacerOptions.bigintStrategy] Convert BigInts to numeric strings or numbers if safe. Default `"string"`.
+     * @param {(v: bigint) => any} [options.replacerOptions.onBigInt] Custom serialization override for BigInt values.
+     * @param {(v: any) => any} [options.replacerOptions.onTypedArray] Custom serialization override for TypedArray values.
+     * @param {(v: Set<any>) => any} [options.replacerOptions.onSet] Custom serialization override for Set objects.
+     * @param {(v: Map<any, any>) => any} [options.replacerOptions.onMap] Custom serialization override for Map objects.
+     * @param {(v: RegExp) => any} [options.replacerOptions.onRegExp] Custom serialization override for RegExp objects.
+     * @param {(v: Date) => any} [options.replacerOptions.onDate] Custom serialization override for Date objects. Takes precedence over `formatDate`.
+     * @param {(v: Error) => any} [options.replacerOptions.onError] Custom serialization override for Error objects. Prevents empty `{}` output.
+     * @param {(v: URLSearchParams) => any} [options.replacerOptions.onURLSearchParams] Custom serialization override for URLSearchParams objects.
+     * @param {(this: any, k: string, v: any) => any} [options.replacerOptions.onCustom] Catch-all serialization override for custom types. Runs after native type checks.
+     * @param {boolean} [options.replacerOptions.handleCircular] If `true`, handles circular references by replacing them instead of throwing.
+     * @param {(this: any, k: string, v: any) => any} [options.replacerOptions.onCircular] Custom fallback when a circular reference is found. Default `"[Circular]"`.
+     * @param {boolean} [options.replacerOptions.voidBigIntReplacement] If `true`, disables the default safe serialization for BigInt values.
+     * @param {boolean} [options.replacerOptions.voidTypedArrayReplacement] If `true`, disables the default safe serialization for TypedArray values.
+     * @param {boolean} [options.replacerOptions.voidSetReplacement] If `true`, disables the default safe serialization for Set objects.
+     * @param {boolean} [options.replacerOptions.voidMapReplacement] If `true`, disables the default safe serialization for Map objects.
+     * @param {boolean} [options.replacerOptions.voidRegExpReplacement] If `true`, disables the default safe serialization for RegExp objects.
+     * @param {boolean} [options.replacerOptions.voidDateReplacement] If `true`, disables the default safe serialization for Date objects.
+     * @param {((this: any, k: string, v: any) => any) | (string | number)[] | null} [options.replacerOptions.replacer] Custom replacer function or array whitelist that runs first for pre-processing.
+     * @returns {string} 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 {string | { write: (str: string) => void }} [file] Target file path or writable stream target (optional).
+     * @param {WriteCSVOptions} [options] CSV formatting options.
+     * @param {string} [options.delimiter] Column delimiter character (default `","`).
+     * @param {boolean} [options.header] When `true` (default), includes column header row.
+     * @param {string} [options.quoteChar] Character used to enclose fields containing special characters (default `'"'`).
+     * @returns {string} 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;