hypercross
641af7341a
Implement a reverse lookup cache to avoid re-filtering the entire referenced table for every row during reverse reference resolution. This improves performance from O(N*M) to O(N+M) where N is the number of rows in the current table and M is the number of rows in the referenced table. Also update documentation to reflect the new union resolution behavior and migration notes for version 2.0.0.
165 lines
4.2 KiB
Markdown
165 lines
4.2 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
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
|
|
|
|
```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
|
|
|
|
```javascript
|
|
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
|
|
|
|
```typescript
|
|
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
|
|
|
|
```typescript
|
|
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` 类型定义文件：
|
|
|
|
```typescript
|
|
// data.csv.d.ts
|
|
type Table = {
|
|
name: string;
|
|
age: number;
|
|
active: boolean;
|
|
scores: number[];
|
|
}[];
|
|
|
|
declare const data: Table;
|
|
export default data;
|
|
```
|
|
|
|
### Importing in TypeScript
|
|
|
|
```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](https://github.com/your-repo/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]` |
|
|
|
|
> **Note:** `int` and `float` are accepted in schemas and validated at parse time, but both collapse to `number` in generated type declarations.
|
|
|
|
## Migration from 1.x
|
|
|
|
- Composite values must be fully bracketed: `[[a; 1]; [b; 2]]`, not `[a; 1]; [b; 2]`.
|
|
- The `[Type][]` array form is removed — use `Type[]`.
|
|
- `[single]` is a 1-tuple, not an array.
|
|
- In unions containing references, reference members are tried first.
|
|
- Double-quoted string literals (`"active" | "inactive"`) in a schema row are handled automatically.
|
|
|
|
## License
|
|
|
|
ISC
|