jsonstat-io 0.1.0

package/dist/ir-Jae2ymov.d.ts

@@ -0,0 +1,143 @@
+import { a as JsonStatRole, b as JsonStatUnit } from './jsonstat-BX4mBLci.js';
+
+/**
+ * Observations IR — the format-agnostic intermediate representation.
+ *
+ * Every source (Arrow, Parquet, DuckDB, Polars, CSVW, CSV) converts its data
+ * into this IR. The cube builder ([`CubeBuilder`](../core/cubeBuilder.ts))
+ * then turns the IR into a JSON-stat [`Dataset`](./jsonstat.ts).
+ *
+ * The IR is deliberately a **long / tidy table**: one row per observation,
+ * with one column per dimension and a single measure column. This is the
+ * natural shape of the columnar stack and the dual of a JSON-stat cube.
+ *
+ * Because the IR is bidirectional, the same model also powers the Phase-2
+ * export path ([`cubeReader`](../core/cubeReader.ts) → IR →
+ * [`arrowFromCube`](../arrow/arrowFromCube.ts) → Arrow/Parquet/CSV). See
+ * [docs/architecture.md](../../docs/architecture.md) §"The two documented seams".
+ */
+
+/**
+ * A dimension column: the observed category *labels or IDs* for each row.
+ *
+ * `values` is a parallel array (one entry per observation) of category IDs.
+ * Category order is *not* implied here — it is resolved by the builder, which
+ * enumerates distinct values and assigns indices. Use `categoryOrder` to pin
+ * a specific order (e.g. chronological time) when the source knows it.
+ */
+interface DimensionColumn {
+    /** Dimension ID (becomes a key in JSON-stat `dimension`). */
+    id: string;
+    /** Human-readable dimension label. */
+    label?: string;
+    /** Per-row category ID. `null` is not permitted for dimensions. */
+    values: string[];
+    /**
+     * Optional explicit category ordering. When omitted the builder enumerates
+     * distinct values in first-seen order. Provide for time dimensions whose
+     * chronological order is not lexicographic.
+     */
+    categoryOrder?: string[];
+    /** ID → human-readable category label. Falls back to the ID. */
+    categoryLabels?: Record<string, string>;
+    /** ID → unit metadata (metric-role dimensions only). */
+    categoryUnits?: Record<string, JsonStatUnit>;
+    /** ID → [lon, lat] (geo-role dimensions only). */
+    categoryCoordinates?: Record<string, [number, number]>;
+    /** Parent ID → direct child IDs (hierarchical dimensions only). */
+    categoryChild?: Record<string, string[]>;
+    /** Optional href to an external dimension definition. */
+    href?: string;
+}
+/**
+ * The measure column: the numeric observation values, one per row.
+ *
+ * `null` represents a missing observation. The importer supports a single
+ * measure column in v0.1 — multi-measure datasets should be split across
+ * multiple datasets (one per metric) or modeled as a metric *dimension*,
+ * matching how JSON-stat treats measures as a dimension with the `metric`
+ * role rather than as separate value arrays.
+ */
+interface MeasureColumn {
+    /** Column name in the source (kept for round-trip fidelity, not emitted). */
+    name?: string;
+    /** Numeric values; `null` = missing. */
+    values: (number | null)[];
+}
+/**
+ * Optional per-row status column. Provider-defined vocabulary; emitted verbatim
+ * as JSON-stat `status` (array form) by the builder.
+ */
+interface StatusColumn {
+    /** Per-row status code. */
+    values: string[];
+}
+/**
+ * Role assignment. Mirrors JSON-stat's `role` object: each role maps to a list
+ * of dimension IDs. The importer assigns roles from source metadata or CLI
+ * hints; unassigned dimensions default to the implicit "classification" role.
+ */
+type RoleMap = JsonStatRole;
+/**
+ * Dataset-level metadata carried alongside the observations.
+ *
+ * These fields map directly to top-level JSON-stat dataset properties
+ * (`label`, `source`, `updated`, `extension`).
+ */
+interface DatasetMeta {
+    label?: string;
+    source?: string;
+    updated?: string;
+    extension?: Record<string, unknown>;
+}
+/**
+ * The complete cube model: everything the builder needs besides the raw
+ * observation columns to produce a fully-specified JSON-stat dataset.
+ */
+interface CubeModel {
+    /** Ordered dimension IDs. Determines row-major stride order. */
+    dimensionIds: string[];
+    /** Role assignments (time/geo/metric). */
+    roles?: RoleMap;
+    /** Dataset-level metadata. */
+    meta?: DatasetMeta;
+    /**
+     * How to emit `value`.
+     * - "auto": dense unless null-ratio exceeds `sparseThreshold`.
+     * - "dense": always array form.
+     * - "sparse": always object form.
+     */
+    valueForm?: "auto" | "dense" | "sparse";
+    /** Null ratio above which "auto" chooses sparse. Default 0.5. */
+    sparseThreshold?: number;
+    /**
+     * Whether to emit a status array. When a StatusColumn is present and this is
+     * not "none", the builder emits status. "object" emits the sparse object form
+     * when there are few non-default statuses; "string" collapses a uniform
+     * status to a single string.
+     */
+    statusForm?: "auto" | "array" | "string" | "object" | "none";
+}
+/**
+ * The Observations IR: a tidy long table plus its cube model.
+ *
+ * Invariants the builder assumes (validated in [`CubeBuilder.build`]):
+ * - All columns in `dimensions` and `measure` share the same length `n`.
+ * - `status`, if present, has length `n`.
+ * - `model.dimensionIds` lists every dimension column id, and no others.
+ * - No dimension value is `null` or `undefined`.
+ */
+interface Observations {
+    /** Dimension columns, keyed by dimension ID. */
+    dimensions: Record<string, DimensionColumn>;
+    /** The single measure column. */
+    measure: MeasureColumn;
+    /** Optional per-row status. */
+    status?: StatusColumn;
+    /** The cube model governing how to build the JSON-stat dataset. */
+    model: CubeModel;
+}
+/** Number of observations (rows). */
+declare function observationCount(obs: Observations): number;
+
+export { type CubeModel as C, type DatasetMeta as D, type MeasureColumn as M, type Observations as O, type RoleMap as R, type StatusColumn as S, type DimensionColumn as a, observationCount as o };

package/dist/jsonstat-BX4mBLci.d.cts

@@ -0,0 +1,179 @@
+/**
+ * JSON-stat 2.0 type model.
+ *
+ * Faithful TypeScript representation of the JSON-stat 2.0 format, derived from
+ * the official specification (raw/fullspec.html) and the vendored JSON Schemas
+ * (raw/schema/{index,dataset,collection,dimension}.json).
+ *
+ * These are *structural* types: they describe the wire format. Cross-field
+ * cube invariants (e.g. `value.length === size.reduce(product)`) live in the
+ * core engine, mirroring how the official JSON Schemas defer semantic checks
+ * to jsonstat-validator (see wiki/validator.md and wiki/schema.md).
+ */
+/** Allowed JSON-stat response classes (see wiki/response-classes.md). */
+type JsonStatClass = "dataset" | "dimension" | "collection" | "bundle" | "error";
+/** Semantic role assigned to one or more dimension IDs (see wiki/dimensions.md). */
+interface JsonStatRole {
+    /** Dimension IDs carrying temporal data (chronological order assumed). */
+    time?: string[];
+    /** Dimension IDs carrying spatial data (categories may have coordinates). */
+    geo?: string[];
+    /** Dimension IDs carrying different metrics/measures (units attached). */
+    metric?: string[];
+}
+/** Unit of measure metadata for a metric-role category (see wiki/dimensions.md). */
+interface JsonStatUnit {
+    /** Required when `unit` is present: number of decimals. */
+    decimals: number;
+    /** Unit text displayed after (or before) the value. */
+    label?: string;
+    /** Unit symbol, e.g. "$" or "%". */
+    symbol?: string;
+    /** Where the symbol goes relative to the value. Defaults to "end". */
+    position?: "start" | "end";
+}
+/** [longitude, latitude] pair for geo-role categories. */
+type Coordinates = [longitude: number, latitude: number];
+/**
+ * Category block of a dimension.
+ *
+ * `index` may be an array (IDs in order) or an object (ID→position map). For
+ * constant (single-category) dimensions `index` is unnecessary provided a
+ * `label` is given. `label` is optional and falls back to category IDs.
+ */
+interface JsonStatCategory {
+    /** Category ordering. Array form: `["M","F","T"]`. Object form: `{"M":0,...}`. */
+    index?: string[] | Record<string, number>;
+    /** ID→human-readable label map. If omitted, IDs are used as labels. */
+    label?: Record<string, string>;
+    /** Parent ID → array of direct-child IDs (hierarchies; see wiki/dimensions.md). */
+    child?: Record<string, string[]>;
+    /** ID → [lon, lat] for geo-role categories. */
+    coordinates?: Record<string, Coordinates>;
+    /** ID → unit metadata for metric-role categories. */
+    unit?: Record<string, JsonStatUnit>;
+}
+/**
+ * A dimension object within `dimension`.
+ *
+ * `category` is the only required property in practice for the dimension
+ * class; for dataset-class dimensions it is always present.
+ */
+interface JsonStatDimension {
+    /** Short descriptive text (lowercase recommended). */
+    label?: string;
+    /** The categories of this dimension. */
+    category?: JsonStatCategory;
+    /** URL to an external dimension definition. */
+    href?: string;
+    /** Provider-specific extension data. */
+    extension?: Record<string, unknown>;
+    /** Related resources (see wiki/links.md). */
+    link?: JsonStatLink[];
+    /** Annotations. */
+    note?: string[];
+}
+/** A single link entry. `rel` is an IANA link relation (e.g. "item", "self"). */
+interface JsonStatLink {
+    /** IANA link relation type. */
+    rel?: string;
+    /** Target URL. */
+    href?: string;
+    /** Type of the linked resource (e.g. a class value). */
+    type?: string;
+    /** Human-readable label. */
+    label?: string;
+    /** When present, the item is embedded inline rather than referenced by href. */
+    [embedded: string]: unknown;
+}
+/** Container for links, indexed by relation. The "item" relation holds an array. */
+interface JsonStatLinkMap {
+    [rel: string]: JsonStatLink[] | undefined;
+}
+/**
+ * Observation-level status. Three forms:
+ * - array: one status code per cell (aligned with `value`)
+ * - string: a single status applied to all cells
+ * - object: position→status for specific cells (sparse status)
+ *
+ * Status has no standard vocabulary — it is provider-defined.
+ */
+type JsonStatStatus = string[] | string | Record<string, string>;
+/**
+ * Cell values in row-major order ("what does not change, first"; the last
+ * dimension in `id` changes fastest).
+ *
+ * - Array form (dense): missing values are `null`.
+ * - Object form (sparse): maps flat position index → value, omitting nulls.
+ */
+type JsonStatValue = (number | null)[] | Record<string, number>;
+/** Top-level dataset response (see wiki/response-classes.md). */
+interface JsonStatDataset {
+    version: "2.0";
+    class: "dataset";
+    /** Short descriptive text. */
+    label?: string;
+    /** Short text describing the dataset source. */
+    source?: string;
+    /** Update time in ISO 8601. */
+    updated?: string;
+    /** Ordered list of dimension IDs. */
+    id: string[];
+    /** Number of categories per dimension, same order as `id`. */
+    size: number[];
+    /** Per-dimension metadata, keyed by dimension ID. */
+    dimension: Record<string, JsonStatDimension>;
+    /** Cell values (dense or sparse). */
+    value: JsonStatValue;
+    /** Observation-level status metadata. */
+    status?: JsonStatStatus;
+    /** Semantic roles for dimensions. */
+    role?: JsonStatRole;
+    /** Provider-specific extension data. */
+    extension?: Record<string, unknown>;
+    /** Related resources. */
+    link?: JsonStatLinkMap;
+    /** Annotations. */
+    note?: string[];
+    /** URL of the dataset. */
+    href?: string;
+    /** Optional error array (suggested, not mandatory). */
+    error?: JsonStatError[];
+}
+/** Dimension-only response. */
+interface JsonStatDimensionResponse {
+    version: "2.0";
+    class: "dimension";
+    label?: string;
+    category: JsonStatCategory;
+    extension?: Record<string, unknown>;
+    link?: JsonStatLinkMap;
+    href?: string;
+}
+/** Collection response (2.0 replacement for bundles). */
+interface JsonStatCollection {
+    version: "2.0";
+    class: "collection";
+    href?: string;
+    label?: string;
+    updated?: string;
+    link: JsonStatLinkMap;
+    extension?: Record<string, unknown>;
+}
+/** A proposed (not mandatory) error entry. */
+interface JsonStatError {
+    status?: number;
+    id?: string;
+    href?: string;
+    label?: string;
+}
+/** Any top-level JSON-stat 2.0 response. */
+type JsonStatResponse = JsonStatDataset | JsonStatDimensionResponse | JsonStatCollection;
+/** Discriminated union guard helper: is this a dataset response? */
+declare function isDataset(r: JsonStatResponse): r is JsonStatDataset;
+/** Discriminated union guard helper: is this a collection response? */
+declare function isCollection(r: JsonStatResponse): r is JsonStatCollection;
+/** Discriminated union guard helper: is this a dimension response? */
+declare function isDimensionResponse(r: JsonStatResponse): r is JsonStatDimensionResponse;
+
+export { type Coordinates as C, type JsonStatDataset as J, type JsonStatRole as a, type JsonStatUnit as b, type JsonStatResponse as c, type JsonStatCategory as d, type JsonStatClass as e, type JsonStatCollection as f, type JsonStatDimension as g, type JsonStatDimensionResponse as h, type JsonStatError as i, type JsonStatLink as j, type JsonStatLinkMap as k, type JsonStatStatus as l, type JsonStatValue as m, isCollection as n, isDataset as o, isDimensionResponse as p };

package/dist/jsonstat-BX4mBLci.d.ts

@@ -0,0 +1,179 @@
+/**
+ * JSON-stat 2.0 type model.
+ *
+ * Faithful TypeScript representation of the JSON-stat 2.0 format, derived from
+ * the official specification (raw/fullspec.html) and the vendored JSON Schemas
+ * (raw/schema/{index,dataset,collection,dimension}.json).
+ *
+ * These are *structural* types: they describe the wire format. Cross-field
+ * cube invariants (e.g. `value.length === size.reduce(product)`) live in the
+ * core engine, mirroring how the official JSON Schemas defer semantic checks
+ * to jsonstat-validator (see wiki/validator.md and wiki/schema.md).
+ */
+/** Allowed JSON-stat response classes (see wiki/response-classes.md). */
+type JsonStatClass = "dataset" | "dimension" | "collection" | "bundle" | "error";
+/** Semantic role assigned to one or more dimension IDs (see wiki/dimensions.md). */
+interface JsonStatRole {
+    /** Dimension IDs carrying temporal data (chronological order assumed). */
+    time?: string[];
+    /** Dimension IDs carrying spatial data (categories may have coordinates). */
+    geo?: string[];
+    /** Dimension IDs carrying different metrics/measures (units attached). */
+    metric?: string[];
+}
+/** Unit of measure metadata for a metric-role category (see wiki/dimensions.md). */
+interface JsonStatUnit {
+    /** Required when `unit` is present: number of decimals. */
+    decimals: number;
+    /** Unit text displayed after (or before) the value. */
+    label?: string;
+    /** Unit symbol, e.g. "$" or "%". */
+    symbol?: string;
+    /** Where the symbol goes relative to the value. Defaults to "end". */
+    position?: "start" | "end";
+}
+/** [longitude, latitude] pair for geo-role categories. */
+type Coordinates = [longitude: number, latitude: number];
+/**
+ * Category block of a dimension.
+ *
+ * `index` may be an array (IDs in order) or an object (ID→position map). For
+ * constant (single-category) dimensions `index` is unnecessary provided a
+ * `label` is given. `label` is optional and falls back to category IDs.
+ */
+interface JsonStatCategory {
+    /** Category ordering. Array form: `["M","F","T"]`. Object form: `{"M":0,...}`. */
+    index?: string[] | Record<string, number>;
+    /** ID→human-readable label map. If omitted, IDs are used as labels. */
+    label?: Record<string, string>;
+    /** Parent ID → array of direct-child IDs (hierarchies; see wiki/dimensions.md). */
+    child?: Record<string, string[]>;
+    /** ID → [lon, lat] for geo-role categories. */
+    coordinates?: Record<string, Coordinates>;
+    /** ID → unit metadata for metric-role categories. */
+    unit?: Record<string, JsonStatUnit>;
+}
+/**
+ * A dimension object within `dimension`.
+ *
+ * `category` is the only required property in practice for the dimension
+ * class; for dataset-class dimensions it is always present.
+ */
+interface JsonStatDimension {
+    /** Short descriptive text (lowercase recommended). */
+    label?: string;
+    /** The categories of this dimension. */
+    category?: JsonStatCategory;
+    /** URL to an external dimension definition. */
+    href?: string;
+    /** Provider-specific extension data. */
+    extension?: Record<string, unknown>;
+    /** Related resources (see wiki/links.md). */
+    link?: JsonStatLink[];
+    /** Annotations. */
+    note?: string[];
+}
+/** A single link entry. `rel` is an IANA link relation (e.g. "item", "self"). */
+interface JsonStatLink {
+    /** IANA link relation type. */
+    rel?: string;
+    /** Target URL. */
+    href?: string;
+    /** Type of the linked resource (e.g. a class value). */
+    type?: string;
+    /** Human-readable label. */
+    label?: string;
+    /** When present, the item is embedded inline rather than referenced by href. */
+    [embedded: string]: unknown;
+}
+/** Container for links, indexed by relation. The "item" relation holds an array. */
+interface JsonStatLinkMap {
+    [rel: string]: JsonStatLink[] | undefined;
+}
+/**
+ * Observation-level status. Three forms:
+ * - array: one status code per cell (aligned with `value`)
+ * - string: a single status applied to all cells
+ * - object: position→status for specific cells (sparse status)
+ *
+ * Status has no standard vocabulary — it is provider-defined.
+ */
+type JsonStatStatus = string[] | string | Record<string, string>;
+/**
+ * Cell values in row-major order ("what does not change, first"; the last
+ * dimension in `id` changes fastest).
+ *
+ * - Array form (dense): missing values are `null`.
+ * - Object form (sparse): maps flat position index → value, omitting nulls.
+ */
+type JsonStatValue = (number | null)[] | Record<string, number>;
+/** Top-level dataset response (see wiki/response-classes.md). */
+interface JsonStatDataset {
+    version: "2.0";
+    class: "dataset";
+    /** Short descriptive text. */
+    label?: string;
+    /** Short text describing the dataset source. */
+    source?: string;
+    /** Update time in ISO 8601. */
+    updated?: string;
+    /** Ordered list of dimension IDs. */
+    id: string[];
+    /** Number of categories per dimension, same order as `id`. */
+    size: number[];
+    /** Per-dimension metadata, keyed by dimension ID. */
+    dimension: Record<string, JsonStatDimension>;
+    /** Cell values (dense or sparse). */
+    value: JsonStatValue;
+    /** Observation-level status metadata. */
+    status?: JsonStatStatus;
+    /** Semantic roles for dimensions. */
+    role?: JsonStatRole;
+    /** Provider-specific extension data. */
+    extension?: Record<string, unknown>;
+    /** Related resources. */
+    link?: JsonStatLinkMap;
+    /** Annotations. */
+    note?: string[];
+    /** URL of the dataset. */
+    href?: string;
+    /** Optional error array (suggested, not mandatory). */
+    error?: JsonStatError[];
+}
+/** Dimension-only response. */
+interface JsonStatDimensionResponse {
+    version: "2.0";
+    class: "dimension";
+    label?: string;
+    category: JsonStatCategory;
+    extension?: Record<string, unknown>;
+    link?: JsonStatLinkMap;
+    href?: string;
+}
+/** Collection response (2.0 replacement for bundles). */
+interface JsonStatCollection {
+    version: "2.0";
+    class: "collection";
+    href?: string;
+    label?: string;
+    updated?: string;
+    link: JsonStatLinkMap;
+    extension?: Record<string, unknown>;
+}
+/** A proposed (not mandatory) error entry. */
+interface JsonStatError {
+    status?: number;
+    id?: string;
+    href?: string;
+    label?: string;
+}
+/** Any top-level JSON-stat 2.0 response. */
+type JsonStatResponse = JsonStatDataset | JsonStatDimensionResponse | JsonStatCollection;
+/** Discriminated union guard helper: is this a dataset response? */
+declare function isDataset(r: JsonStatResponse): r is JsonStatDataset;
+/** Discriminated union guard helper: is this a collection response? */
+declare function isCollection(r: JsonStatResponse): r is JsonStatCollection;
+/** Discriminated union guard helper: is this a dimension response? */
+declare function isDimensionResponse(r: JsonStatResponse): r is JsonStatDimensionResponse;
+
+export { type Coordinates as C, type JsonStatDataset as J, type JsonStatRole as a, type JsonStatUnit as b, type JsonStatResponse as c, type JsonStatCategory as d, type JsonStatClass as e, type JsonStatCollection as f, type JsonStatDimension as g, type JsonStatDimensionResponse as h, type JsonStatError as i, type JsonStatLink as j, type JsonStatLinkMap as k, type JsonStatStatus as l, type JsonStatValue as m, isCollection as n, isDataset as o, isDimensionResponse as p };

package/dist/sources/csv.cjs

@@ -0,0 +1,40 @@
+'use strict';
+
+var chunkKFIKGBIJ_cjs = require('../chunk-KFIKGBIJ.cjs');
+
+
+
+Object.defineProperty(exports, "CsvSourceError", {
+  enumerable: true,
+  get: function () { return chunkKFIKGBIJ_cjs.CsvSourceError; }
+});
+Object.defineProperty(exports, "csvToCube", {
+  enumerable: true,
+  get: function () { return chunkKFIKGBIJ_cjs.csvToCube; }
+});
+Object.defineProperty(exports, "csvToDataset", {
+  enumerable: true,
+  get: function () { return chunkKFIKGBIJ_cjs.csvToDataset; }
+});
+Object.defineProperty(exports, "cubeColumns", {
+  enumerable: true,
+  get: function () { return chunkKFIKGBIJ_cjs.cubeColumns; }
+});
+Object.defineProperty(exports, "cubeToCsv", {
+  enumerable: true,
+  get: function () { return chunkKFIKGBIJ_cjs.cubeToCsv; }
+});
+Object.defineProperty(exports, "parseCsv", {
+  enumerable: true,
+  get: function () { return chunkKFIKGBIJ_cjs.parseCsv; }
+});
+Object.defineProperty(exports, "quoteCsvField", {
+  enumerable: true,
+  get: function () { return chunkKFIKGBIJ_cjs.quoteCsvField; }
+});
+Object.defineProperty(exports, "serializeRows", {
+  enumerable: true,
+  get: function () { return chunkKFIKGBIJ_cjs.serializeRows; }
+});
+//# sourceMappingURL=csv.cjs.map
+//# sourceMappingURL=csv.cjs.map

package/dist/sources/csv.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"csv.cjs"}

package/dist/sources/csv.d.cts

@@ -0,0 +1,112 @@
+import { R as RoleMap, O as Observations } from '../ir-BArfNxo-.cjs';
+import { J as JsonStatDataset } from '../jsonstat-BX4mBLci.cjs';
+
+/**
+ * CSV adapter — `jsonstat-io/csv`.
+ *
+ * **Import:** unlike Parquet/DuckDB/Polars (which funnel through the Arrow
+ * hub), plain CSV has no native Arrow producer in this package, so this adapter
+ * builds the [`Observations`](../model/ir.ts) IR **directly** from parsed rows.
+ *
+ * **Export:** [`cubeToCsv`] writes the [`Observations`] IR to RFC-4180-style
+ * CSV text (dimension columns + measure column + optional status column).
+ *
+ * ## Mapping heuristics (no metadata)
+ *
+ * Without a schema, the adapter infers:
+ *  - The **measure** is the first column that parses as a number for every
+ *    non-empty row (or the one named by `options.measure`).
+ *  - Every other column is a **dimension** (string-typed), in file order.
+ *  - A column named `status` (case-insensitive) is treated as the status
+ *    column unless `options.status` overrides it.
+ *
+ * Empty cells become `null` in the measure and `""` in dimensions (then
+ * rejected by the builder; sources should pre-clean). For richer, lossless
+ * mapping with declared types/labels/roles, use CSVW (see [`csvw`](./csvw.ts)).
+ */
+
+declare class CsvSourceError extends Error {
+    constructor(message: string);
+}
+interface CsvToCubeOptions {
+    /** Explicit measure column name. Overrides inference. */
+    measure?: string;
+    /** Explicit dimension column names, in order. */
+    dimensions?: string[];
+    /** Explicit status column name. Overrides the `status`-name heuristic. */
+    status?: string;
+    /** Role assignments. */
+    roles?: RoleMap;
+    /** Value-form hint. */
+    valueForm?: "auto" | "dense" | "sparse";
+    /** CSV delimiter (default ","). */
+    delimiter?: string;
+    /** Treat the first row as a header (default true). */
+    header?: boolean;
+}
+/**
+ * A tiny, dependency-free RFC-4180-ish CSV parser. Handles quoted fields,
+ * embedded quotes (doubled), and embedded newlines. Sufficient for the
+ * importer's needs; for heavy CSV work, prefer piping through DuckDB/Polars.
+ */
+declare function parseCsv(input: string, delimiter?: string): string[][];
+/**
+ * Parse CSV text into the [`Observations`] IR.
+ *
+ * @throws [`CsvSourceError`] on structural problems.
+ */
+declare function csvToCube(text: string, options?: CsvToCubeOptions): Observations;
+/** Convenience: CSV text → JSON-stat [`Dataset`]. */
+declare function csvToDataset(text: string, options?: CsvToCubeOptions): Promise<JsonStatDataset>;
+interface CubeToCsvOptions {
+    /** CSV delimiter (default ","). */
+    delimiter?: string;
+    /** Line terminator: "\r\n" (RFC-4180 default) or "\n". */
+    lineTerminator?: string;
+}
+/**
+ * Resolve the ordered list of (column name, row value extractor) pairs for a
+ * dataset IR. Shared by [`cubeToCsv`] and [`cubeToCsvw`] so the two writers
+ * agree on column layout.
+ *
+ * Column order: dimension IDs (in `model.dimensionIds` order) → measure
+ * (named `measure.name ?? "value"`) → status (`"status"`, if present).
+ *
+ * @internal
+ */
+declare function cubeColumns(obs: Observations): {
+    header: string[];
+    rows: string[];
+};
+/**
+ * Quote a single CSV field per RFC-4180. A field needs quoting if it contains
+ * the delimiter, a double quote, a CR, or an LF. Embedded quotes are doubled.
+ */
+declare function quoteCsvField(value: string, delimiter: string, force?: boolean): string;
+/**
+ * Serialize a CSV header + rows (as produced by [`cubeColumns`]) into RFC-4180
+ * text. Extracted so CSV and CSVW writers share one escaping path.
+ *
+ * @internal
+ */
+declare function serializeRows(header: string[], rows: string[], options?: CubeToCsvOptions): string;
+/**
+ * Write the [`Observations`](../model/ir.ts) IR to RFC-4180-style CSV text.
+ *
+ * The output is a tidy long table: one header row + one row per observation.
+ * Columns are the dimension IDs (in `model.dimensionIds` order), then the
+ * measure column (`measure.name ?? "value"`), then an optional `status`
+ * column. Null measures are emitted as empty cells.
+ *
+ * This is the lossy inverse of [`csvToCube`]: labels, roles, and category
+ * metadata are not preserved (use [`cubeToCsvw`] for a lossless export).
+ *
+ * @example
+ * ```ts
+ * import { cubeToCsv } from "jsonstat-io/csv";
+ * const csv = cubeToCsv(observations);
+ * ```
+ */
+declare function cubeToCsv(obs: Observations, options?: CubeToCsvOptions): string;
+
+export { CsvSourceError, type CsvToCubeOptions, type CubeToCsvOptions, csvToCube, csvToDataset, cubeColumns, cubeToCsv, parseCsv, quoteCsvField, serializeRows };