jsonstat-io 0.1.0

package/docs/formats/arrow.md

@@ -0,0 +1,111 @@
+# Arrow Format
+
+Apache Arrow is the **hub** of `jsonstat-io`. Parquet, DuckDB, and Polars all produce Arrow tables, and a single converter pair ([`arrowToCube`](../../src/arrow/arrowToCube.ts) / [`cubeToArrow`](../../src/arrow/arrowFromCube.ts)) handles them all in both directions.
+
+## Import path
+
+```ts
+import { arrowToCube, arrowToDataset } from "jsonstat-io";
+// or from the dedicated subpath:
+import { arrowToCube } from "jsonstat-io/arrow";
+```
+
+`apache-arrow` is a **hard dependency** — no peer install needed.
+
+## Reading an Arrow IPC file
+
+```ts
+import { tableFromIPC } from "apache-arrow";
+import { arrowToDataset } from "jsonstat-io";
+import { readFileSync } from "node:fs";
+
+const bytes = readFileSync("./data.arrow");
+const table = tableFromIPC(bytes);
+const dataset = arrowToDataset(table, { measure: "amount" });
+```
+
+In the browser, fetch the bytes and pass them directly:
+
+```ts
+const res = await fetch("/data.arrow");
+const bytes = new Uint8Array(await res.arrayBuffer());
+const table = tableFromIPC(bytes);
+const dataset = arrowToDataset(table);
+```
+
+## How Arrow columns map
+
+| Arrow column type            | JSON-stat role   | Detection |
+|------------------------------|------------------|-----------|
+| `Dictionary<Utf8, Int*>`     | dimension        | Always a dimension |
+| `Utf8`, `Bool`, temporal     | dimension        | Stringified |
+| `Float64`, `Float32`, `Int*` | measure (first)  | First numeric column, unless overridden |
+| Any column with `jsonstat.status: "true"` | status | Metadata marker |
+
+### Without metadata (heuristic mode)
+
+`arrowToCube` infers:
+1. The first `Float64`/`Float32`/`Int64`/`Int32` column is the **measure**.
+2. A column named `status` (case-insensitive) is the **status** column.
+3. All other columns are **dimensions**, in schema order.
+4. Roles: `year`/`date`/`time`/`period` → `time`; `country`/`region`/`geo`/`area` → `geo`; the measure → `metric`.
+
+### With metadata (lossless mode)
+
+Annotate Arrow `Field` and `Schema` metadata with `jsonstat.*` keys for exact, lossless mapping. See the [metadata key reference](../mapping.md#arrow-schema-metadata-contract).
+
+```ts
+import { Field, Schema, Dictionary, Utf8, Int32, Float64 } from "apache-arrow";
+import { buildFieldMeta, buildSchemaMeta } from "jsonstat-io";
+
+const yearField = new Field("year", new Dictionary(new Utf8(), new Int32()), false,
+  new Map(Object.entries(buildFieldMeta({
+    role: "time",
+    label: "Year",
+    categoryOrder: ["2020", "2021", "2022"],
+    categoryLabels: { "2020": "FY 2020", "2021": "FY 2021" },
+  })))
+);
+
+const schema = new Schema(
+  [yearField, /* ... */],
+  new Map(Object.entries(buildSchemaMeta({ label: "Annual Sales", source: "Finance Dept" })))
+);
+```
+
+## Annotating for round-trip fidelity
+
+To guarantee that `arrowToCube` → `cubeToArrow` round-trips losslessly, annotate:
+
+- **Schema**: `jsonstat.label`, `jsonstat.source`, `jsonstat.updated`, `jsonstat.valueForm`.
+- **Each dimension field**: `jsonstat.role`, `jsonstat.label`, `jsonstat.categoryLabels`, `jsonstat.categoryUnits`, `jsonstat.categoryCoords`, `jsonstat.categoryChild`, `jsonstat.categoryOrder`.
+- **Measure field**: `jsonstat.measure: "true"` (or `jsonstat.role: "metric"`).
+- **Status field**: `jsonstat.status: "true"`.
+
+## Export path
+
+[`cubeToArrow`](../../src/arrow/arrowFromCube.ts) converts the `Observations` IR back to an Arrow `Table`, building dictionary-encoded dimensions and a Float64 measure with full `jsonstat.*` metadata annotation.
+
+```ts
+import { exportDataset } from "jsonstat-io";
+
+// JSON-stat → Arrow Table
+const table = await exportDataset(dataset, { to: "arrow" });
+```
+
+Or use `cubeToArrow` directly on the IR:
+
+```ts
+import { cubeToArrow } from "jsonstat-io";
+// obs = Observations IR
+const table = cubeToArrow(obs);
+```
+
+### CLI
+
+```sh
+# JSON-stat → Arrow IPC file
+npx jsonstat-io ./data.jsonstat.json --to arrow -o data.arrow
+```
+
+The exporter writes Arrow IPC stream format. `cubeToArrow` is also the foundation for the Parquet, DuckDB, and Polars exporters — they all call `cubeToArrow` first, then convert the resulting Arrow Table to their target format.

package/docs/formats/csv.md

@@ -0,0 +1,115 @@
+# CSV Format
+
+Plain CSV (no metadata) is the simplest path. The [`csvToCube`](../../src/sources/csv.ts) adapter infers the measure and dimensions heuristically on import. On export, [`cubeToCsv`](../../src/sources/csv.ts) serializes the IR to CSV text. It is **dependency-free** and works in both Node and the browser.
+
+## Import path
+
+```ts
+import { csvToCube, parseCsv } from "jsonstat-io/csv";
+```
+
+Or use the high-level dispatcher:
+
+```ts
+import { importToDataset } from "jsonstat-io";
+const dataset = await importToDataset("./data.csv", { from: "csv", measure: "amount" });
+```
+
+## Inference heuristics (no metadata)
+
+Without a schema, the adapter infers:
+
+1. The **measure** is the first column that parses as a number for every non-empty row — or the one named by `options.measure`.
+2. A column named `status` (case-insensitive) is the **status** column — unless `options.status` overrides it.
+3. Every other column is a **dimension** (string-typed), in file order.
+
+Empty cells become `null` in the measure and `""` in dimensions. For richer, lossless mapping with declared types/labels/roles, use [CSVW](./csvw.md) instead.
+
+## Import example
+
+```ts
+import { csvToCube } from "jsonstat-io/csv";
+import { buildDataset } from "jsonstat-io";
+
+const csvText = `year,country,amount
+2020,Spain,100
+2020,France,200
+2021,Spain,150
+2021,France,250`;
+
+const obs = csvToCube(csvText, {
+  measure: "amount",
+  roles: { time: ["year"], geo: ["country"] },
+});
+
+const { dataset } = buildDataset(obs, { valueForm: "dense" });
+```
+
+## Export path
+
+[`cubeToCsv`](../../src/sources/csv.ts) serializes the `Observations` IR to CSV text. The output has one column per dimension (in `id[]` order), followed by the measure column, and an optional status column.
+
+```ts
+import { exportDataset } from "jsonstat-io";
+
+// JSON-stat → CSV text
+const csv = await exportDataset(dataset, { to: "csv" });
+```
+
+Or use `cubeToCsv` directly on the IR:
+
+```ts
+import { cubeToCsv } from "jsonstat-io/csv";
+
+const csv = cubeToCsv(obs, { delimiter: ";" });
+```
+
+### CLI
+
+```sh
+# JSON-stat → CSV
+npx jsonstat-io ./data.jsonstat.json --to csv -o data.csv
+
+# With custom delimiter via CSVW metadata (CSV itself has no delimiter flag)
+npx jsonstat-io ./data.jsonstat.json --to csvw -o data.csvw --delimiter ";"
+```
+
+## Import CLI
+
+```sh
+# From a file
+npx jsonstat-io ./data.csv --from csv --measure amount --role time=year,geo=country
+
+# From stdin
+cat data.csv | npx jsonstat-io - --measure amount
+
+# Custom delimiter
+npx jsonstat-io ./data.csv --delimiter ";"
+```
+
+When `--from` is omitted, `.csv` extension triggers CSV detection. The CLI checks for a sibling `*-metadata.json` first; if found, it uses CSVW, otherwise plain CSV.
+
+## Options
+
+### `CsvToCubeOptions` (import)
+
+| Field        | Type                              | Default  | Description |
+|--------------|-----------------------------------|----------|-------------|
+| `measure`    | `string`                          | *(inferred)* | Explicit measure column name |
+| `dimensions` | `string[]`                        | *(inferred)* | Explicit dimension column names |
+| `status`     | `string`                          | *(inferred)* | Status column name |
+| `roles`      | `RoleMap`                         | —        | Role assignments |
+| `valueForm`  | `"auto" \| "dense" \| "sparse"`  | `"auto"` | Value form hint |
+| `delimiter`  | `string`                          | `","`    | CSV delimiter |
+| `header`     | `boolean`                         | `true`   | Treat first row as header |
+
+### `CubeToCsvOptions` (export)
+
+| Field           | Type     | Default | Description |
+|-----------------|----------|---------|-------------|
+| `delimiter`     | `string` | `","`   | CSV delimiter. |
+| `lineTerminator`| `string` | `"\n"`  | Row separator. |
+
+## Parser
+
+The bundled `parseCsv(input, delimiter?)` is a tiny, dependency-free RFC-4180-ish CSV parser. It handles quoted fields, embedded quotes (doubled), and embedded newlines. For heavy CSV work (large files, complex quoting), prefer piping through DuckDB or Polars.

package/docs/formats/csvw.md

@@ -0,0 +1,152 @@
+# CSVW Format
+
+[CSV on the Web (CSVW)](https://www.w3.org/TR/tabular-metadata/) provides a metadata layer over plain CSV, declaring column types, names, and roles. This enables **lossless** CSV → JSON-stat mapping without heuristics. On export, the IR is serialized to CSV text plus a CSVW metadata JSON document.
+
+CSVW is a **dependency-free** path — no optional peers needed. It works in both Node and the browser.
+
+## Import path
+
+```ts
+import { csvwToCube, csvwToDataset, parseCsvwMetadata } from "jsonstat-io/csvw";
+```
+
+Or use the high-level dispatcher:
+
+```ts
+import { importToDataset } from "jsonstat-io";
+
+// If a sibling *-metadata.json exists next to the CSV (Node):
+const dataset = await importToDataset("./data.csv", { from: "csvw" });
+
+// Or pass metadata inline:
+const dataset = await importToDataset("./data.csv", {
+  from: "csvw",
+  csvwMetadata: metadataObject,
+});
+```
+
+## Metadata structure
+
+`csvwToCube` expects a parsed CSVW metadata object with this shape:
+
+```json
+{
+  "tableSchema": {
+    "columns": [
+      { "titles": "year", "datatype": "string", "propertyUrl": "http://example.org/#time" },
+      { "titles": "country", "datatype": "string" },
+      { "titles": "amount", "datatype": "decimal" }
+    ],
+    "primaryKey": ["year", "country"]
+  }
+}
+```
+
+### Column mapping
+
+| CSVW property                         | Maps to |
+|---------------------------------------|---------|
+| `titles` (first)                      | Column name |
+| `datatype` = `decimal`/`integer`/`double` | Measure column |
+| Other `datatype`                      | Dimension column |
+| `propertyUrl` containing `#time`      | `time` role |
+| `propertyUrl` containing `#geo`       | `geo` role |
+| `primaryKey`                          | Dimension columns (if no explicit `options.dimensions`) |
+
+### Role detection from `propertyUrl`
+
+The adapter checks if the `propertyUrl` contains a fragment hint:
+
+- `...#time` or `...#temporal` → `time` role
+- `...#geo` or `...#spatial` → `geo` role
+
+## Import example
+
+```ts
+import { csvwToDataset, parseCsvwMetadata } from "jsonstat-io/csvw";
+import { readFileSync } from "node:fs";
+
+const csvText = readFileSync("./sales.csv", "utf8");
+const metadataJson = JSON.parse(readFileSync("./sales-metadata.json", "utf8"));
+const metadata = parseCsvwMetadata(metadataJson);
+
+const dataset = csvwToDataset(csvText, metadata, {
+  dimensions: ["year", "country"],  // optional: overrides primaryKey
+  roles: { time: ["year"] },        // optional: overrides propertyUrl
+});
+```
+
+## Export path
+
+[`cubeToCsvw`](../../src/sources/csvw.ts) serializes the `Observations` IR to a CSV text string **plus** a CSVW metadata JSON object, so the pair round-trips losslessly back through `csvwToCube`.
+
+```ts
+import { exportDataset } from "jsonstat-io";
+
+// JSON-stat → CSV text + CSVW metadata
+const { csv, metadata } = await exportDataset(dataset, { to: "csvw" });
+```
+
+Or use `cubeToCsvw` directly on the IR:
+
+```ts
+import { cubeToCsvw } from "jsonstat-io/csvw";
+
+const { csv, metadata } = cubeToCsvw(obs);
+// csv: string           — the CSV text
+// metadata: CsvwMetadata — the CSVW metadata object (JSON-serializable)
+```
+
+The metadata object includes `@context`, `url`, `tableSchema` (columns with `titles`, `datatype`, `propertyUrl`), `primaryKey` (dimension IDs), and `dc:title`/`dc:source` from the dataset label/source.
+
+### CLI
+
+```sh
+# JSON-stat → CSV + sibling CSVW metadata file
+npx jsonstat-io ./sales.jsonstat.json --to csvw -o sales.csvw
+
+# With -o, writes sales.csvw and sales-metadata.json
+# Without -o, prints CSV + a separator + metadata JSON to stdout
+```
+
+## Import CLI
+
+```sh
+# Auto-loads sibling *-metadata.json
+npx jsonstat-io ./sales.csv --from csvw
+
+# Inline metadata
+npx jsonstat-io ./sales.csv --from csvw \
+  --csvw-metadata '{"tableSchema":{"columns":[{"titles":"year"},{"titles":"amount","datatype":"decimal"}],"primaryKey":["year"]}}'
+```
+
+When `--from csvw` is set and no metadata is supplied, the CLI tries to load `sales-metadata.json` next to `sales.csv`. If not found, it throws with a helpful message suggesting `--from csv` instead.
+
+## Plain CSV (no metadata)
+
+For plain CSV without a metadata file, use [`jsonstat-io/csv`](./csv.md) which infers the measure and dimensions heuristically:
+
+```ts
+import { csvToCube } from "jsonstat-io/csv";
+
+const obs = csvToCube(csvText, { measure: "amount" });
+```
+
+See the [CSV adapter](../../src/sources/csv.ts) for inference rules: first all-numeric column = measure, `status`-named column = status, everything else = dimension.
+
+## Options
+
+### Import (`csvwToCube`)
+
+| Field        | Type       | Description |
+|--------------|------------|-------------|
+| `measure`    | `string`   | Override the detected measure column |
+| `dimensions` | `string[]` | Override dimension columns (overrides primaryKey) |
+| `status`     | `string`   | Status column name |
+| `roles`      | `RoleMap`  | Role assignments (overrides propertyUrl) |
+
+### Export (`CubeToCsvwOptions`)
+
+| Field        | Type     | Default | Description |
+|--------------|----------|---------|-------------|
+| `delimiter`  | `string` | `","`   | CSV delimiter. |

package/docs/formats/duckdb.md

@@ -0,0 +1,151 @@
+# DuckDB Format
+
+Run a SQL query against DuckDB and convert the result (an Arrow table) to JSON-stat via the [Arrow hub](./arrow.md). On export, register an Arrow-backed view or table into a DuckDB connection. Two optional peer backends are supported:
+
+- **Node**: [`duckdb-async`](https://github.com/mortonreddy/duckdb-async) — native binding.
+- **Browser**: [`@duckdb/duckdb-wasm`](https://github.com/duckdb/duckdb-wasm) — WASM.
+
+## Install
+
+```sh
+# Node
+npm install jsonstat-io duckdb-async
+
+# Browser
+npm install jsonstat-io @duckdb/duckdb-wasm
+```
+
+Both are **optional peer dependencies**. The DuckDB adapter is **not** available via the CLI for import — it requires a live connection, so use the programmatic API.
+
+## Import path
+
+```ts
+import { duckdbToCube, duckdbToDataset, openDuckdbNode } from "jsonstat-io/duckdb";
+```
+
+## Node example
+
+```ts
+import { duckdbToDataset, openDuckdbNode } from "jsonstat-io/duckdb";
+
+const conn = await openDuckdbNode("./warehouse.duckdb");
+const dataset = await duckdbToDataset(conn, 
+  "SELECT year, country, amount FROM sales WHERE year >= 2020",
+  { roles: { time: ["year"], geo: ["country"] } }
+);
+```
+
+`openDuckdbNode(path?)` is a convenience helper that lazily imports `duckdb-async` and returns a `DuckdbConnection`. Pass `":memory:"` (the default) for an in-memory database.
+
+## Browser example
+
+Set up `@duckdb/duckdb-wasm` yourself, then pass the connection:
+
+```ts
+import * as duckdb from "@duckdb/duckdb-wasm";
+import { duckdbToDataset } from "jsonstat-io/duckdb";
+
+// Standard duckdb-wasm bootstrap (see their docs for full setup)
+const bundle = await duckdb.selectBundle(duckdb.getBundle());
+const worker = new Worker(bundle.mainWorker);
+const db = new duckdb.AsyncDuckDB(logger, worker);
+await db.instantiate(bundle.mainModule, bundle.pthreadWorker);
+const conn = await db.connect();
+
+const dataset = await duckdbToDataset(conn, "SELECT * FROM sales");
+```
+
+The adapter normalizes both `duckdb-async` and `duckdb-wasm` connection shapes — it looks for `.arrow()` or `.arrowResult()` methods.
+
+## Connection factory
+
+For lazy browser setups, pass a `connect` factory instead of a live connection. The adapter opens and closes it automatically:
+
+```ts
+const obs = await duckdbToCube(null, query, {
+  connect: async () => await createConnection(),
+});
+```
+
+## Export path
+
+[`cubeToDuckdb`](../../src/sources/duckdb.ts) converts the `Observations` IR to an Arrow table (via `cubeToArrow`) and registers it as a named view or table in the DuckDB connection.
+
+```ts
+import { exportDataset } from "jsonstat-io";
+
+// JSON-stat → Arrow-backed view in DuckDB
+const table = await exportDataset(dataset, {
+  to: "duckdb",
+  connection: conn,
+  tableName: "sales",
+  mode: "view",  // or "table" to materialize
+});
+```
+
+Or use `cubeToDuckdb` directly on the IR:
+
+```ts
+import { cubeToDuckdb } from "jsonstat-io/duckdb";
+
+await cubeToDuckdb(conn, obs, { tableName: "sales", mode: "view" });
+
+// Now queryable in DuckDB:
+const result = await conn.arrow("SELECT * FROM sales WHERE amount > 100");
+```
+
+### Export modes
+
+| Mode   | Behavior |
+|--------|----------|
+| `"view"` (default) | Registers a temporary Arrow-backed view — fast, zero-copy, lives for the connection's lifetime. |
+| `"table"` | Materializes the Arrow data into a persistent DuckDB table via `CREATE TABLE ... AS SELECT * FROM <view>`. |
+
+## Options
+
+### `DuckdbToCubeOptions` (import)
+
+Extends [`ArrowToCubeOptions`](./arrow.md):
+
+| Field    | Type                            | Description |
+|----------|---------------------------------|-------------|
+| `connect`| `() => Promise<DuckdbConnection>` | Factory that returns a fresh connection (browser). Takes precedence over `connection`, closed after use. |
+| `measure`| `string`                        | Measure column name |
+| `dimensions` | `string[]`                 | Dimension column names |
+| `roles`  | `RoleMap`                       | Role assignments |
+
+### `CubeToDuckdbOptions` (export)
+
+| Field       | Type                      | Default   | Description |
+|-------------|---------------------------|-----------|-------------|
+| `tableName` | `string`                  | `"data"`  | Name of the view/table to create. |
+| `mode`      | `"view" \| "table"`       | `"view"`  | Register a zero-copy view or materialize a table. |
+
+## DuckdbConnection interface
+
+```ts
+interface DuckdbConnection {
+  arrow(query: string): Promise<any>;  // Returns an Apache Arrow Table
+  close?(): Promise<void>;
+  // Export-side (registered by cubeToDuckdb):
+  register?(name: string, table: any): Promise<void>;
+  insert_arrow_table?(table: any, name: string): Promise<void>;
+  run?(sql: string): Promise<void>;
+}
+```
+
+Both `duckdb-async` and `@duckdb/duckdb-wasm` connections satisfy this interface. If your connection uses `arrowResult()` instead of `arrow()`, the adapter handles that too.
+
+## How it works
+
+**Import:**
+1. `duckdbToCube` runs the SQL query via `conn.arrow(query)` (or `arrowResult()`).
+2. Gets back an Apache Arrow `Table`.
+3. Passes it to `arrowToCube` → `Observations` IR.
+
+**Export:**
+1. `cubeToDuckdb` calls `cubeToArrow(obs)` → Apache Arrow `Table`.
+2. Registers the table into the connection via `conn.register(name, table)` (or `insert_arrow_table`).
+3. For `mode: "table"`, runs `CREATE TABLE <name> AS SELECT * FROM <tmpview>`.
+
+If neither DuckDB package is installed, a `DuckdbSourceError` is thrown.

package/docs/formats/parquet.md

@@ -0,0 +1,132 @@
+# Parquet Format
+
+Parquet files are read via [`parquet-wasm`](https://github.com/kylebarron/parquet-wasm), which decodes Parquet into an Apache Arrow table — then the [Arrow hub](./arrow.md) takes over. On export, the same Arrow table is written back to Parquet bytes via `parquet-wasm`'s `writeParquet`.
+
+## Install
+
+```sh
+npm install jsonstat-io parquet-wasm
+```
+
+`parquet-wasm` is an **optional peer dependency**. It works in both Node and the browser.
+
+## Import path
+
+```ts
+import { parquetToCube, parquetToDataset } from "jsonstat-io/parquet";
+```
+
+Or use the high-level dispatcher (auto-detects Parquet from `PAR1` magic bytes):
+
+```ts
+import { importToDataset } from "jsonstat-io";
+const dataset = await importToDataset("./sales.parquet");
+```
+
+## Node example
+
+```ts
+import { readFileSync } from "node:fs";
+import { parquetToDataset } from "jsonstat-io/parquet";
+
+const bytes = readFileSync("./sales.parquet");
+const dataset = await parquetToDataset(bytes, {
+  measure: "amount",
+  roles: { time: ["year"], geo: ["country"] },
+});
+```
+
+## Browser example
+
+`parquet-wasm` needs its WASM binary loaded. Pass an `init` function to set the base URL or call `parquetWasm.init()`:
+
+```ts
+import { parquetToDataset } from "jsonstat-io/parquet";
+
+async function initParquet() {
+  const wasm = await import("parquet-wasm");
+  if (typeof wasm.init === "function") await wasm.init();
+}
+
+const bytes = new Uint8Array(await (await fetch("/sales.parquet")).arrayBuffer());
+const dataset = await parquetToDataset(bytes, { init: initParquet });
+```
+
+## Export path
+
+[`cubeToParquet`](../../src/sources/parquet.ts) converts the `Observations` IR to Parquet bytes: it calls `cubeToArrow` to build the Arrow table, then `parquet-wasm`'s `writeParquet` to serialize.
+
+```ts
+import { exportDataset } from "jsonstat-io";
+
+// JSON-stat → Parquet bytes
+const bytes = await exportDataset(dataset, {
+  to: "parquet",
+  init: () => parquetWasm.init(),
+});
+```
+
+Or use `cubeToParquet` directly on the IR:
+
+```ts
+import { cubeToParquet } from "jsonstat-io/parquet";
+
+const bytes = await cubeToParquet(obs, {
+  init: () => parquetWasm.init(),
+  compression: "snappy",
+});
+```
+
+### CLI
+
+```sh
+# JSON-stat → Parquet
+npx jsonstat-io ./sales.jsonstat.json --to parquet -o sales.parquet
+```
+
+## Import CLI
+
+```sh
+npx jsonstat-io ./sales.parquet -o sales.jsonstat.json
+npx jsonstat-io ./sales.parquet --from parquet --sparse
+```
+
+The CLI auto-detects Parquet from the `PAR1` magic bytes, so `--from parquet` is optional.
+
+## Options
+
+### `ParquetToCubeOptions` (import)
+
+Extends [`ArrowToCubeOptions`](./arrow.md):
+
+| Field     | Type           | Description |
+|-----------|----------------|-------------|
+| `init`    | `() => Promise<void>` | Async initializer for parquet-wasm (e.g. to set the WASM base URL in the browser). Awaited before reading. |
+| `measure` | `string`       | Measure column name |
+| `dimensions` | `string[]`   | Dimension column names |
+| `roles`   | `RoleMap`      | Role assignments |
+
+### `CubeToParquetOptions` (export)
+
+| Field        | Type           | Description |
+|--------------|----------------|-------------|
+| `init`       | `() => Promise<void>` | Async initializer for parquet-wasm. |
+| `compression`| `string`       | Parquet compression codec (e.g. `"snappy"`, `"gzip"`). |
+
+## How it works
+
+> **Dual-Arrow IPC bridge:** `parquet-wasm` bundles its own copy of `apache-arrow`, so an `instanceof Table` check against its internal `Table` class fails for our caller's `Table` (and vice versa). The adapter bridges this with IPC serialization — a format both copies understand:
+
+**Import:**
+1. `parquetToCube` lazily imports `parquet-wasm`.
+2. Calls `wasm.readParquet(bytes)` → parquet-wasm `Table`.
+3. Serializes via `wasmTable.intoIPCStream()` → reconstructs with `tableFromIPC()` (our apache-arrow).
+4. Passes the reconstructed table to `arrowToCube` → `Observations` IR.
+
+**Export:**
+1. `cubeToParquet` lazily imports `parquet-wasm`.
+2. Calls `cubeToArrow(obs)` → Apache Arrow `Table`.
+3. Serializes via `tableToIPC(table, "stream")` → reconstructs with `wasm.Table.fromIPCStream(ipc)` (parquet-wasm's `Table`).
+4. Calls `wasm.writeParquet(wasmTable, writerProps)` → `Uint8Array`.
+
+If `parquet-wasm` is not installed, a `ParquetSourceError` is thrown with install instructions.