@empyria/common

Shared backend services for higher-level components in Empyria, a nanoservice framework built primarily on Bun: environment variable schemas, error definitions, Codogram (SMS/TOTP-style challenge codes), and Ata (JSON schema building blocks and validation).

Requirements

• Bun >=1.4.0 or Node.js >=26
• Plain ESM, no build step, no TypeScript

Both requirements come from @empyria/classification, which this package depends on and which uses the native Temporal global for all date/time handling.

Install

bun add @empyria/common

Usage

import { createEnv, BaseErrors, generateCodogram, validate, string } from '@empyria/common'

const envSchema = createEnv({ API_KEY: string() })

throw new BaseErrors.EntityInvalid({ type: 'User', id: 42 })

const pin = generateCodogram('PIN')

Everything is re-exported from the package root via index.js. Individual modules under lib/ can also be imported directly if you only need one:

import { defineSchema } from '@empyria/common/lib/Ata.js'

Modules

Every exported function is documented with JSDoc directly in its source file — hovering a function in VSCode or Zed shows its parameters and return type without any extra tooling, since both editors read JSDoc from plain .js files automatically.

Tests live under test/, one file per module, separate from the lib/ sources.

Validation options

createValidator / validate / parse / createChecker / checkSchema forward ata-validator's options to the underlying Validator. Options are resolved in three layers, last wins:

1. library defaults — setAtaDefaults({ ... }), called once at startup for a deployment-wide policy; getAtaDefaults() reads it back, setAtaDefaults() clears it.
2. schema-bound — defineSchema(map, { validation: { ... } }) stores options on a non-enumerable key, so a schema carries its own parsing policy (schemaOptions(schema) reads it). The schema still serialises and compares as plain JSON Schema.
3. per-call — the options argument to any of the functions above.

formats is merged one level deep, with EMPYRIA_FORMATS always underneath.

Return value / mutation. createValidator & validate return ata-validator's result.data — the same object as the input unless coerceTypes / removeAdditional / useDefaults applied. Those passes also mutate the input object in place, so hand them a copy when the caller must keep its input pristine (as the env.js files do with { ...process.env }). parse / createParser are behavioural aliases for call sites whose intent is to transform rather than merely assert. createChecker / checkSchema now also return data (the parsed value on success, undefined on failure).

Schema builders

Each returns a plain JSON Schema fragment; compose them in defineSchema(map, opts).

Dialect

defineSchema(map, { dialect: 'v1' \| '2020-12' \| 'draft-07' \| <uri> }) stamps $schema (ata-validator reads it to pick the dialect). setDefaultDialect('v1') / getDefaultDialect() set a process-wide default a per-call dialect overrides. v1 differs from 2020-12 only in $dynamicRef scoping and unlocks propertyDependencies; discriminated() works on any dialect (ata supports the keyword as an extension) but dialect: 'v1' makes it spec-legitimate.

defineSchema(map, { strict: 'unevaluated' }) sets unevaluatedProperties: false while leaving additionalProperties open — the composable form of strict, for schemas meant to be allOf-combined.

Scripts

bun run format       # check formatting (oxfmt)
bun run format:fix   # apply formatting
bun run lint         # lint (oxlint)
bun run lint:fix     # lint and fix
bun run test         # run tests with coverage

License

MIT © Imre Fazekas