feat: add Valibot, utility functions, enhance readme

Author: Shuunen

.vscode/settings.json

@@ -1,9 +1,13 @@
 {
     "editor.quickSuggestions": {
-    	"strings": "on"
+        "strings": "on"
     },
     // prioritize ArkType's "type" for autoimports
     "typescript.preferences.autoImportSpecifierExcludeRegexes": [
-    	"^(node:)?os$"
+        "^(node:)?os$"
+    ],
+    "cSpell.words": [
+        "arktype",
+        "valibot"
     ],
 }

README.md

@@ -1,15 +1,83 @@
-# validation-lib-comparaison
+# Validation lib comparaison
 
-To install dependencies:
+## The goal of this project
+
+The goal is to compare different libraries and approaches to validate data in a TypeScript ecosystem.
+
+It's interesting to see how each library is designed, how it's used, and how it performs.
+
+Ideally you can use this comparison to choose the library that fits your needs the best.
+
+## Run tests and benchmarks
+
+Make sure you have [Bun](https://bun.sh) v1.1.x then :
 
 ```bash
+# install the dependencies
 bun install
+# run each file once just to verify that everything is working as expected
+bun bench --runs 1
+# run the benchmarks
+bun bench --runs 50
 ```
 
-To run:
+At the time of writing, Node 22 is around 2 times slower than Bun v1 ^^'
 
-```bash
-bun run index.ts
-```
+## The comparison results
+
+Here are the library used in this comparison :
+
+- [arktype](https://github.com/arktypeio/arktype) v2.0.4 from David Blass
+- [valibot](https://github.com/fabian-hiller/valibot) v1.0.0-rc.1 from Fabian Hiller
+- [zod](https://github.com/colinhacks/zod) v3.24.2 from Colin McDonnell
+
+| Date       | Score | Library | Deps  |  Size  | Light | Input | Throw | Safe  | Execution | Fast  |
+| ---------- | :---: | :-----: | :---: | :----: | :---: | :---: | :---: | :---: | :-------: | :---: |
+| 2025-02-21 |   2   | arktype |   2   | 133 KB |   0   | **1** |   0   | **1** |  155 ms   |   0   |
+| 2025-02-21 |   6   | valibot | **0** |  4 KB  | **2** | **1** | **1** | **1** |   74 ms   | **1** |
+| 2025-02-21 |   4   |   zod   | **0** | 62 KB  |   0   | **1** | **1** | **1** |   75 ms   | **1** |
+
+Legend :
+
+- Deps : the number of dependencies of the library
+- Size : the minified build size in bytes of the related file in `src`, run  `bun run build` to see by yourself
+- Light : 1 point if the build is less than 10 KB, 1 bonus point if it's less than 5 KB
+- Input : 1 point if the library can see that `age` is optional in the input but not optional in `type User` the output type
+- Throw : 1 point if the library have a parse or throw method, useful when we don't want to handle the error cases
+- Safe : 1 point if the library have a safe parse method that will not throw and usually return a `Result` type
+- Execution : average time in milliseconds to execute the test file with bun, check the `bun run bench` command output
+- Fast : 1 point if the library execution time is less than 100 ms
+
+## My favorite pick
+
+Valibot is my favorite pick because it's fast as Zod but has a lighter impact on the bundle size.
+
+## Todo
+
+- [ ] vanilla version ?
+- [ ] check error messages
+- [ ] check custom error messages
+- [ ] check custom validation rules
+
+## How to contribute
+
+There are many ways to contribute to this project :
+
+- Add a new library to the comparison
+- Improve the comparison table, criteria, or scoring
+- Improve the samples in `src`
+- Find a way to enhance library isolation to have more meaningful benchmarks
+- Whatever you think that could be useful, check the above todo list for inspiration
+
+Just open an issue or a PR, I'll be happy to discuss it with you <3
+
+## Thanks
 
-This project was created using `bun init` in bun v1.1.8. [Bun](https://bun.sh) is a fast all-in-one JavaScript runtime.
+- [Arktype](https://github.com/arktypeio/arktype) : for making this comparison possible
+- [Bun](https://bun.sh) : for their great tool to do almost everything ^^
+- [Github](https://github.com) : for all their great work year after year, pushing OSS forward
+- [Repo-checker](https://github.com/Shuunen/repo-checker) : eslint cover /src code and this tool the rest ^^
+- [Shields.io](https://shields.io) : for the nice badges on top of this readme
+- [Valibot](https://github.com/fabian-hiller/valibot) : for making this comparison possible
+- [Zod](https://github.com/colinhacks/zod) : for making this comparison possible
+  

arktype.ts

@@ -1,39 +1,41 @@
 {
-  "lockfileVersion": 1,
+  "lockfileVersion": 0,
   "workspaces": {
     "": {
-      "name": "validation-lib-comparaison",
       "dependencies": {
-        "arktype": "^2.0.0",
-        "zod": "^3.24.1",
+        "arktype": "^2.0.4",
+        "valibot": "^1.0.0-rc.1",
+        "zod": "^3.24.2",
       },
       "devDependencies": {
         "@types/bun": "latest",
       },
       "peerDependencies": {
-        "typescript": "^5.0.0",
+        "typescript": "^5.7.3",
       },
     },
   },
   "packages": {
-    "@ark/schema": ["@ark/schema@0.36.0", "", { "dependencies": { "@ark/util": "0.36.0" } }, "sha512-1zL+9AjNk6fNcCp5krt3HxM80kFr+MskqH2Gbz60GzXsjsAVZ38xM5WFVZMEPL8VbmTqDvBiwPm7HvK972lADg=="],
+    "@ark/schema": ["@ark/schema@0.39.0", "", { "dependencies": { "@ark/util": "0.39.0" } }, "sha512-LQbQUb3Sj461LgklXObAyUJNtsUUCBxZlO2HqRLYvRSqpStm0xTMrXn51DwBNNxeSULvKVpXFwoxiSec9kwKww=="],
 
-    "@ark/util": ["@ark/util@0.36.0", "", {}, "sha512-3tn3udpNeoLdmU1kvJYjDnhXereB2PYHED2c2j8Q7OsIRMx+AlOCXWjsI4qjAarjjbfCsKtsdMlE2QnLrcVCuA=="],
+    "@ark/util": ["@ark/util@0.39.0", "", {}, "sha512-90APHVklk8BP4kku7hIh1BgrhuyKYqoZ4O7EybtFRo7cDl9mIyc/QUbGvYDg//73s0J2H0I/gW9pzroA1R4IBQ=="],
 
-    "@types/bun": ["@types/[email protected].0", "", { "dependencies": { "bun-types": "1.2.0" } }, "sha512-5N1JqdahfpBlAv4wy6svEYcd/YfO2GNrbL95JOmFx8nkE6dbK4R0oSE5SpBA4vBRqgrOUAXF8Dpiz+gi7r80SA=="],
+    "@types/bun": ["@types/[email protected].2", "", { "dependencies": { "bun-types": "1.2.2" } }, "sha512-tr74gdku+AEDN5ergNiBnplr7hpDp3V1h7fqI2GcR/rsUaM39jpSeKH0TFibRvU0KwniRx5POgaYnaXbk0hU+w=="],
 
-    "@types/node": ["@types/node@22.10.10", "", { "dependencies": { "undici-types": "~6.20.0" } }, "sha512-X47y/mPNzxviAGY5TcYPtYL8JsY3kAq2n8fMmKoRCxq/c4v4pyGNCzM2R6+M5/umG4ZfHuT+sgqDYqWc9rJ6ww=="],
+    "@types/node": ["@types/node@22.13.4", "", { "dependencies": { "undici-types": "~6.20.0" } }, "sha512-ywP2X0DYtX3y08eFVx5fNIw7/uIv8hYUKgXoK8oayJlLnKcRfEYCxWMVE1XagUdVtCJlZT1AU4LXEABW+L1Peg=="],
 
     "@types/ws": ["@types/[email protected]", "", { "dependencies": { "@types/node": "*" } }, "sha512-bd/YFLW+URhBzMXurx7lWByOu+xzU9+kb3RboOteXYDfW+tr+JZa99OyNmPINEGB/ahzKrEuc8rcv4gnpJmxTw=="],
 
-    "arktype": ["[email protected].1", "", { "dependencies": { "@ark/schema": "0.36.0", "@ark/util": "0.36.0" } }, "sha512-IfczIefYOd2Omac9J1MH8YKmhGe4pQor1rg3w9mc6m8DA9fSnBRI7GF0XP8GQiHH5Khlj6MS6J1ZPbt68HDbrQ=="],
+    "arktype": ["[email protected].4", "", { "dependencies": { "@ark/schema": "0.39.0", "@ark/util": "0.39.0" } }, "sha512-S68rWVDnJauwH7/QCm8zCUM3aTe9Xk6oRihdcc3FSUAtxCo/q1Fwq46JhcwB5Ufv1YStwdQRz+00Y/URlvbhAQ=="],
 
-    "bun-types": ["[email protected].0", "", { "dependencies": { "@types/node": "*", "@types/ws": "~8.5.10" } }, "sha512-KEaJxyZfbV/c4eyG0vyehDpYmBGreNiQbZIqvVHJwZ4BmeuWlNZ7EAzMN2Zcd7ailmS/tGVW0BgYbGf+lGEpWw=="],
+    "bun-types": ["[email protected].2", "", { "dependencies": { "@types/node": "*", "@types/ws": "~8.5.10" } }, "sha512-RCbMH5elr9gjgDGDhkTTugA21XtJAy/9jkKe/G3WR2q17VPGhcquf9Sir6uay9iW+7P/BV0CAHA1XlHXMAVKHg=="],
 
     "typescript": ["[email protected]", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-84MVSjMEHP+FQRPy3pX9sTVV/INIex71s9TL2Gm5FG/WG1SqXeKyZ0k7/blY/4FdOzI12CBy1vGc4og/eus0fw=="],
 
     "undici-types": ["[email protected]", "", {}, "sha512-Ny6QZ2Nju20vw1SRHe3d9jVu6gJ+4e3+MMpqu7pqE5HT6WsTSlce++GQmK5UXS8mzV8DSYHrQH+Xrf2jVcuKNg=="],
 
-    "zod": ["[email protected]", "", {}, "sha512-muH7gBL9sI1nciMZV67X5fTKKBLtwpZ5VBp1vsOQzj1MhrBZ4wlVCm3gedKZWLp0Oyel8sIGfeiz54Su+OVT+A=="],
+    "valibot": ["[email protected]", "", { "peerDependencies": { "typescript": ">=5" }, "optionalPeers": ["typescript"] }, "sha512-bTHNpeeQ403xS7qGHF/tw3EC/zkZOU5VdkfIsmRDu1Sp+BJNTNCm6m5HlwOgyW/03lofP+uQiq3R+Poo9wiCEg=="],
+
+    "zod": ["[email protected]", "", {}, "sha512-lY7CDW43ECgW9u1TcT3IoXHflywfVqDYze4waEz812jR/bZ8FHDsl7pFQoSZTz5N+2NqRXs8GBwnAwo3ZNxqhQ=="],
   }
 }

bun.lock

@@ -1,15 +1,25 @@
 {
-  "name": "validation-lib-comparaison",
-  "module": "index.ts",
-  "type": "module",
+  "dependencies": {
+    "arktype": "^2.0.4",
+    "valibot": "^1.0.0-rc.1",
+    "zod": "^3.24.2"
+  },
   "devDependencies": {
     "@types/bun": "latest"
   },
+  "module": "index.ts",
+  "name": "validation-lib-comparaison",
   "peerDependencies": {
-    "typescript": "^5.0.0"
+    "typescript": "^5.7.3"
   },
-  "dependencies": {
-    "arktype": "^2.0.0",
-    "zod": "^3.24.1"
-  }
+  "scripts": {
+    "bench": "bun bench:bun --warmup 5 --runs 25",
+    "bench:bun": "hyperfine 'bun src/arktype.ts' 'bun src/valibot.ts' 'bun src/zod.ts'",
+    "bench:node": "hyperfine --runs 30 'node dist/arktype.js' 'node dist/valibot.js' 'node dist/zod.js'",
+    "build": "bun scripts/build.ts && echo build success",
+    "check": "bun check:tsc && bun run build && bun check:once && echo check success",
+    "check:once": "bun bench:bun --runs 1 && echo check:once success",
+    "check:tsc": "tsc --noEmit && echo check:tsc success"
+  },
+  "type": "module"
 }

package.json

@@ -0,0 +1,26 @@
+import { Glob } from "bun"
+
+const glob = new Glob("*.ts")
+const ignore = ['utils.ts']
+const outdir = './dist'
+const nameRegex = /dist[\/\\](?<name>[\w-]+)/
+
+function showFileSize (path: string) {
+  const name = nameRegex.exec(path)?.groups?.name
+  if (!name) throw new Error(`Failed to extract name from ${path}`)
+  const stats = Bun.file(path)
+  const kb = Math.round(stats.size / 1024)
+  console.log(name.padStart(10), kb, 'KB')
+}
+
+function build (file: string) {
+  const entrypoints = [`./src/${file}`]
+  Bun.build({ entrypoints, outdir, minify: true }).then((data) => {
+    showFileSize(data.outputs[0].path)
+  }).catch((err) => { console.error('Build failed:', err) })
+}
+
+for await (const file of glob.scan("./src")) {
+  if (ignore.includes(file)) continue
+  build(file)
+}

scripts/build.ts

@@ -0,0 +1,30 @@
+import { type } from "arktype"
+import { checkUserA, checkUserB, checkUserC } from './utils'
+
+const userSchema = type({
+  name: type.string,
+  age: type.number.default(42),
+})
+
+export type User = typeof userSchema.inferOut
+
+export type UserInput = typeof userSchema.inferIn
+
+const userA = userSchema({ name: "Jordan" })
+// @ts-expect-error Argument of type '{ name: string; age: number; } | ArkErrors' is not assignable to parameter of type 'User'.
+checkUserA(userA)
+
+function createUser (input: UserInput) {
+  const user = userSchema(input)
+  if (user instanceof type.errors) return { name: "Jordan", age: 42 } // cannot use userA here
+  return user
+}
+
+const userB = createUser({ name: "Romain", age: 35 })
+checkUserB(userB)
+
+// @ts-expect-error age should be a number
+const userC = createUser({ name: "Romain", age: "35" })
+checkUserC(userC)
+
+console.log('All tests passed successfully.')

src/arktype.ts

@@ -0,0 +1,16 @@
+type User = {
+  name: string,
+  age?: number,
+}
+
+export function checkUserA (userA: User) {
+  console.assert(userA.age === 42, 'userA.age should be 42')
+}
+
+export function checkUserB (userB: User) {
+  console.assert(userB.age === 35, 'userB.age should be 35')
+}
+
+export function checkUserC (userC: User) {
+  console.assert(userC.name === "Jordan", 'userC.name should be Jordan')
+}

src/utils.ts

@@ -0,0 +1,29 @@
+import * as v from 'valibot'
+import { checkUserA, checkUserB, checkUserC } from './utils'
+
+const userSchema = v.object({
+  name: v.string(),
+  age: v.optional(v.number(), 42),
+})
+
+export type User = v.InferOutput<typeof userSchema>
+
+export type UserInput = v.InferInput<typeof userSchema>
+
+const userA = v.parse(userSchema, { name: "Jordan" })
+checkUserA(userA)
+
+function createUser (input: UserInput) {
+  const result = v.safeParse(userSchema, input)
+  if (!result.success) return userA
+  return result.output
+}
+
+const userB = createUser({ name: "Romain", age: 35 })
+checkUserB(userB)
+
+// @ts-expect-error age should be a number
+const userC = createUser({ name: "Romain", age: "35" })
+checkUserC(userC)
+
+console.log('All tests passed successfully.')

src/valibot.ts

@@ -0,0 +1,29 @@
+import { z } from "zod"
+import { checkUserA, checkUserB, checkUserC } from './utils'
+
+const userSchema = z.object({
+  name: z.string(),
+  age: z.number().default(42),
+})
+
+export type User = z.infer<typeof userSchema>
+
+export type UserInput = z.input<typeof userSchema>
+
+const userA = userSchema.parse({ name: "Jordan" })
+checkUserA(userA)
+
+function createUser (input: UserInput) {
+  const result = userSchema.safeParse(input)
+  if (!result.success) return userA
+  return result.data
+}
+
+const userB = createUser({ name: "Romain", age: 35 })
+checkUserB(userB)
+
+// @ts-expect-error age should be a number
+const userC = createUser({ name: "Romain", age: "35" })
+checkUserC(userC)
+
+console.log('All tests passed successfully.')