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

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

@@ -409,7 +409,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 +423,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.1",
   "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

@@ -519,7 +519,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 +533,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;
 }