@platforma-open/milaboratories.software-ptabler.schema 1.11.0 → 1.11.2

package/dist/aggregate.d.ts

@@ -1,8 +1,4 @@
 import { Expression, AggregationType } from './expressions';
-/**
- * Defines standard aggregation functions that operate on a single expression.
- */
-export type StandardAggregationType = 'sum' | 'mean' | 'median' | 'min' | 'max' | 'std' | 'var' | 'count' | 'first' | 'last' | 'n_unique';
 /**
  * Defines aggregation functions that select a value from one expression based on the min/max of another expression.
  */

package/dist/expressions.d.ts

@@ -1,5 +1,5 @@
 import { DataType } from './common';
-export type Expression = ComparisonExpression | BinaryArithmeticExpression | UnaryArithmeticExpression | CastExpression | BooleanLogicExpression | NotExpression | NullCheckExpression | StringJoinExpression | HashExpression | ColumnReferenceExpression | ConstantValueExpression | RankExpression | CumsumExpression | ExtendedUnaryStringExpression | StringDistanceExpression | FuzzyStringFilterExpression | WhenThenOtherwiseExpression | SubstringExpression | StringReplaceExpression | StringContainsExpression | StringStartsWithExpression | StringEndsWithExpression | StringContainsAnyExpression | StringCountMatchesExpression | StringExtractExpression | MinMaxExpression | FillNaExpression | WindowExpression | StructFieldExpression;
+export type Expression = ComparisonExpression | BinaryArithmeticExpression | UnaryArithmeticExpression | CastExpression | BooleanLogicExpression | NotExpression | NullCheckExpression | StringJoinExpression | HashExpression | ColumnReferenceExpression | ConstantValueExpression | RankExpression | CumsumExpression | ExtendedUnaryStringExpression | StringDistanceExpression | FuzzyStringFilterExpression | WhenThenOtherwiseExpression | SubstringExpression | StringReplaceExpression | StringContainsExpression | StringStartsWithExpression | StringEndsWithExpression | StringContainsAnyExpression | StringCountMatchesExpression | StringExtractExpression | MinMaxExpression | FillNullExpression | FillNaNExpression | WindowExpression | StructFieldExpression;
 /** Represents all possible expression types in the system. */
 export type ComparisonOperator = 'gt' | 'ge' | 'eq' | 'lt' | 'le' | 'neq';
 /** Defines a comparison operation between two expressions. */
@@ -374,20 +374,35 @@ export interface MinMaxExpression {
     operands: Expression[];
 }
 /**
- * Represents a fill NA (null) operation.
+ * Represents a fill null operation.
  * If the 'input' expression evaluates to null, the 'fillValue' expression is used.
  * Otherwise, the 'input' expression's value is used.
  * This is a convenience shortcut for a common pattern often implemented with
- * conditional expressions (e.g., when(is_na(input), fillValue).otherwise(input)).
+ * conditional expressions (e.g., when(is_null(input), fillValue).otherwise(input)).
  */
-export interface FillNaExpression {
-    /** The type of operation, always 'fill_na'. */
-    type: 'fill_na';
+export interface FillNullExpression {
+    /** The type of operation, always 'fill_null'. */
+    type: 'fill_null';
     /** The primary expression to evaluate. */
     input: Expression;
     /** The expression whose value is used if 'input' is null. */
     fillValue: Expression;
 }
+/**
+ * Represents a fill NaN operation.
+ * If the 'input' expression evaluates to NaN, the 'fillValue' expression is used.
+ * Otherwise, the 'input' expression's value is used.
+ * This is a convenience shortcut for a common pattern often implemented with
+ * conditional expressions (e.g., when(is_nan(input), fillValue).otherwise(input)).
+ */
+export interface FillNaNExpression {
+    /** The type of operation, always 'fill_nan'. */
+    type: 'fill_nan';
+    /** The primary expression to evaluate. */
+    input: Expression;
+    /** The expression whose value is used if 'input' is NaN. */
+    fillValue: Expression;
+}
 /**
  * Defines standard aggregation functions that can be used in window expressions.
  */
@@ -409,7 +424,13 @@ export interface WindowExpression {
 /**
  * Represents a struct field access operation.
  * This operation retrieves a single field from a struct (nested data structure).
- * It corresponds to Polars' struct.field() functionality.
+ *
+ * Uses native Polars struct.field() functionality when possible for optimal performance,
+ * but falls back to Python UDF (map_elements) when dtype casting or default values
+ * are specified, trading performance for robust handling of missing fields and null structs.
+ *
+ * When fields is an array, the operation performs recursive field access,
+ * where each element in the array represents a level in the nested structure.
  */
 export interface StructFieldExpression {
     /** The type of operation, always 'struct_field'. */
@@ -417,8 +438,20 @@ export interface StructFieldExpression {
     /** The struct expression to extract fields from. */
     struct: Expression;
     /**
-     * The field name to extract from the struct.
-     * Currently only supports single field extraction due to Polars behavior limitations.
+     * The field name(s) to extract from the struct.
+     * - If a string, extracts a single field from the struct.
+     * - If an array, performs recursive field access where each element represents a level in the nested structure.
+     */
+    fields: string | string[];
+    /**
+     * Optional expected data type for the returned value.
+     * This can be used for type validation or casting of the extracted field.
+     */
+    dtype?: DataType;
+    /**
+     * Optional default value to return if the field is not found or is null.
+     * If not provided and the field is missing, the operation returns null.
+     * Only constant scalar values are supported.
      */
-    fields: string;
+    default?: string | number | boolean | null;
 }

package/dist/sort.d.ts

@@ -36,14 +36,8 @@ export interface SortStep {
      * An array of sort directives defining the columns and their respective sort orders.
      * The table is sorted by the first directive in the array, then by the second
      * for any ties, and so on.
+     *
+     * Note: Sorting is always stable (maintains relative order of equivalent rows).
      */
     by: SortDirective[];
-    /**
-     * Optional. If true, maintains the stability of the sort. This means that if
-     * two rows are equivalent according to the sorting criteria, their relative order
-     * from the input table is preserved in the output.
-     * Corresponds to `maintain_order=True` in Polars `DataFrame.sort()`.
-     * Defaults to false.
-     */
-    stable?: boolean;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@platforma-open/milaboratories.software-ptabler.schema",
-  "version": "1.11.0",
+  "version": "1.11.2",
   "description": "Type definitions for PTabler",
   "types": "./dist/index.d.ts",
   "main": "./dist/index.js",
@@ -18,10 +18,10 @@
   ],
   "dependencies": {},
   "devDependencies": {
-    "@platforma-sdk/eslint-config": "^1.0.3",
-    "vite-plugin-dts": "^4.5.4",
-    "eslint": "^9.27.0",
-    "typescript": "~5.5.4",
+    "@platforma-sdk/eslint-config": "",
+    "vite-plugin-dts": "^4.5.3",
+    "eslint": "^9.25.1",
+    "typescript": "~5.6.3",
     "vite": "^6.3.5"
   },
   "scripts": {

package/src/aggregate.ts

@@ -1,21 +1,5 @@
 import type { Expression, AggregationType } from './expressions';
 
-/**
- * Defines standard aggregation functions that operate on a single expression.
- */
-export type StandardAggregationType =
-  | 'sum'
-  | 'mean'
-  | 'median'
-  | 'min'
-  | 'max'
-  | 'std'
-  | 'var'
-  | 'count'
-  | 'first'
-  | 'last'
-  | 'n_unique';
-
 /**
  * Defines aggregation functions that select a value from one expression based on the min/max of another expression.
  */

package/src/expressions.ts

@@ -27,7 +27,8 @@ export type Expression =
   | StringCountMatchesExpression
   | StringExtractExpression
   | MinMaxExpression
-  | FillNaExpression
+  | FillNullExpression
+  | FillNaNExpression
   | WindowExpression
   | StructFieldExpression;
 
@@ -470,21 +471,37 @@ export interface MinMaxExpression {
 }
 
 /**
- * Represents a fill NA (null) operation.
+ * Represents a fill null operation.
  * If the 'input' expression evaluates to null, the 'fillValue' expression is used.
  * Otherwise, the 'input' expression's value is used.
  * This is a convenience shortcut for a common pattern often implemented with
- * conditional expressions (e.g., when(is_na(input), fillValue).otherwise(input)).
+ * conditional expressions (e.g., when(is_null(input), fillValue).otherwise(input)).
  */
-export interface FillNaExpression {
-  /** The type of operation, always 'fill_na'. */
-  type: 'fill_na';
+export interface FillNullExpression {
+  /** The type of operation, always 'fill_null'. */
+  type: 'fill_null';
   /** The primary expression to evaluate. */
   input: Expression;
   /** The expression whose value is used if 'input' is null. */
   fillValue: Expression;
 }
 
+/**
+ * Represents a fill NaN operation.
+ * If the 'input' expression evaluates to NaN, the 'fillValue' expression is used.
+ * Otherwise, the 'input' expression's value is used.
+ * This is a convenience shortcut for a common pattern often implemented with
+ * conditional expressions (e.g., when(is_nan(input), fillValue).otherwise(input)).
+ */
+export interface FillNaNExpression {
+  /** The type of operation, always 'fill_nan'. */
+  type: 'fill_nan';
+  /** The primary expression to evaluate. */
+  input: Expression;
+  /** The expression whose value is used if 'input' is NaN. */
+  fillValue: Expression;
+}
+
 /**
  * Defines standard aggregation functions that can be used in window expressions.
  */
@@ -519,7 +536,13 @@ export interface WindowExpression {
 /**
  * Represents a struct field access operation.
  * This operation retrieves a single field from a struct (nested data structure).
- * It corresponds to Polars' struct.field() functionality.
+ *
+ * Uses native Polars struct.field() functionality when possible for optimal performance,
+ * but falls back to Python UDF (map_elements) when dtype casting or default values
+ * are specified, trading performance for robust handling of missing fields and null structs.
+ *
+ * When fields is an array, the operation performs recursive field access,
+ * where each element in the array represents a level in the nested structure.
  */
 export interface StructFieldExpression {
   /** The type of operation, always 'struct_field'. */
@@ -527,8 +550,20 @@ export interface StructFieldExpression {
   /** The struct expression to extract fields from. */
   struct: Expression;
   /**
-   * The field name to extract from the struct.
-   * Currently only supports single field extraction due to Polars behavior limitations.
+   * The field name(s) to extract from the struct.
+   * - If a string, extracts a single field from the struct.
+   * - If an array, performs recursive field access where each element represents a level in the nested structure.
+   */
+  fields: string | string[];
+  /**
+   * Optional expected data type for the returned value.
+   * This can be used for type validation or casting of the extracted field.
+   */
+  dtype?: DataType;
+  /**
+   * Optional default value to return if the field is not found or is null.
+   * If not provided and the field is missing, the operation returns null.
+   * Only constant scalar values are supported.
    */
-  fields: string;
+  default?: string | number | boolean | null;
 }

package/src/sort.ts

@@ -43,15 +43,8 @@ export interface SortStep {
    * An array of sort directives defining the columns and their respective sort orders.
    * The table is sorted by the first directive in the array, then by the second
    * for any ties, and so on.
+   *
+   * Note: Sorting is always stable (maintains relative order of equivalent rows).
    */
   by: SortDirective[];
-
-  /**
-   * Optional. If true, maintains the stability of the sort. This means that if
-   * two rows are equivalent according to the sorting criteria, their relative order
-   * from the input table is preserved in the output.
-   * Corresponds to `maintain_order=True` in Polars `DataFrame.sort()`.
-   * Defaults to false.
-   */
-  stable?: boolean;
 }