@platforma-open/milaboratories.software-ptabler.schema 1.3.0

package/dist/join.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Defines the structure for mapping a column, with an optional rename.
+ */
+export interface ColumnMapping {
+    /** The original name of the column. */
+    column: string;
+    /** The new name for the column. If absent, the original name is used. */
+    rename?: string;
+}
+/**
+ * Defines the type for join operations (excluding cross join) in a workflow.
+ * This step joins two tables from the tablespace based on specified columns and join strategy.
+ */
+export interface JoinStep {
+    /** The type of the step, which is always "join" for this operation. */
+    type: 'join';
+    /** The name of the left table in the tablespace to be joined. */
+    leftTable: string;
+    /** The name of the right table in the tablespace to be joined. */
+    rightTable: string;
+    /** The name to be assigned to the resulting joined table in the tablespace. */
+    outputTable: string;
+    /** A list of column names from the left table to be used for the equi-join, original not mapped names. */
+    leftOn: string[];
+    /** A list of column names from the right table to be used for the equi-join, original not mapped names. */
+    rightOn: string[];
+    /** The type of join to perform. */
+    how: JoinStrategy;
+    /**
+     * Determines how to handle key columns with the same name from both the left and right tables after the join.
+     * When set to \`true\` (the default), Polars will attempt to merge these identically named key columns into a single column in the output table.
+     * For 'inner', 'left', and 'right' joins, this is the standard behavior.
+     * For 'full' joins, setting this to \`true\` ensures the key columns are coalesced.
+     * When set to \`false\`, identically named key columns from the left and right tables will be kept separate in the output,
+     * with the column from the right table typically being renamed (e.g., by adding a suffix like '_right').
+     * This parameter mirrors the behavior of Polars' join coalescing logic.
+     * It does not apply to 'cross' joins, as they do not involve key columns in the same way.
+     */
+    coalesce?: boolean;
+    /**
+     * An optional list to select and rename columns from the left table.
+     * If provided, only these columns (plus any from `leftOn` not explicitly listed) will be included.
+     * Use the `rename` property within a mapping to change a column's name.
+     */
+    leftColumns?: ColumnMapping[];
+    /**
+     * An optional list to select and rename columns from the right table.
+     * If provided, only these columns (plus any from `rightOn` not explicitly listed) will be included.
+     * Use the `rename` property within a mapping to change a column's name.
+     */
+    rightColumns?: ColumnMapping[];
+}
+/**
+ * Defines the type for a cross join operation in a workflow.
+ * This step computes the Cartesian product of two tables.
+ */
+export interface CrossJoinStep {
+    /** The type of the step, which is always "join" for this operation. */
+    type: 'join';
+    /** The name of the left table in the tablespace to be joined. */
+    leftTable: string;
+    /** The name of the right table in the tablespace to be joined. */
+    rightTable: string;
+    /** The name to be assigned to the resulting joined table in the tablespace. */
+    outputTable: string;
+    /** The type of join to perform, which is always "cross" for this operation. */
+    how: 'cross';
+    /**
+     * An optional list to select and rename columns from the left table.
+     * If provided, only these columns will be included.
+     * Use the `rename` property within a mapping to change a column's name.
+     */
+    leftColumns?: ColumnMapping[];
+    /**
+     * An optional list to select and rename columns from the right table.
+     * If provided, only these columns will be included.
+     * Use the `rename` property within a mapping to change a column's name.
+     */
+    rightColumns?: ColumnMapping[];
+}
+/** Defines the possible join strategies for a standard join operation (excluding cross join). */
+export type JoinStrategy = 'inner' | 'left' | 'right' | 'full';
+/** Defines any possible join step. */
+export type AnyJoinStep = JoinStep | CrossJoinStep;

package/dist/sort.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Defines a single sort instruction, specifying the column, sort order,
+ * and null handling strategy.
+ */
+export interface SortDirective {
+    /** The name of the column to sort by. */
+    column: string;
+    /**
+     * Whether to sort in descending order for this column.
+     * Defaults to false (ascending).
+     */
+    descending?: boolean;
+    /**
+     * Determines how null values are handled in the sort for this column.
+     * If true, nulls are placed last.
+     * If false, nulls are placed first.
+     * If undefined, the default Polars behavior is used (nulls are considered smallest,
+     * so they appear first in ascending sorts and last in descending sorts, unless platform defaults differ).
+     * This maps to Polars' `nulls_last` parameter.
+     */
+    nullsLast?: boolean;
+}
+/**
+ * Defines a step that sorts a table based on one or more column directives.
+ * The operation reads from an input table and writes the sorted result to an output table.
+ */
+export interface SortStep {
+    /** The type identifier for this step. Must be 'sort'. */
+    type: 'sort';
+    /** The name of the input table from the tablespace to be sorted. */
+    inputTable: string;
+    /** The name to be assigned to the newly created sorted table in the tablespace. */
+    outputTable: string;
+    /**
+     * 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.
+     */
+    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

@@ -0,0 +1,33 @@
+{
+  "name": "@platforma-open/milaboratories.software-ptabler.schema",
+  "version": "1.3.0",
+  "description": "Type definitions for PTabler",
+  "types": "./dist/index.d.ts",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "./dist/**/*",
+    "./src/**/*"
+  ],
+  "dependencies": {},
+  "devDependencies": {
+    "@platforma-sdk/eslint-config": "^1.0.3",
+    "vite-plugin-dts": "^4.5.4",
+    "eslint": "^9.27.0",
+    "typescript": "~5.5.4",
+    "vite": "^6.3.5"
+  },
+  "scripts": {
+    "type-check": "tsc --noEmit --composite false",
+    "build": "vite build",
+    "lint": "eslint .",
+    "do-pack": "rm -f *.tgz && pnpm pack && mv *.tgz package.tgz"
+  }
+}

package/src/aggregate.ts

@@ -0,0 +1,77 @@
+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.
+ */
+export type ByClauseAggregationType =
+  | 'max_by'
+  | 'min_by';
+
+/**
+ * Represents a standard aggregation operation like sum, mean, count, etc.
+ */
+export interface StandardAggregationOperation {
+  /** The name for the resulting column after aggregation. */
+  name: string;
+  /** The type of standard aggregation to perform. */
+  aggregation: AggregationType;
+  /**
+   * The primary expression to aggregate.
+   * For aggregations like 'sum', 'mean', 'min', 'max', this is the expression (e.g., a column) whose values are aggregated.
+   * For 'count', this expression might not be directly used by Polars if counting all rows, but can be used to count non-null values in a specific column.
+   * For 'first', 'last', 'n_unique', this is the expression on which the operation is performed.
+   */
+  expression: Expression;
+}
+
+/**
+ * Represents an aggregation operation that selects a value from one expression
+ * based on the minimum or maximum value of another expression (the 'by_expression').
+ */
+export interface ByClauseAggregationOperation {
+  /** The name for the resulting column after aggregation. */
+  name: string;
+  /** The type of 'by-clause' aggregation to perform (e.g., 'max_by', 'min_by'). */
+  aggregation: ByClauseAggregationType;
+  /** The expression whose value is selected. */
+  expression: Expression;
+  /**
+   * The expression or list of expressions to order by to determine which value of `expression` is selected.
+   * If an array of expressions is provided, ordering is done sequentially by each expression.
+   */
+  by: Expression[];
+}
+
+/**
+ * Represents the configuration for an 'aggregate' step in the workflow.
+ * This step performs aggregation operations on a table, optionally grouping by certain columns,
+ * and outputs a new table with the aggregated results.
+ */
+export interface AggregateStep {
+  /** Specifies the type of the step, which is 'aggregate'. */
+  type: 'aggregate';
+  /** The name of the input table from the tablespace on which to perform aggregation. */
+  inputTable: string;
+  /** The name to be assigned to the newly created aggregated table in the tablespace. */
+  outputTable: string;
+  /** An optional list of column names to group by before performing aggregations. */
+  groupBy: string[];
+  /** An array of aggregation operations to apply to the input table. */
+  aggregations: (StandardAggregationOperation | ByClauseAggregationOperation)[];
+}

package/src/basic_steps.ts

@@ -0,0 +1,153 @@
+import type { Expression } from './expressions';
+
+/**
+ * Defines a step that adds one or more new columns to an existing table in the tablespace.
+ * This operation modifies the specified table in place.
+ */
+export interface AddColumnsStep {
+  /**
+   * The type identifier for this step.
+   * Must be 'add_columns'.
+   */
+  type: 'add_columns';
+
+  /**
+   * The name of the target DataFrame in the tablespace to which columns will be added.
+   */
+  table: string;
+
+  /**
+   * An array defining the new columns to be added.
+   * Each object in the array specifies the name of a new column and the expression to compute its values.
+   */
+  columns: {
+    /**
+     * The name of the new column.
+     */
+    name: string;
+
+    /**
+     * An Expression object defining how to compute the column's values.
+     * The expression will be evaluated for each row to generate the values for the new column.
+     */
+    expression: Expression;
+  }[];
+}
+
+/**
+ * Defines a step that filters rows in a table based on a specified condition
+ * and outputs the result to a new table in the tablespace.
+ */
+export interface FilterStep {
+  /**
+   * The type identifier for this step.
+   * Must be 'filter'.
+   */
+  type: 'filter';
+
+  /**
+   * The name of the input table in the tablespace from which rows will be filtered.
+   */
+  inputTable: string;
+
+  /**
+   * The name for the resulting filtered table that will be added to the tablespace.
+   * This new table will contain only the rows that satisfy the condition.
+   */
+  outputTable: string;
+
+  /**
+   * A boolean Expression object used as the filter condition.
+   * Rows for which this expression evaluates to true are kept in the outputTable.
+   * Rows for which it evaluates to false or null are excluded.
+   */
+  condition: Expression;
+}
+
+/**
+ * Defines a step that selects a specific set of columns from an input table,
+ * potentially applying transformations or creating new columns, and outputs
+ * the result to a new table in the tablespace. This operation is similar
+ * to Polars' `select` method.
+ */
+export interface SelectStep {
+  /**
+   * The type identifier for this step.
+   * Must be 'select'.
+   */
+  type: 'select';
+
+  /**
+   * The name of the input table in the tablespace from which columns will be selected.
+   */
+  inputTable: string;
+
+  /**
+   * The name for the resulting table that will be added to the tablespace.
+   * This new table will contain only the columns defined in the 'columns' array.
+   */
+  outputTable: string;
+
+  /**
+   * An array defining the columns for the output table.
+   * Each object in the array specifies the name of a column in the output table
+   * and the expression to compute its values.
+   */
+  columns: {
+    /**
+     * The name of the column in the output table.
+     */
+    name: string;
+
+    /**
+     * An Expression object defining how to compute the column's values.
+     * This expression will be evaluated to generate the values for this column
+     * in the output table.
+     */
+    expression: Expression;
+  }[];
+}
+
+/**
+ * Defines a step that adds new columns to an input table (or replaces existing ones
+ * if names collide) and outputs the result to a new table in the tablespace.
+ * This operation is similar to Polars' `with_columns` method.
+ */
+export interface WithColumnsStep {
+  /**
+   * The type identifier for this step.
+   * Must be 'with_columns'.
+   */
+  type: 'with_columns';
+
+  /**
+   * The name of the input table in the tablespace to which columns will be added.
+   */
+  inputTable: string;
+
+  /**
+   * The name for the resulting table that will be added to the tablespace.
+   * This new table will contain all original columns from the inputTable,
+   * plus the new columns defined here (or with existing columns replaced by
+   * new ones if names match).
+   */
+  outputTable: string;
+
+  /**
+   * An array defining the new or replacement columns.
+   * Each object in the array specifies the name of a column and the
+   * expression to compute its values.
+   */
+  columns: {
+    /**
+     * The name of the new or replacement column.
+     */
+    name: string;
+
+    /**
+     * An Expression object defining how to compute the column's values.
+     * The expression will be evaluated for each row to generate the values for the column.
+     */
+    expression: Expression;
+  }[];
+}

package/src/common.ts

@@ -0,0 +1,30 @@
+/**
+ * Defines the supported Polars primitive data types for schema definition.
+ *
+ * The following are aliases for convenience:
+ * - 'Int': maps to 'Int32'
+ * - 'Long': maps to 'Int64'
+ * - 'Float': maps to 'Float32'
+ * - 'Double': maps to 'Float64'
+ */
+export type DataType =
+  | 'Int8'
+  | 'Int16'
+  | 'Int32'
+  | 'Int64'
+  | 'UInt8'
+  | 'UInt16'
+  | 'UInt32'
+  | 'UInt64'
+  | 'Float32'
+  | 'Float64'
+  | 'Boolean'
+  | 'String'
+  | 'Date'
+  | 'Datetime'
+  | 'Time'
+  // Aliases
+  | 'Int'
+  | 'Long'
+  | 'Float'
+  | 'Double';

package/src/concatenate.ts

@@ -0,0 +1,25 @@
+/**
+ * Defines a step that vertically concatenates multiple tables from the tablespace
+ * into a single output table. Columns are matched by name.
+ */
+export interface ConcatenateStep {
+  /** The type identifier for this step. Must be 'concatenate'. */
+  type: 'concatenate';
+
+  /**
+   * An array of input table names from the tablespace.
+   * The tables are concatenated vertically in the order they appear in this array.
+   */
+  inputTables: string[];
+
+  /** The name to be assigned to the newly created concatenated table in the tablespace. */
+  outputTable: string;
+
+  /**
+   * Optional. A list of column names to select from all input tables.
+   * If omitted, all columns from all input tables are included, and columns are matched by name.
+   * If provided, only these specified columns will be included in the output table.
+   * All input tables must contain all specified columns for the operation to succeed.
+   */
+  columns?: string[];
+}