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