@empyria/common 0.1.6 → 0.1.8

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 (`defineSchema`, `createValidator`, `validate`), 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.                                                                                                                                                                                                                               |
+| [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.                                                                                                                                                                                                                                           |
 
 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

package/lib/Ata.js

@@ -118,6 +118,40 @@ export function validate(schema, input, options) {
 	return validatedInput
 }
 
+/**
+ * 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.
+ * @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.
+ */
+export function createChecker(schema, options) {
+	const v = new Validator(schema, options)
+
+	return (data) => {
+		const result = v.validate(data)
+		return { valid: result.valid, errors: result.valid ? [] : result.errors }
+	}
+}
+
+/**
+ * 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).
+ */
+export function checkSchema(schema, input, options) {
+	return createChecker(schema, options)(input)
+}
+
 /**
  * Re-exported from `ata-validator`:
  * - `renderCompact(errors)` renders a validation error list compactly (one line each).

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@empyria/common",
-	"version": "0.1.6",
+	"version": "0.1.8",
 	"description": "Shared backend goodies for Empyria",
 	"license": "MIT",
 	"author": "Imre Fazekas <imre.fazekas@icloud.com>",
@@ -19,7 +19,7 @@
 		"test:watch": "bun test --watch"
 	},
 	"dependencies": {
-		"@empyria/classification": "0.1.4",
+		"@empyria/classification": "0.1.5",
 		"ata-validator": "1.11.0",
 		"clerobee": "1.0.8",
 		"ms": "2.1.3"
@@ -32,5 +32,5 @@
 		"bun": ">=1.4.0",
 		"node": ">=26"
 	},
-	"packageManager": "bun@1.4.0"
+	"packageManager": "bun@1.4.2"
 }

package/test/Ata.test.js

@@ -7,6 +7,8 @@ import {
 	cloneBySchema,
 	defineSchema,
 	validate,
+	createChecker,
+	checkSchema,
 	bool,
 	string,
 	enumType,
@@ -183,3 +185,28 @@ describe('renderCompact / renderJSON re-exports', () => {
 		expect(typeof renderJSON).toBe('function')
 	})
 })
+
+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:false and a non-empty error list for bad input, without throwing', () => {
+		const result = checkSchema(schema, {})
+		expect(result.valid).toBe(false)
+		expect(Array.isArray(result.errors)).toBe(true)
+		expect(result.errors.length).toBeGreaterThan(0)
+	})
+
+	test('checkSchema errors render through the re-exported renderCompact', () => {
+		const { errors } = checkSchema(schema, {})
+		expect(renderCompact(errors)).toContain('name')
+	})
+
+	test('createChecker builds a reusable checker and forwards options (coerceTypes)', () => {
+		const check = createChecker(defineSchema({ port: number() }), { coerceTypes: true })
+		expect(check({ port: '4040' })).toEqual({ valid: true, errors: [] })
+	})
+})