@afora/core 0.0.11 → 0.0.12
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +60 -209
- package/package.json +8 -3
package/README.md
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
<p align="center">
|
|
2
2
|
<picture>
|
|
3
3
|
<source media="(prefers-color-scheme: dark)" srcset=".github/assets/afora-banner-dark.png">
|
|
4
|
-
<img alt="afora —
|
|
4
|
+
<img alt="afora — Simple to write. Built to hold." src=".github/assets/afora-banner-light.png" width="100%">
|
|
5
5
|
</picture>
|
|
6
6
|
</p>
|
|
7
7
|
|
|
@@ -10,7 +10,7 @@
|
|
|
10
10
|
<a href="https://github.com/afora-framework/core/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/afora-framework/core/actions/workflows/ci.yml/badge.svg?branch=main"></a>
|
|
11
11
|
<a href="https://www.npmjs.com/package/@afora/core"><img alt="npm provenance" src="https://img.shields.io/badge/npm-provenance-2ea44f?logo=npm"></a>
|
|
12
12
|
<a href="https://standardschema.dev"><img alt="Standard Schema V1" src="https://img.shields.io/badge/Standard%20Schema-V1-3178c6"></a>
|
|
13
|
-
<img alt="Bun >= 1.4.4 and Node >= 22" src="https://img.shields.io/badge/runtime-Bun%20%
|
|
13
|
+
<img alt="Bun >= 1.4.4 and Node >= 22" src="https://img.shields.io/badge/runtime-Bun%20%3E%3D%201.4.4%20%7C%20Node%20%3E%3D%2022-555">
|
|
14
14
|
<a href="LICENSE"><img alt="MIT license" src="https://img.shields.io/github/license/afora-framework/core"></a>
|
|
15
15
|
</p>
|
|
16
16
|
|
|
@@ -23,47 +23,42 @@
|
|
|
23
23
|
<a href="https://github.com/afora-framework/core/discussions">Discussions</a>
|
|
24
24
|
</p>
|
|
25
25
|
|
|
26
|
-
|
|
26
|
+
<h3 align="center">Simple to write. Built to hold.</h3>
|
|
27
27
|
|
|
28
|
-
|
|
28
|
+
**afora is a domain-first framework for TypeScript backends.** You declare what your entities, use cases and API are, and the runtime keeps the guarantees that are easy to forget: secrets stay masked, unknown fields are rejected, unique keys hold and business errors get the right status. Whoever writes the code, you or your agent, it holds.
|
|
29
29
|
|
|
30
|
-
|
|
31
|
-
bun add @afora/core @afora/hono hono typebox && bun add -d @afora/codegen
|
|
32
|
-
bunx afora-codegen generate afora.json --stages ./stages.ts # writes src/domain/*.ts
|
|
33
|
-
bun src/server.ts
|
|
34
|
-
```
|
|
35
|
-
|
|
36
|
-
With the [quick start's `afora.json`](#the-same-app-as-an-aforajson) and three small files written by hand (the hashing function, the `hono` stage catalog and the server, shown there), that is the whole API: a `User` with a masked password and a unique email, a use case written as steps, problem+json errors and an OpenAPI document. The same app written by hand in TypeScript is the [quick start](#quick-start), and the [afora.json guide](docs/afora-json.md) covers the whole spec.
|
|
30
|
+
Model the domain; the runtime keeps the invariants. Built on [TypeBox](https://github.com/sinclairzx81/typebox), with [Standard Schema](https://standardschema.dev) on every field, on Bun and Node.
|
|
37
31
|
|
|
38
32
|
## Why afora
|
|
39
33
|
|
|
40
|
-
An HTTP backend written by an agent (or in a hurry) tends to break the same few guarantees. In afora each one is
|
|
34
|
+
An HTTP backend written by an agent (or in a hurry) tends to break the same few guarantees. In afora each one is part of the runtime, not a convention the code has to remember:
|
|
41
35
|
|
|
42
|
-
| What usually breaks | What afora does
|
|
43
|
-
| ---------------------------------------------- |
|
|
44
|
-
| A password hash or token ends up in a response | A
|
|
45
|
-
| Extra fields in a request body are accepted |
|
|
46
|
-
| A business error is returned as a 500 |
|
|
47
|
-
| A duplicate email is written twice | `unique` keys are enforced by the repository
|
|
36
|
+
| What usually breaks | What afora does |
|
|
37
|
+
| ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
|
|
38
|
+
| A password hash or token ends up in a response | A `sensitive` property is masked by `toJSON()` at any depth, so no serializer can leak it ([records](docs/records.md)). |
|
|
39
|
+
| Extra fields in a request body are accepted | Undeclared keys are rejected at any depth, and the API answers 400 ([Standard Schema](docs/standard-schema.md)). |
|
|
40
|
+
| A business error is returned as a 500 | Errors know their layer and become problem+json with the right status ([outputs](docs/outputs.md)). |
|
|
41
|
+
| A duplicate email is written twice | `unique` keys are enforced by the repository, and a violation is a 409 ([repositories](docs/repositories.md)). |
|
|
42
|
+
| One user reads or changes another user's data | A use case declares its `access` (scopes, owner), and every output enforces it before it runs ([access](docs/auth.md)). |
|
|
48
43
|
|
|
49
|
-
[`examples/agent-built`](examples/agent-built/README.md) checks these
|
|
44
|
+
[`examples/agent-built`](examples/agent-built/README.md) checks these five on the running API of a ticketing backend an agent built through the MCP server, next to a Hono + Zod baseline written from the same brief. Both hold them; the afora one wrote no code for any of them.
|
|
50
45
|
|
|
51
|
-
|
|
46
|
+
## For you and your agent
|
|
52
47
|
|
|
53
|
-
|
|
48
|
+
**Developer experience**
|
|
54
49
|
|
|
55
|
-
- **
|
|
56
|
-
- **
|
|
57
|
-
- **
|
|
58
|
-
- **
|
|
59
|
-
- **
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
- **
|
|
64
|
-
- **
|
|
65
|
-
- **
|
|
66
|
-
- **
|
|
50
|
+
- **Four declarations to a CRUD API:** an entity, a repository, a command and an output ([overview](docs/README.md)).
|
|
51
|
+
- **Types that follow the model:** inputs and responses are inferred, `findByEmail` exists because `email` is unique, and `user.change.password()` because you allowed it.
|
|
52
|
+
- **Fits what you already use:** every field is a Standard Schema, so Hono, tRPC and TanStack Form take it as is.
|
|
53
|
+
- **Any server, any store:** [Hono](packages/hono/README.md), [Fastify](packages/fastify/README.md), [Express](packages/express/README.md) or [Elysia](packages/elysia/README.md); in memory, [Drizzle](packages/drizzle/README.md) or [DynamoDB](packages/dynamodb/README.md).
|
|
54
|
+
- **Errors you can read:** each one names its layer and carries the trace of the layers it crossed ([exceptions](docs/exceptions.md)).
|
|
55
|
+
|
|
56
|
+
**Agent experience**
|
|
57
|
+
|
|
58
|
+
- **The application is data:** an `afora.json` declares the entities, the use cases (as steps), the commands and the HTTP API ([guide](docs/afora-json.md)).
|
|
59
|
+
- **An MCP server to write it:** [`@afora/mcp`](packages/mcp/README.md) lets an agent read the catalog, edit and validate the spec, generate the code and see its TypeScript diagnostics.
|
|
60
|
+
- **Code you review:** [`@afora/codegen`](packages/codegen/README.md) turns the spec into the TypeScript you would write by hand, committed; `extractSpec(app)` gives the spec back from code written by hand.
|
|
61
|
+
- **The runtime holds what the agent forgets:** the five rows above, with no code written for them. `examples/blog` is a whole API generated from one `afora.json`.
|
|
67
62
|
|
|
68
63
|
## Install
|
|
69
64
|
|
|
@@ -71,25 +66,11 @@ afora is not a general-purpose validator. It models a domain on [TypeBox](https:
|
|
|
71
66
|
bun add @afora/core typebox # or: npm install @afora/core typebox
|
|
72
67
|
```
|
|
73
68
|
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
`Password` hashes with argon2id: with `Bun.password` on Bun, with native `node:crypto` argon2 on a Node that has it (24.7+), and otherwise it throws `PasswordHasherRequired` until you call `configure({ hasher })`. `Id.generate()` makes a portable, monotonic UUID v7 on any runtime. afora imports no `node:crypto` (or `Buffer`) at load, so it loads in browsers and Workers; the native hasher is looked up on first use through `process.getBuiltinModule` (Node 22.3+). The native hasher derives argon2 version 19 only; a hash of another version throws `UnsupportedPasswordHash` (verify it with `Bun.password`, or `configure({ hasher })`).
|
|
77
|
-
|
|
78
|
-
<!-- docs:code skip: myArgon2 and myUuidV7 stand for your own libraries -->
|
|
79
|
-
```ts
|
|
80
|
-
import { configure, type PasswordHasher } from "@afora/core";
|
|
81
|
-
|
|
82
|
-
const hasher: PasswordHasher = {
|
|
83
|
-
hash: (plain) => myArgon2.hash(plain),
|
|
84
|
-
verify: (plain, hash) => myArgon2.verify(plain, hash),
|
|
85
|
-
verifySync: (plain, hash) => myArgon2.verifySync(plain, hash), // optional; `Password.verifySync` throws without it
|
|
86
|
-
};
|
|
87
|
-
configure({ hasher, idGenerator: () => myUuidV7() }); // both optional; `resetRuntime()` restores the defaults
|
|
88
|
-
```
|
|
69
|
+
Bun >= 1.4.4 or Node.js >= 22; it also loads in browsers and Workers. TypeBox (`typebox`, `^1`) is a peer dependency. How passwords are hashed and ids made on each runtime, and how to replace them with `configure`: [Runtime](docs/runtime.md).
|
|
89
70
|
|
|
90
71
|
## Quick start
|
|
91
72
|
|
|
92
|
-
A `User`
|
|
73
|
+
A `User` with a masked password and a unique email, a use case written as steps, a transaction, and an HTTP API with an OpenAPI document. Install what it uses:
|
|
93
74
|
|
|
94
75
|
```bash
|
|
95
76
|
bun add @afora/core @afora/hono hono typebox
|
|
@@ -157,6 +138,7 @@ class Register extends useCaseOf({
|
|
|
157
138
|
run: "hashPassword",
|
|
158
139
|
fn: hashPassword,
|
|
159
140
|
args: ["$input.plainPassword"],
|
|
141
|
+
params: blueprintOf((ctx) => ({ plain: ctx.string })),
|
|
160
142
|
as: "hash",
|
|
161
143
|
},
|
|
162
144
|
{
|
|
@@ -214,7 +196,12 @@ GET /openapi.json -> the OpenAPI 3.1 document of the route
|
|
|
214
196
|
|
|
215
197
|
### The same app as an afora.json
|
|
216
198
|
|
|
217
|
-
Everything above
|
|
199
|
+
Everything above except the hashing function is data, so it can be written as an `afora.json`. `@afora/codegen` turns it into the same TypeScript, committed and reviewable, and `@afora/mcp` lets an agent write it.
|
|
200
|
+
|
|
201
|
+
<details>
|
|
202
|
+
<summary>The <code>afora.json</code>, the three hand-written files and the commands</summary>
|
|
203
|
+
|
|
204
|
+
This is `examples/interop/quickstart.afora.json`, which the same test validates and generates.
|
|
218
205
|
|
|
219
206
|
```json
|
|
220
207
|
{
|
|
@@ -266,6 +253,7 @@ Everything above, except the hashing function, is data, so it can be written as
|
|
|
266
253
|
"run": "hashPassword",
|
|
267
254
|
"fn": { "import": "../hash-password.ts#hashPassword" },
|
|
268
255
|
"args": ["$input.plainPassword"],
|
|
256
|
+
"params": { "fields": { "plain": "string" } },
|
|
269
257
|
"as": "hash"
|
|
270
258
|
},
|
|
271
259
|
{
|
|
@@ -344,183 +332,46 @@ These three files are `examples/interop/from-json`, which `bun run test:interop`
|
|
|
344
332
|
|
|
345
333
|
`generate` writes one file per kind (`entities.ts`, `repositories.ts`, `use-cases.ts`, `commands.ts`, `outputs.ts`...), an `application.ts` and an `index.ts`, each starting with a banner saying not to edit it. `afora-codegen extract` goes the other way and gives the `afora.json` of an `Application`. The guide is in [docs/afora-json.md](docs/afora-json.md).
|
|
346
334
|
|
|
347
|
-
|
|
335
|
+
</details>
|
|
348
336
|
|
|
349
|
-
|
|
337
|
+
## Learn more
|
|
350
338
|
|
|
351
|
-
- [
|
|
352
|
-
- [
|
|
353
|
-
- [
|
|
354
|
-
- [
|
|
355
|
-
- [Repositories](docs/repositories.md): typed async methods for an entity, queries, soft deletion, providers, transactions and relations.
|
|
356
|
-
- [Schema evolution](docs/schema-evolution.md): `fill`, `renamedFrom`, `schemaVersion` with `upgrade` steps and `previousNames`, so old rows are still read; `app.migrate` to rewrite them, and a schema lock checked in CI and on `start`.
|
|
357
|
-
- [Use cases](docs/use-cases.md): the Command pattern with method injection, written as code or as steps.
|
|
358
|
-
- [Commands](docs/commands.md): use cases under operation names, with a context, a transaction and an event policy.
|
|
359
|
-
- [Outputs](docs/outputs.md): commands through stages into a sink, such as an HTTP API or an OpenAPI document.
|
|
360
|
-
- [Applications](docs/applications.md): a named, checked manifest of every declaration, and `describe()`.
|
|
361
|
-
- [Exceptions](docs/exceptions.md): errors that know their layer and keep a trace.
|
|
362
|
-
- [Environments](docs/environments.md): validated environment variables.
|
|
363
|
-
- [Standard Schema](docs/standard-schema.md), [OpenAPI](docs/openapi.md) and the [afora.json guide](docs/afora-json.md).
|
|
364
|
-
|
|
365
|
-
## Standard Schema
|
|
366
|
-
|
|
367
|
-
Every field (a property, blueprint, list or record class) implements Standard Schema V1 (`vendor: "afora"`), so Hono, tRPC, TanStack Form and any other library that takes one takes it as is. `validate` is synchronous, never throws for an invalid value and reports every issue with its `path`. Without a framework, `safeParse` returns `{ value }` or `{ issues }`. See [docs/standard-schema.md](docs/standard-schema.md); the real-library tests are in `examples/interop`.
|
|
339
|
+
- [Tutorial](docs/tutorial.md): an API built step by step, and [coming from Hono + Zod](docs/coming-from-hono-zod.md).
|
|
340
|
+
- [Concepts](docs/README.md), in the order they build on one another: property → blueprint → record → entity → repository → use case → command → output → application.
|
|
341
|
+
- [The afora.json guide](docs/afora-json.md) and the [MCP server](packages/mcp/README.md).
|
|
342
|
+
- [API reference](docs/reference/api.md), [FAQ](docs/faq.md) and [troubleshooting](docs/troubleshooting.md).
|
|
368
343
|
|
|
369
344
|
## Packages
|
|
370
345
|
|
|
371
|
-
| Package | What it does
|
|
372
|
-
| ---------------------------------------------------------- |
|
|
373
|
-
| [`@afora/core`](https://www.npmjs.com/package/@afora/core) |
|
|
374
|
-
| [`@afora/codegen`](packages/codegen/README.md) |
|
|
375
|
-
| [`@afora/mcp`](packages/mcp/README.md) | An MCP server that lets an agent build
|
|
376
|
-
| [`@afora/hono`](packages/hono/README.md) |
|
|
377
|
-
| [`@afora/fastify`](packages/fastify/README.md) |
|
|
378
|
-
| [`@afora/express`](packages/express/README.md) |
|
|
379
|
-
| [`@afora/elysia`](packages/elysia/README.md) |
|
|
380
|
-
| [`@afora/ws`](packages/ws/README.md) |
|
|
381
|
-
| [`@afora/drizzle`](packages/drizzle/README.md) |
|
|
382
|
-
| [`@afora/dynamodb`](packages/dynamodb/README.md) |
|
|
383
|
-
| [`@afora/otel`](packages/otel/README.md) | OpenTelemetry
|
|
384
|
-
|
|
385
|
-
## Example
|
|
386
|
-
|
|
387
|
-
`examples/blog` is a blog (users with the `authenticatable` plugin, posts with soft deletion, every use case a [standard one](docs/std-use-cases.md), a Hono API on Drizzle and SQLite) whose whole `src/domain` is generated from one `afora.json` by `@afora/codegen`. Only the database, the schema, the provider (made from a `Database` environment with `providerFrom` when the server calls `App.start()`, and named `database` in the `providers` of the spec) and the server are hand-written. Its tests check that the committed code is what the spec generates, drive the API end to end and extract the spec back from the application: `bun run test:blog`.
|
|
388
|
-
|
|
389
|
-
`examples/agent-built` is an event ticketing API (organizers, events with a capacity, tickets) built only through the `@afora/mcp` tools from a written brief, with the tool calls committed and replayed byte for byte, and an evaluation of four invariants on its running API and on a Hono + Zod baseline: `bun run test:agent-built`. See [its write-up](examples/agent-built/README.md).
|
|
346
|
+
| Package | What it does |
|
|
347
|
+
| ---------------------------------------------------------- | ----------------------------------------------------------------- |
|
|
348
|
+
| [`@afora/core`](https://www.npmjs.com/package/@afora/core) | The framework: from properties to outputs (this repository). |
|
|
349
|
+
| [`@afora/codegen`](packages/codegen/README.md) | `afora.json` to TypeScript, and an application back to its spec. |
|
|
350
|
+
| [`@afora/mcp`](packages/mcp/README.md) | An MCP server that lets an agent build the domain. |
|
|
351
|
+
| [`@afora/hono`](packages/hono/README.md) | Serves the operations on Hono, with an optional OpenAPI document. |
|
|
352
|
+
| [`@afora/fastify`](packages/fastify/README.md) | The same on Fastify. |
|
|
353
|
+
| [`@afora/express`](packages/express/README.md) | The same on Express 5. |
|
|
354
|
+
| [`@afora/elysia`](packages/elysia/README.md) | The same on Elysia. |
|
|
355
|
+
| [`@afora/ws`](packages/ws/README.md) | Operations and domain events over WebSocket. |
|
|
356
|
+
| [`@afora/drizzle`](packages/drizzle/README.md) | Repositories on Drizzle ORM (SQLite and Postgres). |
|
|
357
|
+
| [`@afora/dynamodb`](packages/dynamodb/README.md) | Repositories on one DynamoDB table. |
|
|
358
|
+
| [`@afora/otel`](packages/otel/README.md) | OpenTelemetry spans per command, use case and repository call. |
|
|
390
359
|
|
|
391
360
|
## Performance
|
|
392
361
|
|
|
393
|
-
|
|
362
|
+
afora validates and transforms faster than Zod 4 on most of the fourteen measured cases; checkers that compile and do not transform (TypeBox, Ajv, Typia) are faster still. The method, every case and the trade-offs are in [Performance](docs/performance.md).
|
|
394
363
|
|
|
395
364
|
<!-- bench:start -->
|
|
396
365
|
|
|
397
366
|
|
|
398
367
|
|
|
399
|
-
|
|
400
|
-
|
|
401
|
-
| Node 24 | afora | TypeBox | Ajv | Typia | Zod | Valibot | ArkType | Effect Schema | Yup | Joi |
|
|
402
|
-
| -------------------------------------------------------- | -------: | ------: | ----: | ----: | ----: | ------: | ------: | ------------: | -----: | -----: |
|
|
403
|
-
| Small flat object, valid | 579.5 ns | 0.14x | 0.15x | 0.16x | 1.31x | 2.04x | 10.08x | 2.51x | 10.37x | 7.56x |
|
|
404
|
-
| Small flat object, invalid | 1017 ns | 7.65x | 0.12x | 0.63x | 2.53x | 2.22x | 23.82x | 3.43x | 61.39x | 6.48x |
|
|
405
|
-
| Nested user (address, 5 tags max, 10 addresses), valid | 4379 ns | 0.11x | 0.17x | 0.12x | 1.15x | 1.11x | 12.53x | 3.06x | 18.70x | 5.62x |
|
|
406
|
-
| Nested user (address, 5 tags max, 10 addresses), invalid | 5556 ns | 8.41x | 0.18x | 0.76x | 1.53x | 1.17x | 21.08x | 3.17x | 37.22x | 6.04x |
|
|
407
|
-
| API request body (an order with 5 items), valid | 5174 ns | 0.30x | 0.32x | 0.21x | 1.09x | 1.10x | 8.72x | 2.11x | 16.09x | 5.05x |
|
|
408
|
-
| API request body (an order with 5 items), invalid | 6434 ns | 4.79x | 0.16x | 0.85x | 1.75x | 1.12x | 15.93x | 2.53x | 33.94x | 5.43x |
|
|
409
|
-
| List of 1,000 items, valid | 339.2 µs | 0.05x | 0.08x | 0.05x | 0.62x | 2.45x | 17.10x | 3.03x | 21.78x | 6.44x |
|
|
410
|
-
| List of 1,000 items, invalid | 358.9 µs | 15.45x | 0.09x | 0.14x | 0.62x | 2.41x | 21.12x | 2.94x | 22.68x | 6.37x |
|
|
411
|
-
| Union of 4 variants (12 events), valid | 1068 ns | 0.51x | 0.66x | 0.52x | 4.52x | 16.14x | 1.87x | 13.23x | 94.83x | 93.28x |
|
|
412
|
-
| Union of 4 variants (12 events), invalid | 5145 ns | 11.93x | 0.17x | 0.65x | 1.49x | 3.92x | 6.74x | 3.25x | 32.25x | 36.19x |
|
|
413
|
-
| 6 levels of nesting, valid | 1609 ns | 0.06x | 0.09x | 0.07x | 0.80x | 1.27x | 13.88x | 3.68x | 17.45x | 5.29x |
|
|
414
|
-
| 6 levels of nesting, invalid | 2018 ns | 18.04x | 0.11x | 1.47x | 1.73x | 1.67x | 24.36x | 4.52x | 50.40x | 7.09x |
|
|
415
|
-
| Small flat object, checks only, valid | 430.2 ns | 0.20x | 0.20x | 0.21x | 0.79x | 2.16x | 0.40x | 2.05x | 12.75x | 9.22x |
|
|
416
|
-
| Small flat object, checks only, invalid | 934.7 ns | 8.47x | 0.13x | 0.68x | 2.32x | 2.59x | 19.81x | 3.18x | 65.32x | 6.90x |
|
|
417
|
-
|
|
418
|
-
| Bun | afora | TypeBox | Ajv | Typia | Zod | Valibot | ArkType | Effect Schema | Yup | Joi |
|
|
419
|
-
| -------------------------------------------------------- | -------: | ------: | ----: | ----: | ----: | ------: | ------: | ------------: | -----: | -----: |
|
|
420
|
-
| Small flat object, valid | 400.9 ns | 0.15x | 0.17x | 0.16x | 1.63x | 0.86x | 9.95x | 2.29x | 18.78x | 9.88x |
|
|
421
|
-
| Small flat object, invalid | 861.0 ns | 6.52x | 0.18x | 1.00x | 1.38x | 0.87x | 14.29x | 2.23x | 39.21x | 7.40x |
|
|
422
|
-
| Nested user (address, 5 tags max, 10 addresses), valid | 4965 ns | 0.06x | 0.10x | 0.04x | 1.06x | 0.48x | 5.57x | 1.79x | 20.03x | 4.31x |
|
|
423
|
-
| Nested user (address, 5 tags max, 10 addresses), invalid | 4125 ns | 7.60x | 0.17x | 0.89x | 1.58x | 0.92x | 14.61x | 2.76x | 41.12x | 7.68x |
|
|
424
|
-
| API request body (an order with 5 items), valid | 4326 ns | 0.22x | 0.23x | 0.27x | 1.27x | 0.69x | 5.31x | 1.83x | 23.20x | 5.40x |
|
|
425
|
-
| API request body (an order with 5 items), invalid | 4504 ns | 4.89x | 0.16x | 0.93x | 1.93x | 0.95x | 12.21x | 2.29x | 39.23x | 8.54x |
|
|
426
|
-
| List of 1,000 items, valid | 292.5 µs | 0.02x | 0.07x | 0.02x | 1.23x | 0.52x | 8.46x | 1.92x | 31.44x | 5.54x |
|
|
427
|
-
| List of 1,000 items, invalid | 180.8 µs | 19.55x | 0.12x | 0.38x | 2.07x | 0.88x | 21.94x | 3.18x | 52.78x | 9.34x |
|
|
428
|
-
| Union of 4 variants (12 events), valid | 2231 ns | 0.15x | 0.22x | 0.25x | 2.45x | 2.95x | 0.43x | 3.36x | 53.20x | 37.54x |
|
|
429
|
-
| Union of 4 variants (12 events), invalid | 3665 ns | 12.15x | 0.16x | 0.84x | 1.99x | 2.21x | 4.48x | 2.53x | 41.04x | 44.78x |
|
|
430
|
-
| 6 levels of nesting, valid | 903.4 ns | 0.03x | 0.11x | 0.06x | 2.05x | 1.42x | 13.08x | 3.43x | 41.87x | 8.52x |
|
|
431
|
-
| 6 levels of nesting, invalid | 1547 ns | 16.33x | 0.10x | 1.29x | 1.80x | 1.53x | 18.79x | 3.06x | 54.03x | 8.16x |
|
|
432
|
-
| Small flat object, checks only, valid | 224.4 ns | 0.28x | 0.30x | 0.28x | 1.86x | 0.88x | 0.32x | 1.99x | 29.54x | 13.13x |
|
|
433
|
-
| Small flat object, checks only, invalid | 824.2 ns | 6.87x | 0.19x | 1.05x | 1.29x | 0.80x | 10.67x | 1.82x | 37.79x | 6.91x |
|
|
434
|
-
|
|
435
|
-
| Node 22 | afora | TypeBox | Ajv | Typia | Zod | Valibot | ArkType | Effect Schema | Yup | Joi |
|
|
436
|
-
| -------------------------------------------------------- | -------: | ------: | ----: | ----: | ----: | ------: | ------: | ------------: | ------: | ------: |
|
|
437
|
-
| Small flat object, valid | 570.7 ns | 0.15x | 0.14x | 0.16x | 1.29x | 1.05x | 9.74x | 2.50x | 10.93x | 7.53x |
|
|
438
|
-
| Small flat object, invalid | 951.7 ns | 8.05x | 0.13x | 0.61x | 2.63x | 0.99x | 25.38x | 3.59x | 117.28x | 6.52x |
|
|
439
|
-
| Nested user (address, 5 tags max, 10 addresses), valid | 4313 ns | 0.11x | 0.18x | 0.11x | 1.14x | 1.06x | 12.83x | 2.70x | 21.85x | 5.47x |
|
|
440
|
-
| Nested user (address, 5 tags max, 10 addresses), invalid | 5472 ns | 8.29x | 0.18x | 0.75x | 1.63x | 1.16x | 20.80x | 3.07x | 57.50x | 5.97x |
|
|
441
|
-
| API request body (an order with 5 items), valid | 4984 ns | 0.28x | 0.35x | 0.20x | 1.14x | 1.10x | 9.27x | 2.20x | 19.37x | 5.38x |
|
|
442
|
-
| API request body (an order with 5 items), invalid | 6311 ns | 4.83x | 0.19x | 0.81x | 1.88x | 1.13x | 15.79x | 2.54x | 52.78x | 5.44x |
|
|
443
|
-
| List of 1,000 items, valid | 346.1 µs | 0.04x | 0.09x | 0.05x | 0.64x | 1.11x | 16.95x | 2.89x | 28.12x | 6.32x |
|
|
444
|
-
| List of 1,000 items, invalid | 347.0 µs | 15.48x | 0.10x | 0.15x | 0.66x | 1.06x | 21.82x | 2.87x | 30.03x | 6.29x |
|
|
445
|
-
| Union of 4 variants (12 events), valid | 969.6 ns | 0.53x | 0.77x | 0.61x | 4.86x | 9.94x | 2.46x | 13.66x | 125.51x | 105.95x |
|
|
446
|
-
| Union of 4 variants (12 events), invalid | 4865 ns | 12.44x | 0.18x | 0.68x | 1.68x | 2.33x | 7.17x | 3.24x | 44.16x | 37.49x |
|
|
447
|
-
| 6 levels of nesting, valid | 1454 ns | 0.06x | 0.10x | 0.07x | 0.86x | 1.34x | 15.58x | 3.86x | 23.21x | 5.99x |
|
|
448
|
-
| 6 levels of nesting, invalid | 1862 ns | 19.39x | 0.11x | 1.63x | 1.91x | 1.79x | 26.89x | 4.77x | 88.54x | 7.14x |
|
|
449
|
-
| Small flat object, checks only, valid | 399.9 ns | 0.21x | 0.21x | 0.23x | 0.81x | 1.02x | 0.51x | 2.03x | 14.22x | 9.91x |
|
|
450
|
-
| Small flat object, checks only, invalid | 892.3 ns | 8.72x | 0.14x | 0.70x | 2.40x | 0.98x | 21.21x | 3.29x | 119.51x | 6.98x |
|
|
368
|
+
afora 0.0.11 on Bun 1.4.4, Node v22.23.4 and Node v24.22.2, AMD EPYC 9V74 80-Core Processor; generated from `bench/results/latest.json`. Every case, runtime and library, and how it is measured: [Performance](docs/performance.md).
|
|
451
369
|
|
|
452
370
|
<!-- bench:end -->
|
|
453
371
|
|
|
454
|
-
What the table says, for `blueprint.safeParse`, on a GitHub runner (AMD EPYC, Linux, Bun 1.4.4 and Node 24). The table is of afora at commit `8c4395e`; what changed after it is said where it applies.
|
|
455
|
-
|
|
456
|
-
- **Against Zod 4.** On Bun, faster in 12 of the 14 cases, by 1.05x to 2.25x; Zod 4 is ahead on the valid nested object (7%). On Node, faster in 9 of the 14, by 1.2x to 3.9x; Zod 4 is ahead on the list of 1,000 items (1.4x to 1.5x), on the valid deep object (1.3x) and on the valid flat object with nothing to transform (1.2x). The invalid union is told apart below.
|
|
457
|
-
- **Against Valibot.** On Node afora is faster in 13 of the 14 cases, by 1.02x to 2.9x outside the valid union (14.5x). On Bun it is the other way: Valibot is ahead in 11 of them, within 15% on small objects and by 1.5x to 2.4x on the valid nested object, the valid API body and the valid list, and afora is ahead on the valid union (2x) and the deep object (1.5x to 1.6x).
|
|
458
|
-
- **Against Effect Schema, Joi and Yup.** Faster in every case but the invalid union: 1.35x to 5.4x Effect Schema, 3.8x to 15x Joi and 12x to 75x Yup, and more than that on the valid union (up to 13x, 94x and 91x).
|
|
459
|
-
- **Against ArkType.** Faster wherever a value is transformed or rejected, by 4.7x to 28x, because its morphs and its errors take a slower path. With nothing to transform and a valid value, ArkType is 2.3x to 3x faster than afora, and 3.8x on the valid union on Bun.
|
|
460
|
-
- **An invalid union.** In the table it takes about 10x the time of Zod 4: TypeBox `Errors` reported every variant of the union for each rejected value. Since then a property whose schema is a discriminated union tells a rejected value by the variant it names, without `Errors`, and takes about 0.5x the time of Zod 4 on Bun (measured on an Apple M2; the table follows at the next measurement). Valid values of the same union are 1.8x to 3.9x faster than Zod 4.
|
|
461
|
-
- **Floor.** The checkers that compile and do not transform (TypeBox, Ajv, Typia) are 3x to 9x faster than afora on a valid small object, and 10x to 70x on the larger ones. afora builds on TypeBox. On invalid input afora is 5x to 24x faster than TypeBox `Errors` (outside the union), and Ajv stays 5x to 11x ahead.
|
|
462
|
-
- **Records and entities.** `Record.safeParse`, which also creates the instance, takes 1.0x to 2.1x the time of `blueprint.safeParse` on Bun and up to 4x on Node. `Entity.safeParse` also makes an id and the time stamps, which on a small object is most of its time: 5x to 13x `blueprint.safeParse` on the flat object in the table, 1.0x to 4.7x on the larger ones; since then it takes about three quarters of that on a small object, for not checking again the id and the date it has just made. `new Record(value)` throws on invalid input, which costs an exception with its trace (2x to 6x `blueprint.safeParse` on Bun, 2.5x to 13x on Node); use `safeParse` where invalid input is expected.
|
|
463
|
-
- **Bundle and cold start.** afora is a framework with one entry point: validating one object bundles to 100 kB gzipped (Zod 4: 24 kB, Valibot: 1.7 kB) and takes 40 ms to load, build and run once in a new Node process (85 ms on Bun; Zod 4: 7 to 8 ms).
|
|
464
|
-
|
|
465
|
-
What afora does that the fast rows do not all do: a pipeline per property (`preHandle`, schema check, `afterHandle`), where a property with a handler has the shape of the value checked first, so handlers only see the right types; objects walked key by key instead of one compiled function; frozen results; every issue with `code`, `path` and `source`; and, for `Record.safeParse` and `new Record`, creating the instance. If you validate bulk data in a hot path and need none of that, a compiled checker alone is an order of magnitude faster.
|
|
466
|
-
|
|
467
|
-
CI keeps it there: `bun run bench:guard` times `blueprint.safeParse` and Zod 4 `safeParse` on the fourteen cases and fails when afora is over the limit of a case as a multiple of Zod 4 (1.15x unless `bench/guard.limits.ts` states another, with the reason).
|
|
468
|
-
|
|
469
|
-
## Comparison
|
|
470
|
-
|
|
471
|
-
A rough guide, not a verdict. "Partial" means it is possible but not what the library is for.
|
|
472
|
-
|
|
473
|
-
| | afora | Zod 4 | Valibot | Effect Schema |
|
|
474
|
-
| --------------------------- | ---------------------------------------------- | ------------------- | -------------- | ---------------------------------- |
|
|
475
|
-
| Standard Schema V1 | yes, on every field | yes | yes | yes |
|
|
476
|
-
| Transforms | yes (`preHandle`, `afterHandle`) | yes | yes | yes |
|
|
477
|
-
| Domain entities / classes | yes (records with change methods and effects) | no | no | partial (`Schema.Class`) |
|
|
478
|
-
| Sensitive masking | yes (`sensitive`, in `toJSON`) | no | no | partial (`Redacted`) |
|
|
479
|
-
| Layered errors with a trace | yes (`ExceptionLayers`, `trace`) | no | no | partial (tagged errors, no layers) |
|
|
480
|
-
| Runtime speed | slower; see Performance | faster | faster | not measured here |
|
|
481
|
-
| Bundle size | not measured; depends on TypeBox and `slugify` | larger than Valibot | small, modular | larger |
|
|
482
|
-
| Ecosystem and maturity | new, small | very large | large | large, in the Effect ecosystem |
|
|
483
|
-
|
|
484
|
-
Where the others win: Zod and Valibot are faster, have far larger ecosystems and documentation, and have integrations and code generators for most tools; Valibot is modular and small; Effect Schema fits a codebase already built on Effect. afora gives up those to model entities, masking and layers in the type you already validate with.
|
|
485
|
-
|
|
486
372
|
## Contributing
|
|
487
373
|
|
|
488
|
-
Read [CONTRIBUTING.md](CONTRIBUTING.md) for the setup, the checks and how releases work.
|
|
489
|
-
|
|
490
|
-
Commits follow [Conventional Commits](https://www.conventionalcommits.org) (`feat(repository): …`, `fix: …`), checked by commitlint in a Husky `commit-msg` hook; the `pre-commit` hook runs Biome and Knip. CI runs lint, Knip, type checks, unit and interop tests, the build and the Node smoke test on every push and pull request. A pull request that bumps the version in `package.json`, once merged to `main`, publishes to npm with provenance and creates the tag and the GitHub release.
|
|
491
|
-
|
|
492
|
-
Scripts:
|
|
493
|
-
|
|
494
|
-
```bash
|
|
495
|
-
bun install
|
|
496
|
-
bun test # unit tests
|
|
497
|
-
bun check # type check
|
|
498
|
-
bun run test:types # build, then type-check the packed package on TypeScript, bundler and nodenext resolution
|
|
499
|
-
bun run test:type-perf # build, then budget the editor cost per edit and snapshot hovers, completions and errors
|
|
500
|
-
bun run test:api # build, then snapshot the public surface (exports and declarations) and the afora.json schema
|
|
501
|
-
bun run test:interop # Hono, tRPC and TanStack Form tests (examples/interop), including the quick start
|
|
502
|
-
bun run test:blog # the generated blog (examples/blog): drift, API and extraction
|
|
503
|
-
bun run test:agent-built # the agent-built example (examples/agent-built): drift, replay, API and the invariant evaluation
|
|
504
|
-
bun run smoke # build, then run the package on plain Node
|
|
505
|
-
bun run bench # benchmark against TypeBox, Ajv, Typia, Zod, Valibot, ArkType, Effect Schema, Yup and Joi
|
|
506
|
-
bun run lint # biome lint
|
|
507
|
-
bun run knip # unused files, exports and dependencies
|
|
508
|
-
bun run fmt # biome format + fix
|
|
509
|
-
bun run build # build dist/ (ESM + .d.ts)
|
|
510
|
-
bun run test:codegen # tests of packages/codegen
|
|
511
|
-
bun run test:mcp # tests of packages/mcp
|
|
512
|
-
bun run test:hono # tests of packages/hono
|
|
513
|
-
bun run test:fastify # tests of packages/fastify (also test:express, test:elysia)
|
|
514
|
-
bun run test:ws # tests of packages/ws
|
|
515
|
-
bun run test:drizzle # tests of packages/drizzle (SQLite and PGlite)
|
|
516
|
-
bun run test:dynamodb # tests of packages/dynamodb (DynamoDB Local, with DYNAMODB_ENDPOINT)
|
|
517
|
-
bun run test:otel # tests of packages/otel
|
|
518
|
-
bun run build:packages # build the core, then packages/codegen, packages/mcp, packages/hono, packages/fastify, packages/express, packages/elysia, packages/ws, packages/drizzle, packages/dynamodb and packages/otel
|
|
519
|
-
```
|
|
520
|
-
|
|
521
|
-
## Versioning
|
|
522
|
-
|
|
523
|
-
What is stable, what may break and how deprecations work is in [VERSIONING.md](VERSIONING.md).
|
|
374
|
+
Read [CONTRIBUTING.md](CONTRIBUTING.md) for the setup, the checks and how releases work. Questions go to [Discussions](https://github.com/afora-framework/core/discussions); security issues go through [SECURITY.md](SECURITY.md), never a public issue. What is stable and how deprecations work is in [VERSIONING.md](VERSIONING.md).
|
|
524
375
|
|
|
525
376
|
## License
|
|
526
377
|
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@afora/core",
|
|
3
|
-
"version": "0.0.
|
|
4
|
-
"description": "
|
|
3
|
+
"version": "0.0.12",
|
|
4
|
+
"description": "Simple to write, built to hold: domain-first TypeScript backends whose guarantees live in the runtime, for people and AI agents alike.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"domain-driven-design",
|
|
7
7
|
"ddd",
|
|
@@ -15,7 +15,12 @@
|
|
|
15
15
|
"validation",
|
|
16
16
|
"schema",
|
|
17
17
|
"typescript",
|
|
18
|
-
"bun"
|
|
18
|
+
"bun",
|
|
19
|
+
"backend",
|
|
20
|
+
"api",
|
|
21
|
+
"codegen",
|
|
22
|
+
"ai-agents",
|
|
23
|
+
"mcp"
|
|
19
24
|
],
|
|
20
25
|
"author": "Alan Reis <alanreisanjo@gmail.com> (https://github.com/Hoyasumii)",
|
|
21
26
|
"license": "MIT",
|