Files

T

hypercross c969c7f6fc refactor: enforce mandatory brackets for composite values

Implements Phase 1 and 2 of the syntax rework plan:
- Brackets `[]` are now mandatory for all tuple and array values.
- Removed the `[Type][]` array syntax; arrays now only use `Type[]`.
- `[single]` is now strictly a 1-tuple rather than an array.
- Updated documentation and test fixtures to reflect these breaking
  changes.

2026-08-06 09:19:39 +08:00

3.7 KiB

Raw Blame History

typed-csv/csv-loader

A bundler loader (rspack/webpack/rollup/esbuild) for CSV files that uses typed-csv for type validation and cross-table reference resolution.

Installation

npm install typed-csv

Usage

The loader expects:

First row: Property names (headers)
Second row: typed-csv schema definitions for each property
Remaining rows: Data values

Example CSV

name,age,active,scores
string,number,boolean,number[]
Alice,30,true,[90; 85; 95]
Bob,25,false,[75; 80; 70]

rspack/webpack

rspack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.schema\.csv$/,
        use: {
          loader: 'typed-csv/csv-loader',
          options: {
            delimiter: ',',
            quote: '"',
            escape: '\\',
            bom: true,        // 处理 BOM (默认 true)
            comment: '#',     // 忽略 # 开头的注释行 (默认 '#')
            trim: true,       // 修剪表头和值的前后空格 (默认 true)
            // emitTypes: false, // 禁用类型定义生成 (默认 true)
            // typesOutputDir: 'types', // 类型文件输出目录 (可选)
            // writeToDisk: true, // 在 dev server 下写入磁盘 (默认 false)
          },
        },
      },
    ],
  },
};

Vite

vite.config.ts

import { defineConfig } from 'vite';
import { csvLoader } from 'typed-csv/csv-loader/rollup';

export default defineConfig({
  plugins: [
    csvLoader({
      delimiter: ',',
      quote: '"',
      escape: '\\',
      bom: true,
      comment: '#',
      trim: true,
      // emitTypes: false,
      // typesOutputDir: 'types',
      // writeToDisk: true,
    }),
  ],
});

Tsup

tsup.config.ts

import { defineConfig } from 'tsup';
import { csvLoader } from 'typed-csv/csv-loader/rollup';

export default defineConfig({
  entry: ['src/index.ts'],
  format: ['cjs', 'esm'],
  dts: true,
  plugins: [csvLoader()],
});

Generated TypeScript Types

当 emitTypes: true 时，loader 会自动生成 .d.ts 类型定义文件：

// data.csv.d.ts
type Table = {
  name: string;
  age: number;
  active: boolean;
  scores: number[];
}[];

declare const data: Table;
export default data;

Importing in TypeScript

import data from './data.csv';

// TypeScript 会自动推断类型:
// data: { name: string; age: number; active: boolean; scores: number[] }[]

Options

Option	Type	Default	Description
`delimiter`	string	`,`	Column delimiter
`quote`	string	`"`	Quote character
`escape`	string	`\`	Escape character
`bom`	boolean	`true`	Handle byte order mark
`comment`	string \| `false`	`#`	Comment character (set `false` to disable)
`trim`	boolean	`true`	Trim headers and values
`emitTypes`	boolean	`true`	Generate TypeScript declaration file (.d.ts)
`typesOutputDir`	string	`''`	Output directory for generated type files (relative to output path)
`writeToDisk`	boolean	`false`	Write .d.ts files directly to disk (useful for dev server)
`include`	RegExp \| string \| Array	`/\.csv$/`	Include pattern for CSV files (Rollup only)
`exclude`	RegExp \| string \| Array	-	Exclude pattern for CSV files (Rollup only)

Schema Syntax

Uses typed-csv syntax:

Type	Schema	Example
String	`string`	`hello`
Number	`number`	`42`
Boolean	`boolean`	`true`
Array	`string[]`	`[a; b; c]`
Tuple	`[string; number]`	`[hello; 42]`

License

ISC

3.7 KiB Raw Blame History