IncCSV.js

A JavaScript implementation of the INC file format.

INC files are ordinary CSV files with an optional, lightweight metadata block at the top. This package parses and writes INC text in browsers and Node.js. Node file helpers are available from the inccsv/fs export.

Package name: inccsv.

See also the Julia implementation IncCSV.jl and the Python implementation IncCSV.py.

Documentation

Static documentation and browser demos live in docs/:

• Overview: API quick reference and INC file anatomy.
• Playground: parse, inspect, and write INC text.
• Schema demo: validate metadata with an INC mini-schema.
• Examples: rendered examples for common INC patterns.
• Shiny: use the browser bundle from an R Shiny app.

Run the local docs server from this package directory:

npm run docs

Then open http://127.0.0.1:4173/docs/.

Installation

After publication to npm:

npm install inccsv

Usage

import { parseInc, writeInc } from "inccsv";

const file = parseInc(`---
title = Sensor readings
[columns]
temperature = Celsius
---
time,temperature
0,21.4
1,21.8
`);

console.log(file.metadata.title);
console.log(file.rows);

const text = writeInc({
  metadata: file.metadata,
  columns: file.columns,
  rows: file.rows,
});

When metadata includes writer-relevant [structure] values, writeInc uses them for the CSV component:

const tsv = writeInc({
  metadata: { structure: { delimiter: "tab" } },
  columns: ["time", "temperature"],
  rows: [[0, 21.4]],
});

If explicit csvOptions contradict [structure] metadata, writeInc throws rather than producing a file whose metadata describes a different CSV format.

For Node file I/O:

import { readInc, writeIncFile } from "inccsv/fs";

const file = await readInc("data.inc");
await writeIncFile("copy.inc", file);

Browser Bundle And Shiny

Build a browser-ready global bundle with:

npm run build

This writes:

dist/inccsv.browser.js
dist/inccsv.browser.min.js

Both expose the package as window.IncCSV. A complete R Shiny example is included in examples/shiny/. The build script also copies the browser bundle into examples/shiny/www/ so the app can serve it as a normal Shiny asset:

cd examples/shiny
R -e 'shiny::runApp(".")'

Current Scope

• INC and plain CSV reading.
• Metadata parsing with sections, integer/string values, quoting, and comments.
• [structure] support for delimiter, quote character, escape character, comment marker, header, and footerskip.
• INC writing with deterministic metadata ordering and structure-aware CSV output.
• Mini-schema reading and validation.
• Shared conformance tests for the INC specification fixtures.

This package is intentionally small and dependency-free. It is suitable for lightweight browser and Node workflows; applications with highly specialized CSV requirements may still prefer to adapt the parser boundary to their CSV library of choice.

INC follows a bounded version of Postel's law. Writers emit conservative, canonical INC, while readers accept documented compatible variants such as plain CSV passthrough and portable aliases. Malformed or ambiguous metadata is rejected rather than guessed.

Development

npm test

The test harness reads fixtures from ../INCspec.

Before publishing a release, run:

npm run release:check

Release notes and the publishing checklist are maintained in CHANGELOG.md and RELEASE.md.

Disclosure

This package was developed with assistance from OpenAI Codex, an AI coding assistant based on GPT-5. Code design decisions were human mediated, and the resulting code was manually reviewed.