df-script 1.6.0 → 1.8.0

package/dist/columnExpressions/mixins/StructExpr.d.ts

@@ -1,16 +1,86 @@
 import { ExprBase } from "../ExprBase";
 import type { IntoExpr, IExpr } from "../../types";
+/**
+ * @namespace $df.col.struct
+ * @category ColumnExpression
+ * @syntax $df.col(<column_name>).struct.{symbol}(...)
+ */
 export declare class StructExprNamespace {
     expr: IExpr;
     constructor(expr: IExpr);
+    /**
+     * Extracts a sub-field property value from nested objects/struct columns.
+     * @param name Name of the field key to extract.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ user: [{ name: "Alice", id: 1 }] })
+     * >>> df.with_columns($df.col("user").struct.field("name").alias("user_name"))
+     * shape: (1, 2)
+     * ┌─────────────────────────┬───────────┐
+     * │ user                    │ user_name │
+     * ├─────────────────────────┼───────────┤
+     * │ { name: "Alice", id: 1 }│ Alice     │
+     * └─────────────────────────┴───────────┘
+     */
     field(name: string): IExpr;
+    /**
+     * Renames existing field keys inside structured object columns.
+     * @param mapping Key-value map of current field names to new field names.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ user: [{ first: "Alice" }] })
+     * >>> df.with_columns($df.col("user").struct.rename_fields({ first: "first_name" }).alias("user_renamed"))
+     * shape: (1, 2)
+     * ┌───────────────────┬─────────────────────────┐
+     * │ user              │ user_renamed            │
+     * ├───────────────────┼─────────────────────────┤
+     * │ { first: "Alice" }│ { first_name: "Alice" } │
+     * └───────────────────┴─────────────────────────┘
+     */
     rename_fields(mapping: Record<string, string>): IExpr;
+    /**
+     * Inserts or updates fields inside structured object columns.
+     * @param fields Expressions or field map defining new or updated fields.
+     * @returns ColumnExpression
+     * @throws {Error} If expressions passed without an alias or name.
+     * @example
+     * >>> const df = $df.data({ user: [{ name: "Alice" }], age: [30] })
+     * >>> df.with_columns($df.col("user").struct.with_fields({ user_age: $df.col("age") }).alias("updated_user"))
+     * shape: (1, 3)
+     * ┌─────────────────┬─────┬───────────────────────────────┐
+     * │ user            │ age │ updated_user                  │
+     * ├─────────────────┼─────┼───────────────────────────────┤
+     * │ { name: "Alice"}│ 30  │ { name: "Alice", user_age: 30}│
+     * └─────────────────┴─────┴───────────────────────────────┘
+     */
     with_fields(fields: IntoExpr[] | Record<string, IntoExpr>): IExpr;
+    /**
+     * Expands nested struct attributes into distinct columns in the DataFrame schema.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ user: [{ name: "Alice", age: 30 }] })
+     * >>> df.select($df.col("user").struct.unnest())
+     * shape: (1, 2)
+     * ┌───────┬─────┐
+     * │ name  │ age │
+     * ├───────┼─────┤
+     * │ Alice │ 30  │
+     * └───────┴─────┘
+     */
     unnest(): IExpr;
 }
 export interface StructExprNamespace {
     [key: string]: any;
 }
 export declare class StructExpr extends ExprBase {
+    /**
+     * Struct namespace accessor for operating on nested object/struct columns.
+     * @namespace $df.col
+     * @category ColumnExpression
+     * @syntax $df.col(<column_name>).struct
+     * @returns StructExprNamespace
+     * @example
+     * >>> df.select($df.col("user").struct.field("name"))
+     */
     get struct(): StructExprNamespace;
 }