@arrirpc/schema 0.71.0 → 0.72.0

package/README.md

@@ -1,8 +1,8 @@
 # Arri Schema
 
-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.
+A Typescript validator and schema builder that can be compiled to other languages. 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.
 
-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.
+Under the hood this library constructs [Arri Type Definitions (ATD)](/specifications/arri_type_definition.md). These definitions can be passed to the [Arri CLI](/tooling/cli//README.md) to generate code for any of the client languages that Arri supports. Lastly, this library also comes with a [JIT compiler](#compiled-validators) which produces precompiled validators that are more than 100x faster than Zod.
 
 ## Project Philosophy
 
@@ -26,7 +26,8 @@ Originally this library was created as a way for building schemas for [Json Type
 
 - [Installation](#installation)
 - [Basic Example](#basic-example)
-- [Usage With @arrirpc/server](#usage-with-arrirpcserver)
+- [Usage with @arrirpc/server](#usage-with-arrirpcserver)
+- [Compiling to other languages](#compiling-to-other-languages)
 - [Supported Types](#supported-types)
     - [Primitives](#primitives)
     - [Enums](#enums)
@@ -50,8 +51,8 @@ Originally this library was created as a way for building schemas for [Json Type
     - [Safe Coerce](#safe-coerce)
     - [Serialize](#serialize)
     - [Errors](#errors)
-- [Compiled Validators](#compiled-validators)
 - [Metadata](#metadata)
+- [Compiled Validators](#compiled-validators)
 - [Benchmarks](#benchmarks)
 - [Development](#development)
 
@@ -89,6 +90,12 @@ a.validate(User, { id: '1', name: null });
 
 // outputs valid json
 a.serialize(User, { id: '1', name: 'John Doe' });
+
+// JIT compiled validator (faster but server-side only)
+const $$User = a.compile(User);
+$$User.validate({ id: '1', name: 'John Doe' });
+$$User.parse(`{"id": "1", "name": "John Doe"}`);
+$$User.serialize({ id: '1', name: 'John Doe' });
 ```
 
 ## Usage With @arrirpc/server
@@ -115,6 +122,135 @@ export default defineRpc({
 });
 ```
 
+## Compiling To Other Languages
+
+All schemas defined with this library can be compiled to other languages using the [Arri CLI](/tooling/cli/README.md).
+
+### Install the Arri ClI
+
+```bash
+# npm
+npm i --save-dev arri
+
+# pnpm
+pnpm i --save-dev arri
+```
+
+### Create You Arri Config
+
+```ts
+import { defineConfig, generators } from 'arri';
+
+export default defineConfig({
+    generators: [
+        // add your generators here
+        generators.rustClient({
+            // options
+        }),
+        generators.dartClient({
+            // options
+        }),
+    ],
+});
+```
+
+### Create And Export Your Schemas
+
+Use the `createAppDefinition` helper to export your schemas for the Arri CLI.
+
+```ts
+// definitions.ts
+import { createAppDefinition } from 'arri';
+import { a } from '@arrirpc/schema';
+
+const User = a.object('User', {
+    id: a.string(),
+    name: a.optional(string()),
+    email: a.nullable(a.string()),
+    createdAt: a.timestamp({ description: 'When the user was created' }),
+    updatedAt: a.timestamp(),
+});
+
+export default createAppDefinition({
+    definitions: {
+        User,
+    },
+});
+```
+
+### Run the Code Generator
+
+```bash
+# npm
+npx arri codegen ./definitions.ts
+
+# pnpm
+pnpm arri codegen ./definitions.ts
+```
+
+And your done. Now you can rerun this command whenever any of your schemas get updated.
+
+### Example Output
+
+```dart
+// dart output
+
+class User {
+  final String id;
+  final String? name;
+  final String? email;
+  /// when the user was created
+  final DateTime createdAt;
+  final DateTime updatedAt;
+  const User({
+     required this.id,
+     this.name,
+     required this.email,
+     required this.createdAt,
+     required this.updatedAt,
+  });
+
+  // implementation details
+}
+```
+
+```rust
+// rust output
+
+pub struct User {
+  id: String,
+  name: String,
+  name: Option<String>,
+  email: Option<String>,
+  // when the user was created
+  created_at: DateTime<FixedOffset>,
+  updated_at: DateTime<FixedOffset>,
+}
+
+impl ArriModel for User {
+  // implementation details
+}
+```
+
+```kotlin
+// kotlin output
+
+data class User(
+  val id: String,
+  val name: String?,
+  val email: String? = null,
+  /**
+   * When the user was created
+   */
+  val createdAt: Instant,
+  val updatedAt: Instance,
+) {
+  // implementation details
+}
+```
+
+See [here](/README.md#client-generators) for a list of all officially supported language generators.
+
 ## Supported Types
 
 ### Primitives
@@ -150,7 +286,7 @@ a.validate(Status, 'BLAH'); // false
 a.validate(Status, 'ACTIVE'); // true
 ```
 
-**Outputted JTD**
+**Outputted ATD**
 
 ```json
 {
@@ -170,7 +306,7 @@ a.validate(MyList, [1, 2]); // false
 a.validate(MyList, ['hello', 'world']); // true
 ```
 
-**Outputted JTD**
+**Outputted ATD**
 
 ```json
 {
@@ -204,7 +340,7 @@ a.validate({
 }); // false
 ```
 
-**Outputted JTD**
+**Outputted ATD**
 
 ```json
 {
@@ -246,7 +382,7 @@ a.parse(UserStrict, {
 }); // fails parsing because of the additional field "bio"
 ```
 
-**Outputted JTD**
+**Outputted ATD**
 
 ```json
 {
@@ -282,7 +418,7 @@ a.validate(R, {
 }); // false;
 ```
 
-**Outputted JTD**
+**Outputted ATD**
 
 ```json
 {
@@ -328,7 +464,7 @@ a.validate(Shape, {
 }); // false
 ```
 
-**Outputted JTD**
+**Outputted ATD**
 
 ```json
 {
@@ -413,7 +549,7 @@ a.validate(BinaryTree, {
 }); // false
 ```
 
-**Outputted JTD**
+**Outputted ATD**
 
 ```json
 {
@@ -456,7 +592,7 @@ const User = a.object({
  */
 ```
 
-**Outputted JTD**
+**Outputted ATD**
 
 ```json
 {
@@ -489,7 +625,7 @@ const name = a.nullable(a.string());
  */
 ```
 
-**Outputted JTD**
+**Outputted ATD**
 
 ```json
 {
@@ -717,34 +853,6 @@ a.errors(User, { id: 1, date: 'hello world' });
  */
 ```
 
-## Compiled Validators
-
-`@arrirpc/schema` comes with a high performance JIT compiler that transforms Arri Schemas into highly optimized validation, parsing, serialization functions.
-
-```ts
-const User = a.object({
-    id: a.string(),
-    email: a.nullable(a.string()),
-    created: a.timestamp(),
-});
-
-const $$User = a.compile(User);
-
-$$User.validate(someInput);
-$$User.parse(someJson);
-$$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.
-
-You can also use `a.compile` for code generation. The compiler result gives you access to the generated function bodies.
-
-```ts
-$$User.compiledCode.validate; // the generated validation code
-$$User.compiledCode.parse; // the generated parsing code
-$$User.compiledCode.serialize; // the generated serialization code
-```
-
 ## Metadata
 
 Metadata is used during cross-language code generation. Arri schemas allow you to specify the following metadata fields:
@@ -827,9 +935,9 @@ data class Book(
 )
 ```
 
-### ID Shorthand (Experimental)
+### ID Shorthand
 
-Because IDs are really important for producing concise type names. Arri validate also provides an _experimental\*_ shorthand for defining IDs of objects, discriminators, and recursive types.
+Because IDs are really important for producing concise type names. Arri validate also provides shorthand for defining IDs of objects, discriminators, and recursive types.
 
 ```ts
 // ID will be set to "Book"
@@ -860,7 +968,33 @@ const BinaryTreeSchema = a.recursive('BTree', (self) =>
 );
 ```
 
-\* Because this is experimental it may be removed in the future. The main thing I'm testings is whether added convenience is worth the overhead of maintaining 2 versions of each of these functions. The shorthand could also introduce unintended confusion for users of this library as it creates two places to look for an id.
+## Compiled Validators
+
+`@arrirpc/schema` comes with a high performance JIT compiler that transforms Arri Schemas into highly optimized validation, parsing, serialization functions. The result of the compilation also implements the [standard-schema](https://github.com/standard-schema/standard-schema) interface, meaning it can be passed into any library that accepts standard-schema.
+
+```ts
+const User = a.object({
+    id: a.string(),
+    email: a.nullable(a.string()),
+    created: a.timestamp(),
+});
+
+const $$User = a.compile(User);
+
+$$User.validate(someInput);
+$$User.parse(someJson);
+$$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 are created using [`new Function()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function) 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.
+
+You can also use `a.compile` for code generation. The compiler result gives you access to the generated function bodies.
+
+```ts
+$$User.compiledCode.validate; // the generated validation code
+$$User.compiledCode.parse; // the generated parsing code
+$$User.compiledCode.serialize; // the generated serialization code
+```
 
 ## Benchmarks
 

package/dist/index.cjs

@@ -2,7 +2,7 @@
 
 const typeDefs = require('@arrirpc/type-defs');
 const scule = require('scule');
-const timestamp = require('./shared/schema.BcsXcrqv.cjs');
+const timestamp = require('./shared/schema.COiEWm_0.cjs');
 
 function createParsingTemplate(input, schema) {
   const fallbackTemplate = `

package/dist/index.mjs

@@ -1,7 +1,7 @@
 import { isSchemaFormProperties, isSchemaFormValues, isSchemaFormElements, isSchemaFormDiscriminator, isSchemaFormEmpty, isSchemaFormType, isSchemaFormEnum, isSchemaFormRef } from '@arrirpc/type-defs';
 import { camelCase } from 'scule';
-import { u as uint8Max, a as uint8Min, b as uint16Max, c as uint16Min, d as uint32Max, e as uint32Min, i as int8Max, f as int8Min, g as int16Max, h as int16Min, j as int32Max, k as int32Min, l as isAScalarSchema, m as isAObjectSchema, n as isAStringEnumSchema, o as isAAraySchema, p as isARecordSchema, q as isADiscriminatorSchema, r as isARefSchema, s as errors, V as ValidationError, t as createStandardSchemaProperty, v as any, w as array, x as boolean, y as clone, z as coerce, A as discriminator, B as enumerator, C as extend, D as float32, E as float64, F as int16, G as int32, H as int64, I as int8, J as nullable, K as number, L as object, M as omit, N as optional, O as parse, P as partial, Q as pick, R as record, S as recursive, T as safeCoerce, U as safeParse, W as serialize, X as string, Y as stringEnum, Z as timestamp, _ as uint16, $ as uint32, a0 as uint64, a1 as uint8, a2 as validate, a3 as SCHEMA_METADATA } from './shared/schema.O5uzRO_D.mjs';
-export { ah as NumberTypeValues, ac as STR_ESCAPE, aj as hideInvalidProperties, a5 as int64Max, a4 as int64Min, ag as isASchema, ai as isObject, af as isValidationError, a8 as parseObjectSchema, ae as sanitizeJson, aa as serializeObject, ad as serializeSmallString, ab as serializeString, a7 as uint64Max, a6 as uint64Min, a9 as validateObjectSchema } from './shared/schema.O5uzRO_D.mjs';
+import { u as uint8Max, a as uint8Min, b as uint16Max, c as uint16Min, d as uint32Max, e as uint32Min, i as int8Max, f as int8Min, g as int16Max, h as int16Min, j as int32Max, k as int32Min, l as isAScalarSchema, m as isAObjectSchema, n as isAStringEnumSchema, o as isAAraySchema, p as isARecordSchema, q as isADiscriminatorSchema, r as isARefSchema, s as errors, V as ValidationError, t as createStandardSchemaProperty, v as any, w as array, x as boolean, y as clone, z as coerce, A as discriminator, B as enumerator, C as extend, D as float32, E as float64, F as int16, G as int32, H as int64, I as int8, J as nullable, K as number, L as object, M as omit, N as optional, O as parse, P as partial, Q as pick, R as record, S as recursive, T as safeCoerce, U as safeParse, W as serialize, X as string, Y as stringEnum, Z as timestamp, _ as uint16, $ as uint32, a0 as uint64, a1 as uint8, a2 as validate, a3 as SCHEMA_METADATA } from './shared/schema.PNAcAdz3.mjs';
+export { ah as NumberTypeValues, ac as STR_ESCAPE, aj as hideInvalidProperties, a5 as int64Max, a4 as int64Min, ag as isASchema, ai as isObject, af as isValidationError, a8 as parseObjectSchema, ae as sanitizeJson, aa as serializeObject, ad as serializeSmallString, ab as serializeString, a7 as uint64Max, a6 as uint64Min, a9 as validateObjectSchema } from './shared/schema.PNAcAdz3.mjs';
 
 function createParsingTemplate(input, schema) {
   const fallbackTemplate = `

package/dist/shared/{schema.BcsXcrqv.cjs → schema.COiEWm_0.cjs}

@@ -1,6 +1,7 @@
 'use strict';
 
 const typeDefs = require('@arrirpc/type-defs');
+require('scule');
 
 const int8Min = -128;
 const int8Max = 127;
@@ -86,7 +87,7 @@ function createStandardSchemaProperty(validate, parse) {
       };
       try {
         const result = parse(input, ctx);
-        if (!result || ctx.errors.length) {
+        if (ctx.errors.length) {
           return {
             issues: ctx.errors.map((err) => ({
               message: err.message ?? "Unknown error",
@@ -98,6 +99,14 @@ function createStandardSchemaProperty(validate, parse) {
           value: result
         };
       } catch (err) {
+        if (err instanceof ValidationError) {
+          return {
+            issues: err.errors.map((err2) => ({
+              message: err2.message ?? "Unknown error",
+              path: err2.instancePath.split("/").filter((item) => item.length > 0)
+            }))
+          };
+        }
         return {
           issues: [
             {

package/dist/shared/{schema.O5uzRO_D.mjs → schema.PNAcAdz3.mjs}

@@ -1,4 +1,5 @@
 import { TypeValues, isSchemaFormElements, isSchemaFormEnum, isSchemaFormDiscriminator, isSchemaFormValues, isSchemaFormProperties, isSchemaFormRef } from '@arrirpc/type-defs';
+import 'scule';
 
 const int8Min = -128;
 const int8Max = 127;
@@ -84,7 +85,7 @@ function createStandardSchemaProperty(validate, parse) {
       };
       try {
         const result = parse(input, ctx);
-        if (!result || ctx.errors.length) {
+        if (ctx.errors.length) {
           return {
             issues: ctx.errors.map((err) => ({
               message: err.message ?? "Unknown error",
@@ -96,6 +97,14 @@ function createStandardSchemaProperty(validate, parse) {
           value: result
         };
       } catch (err) {
+        if (err instanceof ValidationError) {
+          return {
+            issues: err.errors.map((err2) => ({
+              message: err2.message ?? "Unknown error",
+              path: err2.instancePath.split("/").filter((item) => item.length > 0)
+            }))
+          };
+        }
         return {
           issues: [
             {

package/dist/testSuites.cjs

@@ -2,7 +2,7 @@
 
 require('@arrirpc/type-defs');
 require('scule');
-const timestamp = require('./shared/schema.BcsXcrqv.cjs');
+const timestamp = require('./shared/schema.COiEWm_0.cjs');
 
 const User = timestamp.object({
   id: timestamp.string(),

package/dist/testSuites.mjs

@@ -1,6 +1,6 @@
 import '@arrirpc/type-defs';
 import 'scule';
-import { L as object, X as string, N as optional, J as nullable, G as int32, A as discriminator, x as boolean, Y as stringEnum, w as array, Z as timestamp, $ as uint32, v as any, K as number, R as record, S as recursive, E as float64, D as float32, H as int64, F as int16, _ as uint16, I as int8, a1 as uint8, P as partial, a0 as uint64, Q as pick, B as enumerator } from './shared/schema.O5uzRO_D.mjs';
+import { L as object, X as string, N as optional, J as nullable, G as int32, A as discriminator, x as boolean, Y as stringEnum, w as array, Z as timestamp, $ as uint32, v as any, K as number, R as record, S as recursive, E as float64, D as float32, H as int64, F as int16, _ as uint16, I as int8, a1 as uint8, P as partial, a0 as uint64, Q as pick, B as enumerator } from './shared/schema.PNAcAdz3.mjs';
 
 const User = object({
   id: string(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arrirpc/schema",
-  "version": "0.71.0",
+  "version": "0.72.0",
   "type": "module",
   "license": "MIT",
   "author": {
@@ -25,7 +25,7 @@
     "scule": "^1.3.0",
     "uncrypto": "^0.1.3",
     "@standard-schema/spec": "1.0.0-rc.0",
-    "@arrirpc/type-defs": "0.71.0"
+    "@arrirpc/type-defs": "0.72.0"
   },
   "devDependencies": {
     "ajv": "^8.17.1",