typed-csv

A TypeScript library for typed CSV data with inline schema validation using a TypeScript-like syntax with ; instead of ,.

Installation

npm install typed-csv

Usage

Basic Example

import { defineSchema } from 'typed-csv';

// Define a schema
const stringSchema = defineSchema('string');
const numberSchema = defineSchema('number');
const booleanSchema = defineSchema('boolean');

// Parse values
const name = stringSchema.parse('hello');        // "hello"
const age = numberSchema.parse('42');            // 42
const active = booleanSchema.parse('true');      // true

// Validate parsed values
stringSchema.validator(name);    // true
numberSchema.validator(name);    // false

Tuples

const tupleSchema = defineSchema('[string; number; boolean]');

// With brackets
const value1 = tupleSchema.parse('[hello; 42; true]');
// ["hello", 42, true]

// Without brackets (outermost brackets are optional)
const value2 = tupleSchema.parse('hello; 42; true');
// ["hello", 42, true]

tupleSchema.validator(value1);    // true
tupleSchema.validator(['a', 'b', true]);  // false (second element should be number)

Arrays

// Array syntax: Type[] or [Type][]
const stringArray = defineSchema('string[]');
const numberArray = defineSchema('[number][]');

// With brackets
const names1 = stringArray.parse('[alice; bob; charlie]');
// ["alice", "bob", "charlie"]

// Without brackets (outermost brackets are optional)
const names2 = stringArray.parse('alice; bob; charlie');
// ["alice", "bob", "charlie"]

const numbers = numberArray.parse('[1; 2; 3; 4; 5]');
// [1, 2, 3, 4, 5]

Array of Tuples

const schema = defineSchema('[string; number][]');

// With outer brackets
const data1 = schema.parse('[[a; 1]; [b; 2]; [c; 3]]');
// [["a", 1], ["b", 2], ["c", 3]]

// Without outer brackets
const data2 = schema.parse('[a; 1]; [b; 2]; [c; 3]');
// [["a", 1], ["b", 2], ["c", 3]]

Escaping Special Characters

Use \ to escape special characters ;, [, ], and \ in string values:

const schema = defineSchema('string');

const value1 = schema.parse('hello\\;world');    // "hello;world"
const value2 = schema.parse('hello\\[world');    // "hello[world"
const value3 = schema.parse('hello\\\\world');   // "hello\\world"

// In tuples
const tupleSchema = defineSchema('[string; string]');
const tuple = tupleSchema.parse('hello\\;world; test');
// ["hello;world", "test"]

String Identifiers

Any identifier (including hyphens) is treated as a string schema:

const schema = defineSchema('word-smith');
const value = schema.parse('word-smith');
// "word-smith"

API

defineSchema(schemaString: string): ParsedSchema

Parses a schema string and returns an object with:

• schema: The parsed schema AST
• validator: A function to validate values against the schema
• parse: A function to parse value strings

parseSchema(schemaString: string): Schema

Parses a schema string and returns the schema AST.

parseValue(schema: Schema, valueString: string): unknown

Parses a value string according to the given schema.

createValidator(schema: Schema): (value: unknown) => boolean

Creates a validation function for the given schema.

schemaToTypeString(schema: Schema): string

Converts a schema AST back to a human-readable type string.

ParseError

Error class thrown for invalid schema syntax.

Types

The following TypeScript types are exported:

• Schema — union of all schema AST node types
• ParsedSchema — the return type of defineSchema()
• PrimitiveSchema, TupleSchema, ArraySchema — AST node types
• ReferenceSchema, ReverseReferenceSchema — reference AST node types
• StringLiteralSchema, UnionSchema — literal and union AST node types

Schema Syntax

Type	Schema	Example Value
String	string or identifier	hello
Int	int	42
Float	float	3.14
Number	number	42 or 3.14
Boolean	boolean	true or false
Tuple	[Type1; Type2; ...]	[hello; 42; true] or hello; 42; true
Array	Type[] or [Type][]	[1; 2; 3] or 1; 2; 3
Array of Tuples	[Type1; Type2][]	[[a; 1]; [b; 2]] or [a; 1]; [b; 2]
Union	Type1 | Type2	hello or 42 (matches first valid member)
String Literal	'on' | 'off' or "red"	on or off
Reference	@tablename or @tablename[]	(resolved at CSV load time)
Reverse Reference	~tablename(fk)	(resolved at CSV load time)

Notes

• Semicolons ; are used as separators instead of commas ,
• Outermost brackets [] are optional for tuple and array values
• Special characters can be escaped with backslash: \;, \[, \], \\
• Empty arrays/tuples are not allowed
• For CSV loading with reference resolution, see csv-loader.md

// rspack.config.js
module.exports = {
  module: {
    rules: [
      {
        test: /\.schema\.csv$/,
        use: 'typed-csv/csv-loader',
      },
    ],
  },
};

License

ISC