@ohos-ports/nodejs-polars 0.22.2-beta.0

package/bin/shared_traits.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/bin/sql.d.ts

@@ -0,0 +1,244 @@
+import { DataFrame, type LazyDataFrame } from ".";
+declare const INSPECT: unique symbol;
+/**
+ * Run SQL queries against DataFrame/LazyFrame data.
+ *
+ * @experimental This functionality is considered **unstable**, although it is close to being
+ * considered stable. It may be changed at any point without it being considered a breaking change.
+ */
+export interface iSQLContext {
+    /**
+     * Parse the given SQL query and execute it against the registered frame data.
+     *
+     * @param query - A valid string SQL query.
+     * @param eager - Apply the query eagerly, returning `DataFrame` instead of `LazyFrame`.
+     *                If unset, the value of the init-time parameter "eager_execution" will be
+     *                used. (Note that the query itself is always executed in lazy-mode; this
+     *                parameter only impacts the type of the returned frame).
+     *
+     * @example
+     * Declare frame data and register with a SQLContext:
+     *
+     * ```ts
+     * const df = pl.DataFrame({
+     *   data: [
+     *     ("The Godfather", 1972, 6_000_000, 134_821_952, 9.2),
+     *     ("The Dark Knight", 2008, 185_000_000, 533_316_061, 9.0),
+     *     ("Schindler's List", 1993, 22_000_000, 96_067_179, 8.9),
+     *     ("Pulp Fiction", 1994, 8_000_000, 107_930_000, 8.9),
+     *     ("The Shawshank Redemption", 1994, 25_000_000, 28_341_469, 9.3),
+     *   ],
+     *   schema: ["title", "release_year", "budget", "gross", "imdb_score"],
+     * });
+     * const ctx = pl.SQLContext({ films: df });
+     * ```
+     *
+     * Execute a SQL query against the registered frame data:
+     *
+     * ```ts
+     * const result = ctx.execute(`
+     *   SELECT title, release_year, imdb_score
+     *   FROM films
+     *   WHERE release_year > 1990
+     *   ORDER BY imdb_score DESC
+     * `, { eager: true });
+     * console.log(result);
+     * // shape: (4, 3)
+     * // ┌──────────────────────────┬──────────────┬────────────┐
+     * // │ title                    ┆ release_year ┆ imdb_score │
+     * // │ ---                      ┆ ---          ┆ ---        │
+     * // ╞══════════════════════════╪══════════════╪════════════╡
+     * // │ The Shawshank Redemption ┆ 1994         ┆ 9.3        │
+     * // │ The Dark Knight          ┆ 2008         ┆ 9.0        │
+     * // │ Schindler's List         ┆ 1993         ┆ 8.9        │
+     * // │ Pulp Fiction             ┆ 1994         ┆ 8.9        │
+     * // └──────────────────────────┴──────────────┴────────────┘
+     * ```
+     *
+     * Execute a GROUP BY query:
+     *
+     * ```ts
+     * ctx.execute(`
+     *   SELECT
+     *       MAX(release_year / 10) * 10 AS decade,
+     *       SUM(gross) AS total_gross,
+     *       COUNT(title) AS n_films,
+     *   FROM films
+     *   GROUP BY (release_year / 10) -- decade
+     *   ORDER BY total_gross DESC
+     * `, { eager: true });
+     * // shape: (3, 3)
+     * // ┌────────┬─────────────┬─────────┐
+     * // │ decade ┆ total_gross ┆ n_films │
+     * // │ ---    ┆ ---         ┆ ---     │
+     * // ╞════════╪═════════════╪═════════╡
+     * // │ 2000   ┆ 533316061   ┆ 1       │
+     * // │ 1990   ┆ 232338648   ┆ 3       │
+     * // │ 1970   ┆ 134821952   ┆ 1       │
+     * // └────────┴─────────────┴─────────┘
+     * ```
+     */
+    execute(query: string, { eager }: {
+        eager: true;
+    }): DataFrame;
+    execute(query: string, { eager }: {
+        eager: false;
+    }): LazyDataFrame;
+    execute(query: string): LazyDataFrame;
+    /**
+     * Register a single frame as a table, using the given name.
+     *
+     * Parameters
+     * ----------
+     * name : string
+     *     Name of the table.
+     * frame : DataFrame | LazyFrame | null
+     *     Eager/lazy frame to associate with this table name.
+     *
+     * See Also
+     * --------
+     * register_globals
+     * register_many
+     * unregister
+     *
+     * Examples
+     * --------
+     * const df = pl.DataFrame({"hello": ["world"]});
+     * const ctx = pl.SQLContext();
+     * ctx.register("frame_data", df).execute("SELECT * FROM frame_data").collect();
+     * returns: shape: (1, 1)
+     * ┌───────┐
+     * │ hello │
+     * │ ---   │
+     * │ str   │
+     * ╞═══════╡
+     * │ world │
+     * └───────┘
+     */
+    register(name: string, frame: DataFrame | LazyDataFrame | null): SQLContext;
+    /**
+     * Register multiple DataFrames as tables, using the associated names.
+     *
+     * @param {Object} frames An `{name: df, ...}` mapping.
+     *
+     * @returns {SQLContext} The SQLContext with registered DataFrames.
+     *
+     * @see register
+     * @see unregister
+     *
+     * @example
+     * const lf1 = pl.DataFrame({"a": [1, 2, 3], "b": ["m", "n", "o"]});
+     * const lf2 = pl.DataFrame({"a": [2, 3, 4], "c": ["p", "q", "r"]});
+     *
+     * // Register multiple DataFrames at once
+     * const ctx = pl.SQLContext().registerMany({"tbl1": lf1, "tbl2": lf2});
+     * console.log(ctx.tables());
+     * // Output: ['tbl1', 'tbl2']
+     */
+    registerMany(frames: Record<string, DataFrame | LazyDataFrame>): SQLContext;
+    /**
+     * Unregister one or more eager/lazy frames by name.
+     *
+     * @param names - Names of the tables to unregister.
+     *
+     * @remarks
+     * You can also control table registration lifetime by using `SQLContext` as a
+     * context manager; this can often be more useful when such control is wanted.
+     *
+     * Frames registered in-scope are automatically unregistered on scope-exit. Note
+     * that frames registered on construction will persist through subsequent scopes.
+     *
+     * @example
+     * ```ts
+     * const df0 = pl.DataFrame({"colx": [0, 1, 2]});
+     * const df1 = pl.DataFrame({"colx": [1, 2, 3]});
+     * const df2 = pl.DataFrame({"colx": [2, 3, 4]});
+     *
+     * // Register one frame at construction time, and the other two in-scope
+     * const ctx = pl.SQLContext({ tbl0: df0 });
+     * ctx.register("tbl1", df1);
+     * ctx.register("tbl2", df2);
+     * console.log(ctx.tables()); // Output: ['tbl0', 'tbl1', 'tbl2']
+     *
+     * // After scope exit, none of the tables registered in-scope remain
+     * ```
+     *
+     * @see register
+     * @see register_globals
+     * @see register_many
+     *
+     * @example
+     * ```ts
+     * const df0 = pl.DataFrame({"ints": [9, 8, 7, 6, 5]});
+     * const lf1 = pl.DataFrame({"text": ["a", "b", "c"]}).lazy();
+     * const lf2 = pl.DataFrame({"misc": ["testing1234"]}).lazy();
+     *
+     * // Register with a SQLContext object
+     * const ctx = pl.SQLContext({ test1: df0, test2: lf1, test3: lf2 });
+     * console.log(ctx.tables()); // Output: ['test1', 'test2', 'test3']
+     *
+     * // Unregister one or more of the tables
+     * ctx.unregister(["test1", "test3"]);
+     * console.log(ctx.tables()); // Output: ['test2']
+     * ctx.unregister("test2");
+     * console.log(ctx.tables()); // Output: []
+     * ```
+     */
+    unregister(names: string | string[]): SQLContext;
+    /**
+     * Returns a list of the registered table names.
+     *
+     * @remarks
+     * The `tables` method will return the same values as the "SHOW TABLES" SQL statement, but as a list instead of a frame.
+     *
+     * Executing as SQL:
+     * ```ts
+     * const frame_data = pl.DataFrame({"hello": ["world"]});
+     * const ctx = pl.SQLContext({ hello_world: frame_data });
+     * console.log(ctx.execute("SHOW TABLES", { eager: true }));
+     * // shape: (1, 1)
+     * // ┌─────────────┐
+     * // │ name        │
+     * // │ ---         │
+     * // │ str         │
+     * // ╞═════════════╡
+     * // │ hello_world │
+     * // └─────────────┘
+     * ```
+     *
+     * Calling the method:
+     * ```ts
+     * console.log(ctx.tables());
+     * // ['hello_world']
+     * ```
+     *
+     * @example
+     * ```ts
+     * const df1 = pl.DataFrame({"hello": ["world"]});
+     * const df2 = pl.DataFrame({"foo": ["bar", "baz"]});
+     * const ctx = pl.SQLContext({ hello_data: df1, foo_bar: df2 });
+     * console.log(ctx.tables());
+     * // ['foo_bar', 'hello_data']
+     * ```
+     *
+     * @returns {string[]} An array of the registered table names.
+     */
+    tables(): string[];
+}
+export declare class SQLContext implements iSQLContext {
+    #private;
+    [INSPECT](): string;
+    constructor(frames?: Record<string, DataFrame | LazyDataFrame>);
+    execute(query: string): LazyDataFrame;
+    execute(query: string, { eager }: {
+        eager: true;
+    }): DataFrame;
+    execute(query: string, { eager }: {
+        eager: false;
+    }): LazyDataFrame;
+    register(this: SQLContext, name: string, frame: DataFrame | LazyDataFrame | null): SQLContext;
+    registerMany(this: SQLContext, frames: Record<string, DataFrame | LazyDataFrame>): SQLContext;
+    unregister(names: string | string[]): SQLContext;
+    tables(): string[];
+}
+export {};

package/bin/sql.js

@@ -0,0 +1,63 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SQLContext = void 0;
+const _1 = require(".");
+const polars_internal_1 = __importDefault(require("./internals/polars_internal"));
+const INSPECT = Symbol.for("nodejs.util.inspect.custom");
+class SQLContext {
+    #ctx; // native SQLContext
+    [INSPECT]() {
+        return `SQLContext: {${this.#ctx.getTables().join(", ")}}`;
+    }
+    constructor(frames) {
+        this.#ctx = new polars_internal_1.default.SqlContext();
+        for (const [name, frame] of Object.entries(frames ?? {})) {
+            if (_1.DataFrame.isDataFrame(frame)) {
+                this.#ctx.register(name, frame._df.lazy());
+            }
+            else {
+                this.#ctx.register(name, frame._ldf);
+            }
+        }
+    }
+    execute(query, { eager } = { eager: false }) {
+        const lf_ = this.#ctx.execute(query);
+        const lf = (0, _1._LazyDataFrame)(lf_);
+        if (eager) {
+            return lf.collectSync();
+        }
+        return lf;
+    }
+    register(name, frame) {
+        if (frame == null) {
+            frame = (0, _1.DataFrame)().lazy();
+        }
+        else if (_1.DataFrame.isDataFrame(frame)) {
+            frame = frame.lazy();
+        }
+        this.#ctx.register(name, frame._ldf);
+        return this;
+    }
+    registerMany(frames) {
+        for (const [name, frame] of Object.entries(frames)) {
+            this.register(name, frame);
+        }
+        return this;
+    }
+    unregister(names) {
+        if (typeof names === "string") {
+            names = [names];
+        }
+        for (const name of names) {
+            this.#ctx.unregister(name);
+        }
+        return this;
+    }
+    tables() {
+        return this.#ctx.getTables();
+    }
+}
+exports.SQLContext = SQLContext;

package/bin/types.d.ts

@@ -0,0 +1,284 @@
+import type { ValueOrArray } from "./utils";
+/**
+ * Downsample rules
+ */
+export type DownsampleRule = "month" | "week" | "day" | "hour" | "minute" | "second";
+/**
+ * Fill null strategies
+ */
+export type FillNullStrategy = "backward" | "forward" | "mean" | "min" | "max" | "zero" | "one";
+/**
+ * Rank methods
+ */
+export type RankMethod = "average" | "min" | "max" | "dense" | "ordinal" | "random";
+/**
+ * Round modes
+ */
+export type RoundMode = "halftoeven" | "halfawayfromzero";
+/**
+ * Options for {@link concat}
+ */
+export interface ConcatOptions {
+    rechunk?: boolean;
+    parallel?: boolean;
+    how?: "vertical" | "verticalRelaxed" | "horizontal" | "diagonal" | "diagonalRelaxed" | "align" | "alignInner" | "alignFull" | "alignLeft" | "alignRight";
+}
+/**
+ * Options for @see {@link DataFrame.writeCSV}
+ * Options for @see {@link LazyDataFrame.sinkCSV}
+ * @category Options
+ */
+export interface CsvWriterOptions {
+    includeBom?: boolean;
+    includeHeader?: boolean;
+    separator?: string;
+    quoteChar?: string;
+    lineTerminator?: string;
+    batchSize?: number;
+    datetimeFormat?: string;
+    dateFormat?: string;
+    timeFormat?: string;
+    floatPrecision?: number;
+    nullValue?: string;
+    maintainOrder?: boolean;
+}
+export interface SinkOptions {
+    syncOnClose: any;
+    maintainOrder: boolean;
+    mkdir: boolean;
+}
+/**
+ * Options for @see {@link LazyDataFrame.sinkParquet }
+ * @category Options
+ */
+export interface SinkParquetOptions {
+    compression?: string;
+    compressionLevel?: number;
+    statistics?: boolean;
+    rowGroupSize?: number;
+    dataPagesizeLimit?: number;
+    maintainOrder?: boolean;
+    typeCoercion?: boolean;
+    predicatePushdown?: boolean;
+    projectionPushdown?: boolean;
+    simplifyExpression?: boolean;
+    slicePushdown?: boolean;
+    noOptimization?: boolean;
+    cloudOptions?: Map<string, string>;
+    retries?: number;
+    sinkOptions?: SinkOptions;
+}
+/**
+ * Options for @see {@link LazyDataFrame.sinkNdJson}
+ * @category Options
+ */
+export interface SinkJsonOptions {
+    cloudOptions?: Map<string, string>;
+    retries?: number;
+    syncOnClose?: string;
+    maintainOrder?: boolean;
+    mkdir?: boolean;
+}
+/**
+ * Options for @see {@link LazyDataFrame.sinkIpc}
+ * @category Options
+ */
+export interface SinkIpcOptions {
+    compression?: string;
+    compatLevel?: string;
+    cloudOptions?: Map<string, string>;
+    retries?: number;
+    syncOnClose?: string;
+    maintainOrder?: boolean;
+    mkdir?: boolean;
+}
+/**
+ * Options for {@link DataFrame.writeJSON}
+ * @category Options
+ */
+export interface WriteJsonOptions {
+    orient?: "row" | "col" | "dataframe";
+    multiline?: boolean;
+}
+/**
+ * Options for {@link scanJson}
+ */
+export interface JsonScanOptions {
+    inferSchemaLength?: number;
+    nThreads?: number;
+    batchSize?: number;
+    lowMemory?: boolean;
+    numRows?: number;
+    skipRows?: number;
+    rowCount?: RowCount;
+}
+/**
+ * Options for {@link DataFrame.writeParquet}
+ * @category Options
+ */
+export interface WriteParquetOptions {
+    compression?: "uncompressed" | "snappy" | "gzip" | "lzo" | "brotli" | "lz4" | "zstd";
+}
+/**
+ * Options for {@link readParquet}
+ */
+export interface ReadParquetOptions {
+    columns?: string[] | number[];
+    numRows?: number;
+    parallel?: "auto" | "columns" | "row_groups" | "none";
+    rowCount?: RowCount;
+}
+/**
+ * Options for {@link scanParquet}
+ */
+export interface ScanParquetOptions {
+    nRows?: number;
+    rowIndexName?: string;
+    rowIndexOffset?: number;
+    cache?: boolean;
+    parallel?: "auto" | "columns" | "row_groups" | "none";
+    glob?: boolean;
+    hivePartitioning?: boolean;
+    hiveSchema?: unknown;
+    tryParseHiveDates?: boolean;
+    rechunk?: boolean;
+    lowMemory?: boolean;
+    useStatistics?: boolean;
+    cloudOptions?: Map<string, string>;
+    retries?: number;
+    includeFilePaths?: string;
+    allowMissingColumns?: boolean;
+}
+/**
+ * Add row count as column
+ */
+export interface RowCount {
+    /** name of column */
+    name: string;
+    /** offset */
+    offset: number;
+}
+/**
+ * Options for {@link DataFrame.writeIPC}
+ * @category Options
+ */
+export interface WriteIPCOptions {
+    compression?: "uncompressed" | "lz4" | "zstd";
+}
+/**
+ * Options for writing Avro files
+ * @category Options
+ */
+export interface WriteAvroOptions {
+    compression?: "uncompressed" | "snappy" | "deflate";
+}
+/**
+ * Interpolation types
+ */
+export type InterpolationMethod = "nearest" | "higher" | "lower" | "midpoint" | "linear";
+/**
+ * Join types
+ */
+export type JoinType = "left" | "inner" | "full" | "semi" | "anti" | "cross";
+/**
+ * options for same named column join @see {@link DataFrame.join}
+ */
+export type SameNameColumnJoinOptions<L extends string = string, R extends string = string> = {
+    /** Name(s) of the join columns in both DataFrames. */
+    on: ValueOrArray<L & R>;
+    /** Join strategy */
+    how?: Exclude<JoinType, "cross">;
+    /** Suffix to append to columns with a duplicate name. */
+    suffix?: string;
+    /** Coalescing behavior (merging of join columns). */
+    coalesce?: boolean;
+};
+/**
+ * options for differently named column join @see {@link DataFrame.join}
+ */
+export type DifferentNameColumnJoinOptions<L extends string = string, R extends string = string> = {
+    /** Name(s) of the left join column(s). */
+    leftOn: ValueOrArray<L>;
+    /** Name(s) of the right join column(s). */
+    rightOn: ValueOrArray<R>;
+    /** Join strategy */
+    how?: Exclude<JoinType, "cross">;
+    /** Suffix to append to columns with a duplicate name. */
+    suffix?: string;
+    /** Coalescing behavior (merging of join columns). */
+    coalesce?: boolean;
+};
+/**
+ * options for cross join @see {@link DataFrame.join}
+ */
+export type CrossJoinOptions = {
+    /** Join strategy */
+    how: "cross";
+    /** Suffix to append to columns with a duplicate name. */
+    suffix?: string;
+    /** Coalescing behavior (merging of join columns). */
+    coalesce?: boolean;
+};
+/**
+ * options for join operations @see {@link DataFrame.join}
+ */
+export type JoinOptions<L extends string = string, R extends string = string> = SameNameColumnJoinOptions<L, R> | DifferentNameColumnJoinOptions<L, R> | CrossJoinOptions;
+type LazyJoinBase = {
+    /** Allow the physical plan to optionally evaluate the computation of both DataFrames up to the join in parallel. */
+    allowParallel?: boolean;
+    /** Force the physical plan to evaluate the computation of both DataFrames up to the join in parallel. */
+    forceParallel?: boolean;
+};
+export type LazySameNameColumnJoinOptions<L extends string = string, R extends string = string> = SameNameColumnJoinOptions<L, R> & LazyJoinBase;
+export type LazyDifferentNameColumnJoinOptions<L extends string = string, R extends string = string> = DifferentNameColumnJoinOptions<L, R> & LazyJoinBase;
+export type LazyCrossJoinOptions = CrossJoinOptions & LazyJoinBase;
+/**
+ * options for lazy join operations @see {@link LazyDataFrame.join}
+ */
+export type LazyJoinOptions<L extends string = string, R extends string = string> = LazySameNameColumnJoinOptions<L, R> | LazyDifferentNameColumnJoinOptions<L, R> | LazyCrossJoinOptions;
+/**
+ * options for lazy operations @see {@link LazyDataFrame.collect}
+ */
+export type LazyOptions = {
+    typeCoercion?: boolean;
+    predicatePushdown?: boolean;
+    projectionPushdown?: boolean;
+    simplifyExpression?: boolean;
+    slicePushdown?: boolean;
+    noOptimization?: boolean;
+    commSubplanElim?: boolean;
+    commSubexprElim?: boolean;
+    streaming?: boolean;
+};
+/**
+ * options for rolling window operations
+ * @category Options
+ */
+export interface RollingOptions {
+    windowSize: number;
+    weights?: Array<number>;
+    minPeriods?: number;
+    center?: boolean;
+    ddof?: number;
+}
+/**
+ * options for rolling quantile operations
+ * @category Options
+ */
+export interface RollingQuantileOptions extends RollingOptions {
+    quantile: number;
+    interpolation?: InterpolationMethod;
+}
+/**
+ * options for rolling mean operations
+ * @category Options
+ */
+export interface RollingSkewOptions {
+    windowSize: number;
+    bias?: boolean;
+}
+/**
+ * ClosedWindow types
+ */
+export type ClosedWindow = "None" | "Both" | "Left" | "Right";
+export {};

package/bin/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/bin/utils.d.ts

@@ -0,0 +1,38 @@
+import { DataFrame } from "./dataframe";
+import { LazyDataFrame } from "./lazy/dataframe";
+import { Expr } from "./lazy/expr";
+import { Series } from "./series";
+/** @ignore */
+export type ValueOrArray<T> = T | Array<ValueOrArray<T>>;
+/** @ignore */
+export type ColumnSelection = ValueOrArray<string>;
+/** @ignore */
+export type ExpressionSelection = ValueOrArray<Expr>;
+/** @ignore */
+export type ColumnsOrExpr = ColumnSelection | ExpressionSelection;
+/** @ignore */
+export type ExprOrString = Expr | string;
+/**
+ * @typeParam StartBy - The strategy to determine the start of the first window by.
+ */
+export type StartBy = "window" | "datapoint" | "monday" | "tuesday" | "wednesday" | "thursday" | "friday" | "saturday" | "sunday";
+/** @ignore */
+export declare function columnOrColumns(columns: ColumnSelection | string | Array<string> | undefined): Array<string> | undefined;
+/** @ignore */
+export declare function columnOrColumnsStrict(...columns: string[] | ValueOrArray<string>[]): Array<string>;
+/** @ignore */
+export declare function selectionToExprList(columns: any[], stringToLit?: any): any[];
+/** @ignore */
+export declare function isPath(s: string, expectedExtensions?: string[]): boolean;
+export declare const range: (start: number, end: number) => number[];
+export declare const isDataFrameArray: (ty: any) => ty is DataFrame[];
+export declare const isLazyDataFrameArray: (ty: any) => ty is LazyDataFrame[];
+export declare const isSeriesArray: <_T>(ty: any) => ty is Series[];
+export declare const isExprArray: (ty: any) => ty is Expr[];
+export declare const isIterator: <T>(ty: any) => ty is Iterable<T>;
+export declare const regexToString: (r: string | RegExp) => string;
+export declare const commonValue: (...arr: string[][]) => string[];
+export declare const INSPECT_SYMBOL: unique symbol;
+export type Simplify<T> = {
+    [K in keyof T]: T[K];
+} & {};