@empyria/common 0.1.0 → 0.1.1

package/AGENTS.md

@@ -1,6 +1,6 @@
 # AGENTS.md
 
-Shared backend services for higher-level components in **Principia**, a nanoservice
+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 + validation).
 

package/README.md

@@ -1,6 +1,6 @@
 # @empyria/common
 
-Shared backend services for higher-level components in **Principia**, a nanoservice
+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).
@@ -43,9 +43,9 @@ import { defineSchema } from '@empyria/common/lib/Ata.js'
 
 | Module                                 | Purpose                                                                                                                                                                                                                                             |
 | -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [index.js](./index.js)                 | Package entry point; re-exports every module below plus Moleculer meta helpers (`moleculerMeta`, `moleculerPrincipiaMeta`) and workflow ID helpers (`workflowName`, `workflowId`, `identifyWorkflow`).                                              |
-| [lib/Errors.js](./lib/Errors.js)       | `PrincipiaError`, the `ErrorCreator` factory, and `BaseErrors` — Principia's catalog of pre-built, templated errors.                                                                                                                                |
-| [lib/Env.js](./lib/Env.js)             | `createEnv` — builds a service's environment-variable JSON schema from Principia-wide defaults.                                                                                                                                                     |
+| [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.                                                                                                                                                                   |

package/index.js

@@ -2,7 +2,7 @@ import { randomUUID as uuid } from 'node:crypto'
 
 import { TRANS } from '@empyria/classification'
 
-import { PrincipiaError, ErrorCreator, BaseErrors } from './lib/Errors.js'
+import { EmpyriaError, ErrorCreator, BaseErrors } from './lib/Errors.js'
 import { createEnv } from './lib/Env.js'
 
 export * from './lib/Ata.js'
@@ -11,17 +11,17 @@ export * from './lib/Codogram.js'
 
 export * from './lib/Defaulter.js'
 
-export { PrincipiaError, ErrorCreator, BaseErrors, createEnv }
+export { EmpyriaError, ErrorCreator, BaseErrors, createEnv }
 
-/** Role tag Moleculer assigns to every Principia microservice. */
+/** Role tag Moleculer assigns to every Empyria microservice. */
 export const MOLECULER_SERVICE_ROLE = 'microservice'
 
 /** The federation's own actor/federation ID, used for system-originated calls. */
-export const PRINCIPIA_FEDERATION_ID =
-	process.env.PRINCIPIA_FEDERATION_ID ?? '563ac2a1-3fe3-4c5f-b20f-6f33e5cbd680'
+export const EMPYRIA_FEDERATION_ID =
+	process.env.EMPYRIA_FEDERATION_ID ?? '563ac2a1-3fe3-4c5f-b20f-6f33e5cbd680'
 
 /**
- * Builds a Moleculer call-context `meta` object carrying Principia's actor/tracing fields.
+ * Builds a Moleculer call-context `meta` object carrying Empyria's actor/tracing fields.
  * @param {Object} params
  * @param {string} params.actor - ID of the user/service making the call.
  * @param {string} params.federation - Federation the call belongs to.
@@ -45,7 +45,7 @@ export function moleculerMeta({ actor, federation, flowID, processID, role, toke
 }
 
 /**
- * Builds a {@link moleculerMeta} object for a system-originated (Principia-as-actor) call,
+ * Builds a {@link moleculerMeta} object for a system-originated (Empyria-as-actor) call,
  * generating a `flowID`/`processID` when not supplied.
  * @param {Object} params
  * @param {string} [params.flowID] - Flow correlation ID; a new UUID is generated if omitted.
@@ -53,10 +53,10 @@ export function moleculerMeta({ actor, federation, flowID, processID, role, toke
  * @param {string} params.tokenKey - Auth token key for the call.
  * @returns {ReturnType<typeof moleculerMeta>}
  */
-export function moleculerPrincipiaMeta({ flowID, processID, tokenKey }) {
+export function moleculerEmpyriaMeta({ flowID, processID, tokenKey }) {
 	return moleculerMeta({
-		actor: PRINCIPIA_FEDERATION_ID,
-		federation: PRINCIPIA_FEDERATION_ID,
+		actor: EMPYRIA_FEDERATION_ID,
+		federation: EMPYRIA_FEDERATION_ID,
 		flowID: flowID ?? uuid(),
 		processID: processID ?? uuid(),
 		role: MOLECULER_SERVICE_ROLE,
@@ -88,12 +88,12 @@ export function workflowId(workflow) {
  * Parses a workflow ID (as produced by {@link workflowId}) back into its service/handler.
  * @param {string} workflowId - A `"SERVICE:HANDLER:<uuid>"`-shaped ID.
  * @returns {{service: string, handler: string}}
- * @throws {PrincipiaError} If `workflowId` doesn't have at least three `:`-separated components.
+ * @throws {EmpyriaError} If `workflowId` doesn't have at least three `:`-separated components.
  */
 export const identifyWorkflow = (workflowId) => {
 	const components = workflowId?.split(':')
 	if (!components || components.length < 3) {
-		throw new PrincipiaError('Invalid workflow ID format')
+		throw new EmpyriaError('Invalid workflow ID format')
 	}
 	return {
 		service: components[0],

package/lib/Ata.js

@@ -67,7 +67,7 @@ export function defineSchema(schemaDef, options = {}) {
  *   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.
- * @throws {PrincipiaError} `BaseErrors.ValidationError` (with a pretty-rendered violation list
+ * @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) {
@@ -92,7 +92,7 @@ export function createValidator(schema, options) {
  * @param {*} input - Value to validate.
  * @param {Object} [options] - Forwarded to {@link createValidator} (see its docs).
  * @returns {*} `input` unchanged, if valid.
- * @throws {PrincipiaError} `BaseErrors.ValidationError` if `input` doesn't satisfy the schema.
+ * @throws {EmpyriaError} `BaseErrors.ValidationError` if `input` doesn't satisfy the schema.
  */
 export function validate(schema, input, options) {
 	const validateInput = createValidator(schema, options)

package/lib/Codogram.js

@@ -3,7 +3,7 @@ import { enumise } from '@empyria/classification'
 import Clerobee from 'clerobee'
 import { BaseErrors } from './Errors.js'
 
-const clerobee = new Clerobee(process.env.PRINCIPIA_ID_LENGTH || 32)
+const clerobee = new Clerobee(process.env.EMPYRIA_ID_LENGTH || 32)
 
 const CPIN = 'PIN'
 const CODE = 'Code'
@@ -26,7 +26,7 @@ const CABN_LENGTH = 6
  * @param {Object} [options={}]
  * @param {number} [options.length] - Overrides the type's default length.
  * @returns {number|string} A numeric PIN for `'PIN'`, otherwise an upper-cased string.
- * @throws {PrincipiaError} `BaseErrors.UnrecognisedType` if `type` isn't one of {@link CODOGRAM_LIST}.
+ * @throws {EmpyriaError} `BaseErrors.UnrecognisedType` if `type` isn't one of {@link CODOGRAM_LIST}.
  */
 export function generateCodogram(type, options = {}) {
 	switch (type) {

package/lib/Env.js

@@ -1,8 +1,8 @@
 import { defineSchema, bool, number, tmpFile, string, logLevel, logFile, nodeEnv } from './Ata.js'
 
-/** Environment schema shared by every Principia microservice. */
+/** Environment schema shared by every Empyria microservice. */
 const DEFAULT_SERVICE_SCHEMA = {
-	PRINCIPIA_ID_LENGTH: number(32),
+	EMPYRIA_ID_LENGTH: number(32),
 
 	TMP_FOLDER: tmpFile(),
 
@@ -16,7 +16,7 @@ const DEFAULT_SERVICE_SCHEMA = {
 	MOLECULER_TRANSPORTER: string('TCP'),
 
 	MOLECULER_CACHE_ENABLED: bool(false),
-	MOLECULER_CACHE_PREFIX: string('Principia'),
+	MOLECULER_CACHE_PREFIX: string('Empyria'),
 	MOLECULER_CACHE_URL: string('redis://redis:6379/15'),
 
 	RESTATE_ADMIN_URL: string('http://restate:9070'),
@@ -25,7 +25,7 @@ const DEFAULT_SERVICE_SCHEMA = {
 
 /**
  * Builds a JSON schema for a microservice's environment variables, merging the
- * Principia-wide defaults with any service-specific additions/overrides.
+ * Empyria-wide defaults with any service-specific additions/overrides.
  * @param {Object} [specificSchema] - Additional or overriding property schemas, keyed by env var name.
  * @returns {Object} A JSON schema object (see `defineSchema` in `./Ata.js`).
  */

package/lib/Errors.js

@@ -3,20 +3,20 @@ import { inherits } from 'util'
 import { templating } from '@empyria/classification'
 
 /**
- * Principia's base error type. Carries a machine-readable `errorName`/`errorCode`
+ * Empyria's base error type. Carries a machine-readable `errorName`/`errorCode`
  * alongside the usual `message`, and captures its own stack trace.
  * @constructor
  * @param {string} message - Human-readable error message.
  * @param {string} [errorName] - Machine-readable error identifier.
  * @param {number} [errorCode] - Numeric error code.
  */
-let PrincipiaError = function (message, errorName, errorCode) {
+let EmpyriaError = function (message, errorName, errorCode) {
 	this.message = message
 	this.errorName = errorName
 	this.errorCode = errorCode
-	Error.captureStackTrace(this, PrincipiaError)
+	Error.captureStackTrace(this, EmpyriaError)
 }
-inherits(PrincipiaError, Error)
+inherits(EmpyriaError, Error)
 
 /**
  * Builds a reusable error factory from a template.
@@ -25,8 +25,8 @@ inherits(PrincipiaError, Error)
  * @param {string} [options.errorName] - Machine-readable error identifier.
  * @param {string} [options.message] - Message template with `{param}` placeholders (see
  *   `templating` in `@empyria/classification`).
- * @returns {(opts?: Object) => PrincipiaError} Function that, given template values, returns a
- *   new {@link PrincipiaError} with its `message` filled in and `params` set to the values used.
+ * @returns {(opts?: Object) => EmpyriaError} Function that, given template values, returns a
+ *   new {@link EmpyriaError} with its `message` filled in and `params` set to the values used.
  */
 let ErrorCreator = function (options = {}) {
 	let errorCode = options.errorCode
@@ -37,7 +37,7 @@ let ErrorCreator = function (options = {}) {
 	let fnc = function (opts = {}) {
 		let newArgs = Object.assign({}, args, opts)
 		let message = templating(options.message, newArgs)
-		let resultError = new PrincipiaError(message, options.errorName || errorCode, errorCode)
+		let resultError = new EmpyriaError(message, options.errorName || errorCode, errorCode)
 		resultError.params = newArgs
 		return resultError
 	}
@@ -45,10 +45,10 @@ let ErrorCreator = function (options = {}) {
 }
 
 /**
- * Principia's catalog of pre-built error factories, one per well-known failure case.
+ * Empyria's catalog of pre-built error factories, one per well-known failure case.
  * Each entry is a function built via {@link ErrorCreator} — call it with the template's
  * parameters (e.g. `BaseErrors.EntityInvalid({ type: 'User', id: 42 })`) to get a
- * {@link PrincipiaError} instance ready to `throw`.
+ * {@link EmpyriaError} instance ready to `throw`.
  */
 let BaseErrors = {
 	InvalidModel: ErrorCreator({
@@ -74,7 +74,7 @@ let BaseErrors = {
 	NotInited: ErrorCreator({
 		errorCode: 599997,
 		errorName: 'NotInited',
-		message: 'Principia is not inited',
+		message: 'Empyria is not inited',
 	}),
 	UnImplemented: ErrorCreator({
 		errorCode: 599998,
@@ -163,4 +163,4 @@ let BaseErrors = {
 	}),
 }
 
-export { PrincipiaError, ErrorCreator, BaseErrors }
+export { EmpyriaError, ErrorCreator, BaseErrors }

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@empyria/common",
-	"version": "0.1.0",
-	"description": "Shared backend goodies for Principia",
+	"version": "0.1.1",
+	"description": "Shared backend goodies for Empyria",
 	"license": "MIT",
 	"author": "Imre Fazekas <imre.fazekas@icloud.com>",
 	"repository": {
@@ -19,7 +19,7 @@
 		"test:watch": "bun test --watch"
 	},
 	"dependencies": {
-		"@empyria/classification": "0.1.0",
+		"@empyria/classification": "0.1.1",
 		"ata-validator": "1.6.1",
 		"clerobee": "1.0.8",
 		"ms": "2.1.3"

package/test/Ata.test.js

@@ -22,7 +22,7 @@ import {
 	renderCompact,
 	renderJSON,
 } from '../lib/Ata.js'
-import { PrincipiaError } from '../lib/Errors.js'
+import { EmpyriaError } from '../lib/Errors.js'
 
 describe('P_EMAIL', () => {
 	const re = new RegExp(`^${P_EMAIL}`, 'i')
@@ -103,12 +103,12 @@ describe('createValidator / validate', () => {
 		expect(validate(schema, { name: 'Bob' })).toEqual({ name: 'Bob' })
 	})
 
-	test('throws a PrincipiaError with a rendered message when invalid', () => {
+	test('throws a EmpyriaError with a rendered message when invalid', () => {
 		try {
 			validate(schema, {})
 			throw new Error('should have thrown')
 		} catch (err) {
-			expect(err).toBeInstanceOf(PrincipiaError)
+			expect(err).toBeInstanceOf(EmpyriaError)
 			expect(err.errorName).toBe('ValidationError')
 			expect(err.message).toContain('name')
 		}
@@ -116,7 +116,7 @@ describe('createValidator / validate', () => {
 
 	test('is strict by default: a numeric string is rejected for a number schema', () => {
 		const numSchema = defineSchema({ port: number() })
-		expect(() => validate(numSchema, { port: '4040' })).toThrow(PrincipiaError)
+		expect(() => validate(numSchema, { port: '4040' })).toThrow(EmpyriaError)
 	})
 
 	test('options are forwarded to the underlying Validator (coerceTypes)', () => {

package/test/Codogram.test.js

@@ -1,6 +1,6 @@
 import { describe, test, expect } from 'bun:test'
 import { generateCodogram, CODOGRAM_LIST, CODOGRAMS } from '../lib/Codogram.js'
-import { PrincipiaError } from '../lib/Errors.js'
+import { EmpyriaError } from '../lib/Errors.js'
 
 describe('generateCodogram', () => {
 	test('PIN: numeric within the default digit range', () => {
@@ -29,7 +29,7 @@ describe('generateCodogram', () => {
 	})
 
 	test('throws for an unrecognised type', () => {
-		expect(() => generateCodogram('nonsense')).toThrow(PrincipiaError)
+		expect(() => generateCodogram('nonsense')).toThrow(EmpyriaError)
 	})
 })
 

package/test/Env.test.js

@@ -6,13 +6,13 @@ describe('createEnv', () => {
 		const schema = createEnv({ CUSTOM_FLAG: { type: 'boolean' } })
 		expect(schema.type).toBe('object')
 		expect(schema.properties.NODE_ENV.default).toBe('local')
-		expect(schema.properties.PRINCIPIA_ID_LENGTH.default).toBe(32)
+		expect(schema.properties.EMPYRIA_ID_LENGTH.default).toBe(32)
 		expect(schema.properties.CUSTOM_FLAG).toEqual({ type: 'boolean' })
 		expect(schema.required).toContain('CUSTOM_FLAG')
 	})
 
 	test('does not include connector-only settings', () => {
 		const schema = createEnv()
-		expect(schema.properties.PRINCIPIA_MONGO_URI).toBeUndefined()
+		expect(schema.properties.EMPYRIA_MONGO_URI).toBeUndefined()
 	})
 })

package/test/Errors.test.js

@@ -1,9 +1,9 @@
 import { describe, test, expect } from 'bun:test'
-import { PrincipiaError, ErrorCreator, BaseErrors } from '../lib/Errors.js'
+import { EmpyriaError, ErrorCreator, BaseErrors } from '../lib/Errors.js'
 
-describe('PrincipiaError', () => {
+describe('EmpyriaError', () => {
 	test('carries message, errorName, and errorCode', () => {
-		const err = new PrincipiaError('Something broke', 'SomeError', 12345)
+		const err = new EmpyriaError('Something broke', 'SomeError', 12345)
 		expect(err).toBeInstanceOf(Error)
 		expect(err.message).toBe('Something broke')
 		expect(err.errorName).toBe('SomeError')
@@ -20,7 +20,7 @@ describe('ErrorCreator', () => {
 			message: 'Value {value} is bad',
 		})
 		const err = factory({ value: 42 })
-		expect(err).toBeInstanceOf(PrincipiaError)
+		expect(err).toBeInstanceOf(EmpyriaError)
 		expect(err.message).toBe('Value 42 is bad')
 		expect(err.errorName).toBe('Custom')
 		expect(err.errorCode).toBe(1)

package/test/index.test.js

@@ -1,13 +1,13 @@
 import { describe, test, expect } from 'bun:test'
 import {
 	MOLECULER_SERVICE_ROLE,
-	PRINCIPIA_FEDERATION_ID,
+	EMPYRIA_FEDERATION_ID,
 	moleculerMeta,
-	moleculerPrincipiaMeta,
+	moleculerEmpyriaMeta,
 	workflowName,
 	workflowId,
 	identifyWorkflow,
-	PrincipiaError,
+	EmpyriaError,
 } from '../index.js'
 
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
@@ -30,19 +30,19 @@ describe('moleculerMeta', () => {
 	})
 })
 
-describe('moleculerPrincipiaMeta', () => {
+describe('moleculerEmpyriaMeta', () => {
 	test('uses the federation ID as actor/federation and generates missing IDs', () => {
 		// Regression test: this used to call an unimported `uuid()` and throw ReferenceError.
-		const meta = moleculerPrincipiaMeta({ tokenKey: 'key' })
-		expect(meta.user.actor).toBe(PRINCIPIA_FEDERATION_ID)
-		expect(meta.user.federation).toBe(PRINCIPIA_FEDERATION_ID)
+		const meta = moleculerEmpyriaMeta({ tokenKey: 'key' })
+		expect(meta.user.actor).toBe(EMPYRIA_FEDERATION_ID)
+		expect(meta.user.federation).toBe(EMPYRIA_FEDERATION_ID)
 		expect(meta.user.role).toBe(MOLECULER_SERVICE_ROLE)
 		expect(meta.user.flowID).toMatch(UUID_RE)
 		expect(meta.user.processID).toMatch(UUID_RE)
 	})
 
 	test('keeps explicitly provided flowID/processID', () => {
-		const meta = moleculerPrincipiaMeta({ flowID: 'f1', processID: 'p1', tokenKey: 'key' })
+		const meta = moleculerEmpyriaMeta({ flowID: 'f1', processID: 'p1', tokenKey: 'key' })
 		expect(meta.user.flowID).toBe('f1')
 		expect(meta.user.processID).toBe('p1')
 	})
@@ -69,8 +69,8 @@ describe('identifyWorkflow', () => {
 		expect(identifyWorkflow(id)).toEqual({ service: 'SVC', handler: 'H' })
 	})
 
-	test('throws a PrincipiaError for a malformed ID', () => {
-		expect(() => identifyWorkflow('too:short')).toThrow(PrincipiaError)
-		expect(() => identifyWorkflow(undefined)).toThrow(PrincipiaError)
+	test('throws a EmpyriaError for a malformed ID', () => {
+		expect(() => identifyWorkflow('too:short')).toThrow(EmpyriaError)
+		expect(() => identifyWorkflow(undefined)).toThrow(EmpyriaError)
 	})
 })