typed-csv 1.0.0

package/README.md

@@ -0,0 +1,190 @@
+# typed-csv
+
+A TypeScript library for typed CSV data with inline schema validation using a TypeScript-like syntax with `;` instead of `,`.
+
+## Installation
+
+```bash
+npm install typed-csv
+```
+
+## Usage
+
+### Basic Example
+
+```typescript
+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
+
+```typescript
+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
+
+```typescript
+// 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
+
+```typescript
+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:
+
+```typescript
+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:
+
+```typescript
+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](./csv-loader.md)
+
+```javascript
+// rspack.config.js
+module.exports = {
+  module: {
+    rules: [
+      {
+        test: /\.schema\.csv$/,
+        use: 'typed-csv/csv-loader',
+      },
+    ],
+  },
+};
+```
+
+## License
+
+ISC

package/dist/csv-loader/esbuild.d.mts

@@ -0,0 +1,45 @@
+import { Plugin } from 'esbuild';
+
+interface CsvLoaderOptions {
+    delimiter?: string;
+    quote?: string;
+    escape?: string;
+    bom?: boolean;
+    comment?: string | false;
+    trim?: boolean;
+    /** Generate TypeScript declaration file (.d.ts) */
+    emitTypes?: boolean;
+    /** Output directory for generated type files (relative to output path) */
+    typesOutputDir?: string;
+    /** Write .d.ts files to disk (useful for dev server) */
+    writeToDisk?: boolean;
+    /** Base directory for resolving referenced CSV files (default: directory of current file) */
+    refBaseDir?: string;
+    /** Primary key field name for referenced tables (default: 'id') */
+    defaultPrimaryKey?: string;
+    /** Current file path (used to resolve relative references) */
+    currentFilePath?: string;
+    /**
+     * When false, reference fields store parsed IDs instead of resolved objects.
+     * Used by csvToModule to emit accessor-based code with lazy resolution.
+     * Default: true (resolves references eagerly by loading referenced CSV files).
+     */
+    resolveReferences?: boolean;
+}
+
+interface CsvEsbuildOptions extends CsvLoaderOptions {
+    /** Include pattern for CSV files (default: /\.csv$/) */
+    include?: RegExp | string | Array<RegExp | string>;
+    /** Exclude pattern for CSV files */
+    exclude?: RegExp | string | Array<RegExp | string>;
+    /** Base directory for resolving referenced CSV files (default: directory of current file) */
+    refBaseDir?: string;
+    /** Primary key field name for referenced tables (default: 'id') */
+    defaultPrimaryKey?: string;
+}
+/**
+ * Esbuild plugin for loading CSV files with typed-csv validation.
+ */
+declare function csvLoader(options?: CsvEsbuildOptions): Plugin;
+
+export { type CsvEsbuildOptions, csvLoader, csvLoader as default };

package/dist/csv-loader/esbuild.d.ts

@@ -0,0 +1,45 @@
+import { Plugin } from 'esbuild';
+
+interface CsvLoaderOptions {
+    delimiter?: string;
+    quote?: string;
+    escape?: string;
+    bom?: boolean;
+    comment?: string | false;
+    trim?: boolean;
+    /** Generate TypeScript declaration file (.d.ts) */
+    emitTypes?: boolean;
+    /** Output directory for generated type files (relative to output path) */
+    typesOutputDir?: string;
+    /** Write .d.ts files to disk (useful for dev server) */
+    writeToDisk?: boolean;
+    /** Base directory for resolving referenced CSV files (default: directory of current file) */
+    refBaseDir?: string;
+    /** Primary key field name for referenced tables (default: 'id') */
+    defaultPrimaryKey?: string;
+    /** Current file path (used to resolve relative references) */
+    currentFilePath?: string;
+    /**
+     * When false, reference fields store parsed IDs instead of resolved objects.
+     * Used by csvToModule to emit accessor-based code with lazy resolution.
+     * Default: true (resolves references eagerly by loading referenced CSV files).
+     */
+    resolveReferences?: boolean;
+}
+
+interface CsvEsbuildOptions extends CsvLoaderOptions {
+    /** Include pattern for CSV files (default: /\.csv$/) */
+    include?: RegExp | string | Array<RegExp | string>;
+    /** Exclude pattern for CSV files */
+    exclude?: RegExp | string | Array<RegExp | string>;
+    /** Base directory for resolving referenced CSV files (default: directory of current file) */
+    refBaseDir?: string;
+    /** Primary key field name for referenced tables (default: 'id') */
+    defaultPrimaryKey?: string;
+}
+/**
+ * Esbuild plugin for loading CSV files with typed-csv validation.
+ */
+declare function csvLoader(options?: CsvEsbuildOptions): Plugin;
+
+export { type CsvEsbuildOptions, csvLoader, csvLoader as default };