df-script 1.5.0 → 1.7.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,3 +1,4 @@
+/** @typefile */
 import type { IExpr, AggFn, RowRecord, DataFrameSchema, JSONFormat } from "../types";
 import type { DataFrame } from "./dataframe";
 import type { JSONParseOptions, SafeJsonReplacerOptions, NDJSONParseOptions } from "../utils";

package/dist/dataframe/utils.d.ts

@@ -1,3 +1,4 @@
+/** @internalfile */
 import type { IExpr, ColumnData, ColumnDict, RegisteredDataType } from "../types";
 export declare function resolveWindowExpr(expr: IExpr, columns: ColumnDict, height: number): ColumnData;
 export declare function rowsToColumns(rows: any[]): {

package/dist/datatypes/index.d.ts

@@ -1,5 +1,5 @@
 import { DataType as BaseDataType } from "./DataType";
-import { DecimalType } from "./types";
+import { DecimalType, BooleanDataType as Boolean, DateDataType as Date, ObjectDataType as Object, ArrayDataType as Array } from "./types";
 export { BaseDataType as DataType };
 export declare const DataTypeRegistry: {
     Int8: import("./types").Int8Type;
@@ -22,8 +22,9 @@ export declare const DataTypeRegistry: {
     Duration: import("./types").DurationType;
     Object: import("./types").ObjectType;
     Null: import("./types").NullType;
-    List: <TInner>(inner: import("./types").RegisteredDataType & BaseDataType<TInner>) => import("./types").ListType<TInner>;
+    Array: <TInner>(inner: import("./types").RegisteredDataType & BaseDataType<TInner>) => import("./types").ArrayType<TInner>;
     Struct: <TFields extends import("..").RowRecord>(fields: { [K in keyof TFields]: import("./types").RegisteredDataType & BaseDataType<TFields[K]>; }) => import("./types").StructType<TFields>;
 };
+export { Boolean, Date, Object, Array };
 export * from "./types";
 export * from "./DataType";

package/dist/datatypes/types.d.ts

@@ -1,3 +1,4 @@
+/** @typefile */
 import { DataType, SignedIntegerType, UnsignedIntegerType, FloatDataType, TemporalDataType, NestedDataType, NumericDataType } from "./DataType";
 import type { RowRecord } from "../types";
 export declare class Int8Type extends SignedIntegerType {
@@ -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;
@@ -86,7 +109,11 @@ export declare class BooleanType extends DataType<boolean | null> {
     equals(other: DataType): boolean;
     allocate(size: number): (boolean | null)[];
 }
-export declare const Boolean: BooleanType;
+export declare const BooleanDataType: BooleanType;
+/**
+ * Unicode UTF-8 string datatype.
+ *
+ */
 export declare class Utf8Type extends DataType<string | null> {
     readonly name = "Utf8";
     get isString(): boolean;
@@ -119,14 +146,22 @@ export declare class ObjectType extends DataType {
     equals(other: DataType): boolean;
     allocate(size: number): any[];
 }
-export declare const Object: ObjectType;
+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;
     equals(other: DataType): boolean;
     allocate(size: number): (Date | null)[];
 }
-export declare const Date: DateType;
+export declare const DateDataType: DateType;
+/**
+ * Date and time type (year, month, day, hour, minute, second, millisecond).
+ *
+ */
 export declare class DatetimeType extends TemporalDataType<Date | null> {
     readonly name = "Datetime";
     coerce(val: unknown): Date | null;
@@ -148,15 +183,25 @@ export declare class DurationType extends TemporalDataType<number | null> {
     allocate(size: number): (number | null)[];
 }
 export declare const Duration: DurationType;
-export declare class ListType<TInner = any> extends NestedDataType<TInner[] | null> {
+/**
+ * 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 = "List";
+    readonly name = "Array";
     constructor(innerType: RegisteredDataType & DataType<TInner>);
     coerce(val: unknown): TInner[] | null;
     equals(other: DataType): boolean;
     allocate(size: number): (TInner[] | null)[];
 }
-export declare const List: <TInner>(inner: RegisteredDataType & DataType<TInner>) => ListType<TInner>;
+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]>;
@@ -170,4 +215,4 @@ export declare class StructType<TFields extends RowRecord = any> extends NestedD
     allocate(size: number): (TFields | null)[];
 }
 export declare const Struct: <TFields extends RowRecord>(fields: { [K in keyof TFields]: RegisteredDataType & DataType<TFields[K]>; }) => StructType<TFields>;
-export type RegisteredDataType = Int8Type | Int16Type | Int32Type | Int64Type | UInt8Type | UInt16Type | UInt32Type | UInt64Type | Float32Type | Float64Type | DecimalType | BooleanType | Utf8Type | BinaryType | NullType | ObjectType | DateType | DatetimeType | TimeType | DurationType | ListType<any> | StructType<any>;
+export type RegisteredDataType = Int8Type | Int16Type | Int32Type | Int64Type | UInt8Type | UInt16Type | UInt32Type | UInt64Type | Float32Type | Float64Type | DecimalType | BooleanType | Utf8Type | BinaryType | NullType | ObjectType | DateType | DatetimeType | TimeType | DurationType | ArrayType<any> | StructType<any>;

package/dist/exceptions/index.d.ts

@@ -1,15 +1,38 @@
+/**
+ * @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 {
 }
 export * from "./utils";

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>