From e29a16b5d380ef67229112018584b3f0ed1d22ff Mon Sep 17 00:00:00 2001 From: Vitaly Budovski Date: Sun, 22 Dec 2024 14:47:46 +1100 Subject: [PATCH] feature: Add README to package --- README.md | 52 +------------------------------------------- paseri-lib/README.md | 51 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 52 insertions(+), 51 deletions(-) mode change 100644 => 120000 README.md create mode 100644 paseri-lib/README.md diff --git a/README.md b/README.md deleted file mode 100644 index 513f8b3..0000000 --- a/README.md +++ /dev/null @@ -1,51 +0,0 @@ -[![Release](https://github.com/vbudovski/paseri/actions/workflows/release.yml/badge.svg)](https://github.com/vbudovski/paseri/actions/workflows/release.yml) -[![Coverage](https://gist.githubusercontent.com/vbudovski/80548a1b87f9f00fe1ae426ca6a2a517/raw/vbudovski_paseri_main-coverage.svg)](https://github.com/vbudovski/paseri/actions/workflows/release.yml) - ---- - -# Paseri - -A TypeScript parsing, and validation library for structured data. Ensure that untrusted input from users or external -APIs conforms to the expected format. - -Why the name? It's the Japanese name for parsley (パセリ), and also a play on words on parse/parsing, which is the goal -of this library. - -## Acknowledgements - -### Zod - -This library wouldn't exist without [Zod](https://github.com/colinhacks/zod) as a source of inspiration, with its incredibly expressive, and -straightforward API. Zod is an excellent, and very mature library, and if the highest possible performance isn't a key -requirement, then it is a great choice. - -### Valita - -It sets an incredibly high bar for parsing performance, and is the current benchmark for this implementation. Some of -the goals of this library differ from the goals of [Valita](https://github.com/badrap/valita), but it is nonetheless an excellent project. - -## Goals - -The list may be expanded in time, but for now the objectives are the following: - -* Parsing and validation of untrusted input to ensure it conforms to the expected format. A successful result will - be typed with the narrowest possible definition to obviate the need to do additional validation at the point of - usage[^1]. -* High performance[^2], and usability in a strict - [Content Security Policy (CSP)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP) environment. -* An API that is *reasonably* close to that of Zod. One-to-one compatibility is not the intention. -* Immutability of schemas. This avoids a lot of bugs caused by mutating references to non-primitive types. - -## Documentation - -https://paseri.dev - ---- - -[^1]: An [excellent article](https://lexi-lambda.github.io/blog/2019/11/05/parse-don-t-validate/) on the concept of -type-driven design. - -[^2]: It's certainly possible to create much faster parsers using dynamic code execution or ahead-of-time compilation, -but they each have drawbacks in the form of potential -[security issues](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/eval#never_use_direct_eval!) -or added complexity from requiring a manual compilation step. diff --git a/README.md b/README.md new file mode 120000 index 0000000..ac251f3 --- /dev/null +++ b/README.md @@ -0,0 +1 @@ +paseri-lib/README.md \ No newline at end of file diff --git a/paseri-lib/README.md b/paseri-lib/README.md new file mode 100644 index 0000000..513f8b3 --- /dev/null +++ b/paseri-lib/README.md @@ -0,0 +1,51 @@ +[![Release](https://github.com/vbudovski/paseri/actions/workflows/release.yml/badge.svg)](https://github.com/vbudovski/paseri/actions/workflows/release.yml) +[![Coverage](https://gist.githubusercontent.com/vbudovski/80548a1b87f9f00fe1ae426ca6a2a517/raw/vbudovski_paseri_main-coverage.svg)](https://github.com/vbudovski/paseri/actions/workflows/release.yml) + +--- + +# Paseri + +A TypeScript parsing, and validation library for structured data. Ensure that untrusted input from users or external +APIs conforms to the expected format. + +Why the name? It's the Japanese name for parsley (パセリ), and also a play on words on parse/parsing, which is the goal +of this library. + +## Acknowledgements + +### Zod + +This library wouldn't exist without [Zod](https://github.com/colinhacks/zod) as a source of inspiration, with its incredibly expressive, and +straightforward API. Zod is an excellent, and very mature library, and if the highest possible performance isn't a key +requirement, then it is a great choice. + +### Valita + +It sets an incredibly high bar for parsing performance, and is the current benchmark for this implementation. Some of +the goals of this library differ from the goals of [Valita](https://github.com/badrap/valita), but it is nonetheless an excellent project. + +## Goals + +The list may be expanded in time, but for now the objectives are the following: + +* Parsing and validation of untrusted input to ensure it conforms to the expected format. A successful result will + be typed with the narrowest possible definition to obviate the need to do additional validation at the point of + usage[^1]. +* High performance[^2], and usability in a strict + [Content Security Policy (CSP)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP) environment. +* An API that is *reasonably* close to that of Zod. One-to-one compatibility is not the intention. +* Immutability of schemas. This avoids a lot of bugs caused by mutating references to non-primitive types. + +## Documentation + +https://paseri.dev + +--- + +[^1]: An [excellent article](https://lexi-lambda.github.io/blog/2019/11/05/parse-don-t-validate/) on the concept of +type-driven design. + +[^2]: It's certainly possible to create much faster parsers using dynamic code execution or ahead-of-time compilation, +but they each have drawbacks in the form of potential +[security issues](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/eval#never_use_direct_eval!) +or added complexity from requiring a manual compilation step.