baobox 0.1.0 → 0.1.1-rc.0

package/README.md

@@ -1,6 +1,32 @@
 # Baobox
 
-Baobox is a Bun-first, TypeScript-first schema library that targets TypeBox parity while leaving room for Bun-native improvements.
+[![CI](https://github.com/d4551/baobox/actions/workflows/publish.yml/badge.svg)](https://github.com/d4551/baobox/actions/workflows/publish.yml)
+[![License](https://img.shields.io/github/license/d4551/baobox)](https://github.com/d4551/baobox)
+[![Bun](https://img.shields.io/badge/bun-%3E%3D1.3.11-black?logo=bun)](https://bun.sh)
+[![TypeScript](https://img.shields.io/badge/typescript-%3E%3D6.0.0-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+
+Baobox is a Bun-first, TypeScript-first schema library that keeps the familiar TypeBox-style authoring surface while adding result-first runtime APIs, scoped runtime contexts, compile caching, portable validator artifacts, and schema-interop helpers.
+
+## ELI5
+
+- You describe what valid data looks like once.
+- Baobox can then answer different questions with the same schema:
+  - Is this value valid: `Check`
+  - Can you clean and coerce it safely: `TryParse`
+  - What exactly failed: `Explain` or `Errors`
+  - Can I reuse this on a hot path: `CompileCached`
+  - Can another tool consume the same schema: `StandardSchemaV1`
+- If you do not want exception-driven control flow, use the `Try*` family.
+
+## Why Baobox
+
+- TypeBox-compatible root surface with baobox-only additions at the root entrypoint.
+- Result-first runtime helpers: `TryParse`, `TryDecode`, `TryEncode`, `TryCreate`, and `TryRepair`.
+- Scoped runtime contexts so locale catalogs, registries, settings, and compile caches do not have to be process-global.
+- Compiled validators with cache reuse and portable `Validator.Artifact()` output.
+- Standard Schema V1 adapters for typed baobox schemas and raw JSON-schema-style objects.
+- Built-in codecs for common interop-heavy values: `Uint8Array`, `Date`, `URL`, and `bigint`.
+- Localized validation errors with official bundles for every declared locale code through `baobox/locale`.
 
 ## Install
 
@@ -32,12 +58,14 @@ const User = Type.Object({
 }, { required: ['id', 'email', 'age'] })
 
 Check(User, { id: 'usr_1', email: 'ada@example.com', age: 37 })
+// true
 
 TryParse(Type.Object({ count: Type.Number() }), { count: '5' })
 // { success: true, value: { count: 5 } }
 
 const validator = CompileCached(User)
 validator.Check({ id: 'usr_1', email: 'ada@example.com', age: 37 })
+// true
 
 TryDecode(DateCodec(), '2024-01-01T00:00:00.000Z')
 // { success: true, value: new Date('2024-01-01T00:00:00.000Z') }
@@ -47,68 +75,102 @@ StandardUser['~standard'].validate({ id: 'usr_1', email: 'ada@example.com', age:
 // { value: { id: 'usr_1', email: 'ada@example.com', age: 37 } }
 ```
 
-## Choose A Workflow
+## API Map
 
-- `Check(schema, value)` returns a boolean. Use it when you only need pass/fail validation.
-- `TryParse(schema, value)` runs the full normalization pipeline and returns `{ success, value | errors }`. Use it when the caller needs a non-throwing normalization path.
-- `TryDecode`, `TryEncode`, `TryCreate`, and `TryRepair` extend the same result-first contract to codecs, default generation, and repair flows.
-- `Parse(schema, value)` runs the full value pipeline: clone, default, convert, clean, then validate. It throws `ParseError` when validation still fails.
-- `Explain(schema, value)` returns raw issue metadata plus the localized message and active locale.
-- `Compile(schema)` creates a reusable validator for hot paths, now with per-context compile caching and portable `Validator.Artifact()` output. `Validator.Errors()` uses the same localized error messages as `Value.Errors()`.
+| Problem | API | Result |
+| --- | --- | --- |
+| Fast pass/fail validation | `Check(schema, value)` | `boolean` |
+| Normalize without exceptions | `TryParse(schema, value)` | `ParseResult<T>` |
+| Throwing parity path | `Parse(schema, value)` | normalized value or `ParseError` |
+| Codec decode without exceptions | `TryDecode(schema, value)` | `ParseResult<T>` |
+| Codec encode without exceptions | `TryEncode(schema, value)` | `ParseResult<T>` |
+| Default generation without exceptions | `TryCreate(schema)` | `ParseResult<T>` |
+| Repair without exceptions | `TryRepair(schema, value)` | `ParseResult<T>` |
+| Raw issue metadata plus localized messages | `Explain(schema, value)` | diagnostics array |
+| Reusable hot-path validator | `Compile(schema)` or `CompileCached(schema)` | `Validator` |
+| Reload a prebuilt validator body | `CompileFromArtifact(schema, artifact)` | `Validator` |
+| Adapt to Standard Schema V1 | `StandardSchemaV1(schema)` | standard-compatible wrapper |
 
-## Standard Schema Adapter
+## Result-First Runtime
 
-```ts
-import { StandardSchemaV1, Type } from 'baobox'
-
-const User = StandardSchemaV1(Type.Object({
-  name: Type.String(),
-  age: Type.Number(),
-}, { required: ['name', 'age'] }))
+Baobox keeps `Parse(schema, value)` as the upstream-style throwing path, but the default baobox direction is result-first:
 
-User['~standard'].validate({ name: 'Ada', age: '37' })
-// { value: { name: 'Ada', age: 37 } }
-```
+- `TryParse` runs `Clone -> Default -> Convert -> Clean -> Check`
+- `TryDecode` and `TryEncode` apply codec transforms without exception control flow
+- `TryCreate` and `TryRepair` make default-generation and corrective flows explicit
+- `Explain` preserves issue codes, params, locale, and final message
 
-Baobox also ships the dedicated `baobox/standard` subpath for schema-agnostic integrations.
+If you are writing request handling, config loading, env parsing, or service boundaries, the `Try*` APIs are usually the better fit.
 
-`ToStandardSchema()` is the generic alias when you already have either a baobox schema or a raw JSON schema object. `FromJsonSchema()` is the explicit raw-schema entry point.
+## Compiled Validators
 
-## Localized Validation Errors
+`Compile()` builds a reusable validator object. `CompileCached()` adds per-runtime-context cache reuse. `CompileFromArtifact()` reloads previously emitted validator code.
 
 ```ts
-import { Errors, String } from 'baobox'
-import { System } from 'baobox/system'
+import { CompileCached, CompileFromArtifact, Number, Object } from 'baobox'
 
-System.Locale.Set(System.Locale.ko_KR)
+const schema = Object({
+  count: Number({ minimum: 1 }),
+}, { required: ['count'] })
 
-Errors(String(), 42)
-// [{ path: '/', code: 'INVALID_TYPE', message: 'string이어야 합니다. 현재 값 유형: number' }]
+const validator = CompileCached(schema)
+const artifact = validator.Artifact()
+const loaded = CompileFromArtifact(schema, artifact)
+
+loaded.TryParse({ count: '2' })
+// { success: true, value: { count: 2 } }
 ```
 
-`en_US` is the default locale. Baobox now ships an official bundle for every declared locale code through `baobox/locale`, so declared locales no longer fall back through the registry lookup path. The translated catalog families currently include `de_DE`, `en_US`, the Spanish family (`es_419`, `es_AR`, `es_ES`, `es_MX`), the French family (`fr_CA`, `fr_FR`), `ja_JP`, `ko_KR`, the Portuguese family (`pt_BR`, `pt_PT`), and both Chinese packs (`zh_Hans`, `zh_Hant`). The remaining official bundles currently alias the English catalog until native translations are added.
+Technical details:
+
+- compile caching is scoped to the active runtime context
+- artifacts let you ship emitted validator code instead of regenerating it at startup
+- Bun-specific byte-oriented fast paths are used only when the schema shape makes that safe
 
-You can also register scoped or process-default catalogs directly:
+## Standard Schema Interop
+
+Baobox can expose the same validation logic through the Standard Schema V1 contract.
 
 ```ts
-import { CreateRuntimeContext, LocaleCodes, String, Errors } from 'baobox'
+import { FromJsonSchema, StandardSchemaV1, Type, ToStandardSchema } from 'baobox'
+
+const typed = StandardSchemaV1(Type.Object({
+  name: Type.String(),
+  age: Type.Number(),
+}, { required: ['name', 'age'] }))
 
-const context = CreateRuntimeContext()
-context.Locale.Register('en_TEST', {
-  ...context.Locale.GetCatalog(LocaleCodes.en_US),
-  INVALID_TYPE: () => 'yarrr-invalid-type',
+const raw = FromJsonSchema({
+  type: 'object',
+  properties: {
+    name: { type: 'string' },
+    age: { type: 'number' },
+  },
+  required: ['name', 'age'],
 })
-context.Locale.Set('en_TEST')
 
-Errors(String(), 42, context)
-// [{ path: '/', code: 'INVALID_TYPE', message: 'yarrr-invalid-type' }]
+ToStandardSchema(raw)['~standard'].validate({ name: 'Ada', age: 37 })
 ```
 
-If you want to seed a scoped runtime with one of the official bundles explicitly, import it from `baobox/locale`:
+Use:
+
+- `StandardSchemaV1()` when you want the canonical baobox adapter
+- `ToStandardSchema()` when the input may already be typed or raw
+- `FromJsonSchema()` when the source is explicitly a raw JSON-schema-style object
+
+For schema-agnostic integrations, you can also import from `baobox/standard`.
+
+## Locales And Runtime Contexts
+
+The default runtime context is preloaded with an official bundle for every declared locale code. Native translated catalogs currently ship for `de_DE`, `en_US`, the Spanish family, the French family, `ja_JP`, `ko_KR`, the Portuguese family, and both Chinese packs. Remaining official bundles currently alias the English catalog until native translations are added.
 
 ```ts
 import LocalePacks from 'baobox/locale'
 import { CreateRuntimeContext, Errors, LocaleCodes, String } from 'baobox'
+import { System } from 'baobox/system'
+
+System.Locale.Set(System.Locale.ko_KR)
+Errors(String(), 42)
+// [{ path: '/', code: 'INVALID_TYPE', message: 'string이어야 합니다. 현재 값 유형: number' }]
 
 const context = CreateRuntimeContext({ localeCatalogs: [] })
 context.Locale.Register(LocaleCodes.it_IT, LocalePacks.it_IT)
@@ -118,25 +180,42 @@ Errors(String(), 42, context)
 // [{ path: '/', code: 'INVALID_TYPE', message: 'Expected string, got number' }]
 ```
 
-## Package Contract
-
-- Bun resolves public package entrypoints through the `bun` export condition to raw `src/*.ts` files.
-- Standard ESM consumers resolve to built `dist/*.js` files plus generated declarations.
-- The published JS layout is `dist/index.js`, `dist/value/index.js`, and matching subpath directories, which now aligns with the export map exactly.
-- Supported public entrypoints are:
-  - `baobox`
-  - `baobox/type`
-  - `baobox/value`
-  - `baobox/schema`
-  - `baobox/error`
-  - `baobox/compile`
-  - `baobox/format`
-  - `baobox/guard`
-  - `baobox/system`
-  - `baobox/script`
-  - `baobox/locale`
-  - `baobox/standard`
-- Direct `src/*` imports are used by this repository's tests and local development. They are not part of the published package contract.
+Use runtime contexts when you need:
+
+- per-test or per-worker isolation
+- tenant-specific registries or locale catalogs
+- explicit compile-cache boundaries
+- non-global settings and type-policy changes
+
+## Built-In Codecs
+
+Baobox ships codec helpers for common wire-format boundaries:
+
+- `Uint8ArrayCodec()` for base64 JSON payloads and runtime byte arrays
+- `DateCodec()` for ISO datetime strings to `Date`
+- `URLCodec()` for string to `URL`
+- `BigIntCodec()` for integer-string to `bigint`
+
+These work with the same value and compile APIs as ordinary schemas.
+
+## Public Entrypoints
+
+| Entrypoint | Purpose |
+| --- | --- |
+| `baobox` | Root builders, value helpers, compile helpers, and baobox additions |
+| `baobox/type` | Type builders and static type exports |
+| `baobox/value` | Runtime value operations such as `Check`, `Parse`, `Errors`, `Repair`, `Diff`, and `Patch` |
+| `baobox/schema` | Raw schema runtime plus baobox schema-emitter helpers |
+| `baobox/error` | Structured validation error surface |
+| `baobox/compile` | `Compile`, `Code`, and `Validator` |
+| `baobox/format` | Format registry and format helpers |
+| `baobox/guard` | Guard namespaces aligned with the TypeBox-style guard surface |
+| `baobox/system` | Runtime settings, locale, hashing, memory, and environment helpers |
+| `baobox/script` | Script DSL helpers |
+| `baobox/locale` | Official locale bundles for the declared locale registry |
+| `baobox/standard` | Standard Schema V1 adapter helpers |
+
+Published consumers should only rely on package entrypoints. Direct `src/*` imports are internal to this repository and its tests.
 
 ## Guides
 
@@ -146,21 +225,6 @@ Errors(String(), 42, context)
 - [Package contract and supported imports](docs/package-contract.md)
 - [Parity policy and baobox-only additions](docs/parity-and-extensions.md)
 
-## Parity Policy
-
-- Root exports are maintained as an upstream-complete superset.
-- The `compile`, `error`, `format`, `guard`, `system`, and `value` subpaths are parity-tested against the installed `typebox` package.
-- `baobox/schema` intentionally combines a `typebox/schema`-style raw schema runtime with baobox's schema emitter helpers.
-
-## Bun-Native Fast Paths
-
-- `Compile()` can specialize hot validation paths for Bun when the schema shape makes that safe.
-- `CompileCached()` is the root convenience wrapper for cached validators, and `CompileFromArtifact()` reloads portable artifacts without re-emitting code.
-- `Uint8ArrayCodec()` adds a Bun-first base64 codec surface for binary payloads and supports constant-payload specialization in compiled validators.
-- `DateCodec()`, `URLCodec()`, and `BigIntCodec()` provide built-in codec surfaces for common interop-heavy values.
-- Raw `Uint8Array` constant-byte comparisons can use a Bun `bun:ffi` memcmp fast path when the platform supports it.
-- Bun documents `bun:ffi` as experimental, so baobox keeps the fast path narrow and falls back to non-FFI compiled validation whenever the schema does not require native byte comparison.
-
 ## Repository Scripts
 
 ```bash
@@ -168,25 +232,9 @@ bun run build
 bun run typecheck
 bun test
 bun run bench
-bun run publish:dry-run
-```
-
-`bun run bench` prints comparative validation and codec throughput against the installed `typebox` package so benchmark output stays tied to the current upstream implementation.
-
-## Publishing
-
-Baobox is configured to publish to npm with `bun`.
-
-```bash
-bun run publish:dry-run
-bun publish --access public
 ```
 
-- `prepublishOnly` runs `bun run verify`, so a live publish always rebuilds and reruns the test suite first.
-- GitHub Actions will attempt a publish on pushes to `main`, on published GitHub releases, and through manual workflow dispatch when `package.json` contains a version that is not already on npm.
-- The workflow configures the npm registry on the runner and then requires the repository secret `NPM_TOKEN` before attempting a live publish.
-- For a local first publish, authenticate once with `bunx npm login` before running `bun publish --access public`.
-- Local `.npmrc` files are gitignored so auth tokens do not end up in the repository.
+`bun run bench` compares validation and codec throughput against the installed `typebox` package so performance numbers stay tied to the current upstream implementation.
 
 ## License
 

package/dist/compile/bun-fast-path.d.ts

@@ -1,7 +1,7 @@
 import type { TSchema } from '../type/schema.js';
 import type { RuntimeContext } from '../shared/runtime-context.js';
 type FastCheck = (value: unknown) => boolean;
-type FastStrategy = 'bun-native' | 'bun-native-const' | 'bun-ffi';
+type FastStrategy = 'bun-native' | 'bun-native-const';
 export interface BunFastPathResult {
     fn: FastCheck;
     code: string;

package/dist/compile/bun-fast-path.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bun-fast-path.d.ts","sourceRoot":"","sources":["../../src/compile/bun-fast-path.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAEjD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAwBnE,KAAK,SAAS,GAAG,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;AAC7C,KAAK,YAAY,GAAG,YAAY,GAAG,kBAAkB,GAAG,SAAS,CAAC;AAElE,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,SAAS,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,OAAO,CAAC;IACrB,QAAQ,EAAE,YAAY,CAAC;CACxB;AAuPD,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,OAAO,EACf,OAAO,EAAE,cAAc,GACtB,iBAAiB,GAAG,IAAI,CAc1B;AAED,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,OAAO,EACd,aAAa,CAAC,EAAE,MAAM,EACtB,aAAa,CAAC,EAAE,MAAM,EACtB,UAAU,CAAC,EAAE,UAAU,EACvB,WAAW,CAAC,EAAE,MAAM,GACnB,OAAO,CAET"}
+{"version":3,"file":"bun-fast-path.d.ts","sourceRoot":"","sources":["../../src/compile/bun-fast-path.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAGjD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAyBnE,KAAK,SAAS,GAAG,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;AAC7C,KAAK,YAAY,GAAG,YAAY,GAAG,kBAAkB,CAAC;AAEtD,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,SAAS,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,OAAO,CAAC;IACrB,QAAQ,EAAE,YAAY,CAAC;CACxB;AAwPD,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,OAAO,EACf,OAAO,EAAE,cAAc,GACtB,iBAAiB,GAAG,IAAI,CAc1B;AAED,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,OAAO,EACd,aAAa,CAAC,EAAE,MAAM,EACtB,aAAa,CAAC,EAAE,MAAM,EACtB,UAAU,CAAC,EAAE,UAAU,EACvB,WAAW,CAAC,EAAE,MAAM,GACnB,OAAO,CAET"}