@empyria/common 0.1.9 → 0.2.0

package/README.md

@@ -41,14 +41,14 @@ import { defineSchema } from '@empyria/common/lib/Ata.js'
 
 ## Modules
 
-| Module                                 | Purpose                                                                                                                                                                                                                                                                                                                     |
-| -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [index.js](./index.js)                 | Package entry point; re-exports every module below plus Moleculer meta helpers (`moleculerMeta`, `moleculerEmpyriaMeta`) and workflow ID helpers (`workflowName`, `workflowId`, `identifyWorkflow`).                                                                                                                        |
-| [lib/Errors.js](./lib/Errors.js)       | `EmpyriaError`, the `ErrorCreator` factory, and `BaseErrors` — Empyria's catalog of pre-built, templated errors.                                                                                                                                                                                                            |
-| [lib/Env.js](./lib/Env.js)             | `createEnv` — builds a service's environment-variable JSON schema from Empyria-wide defaults.                                                                                                                                                                                                                               |
-| [lib/Ata.js](./lib/Ata.js)             | JSON schema building blocks (`string`, `number`, `bool`, `enumType`, `email`, `password`, `ip4`, `ip6`, ...) and validation — throwing (`defineSchema`, `createValidator`, `validate`) or non-throwing/structured (`createChecker`, `checkSchema`) — built on [ata-validator](https://www.npmjs.com/package/ata-validator). |
-| [lib/Codogram.js](./lib/Codogram.js)   | `generateCodogram` — one-time challenge codes (PIN, alphanumeric, alphabetic) for SMS/TOTP-style verification flows.                                                                                                                                                                                                        |
-| [lib/Defaulter.js](./lib/Defaulter.js) | `defaultsFromSchema` — builds a fully-populated default object for a JSON schema.                                                                                                                                                                                                                                           |
+| Module                                 | Purpose                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [index.js](./index.js)                 | Package entry point; re-exports every module below plus Moleculer meta helpers (`moleculerMeta`, `moleculerEmpyriaMeta`) and workflow ID helpers (`workflowName`, `workflowId`, `identifyWorkflow`).                                                                                                                                                                                                                                              |
+| [lib/Errors.js](./lib/Errors.js)       | `EmpyriaError`, the `ErrorCreator` factory, and `BaseErrors` — Empyria's catalog of pre-built, templated errors.                                                                                                                                                                                                                                                                                                                                  |
+| [lib/Env.js](./lib/Env.js)             | `createEnv` — builds a service's environment-variable JSON schema from Empyria-wide defaults; pass `{ closed: true }` to reject undeclared vars and bind `{ coerceTypes, removeAdditional }` to the schema.                                                                                                                                                                                                                                       |
+| [lib/Ata.js](./lib/Ata.js)             | JSON schema building blocks (`string`, `number`, `bool`, `enumType`, `email`, `password`, `ip4`, `ip6`, ...) and validation — throwing (`defineSchema`, `createValidator`, `validate`), transform-intent aliases (`parse`, `createParser`), or non-throwing/structured (`createChecker`, `checkSchema`, now returning the parsed `data`) — built on [ata-validator](https://www.npmjs.com/package/ata-validator). See _Validation options_ below. |
+| [lib/Codogram.js](./lib/Codogram.js)   | `generateCodogram` — one-time challenge codes (PIN, alphanumeric, alphabetic) for SMS/TOTP-style verification flows.                                                                                                                                                                                                                                                                                                                              |
+| [lib/Defaulter.js](./lib/Defaulter.js) | `defaultsFromSchema` — builds a fully-populated default object for a JSON schema.                                                                                                                                                                                                                                                                                                                                                                 |
 
 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
@@ -56,6 +56,40 @@ tooling, since both editors read JSDoc from plain `.js` files automatically.
 
 Tests live under [test/](./test/), one file per module, separate from the `lib/` sources.
 
+## Validation options
+
+`createValidator` / `validate` / `parse` / `createChecker` / `checkSchema` forward
+[`ata-validator`'s options](https://www.npmjs.com/package/ata-validator) 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.
+
+| Option             | What it does (Empyria relevance)                                                                                                              |
+| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| `coerceTypes`      | `"4040"` → `4040` before validation. The reason `env.js` files work — every `process.env` value is a string.                                  |
+| `useDefaults`      | Fill missing props from their schema `default`. **On by default**; every `string()/number()/bool()/enumType()` emits one.                     |
+| `removeAdditional` | Strip keys not covered by the schema. Only visible with `additionalProperties: false` (i.e. `defineSchema({ strict: true })`).                |
+| `assertFormat`     | Whether a `format` mismatch is a hard error. On by default.                                                                                   |
+| `abortEarly`       | Stop at the first error, skip enrichment. For hot verdict-only paths (pair with `createChecker`, not the throwing path).                      |
+| `richErrors`       | Keep `ATA####` codes / doc URLs / hints that `renderPretty` & co. consume. On by default; leave it on.                                        |
+| `verbose`          | Add `parentSchema` to each error (ajv's `verbose`).                                                                                           |
+| `formats`          | Custom `format` checkers. `EMPYRIA_FORMATS` (`empyria-email`, `empyria-password`, `empyria-ipv4`, `empyria-ipv6`) is folded in automatically. |
+
+**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).
+
 ## Scripts
 
 ```bash

package/lib/Ata.js

@@ -31,6 +31,98 @@ export const P_IPv6 = `
 	.replace(/\n/g, '')
 	.trim()
 
+const RE_EMAIL = new RegExp(`^${P_EMAIL}`, 'i')
+const RE_PASS = new RegExp(P_PASS)
+const RE_IPv4 = new RegExp(`^${P_IPv4}`)
+const RE_IPv6 = new RegExp(`^${P_IPv6}`)
+
+/**
+ * Empyria's custom `format` checkers, keyed by the `format` name a schema references.
+ * Registered automatically on every validator this module builds (see `resolveOptions`), so
+ * a schema carrying `{ type: 'string', format: 'empyria-email' }` — as produced by
+ * {@link email}, {@link password}, {@link ip4}, {@link ip6} — is enforced with no per-call
+ * wiring.
+ *
+ * The names are deliberately prefixed rather than reusing `email` / `ipv4` / `ipv6`:
+ * `ata-validator`'s compiled path only lets a custom `formats` entry override a *built-in*
+ * name at the schema root, not on a nested property, whereas an unknown name is honoured
+ * everywhere. A caller's own `options.formats` entry for the same key still wins.
+ *
+ * A schema from {@link email} & co. is only enforced when validated through this module (or
+ * through a validator the caller seeded with this map); a bare `new Validator(schema)` sees
+ * these as unknown (ignored) formats.
+ * @type {Record<string, (value: unknown) => boolean>}
+ */
+export const EMPYRIA_FORMATS = {
+	'empyria-email': (s) => typeof s === 'string' && RE_EMAIL.test(s),
+	'empyria-password': (s) => typeof s === 'string' && RE_PASS.test(s),
+	'empyria-ipv4': (s) => typeof s === 'string' && RE_IPv4.test(s),
+	'empyria-ipv6': (s) => typeof s === 'string' && RE_IPv6.test(s),
+}
+
+/** Non-enumerable key under which {@link defineSchema} stashes a schema's bound options. */
+const SCHEMA_OPTIONS = Symbol('ataOptions')
+
+/** Process-wide default `ata-validator` options; the base layer for every call here. */
+let libraryDefaults = {}
+
+/**
+ * Sets this module's process-wide default `ata-validator` options — the base layer every
+ * {@link createValidator} / {@link validate} / {@link parse} / {@link createChecker} call in
+ * this process starts from. Meant to be called once at startup to express a deployment-wide
+ * policy (e.g. `{ coerceTypes: true }`). Individual calls stay free to override any key, and
+ * a schema built by {@link defineSchema} with a `validation` bag overrides these too.
+ *
+ * Merge order, lowest to highest precedence: **library defaults → schema-bound → per-call**.
+ * `formats` is merged one level deep, with {@link EMPYRIA_FORMATS} always underneath.
+ * @param {import('ata-validator').ValidatorOptions} [options={}] - Replaces the current
+ *   defaults wholesale. Pass `{}` (or call with no argument) to clear them.
+ * @returns {void}
+ */
+export function setAtaDefaults(options = {}) {
+	libraryDefaults = { ...options }
+}
+
+/**
+ * Returns a shallow copy of the current process-wide default options (see {@link setAtaDefaults}).
+ * @returns {import('ata-validator').ValidatorOptions}
+ */
+export function getAtaDefaults() {
+	return { ...libraryDefaults }
+}
+
+/**
+ * Returns a shallow copy of the `ata-validator` options bound to `schema` by
+ * {@link defineSchema}'s `validation` option, or `{}` if none were bound.
+ * @param {Object} schema
+ * @returns {import('ata-validator').ValidatorOptions}
+ */
+export function schemaOptions(schema) {
+	const bound = schema?.[SCHEMA_OPTIONS]
+	return bound ? { ...bound } : {}
+}
+
+/**
+ * Merges the three option layers for a single call and folds in {@link EMPYRIA_FORMATS}.
+ * @param {Object} schema - Schema being validated (may carry bound options).
+ * @param {import('ata-validator').ValidatorOptions} [perCall] - Options passed to this call.
+ * @returns {import('ata-validator').ValidatorOptions}
+ */
+function resolveOptions(schema, perCall) {
+	const bound = schema?.[SCHEMA_OPTIONS] ?? {}
+	return {
+		...libraryDefaults,
+		...bound,
+		...perCall,
+		formats: {
+			...EMPYRIA_FORMATS,
+			...libraryDefaults.formats,
+			...bound.formats,
+			...(perCall && perCall.formats),
+		},
+	}
+}
+
 /**
  * Builds a function that clones only the keys declared on a schema's `properties`.
  * @param {Object} schema - JSON schema with a `properties` map.
@@ -45,12 +137,22 @@ export function cloneBySchema(schema) {
  * Builds a JSON schema object from a flat map of property schemas.
  * @param {Object} schemaDef - Map of property name to its JSON schema.
  * @param {Object} [options={}]
- * @param {boolean} [options.strict] - If true, disallows properties not listed in `schemaDef`.
+ * @param {boolean} [options.strict] - If true, disallows properties not listed in `schemaDef`
+ *   (`additionalProperties: false`). Combine with `validation: { removeAdditional: true }` to
+ *   *strip* unknown keys instead of rejecting them. Ignored when `options.additionalProperties`
+ *   is given.
+ * @param {boolean|Object} [options.additionalProperties] - Explicit `additionalProperties`
+ *   value (a boolean, or a sub-schema for the extra keys). Overrides `options.strict`.
  * @param {boolean} [options.optional] - If true, a property whose own schema carries
  *   `optional: true` is excluded from `required` (that marker is then stripped from the
  *   property itself — never leaked into the resulting schema, since it isn't a real JSON
  *   Schema keyword). Off by default: every declared property is required, exactly as before —
  *   a caller that never sets `optional: true` on any property sees no difference either way.
+ * @param {import('ata-validator').ValidatorOptions} [options.validation] - `ata-validator`
+ *   options bound to the returned schema: every {@link createValidator} / {@link validate} /
+ *   {@link parse} / {@link createChecker} call for it starts from these (below per-call
+ *   options, above {@link setAtaDefaults}). Stored on a non-enumerable key, so the schema
+ *   still serialises and compares as a plain JSON Schema.
  * @returns {Object} A JSON schema: `{ type: 'object', properties, required, additionalProperties }`.
  */
 export function defineSchema(schemaDef, options = {}) {
@@ -70,7 +172,16 @@ export function defineSchema(schemaDef, options = {}) {
 		type: 'object',
 		properties,
 		required,
-		additionalProperties: !options.strict,
+		additionalProperties: defined(options.additionalProperties)
+			? options.additionalProperties
+			: !options.strict,
+	}
+
+	if (options.validation) {
+		Object.defineProperty(schema, SCHEMA_OPTIONS, {
+			value: { ...options.validation },
+			enumerable: false,
+		})
 	}
 
 	return schema
@@ -78,17 +189,26 @@ export function defineSchema(schemaDef, options = {}) {
 
 /**
  * Builds a validating function for a JSON schema.
+ *
+ * Options are resolved in three layers — {@link setAtaDefaults} → the schema's bound
+ * `validation` (see {@link defineSchema}) → the `options` argument here — with the last
+ * winning, and {@link EMPYRIA_FORMATS} always folded into `formats`.
+ *
+ * The returned function returns the schema-shaped value: `ata-validator`'s `result.data`,
+ * which is `data` itself unless `coerceTypes` / `removeAdditional` / `useDefaults` (the last
+ * on by default) applied. Those passes also mutate `data` in place, so pass a copy when the
+ * caller must keep its input pristine (see `createEnv` / the `env.js` files).
  * @param {Object} schema - JSON schema to validate against.
- * @param {Object} [options] - Forwarded to `ata-validator`'s `Validator` constructor
- *   (`coerceTypes`, `removeAdditional`, `useDefaults`, ...). Left unset, validation is
- *   strict: a schema expecting `type: 'number'` rejects `"32"`. Pass `{ coerceTypes: true }`
- *   for input that's inherently string-typed, such as `process.env` (see `createEnv`).
- * @returns {(data: *) => *} Function that returns `data` unchanged if valid.
+ * @param {import('ata-validator').ValidatorOptions} [options] - Per-call options (see above):
+ *   `coerceTypes`, `removeAdditional`, `useDefaults`, `assertFormat`, `abortEarly`,
+ *   `richErrors`, `verbose`, `formats`, ... Left unset, validation is strict: a schema
+ *   expecting `type: 'number'` rejects `"32"`.
+ * @returns {(data: *) => *} Function that returns the (possibly coerced/defaulted) value.
  * @throws {EmpyriaError} `BaseErrors.ValidationError` (with a pretty-rendered violation list
  *   in its `validation` param) if `data` doesn't satisfy the schema.
  */
 export function createValidator(schema, options) {
-	const v = new Validator(schema, options)
+	const v = new Validator(schema, resolveOptions(schema, options))
 
 	return (data) => {
 		const result = v.validate(data)
@@ -99,7 +219,7 @@ export function createValidator(schema, options) {
 				validation: renderPretty(result.errors),
 			})
 		}
-		return data
+		return result.data ?? data
 	}
 }
 
@@ -107,8 +227,8 @@ export function createValidator(schema, options) {
  * Validates `input` against `schema` in one call.
  * @param {Object} schema - JSON schema to validate against.
  * @param {*} input - Value to validate.
- * @param {Object} [options] - Forwarded to {@link createValidator} (see its docs).
- * @returns {*} `input` unchanged, if valid.
+ * @param {import('ata-validator').ValidatorOptions} [options] - Forwarded to {@link createValidator}.
+ * @returns {*} `input` — coerced/defaulted/stripped per the resolved options — if valid.
  * @throws {EmpyriaError} `BaseErrors.ValidationError` if `input` doesn't satisfy the schema.
  */
 export function validate(schema, input, options) {
@@ -118,25 +238,57 @@ export function validate(schema, input, options) {
 	return validatedInput
 }
 
+/**
+ * {@link createValidator} under an intent-revealing name, for call sites whose purpose is to
+ * *transform* input — coerce string-typed values, strip unknown keys, apply schema defaults —
+ * rather than merely assert its shape. Behaviour is identical; the name documents that the
+ * returned value is expected to differ from the input.
+ * @param {Object} schema - JSON schema to validate/parse against.
+ * @param {import('ata-validator').ValidatorOptions} [options] - Typically `{ coerceTypes: true }`
+ *   and/or `{ removeAdditional: true }` (with a closed schema).
+ * @returns {(data: *) => *} Function returning the parsed value.
+ * @throws {EmpyriaError} `BaseErrors.ValidationError` on invalid input.
+ */
+export function createParser(schema, options) {
+	return createValidator(schema, options)
+}
+
+/**
+ * {@link validate} under an intent-revealing name — see {@link createParser}.
+ * @param {Object} schema - JSON schema to parse against.
+ * @param {*} input - Value to parse.
+ * @param {import('ata-validator').ValidatorOptions} [options] - Forwarded to {@link createParser}.
+ * @returns {*} The parsed (coerced/defaulted/stripped) value, if valid.
+ * @throws {EmpyriaError} `BaseErrors.ValidationError` on invalid input.
+ */
+export function parse(schema, input, options) {
+	return createParser(schema, options)(input)
+}
+
 /**
  * Builds a non-throwing checking function for a JSON schema — the structured-result
  * counterpart to {@link createValidator}. Use it when a caller needs `ata-validator`'s own
  * error list (to build its own error type, count violations, or render them itself with
  * {@link renderCompact} / {@link renderJSON}) rather than a `BaseErrors.ValidationError`
- * carrying a pre-rendered string.
+ * carrying a pre-rendered string, or when it wants the parsed value without a `try`/`catch`.
  * @param {Object} schema - JSON schema to validate against.
- * @param {Object} [options] - Forwarded to `ata-validator`'s `Validator` constructor
- *   (see {@link createValidator} for the common flags).
- * @returns {(data: *) => { valid: boolean, errors: Array<Object> }} Function that returns the
- *   verdict and, when invalid, `ata-validator`'s raw error objects (empty array when valid).
- *   Never throws on a validation failure.
+ * @param {import('ata-validator').ValidatorOptions} [options] - Resolved the same way as for
+ *   {@link createValidator} (see its docs for the layers and the common flags).
+ * @returns {(data: *) => { valid: boolean, data: *, errors: Array<Object> }} Function that
+ *   returns the verdict, the parsed value (`data` when valid — coerced/defaulted/stripped per
+ *   the resolved options; `undefined` when invalid), and, when invalid, `ata-validator`'s raw
+ *   error objects (empty array when valid). Never throws on a validation failure.
  */
 export function createChecker(schema, options) {
-	const v = new Validator(schema, options)
+	const v = new Validator(schema, resolveOptions(schema, options))
 
 	return (data) => {
 		const result = v.validate(data)
-		return { valid: result.valid, errors: result.valid ? [] : result.errors }
+		return {
+			valid: result.valid,
+			data: result.valid ? (result.data ?? data) : undefined,
+			errors: result.valid ? [] : result.errors,
+		}
 	}
 }
 
@@ -144,9 +296,9 @@ export function createChecker(schema, options) {
  * Checks `input` against `schema` in one call, without throwing.
  * @param {Object} schema - JSON schema to validate against.
  * @param {*} input - Value to validate.
- * @param {Object} [options] - Forwarded to {@link createChecker} (see its docs).
- * @returns {{ valid: boolean, errors: Array<Object> }} The verdict, plus `ata-validator`'s raw
- *   error objects when invalid (empty array when valid).
+ * @param {import('ata-validator').ValidatorOptions} [options] - Forwarded to {@link createChecker}.
+ * @returns {{ valid: boolean, data: *, errors: Array<Object> }} The verdict, the parsed value
+ *   (when valid), plus `ata-validator`'s raw error objects when invalid.
  */
 export function checkSchema(schema, input, options) {
 	return createChecker(schema, options)(input)
@@ -250,50 +402,54 @@ export function number(defaultValue) {
 }
 
 /**
- * JSON schema for an email-address string, pattern-matched against {@link P_EMAIL}.
- * @returns {Object} String schema with `pattern` and `description` set.
+ * JSON schema for an email-address string, checked against the `email` format
+ * ({@link EMPYRIA_FORMATS}, which mirrors {@link P_EMAIL}).
+ * @returns {Object} String schema with `format` and `description` set.
  */
 export function email() {
 	return {
 		type: 'string',
-		pattern: P_EMAIL,
+		format: 'empyria-email',
 		description: 'Email address',
 	}
 }
 
 /**
- * JSON schema for a password string, pattern-matched against {@link P_PASS}
- * (requires lower-case, upper-case, a digit, and at least 8 characters).
- * @returns {Object} String schema with `pattern` and `description` set.
+ * JSON schema for a password string, checked against the `password` format
+ * ({@link EMPYRIA_FORMATS}, which mirrors {@link P_PASS}: lower-case, upper-case, a digit,
+ * and at least 8 characters).
+ * @returns {Object} String schema with `format` and `description` set.
  */
 export function password() {
 	return {
 		type: 'string',
-		pattern: P_PASS,
+		format: 'empyria-password',
 		description: 'password',
 	}
 }
 
 /**
- * JSON schema for an IPv4-address string, pattern-matched against {@link P_IPv4}.
- * @returns {Object} String schema with `pattern` and `description` set.
+ * JSON schema for an IPv4-address string, checked against the `ipv4` format
+ * ({@link EMPYRIA_FORMATS}, which mirrors {@link P_IPv4}).
+ * @returns {Object} String schema with `format` and `description` set.
  */
 export function ip4() {
 	return {
 		type: 'string',
-		pattern: P_IPv4,
+		format: 'empyria-ipv4',
 		description: 'IP address v4',
 	}
 }
 
 /**
- * JSON schema for an IPv6-address string, pattern-matched against {@link P_IPv6}.
- * @returns {Object} String schema with `pattern` and `description` set.
+ * JSON schema for an IPv6-address string, checked against the `ipv6` format
+ * ({@link EMPYRIA_FORMATS}, which mirrors {@link P_IPv6}).
+ * @returns {Object} String schema with `format` and `description` set.
  */
 export function ip6() {
 	return {
 		type: 'string',
-		pattern: P_IPv6,
+		format: 'empyria-ipv6',
 		description: 'IP address v6',
 	}
 }

package/lib/Env.js

@@ -27,8 +27,17 @@ const DEFAULT_SERVICE_SCHEMA = {
  * Builds a JSON schema for a microservice's environment variables, merging the
  * Empyria-wide defaults with any service-specific additions/overrides.
  * @param {Object} [specificSchema] - Additional or overriding property schemas, keyed by env var name.
+ * @param {Object} [options={}]
+ * @param {boolean} [options.closed] - When true, the schema rejects the whole of
+ *   `process.env` beyond its declared keys and binds `{ coerceTypes: true, removeAdditional:
+ *   true }` to itself, so `validate`/`parse` return an object holding *only* the declared
+ *   vars — no undeclared environment riding along into `settings`. Off by default:
+ *   `additionalProperties: true`, every extra var passes through unchanged.
  * @returns {Object} A JSON schema object (see `defineSchema` in `./Ata.js`).
  */
-export function createEnv(specificSchema) {
-	return defineSchema(Object.assign({}, DEFAULT_SERVICE_SCHEMA, specificSchema))
+export function createEnv(specificSchema, { closed = false } = {}) {
+	return defineSchema(
+		Object.assign({}, DEFAULT_SERVICE_SCHEMA, specificSchema),
+		closed ? { strict: true, validation: { coerceTypes: true, removeAdditional: true } } : {},
+	)
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@empyria/common",
-	"version": "0.1.9",
+	"version": "0.2.0",
 	"description": "Shared backend goodies for Empyria",
 	"license": "MIT",
 	"author": "Imre Fazekas <imre.fazekas@icloud.com>",
@@ -20,7 +20,7 @@
 	},
 	"dependencies": {
 		"@empyria/classification": "0.1.6",
-		"ata-validator": "1.13.2",
+		"ata-validator": "1.14.1",
 		"clerobee": "1.0.8",
 		"ms": "2.1.3"
 	},
@@ -29,7 +29,7 @@
 		"oxlint": "1.82.0"
 	},
 	"engines": {
-		"bun": ">=1.4.0",
+		"bun": ">=1.4.2",
 		"node": ">=26"
 	},
 	"packageManager": "bun@1.4.2"

package/test/Ata.test.js

@@ -7,8 +7,15 @@ import {
 	cloneBySchema,
 	defineSchema,
 	validate,
+	parse,
+	createParser,
+	createValidator,
 	createChecker,
 	checkSchema,
+	schemaOptions,
+	setAtaDefaults,
+	getAtaDefaults,
+	EMPYRIA_FORMATS,
 	bool,
 	string,
 	enumType,
@@ -89,6 +96,31 @@ describe('defineSchema', () => {
 	test('disallows extra properties when strict', () => {
 		expect(defineSchema({ a: string() }, { strict: true }).additionalProperties).toBe(false)
 	})
+
+	test('an explicit additionalProperties overrides strict', () => {
+		expect(
+			defineSchema({ a: string() }, { strict: true, additionalProperties: true })
+				.additionalProperties,
+		).toBe(true)
+		expect(
+			defineSchema({ a: string() }, { additionalProperties: false }).additionalProperties,
+		).toBe(false)
+	})
+
+	test('binds validation options on a non-enumerable key, invisible to JSON/toEqual', () => {
+		const schema = defineSchema(
+			{ a: string() },
+			{ validation: { coerceTypes: true, removeAdditional: true } },
+		)
+		expect(schema).toEqual({
+			type: 'object',
+			properties: { a: { type: 'string' } },
+			required: ['a'],
+			additionalProperties: true,
+		})
+		expect(JSON.stringify(schema)).not.toContain('coerceTypes')
+		expect(schemaOptions(schema)).toEqual({ coerceTypes: true, removeAdditional: true })
+	})
 })
 
 describe('cloneBySchema', () => {
@@ -171,11 +203,11 @@ describe('schema builders', () => {
 		})
 	})
 
-	test('email/password/ip4/ip6 reference their patterns', () => {
-		expect(email().pattern).toBe(P_EMAIL)
-		expect(password().pattern).toBe(P_PASS)
-		expect(ip4().pattern).toBe(P_IPv4)
-		expect(ip6().pattern).toBe(P_IPv6)
+	test('email/password/ip4/ip6 reference their named formats', () => {
+		expect(email().format).toBe('empyria-email')
+		expect(password().format).toBe('empyria-password')
+		expect(ip4().format).toBe('empyria-ipv4')
+		expect(ip6().format).toBe('empyria-ipv6')
 	})
 })
 
@@ -189,8 +221,16 @@ describe('renderCompact / renderJSON re-exports', () => {
 describe('createChecker / checkSchema', () => {
 	const schema = defineSchema({ name: string() })
 
-	test('checkSchema returns valid:true and no errors for good input', () => {
-		expect(checkSchema(schema, { name: 'Bob' })).toEqual({ valid: true, errors: [] })
+	test('checkSchema returns valid:true, the parsed value, and no errors for good input', () => {
+		expect(checkSchema(schema, { name: 'Bob' })).toEqual({
+			valid: true,
+			data: { name: 'Bob' },
+			errors: [],
+		})
+	})
+
+	test('checkSchema reports data:undefined for bad input', () => {
+		expect(checkSchema(schema, {}).data).toBeUndefined()
 	})
 
 	test('checkSchema returns valid:false and a non-empty error list for bad input, without throwing', () => {
@@ -205,8 +245,87 @@ describe('createChecker / checkSchema', () => {
 		expect(renderCompact(errors)).toContain('name')
 	})
 
-	test('createChecker builds a reusable checker and forwards options (coerceTypes)', () => {
+	test('createChecker builds a reusable checker, forwards options, and returns the parsed value', () => {
 		const check = createChecker(defineSchema({ port: number() }), { coerceTypes: true })
-		expect(check({ port: '4040' })).toEqual({ valid: true, errors: [] })
+		expect(check({ port: '4040' })).toEqual({ valid: true, data: { port: 4040 }, errors: [] })
+	})
+})
+
+describe('named formats', () => {
+	test('EMPYRIA_FORMATS enforce their patterns', () => {
+		expect(EMPYRIA_FORMATS['empyria-email']('user@example.com')).toBe(true)
+		expect(EMPYRIA_FORMATS['empyria-email']('user@example!com')).toBe(false)
+		expect(EMPYRIA_FORMATS['empyria-password']('Abcdefg1')).toBe(true)
+		expect(EMPYRIA_FORMATS['empyria-password']('Abcdefgh')).toBe(false)
+		expect(EMPYRIA_FORMATS['empyria-ipv4']('192.168.0.1')).toBe(true)
+		expect(EMPYRIA_FORMATS['empyria-ipv4']('999.0.0.1')).toBe(false)
+	})
+
+	test('a schema from email() is enforced through this module without per-call wiring', () => {
+		const schema = defineSchema({ addr: email() })
+		expect(validate(schema, { addr: 'user@example.com' })).toEqual({ addr: 'user@example.com' })
+		expect(() => validate(schema, { addr: 'nope' })).toThrow(EmpyriaError)
+	})
+
+	test('a schema from password() is enforced (no ata-validator built-in for it)', () => {
+		const schema = defineSchema({ pw: password() })
+		expect(() => validate(schema, { pw: 'weak' })).toThrow(EmpyriaError)
+		expect(validate(schema, { pw: 'Abcdefg1' })).toEqual({ pw: 'Abcdefg1' })
+	})
+
+	test('a per-call formats entry overrides the Empyria default', () => {
+		const schema = defineSchema({ addr: email() })
+		const only = { formats: { 'empyria-email': (s) => s === 'ok@ok.io' } }
+		expect(validate(schema, { addr: 'ok@ok.io' }, only)).toEqual({ addr: 'ok@ok.io' })
+		expect(() => validate(schema, { addr: 'user@example.com' }, only)).toThrow(EmpyriaError)
+	})
+})
+
+describe('option layering: setAtaDefaults / schema-bound / per-call', () => {
+	test('getAtaDefaults starts empty', () => {
+		expect(getAtaDefaults()).toEqual({})
+	})
+
+	test('a library default is applied when no per-call option is given', () => {
+		const schema = defineSchema({ port: number() })
+		expect(() => validate(schema, { port: '8080' })).toThrow(EmpyriaError)
+		setAtaDefaults({ coerceTypes: true })
+		try {
+			expect(validate(schema, { port: '8080' })).toEqual({ port: 8080 })
+		} finally {
+			setAtaDefaults()
+		}
+		expect(getAtaDefaults()).toEqual({})
+	})
+
+	test('schema-bound validation options beat library defaults, per-call beats both', () => {
+		setAtaDefaults({ coerceTypes: false })
+		try {
+			const bound = defineSchema({ port: number() }, { validation: { coerceTypes: true } })
+			// schema-bound coerceTypes:true wins over the library default
+			expect(validate(bound, { port: '80' })).toEqual({ port: 80 })
+			// per-call coerceTypes:false wins over the schema-bound value
+			expect(() => validate(bound, { port: '80' }, { coerceTypes: false })).toThrow(
+				EmpyriaError,
+			)
+		} finally {
+			setAtaDefaults()
+		}
+	})
+})
+
+describe('parse / createParser', () => {
+	test('parse coerces and strips against a closed schema', () => {
+		const schema = defineSchema(
+			{ port: number() },
+			{ strict: true, validation: { coerceTypes: true, removeAdditional: true } },
+		)
+		expect(parse(schema, { port: '3000', stray: 'x' })).toEqual({ port: 3000 })
+	})
+
+	test('createParser is a reusable createValidator under an intent-revealing name', () => {
+		const p = createParser(defineSchema({ n: number() }), { coerceTypes: true })
+		expect(p({ n: '7' })).toEqual({ n: 7 })
+		expect(typeof createValidator).toBe('function')
 	})
 })

package/test/Env.test.js

@@ -1,5 +1,6 @@
 import { describe, test, expect } from 'bun:test'
 import { createEnv } from '../lib/Env.js'
+import { validate, schemaOptions } from '../lib/Ata.js'
 
 describe('createEnv', () => {
 	test('includes the shared service defaults plus service-specific additions', () => {
@@ -15,4 +16,33 @@ describe('createEnv', () => {
 		const schema = createEnv()
 		expect(schema.properties.EMPYRIA_MONGO_URI).toBeUndefined()
 	})
+
+	test('is open by default: undeclared vars pass through untouched', () => {
+		const schema = createEnv()
+		expect(schema.additionalProperties).toBe(true)
+		expect(schemaOptions(schema)).toEqual({})
+		const out = validate(
+			schema,
+			{ NODE_ENV: 'test', UNDECLARED: 'ride-along' },
+			{ coerceTypes: true },
+		)
+		expect(out.UNDECLARED).toBe('ride-along')
+	})
+
+	test('closed: rejects the wider environment and returns only the declared keys', () => {
+		const schema = createEnv({}, { closed: true })
+		expect(schema.additionalProperties).toBe(false)
+		expect(schemaOptions(schema)).toEqual({ coerceTypes: true, removeAdditional: true })
+
+		const out = validate(schema, {
+			NODE_ENV: 'test',
+			EMPYRIA_ID_LENGTH: '48',
+			PATH: '/usr/bin',
+			HOME: '/root',
+		})
+		expect(out.EMPYRIA_ID_LENGTH).toBe(48)
+		expect(out.NODE_ENV).toBe('test')
+		expect(out.PATH).toBeUndefined()
+		expect(out.HOME).toBeUndefined()
+	})
 })