jsonstat-io 0.1.0

package/dist/sources/csv.d.ts

@@ -0,0 +1,112 @@
+import { R as RoleMap, O as Observations } from '../ir-Jae2ymov.js';
+import { J as JsonStatDataset } from '../jsonstat-BX4mBLci.js';
+
+/**
+ * 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 };

package/dist/sources/csv.js

@@ -0,0 +1,3 @@
+export { CsvSourceError, csvToCube, csvToDataset, cubeColumns, cubeToCsv, parseCsv, quoteCsvField, serializeRows } from '../chunk-62NIY7ML.js';
+//# sourceMappingURL=csv.js.map
+//# sourceMappingURL=csv.js.map

package/dist/sources/csv.js.map

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

package/dist/sources/csvw.cjs

@@ -0,0 +1,236 @@
+'use strict';
+
+var chunkKFIKGBIJ_cjs = require('../chunk-KFIKGBIJ.cjs');
+
+// src/sources/csvw.ts
+var CsvwSourceError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "CsvwSourceError";
+  }
+};
+function firstTitle(col) {
+  if (!col.titles) return void 0;
+  return Array.isArray(col.titles) ? col.titles[0] : col.titles;
+}
+function isNumericDatatype(dt) {
+  if (!dt) return false;
+  const base = typeof dt === "string" ? dt : dt.base;
+  return base === "decimal" || base === "integer" || base === "double" || base === "float" || base === "number" || base === "long" || base === "int" || base === "short" || base === "byte";
+}
+function roleFromPropertyUrl(url) {
+  if (!url) return void 0;
+  const u = url.toLowerCase();
+  if (u.includes("time") || u.includes("date")) return "time";
+  if (u.includes("geo") || u.includes("spatial") || u.includes("place")) return "geo";
+  if (u.includes("metric") || u.includes("measure") || u.includes("obsvalue")) return "metric";
+  return void 0;
+}
+function csvwToCube(csvText, metadata, options = {}) {
+  if (!metadata.tableSchema?.columns?.length) {
+    throw new CsvwSourceError("CSVW metadata is missing tableSchema.columns");
+  }
+  const delimiter = options.delimiter ?? ",";
+  const header = options.header ?? true;
+  const schema = metadata.tableSchema;
+  const rows = chunkKFIKGBIJ_cjs.parseCsv(csvText, delimiter);
+  if (rows.length === 0) throw new CsvwSourceError("CSV has no rows");
+  let dataRows;
+  if (header) {
+    dataRows = rows.slice(1);
+  } else {
+    dataRows = rows;
+  }
+  const cols = schema.columns.filter((c) => !c.virtual);
+  const colCount = cols.length;
+  if (dataRows.length === 0) throw new CsvwSourceError("CSV has no data rows");
+  const columnValues = cols.map(() => []);
+  for (const r of dataRows) {
+    for (let c = 0; c < colCount; c++) {
+      const cell = r[c] ?? cols[c].default ?? "";
+      columnValues[c].push(cell);
+    }
+  }
+  let measureIdx = cols.findIndex((c) => c.name === options.measure);
+  if (measureIdx === -1) {
+    measureIdx = cols.findIndex((c) => isNumericDatatype(c.datatype));
+    if (measureIdx === -1) {
+      throw new CsvwSourceError(
+        "No measure column: no column has a numeric datatype. Pass options.measure to name one."
+      );
+    }
+  }
+  let statusIdx = cols.findIndex((c) => c.name === options.status);
+  if (statusIdx === -1 && !options.status) {
+    statusIdx = cols.findIndex(
+      (c) => c.name.toLowerCase() === "status" || roleFromPropertyUrl(c.propertyUrl) === void 0 && c.name.toLowerCase() === "status"
+    );
+    if (statusIdx === measureIdx) statusIdx = -1;
+  }
+  let dimensionIdxs;
+  if (options.dimensions) {
+    dimensionIdxs = options.dimensions.map((n) => {
+      const idx = cols.findIndex((c) => c.name === n);
+      if (idx === -1) throw new CsvwSourceError(`Dimension column "${n}" not in schema`);
+      return idx;
+    });
+  } else {
+    const pk = schema.primaryKey ? Array.isArray(schema.primaryKey) ? schema.primaryKey : [schema.primaryKey] : [];
+    if (pk.length > 0) {
+      dimensionIdxs = pk.map((n) => {
+        const idx = cols.findIndex((c) => c.name === n);
+        if (idx === -1) throw new CsvwSourceError(`primaryKey column "${n}" not in schema`);
+        return idx;
+      });
+      for (let i = 0; i < cols.length; i++) {
+        if (i === measureIdx || i === statusIdx || dimensionIdxs.includes(i)) continue;
+        dimensionIdxs.push(i);
+      }
+    } else {
+      dimensionIdxs = cols.map((_, i) => i).filter((i) => i !== measureIdx && i !== statusIdx);
+    }
+  }
+  if (dimensionIdxs.length === 0) {
+    throw new CsvwSourceError("No dimension columns resolved");
+  }
+  const dimensions = {};
+  for (const idx of dimensionIdxs) {
+    const col = cols[idx];
+    const label = firstTitle(col);
+    dimensions[col.name] = {
+      id: col.name,
+      values: columnValues[idx].map((v) => v === "" ? "" : v),
+      label
+    };
+  }
+  const measure = {
+    name: cols[measureIdx].name,
+    values: columnValues[measureIdx].map((v) => {
+      if (v === "") return null;
+      const n = Number(v);
+      return Number.isFinite(n) ? n : null;
+    })
+  };
+  let status;
+  if (statusIdx !== -1) {
+    status = { values: columnValues[statusIdx].slice() };
+  }
+  const roles = {};
+  const addRole = (role, id) => {
+    (roles[role] ?? (roles[role] = [])).push(id);
+  };
+  if (metadata["jsonstat:roles"]) {
+    for (const r of ["time", "geo", "metric"]) {
+      for (const id of metadata["jsonstat:roles"][r] ?? []) addRole(r, id);
+    }
+  }
+  for (const idx of dimensionIdxs) {
+    const role = roleFromPropertyUrl(cols[idx].propertyUrl);
+    if (role) addRole(role, cols[idx].name);
+  }
+  if (options.roles) {
+    for (const r of ["time", "geo", "metric"]) {
+      for (const id of options.roles[r] ?? []) addRole(r, id);
+    }
+  }
+  const observations = {
+    dimensions,
+    measure,
+    status,
+    model: {
+      dimensionIds: dimensionIdxs.map((i) => cols[i].name),
+      roles: Object.keys(roles).length ? roles : void 0,
+      meta: {
+        label: metadata["dc:title"],
+        source: metadata["dc:source"],
+        updated: metadata["dcat:modified"],
+        extension: metadata["jsonstat:extension"]
+      },
+      valueForm: metadata["jsonstat:valueForm"] ?? "auto",
+      statusForm: status ? "auto" : "none"
+    }
+  };
+  return observations;
+}
+async function csvwToDataset(csvText, metadata, options) {
+  const { toDataset } = await import('../cubeBuilder-ZU76VVEX.cjs');
+  return toDataset(csvwToCube(csvText, metadata, options));
+}
+function parseCsvwMetadata(json) {
+  const m = json;
+  if (!m || !m.tableSchema || !Array.isArray(m.tableSchema.columns)) {
+    throw new CsvwSourceError("Invalid CSVW metadata: missing tableSchema.columns");
+  }
+  return m;
+}
+function propertyUrlForRole(role) {
+  if (role === "time") return "schema:DateTime";
+  if (role === "geo") return "schema:Place";
+  if (role === "metric") return "schema:Measure";
+  return void 0;
+}
+function roleOf(obs, id) {
+  const roles = obs.model.roles;
+  if (!roles) return void 0;
+  if (roles.time?.includes(id)) return "time";
+  if (roles.geo?.includes(id)) return "geo";
+  if (roles.metric?.includes(id)) return "metric";
+  return void 0;
+}
+function cubeToCsvw(obs, options = {}) {
+  const { header, rows } = chunkKFIKGBIJ_cjs.cubeColumns(obs);
+  const csv = chunkKFIKGBIJ_cjs.serializeRows(header, rows, options);
+  const dimIds = obs.model.dimensionIds;
+  const measureName = obs.measure.name ?? "value";
+  const hasStatus = obs.status !== void 0;
+  const meta = obs.model.meta;
+  const columns = [];
+  for (const id of dimIds) {
+    const col = obs.dimensions[id];
+    const role = roleOf(obs, id);
+    const propUrl = propertyUrlForRole(role);
+    columns.push({
+      name: id,
+      titles: col?.label ?? id,
+      datatype: "string",
+      ...propUrl ? { propertyUrl: propUrl } : {}
+    });
+  }
+  columns.push({
+    name: measureName,
+    titles: measureName,
+    datatype: "decimal",
+    propertyUrl: "schema:value",
+    required: false
+  });
+  if (hasStatus) {
+    columns.push({
+      name: "status",
+      titles: "status",
+      datatype: "string"
+    });
+  }
+  const metadata = {
+    url: options.url ?? "data.csv",
+    "@context": ["http://www.w3.org/ns/csvw", { "@language": "en" }],
+    tableSchema: {
+      columns,
+      primaryKey: dimIds.slice()
+    }
+  };
+  if (meta?.label) metadata["dc:title"] = meta.label;
+  if (meta?.source) metadata["dc:source"] = meta.source;
+  if (meta?.updated) metadata["dcat:modified"] = meta.updated;
+  if (meta?.extension) metadata["jsonstat:extension"] = meta.extension;
+  if (obs.model.roles) metadata["jsonstat:roles"] = obs.model.roles;
+  if (obs.model.valueForm) metadata["jsonstat:valueForm"] = obs.model.valueForm;
+  return { csv, metadata };
+}
+
+exports.CsvwSourceError = CsvwSourceError;
+exports.csvwToCube = csvwToCube;
+exports.csvwToDataset = csvwToDataset;
+exports.cubeToCsvw = cubeToCsvw;
+exports.parseCsvwMetadata = parseCsvwMetadata;
+//# sourceMappingURL=csvw.cjs.map
+//# sourceMappingURL=csvw.cjs.map

package/dist/sources/csvw.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/sources/csvw.ts"],"names":["parseCsv","cubeColumns","serializeRows"],"mappings":"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","file":"csvw.cjs","sourcesContent":["/**\n * CSVW (CSV on the Web) adapter — `jsonstat-io/csvw`.\n *\n * **Import:** CSVW pairs a CSV file with a JSON-LD metadata document that\n * declares a `tableSchema` — column names, types, `titles` (human labels),\n * `primaryKey`, and property URLs. This metadata enables a **lossless** mapping\n * straight to the [`Observations`](../model/ir.ts) IR, without the inference\n * heuristics of plain [`csv`](./csv.ts).\n *\n * **Export:** [`cubeToCsvw`] generates both the CSV text and a CSVW metadata\n * document from the [`Observations`] IR.\n *\n * ## Mapping\n *\n *  - Columns whose `datatype` is numeric → measure candidates.\n *  - The measure is the first numeric column, or the one flagged via\n *    `options.measure`. Other columns are dimensions.\n *  - `tableSchema.primaryKey` columns are treated as dimensions (and can pin\n *    the dimension order via `options.dimensions`).\n *  - `titles` → dimension/category labels; `name` → dimension id.\n *  - `primaryKey` → dimension id list (used as `dimensionIds` when\n *    `options.dimensions` is not given).\n *  - `propertyUrl` containing `time`/`geo`/`metric` → role hints.\n *\n * The adapter does not implement the full CSVW spec (foreign keys, URL\n * templates, cell value transformations); it covers the subset needed to\n * faithfully round-trip statistical cubes. See [docs/formats/csvw.md](../../docs/formats/csvw.md).\n */\n\nimport type {\n  DimensionColumn,\n  MeasureColumn,\n  Observations,\n  RoleMap,\n  StatusColumn,\n} from \"../model/ir\";\nimport type { JsonStatDataset } from \"../model/jsonstat\";\nimport { parseCsv, cubeColumns, serializeRows } from \"./csv\";\n\n// ---------------------------------------------------------------------------\n// Errors & CSVW metadata types\n// ---------------------------------------------------------------------------\n\nexport class CsvwSourceError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = \"CsvwSourceError\";\n  }\n}\n\n/** A column declaration in a CSVW `tableSchema`. */\nexport interface CsvwColumn {\n  name: string;\n  titles?: string | string[];\n  datatype?: string | { base: string };\n  propertyUrl?: string;\n  /** CSVW virtual columns are not backed by a CSV cell. */\n  virtual?: boolean;\n  /** Default value for missing cells. */\n  default?: string;\n  /** Whether null is allowed. */\n  required?: boolean;\n}\n\n/** The `tableSchema` object from a CSVW metadata document. */\nexport interface CsvwTableSchema {\n  columns: CsvwColumn[];\n  primaryKey?: string | string[];\n  /** Foreign keys are parsed but not enforced. */\n  foreignKeys?: unknown[];\n}\n\n/** A trimmed CSVW metadata document (only the fields we use). */\nexport interface CsvwMetadata {\n  url?: string;\n  \"@context\"?: string | unknown[];\n  \"dc:title\"?: string;\n  \"dc:source\"?: string;\n  \"dcat:modified\"?: string;\n  tableSchema: CsvwTableSchema;\n  /**\n   * Extension object: if present, attached to the dataset as `extension`.\n   * CSVW doesn't standardize this; consumers may add `jsonstat:*` keys here.\n   */\n  \"jsonstat:extension\"?: Record<string, unknown>;\n  \"jsonstat:roles\"?: RoleMap;\n  \"jsonstat:valueForm\"?: \"auto\" | \"dense\" | \"sparse\";\n}\n\n// ---------------------------------------------------------------------------\n// Options\n// ---------------------------------------------------------------------------\n\nexport interface CsvwToCubeOptions {\n  /** Explicit measure column name. Overrides schema-based detection. */\n  measure?: string;\n  /** Explicit dimension column names, in order. */\n  dimensions?: string[];\n  /** Explicit status column name. */\n  status?: string;\n  /** Role assignments (merged with, and overriding, metadata hints). */\n  roles?: RoleMap;\n  /** CSV delimiter (default \",\"). */\n  delimiter?: string;\n  /** Treat the CSV's first row as a header (default true). */\n  header?: boolean;\n}\n\n// ---------------------------------------------------------------------------\n// Helpers\n// ---------------------------------------------------------------------------\n\nfunction firstTitle(col: CsvwColumn): string | undefined {\n  if (!col.titles) return undefined;\n  return Array.isArray(col.titles) ? col.titles[0] : col.titles;\n}\n\n/** Is a CSVW datatype numeric? */\nfunction isNumericDatatype(dt: string | { base: string } | undefined): boolean {\n  if (!dt) return false;\n  const base = typeof dt === \"string\" ? dt : dt.base;\n  return (\n    base === \"decimal\" ||\n    base === \"integer\" ||\n    base === \"double\" ||\n    base === \"float\" ||\n    base === \"number\" ||\n    base === \"long\" ||\n    base === \"int\" ||\n    base === \"short\" ||\n    base === \"byte\"\n  );\n}\n\n/** Infer a role from a CSVW propertyUrl. */\nfunction roleFromPropertyUrl(url: string | undefined): \"time\" | \"geo\" | \"metric\" | undefined {\n  if (!url) return undefined;\n  const u = url.toLowerCase();\n  if (u.includes(\"time\") || u.includes(\"date\")) return \"time\";\n  if (u.includes(\"geo\") || u.includes(\"spatial\") || u.includes(\"place\")) return \"geo\";\n  if (u.includes(\"metric\") || u.includes(\"measure\") || u.includes(\"obsvalue\")) return \"metric\";\n  return undefined;\n}\n\n// ---------------------------------------------------------------------------\n// Public API\n// ---------------------------------------------------------------------------\n\n/**\n * Convert CSV text + CSVW metadata into the [`Observations`] IR.\n *\n * @param csvText The raw CSV file content.\n * @param metadata The parsed CSVW metadata document (the `tableSchema` is\n *        required).\n * @throws [`CsvwSourceError`] on structural problems.\n */\nexport function csvwToCube(\n  csvText: string,\n  metadata: CsvwMetadata,\n  options: CsvwToCubeOptions = {},\n): Observations {\n  if (!metadata.tableSchema?.columns?.length) {\n    throw new CsvwSourceError(\"CSVW metadata is missing tableSchema.columns\");\n  }\n\n  const delimiter = options.delimiter ?? \",\";\n  const header = options.header ?? true;\n  const schema = metadata.tableSchema;\n\n  // The CSVW column `name` is the canonical header. If the CSV has its own\n  // header row, we expect it to match the `name`s (or `titles`); if not, we\n  // rely on column position. To be robust, we parse by position and label by\n  // the schema's `name`.\n  const rows = parseCsv(csvText, delimiter);\n  if (rows.length === 0) throw new CsvwSourceError(\"CSV has no rows\");\n\n  let dataRows: string[][];\n  if (header) {\n    dataRows = rows.slice(1);\n  } else {\n    dataRows = rows;\n  }\n  const cols = schema.columns.filter((c) => !c.virtual);\n  const colCount = cols.length;\n  if (dataRows.length === 0) throw new CsvwSourceError(\"CSV has no data rows\");\n\n  // Read each CSVW column into a string array (by position).\n  const columnValues: string[][] = cols.map(() => []);\n  for (const r of dataRows) {\n    for (let c = 0; c < colCount; c++) {\n      const cell = r[c] ?? cols[c].default ?? \"\";\n      columnValues[c].push(cell);\n    }\n  }\n\n  // Resolve measure: explicit > first numeric-datatype column.\n  let measureIdx = cols.findIndex((c) => c.name === options.measure);\n  if (measureIdx === -1) {\n    measureIdx = cols.findIndex((c) => isNumericDatatype(c.datatype));\n    if (measureIdx === -1) {\n      throw new CsvwSourceError(\n        \"No measure column: no column has a numeric datatype. \" +\n          \"Pass options.measure to name one.\",\n      );\n    }\n  }\n\n  // Resolve status: explicit > a column named/propertyUrl'd 'status'.\n  let statusIdx = cols.findIndex((c) => c.name === options.status);\n  if (statusIdx === -1 && !options.status) {\n    statusIdx = cols.findIndex(\n      (c) => c.name.toLowerCase() === \"status\" || roleFromPropertyUrl(c.propertyUrl) === undefined && c.name.toLowerCase() === \"status\",\n    );\n    if (statusIdx === measureIdx) statusIdx = -1;\n  }\n\n  // Resolve dimensions.\n  let dimensionIdxs: number[];\n  if (options.dimensions) {\n    dimensionIdxs = options.dimensions.map((n) => {\n      const idx = cols.findIndex((c) => c.name === n);\n      if (idx === -1) throw new CsvwSourceError(`Dimension column \"${n}\" not in schema`);\n      return idx;\n    });\n  } else {\n    // Prefer primaryKey columns as dimensions, in declared order; fall back to\n    // all non-measure/non-status columns.\n    const pk = schema.primaryKey\n      ? Array.isArray(schema.primaryKey)\n        ? schema.primaryKey\n        : [schema.primaryKey]\n      : [];\n    if (pk.length > 0) {\n      dimensionIdxs = pk.map((n) => {\n        const idx = cols.findIndex((c) => c.name === n);\n        if (idx === -1) throw new CsvwSourceError(`primaryKey column \"${n}\" not in schema`);\n        return idx;\n      });\n      // Append any remaining non-measure/non-status columns not in the PK.\n      for (let i = 0; i < cols.length; i++) {\n        if (i === measureIdx || i === statusIdx || dimensionIdxs.includes(i)) continue;\n        dimensionIdxs.push(i);\n      }\n    } else {\n      dimensionIdxs = cols\n        .map((_, i) => i)\n        .filter((i) => i !== measureIdx && i !== statusIdx);\n    }\n  }\n  if (dimensionIdxs.length === 0) {\n    throw new CsvwSourceError(\"No dimension columns resolved\");\n  }\n\n  // Build dimension columns, pulling labels from `titles`.\n  const dimensions: Record<string, DimensionColumn> = {};\n  for (const idx of dimensionIdxs) {\n    const col = cols[idx];\n    const label = firstTitle(col);\n    dimensions[col.name] = {\n      id: col.name,\n      values: columnValues[idx].map((v) => (v === \"\" ? \"\" : v)),\n      label,\n    };\n  }\n\n  // Measure: parse numerically per the datatype.\n  const measure: MeasureColumn = {\n    name: cols[measureIdx].name,\n    values: columnValues[measureIdx].map((v) => {\n      if (v === \"\") return null;\n      const n = Number(v);\n      return Number.isFinite(n) ? n : null;\n    }),\n  };\n\n  let status: StatusColumn | undefined;\n  if (statusIdx !== -1) {\n    status = { values: columnValues[statusIdx].slice() };\n  }\n\n  // Roles: metadata hints + propertyUrl inference + caller overrides.\n  const roles: RoleMap = {};\n  const addRole = (role: keyof RoleMap, id: string) => {\n    (roles[role] ??= []).push(id);\n  };\n  if (metadata[\"jsonstat:roles\"]) {\n    for (const r of [\"time\", \"geo\", \"metric\"] as const) {\n      for (const id of metadata[\"jsonstat:roles\"][r] ?? []) addRole(r, id);\n    }\n  }\n  for (const idx of dimensionIdxs) {\n    const role = roleFromPropertyUrl(cols[idx].propertyUrl);\n    if (role) addRole(role, cols[idx].name);\n  }\n  // The measure, if it has a metric propertyUrl, records the metric role on\n  // itself (it is not a dimension, so this is informational).\n  if (options.roles) {\n    for (const r of [\"time\", \"geo\", \"metric\"] as const) {\n      for (const id of options.roles[r] ?? []) addRole(r, id);\n    }\n  }\n\n  const observations: Observations = {\n    dimensions,\n    measure,\n    status,\n    model: {\n      dimensionIds: dimensionIdxs.map((i) => cols[i].name),\n      roles: Object.keys(roles).length ? roles : undefined,\n      meta: {\n        label: metadata[\"dc:title\"],\n        source: metadata[\"dc:source\"],\n        updated: metadata[\"dcat:modified\"],\n        extension: metadata[\"jsonstat:extension\"],\n      },\n      valueForm: metadata[\"jsonstat:valueForm\"] ?? \"auto\",\n      statusForm: status ? \"auto\" : \"none\",\n    },\n  };\n\n  return observations;\n}\n\n/** Convenience: CSVW (CSV + metadata) → JSON-stat [`Dataset`]. */\nexport async function csvwToDataset(\n  csvText: string,\n  metadata: CsvwMetadata,\n  options?: CsvwToCubeOptions,\n): Promise<JsonStatDataset> {\n  const { toDataset } = await import(\"../core/cubeBuilder\");\n  return toDataset(csvwToCube(csvText, metadata, options));\n}\n\n/** Parse a CSVW metadata JSON document, validating minimally. */\nexport function parseCsvwMetadata(json: unknown): CsvwMetadata {\n  const m = json as CsvwMetadata;\n  if (!m || !m.tableSchema || !Array.isArray(m.tableSchema.columns)) {\n    throw new CsvwSourceError(\"Invalid CSVW metadata: missing tableSchema.columns\");\n  }\n  return m;\n}\n\n// ---------------------------------------------------------------------------\n// Export: Observations IR → CSVW (CSV text + metadata JSON)\n// ---------------------------------------------------------------------------\n\nexport interface CubeToCsvwOptions {\n  /** CSV delimiter (default \",\"). */\n  delimiter?: string;\n  /** Line terminator: \"\\r\\n\" (default) or \"\\n\". */\n  lineTerminator?: string;\n  /**\n   * The `url` of the CSV file the metadata describes. Required by the CSVW\n   * spec for a stand-alone metadata document; falls back to `\"data.csv\"`.\n   */\n  url?: string;\n}\n\n/** Result of [`cubeToCsvw`]: the CSV body + the CSVW metadata document. */\nexport interface CsvwExport {\n  /** The CSV text (header + rows). */\n  csv: string;\n  /** The CSVW metadata document, ready to `JSON.stringify`. */\n  metadata: CsvwMetadata;\n}\n\n/** JSON-stat role → CSVW `propertyUrl` template fragment. */\nfunction propertyUrlForRole(\n  role: \"time\" | \"geo\" | \"metric\" | undefined,\n): string | undefined {\n  if (role === \"time\") return \"schema:DateTime\";\n  if (role === \"geo\") return \"schema:Place\";\n  if (role === \"metric\") return \"schema:Measure\";\n  return undefined;\n}\n\n/** Look up the role of a dimension id in the IR model. */\nfunction roleOf(\n  obs: Observations,\n  id: string,\n): \"time\" | \"geo\" | \"metric\" | undefined {\n  const roles = obs.model.roles;\n  if (!roles) return undefined;\n  if (roles.time?.includes(id)) return \"time\";\n  if (roles.geo?.includes(id)) return \"geo\";\n  if (roles.metric?.includes(id)) return \"metric\";\n  return undefined;\n}\n\n/**\n * Write the [`Observations`](../model/ir.ts) IR to a CSVW pair: the CSV text\n * (RFC-4180) and a CSVW metadata document declaring the `tableSchema`.\n *\n * The metadata records, per column:\n *  - `name` (the dimension id / measure name / `\"status\"`),\n *  - `titles` (the dimension label, when known),\n *  - `datatype` (`string` for dimensions/status, `decimal` for the measure),\n *  - `propertyUrl` (a role-derived schema.org URL, when a role is assigned).\n *\n * The schema's `primaryKey` is set to all dimension columns — together they\n * uniquely identify an observation. Dataset-level metadata (`label`, `source`,\n * `updated`, `extension`, `roles`, `valueForm`) is emitted as the CSVW\n * `dc:title` / `dc:source` / `dcat:modified` / `jsonstat:*` keys, so the\n * round-trip through [`csvwToCube`] is lossless.\n *\n * @example\n * ```ts\n * import { cubeToCsvw } from \"jsonstat-io/csvw\";\n * const { csv, metadata } = cubeToCsvw(observations);\n * ```\n */\nexport function cubeToCsvw(\n  obs: Observations,\n  options: CubeToCsvwOptions = {},\n): CsvwExport {\n  const { header, rows } = cubeColumns(obs);\n  const csv = serializeRows(header, rows, options);\n\n  const dimIds = obs.model.dimensionIds;\n  const measureName = obs.measure.name ?? \"value\";\n  const hasStatus = obs.status !== undefined;\n  const meta = obs.model.meta;\n\n  const columns: CsvwColumn[] = [];\n\n  for (const id of dimIds) {\n    const col = obs.dimensions[id];\n    const role = roleOf(obs, id);\n    const propUrl = propertyUrlForRole(role);\n    columns.push({\n      name: id,\n      titles: col?.label ?? id,\n      datatype: \"string\",\n      ...(propUrl ? { propertyUrl: propUrl } : {}),\n    });\n  }\n\n  // Measure column: numeric datatype.\n  columns.push({\n    name: measureName,\n    titles: measureName,\n    datatype: \"decimal\",\n    propertyUrl: \"schema:value\",\n    required: false,\n  });\n\n  if (hasStatus) {\n    columns.push({\n      name: \"status\",\n      titles: \"status\",\n      datatype: \"string\",\n    });\n  }\n\n  const metadata: CsvwMetadata = {\n    url: options.url ?? \"data.csv\",\n    \"@context\": [\"http://www.w3.org/ns/csvw\", { \"@language\": \"en\" }],\n    tableSchema: {\n      columns,\n      primaryKey: dimIds.slice(),\n    },\n  };\n\n  if (meta?.label) metadata[\"dc:title\"] = meta.label;\n  if (meta?.source) metadata[\"dc:source\"] = meta.source;\n  if (meta?.updated) metadata[\"dcat:modified\"] = meta.updated;\n  if (meta?.extension) metadata[\"jsonstat:extension\"] = meta.extension;\n  if (obs.model.roles) metadata[\"jsonstat:roles\"] = obs.model.roles;\n  if (obs.model.valueForm) metadata[\"jsonstat:valueForm\"] = obs.model.valueForm;\n\n  return { csv, metadata };\n}\n"]}

package/dist/sources/csvw.d.cts

@@ -0,0 +1,143 @@
+import { R as RoleMap, O as Observations } from '../ir-BArfNxo-.cjs';
+import { J as JsonStatDataset } from '../jsonstat-BX4mBLci.cjs';
+
+/**
+ * CSVW (CSV on the Web) adapter — `jsonstat-io/csvw`.
+ *
+ * **Import:** CSVW pairs a CSV file with a JSON-LD metadata document that
+ * declares a `tableSchema` — column names, types, `titles` (human labels),
+ * `primaryKey`, and property URLs. This metadata enables a **lossless** mapping
+ * straight to the [`Observations`](../model/ir.ts) IR, without the inference
+ * heuristics of plain [`csv`](./csv.ts).
+ *
+ * **Export:** [`cubeToCsvw`] generates both the CSV text and a CSVW metadata
+ * document from the [`Observations`] IR.
+ *
+ * ## Mapping
+ *
+ *  - Columns whose `datatype` is numeric → measure candidates.
+ *  - The measure is the first numeric column, or the one flagged via
+ *    `options.measure`. Other columns are dimensions.
+ *  - `tableSchema.primaryKey` columns are treated as dimensions (and can pin
+ *    the dimension order via `options.dimensions`).
+ *  - `titles` → dimension/category labels; `name` → dimension id.
+ *  - `primaryKey` → dimension id list (used as `dimensionIds` when
+ *    `options.dimensions` is not given).
+ *  - `propertyUrl` containing `time`/`geo`/`metric` → role hints.
+ *
+ * The adapter does not implement the full CSVW spec (foreign keys, URL
+ * templates, cell value transformations); it covers the subset needed to
+ * faithfully round-trip statistical cubes. See [docs/formats/csvw.md](../../docs/formats/csvw.md).
+ */
+
+declare class CsvwSourceError extends Error {
+    constructor(message: string);
+}
+/** A column declaration in a CSVW `tableSchema`. */
+interface CsvwColumn {
+    name: string;
+    titles?: string | string[];
+    datatype?: string | {
+        base: string;
+    };
+    propertyUrl?: string;
+    /** CSVW virtual columns are not backed by a CSV cell. */
+    virtual?: boolean;
+    /** Default value for missing cells. */
+    default?: string;
+    /** Whether null is allowed. */
+    required?: boolean;
+}
+/** The `tableSchema` object from a CSVW metadata document. */
+interface CsvwTableSchema {
+    columns: CsvwColumn[];
+    primaryKey?: string | string[];
+    /** Foreign keys are parsed but not enforced. */
+    foreignKeys?: unknown[];
+}
+/** A trimmed CSVW metadata document (only the fields we use). */
+interface CsvwMetadata {
+    url?: string;
+    "@context"?: string | unknown[];
+    "dc:title"?: string;
+    "dc:source"?: string;
+    "dcat:modified"?: string;
+    tableSchema: CsvwTableSchema;
+    /**
+     * Extension object: if present, attached to the dataset as `extension`.
+     * CSVW doesn't standardize this; consumers may add `jsonstat:*` keys here.
+     */
+    "jsonstat:extension"?: Record<string, unknown>;
+    "jsonstat:roles"?: RoleMap;
+    "jsonstat:valueForm"?: "auto" | "dense" | "sparse";
+}
+interface CsvwToCubeOptions {
+    /** Explicit measure column name. Overrides schema-based detection. */
+    measure?: string;
+    /** Explicit dimension column names, in order. */
+    dimensions?: string[];
+    /** Explicit status column name. */
+    status?: string;
+    /** Role assignments (merged with, and overriding, metadata hints). */
+    roles?: RoleMap;
+    /** CSV delimiter (default ","). */
+    delimiter?: string;
+    /** Treat the CSV's first row as a header (default true). */
+    header?: boolean;
+}
+/**
+ * Convert CSV text + CSVW metadata into the [`Observations`] IR.
+ *
+ * @param csvText The raw CSV file content.
+ * @param metadata The parsed CSVW metadata document (the `tableSchema` is
+ *        required).
+ * @throws [`CsvwSourceError`] on structural problems.
+ */
+declare function csvwToCube(csvText: string, metadata: CsvwMetadata, options?: CsvwToCubeOptions): Observations;
+/** Convenience: CSVW (CSV + metadata) → JSON-stat [`Dataset`]. */
+declare function csvwToDataset(csvText: string, metadata: CsvwMetadata, options?: CsvwToCubeOptions): Promise<JsonStatDataset>;
+/** Parse a CSVW metadata JSON document, validating minimally. */
+declare function parseCsvwMetadata(json: unknown): CsvwMetadata;
+interface CubeToCsvwOptions {
+    /** CSV delimiter (default ","). */
+    delimiter?: string;
+    /** Line terminator: "\r\n" (default) or "\n". */
+    lineTerminator?: string;
+    /**
+     * The `url` of the CSV file the metadata describes. Required by the CSVW
+     * spec for a stand-alone metadata document; falls back to `"data.csv"`.
+     */
+    url?: string;
+}
+/** Result of [`cubeToCsvw`]: the CSV body + the CSVW metadata document. */
+interface CsvwExport {
+    /** The CSV text (header + rows). */
+    csv: string;
+    /** The CSVW metadata document, ready to `JSON.stringify`. */
+    metadata: CsvwMetadata;
+}
+/**
+ * Write the [`Observations`](../model/ir.ts) IR to a CSVW pair: the CSV text
+ * (RFC-4180) and a CSVW metadata document declaring the `tableSchema`.
+ *
+ * The metadata records, per column:
+ *  - `name` (the dimension id / measure name / `"status"`),
+ *  - `titles` (the dimension label, when known),
+ *  - `datatype` (`string` for dimensions/status, `decimal` for the measure),
+ *  - `propertyUrl` (a role-derived schema.org URL, when a role is assigned).
+ *
+ * The schema's `primaryKey` is set to all dimension columns — together they
+ * uniquely identify an observation. Dataset-level metadata (`label`, `source`,
+ * `updated`, `extension`, `roles`, `valueForm`) is emitted as the CSVW
+ * `dc:title` / `dc:source` / `dcat:modified` / `jsonstat:*` keys, so the
+ * round-trip through [`csvwToCube`] is lossless.
+ *
+ * @example
+ * ```ts
+ * import { cubeToCsvw } from "jsonstat-io/csvw";
+ * const { csv, metadata } = cubeToCsvw(observations);
+ * ```
+ */
+declare function cubeToCsvw(obs: Observations, options?: CubeToCsvwOptions): CsvwExport;
+
+export { type CsvwColumn, type CsvwExport, type CsvwMetadata, CsvwSourceError, type CsvwTableSchema, type CsvwToCubeOptions, type CubeToCsvwOptions, csvwToCube, csvwToDataset, cubeToCsvw, parseCsvwMetadata };