@arrirpc/schema 0.69.2 → 0.71.0

package/README.md

@@ -2,13 +2,15 @@
 
 A type builder and validation library for [Arri Type Definitions](/specifications/arri_type_definition.md). A lot of inspiration was taken from both [Typebox](https://github.com/sinclairzx81/typebox) and [Zod](https://github.com/colinhacks/zod) when designing this library.
 
+This library also supports [standard-schema](https://github.com/standard-schema/standard-schema) meaning it can be used with any third-party library that accepts standard schema.
+
 ## Project Philosophy
 
 The goals of this project are as follows:
 
--   Portable type definitions
--   High performance validation, parsing, and serialization
--   Consistent error reporting for parsing and serialization errors
+- Portable type definitions
+- High performance validation, parsing, and serialization
+- Consistent error reporting for parsing and serialization errors
 
 I am not looking to support every feature of Typescript's type system or even every possible representation of JSON. The goal is that the data models defined through this library can be used as a source of truth across multiple programming languages. Both JSON and Typescript have to be limited to accomplish this.
 
@@ -16,42 +18,42 @@ I am not looking to support every feature of Typescript's type system or even ev
 
 Originally this library was created as a way for building schemas for [Json Type Definition](https://jsontypedef.com/). However over time parts of the internal schema were modified to better suite the goals of Arri RPC. Some of these modifications include:
 
--   Adding support for 64-bit integers
--   Replacing the `additionalProperties` field with `strict` to allow for additional properties by default.
--   Restrict `ref` to only be used for recursive references.
+- Adding support for 64-bit integers
+- Replacing the `additionalProperties` field with `strict` to allow for additional properties by default.
+- Restrict `ref` to only be used for recursive references.
 
 ## Table of Contents
 
--   [Installation](#installation)
--   [Basic Example](#basic-example)
--   [Usage With @arrirpc/server](#usage-with-arrirpcserver)
--   [Supported Types](#supported-types)
-    -   [Primitives](#primitives)
-    -   [Enums](#enums)
-    -   [Arrays / Lists](#arrays--lists)
-    -   [Objects](#objects)
-    -   [Records / Maps](#records--maps)
-    -   [Discriminated Unions](#discriminated-unions)
-    -   [Recursive Types](#recursive-types)
--   [Modifiers](#modifiers)
-    -   [Optional](#optional)
-    -   [Nullable](#nullable)
-    -   [Extend](#extend)
-    -   [Omit](#omit)
-    -   [Pick](#pick)
-    -   [Partial](#partial)
--   [Utilities](#utilities)
-    -   [Validate](#validate)
-    -   [Parse](#parse)
-    -   [Safe Parse](#safe-parse)
-    -   [Coerce](#coerce)
-    -   [Safe Coerce](#safe-coerce)
-    -   [Serialize](#serialize)
-    -   [Errors](#errors)
--   [Compiled Validators](#compiled-validators)
--   [Metadata](#metadata)
--   [Benchmarks](#benchmarks)
--   [Development](#development)
+- [Installation](#installation)
+- [Basic Example](#basic-example)
+- [Usage With @arrirpc/server](#usage-with-arrirpcserver)
+- [Supported Types](#supported-types)
+    - [Primitives](#primitives)
+    - [Enums](#enums)
+    - [Arrays / Lists](#arrays--lists)
+    - [Objects](#objects)
+    - [Records / Maps](#records--maps)
+    - [Discriminated Unions](#discriminated-unions)
+    - [Recursive Types](#recursive-types)
+- [Modifiers](#modifiers)
+    - [Optional](#optional)
+    - [Nullable](#nullable)
+    - [Extend](#extend)
+    - [Omit](#omit)
+    - [Pick](#pick)
+    - [Partial](#partial)
+- [Utilities](#utilities)
+    - [Validate](#validate)
+    - [Parse](#parse)
+    - [Safe Parse](#safe-parse)
+    - [Coerce](#coerce)
+    - [Safe Coerce](#safe-coerce)
+    - [Serialize](#serialize)
+    - [Errors](#errors)
+- [Compiled Validators](#compiled-validators)
+- [Metadata](#metadata)
+- [Benchmarks](#benchmarks)
+- [Development](#development)
 
 ## Installation
 
@@ -66,7 +68,7 @@ pnpm install @arrirpc/schema
 ## Basic Example
 
 ```ts
-import { a } from "@arrirpc/schema";
+import { a } from '@arrirpc/schema';
 
 const User = a.object({
     id: a.string(),
@@ -81,12 +83,12 @@ a.parse(User, `{"id": "1", "name": "John Doe"}`);
 a.parse(User, `{"id": "1", "name": null}`);
 
 // returns true
-a.validate(User, { id: "1", name: "John Doe" });
+a.validate(User, { id: '1', name: 'John Doe' });
 // returns false
-a.validate(User, { id: "1", name: null });
+a.validate(User, { id: '1', name: null });
 
 // outputs valid json
-a.serialize(User, { id: "1", name: "John Doe" });
+a.serialize(User, { id: '1', name: 'John Doe' });
 ```
 
 ## Usage With @arrirpc/server
@@ -94,8 +96,8 @@ a.serialize(User, { id: "1", name: "John Doe" });
 See [here](/languages/ts/ts-server/README.md) for full details.
 
 ```ts
-import { a } from "@arrirpc/schema";
-import { defineRpc } from "@arrirpc/server";
+import { a } from '@arrirpc/schema';
+import { defineRpc } from '@arrirpc/server';
 
 export default defineRpc({
     params: a.object({
@@ -141,11 +143,11 @@ Enum schemas allow you to specify a predefine list of accepted strings
 **Usage**
 
 ```ts
-const Status = a.enumerator(["ACTIVE", "INACTIVE", "UNKNOWN"]);
+const Status = a.enumerator(['ACTIVE', 'INACTIVE', 'UNKNOWN']);
 type Status = a.infer<typeof Status>; // "ACTIVE" | "INACTIVE" | "UNKNOWN";
 
-a.validate(Status, "BLAH"); // false
-a.validate(Status, "ACTIVE"); // true
+a.validate(Status, 'BLAH'); // false
+a.validate(Status, 'ACTIVE'); // true
 ```
 
 **Outputted JTD**
@@ -165,7 +167,7 @@ const MyList = a.array(a.string());
 type MyList = a.infer<typeof MyList>; // string[];
 
 a.validate(MyList, [1, 2]); // false
-a.validate(MyList, ["hello", "world"]); // true
+a.validate(MyList, ['hello', 'world']); // true
 ```
 
 **Outputted JTD**
@@ -191,12 +193,12 @@ const User = a.object({
 type User = a.infer<typeof User>; // { id: string; email: string; created: Date; }
 
 a.validate({
-    id: "1",
-    email: "johndoe@example.com",
+    id: '1',
+    email: 'johndoe@example.com',
     created: new Date(),
 }); // true
 a.validate({
-    id: "1",
+    id: '1',
     email: null,
     created: new Date(),
 }); // false
@@ -237,10 +239,10 @@ const UserStrict = a.object(
 );
 
 a.parse(UserStrict, {
-    id: "1",
-    name: "johndoe",
+    id: '1',
+    name: 'johndoe',
     created: new Date(),
-    bio: "my name is joe",
+    bio: 'my name is joe',
 }); // fails parsing because of the additional field "bio"
 ```
 
@@ -276,7 +278,7 @@ a.validate(R, {
     world: false,
 }); // true;
 a.validate(R, {
-    hello: "world",
+    hello: 'world',
 }); // false;
 ```
 
@@ -295,7 +297,7 @@ a.validate(R, {
 **Usage**
 
 ```ts
-const Shape = a.discriminator("type", {
+const Shape = a.discriminator('type', {
     RECTANGLE: a.object({
         width: a.float32(),
         height: a.float32(),
@@ -307,20 +309,20 @@ const Shape = a.discriminator("type", {
 type Shape = a.infer<typeof Shape>; // { type: "RECTANGLE"; width: number; height: number; } | { type: "CIRCLE"; radius: number; }
 
 // Infer specific sub types of the union
-type ShapeTypeRectangle = a.inferSubType<Shape, "type", "RECTANGLE">; // { type "RECTANGLE"; width: number; height: number; };
-type ShapeTypeCircle = a.inferSubType<Shape, "type", "CIRCLE">; // { type "CIRCLE"; radius: number; }
+type ShapeTypeRectangle = a.inferSubType<Shape, 'type', 'RECTANGLE'>; // { type "RECTANGLE"; width: number; height: number; };
+type ShapeTypeCircle = a.inferSubType<Shape, 'type', 'CIRCLE'>; // { type "CIRCLE"; radius: number; }
 
 a.validate(Shape, {
-    type: "RECTANGLE",
+    type: 'RECTANGLE',
     width: 1,
     height: 1.5,
 }); // true
 a.validate(Shape, {
-    type: "CIRCLE",
+    type: 'CIRCLE',
     radius: 5,
 }); // true
 a.validate(Shape, {
-    type: "CIRCLE",
+    type: 'CIRCLE',
     width: 1,
     height: 1.5,
 }); // false
@@ -385,7 +387,7 @@ const BinaryTree = a.recursive<BinaryTree>(
             right: a.nullable(self),
         }),
     {
-        id: "BinaryTree",
+        id: 'BinaryTree',
     },
 );
 
@@ -506,7 +508,7 @@ const A = a.object(
         a: a.string(),
         b: a.float32(),
     },
-    { id: "A" },
+    { id: 'A' },
 );
 console.log(A.metadata.id); // "A"
 
@@ -545,7 +547,7 @@ const A = a.object({
 });
 // { a: string; b: number; }
 
-const B = a.omit(A, ["a"]);
+const B = a.omit(A, ['a']);
 // { b: number; }
 ```
 
@@ -561,7 +563,7 @@ const A = a.object({
 });
 // { a: string; b: number; c: Date; }
 
-const B = a.pick(A, ["a", "c"]);
+const B = a.pick(A, ['a', 'c']);
 // { a: string; c: Date; }
 ```
 
@@ -593,7 +595,7 @@ const User = a.object({
     name: a.string(),
 });
 a.validate(User, true); // false
-a.validate(User, { id: "1", name: "john doe" }); // true
+a.validate(User, { id: '1', name: 'john doe' }); // true
 
 if (a.validate(User, someInput)) {
     console.log(someInput.id); // intellisense works here
@@ -644,9 +646,9 @@ const A = a.object({
 });
 
 a.coerce(A, {
-    a: "1",
-    b: "true",
-    c: "500.24",
+    a: '1',
+    b: 'true',
+    c: '500.24',
 });
 // { a: "1", b: true, c: 500.24 };
 ```
@@ -681,7 +683,7 @@ const User = a.object({
     name: a.string(),
 });
 
-a.serialize(User, { id: "1", name: "john doe" });
+a.serialize(User, { id: '1', name: 'john doe' });
 // {"id":"1","name":"john doe"}
 ```
 
@@ -697,7 +699,7 @@ const User = a.object({
     date: a.timestamp(),
 });
 
-a.errors(User, { id: 1, date: "hello world" });
+a.errors(User, { id: 1, date: 'hello world' });
 /**
  * [
  *   {
@@ -730,7 +732,7 @@ const $$User = a.compile(User);
 
 $$User.validate(someInput);
 $$User.parse(someJson);
-$$User.serialize({ id: "1", email: null, created: new Date() });
+$$User.serialize({ id: '1', email: null, created: new Date() });
 ```
 
 In most cases, the compiled validators will be much faster than the standard utilities. However there is some overhead with compiling the schemas so ideally each validator would be compiled once. Additionally the resulting methods make use of eval so they can only be used in an environment that you control such as a backend server. They WILL NOT work in a browser environment.
@@ -747,9 +749,9 @@ $$User.compiledCode.serialize; // the generated serialization code
 
 Metadata is used during cross-language code generation. Arri schemas allow you to specify the following metadata fields:
 
--   id - Will be used as the type name in any arri client generators
--   description - Will be added as a description comment above any generated types
--   isDeprecated - Will mark any generated code with the deprecation annotation of target language
+- id - Will be used as the type name in any arri client generators
+- description - Will be added as a description comment above any generated types
+- isDeprecated - Will mark any generated code with the deprecation annotation of target language
 
 ### Examples
 
@@ -764,8 +766,8 @@ const BookSchema = a.object(
         publishDate: a.timestamp(),
     },
     {
-        id: "Book",
-        description: "This is a book",
+        id: 'Book',
+        description: 'This is a book',
     },
 );
 ```
@@ -831,14 +833,14 @@ Because IDs are really important for producing concise type names. Arri validate
 
 ```ts
 // ID will be set to "Book"
-const BookSchema = a.object("Book", {
+const BookSchema = a.object('Book', {
     title: a.string(),
     author: a.string(),
     publishDate: a.timestamp(),
 });
 
 // ID will be set to "Message"
-const MessageSchema = a.discriminator("Message", "type", {
+const MessageSchema = a.discriminator('Message', 'type', {
     TEXT: a.object({
         userId: a.string(),
         content: a.string(),
@@ -850,7 +852,7 @@ const MessageSchema = a.discriminator("Message", "type", {
 });
 
 // ID will be set to "BTree"
-const BinaryTreeSchema = a.recursive("BTree", (self) =>
+const BinaryTreeSchema = a.recursive('BTree', (self) =>
     a.object({
         left: a.nullable(self),
         right: a.nullable(self),
@@ -862,7 +864,7 @@ const BinaryTreeSchema = a.recursive("BTree", (self) =>
 
 ## Benchmarks
 
-_Last Updated: 2024-03-19_
+_Last Updated: 2024-12-27_
 
 All benchmarks were run on my personal desktop. You can view the methodology used in [./benchmarks/src](./benchmark/src).
 
@@ -907,44 +909,44 @@ The following data was used in these benchmarks. Relevant schemas were created i
 
 #### Validation
 
-| Library                      | op/s        |
-| ---------------------------- | ----------- |
-| **Arri (Compiled)**          | 122,753,978 |
-| Typebox (Compiled)           | 63,131,651  |
-| Ajv -JTD (Compiled)          | 37,814,896  |
-| Ajv - JTD                    | 29,402,413  |
-| Ajv - JSON Schema (Compiled) | 12,003,432  |
-| Ajv -JSON Schema             | 10,057,501  |
-| **Arri**                     | 2,131,823   |
-| Typebox                      | 93,5599     |
-| Zod                          | 52,1357     |
+| Library                      | op/s           |
+| ---------------------------- | -------------- |
+| **Arri (Compiled)**          | **51,149,033** |
+| Typebox (Compiled)           | 47,826,755     |
+| Ajv -JTD (Compiled)          | 32,001,140     |
+| Ajv - JTD                    | 12,731,224     |
+| Ajv - JSON Schema (Compiled) | 12,371,095     |
+| Ajv -JSON Schema             | 8,811,605      |
+| **Arri**                     | **2,151,961**  |
+| Typebox                      | 1,024,386      |
+| Zod                          | 471,700        |
 
 #### Parsing
 
-| Library             | op/s    |
-| ------------------- | ------- |
-| JSON.parse          | 749,534 |
-| **Arri (Compiled)** | 728,382 |
-| **Arri**            | 378,175 |
-| Ajv -JTD (Compiled) | 241,107 |
+| Library             | op/s        |
+| ------------------- | ----------- |
+| JSON.parse          | 785,364     |
+| **Arri (Compiled)** | **736,957** |
+| **Arri**            | **378,841** |
+| Ajv -JTD (Compiled) | 230,124     |
 
 #### Serialization
 
-| Library                                    | op/s      |
-| ------------------------------------------ | --------- |
-| **Arri (Compiled)**                        | 4,272,430 |
-| **Arri (Compiled) Validate and Serialize** | 3,846,453 |
-| Ajv - JTD (Compiled)                       | 2,012,894 |
-| JSON.stringify                             | 938,289   |
-| Arri                                       | 481,985   |
+| Library                                    | op/s          |
+| ------------------------------------------ | ------------- |
+| **Arri (Compiled)**                        | **4,131,382** |
+| **Arri (Compiled) Validate and Serialize** | **3,710,794** |
+| Ajv - JTD (Compiled)                       | 2,066,041     |
+| JSON.stringify                             | 1,599,758     |
+| Arri                                       | 467,417       |
 
 #### Coercion
 
-| Library  | op/s    |
-| -------- | ------- |
-| **Arri** | 818,963 |
-| Zod      | 466,092 |
-| Typebox  | 209,363 |
+| Library  | op/s        |
+| -------- | ----------- |
+| **Arri** | **820,103** |
+| Zod      | 465,466     |
+| Typebox  | 405,292     |
 
 ### Integers
 
@@ -952,44 +954,44 @@ The following benchmarks measure how quickly each library operates on a single i
 
 #### Validation
 
-| Library                      | op/s        |
-| ---------------------------- | ----------- |
-| Ajv - JSON Schema (Compiled) | 329,332,736 |
-| **Arri (Compiled)**          | 201,644,167 |
-| **Arri**                     | 186,634,732 |
-| Ajv - JTD (Compiled)         | 151,044,902 |
-| Typebox (Compiled)           | 110,692,029 |
-| Ajv - JTD                    | 48,200,004  |
-| Ajv - JSON Schema            | 47,840,571  |
-| Typebox                      | 42,363,980  |
-| Zod                          | 1,266,268   |
+| Library                      | op/s            |
+| ---------------------------- | --------------- |
+| Typebox (Compiled)           | 196,718,452     |
+| **Arri (Compiled)**          | **190,853,038** |
+| Ajv - JSON Schema (Compiled) | 189,905,832     |
+| Ajv - JTD (Compiled)         | 143,619,126     |
+| **Arri**                     | **89,428,888**  |
+| Typebox                      | 48,408,435      |
+| Ajv - JSON Schema            | 36,560,467      |
+| Ajv - JTD                    | 35,639,616      |
+| Zod                          | 1,286,707       |
 
 #### Parsing
 
-| Library              | op/s        |
-| -------------------- | ----------- |
-| **Arri (Compiled)**  | 138,189,123 |
-| **Arri**             | 136,995,619 |
-| JSON.parse()         | 19,911,721  |
-| Ajv - JTD (Compiled) | 8,996,081   |
+| Library              | op/s            |
+| -------------------- | --------------- |
+| **Arri (Compiled)**  | **131,214,018** |
+| **Arri**             | **56,134,552**  |
+| JSON.parse()         | 21,001,320      |
+| Ajv - JTD (Compiled) | 9,441,285       |
 
 #### Serialization
 
-| Library              | op/s        |
-| -------------------- | ----------- |
-| Ajv - JTD (Compiled) | 198,980,679 |
-| **Arri (Compiled)**  | 190,386,426 |
-| **Arri**             | 114,799,692 |
-| JSON.stringify       | 21,433,854  |
+| Library              | op/s            |
+| -------------------- | --------------- |
+| Ajv - JTD (Compiled) | 199,802,584     |
+| **Arri (Compiled)**  | **194,399,849** |
+| **Arri**             | **65,097,829**  |
+| JSON.stringify       | 16,853,237      |
 
 #### Coercion
 
-| Library           | op/s        |
-| ----------------- | ----------- |
-| Arri              | 117,854,219 |
-| TypeBox           | 34,633,126  |
-| Ajv - JSON Schema | 28,016,735  |
-| Zod               | 1,586,546   |
+| Library           | op/s           |
+| ----------------- | -------------- |
+| **Arri**          | **55,840,221** |
+| TypeBox           | 34,403,424     |
+| Ajv - JSON Schema | 22,190,607     |
+| Zod               | 1,195,111      |
 
 ## Development