nodejs-polars

Benchmark results are printed to the console via console.table and saved to ./benchmarks/list-operations.csv.

Metrics

• Timings: All values are in milliseconds (lower is better).
• mean: The average time across all iterations.
• min: The fastest single run.
• max: The slowest single run.
• stddev: The standard deviation across iterations.

Data Organization

Rows are grouped by list_size, then by operation, and sorted by mean time. This ensures the fastest data structure for a specific operation appears at the top of its group.

You can install nodejs-polars using your preferred package manager. Note that releases occur frequently, so regular updates are recommended to receive the latest features and bugfixes.

Minimum Requirements:

• Node version >=18
• Rust version >=1.86 (only required if compiling from source)

yarn add nodejs-polars   # yarn
npm i -s nodejs-polars   # npm
bun i -D nodejs-polars   # Bun

In Deno, you can import Polars directly from npm. For notebook environments, you can display DataFrames using the display function (Deno 1.37+) or by making the DataFrame the last expression in a cell (Deno 1.38+).

// Standard import
import pl from "npm:nodejs-polars";

// Deno Notebook (1.38+)
import pl from "npm:nodejs-polars";
let response = await fetch(
  "https://cdn.jsdelivr.net/npm/world-atlas@1/world/110m.tsv",
);
let data = await response.text();
let df = pl.readCSV(data, { sep: "\t" });
df // Last expression renders in notebook

The benchmark suite compares nodejs-polars Series performance against native JavaScript arrays, lodash, and ramda for basic list operations.

Prerequisites

1. Build the project: You must have a build of nodejs-polars available to require("nodejs-polars"). It is recommended to build it from the repository root first using yarn build.
2. Prepare the directory: Ensure the benchmarks/ directory exists, as results are appended to ./benchmarks/list-operations.csv.

Execution Steps

From the benches/ directory, run:

# 1. Install comparison dependencies
yarn install

# 2. Run the benchmark suite
node ./list-operations.js

Depending on your module system, import the library as follows:

ESM:

import pl from 'nodejs-polars';

CommonJS (require):

const pl = require('nodejs-polars');

// esm
import pl from 'nodejs-polars';

// require
const pl = require('nodejs-polars');

To get a bleeding edge release or maximal performance, you can compile Polars from source. This requires the Rust compiler.

Steps:

1. Install the latest Rust compiler.
2. Run npm|yarn install in the repository.
3. Run the build commands:

• For fastest binary (long compile times): cd nodejs-polars && yarn build && yarn build:ts

• For debugging (fastest compile times, slow/large binary): cd nodejs-polars && yarn build:debug && yarn build:ts

# Fastest binary
cd nodejs-polars && yarn build && yarn build:ts

# Debugging build
cd nodejs-polars && yarn build:debug && yarn build:ts

A Series represents a single column in a Polars DataFrame. It is an ArrayLike object that supports various data manipulation operations including arithmetic, comparison, rolling windows, and cumulative operations. It provides specialized namespaces for different data types:

• str: SeriesStringFunctions for string operations.
• list: SeriesListFunctions for list/array operations.
• dt: SeriesDateFunctions for datetime operations.
• struct: SeriesStructFunctions for struct operations.

Polars provides two ways to add data to a Series:

1. append(other): Adds the chunks from the other Series to the chunks of this series. Use this when appending many times (e.g., reading multiple files) before performing a query. Finish with rechunk() if needed.
2. extend(other): Appends data from other to the underlying memory locations. This may cause a reallocation but results in a single chunk, making subsequent queries faster. Use this for online operations where you add rows and immediately rerun a query.

Note: extend modifies the series in-place.

const a = pl.Series("a", [1, 2, 3]);
const b = pl.Series("b", [4, 5]);

// Option 1: Append (adds chunks)
a.append(b);

// Option 2: Extend (modifies in-place, potentially reallocates)
a.extend(b);