158 lines
4.2 KiB
Markdown
158 lines
4.2 KiB
Markdown
# Parsec
|
|
|
|
A tiny (<1kb gzipped) library for parsing and validating data in TypeScript.
|
|
|
|
For more comprehensive type modeling, consider [zod](https://zod.dev)
|
|
|
|
## Install
|
|
|
|
Configure your environment to be aware of @endeavorance packages:
|
|
|
|
```toml
|
|
# Bunfig.toml
|
|
[install.scopes]
|
|
endeavorance = "https://git.astral.camp/api/packages/endeavorance/npm/"
|
|
```
|
|
|
|
Then install the package:
|
|
|
|
```sh
|
|
bun add @endeavorance/parsec
|
|
```
|
|
|
|
## API
|
|
|
|
Parsec exports the `Parse` constant which contains a set of functions for
|
|
parsing and validating data.
|
|
|
|
### Primitives
|
|
|
|
These functions can be invoked directly, passing in the value to parse.
|
|
|
|
- `Parse.unknown(value: unknown): unknown`
|
|
- `Parse.string(value: unknown): string`
|
|
- `Parse.number(value: unknown): number`
|
|
- `Parse.boolean(value: unknown): boolean`
|
|
- `Parse.null(value: unknown): null`
|
|
- `Parse.undefined(value: unknown): undefined`
|
|
- `Parse.bigint(value: unknown): bigint`
|
|
- `Parse.symbol(value: unknown): symbol`
|
|
|
|
|
|
```ts
|
|
const num = Parse.number(42);
|
|
const str = Parse.string("hello");
|
|
const wontParse = Parse.number("hello"); // throws ParseError
|
|
```
|
|
### Primitive Values
|
|
|
|
These functions can be invoked directly and parse primitive values with
|
|
additional constraints or specific meaning.
|
|
|
|
- `Parse.int(value: unknown): number`
|
|
- `Parse.nan(value: unknown): number`
|
|
|
|
```ts
|
|
const anInteger = Parse.int(42);
|
|
const willThrow = Parse.int(42.5); // throws ParseError
|
|
|
|
const itsNan = Parse.nan(NaN);
|
|
const itsNotNan = Parse.nan(42); // throws ParseError
|
|
```
|
|
|
|
### Parser Creators
|
|
|
|
These functions return a new parser function that can be used to parse values.
|
|
|
|
These functions each take an optional second parameter: a human-readable string
|
|
identifying the shape that this parser is for. This is useful for debugging but is not
|
|
required and will default to an generic version of the parser.
|
|
|
|
- `Parse.arrayOf<T>(parser: Parser<T>): (val: unknown) => T[]`
|
|
- `Parse.shape<T>(shape: T): (val: unknown) => T`
|
|
- `Parse.enum<E extends string>(values: readonly E[]): (val: unknown) => E`
|
|
- `Parse.regex(regex: RegExp): (val: unknown) => string`
|
|
- `Parse.literal(literal: unknown): (val: unknown) => literal`
|
|
- `Parse.instanceOf<T>(classDef: Class): (val: unknown) => T`
|
|
|
|
```ts
|
|
// An array of strings
|
|
const arrayOfStrings = Parse.arrayOf(Parse.string)(["hello", "world"]);
|
|
|
|
// A defined object shape
|
|
const personParser = Parse.shape({
|
|
name: Parse.string,
|
|
age: Parse.number,
|
|
isCool: Parse.boolean,
|
|
}, "Person");
|
|
|
|
const person = personParser({
|
|
name: "Alice",
|
|
age: 42,
|
|
isCool: true,
|
|
});
|
|
|
|
// An element of an enum
|
|
const MOODS = ["happy", "sad", "angry"] as const;
|
|
const moodParser = Parse.enum(MOODS);
|
|
const mood = moodParser("happy");
|
|
|
|
// A string that matches a regex
|
|
const allCaps = Parse.regex(/^[A-Z]+$/)("HELLO");
|
|
|
|
// A literal value
|
|
const parseHello = Parse.literal("hello");
|
|
const parsedHello = parseHello("hello");
|
|
const wontWork = parseHello("world"); // throws ParseError
|
|
|
|
// An instance
|
|
const parseDate = Parse.instanceOf(Date)(new Date());
|
|
```
|
|
### Modifiers
|
|
|
|
Use `Parse.nullable()` and `Parse.optional()` to wrap parsers to allow for `null` or `undefined` respectively:
|
|
|
|
```ts
|
|
const numberOrNull = Parse.nullable(Parse.number);
|
|
const optionalArrayOfStrings = Parse.optional(Parse.arrayOf(Parse.string)));
|
|
```
|
|
|
|
### Extracting Types from Parsers
|
|
|
|
When composing parsers to create more complex types, you can use the `ReturnType`
|
|
type helper:
|
|
|
|
```ts
|
|
const parsePerson = Parse.shape({
|
|
name: Parse.string,
|
|
age: Parse.number,
|
|
isCool: Parse.boolean,
|
|
});
|
|
|
|
type Person = ReturnType<typeof parsePerson>;
|
|
```
|
|
## Errors
|
|
|
|
Parsec will throw `ParseError` errors when parsing fails.
|
|
|
|
`ParseError` objects have a string `shape` property which contains the
|
|
expected type of the value.
|
|
|
|
## Branding
|
|
|
|
Parsec exports a helper type, `Brand<T, B>` which brands type T with the
|
|
label provided in B. This is useful for creating custom types that are
|
|
primitive types under the hood but have a different name.
|
|
|
|
```ts
|
|
import type { Brand } from "@endeavorance/parsec";
|
|
type NegativeInteger = Brand<number, "NegativeInteger">;
|
|
function parseInteger(val: unknown): Integer {
|
|
if (typeof val !== "number" || !Number.isInteger(val) || val > 0) {
|
|
throw new ParseTypeMismatch("Integer", val);
|
|
}
|
|
|
|
return val as NegativeInteger;
|
|
}
|
|
```
|