df-script 1.6.0 → 1.8.0

package/dist/dataframe/grouped/grouped.d.ts

@@ -1,14 +1,49 @@
 import { DataFrame } from "../dataframe";
 import type { GroupMap } from "../types";
 import type { IExpr, ColumnDict, RowRecord, DataFrameSchema } from "../../types";
+/**
+ * Represents a DataFrame grouped by key columns, supporting aggregation operations.
+ * @namespace df
+ * @category DataFrame
+ * @syntax df.groupby(...).{symbol}(...)
+ */
 export declare class GroupedData<T, K extends keyof T> {
-    private groups;
-    private keys;
-    private allKeys;
-    private parentColumns;
-    private parentHeight;
-    private parentSchema;
+    private _groups;
+    private _keys;
+    private _allKeys;
+    private _parentColumns;
+    private _parentHeight;
+    private _parentSchema;
     constructor(groups: GroupMap, keys: K[], allKeys: (keyof T)[], parentColumns: ColumnDict, parentHeight: number, parentSchema: DataFrameSchema);
+    /**
+     * Converts group keys back into a single distinct DataFrame without aggregations.
+     * @returns DataFrame
+     * @example
+     * >>> const df = $df.data({ group: ["A", "A", "B"], val: [1, 2, 3] })
+     * >>> df.groupby("group").to_dataframe()
+     * shape: (2, 1)
+     * ┌───────┐
+     * │ group │
+     * ├───────┤
+     * │ A     │
+     * │ B     │
+     * └───────┘
+     */
     to_dataframe<U extends RowRecord = any>(): DataFrame<U>;
+    /**
+     * Aggregates grouped partitions using aggregation column expressions.
+     * @param exprs One or more aggregation column expressions.
+     * @returns DataFrame
+     * @example
+     * >>> const df = $df.data({ group: ["A", "A", "B"], val: [10, 20, 30] })
+     * >>> df.groupby("group").agg($df.col("val").sum().alias("sum_val"))
+     * shape: (2, 2)
+     * ┌───────┬─────────┐
+     * │ group │ sum_val │
+     * ├───────┼─────────┤
+     * │ A     │ 30      │
+     * │ B     │ 30      │
+     * └───────┴─────────┘
+     */
     agg<U extends RowRecord = any>(...exprs: (IExpr | any)[]): DataFrame<U>;
 }

package/dist/dataframe/types.d.ts

@@ -1,8 +1,10 @@
+/** @typefile */
 import type { IExpr, AggFn, RowRecord, DataFrameSchema, JSONFormat } from "../types";
 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 {
@@ -21,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,4 +1,7 @@
-import type { IExpr, ColumnData, ColumnDict, RegisteredDataType } from "../types";
+/** @internalfile */
+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;
@@ -17,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,5 +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;
@@ -14,6 +15,10 @@ export declare class Int16Type extends SignedIntegerType {
     allocate(size: number): Int16Array;
 }
 export declare const Int16: Int16Type;
+/**
+ * 32-bit signed integer type (values from -2,147,483,648 to 2,147,483,647).
+ *
+ */
 export declare class Int32Type extends SignedIntegerType {
     readonly name = "Int32";
     coerce(val: unknown): number | null;
@@ -21,6 +26,10 @@ export declare class Int32Type extends SignedIntegerType {
     allocate(size: number): Int32Array;
 }
 export declare const Int32: Int32Type;
+/**
+ * 64-bit signed integer type (represented as JavaScript BigInt).
+ *
+ */
 export declare class Int64Type extends SignedIntegerType<bigint | null> {
     readonly name = "Int64";
     coerce(val: unknown): bigint | null;
@@ -63,6 +72,10 @@ export declare class Float32Type extends FloatDataType {
     allocate(size: number): Float32Array;
 }
 export declare const Float32: Float32Type;
+/**
+ * 64-bit double precision floating point number type.
+ *
+ */
 export declare class Float64Type extends FloatDataType {
     readonly name = "Float64";
     coerce(val: unknown): number | null;
@@ -70,6 +83,12 @@ export declare class Float64Type extends FloatDataType {
     allocate(size: number): Float64Array;
 }
 export declare const Float64: Float64Type;
+/**
+ * Fixed point decimal type with optional precision and scale arguments.
+ *
+ * @param precision Precision level (total number of digits)
+ * @param scale Scale level (number of decimal place digits)
+ */
 export declare class DecimalType extends NumericDataType {
     readonly precision?: number | undefined;
     readonly scale?: number | undefined;
@@ -79,6 +98,10 @@ export declare class DecimalType extends NumericDataType {
     equals(other: DataType): boolean;
     allocate(size: number): (number | null)[];
 }
+/**
+ * Boolean datatype representing binary values (true or false).
+ *
+ */
 export declare class BooleanType extends DataType<boolean | null> {
     readonly name = "Boolean";
     get isBoolean(): boolean;
@@ -87,6 +110,10 @@ export declare class BooleanType extends DataType<boolean | null> {
     allocate(size: number): (boolean | null)[];
 }
 export declare const BooleanDataType: BooleanType;
+/**
+ * Unicode UTF-8 string datatype.
+ *
+ */
 export declare class Utf8Type extends DataType<string | null> {
     readonly name = "Utf8";
     get isString(): boolean;
@@ -120,6 +147,10 @@ export declare class ObjectType extends DataType {
     allocate(size: number): any[];
 }
 export declare const ObjectDataType: ObjectType;
+/**
+ * Calendar date type storing UTC year, month, and day.
+ *
+ */
 export declare class DateType extends TemporalDataType<Date | null> {
     readonly name = "Date";
     coerce(val: unknown): Date | null;
@@ -127,8 +158,15 @@ export declare class DateType extends TemporalDataType<Date | null> {
     allocate(size: number): (Date | null)[];
 }
 export declare const DateDataType: DateType;
+/**
+ * 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)[];
@@ -143,11 +181,18 @@ 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)[];
 }
 export declare const Duration: DurationType;
+/**
+ * Nested array list datatype wrapping an inner element type.
+ *
+ * @param innerType The child elements datatype
+ */
 export declare class ArrayType<TInner = any> extends NestedDataType<TInner[] | null> {
     readonly innerType: RegisteredDataType & DataType<TInner>;
     readonly name = "Array";
@@ -157,6 +202,11 @@ export declare class ArrayType<TInner = any> extends NestedDataType<TInner[] | n
     allocate(size: number): (TInner[] | null)[];
 }
 export declare const ArrayDataType: <TInner>(inner: RegisteredDataType & DataType<TInner>) => ArrayType<TInner>;
+/**
+ * Keyed struct object datatype wrapping sub-field schemas.
+ *
+ * @param fields Schema mapping of field names to Datatypes
+ */
 export declare class StructType<TFields extends RowRecord = any> extends NestedDataType<TFields | null> {
     readonly fields: {
         [K in keyof TFields]: RegisteredDataType & DataType<TFields[K]>;

package/dist/exceptions/index.d.ts

@@ -1,15 +1,48 @@
+/**
+ * @namespace Exception
+ * @category Exception
+ * @syntax throw new {symbol}("message")
+ */
+/**
+ * Base exception class for all df-script errors.
+ */
 export declare class DFScriptError extends Error {
     constructor(message: string);
 }
+/**
+ * General error thrown during DataFrame instantiation or execution.
+ */
 export declare class DataFrameError extends DFScriptError {
 }
+/**
+ * Error thrown when a specified column name does not exist in the DataFrame schema.
+ */
 export declare class ColumnNotFoundError extends DataFrameError {
     constructor(columnName: string, message?: string);
 }
+/**
+ * Error thrown when schema definitions, coercions, or data types are invalid.
+ */
 export declare class SchemaError extends DFScriptError {
 }
+/**
+ * Error thrown during expression evaluation or element-wise calculations.
+ */
 export declare class ComputeError extends DFScriptError {
 }
+/**
+ * Error thrown when shape dimensions or column heights mismatch.
+ */
 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;

package/dist/functions/concat.d.ts

@@ -1,3 +1,53 @@
 import { DataFrame } from "../dataframe/dataframe";
 import type { ConcatOptions, ConcatItem, RowRecord } from "../types";
+/**
+ * Concatenates items vertically, horizontally, or diagonally.
+ * @namespace $df
+ * @category ColumnExpression
+ * @syntax $df.{symbol}(...)
+ * @param rawItems 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] })
+ * >>> const df2 = $df.data({ a: [2] })
+ * >>> $df.concat([df1, 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] })
+ * >>> $df.concat([df1, 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] })
+ * >>> $df.concat([df1, df2], { how: "diagonal" })
+ * shape: (2, 2)
+ * ┌──────┬──────┐
+ * │ a    │ b    │
+ * ├──────┼──────┤
+ * │ 1    │ null │
+ * │ null │ 2    │
+ * └──────┴──────┘
+ *
+ */
 export declare function concat<U extends RowRecord = any>(rawItems: ConcatItem | ConcatItem[], { how, horizontal }?: ConcatOptions): DataFrame<U>;

package/dist/functions/read_csv.d.ts

@@ -4,5 +4,14 @@ import type { RowRecord } from "../types";
 /**
  * Reads a CSV string and constructs a DataFrame.
  * Automatically infers column data types unless an explicit schema is provided.
+ * @namespace $df
+ * @category ColumnExpression
+ * @syntax $df.{symbol}(...)
+ * @param content The CSV content string.
+ * @param [options] Parse and configuration options.
+ * @param [options.hasHeader] Whether the first row is a header row (default `true`).
+ * @param [options.schema] Optional column schema to coerce types.
+ * @param [options.inferSchema] When `true` (default), automatically infers column types.
+ * @returns DataFrame
  */
 export declare function read_csv<T extends RowRecord = any>(content: string, options?: ReadCSVOptions): DataFrame<T>;

package/dist/functions/read_json.d.ts

@@ -2,9 +2,14 @@ import { DataFrame } from "../dataframe/dataframe";
 import type { ReadJSONOptions } from "../dataframe/types";
 /**
  * Parses JSON content (JSON or NDJSON) and loads it into a new DataFrame.
- *
+ * @namespace $df
+ * @category ColumnExpression
+ * @syntax $df.{symbol}(...)
  * @param content The JSON or NDJSON content string.
- * @param options Parse and configuration options.
+ * @param [options] Parse and configuration options.
+ * @param [options.format] Input format (`"json"` or `"ndjson"`). Default `"json"`.
+ * @param [options.trimBeforeParse] When `true` (default), trims whitespace before parsing.
+ * @param [options.schema] Optional column schema to coerce types.
  * @returns A new DataFrame instance populated with the parsed records.
  */
 export declare function read_json(content: string, { format, trimBeforeParse, schema, ...parseOpts }?: ReadJSONOptions): DataFrame<any>;

package/dist/index.html

@@ -0,0 +1,17 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>🚀 DFScript Interactive Playground</title>
+  <!-- Google Fonts: Outfit (headings) & Inter (body) & Fira Code (monocode) -->
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=Fira+Code:wght@400;500&family=Inter:wght@300;400;500;600&family=Outfit:wght@400;500;600;700;800&display=swap" rel="stylesheet">
+  <script type="module" crossorigin src="/assets/index-DEJEV_tU.js"></script>
+  <link rel="stylesheet" crossorigin href="/assets/index-DBhGK6Tp.css">
+</head>
+<body>
+  <div id="root"></div>
+</body>
+</html>