170 lines
4.2 KiB
Markdown
170 lines
4.2 KiB
Markdown
# inline-schema
|
|
|
|
A TypeScript library for parsing and validating inline schemas with a TypeScript-like syntax using `;` instead of `,`.
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
npm install inline-schema
|
|
```
|
|
|
|
## Usage
|
|
|
|
### Basic Example
|
|
|
|
```typescript
|
|
import { defineSchema } from 'inline-schema';
|
|
|
|
// 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.
|
|
|
|
## Schema Syntax
|
|
|
|
| Type | Schema | Example Value |
|
|
|------|--------|---------------|
|
|
| String | `string` or `identifier` | `hello` |
|
|
| Number | `number` | `42` |
|
|
| 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]` |
|
|
|
|
## 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
|
|
|
|
## CSV Loader
|
|
|
|
For loading CSV files with schema validation in rspack, see [csv-loader.md](./csv-loader.md).
|
|
|
|
```javascript
|
|
// rspack.config.js
|
|
module.exports = {
|
|
module: {
|
|
rules: [
|
|
{
|
|
test: /\.schema\.csv$/,
|
|
use: 'inline-schema/csv-loader',
|
|
},
|
|
],
|
|
},
|
|
};
|
|
```
|
|
|
|
## License
|
|
|
|
ISC
|