df-script 1.7.0 → 1.8.0

package/dist/dataframe/dataframe.d.ts

@@ -1,6 +1,6 @@
 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.
  */
@@ -50,11 +50,11 @@ export declare class DataFrame<T extends RowRecord = any> {
     /**
      * 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
+     * @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):
@@ -105,8 +105,8 @@ export declare class DataFrame<T extends RowRecord = any> {
     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
+     * @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
@@ -127,8 +127,8 @@ export declare class DataFrame<T extends RowRecord = any> {
     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
+     * @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
@@ -168,11 +168,11 @@ export declare class DataFrame<T extends RowRecord = any> {
     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
+     * @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
@@ -194,11 +194,11 @@ export declare class DataFrame<T extends RowRecord = any> {
     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
+     * @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
@@ -223,8 +223,8 @@ export declare class DataFrame<T extends RowRecord = any> {
     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
+     * @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
@@ -264,8 +264,8 @@ export declare class DataFrame<T extends RowRecord = any> {
     get_schema(): DataFrameSchema;
     /**
      * Groups rows by key columns to prepare for aggregations.
-     * @param keys Column name or array of key column names.
-     * @returns GroupedData
+     * @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
@@ -313,6 +313,35 @@ export declare class DataFrame<T extends RowRecord = any> {
      * └───┘
      */
     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.
@@ -333,10 +362,10 @@ export declare class DataFrame<T extends RowRecord = any> {
     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
+     * @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
@@ -360,10 +389,10 @@ export declare class DataFrame<T extends RowRecord = any> {
     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
+     * @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
@@ -384,9 +413,9 @@ export declare class DataFrame<T extends RowRecord = any> {
     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.
+     * @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
@@ -443,13 +472,32 @@ export declare class DataFrame<T extends RowRecord = any> {
         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
+     * 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
@@ -471,13 +519,85 @@ export declare class DataFrame<T extends RowRecord = any> {
      * └────┴─────┴─────┘
      */
     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 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
+     * @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
@@ -536,8 +656,8 @@ export declare class DataFrame<T extends RowRecord = any> {
     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
+     * @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
@@ -599,8 +719,8 @@ export declare class DataFrame<T extends RowRecord = any> {
     get schema(): DataFrameSchema;
     /**
      * Selects specific columns or evaluates column expressions.
-     * @param args Column names, column expressions, or object maps to evaluate.
-     * @returns DataFrame
+     * @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
@@ -640,9 +760,9 @@ export declare class DataFrame<T extends RowRecord = any> {
     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
+     * @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
@@ -667,12 +787,12 @@ export declare class DataFrame<T extends RowRecord = any> {
     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
+     * @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
@@ -756,8 +876,8 @@ export declare class DataFrame<T extends RowRecord = any> {
     to_dicts(): T[];
     /**
      * 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.
+     * @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
@@ -774,11 +894,11 @@ export declare class DataFrame<T extends RowRecord = any> {
     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
+     * @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
@@ -801,8 +921,8 @@ export declare class DataFrame<T extends RowRecord = any> {
     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
+     * @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
@@ -826,12 +946,12 @@ export declare class DataFrame<T extends RowRecord = any> {
     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
+     * @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
@@ -853,8 +973,8 @@ export declare class DataFrame<T extends RowRecord = any> {
     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
+     * @param {ConcatItem | ConcatItem[]} other Single DataFrame or array of DataFrames to append vertically.
+     * @returns {DataFrame}
      * @example
      * >>> const df1 = $df.data({ a: [1] })
      * >>> df1
@@ -894,8 +1014,8 @@ export declare class DataFrame<T extends RowRecord = any> {
     private _normalizeArgs;
     /**
      * Adds new columns or updates existing ones using column expressions.
-     * @param args Expressions or field objects defining column calculations.
-     * @returns DataFrame
+     * @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
@@ -918,9 +1038,9 @@ export declare class DataFrame<T extends RowRecord = any> {
     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
+     * @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
@@ -943,11 +1063,31 @@ export declare class DataFrame<T extends RowRecord = any> {
     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.
+     * @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
@@ -965,12 +1105,12 @@ export declare class DataFrame<T extends RowRecord = any> {
     }, { 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.
+     * @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

package/dist/dataframe/types.d.ts

@@ -3,7 +3,8 @@ import type { IExpr, AggFn, RowRecord, DataFrameSchema, JSONFormat } from "../ty
 import type { DataFrame } from "./dataframe";
 import type { JSONParseOptions, SafeJsonReplacerOptions, NDJSONParseOptions } from "../utils";
 export type { JSONParseOptions, SafeJsonReplacerOptions, NDJSONParseOptions };
-export type JoinType = "inner" | "left" | "outer" | "right";
+export type JoinType = "inner" | "outer" | "left" | "right" | "semi" | "anti" | "cross";
+export type JoinMaintainOrder = "none" | "left" | "right" | "left_right" | "right_left";
 export type LimitPosition = "start" | "end";
 export type GroupMap = Map<string, number[]>;
 export interface LimitOptions {
@@ -22,11 +23,32 @@ export interface PivotOptions<T> {
     values: keyof T;
     agg?: AggFn<any> | string;
 }
-export interface JoinOptions<T, U extends RowRecord = any> {
+export interface JoinOptions<T = any, U extends RowRecord = any> {
     other: DataFrame<U>;
-    on: (keyof T & keyof U) | (keyof T & keyof U)[];
+    on?: (keyof T & keyof U) | (keyof T & keyof U)[];
+    leftOn?: (keyof T) | (keyof T)[];
+    rightOn?: (keyof U) | (keyof U)[];
     how?: JoinType;
     suffixes?: [string, string];
+    join_nulls?: boolean;
+    coalesce?: boolean;
+    maintain_order?: JoinMaintainOrder | boolean;
+}
+export type AsofJoinStrategy = "backward" | "forward" | "nearest";
+export interface AsofJoinOptions<T = any, U extends RowRecord = any> {
+    other: DataFrame<U>;
+    on?: (keyof T & keyof U);
+    leftOn?: (keyof T);
+    rightOn?: (keyof U);
+    by?: (keyof T & keyof U) | (keyof T & keyof U)[];
+    leftBy?: (keyof T) | (keyof T)[];
+    rightBy?: (keyof U) | (keyof U)[];
+    strategy?: AsofJoinStrategy;
+    tolerance?: number | string;
+    allow_exact_matches?: boolean;
+    suffixes?: [string, string];
+    coalesce?: boolean;
+    check_sorted?: boolean;
 }
 export interface UnpivotOptions<T> {
     idVars: (keyof T) | (keyof T)[];

package/dist/dataframe/utils.d.ts

@@ -1,5 +1,7 @@
 /** @internalfile */
-import type { IExpr, ColumnData, ColumnDict, RegisteredDataType } from "../types";
+import type { IExpr, ColumnData, ColumnDict, RegisteredDataType, DataFrameSchema, RowRecord } from "../types";
+import type { JoinOptions, AsofJoinOptions } from "./types";
+import { DataFrame } from "./dataframe";
 export declare function resolveWindowExpr(expr: IExpr, columns: ColumnDict, height: number): ColumnData;
 export declare function rowsToColumns(rows: any[]): {
     columns: ColumnDict;
@@ -18,3 +20,21 @@ export declare function coerceColumn(col: ColumnData, type: RegisteredDataType,
 export declare function writeStringToFileOrStream(file: string | {
     write: (str: string) => void;
 } | undefined, content: string): void;
+/**
+ * Generic key-alignment engine computing positional row index mappings (leftIndex <-> rightIndex)
+ * between two columnar datasets based on key hashing.
+ * Reusable for Joins, Set Operations (Intersect/Difference), Upserts, and Alignments.
+ */
+export declare function alignKeyIndices(leftCols: ColumnDict, rightCols: ColumnDict, leftHeight: number, rightHeight: number, leftKeys: string[], rightKeys: string[], options?: Partial<JoinOptions>): {
+    leftIndices: number[];
+    rightIndices: (number | null)[];
+};
+export declare function alignAsofIndices(leftCols: ColumnDict, rightCols: ColumnDict, leftHeight: number, rightHeight: number, leftOnKey: string, rightOnKey: string, leftByKeys: string[], rightByKeys: string[], options?: AsofJoinOptions): {
+    leftIndices: number[];
+    rightIndices: (number | null)[];
+};
+export declare function materializeJoinedDataFrame<R extends RowRecord = any>(leftCols: ColumnDict, rightCols: ColumnDict, leftSchema: DataFrameSchema, rightSchema: DataFrameSchema, leftIndices: number[], rightIndices: (number | null)[], leftKeysStr: string[], rightKeysStr: string[], options?: {
+    suffixes?: [string, string];
+    coalesce?: boolean;
+    how?: string;
+}): DataFrame<R>;

package/dist/datatypes/types.d.ts

@@ -1,6 +1,6 @@
 /** @typefile */
 import { DataType, SignedIntegerType, UnsignedIntegerType, FloatDataType, TemporalDataType, NestedDataType, NumericDataType } from "./DataType";
-import type { RowRecord } from "../types";
+import type { RowRecord, DatetimeTimeUnit } from "../types";
 export declare class Int8Type extends SignedIntegerType {
     readonly name = "Int8";
     coerce(val: unknown): number | null;
@@ -159,11 +159,14 @@ export declare class DateType extends TemporalDataType<Date | null> {
 }
 export declare const DateDataType: DateType;
 /**
- * Date and time type (year, month, day, hour, minute, second, millisecond).
- *
+ * Date and time type (year, month, day, hour, minute, second, millisecond)
+ * with timeUnit precision and optional timezone awareness.
  */
 export declare class DatetimeType extends TemporalDataType<Date | null> {
     readonly name = "Datetime";
+    readonly timeUnit: DatetimeTimeUnit;
+    readonly timeZone: string | null;
+    constructor(timeUnit?: DatetimeTimeUnit, timeZone?: string | null);
     coerce(val: unknown): Date | null;
     equals(other: DataType): boolean;
     allocate(size: number): (Date | null)[];
@@ -178,6 +181,8 @@ export declare class TimeType extends TemporalDataType<string | null> {
 export declare const Time: TimeType;
 export declare class DurationType extends TemporalDataType<number | null> {
     readonly name = "Duration";
+    readonly timeUnit: DatetimeTimeUnit;
+    constructor(timeUnit?: DatetimeTimeUnit);
     coerce(val: unknown): number | null;
     equals(other: DataType): boolean;
     allocate(size: number): (number | null)[];

package/dist/exceptions/index.d.ts

@@ -35,4 +35,14 @@ export declare class ComputeError extends DFScriptError {
  */
 export declare class ShapeError extends DFScriptError {
 }
+/**
+ * Error thrown when a parameter or argument provided to a function is invalid.
+ */
+export declare class InvalidArgumentError extends DFScriptError {
+}
+/**
+ * Error thrown during file I/O or streaming operations.
+ */
+export declare class IOStreamError extends DFScriptError {
+}
 export * from "./utils";

package/dist/exceptions/utils.d.ts

@@ -1,3 +1,5 @@
 import type { ColumnDict } from "../types";
 export declare function assertColumnExists(columnName: string, columns: ColumnDict, context: string, suffix?: string): void;
 export declare function assertHeight(columns: ColumnDict, height?: number): number;
+export declare function assertNotNull<T>(value: T | null | undefined, message?: string): T;
+export declare function assertValidArgument(condition: boolean, message: string): void;