baobox 0.1.0

package/README.md

@@ -0,0 +1,193 @@
+# Baobox
+
+Baobox is a Bun-first, TypeScript-first schema library that targets TypeBox parity while leaving room for Bun-native improvements.
+
+## Install
+
+```bash
+bun add baobox
+```
+
+Requirements:
+
+- `bun >= 1.3.11`
+- `typescript >= 6.0.0`
+
+## Quick Start
+
+```ts
+import Type, {
+  Check,
+  CompileCached,
+  DateCodec,
+  StandardSchemaV1,
+  TryDecode,
+  TryParse,
+} from 'baobox'
+
+const User = Type.Object({
+  id: Type.String(),
+  email: Type.String({ format: 'email' }),
+  age: Type.Number({ minimum: 0 }),
+}, { required: ['id', 'email', 'age'] })
+
+Check(User, { id: 'usr_1', email: 'ada@example.com', age: 37 })
+
+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 })
+
+TryDecode(DateCodec(), '2024-01-01T00:00:00.000Z')
+// { success: true, value: new Date('2024-01-01T00:00:00.000Z') }
+
+const StandardUser = StandardSchemaV1(User)
+StandardUser['~standard'].validate({ id: 'usr_1', email: 'ada@example.com', age: '37' })
+// { value: { id: 'usr_1', email: 'ada@example.com', age: 37 } }
+```
+
+## Choose A Workflow
+
+- `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()`.
+
+## Standard Schema Adapter
+
+```ts
+import { StandardSchemaV1, Type } from 'baobox'
+
+const User = StandardSchemaV1(Type.Object({
+  name: Type.String(),
+  age: Type.Number(),
+}, { required: ['name', 'age'] }))
+
+User['~standard'].validate({ name: 'Ada', age: '37' })
+// { value: { name: 'Ada', age: 37 } }
+```
+
+Baobox also ships the dedicated `baobox/standard` subpath for schema-agnostic integrations.
+
+`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.
+
+## Localized Validation Errors
+
+```ts
+import { Errors, 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' }]
+```
+
+`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.
+
+You can also register scoped or process-default catalogs directly:
+
+```ts
+import { CreateRuntimeContext, LocaleCodes, String, Errors } from 'baobox'
+
+const context = CreateRuntimeContext()
+context.Locale.Register('en_TEST', {
+  ...context.Locale.GetCatalog(LocaleCodes.en_US),
+  INVALID_TYPE: () => 'yarrr-invalid-type',
+})
+context.Locale.Set('en_TEST')
+
+Errors(String(), 42, context)
+// [{ path: '/', code: 'INVALID_TYPE', message: 'yarrr-invalid-type' }]
+```
+
+If you want to seed a scoped runtime with one of the official bundles explicitly, import it from `baobox/locale`:
+
+```ts
+import LocalePacks from 'baobox/locale'
+import { CreateRuntimeContext, Errors, LocaleCodes, String } from 'baobox'
+
+const context = CreateRuntimeContext({ localeCatalogs: [] })
+context.Locale.Register(LocaleCodes.it_IT, LocalePacks.it_IT)
+context.Locale.Set(LocaleCodes.it_IT)
+
+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.
+
+## Guides
+
+- [Choose Check vs TryParse vs Parse vs Compile](docs/workflows.md)
+- [Work with official locale packs and registry scoping](docs/locale-packs.md)
+- [Use Script, Module, and custom registries](docs/script-module-registries.md)
+- [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
+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.
+
+## License
+
+MIT

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

@@ -0,0 +1,14 @@
+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';
+export interface BunFastPathResult {
+    fn: FastCheck;
+    code: string;
+    accelerated: boolean;
+    strategy: FastStrategy;
+}
+export declare function compileBunFastPath(schema: TSchema, context: RuntimeContext): BunFastPathResult | null;
+export declare function checkUint8ArrayCodecValue(value: unknown, minByteLength?: number, maxByteLength?: number, constBytes?: Uint8Array, constBase64?: string): boolean;
+export {};
+//# sourceMappingURL=bun-fast-path.d.ts.map

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

@@ -0,0 +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"}

package/dist/compile/emit.d.ts

@@ -0,0 +1,5 @@
+import type { TSchema } from '../type/schema.js';
+export type EmitSchema = (schema: TSchema, valueExpr: string) => string;
+export declare function emitPrimitiveSchemaCheck(currentSchema: TSchema, valueExpr: string): string | undefined;
+export declare function emitStructuredSchemaCheck(currentSchema: TSchema, valueExpr: string, emitSchema: EmitSchema, nextVar: () => string): string | undefined;
+//# sourceMappingURL=emit.d.ts.map

package/dist/compile/emit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"emit.d.ts","sourceRoot":"","sources":["../../src/compile/emit.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAQV,OAAO,EAIR,MAAM,mBAAmB,CAAC;AAG3B,MAAM,MAAM,UAAU,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,KAAK,MAAM,CAAC;AAsFxE,wBAAgB,wBAAwB,CAAC,aAAa,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAoCtG;AAED,wBAAgB,yBAAyB,CACvC,aAAa,EAAE,OAAO,EACtB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,UAAU,EACtB,OAAO,EAAE,MAAM,MAAM,GACpB,MAAM,GAAG,SAAS,CAqBpB"}

package/dist/compile/index.d.ts

@@ -0,0 +1,57 @@
+import type { Static, StaticDecode, StaticEncode, StaticParse, TSchema } from '../type/schema.js';
+import type { ParseResult, SchemaError } from '../error/errors.js';
+import type { SchemaIssueDiagnostic } from '../error/messages.js';
+import { RuntimeContext } from '../shared/runtime-context.js';
+export interface ValidatorArtifact {
+    body: string;
+    code: string;
+    hash: string;
+}
+export interface CompileOptions {
+    artifact?: ValidatorArtifact;
+    cache?: boolean;
+    context?: RuntimeContext;
+}
+type RuntimeCheck = (value: unknown) => boolean;
+interface CompileResult {
+    accelerated: boolean;
+    body: string;
+    code: string;
+    fn: RuntimeCheck;
+    strategy: string;
+}
+export declare class Validator<T extends TSchema> {
+    private readonly schema;
+    private readonly context;
+    private readonly hash;
+    private readonly artifact;
+    private readonly result;
+    constructor(schema: T, context: RuntimeContext, hash: string, artifact: ValidatorArtifact, result: CompileResult);
+    Artifact(): ValidatorArtifact;
+    Check(value: unknown): value is Static<T>;
+    Clean(value: unknown): StaticParse<T>;
+    Code(): string;
+    Context(): RuntimeContext;
+    Convert(value: unknown): StaticParse<T>;
+    Create(): Static<T>;
+    Decode(value: unknown): StaticDecode<T>;
+    Default(value: unknown): StaticParse<T>;
+    Encode(value: unknown): StaticEncode<T>;
+    Errors(value: unknown): SchemaError[];
+    Explain(value: unknown): SchemaIssueDiagnostic[];
+    Hash(): string;
+    IsAccelerated(): boolean;
+    Parse(value: unknown): StaticParse<T>;
+    Repair(value: unknown): StaticParse<T>;
+    Strategy(): string;
+    TryCreate(): ParseResult<Static<T>>;
+    TryDecode(value: unknown): ParseResult<StaticDecode<T>>;
+    TryEncode(value: unknown): ParseResult<StaticEncode<T>>;
+    TryParse(value: unknown): ParseResult<StaticParse<T>>;
+    TryRepair(value: unknown): ParseResult<StaticParse<T>>;
+}
+export declare function Compile<T extends TSchema>(schema: T): Validator<T>;
+export declare function Compile<T extends TSchema>(schema: T, options: CompileOptions | RuntimeContext): Validator<T>;
+export declare function Code<T extends TSchema>(schema: T, options?: CompileOptions | RuntimeContext): string;
+export default Compile;
+//# sourceMappingURL=index.d.ts.map

package/dist/compile/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/compile/index.ts"],"names":[],"mappings":"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"}