jsonstat-io 0.1.0

package/dist/sources/parquet.d.ts

@@ -0,0 +1,83 @@
+import { O as Observations } from '../ir-Jae2ymov.js';
+import { J as JsonStatDataset } from '../jsonstat-BX4mBLci.js';
+import { A as ArrowToCubeOptions } from '../arrowToCube-Mjr79ZHM.js';
+import { Table } from 'apache-arrow';
+
+/**
+ * Parquet adapter — `jsonstat-io/parquet`.
+ *
+ * **Import:** reads a Parquet file (bytes) into an Arrow [`Table`] via
+ * `parquet-wasm`, then funnels through the Arrow hub
+ * ([`arrowToCube`](../arrow/arrowToCube.ts)).
+ *
+ * **Export:** [`cubeToParquet`] writes the [`Observations`] IR to a Parquet
+ * file via `cubeToArrow` → `parquet-wasm` `writeParquet`.
+ *
+ * `parquet-wasm` is an **optional peer dependency** — it is imported lazily so
+ * that consumers who never touch Parquet pay no bundle cost. If it is not
+ * installed, calling [`parquetToCube`] / [`cubeToParquet`] throws a helpful
+ * error.
+ */
+
+declare class ParquetSourceError extends Error {
+    constructor(message: string);
+}
+interface ParquetToCubeOptions extends ArrowToCubeOptions {
+    /**
+     * Async initializer for parquet-wasm (e.g. to set the WASM base URL in the
+     * browser). If provided, it is awaited before reading. Defaults to a no-op.
+     */
+    init?: () => Promise<void>;
+}
+/**
+ * Read a Parquet file (as `Uint8Array` / `ArrayBuffer`) into the
+ * [`Observations`] IR.
+ *
+ * @throws [`ParquetSourceError`] if parquet-wasm is missing or the file is invalid.
+ */
+declare function parquetToCube(bytes: Uint8Array | ArrayBuffer, options?: ParquetToCubeOptions): Promise<Observations>;
+/** Convenience: Parquet bytes → JSON-stat [`Dataset`]. */
+declare function parquetToDataset(bytes: Uint8Array | ArrayBuffer, options?: ParquetToCubeOptions): Promise<JsonStatDataset>;
+interface CubeToParquetOptions {
+    /**
+     * Async initializer for parquet-wasm (e.g. to set the WASM base URL in the
+     * browser). If provided, it is awaited before writing. Defaults to a no-op.
+     */
+    init?: () => Promise<void>;
+    /**
+     * Compression codec. Falls back to parquet-wasm's default (Snappy) when
+     * undefined. Friendly names (case-insensitive) accepted: `"uncompressed"`,
+     * `"snappy"`, `"gzip"`, `"brotli"`, `"lz4"`, `"lz4_raw"`, `"zstd"`, `"lzo"`.
+     * Codec availability depends on the parquet-wasm build flavor (e.g. Brotli
+     * may be absent in slim builds); an unavailable codec surfaces as a
+     * [`ParquetSourceError`].
+     */
+    compression?: string;
+}
+/**
+ * Serialize an Arrow [`Table`] to Parquet bytes using `parquet-wasm`. Extracted
+ * so [`cubeToParquet`] and the round-trip tests share one path.
+ *
+ * @internal
+ */
+declare function arrowToParquet(table: Table, options?: CubeToParquetOptions): Promise<Uint8Array>;
+/**
+ * Write the [`Observations`](../model/ir.ts) IR to a Parquet file (bytes).
+ *
+ * The IR is first converted to an Arrow [`Table`] via [`cubeToArrow`], then
+ * serialized to Parquet via `parquet-wasm`'s `writeParquet`. All `jsonstat.*`
+ * schema/field metadata is preserved, so the result round-trips through
+ * [`parquetToCube`].
+ *
+ * @returns A `Uint8Array` of the Parquet file.
+ * @throws [`ParquetSourceError`] if parquet-wasm is missing or the write fails.
+ *
+ * @example
+ * ```ts
+ * import { cubeToParquet } from "jsonstat-io/parquet";
+ * const bytes = await cubeToParquet(observations);
+ * ```
+ */
+declare function cubeToParquet(obs: Observations, options?: CubeToParquetOptions): Promise<Uint8Array>;
+
+export { type CubeToParquetOptions, ParquetSourceError, type ParquetToCubeOptions, arrowToParquet, cubeToParquet, parquetToCube, parquetToDataset };

package/dist/sources/parquet.js

@@ -0,0 +1,111 @@
+import { arrowToCube, cubeToArrow } from '../chunk-IDTQZG4B.js';
+import { tableFromIPC, tableToIPC } from 'apache-arrow';
+
+var ParquetSourceError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ParquetSourceError";
+  }
+};
+async function ensureParquetWasmInit(mod) {
+  const initialize = typeof mod.default === "function" ? mod.default : typeof mod.init === "function" ? mod.init : void 0;
+  if (initialize) await initialize();
+}
+async function loadParquetWasm() {
+  try {
+    const mod = await import('parquet-wasm');
+    await ensureParquetWasmInit(mod);
+    if (mod.default && typeof mod.default.readParquet === "function") return mod.default;
+    return mod;
+  } catch (e) {
+    throw new ParquetSourceError(
+      "parquet-wasm is not installed. Install it with `npm i parquet-wasm` to read Parquet files."
+    );
+  }
+}
+async function parquetToCube(bytes, options = {}) {
+  if (options.init) await options.init();
+  const wasm = await loadParquetWasm();
+  let wasmTable;
+  try {
+    wasmTable = wasm.readParquet(bytes);
+  } catch (e) {
+    throw new ParquetSourceError(`Failed to read Parquet: ${e?.message ?? e}`);
+  }
+  if (!wasmTable) throw new ParquetSourceError("parquet-wasm returned no table");
+  const ipc = wasmTable.intoIPCStream();
+  const table = tableFromIPC(ipc);
+  return arrowToCube(table, options);
+}
+async function parquetToDataset(bytes, options) {
+  const { toDataset } = await import('../cubeBuilder-BEGA4C5Y.js');
+  return toDataset(await parquetToCube(bytes, options));
+}
+var COMPRESSION_CODEC_KEYS = [
+  "uncompressed",
+  "snappy",
+  "gzip",
+  "brotli",
+  "lz4",
+  "lz4_raw",
+  "zstd",
+  "lzo"
+];
+var COMPRESSION_CODEC_SET = new Set(COMPRESSION_CODEC_KEYS);
+function buildWriterProperties(wasm, codec) {
+  if (!codec) return void 0;
+  const key = codec.toLowerCase();
+  if (!COMPRESSION_CODEC_SET.has(key)) {
+    throw new ParquetSourceError(
+      `Unknown compression codec "${codec}". Valid (case-insensitive): ${[...COMPRESSION_CODEC_KEYS].join(", ")}.`
+    );
+  }
+  const Compression = wasm.Compression;
+  const WriterPropertiesBuilder = wasm.WriterPropertiesBuilder;
+  if (!Compression || !WriterPropertiesBuilder) {
+    throw new ParquetSourceError(
+      `Cannot apply compression "${codec}": this parquet-wasm build does not export WriterPropertiesBuilder/Compression. Omit the \`compression\` option to use the default codec.`
+    );
+  }
+  const enumKey = key.toUpperCase();
+  if (!(enumKey in Compression)) {
+    throw new ParquetSourceError(
+      `Compression codec "${codec}" is not available in this parquet-wasm build. Omit the \`compression\` option to use the default codec.`
+    );
+  }
+  return new WriterPropertiesBuilder().setCompression(Compression[enumKey]).build();
+}
+async function loadParquetWriter() {
+  try {
+    const mod = await import('parquet-wasm');
+    await ensureParquetWasmInit(mod);
+    if (mod.default && typeof mod.default.writeParquet === "function") return mod.default;
+    return mod;
+  } catch {
+    throw new ParquetSourceError(
+      "parquet-wasm is not installed. Install it with `npm i parquet-wasm` to write Parquet files."
+    );
+  }
+}
+async function arrowToParquet(table, options = {}) {
+  if (options.init) await options.init();
+  const wasm = await loadParquetWriter();
+  try {
+    const writerProps = buildWriterProperties(wasm, options.compression);
+    const ipc = tableToIPC(table, "stream");
+    const wasmTable = wasm.Table.fromIPCStream(ipc);
+    const bytes = wasm.writeParquet(wasmTable, writerProps);
+    if (bytes instanceof Uint8Array) return bytes;
+    return new Uint8Array(bytes);
+  } catch (e) {
+    throw new ParquetSourceError(`Failed to write Parquet: ${e?.message ?? e}`);
+  }
+}
+async function cubeToParquet(obs, options = {}) {
+  const table = cubeToArrow(obs);
+  return arrowToParquet(table, options);
+}
+
+export { ParquetSourceError, arrowToParquet, cubeToParquet, parquetToCube, parquetToDataset };
+//# sourceMappingURL=parquet.js.map
+//# sourceMappingURL=parquet.js.map

package/dist/sources/parquet.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/sources/parquet.ts"],"names":[],"mappings":"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","file":"parquet.js","sourcesContent":["/**\n * Parquet adapter — `jsonstat-io/parquet`.\n *\n * **Import:** reads a Parquet file (bytes) into an Arrow [`Table`] via\n * `parquet-wasm`, then funnels through the Arrow hub\n * ([`arrowToCube`](../arrow/arrowToCube.ts)).\n *\n * **Export:** [`cubeToParquet`] writes the [`Observations`] IR to a Parquet\n * file via `cubeToArrow` → `parquet-wasm` `writeParquet`.\n *\n * `parquet-wasm` is an **optional peer dependency** — it is imported lazily so\n * that consumers who never touch Parquet pay no bundle cost. If it is not\n * installed, calling [`parquetToCube`] / [`cubeToParquet`] throws a helpful\n * error.\n */\n\nimport type { Observations } from \"../model/ir\";\nimport type { JsonStatDataset } from \"../model/jsonstat\";\nimport { arrowToCube, type ArrowToCubeOptions } from \"../arrow/arrowToCube\";\nimport { cubeToArrow } from \"../arrow/arrowFromCube\";\nimport type { Table } from \"apache-arrow\";\nimport { tableToIPC, tableFromIPC } from \"apache-arrow\";\n\n// ---------------------------------------------------------------------------\n// Errors\n// ---------------------------------------------------------------------------\n\nexport class ParquetSourceError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = \"ParquetSourceError\";\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Options\n// ---------------------------------------------------------------------------\n\nexport interface ParquetToCubeOptions extends ArrowToCubeOptions {\n  /**\n   * Async initializer for parquet-wasm (e.g. to set the WASM base URL in the\n   * browser). If provided, it is awaited before reading. Defaults to a no-op.\n   */\n  init?: () => Promise<void>;\n}\n\n// ---------------------------------------------------------------------------\n// Internal: lazy parquet-wasm loader\n// ---------------------------------------------------------------------------\n\n/**\n * Dynamically import parquet-wasm and ensure its WASM binary is instantiated.\n * Kept in a function so the import is only evaluated when a Parquet read is\n * actually requested.\n *\n * parquet-wasm's ESM build exports the WASM initializer (`__wbg_init`) as the\n * module's **default** export. Calling it with no argument makes it fetch and\n * instantiate `parquet_wasm_bg.wasm` relative to the module URL. It is\n * idempotent (early-returns once `wasm` is set), so calling it again on a build\n * that already initialized — e.g. the Node/CJS build, which may auto-init — is\n * safe. Without this call, `readParquet`/`writeParquet` throw because the\n * wasm-bindgen internals (e.g. `__wbindgen_add_to_stack_pointer`) are not yet\n * wired up.\n */\nasync function ensureParquetWasmInit(mod: any): Promise<void> {\n  const initialize =\n    typeof mod.default === \"function\"\n      ? mod.default // ESM build: default export = __wbg_init\n      : typeof mod.init === \"function\"\n        ? mod.init // some bundles expose a named init()\n        : undefined;\n  if (initialize) await initialize();\n}\n\n/**\n * Dynamically import parquet-wasm, ensure the WASM binary is ready, and return\n * the object exposing `readParquet`.\n */\nasync function loadParquetWasm(): Promise<any> {\n  try {\n    const mod: any = await import(\"parquet-wasm\");\n    await ensureParquetWasmInit(mod);\n    // After init, the named exports (readParquet, Table, ...) are ready.\n    if (mod.default && typeof mod.default.readParquet === \"function\") return mod.default;\n    return mod;\n  } catch (e) {\n    throw new ParquetSourceError(\n      \"parquet-wasm is not installed. Install it with `npm i parquet-wasm` to read Parquet files.\",\n    );\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Public API\n// ---------------------------------------------------------------------------\n\n/**\n * Read a Parquet file (as `Uint8Array` / `ArrayBuffer`) into the\n * [`Observations`] IR.\n *\n * @throws [`ParquetSourceError`] if parquet-wasm is missing or the file is invalid.\n */\nexport async function parquetToCube(\n  bytes: Uint8Array | ArrayBuffer,\n  options: ParquetToCubeOptions = {},\n): Promise<Observations> {\n  if (options.init) await options.init();\n  const wasm = await loadParquetWasm();\n  let wasmTable: any;\n  try {\n    // parquet-wasm's readParquet returns its own Arrow Table (apache-arrow\n    // interop via IPC), not the caller's apache-arrow Table.\n    wasmTable = wasm.readParquet(bytes);\n  } catch (e: any) {\n    throw new ParquetSourceError(`Failed to read Parquet: ${e?.message ?? e}`);\n  }\n  if (!wasmTable) throw new ParquetSourceError(\"parquet-wasm returned no table\");\n\n  // Bridge the dual-Arrow hazard: serialize via IPC (a format both copies\n  // understand) and reconstruct with our apache-arrow `tableFromIPC`, exactly\n  // as documented in the parquet-wasm README:\n  //   const arrowTable = tableFromIPC(wasmTable.intoIPCStream());\n  const ipc = wasmTable.intoIPCStream();\n  const table = tableFromIPC(ipc);\n  return arrowToCube(table, options);\n}\n\n/** Convenience: Parquet bytes → JSON-stat [`Dataset`]. */\nexport async function parquetToDataset(\n  bytes: Uint8Array | ArrayBuffer,\n  options?: ParquetToCubeOptions,\n): Promise<JsonStatDataset> {\n  const { toDataset } = await import(\"../core/cubeBuilder\");\n  return toDataset(await parquetToCube(bytes, options));\n}\n\n// ---------------------------------------------------------------------------\n// Export: Observations IR → Parquet bytes\n// ---------------------------------------------------------------------------\n\nexport interface CubeToParquetOptions {\n  /**\n   * Async initializer for parquet-wasm (e.g. to set the WASM base URL in the\n   * browser). If provided, it is awaited before writing. Defaults to a no-op.\n   */\n  init?: () => Promise<void>;\n  /**\n   * Compression codec. Falls back to parquet-wasm's default (Snappy) when\n   * undefined. Friendly names (case-insensitive) accepted: `\"uncompressed\"`,\n   * `\"snappy\"`, `\"gzip\"`, `\"brotli\"`, `\"lz4\"`, `\"lz4_raw\"`, `\"zstd\"`, `\"lzo\"`.\n   * Codec availability depends on the parquet-wasm build flavor (e.g. Brotli\n   * may be absent in slim builds); an unavailable codec surfaces as a\n   * [`ParquetSourceError`].\n   */\n  compression?: string;\n}\n\n/**\n * Friendly codec name (lowercase) → parquet-wasm `Compression` enum key.\n *\n * The enum's *numeric* values are read off the loaded wasm module at runtime\n * (see [`buildWriterProperties`]) rather than hardcoded here, so the adapter\n * tracks upstream renumbering automatically. We only map names → enum keys.\n */\nconst COMPRESSION_CODEC_KEYS = [\n  \"uncompressed\",\n  \"snappy\",\n  \"gzip\",\n  \"brotli\",\n  \"lz4\",\n  \"lz4_raw\",\n  \"zstd\",\n  \"lzo\",\n] as const;\n\n/** Set of accepted codec names, for fast lowercase lookup + error messages. */\nconst COMPRESSION_CODEC_SET = new Set<string>(COMPRESSION_CODEC_KEYS);\n\n/**\n * Build a parquet-wasm `WriterProperties` for the requested codec, or return\n * `undefined` to let `writeParquet` use its default (Snappy).\n *\n * Reads the real `Compression` enum off the loaded wasm module — so we never\n * hardcode numeric values that could drift across parquet-wasm versions.\n *\n * @throws [`ParquetSourceError`] if the codec name is unknown, or if the wasm\n *   build does not export `WriterPropertiesBuilder` / `Compression` / the\n *   requested codec key.\n */\nfunction buildWriterProperties(wasm: any, codec: string | undefined): any {\n  if (!codec) return undefined;\n  const key = codec.toLowerCase();\n  if (!COMPRESSION_CODEC_SET.has(key)) {\n    throw new ParquetSourceError(\n      `Unknown compression codec \"${codec}\". ` +\n        `Valid (case-insensitive): ${[...COMPRESSION_CODEC_KEYS].join(\", \")}.`,\n    );\n  }\n  const Compression: any = wasm.Compression;\n  const WriterPropertiesBuilder: any = wasm.WriterPropertiesBuilder;\n  if (!Compression || !WriterPropertiesBuilder) {\n    throw new ParquetSourceError(\n      `Cannot apply compression \"${codec}\": this parquet-wasm build does not ` +\n        \"export WriterPropertiesBuilder/Compression. \" +\n        \"Omit the `compression` option to use the default codec.\",\n    );\n  }\n  const enumKey = key.toUpperCase();\n  if (!(enumKey in Compression)) {\n    throw new ParquetSourceError(\n      `Compression codec \"${codec}\" is not available in this parquet-wasm ` +\n        \"build. Omit the `compression` option to use the default codec.\",\n    );\n  }\n  return new WriterPropertiesBuilder().setCompression(Compression[enumKey]).build();\n}\n\n/**\n * Resolve the parquet-wasm `writeParquet` entrypoint. Mirrors\n * [`loadParquetWasm`], but documented separately because the two bindings can\n * diverge across parquet-wasm versions.\n */\nasync function loadParquetWriter(): Promise<any> {\n  try {\n    const mod: any = await import(\"parquet-wasm\");\n    await ensureParquetWasmInit(mod);\n    if (mod.default && typeof mod.default.writeParquet === \"function\") return mod.default;\n    return mod;\n  } catch {\n    throw new ParquetSourceError(\n      \"parquet-wasm is not installed. Install it with `npm i parquet-wasm` to write Parquet files.\",\n    );\n  }\n}\n\n/**\n * Serialize an Arrow [`Table`] to Parquet bytes using `parquet-wasm`. Extracted\n * so [`cubeToParquet`] and the round-trip tests share one path.\n *\n * @internal\n */\nexport async function arrowToParquet(\n  table: Table,\n  options: CubeToParquetOptions = {},\n): Promise<Uint8Array> {\n  if (options.init) await options.init();\n  const wasm = await loadParquetWriter();\n  try {\n    // Resolve the codec to a real parquet-wasm WriterProperties instance.\n    // parquet-wasm@0.6.x's writeParquet expects a WriterProperties built via\n    // WriterPropertiesBuilder (NOT a plain {compression} options bag); passing\n    // a plain object throws \"expected instance of WriterProperties\". When\n    // `compression` is omitted we pass `undefined` so writeParquet falls back\n    // to its own default (Snappy). See .idea/jsonstat-io-parquet-compression-plan.md.\n    const writerProps = buildWriterProperties(wasm, options.compression);\n\n    // Bridge the dual-Arrow hazard: parquet-wasm bundles its own copy of\n    // apache-arrow, so an `instanceof` check against its internal `Table` fails\n    // for our caller's `Table`. We serialize via IPC (a format both copies\n    // understand) and reconstruct inside parquet-wasm's `Table`, exactly as\n    // documented in the parquet-wasm README:\n    //   Table.fromIPCStream(tableToIPC(table, \"stream\"))\n    const ipc = tableToIPC(table, \"stream\");\n    const wasmTable = wasm.Table.fromIPCStream(ipc);\n    const bytes = wasm.writeParquet(wasmTable, writerProps);\n\n    // parquet-wasm returns a Uint8Array (node) or a WebAssembly.Memory-backed\n    // view; normalize to Uint8Array in both runtimes.\n    if (bytes instanceof Uint8Array) return bytes;\n    return new Uint8Array(bytes);\n  } catch (e: any) {\n    throw new ParquetSourceError(`Failed to write Parquet: ${e?.message ?? e}`);\n  }\n}\n\n/**\n * Write the [`Observations`](../model/ir.ts) IR to a Parquet file (bytes).\n *\n * The IR is first converted to an Arrow [`Table`] via [`cubeToArrow`], then\n * serialized to Parquet via `parquet-wasm`'s `writeParquet`. All `jsonstat.*`\n * schema/field metadata is preserved, so the result round-trips through\n * [`parquetToCube`].\n *\n * @returns A `Uint8Array` of the Parquet file.\n * @throws [`ParquetSourceError`] if parquet-wasm is missing or the write fails.\n *\n * @example\n * ```ts\n * import { cubeToParquet } from \"jsonstat-io/parquet\";\n * const bytes = await cubeToParquet(observations);\n * ```\n */\nexport async function cubeToParquet(\n  obs: Observations,\n  options: CubeToParquetOptions = {},\n): Promise<Uint8Array> {\n  const table = cubeToArrow(obs);\n  return arrowToParquet(table, options);\n}\n"]}

package/dist/sources/polars.cjs

@@ -0,0 +1,94 @@
+'use strict';
+
+var chunkPHLCWTHB_cjs = require('../chunk-PHLCWTHB.cjs');
+
+// src/sources/polars.ts
+var PolarsSourceError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "PolarsSourceError";
+  }
+};
+async function polarsToArrow(df, method) {
+  const tried = [];
+  const tryMethod = async (name) => {
+    if (typeof df[name] !== "function") {
+      tried.push(name);
+      return void 0;
+    }
+    const result = await df[name]();
+    return result;
+  };
+  if (method === "toArrow" || method === "auto" || method === void 0) {
+    const t = await tryMethod("toArrow");
+    if (t) return t;
+  }
+  if (method === "toIPC" || method === "auto" || method === void 0) {
+    const ipc = await tryMethod("toIPC");
+    if (ipc) {
+      const { tableFromIPC } = await import('apache-arrow');
+      return tableFromIPC(ipc);
+    }
+  }
+  throw new PolarsSourceError(
+    `Could not obtain an Arrow Table from the Polars DataFrame (tried: ${tried.join(", ")}). Ensure nodejs-polars is installed and the DataFrame supports toArrow()/toIPC().`
+  );
+}
+async function polarsToCube(df, options = {}) {
+  const table = await polarsToArrow(df, options.arrowMethod ?? "auto");
+  if (!table) throw new PolarsSourceError("Polars DataFrame yielded no Arrow table");
+  return chunkPHLCWTHB_cjs.arrowToCube(table, options);
+}
+async function polarsToDataset(df, options) {
+  const { toDataset } = await import('../cubeBuilder-ZU76VVEX.cjs');
+  return toDataset(await polarsToCube(df, options));
+}
+async function loadPolars() {
+  try {
+    return await import('nodejs-polars');
+  } catch {
+    throw new PolarsSourceError(
+      "nodejs-polars is not installed. Install it with `npm i nodejs-polars` (Node only)."
+    );
+  }
+}
+async function arrowToPolars(table, method = "auto") {
+  const pl = await loadPolars();
+  const tried = [];
+  if (method === "fromArrow" || method === "auto") {
+    tried.push("pl.fromArrow");
+    if (typeof pl.fromArrow === "function") {
+      try {
+        return pl.fromArrow(table);
+      } catch {
+      }
+    }
+  }
+  if (method === "ipc" || method === "auto") {
+    tried.push("pl.readIPC");
+    const { tableToIPC } = await import('apache-arrow');
+    const buf = tableToIPC(table, "stream");
+    if (typeof pl.readIPC === "function") {
+      try {
+        return pl.readIPC(buf);
+      } catch {
+      }
+    }
+  }
+  throw new PolarsSourceError(
+    `Could not build a Polars DataFrame from the Arrow Table (tried: ${tried.join(", ")}). Ensure nodejs-polars is installed and supports fromArrow()/readIPC().`
+  );
+}
+async function cubeToPolars(obs, options = {}) {
+  const table = chunkPHLCWTHB_cjs.cubeToArrow(obs);
+  return arrowToPolars(table, options.method);
+}
+
+exports.PolarsSourceError = PolarsSourceError;
+exports.arrowToPolars = arrowToPolars;
+exports.cubeToPolars = cubeToPolars;
+exports.loadPolars = loadPolars;
+exports.polarsToCube = polarsToCube;
+exports.polarsToDataset = polarsToDataset;
+//# sourceMappingURL=polars.cjs.map
+//# sourceMappingURL=polars.cjs.map

package/dist/sources/polars.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/sources/polars.ts"],"names":["arrowToCube","cubeToArrow"],"mappings":";;;;;AA6BO,IAAM,iBAAA,GAAN,cAAgC,KAAA,CAAM;AAAA,EAC3C,YAAY,OAAA,EAAiB;AAC3B,IAAA,KAAA,CAAM,OAAO,CAAA;AACb,IAAA,IAAA,CAAK,IAAA,GAAO,mBAAA;AAAA,EACd;AACF;AAwBA,eAAe,aAAA,CAAc,IAAS,MAAA,EAA0D;AAC9F,EAAA,MAAM,QAAkB,EAAC;AACzB,EAAA,MAAM,SAAA,GAAY,OAAO,IAAA,KAA+B;AACtD,IAAA,IAAI,OAAO,EAAA,CAAG,IAAI,CAAA,KAAM,UAAA,EAAY;AAClC,MAAA,KAAA,CAAM,KAAK,IAAI,CAAA;AACf,MAAA,OAAO,MAAA;AAAA,IACT;AACA,IAAA,MAAM,MAAA,GAAS,MAAM,EAAA,CAAG,IAAI,CAAA,EAAE;AAC9B,IAAA,OAAO,MAAA;AAAA,EACT,CAAA;AAEA,EAAA,IAAI,MAAA,KAAW,SAAA,IAAa,MAAA,KAAW,MAAA,IAAU,WAAW,MAAA,EAAW;AACrE,IAAA,MAAM,CAAA,GAAI,MAAM,SAAA,CAAU,SAAS,CAAA;AACnC,IAAA,IAAI,GAAG,OAAO,CAAA;AAAA,EAChB;AACA,EAAA,IAAI,MAAA,KAAW,OAAA,IAAW,MAAA,KAAW,MAAA,IAAU,WAAW,MAAA,EAAW;AACnE,IAAA,MAAM,GAAA,GAAM,MAAM,SAAA,CAAU,OAAO,CAAA;AACnC,IAAA,IAAI,GAAA,EAAK;AAEP,MAAA,MAAM,EAAE,YAAA,EAAa,GAAI,MAAM,OAAO,cAAc,CAAA;AACpD,MAAA,OAAO,aAAa,GAAG,CAAA;AAAA,IACzB;AAAA,EACF;AAEA,EAAA,MAAM,IAAI,iBAAA;AAAA,IACR,CAAA,kEAAA,EAAqE,KAAA,CAAM,IAAA,CAAK,IAAI,CAAC,CAAA,kFAAA;AAAA,GAEvF;AACF;AAaA,eAAsB,YAAA,CACpB,EAAA,EACA,OAAA,GAA+B,EAAC,EACT;AACvB,EAAA,MAAM,QAAQ,MAAM,aAAA,CAAc,EAAA,EAAI,OAAA,CAAQ,eAAe,MAAM,CAAA;AACnE,EAAA,IAAI,CAAC,KAAA,EAAO,MAAM,IAAI,kBAAkB,yCAAyC,CAAA;AACjF,EAAA,OAAOA,6BAAA,CAAY,OAAO,OAAO,CAAA;AACnC;AAGA,eAAsB,eAAA,CACpB,IACA,OAAA,EAC0B;AAC1B,EAAA,MAAM,EAAE,SAAA,EAAU,GAAI,MAAM,OAAO,6BAAqB,CAAA;AACxD,EAAA,OAAO,SAAA,CAAU,MAAM,YAAA,CAAa,EAAA,EAAI,OAAO,CAAC,CAAA;AAClD;AAMA,eAAsB,UAAA,GAA2B;AAC/C,EAAA,IAAI;AACF,IAAA,OAAO,MAAM,OAAO,eAAe,CAAA;AAAA,EACrC,CAAA,CAAA,MAAQ;AACN,IAAA,MAAM,IAAI,iBAAA;AAAA,MACR;AAAA,KACF;AAAA,EACF;AACF;AAuBA,eAAsB,aAAA,CACpB,KAAA,EACA,MAAA,GAAwC,MAAA,EAC1B;AACd,EAAA,MAAM,EAAA,GAAK,MAAM,UAAA,EAAW;AAC5B,EAAA,MAAM,QAAkB,EAAC;AAEzB,EAAA,IAAI,MAAA,KAAW,WAAA,IAAe,MAAA,KAAW,MAAA,EAAQ;AAC/C,IAAA,KAAA,CAAM,KAAK,cAAc,CAAA;AACzB,IAAA,IAAI,OAAO,EAAA,CAAG,SAAA,KAAc,UAAA,EAAY;AACtC,MAAA,IAAI;AACF,QAAA,OAAO,EAAA,CAAG,UAAU,KAAK,CAAA;AAAA,MAC3B,CAAA,CAAA,MAAQ;AAAA,MAER;AAAA,IACF;AAAA,EACF;AAEA,EAAA,IAAI,MAAA,KAAW,KAAA,IAAS,MAAA,KAAW,MAAA,EAAQ;AACzC,IAAA,KAAA,CAAM,KAAK,YAAY,CAAA;AAEvB,IAAA,MAAM,EAAE,UAAA,EAAW,GAAI,MAAM,OAAO,cAAc,CAAA;AAClD,IAAA,MAAM,GAAA,GAAM,UAAA,CAAW,KAAA,EAAO,QAAQ,CAAA;AACtC,IAAA,IAAI,OAAO,EAAA,CAAG,OAAA,KAAY,UAAA,EAAY;AACpC,MAAA,IAAI;AACF,QAAA,OAAO,EAAA,CAAG,QAAQ,GAAG,CAAA;AAAA,MACvB,CAAA,CAAA,MAAQ;AAAA,MAER;AAAA,IACF;AAAA,EACF;AAEA,EAAA,MAAM,IAAI,iBAAA;AAAA,IACR,CAAA,gEAAA,EAAmE,KAAA,CAAM,IAAA,CAAK,IAAI,CAAC,CAAA,wEAAA;AAAA,GAErF;AACF;AAuBA,eAAsB,YAAA,CACpB,GAAA,EACA,OAAA,GAA+B,EAAC,EAClB;AACd,EAAA,MAAM,KAAA,GAAQC,8BAAY,GAAG,CAAA;AAC7B,EAAA,OAAO,aAAA,CAAc,KAAA,EAAO,OAAA,CAAQ,MAAM,CAAA;AAC5C","file":"polars.cjs","sourcesContent":["/**\n * Polars adapter — `jsonstat-io/polars`.\n *\n * **Import:** accepts a Polars `DataFrame` (from `nodejs-polars`) and funnels\n * its Arrow representation through the Arrow hub\n * ([`arrowToCube`](../arrow/arrowToCube.ts)).\n *\n * **Export:** [`cubeToPolars`] builds an Arrow [`Table`] from the\n * [`Observations`] IR and converts it back to a Polars `DataFrame`.\n *\n * ## Node-only\n *\n * `nodejs-polars` is a native Node module — it cannot run in the browser. For\n * browser Polars data, convert to Arrow IPC first and use\n * `jsonstat-io/arrow` directly. This adapter is therefore documented as\n * **Node-only**; importing it in a browser bundle will fail at runtime (the\n * `nodejs-polars` import is lazy, so the failure only happens on use).\n */\n\nimport type { Observations } from \"../model/ir\";\nimport type { JsonStatDataset } from \"../model/jsonstat\";\nimport { arrowToCube, type ArrowToCubeOptions } from \"../arrow/arrowToCube\";\nimport { cubeToArrow } from \"../arrow/arrowFromCube\";\nimport type { Table } from \"apache-arrow\";\n\n// ---------------------------------------------------------------------------\n// Errors\n// ---------------------------------------------------------------------------\n\nexport class PolarsSourceError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = \"PolarsSourceError\";\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Options\n// ---------------------------------------------------------------------------\n\nexport interface PolarsToCubeOptions extends ArrowToCubeOptions {\n  /**\n   * Polars frames expose different Arrow conversion methods across versions\n   * (`toArrow()`, `toRecords()`, etc.). The adapter tries them in order; this\n   * option forces a specific one. Usually unnecessary.\n   */\n  arrowMethod?: \"toArrow\" | \"toIPC\" | \"auto\";\n}\n\n// ---------------------------------------------------------------------------\n// Internal: lazy nodejs-polars-free Arrow extraction\n// ---------------------------------------------------------------------------\n\n/**\n * Extract an Arrow Table from a Polars DataFrame. Tries the common conversion\n * methods. We do NOT statically import `nodejs-polars` — the caller passes a\n * DataFrame object, keeping this module free of a hard dependency.\n */\nasync function polarsToArrow(df: any, method: PolarsToCubeOptions[\"arrowMethod\"]): Promise<any> {\n  const tried: string[] = [];\n  const tryMethod = async (name: string): Promise<any> => {\n    if (typeof df[name] !== \"function\") {\n      tried.push(name);\n      return undefined;\n    }\n    const result = await df[name]();\n    return result;\n  };\n\n  if (method === \"toArrow\" || method === \"auto\" || method === undefined) {\n    const t = await tryMethod(\"toArrow\");\n    if (t) return t;\n  }\n  if (method === \"toIPC\" || method === \"auto\" || method === undefined) {\n    const ipc = await tryMethod(\"toIPC\");\n    if (ipc) {\n      // IPC bytes → Arrow Table via apache-arrow's readIPC (lazy import).\n      const { tableFromIPC } = await import(\"apache-arrow\");\n      return tableFromIPC(ipc);\n    }\n  }\n\n  throw new PolarsSourceError(\n    `Could not obtain an Arrow Table from the Polars DataFrame (tried: ${tried.join(\", \")}). ` +\n      \"Ensure nodejs-polars is installed and the DataFrame supports toArrow()/toIPC().\",\n  );\n}\n\n// ---------------------------------------------------------------------------\n// Public API\n// ---------------------------------------------------------------------------\n\n/**\n * Convert a Polars `DataFrame` to the [`Observations`] IR via the Arrow hub.\n *\n * @param df A Polars DataFrame (`nodejs-polars`). Not statically typed to avoid\n *        a hard dependency; pass any object exposing `toArrow()`/`toIPC()`.\n * @throws [`PolarsSourceError`] if Arrow extraction fails.\n */\nexport async function polarsToCube(\n  df: any,\n  options: PolarsToCubeOptions = {},\n): Promise<Observations> {\n  const table = await polarsToArrow(df, options.arrowMethod ?? \"auto\");\n  if (!table) throw new PolarsSourceError(\"Polars DataFrame yielded no Arrow table\");\n  return arrowToCube(table, options);\n}\n\n/** Convenience: Polars DataFrame → JSON-stat [`Dataset`]. */\nexport async function polarsToDataset(\n  df: any,\n  options?: PolarsToCubeOptions,\n): Promise<JsonStatDataset> {\n  const { toDataset } = await import(\"../core/cubeBuilder\");\n  return toDataset(await polarsToCube(df, options));\n}\n\n/**\n * Lazily load `nodejs-polars`. Exposed so callers can `readCSV`/`readParquet`\n * via Polars without a direct import in their own code.\n */\nexport async function loadPolars(): Promise<any> {\n  try {\n    return await import(\"nodejs-polars\");\n  } catch {\n    throw new PolarsSourceError(\n      \"nodejs-polars is not installed. Install it with `npm i nodejs-polars` (Node only).\",\n    );\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Export: Observations IR → Polars DataFrame\n// ---------------------------------------------------------------------------\n\nexport interface CubeToPolarsOptions {\n  /**\n   * Conversion path from Arrow to Polars. `\"fromArrow\"` (default) uses\n   * `pl.fromArrow(table)`; `\"ipc\"` serializes the table to Arrow IPC and reads\n   * it via `pl.readIPC(buf)`. Usually unnecessary; `\"auto\"` tries `\"fromArrow\"`\n   * first, then `\"ipc\"`.\n   */\n  method?: \"fromArrow\" | \"ipc\" | \"auto\";\n}\n\n/**\n * Convert an Arrow [`Table`] to a Polars `DataFrame`. Tries the common\n * nodejs-polars constructors in order. Extracted so [`cubeToPolars`] and the\n * round-trip tests share one path.\n *\n * @internal\n */\nexport async function arrowToPolars(\n  table: Table,\n  method: CubeToPolarsOptions[\"method\"] = \"auto\",\n): Promise<any> {\n  const pl = await loadPolars();\n  const tried: string[] = [];\n\n  if (method === \"fromArrow\" || method === \"auto\") {\n    tried.push(\"pl.fromArrow\");\n    if (typeof pl.fromArrow === \"function\") {\n      try {\n        return pl.fromArrow(table);\n      } catch {\n        // fall through to ipc\n      }\n    }\n  }\n\n  if (method === \"ipc\" || method === \"auto\") {\n    tried.push(\"pl.readIPC\");\n    // Serialize the Arrow Table to IPC stream bytes, then read via Polars.\n    const { tableToIPC } = await import(\"apache-arrow\");\n    const buf = tableToIPC(table, \"stream\");\n    if (typeof pl.readIPC === \"function\") {\n      try {\n        return pl.readIPC(buf);\n      } catch {\n        // fall through\n      }\n    }\n  }\n\n  throw new PolarsSourceError(\n    `Could not build a Polars DataFrame from the Arrow Table (tried: ${tried.join(\", \")}). ` +\n      \"Ensure nodejs-polars is installed and supports fromArrow()/readIPC().\",\n  );\n}\n\n/**\n * Write the [`Observations`](../model/ir.ts) IR to a Polars `DataFrame`.\n *\n * The IR is first converted to an Arrow [`Table`] via [`cubeToArrow`], then\n * handed to `nodejs-polars` (`pl.fromArrow`). All `jsonstat.*` schema/field\n * metadata travels on the Arrow schema; Polars preserves it through the Arrow\n * IPC pathway, so a subsequent `df.toArrow()` → [`arrowToCube`] round-trips.\n *\n * Node-only: this function dynamically imports `nodejs-polars` and will throw\n * [`PolarsSourceError`] in the browser.\n *\n * @returns A Polars `DataFrame` (`nodejs-polars`).\n * @throws [`PolarsSourceError`] if nodejs-polars is missing or the conversion fails.\n *\n * @example\n * ```ts\n * import { cubeToPolars } from \"jsonstat-io/polars\";\n * const df = await cubeToPolars(observations);\n * console.log(df.shape);\n * ```\n */\nexport async function cubeToPolars(\n  obs: Observations,\n  options: CubeToPolarsOptions = {},\n): Promise<any> {\n  const table = cubeToArrow(obs);\n  return arrowToPolars(table, options.method);\n}\n"]}

package/dist/sources/polars.d.cts

@@ -0,0 +1,91 @@
+import { O as Observations } from '../ir-BArfNxo-.cjs';
+import { J as JsonStatDataset } from '../jsonstat-BX4mBLci.cjs';
+import { A as ArrowToCubeOptions } from '../arrowToCube-BdRWZ5oG.cjs';
+import { Table } from 'apache-arrow';
+
+/**
+ * Polars adapter — `jsonstat-io/polars`.
+ *
+ * **Import:** accepts a Polars `DataFrame` (from `nodejs-polars`) and funnels
+ * its Arrow representation through the Arrow hub
+ * ([`arrowToCube`](../arrow/arrowToCube.ts)).
+ *
+ * **Export:** [`cubeToPolars`] builds an Arrow [`Table`] from the
+ * [`Observations`] IR and converts it back to a Polars `DataFrame`.
+ *
+ * ## Node-only
+ *
+ * `nodejs-polars` is a native Node module — it cannot run in the browser. For
+ * browser Polars data, convert to Arrow IPC first and use
+ * `jsonstat-io/arrow` directly. This adapter is therefore documented as
+ * **Node-only**; importing it in a browser bundle will fail at runtime (the
+ * `nodejs-polars` import is lazy, so the failure only happens on use).
+ */
+
+declare class PolarsSourceError extends Error {
+    constructor(message: string);
+}
+interface PolarsToCubeOptions extends ArrowToCubeOptions {
+    /**
+     * Polars frames expose different Arrow conversion methods across versions
+     * (`toArrow()`, `toRecords()`, etc.). The adapter tries them in order; this
+     * option forces a specific one. Usually unnecessary.
+     */
+    arrowMethod?: "toArrow" | "toIPC" | "auto";
+}
+/**
+ * Convert a Polars `DataFrame` to the [`Observations`] IR via the Arrow hub.
+ *
+ * @param df A Polars DataFrame (`nodejs-polars`). Not statically typed to avoid
+ *        a hard dependency; pass any object exposing `toArrow()`/`toIPC()`.
+ * @throws [`PolarsSourceError`] if Arrow extraction fails.
+ */
+declare function polarsToCube(df: any, options?: PolarsToCubeOptions): Promise<Observations>;
+/** Convenience: Polars DataFrame → JSON-stat [`Dataset`]. */
+declare function polarsToDataset(df: any, options?: PolarsToCubeOptions): Promise<JsonStatDataset>;
+/**
+ * Lazily load `nodejs-polars`. Exposed so callers can `readCSV`/`readParquet`
+ * via Polars without a direct import in their own code.
+ */
+declare function loadPolars(): Promise<any>;
+interface CubeToPolarsOptions {
+    /**
+     * Conversion path from Arrow to Polars. `"fromArrow"` (default) uses
+     * `pl.fromArrow(table)`; `"ipc"` serializes the table to Arrow IPC and reads
+     * it via `pl.readIPC(buf)`. Usually unnecessary; `"auto"` tries `"fromArrow"`
+     * first, then `"ipc"`.
+     */
+    method?: "fromArrow" | "ipc" | "auto";
+}
+/**
+ * Convert an Arrow [`Table`] to a Polars `DataFrame`. Tries the common
+ * nodejs-polars constructors in order. Extracted so [`cubeToPolars`] and the
+ * round-trip tests share one path.
+ *
+ * @internal
+ */
+declare function arrowToPolars(table: Table, method?: CubeToPolarsOptions["method"]): Promise<any>;
+/**
+ * Write the [`Observations`](../model/ir.ts) IR to a Polars `DataFrame`.
+ *
+ * The IR is first converted to an Arrow [`Table`] via [`cubeToArrow`], then
+ * handed to `nodejs-polars` (`pl.fromArrow`). All `jsonstat.*` schema/field
+ * metadata travels on the Arrow schema; Polars preserves it through the Arrow
+ * IPC pathway, so a subsequent `df.toArrow()` → [`arrowToCube`] round-trips.
+ *
+ * Node-only: this function dynamically imports `nodejs-polars` and will throw
+ * [`PolarsSourceError`] in the browser.
+ *
+ * @returns A Polars `DataFrame` (`nodejs-polars`).
+ * @throws [`PolarsSourceError`] if nodejs-polars is missing or the conversion fails.
+ *
+ * @example
+ * ```ts
+ * import { cubeToPolars } from "jsonstat-io/polars";
+ * const df = await cubeToPolars(observations);
+ * console.log(df.shape);
+ * ```
+ */
+declare function cubeToPolars(obs: Observations, options?: CubeToPolarsOptions): Promise<any>;
+
+export { type CubeToPolarsOptions, PolarsSourceError, type PolarsToCubeOptions, arrowToPolars, cubeToPolars, loadPolars, polarsToCube, polarsToDataset };

package/dist/sources/polars.d.ts

@@ -0,0 +1,91 @@
+import { O as Observations } from '../ir-Jae2ymov.js';
+import { J as JsonStatDataset } from '../jsonstat-BX4mBLci.js';
+import { A as ArrowToCubeOptions } from '../arrowToCube-Mjr79ZHM.js';
+import { Table } from 'apache-arrow';
+
+/**
+ * Polars adapter — `jsonstat-io/polars`.
+ *
+ * **Import:** accepts a Polars `DataFrame` (from `nodejs-polars`) and funnels
+ * its Arrow representation through the Arrow hub
+ * ([`arrowToCube`](../arrow/arrowToCube.ts)).
+ *
+ * **Export:** [`cubeToPolars`] builds an Arrow [`Table`] from the
+ * [`Observations`] IR and converts it back to a Polars `DataFrame`.
+ *
+ * ## Node-only
+ *
+ * `nodejs-polars` is a native Node module — it cannot run in the browser. For
+ * browser Polars data, convert to Arrow IPC first and use
+ * `jsonstat-io/arrow` directly. This adapter is therefore documented as
+ * **Node-only**; importing it in a browser bundle will fail at runtime (the
+ * `nodejs-polars` import is lazy, so the failure only happens on use).
+ */
+
+declare class PolarsSourceError extends Error {
+    constructor(message: string);
+}
+interface PolarsToCubeOptions extends ArrowToCubeOptions {
+    /**
+     * Polars frames expose different Arrow conversion methods across versions
+     * (`toArrow()`, `toRecords()`, etc.). The adapter tries them in order; this
+     * option forces a specific one. Usually unnecessary.
+     */
+    arrowMethod?: "toArrow" | "toIPC" | "auto";
+}
+/**
+ * Convert a Polars `DataFrame` to the [`Observations`] IR via the Arrow hub.
+ *
+ * @param df A Polars DataFrame (`nodejs-polars`). Not statically typed to avoid
+ *        a hard dependency; pass any object exposing `toArrow()`/`toIPC()`.
+ * @throws [`PolarsSourceError`] if Arrow extraction fails.
+ */
+declare function polarsToCube(df: any, options?: PolarsToCubeOptions): Promise<Observations>;
+/** Convenience: Polars DataFrame → JSON-stat [`Dataset`]. */
+declare function polarsToDataset(df: any, options?: PolarsToCubeOptions): Promise<JsonStatDataset>;
+/**
+ * Lazily load `nodejs-polars`. Exposed so callers can `readCSV`/`readParquet`
+ * via Polars without a direct import in their own code.
+ */
+declare function loadPolars(): Promise<any>;
+interface CubeToPolarsOptions {
+    /**
+     * Conversion path from Arrow to Polars. `"fromArrow"` (default) uses
+     * `pl.fromArrow(table)`; `"ipc"` serializes the table to Arrow IPC and reads
+     * it via `pl.readIPC(buf)`. Usually unnecessary; `"auto"` tries `"fromArrow"`
+     * first, then `"ipc"`.
+     */
+    method?: "fromArrow" | "ipc" | "auto";
+}
+/**
+ * Convert an Arrow [`Table`] to a Polars `DataFrame`. Tries the common
+ * nodejs-polars constructors in order. Extracted so [`cubeToPolars`] and the
+ * round-trip tests share one path.
+ *
+ * @internal
+ */
+declare function arrowToPolars(table: Table, method?: CubeToPolarsOptions["method"]): Promise<any>;
+/**
+ * Write the [`Observations`](../model/ir.ts) IR to a Polars `DataFrame`.
+ *
+ * The IR is first converted to an Arrow [`Table`] via [`cubeToArrow`], then
+ * handed to `nodejs-polars` (`pl.fromArrow`). All `jsonstat.*` schema/field
+ * metadata travels on the Arrow schema; Polars preserves it through the Arrow
+ * IPC pathway, so a subsequent `df.toArrow()` → [`arrowToCube`] round-trips.
+ *
+ * Node-only: this function dynamically imports `nodejs-polars` and will throw
+ * [`PolarsSourceError`] in the browser.
+ *
+ * @returns A Polars `DataFrame` (`nodejs-polars`).
+ * @throws [`PolarsSourceError`] if nodejs-polars is missing or the conversion fails.
+ *
+ * @example
+ * ```ts
+ * import { cubeToPolars } from "jsonstat-io/polars";
+ * const df = await cubeToPolars(observations);
+ * console.log(df.shape);
+ * ```
+ */
+declare function cubeToPolars(obs: Observations, options?: CubeToPolarsOptions): Promise<any>;
+
+export { type CubeToPolarsOptions, PolarsSourceError, type PolarsToCubeOptions, arrowToPolars, cubeToPolars, loadPolars, polarsToCube, polarsToDataset };

package/dist/sources/polars.js

@@ -0,0 +1,87 @@
+import { arrowToCube, cubeToArrow } from '../chunk-IDTQZG4B.js';
+
+// src/sources/polars.ts
+var PolarsSourceError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "PolarsSourceError";
+  }
+};
+async function polarsToArrow(df, method) {
+  const tried = [];
+  const tryMethod = async (name) => {
+    if (typeof df[name] !== "function") {
+      tried.push(name);
+      return void 0;
+    }
+    const result = await df[name]();
+    return result;
+  };
+  if (method === "toArrow" || method === "auto" || method === void 0) {
+    const t = await tryMethod("toArrow");
+    if (t) return t;
+  }
+  if (method === "toIPC" || method === "auto" || method === void 0) {
+    const ipc = await tryMethod("toIPC");
+    if (ipc) {
+      const { tableFromIPC } = await import('apache-arrow');
+      return tableFromIPC(ipc);
+    }
+  }
+  throw new PolarsSourceError(
+    `Could not obtain an Arrow Table from the Polars DataFrame (tried: ${tried.join(", ")}). Ensure nodejs-polars is installed and the DataFrame supports toArrow()/toIPC().`
+  );
+}
+async function polarsToCube(df, options = {}) {
+  const table = await polarsToArrow(df, options.arrowMethod ?? "auto");
+  if (!table) throw new PolarsSourceError("Polars DataFrame yielded no Arrow table");
+  return arrowToCube(table, options);
+}
+async function polarsToDataset(df, options) {
+  const { toDataset } = await import('../cubeBuilder-BEGA4C5Y.js');
+  return toDataset(await polarsToCube(df, options));
+}
+async function loadPolars() {
+  try {
+    return await import('nodejs-polars');
+  } catch {
+    throw new PolarsSourceError(
+      "nodejs-polars is not installed. Install it with `npm i nodejs-polars` (Node only)."
+    );
+  }
+}
+async function arrowToPolars(table, method = "auto") {
+  const pl = await loadPolars();
+  const tried = [];
+  if (method === "fromArrow" || method === "auto") {
+    tried.push("pl.fromArrow");
+    if (typeof pl.fromArrow === "function") {
+      try {
+        return pl.fromArrow(table);
+      } catch {
+      }
+    }
+  }
+  if (method === "ipc" || method === "auto") {
+    tried.push("pl.readIPC");
+    const { tableToIPC } = await import('apache-arrow');
+    const buf = tableToIPC(table, "stream");
+    if (typeof pl.readIPC === "function") {
+      try {
+        return pl.readIPC(buf);
+      } catch {
+      }
+    }
+  }
+  throw new PolarsSourceError(
+    `Could not build a Polars DataFrame from the Arrow Table (tried: ${tried.join(", ")}). Ensure nodejs-polars is installed and supports fromArrow()/readIPC().`
+  );
+}
+async function cubeToPolars(obs, options = {}) {
+  const table = cubeToArrow(obs);
+  return arrowToPolars(table, options.method);
+}
+
+export { PolarsSourceError, arrowToPolars, cubeToPolars, loadPolars, polarsToCube, polarsToDataset };
+//# sourceMappingURL=polars.js.map
+//# sourceMappingURL=polars.js.map

package/dist/sources/polars.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/sources/polars.ts"],"names":[],"mappings":"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","file":"polars.js","sourcesContent":["/**\n * Polars adapter — `jsonstat-io/polars`.\n *\n * **Import:** accepts a Polars `DataFrame` (from `nodejs-polars`) and funnels\n * its Arrow representation through the Arrow hub\n * ([`arrowToCube`](../arrow/arrowToCube.ts)).\n *\n * **Export:** [`cubeToPolars`] builds an Arrow [`Table`] from the\n * [`Observations`] IR and converts it back to a Polars `DataFrame`.\n *\n * ## Node-only\n *\n * `nodejs-polars` is a native Node module — it cannot run in the browser. For\n * browser Polars data, convert to Arrow IPC first and use\n * `jsonstat-io/arrow` directly. This adapter is therefore documented as\n * **Node-only**; importing it in a browser bundle will fail at runtime (the\n * `nodejs-polars` import is lazy, so the failure only happens on use).\n */\n\nimport type { Observations } from \"../model/ir\";\nimport type { JsonStatDataset } from \"../model/jsonstat\";\nimport { arrowToCube, type ArrowToCubeOptions } from \"../arrow/arrowToCube\";\nimport { cubeToArrow } from \"../arrow/arrowFromCube\";\nimport type { Table } from \"apache-arrow\";\n\n// ---------------------------------------------------------------------------\n// Errors\n// ---------------------------------------------------------------------------\n\nexport class PolarsSourceError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = \"PolarsSourceError\";\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Options\n// ---------------------------------------------------------------------------\n\nexport interface PolarsToCubeOptions extends ArrowToCubeOptions {\n  /**\n   * Polars frames expose different Arrow conversion methods across versions\n   * (`toArrow()`, `toRecords()`, etc.). The adapter tries them in order; this\n   * option forces a specific one. Usually unnecessary.\n   */\n  arrowMethod?: \"toArrow\" | \"toIPC\" | \"auto\";\n}\n\n// ---------------------------------------------------------------------------\n// Internal: lazy nodejs-polars-free Arrow extraction\n// ---------------------------------------------------------------------------\n\n/**\n * Extract an Arrow Table from a Polars DataFrame. Tries the common conversion\n * methods. We do NOT statically import `nodejs-polars` — the caller passes a\n * DataFrame object, keeping this module free of a hard dependency.\n */\nasync function polarsToArrow(df: any, method: PolarsToCubeOptions[\"arrowMethod\"]): Promise<any> {\n  const tried: string[] = [];\n  const tryMethod = async (name: string): Promise<any> => {\n    if (typeof df[name] !== \"function\") {\n      tried.push(name);\n      return undefined;\n    }\n    const result = await df[name]();\n    return result;\n  };\n\n  if (method === \"toArrow\" || method === \"auto\" || method === undefined) {\n    const t = await tryMethod(\"toArrow\");\n    if (t) return t;\n  }\n  if (method === \"toIPC\" || method === \"auto\" || method === undefined) {\n    const ipc = await tryMethod(\"toIPC\");\n    if (ipc) {\n      // IPC bytes → Arrow Table via apache-arrow's readIPC (lazy import).\n      const { tableFromIPC } = await import(\"apache-arrow\");\n      return tableFromIPC(ipc);\n    }\n  }\n\n  throw new PolarsSourceError(\n    `Could not obtain an Arrow Table from the Polars DataFrame (tried: ${tried.join(\", \")}). ` +\n      \"Ensure nodejs-polars is installed and the DataFrame supports toArrow()/toIPC().\",\n  );\n}\n\n// ---------------------------------------------------------------------------\n// Public API\n// ---------------------------------------------------------------------------\n\n/**\n * Convert a Polars `DataFrame` to the [`Observations`] IR via the Arrow hub.\n *\n * @param df A Polars DataFrame (`nodejs-polars`). Not statically typed to avoid\n *        a hard dependency; pass any object exposing `toArrow()`/`toIPC()`.\n * @throws [`PolarsSourceError`] if Arrow extraction fails.\n */\nexport async function polarsToCube(\n  df: any,\n  options: PolarsToCubeOptions = {},\n): Promise<Observations> {\n  const table = await polarsToArrow(df, options.arrowMethod ?? \"auto\");\n  if (!table) throw new PolarsSourceError(\"Polars DataFrame yielded no Arrow table\");\n  return arrowToCube(table, options);\n}\n\n/** Convenience: Polars DataFrame → JSON-stat [`Dataset`]. */\nexport async function polarsToDataset(\n  df: any,\n  options?: PolarsToCubeOptions,\n): Promise<JsonStatDataset> {\n  const { toDataset } = await import(\"../core/cubeBuilder\");\n  return toDataset(await polarsToCube(df, options));\n}\n\n/**\n * Lazily load `nodejs-polars`. Exposed so callers can `readCSV`/`readParquet`\n * via Polars without a direct import in their own code.\n */\nexport async function loadPolars(): Promise<any> {\n  try {\n    return await import(\"nodejs-polars\");\n  } catch {\n    throw new PolarsSourceError(\n      \"nodejs-polars is not installed. Install it with `npm i nodejs-polars` (Node only).\",\n    );\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Export: Observations IR → Polars DataFrame\n// ---------------------------------------------------------------------------\n\nexport interface CubeToPolarsOptions {\n  /**\n   * Conversion path from Arrow to Polars. `\"fromArrow\"` (default) uses\n   * `pl.fromArrow(table)`; `\"ipc\"` serializes the table to Arrow IPC and reads\n   * it via `pl.readIPC(buf)`. Usually unnecessary; `\"auto\"` tries `\"fromArrow\"`\n   * first, then `\"ipc\"`.\n   */\n  method?: \"fromArrow\" | \"ipc\" | \"auto\";\n}\n\n/**\n * Convert an Arrow [`Table`] to a Polars `DataFrame`. Tries the common\n * nodejs-polars constructors in order. Extracted so [`cubeToPolars`] and the\n * round-trip tests share one path.\n *\n * @internal\n */\nexport async function arrowToPolars(\n  table: Table,\n  method: CubeToPolarsOptions[\"method\"] = \"auto\",\n): Promise<any> {\n  const pl = await loadPolars();\n  const tried: string[] = [];\n\n  if (method === \"fromArrow\" || method === \"auto\") {\n    tried.push(\"pl.fromArrow\");\n    if (typeof pl.fromArrow === \"function\") {\n      try {\n        return pl.fromArrow(table);\n      } catch {\n        // fall through to ipc\n      }\n    }\n  }\n\n  if (method === \"ipc\" || method === \"auto\") {\n    tried.push(\"pl.readIPC\");\n    // Serialize the Arrow Table to IPC stream bytes, then read via Polars.\n    const { tableToIPC } = await import(\"apache-arrow\");\n    const buf = tableToIPC(table, \"stream\");\n    if (typeof pl.readIPC === \"function\") {\n      try {\n        return pl.readIPC(buf);\n      } catch {\n        // fall through\n      }\n    }\n  }\n\n  throw new PolarsSourceError(\n    `Could not build a Polars DataFrame from the Arrow Table (tried: ${tried.join(\", \")}). ` +\n      \"Ensure nodejs-polars is installed and supports fromArrow()/readIPC().\",\n  );\n}\n\n/**\n * Write the [`Observations`](../model/ir.ts) IR to a Polars `DataFrame`.\n *\n * The IR is first converted to an Arrow [`Table`] via [`cubeToArrow`], then\n * handed to `nodejs-polars` (`pl.fromArrow`). All `jsonstat.*` schema/field\n * metadata travels on the Arrow schema; Polars preserves it through the Arrow\n * IPC pathway, so a subsequent `df.toArrow()` → [`arrowToCube`] round-trips.\n *\n * Node-only: this function dynamically imports `nodejs-polars` and will throw\n * [`PolarsSourceError`] in the browser.\n *\n * @returns A Polars `DataFrame` (`nodejs-polars`).\n * @throws [`PolarsSourceError`] if nodejs-polars is missing or the conversion fails.\n *\n * @example\n * ```ts\n * import { cubeToPolars } from \"jsonstat-io/polars\";\n * const df = await cubeToPolars(observations);\n * console.log(df.shape);\n * ```\n */\nexport async function cubeToPolars(\n  obs: Observations,\n  options: CubeToPolarsOptions = {},\n): Promise<any> {\n  const table = cubeToArrow(obs);\n  return arrowToPolars(table, options.method);\n}\n"]}