architex-js 1.5.0 → 1.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "architex-js",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "main": "src/index.js",
   "exports": {
     ".": "./src/index.js",
@@ -9,7 +9,8 @@
     "./microkernel": "./src/microkernel/index.js",
     "./exceptions": "./src/exceptions/index.js",
     "./pipeline": "./src/pipeline/index.js",
-    "./result": "./src/result/index.js"
+    "./result": "./src/result/index.js",
+    "./guards": "./src/guards/index.js"
   },
   "description": "Architectural Toolbox for JavaScript - Providing high-level building blocks for robust systems.",
   "author": {

package/src/guards/Guard.js

@@ -0,0 +1,165 @@
+/**
+ * Defensive programming utilities.
+ * Guard methods throw descriptive errors when assertions fail,
+ * keeping domain invariants clean and readable.
+ *
+ * @example
+ * Guard.notNull(userId, 'userId');
+ * Guard.minLength(username, 3, 'username');
+ * Guard.positiveNumber(price, 'price');
+ */
+class Guard {
+    /**
+     * @param {string} fieldName
+     * @param {string} message
+     */
+    static #fail(fieldName, message) {
+        throw new Error(`[Guard] ${fieldName}: ${message}`);
+    }
+
+    /**
+     * Asserts the value is not null or undefined.
+     * @param {*} value
+     * @param {string} fieldName
+     */
+    static notNull(value, fieldName = 'value') {
+        if (value === null || value === undefined) {
+            Guard.#fail(fieldName, 'must not be null or undefined');
+        }
+        return value;
+    }
+
+    /**
+     * Asserts the string is non-empty after trimming.
+     * @param {string} value
+     * @param {string} fieldName
+     */
+    static notEmpty(value, fieldName = 'value') {
+        Guard.notNull(value, fieldName);
+        if (typeof value !== 'string' || value.trim().length === 0) {
+            Guard.#fail(fieldName, 'must not be an empty string');
+        }
+        return value;
+    }
+
+    /**
+     * Asserts the string has at least `min` characters.
+     * @param {string} value
+     * @param {number} min
+     * @param {string} fieldName
+     */
+    static minLength(value, min, fieldName = 'value') {
+        Guard.notNull(value, fieldName);
+        if (typeof value !== 'string' || value.length < min) {
+            Guard.#fail(fieldName, `must have at least ${min} character(s), got ${value?.length ?? 0}`);
+        }
+        return value;
+    }
+
+    /**
+     * Asserts the string has at most `max` characters.
+     * @param {string} value
+     * @param {number} max
+     * @param {string} fieldName
+     */
+    static maxLength(value, max, fieldName = 'value') {
+        Guard.notNull(value, fieldName);
+        if (typeof value !== 'string' || value.length > max) {
+            Guard.#fail(fieldName, `must have at most ${max} character(s), got ${value?.length ?? 0}`);
+        }
+        return value;
+    }
+
+    /**
+     * Asserts the number is greater than zero (no zero allowed).
+     * @param {number} value
+     * @param {string} fieldName
+     */
+    static positiveNumber(value, fieldName = 'value') {
+        Guard.notNull(value, fieldName);
+        if (typeof value !== 'number' || value <= 0) {
+            Guard.#fail(fieldName, `must be a positive number, got ${value}`);
+        }
+        return value;
+    }
+
+    /**
+     * Asserts the number is zero or greater.
+     * @param {number} value
+     * @param {string} fieldName
+     */
+    static nonNegativeNumber(value, fieldName = 'value') {
+        Guard.notNull(value, fieldName);
+        if (typeof value !== 'number' || value < 0) {
+            Guard.#fail(fieldName, `must be >= 0, got ${value}`);
+        }
+        return value;
+    }
+
+    /**
+     * Asserts the value falls within a numeric range [min, max].
+     * @param {number} value
+     * @param {number} min
+     * @param {number} max
+     * @param {string} fieldName
+     */
+    static inRange(value, min, max, fieldName = 'value') {
+        Guard.notNull(value, fieldName);
+        if (typeof value !== 'number' || value < min || value > max) {
+            Guard.#fail(fieldName, `must be between ${min} and ${max}, got ${value}`);
+        }
+        return value;
+    }
+
+    /**
+     * Asserts the value matches a regular expression.
+     * @param {string} value
+     * @param {RegExp} pattern
+     * @param {string} fieldName
+     */
+    static matches(value, pattern, fieldName = 'value') {
+        Guard.notNull(value, fieldName);
+        if (typeof value !== 'string' || !pattern.test(value)) {
+            Guard.#fail(fieldName, `must match pattern ${pattern}`);
+        }
+        return value;
+    }
+
+    /**
+     * Asserts the value is a valid email address.
+     * @param {string} value
+     * @param {string} fieldName
+     */
+    static isEmail(value, fieldName = 'value') {
+        return Guard.matches(value, /^[^\s@]+@[^\s@]+\.[^\s@]+$/, fieldName);
+    }
+
+    /**
+     * Asserts the value is one of the allowed options.
+     * @param {*} value
+     * @param {Array} options
+     * @param {string} fieldName
+     */
+    static oneOf(value, options, fieldName = 'value') {
+        Guard.notNull(value, fieldName);
+        if (!options.includes(value)) {
+            Guard.#fail(fieldName, `must be one of [${options.join(', ')}], got "${value}"`);
+        }
+        return value;
+    }
+
+    /**
+     * Asserts the value is an Array with at least one element.
+     * @param {Array} value
+     * @param {string} fieldName
+     */
+    static notEmptyArray(value, fieldName = 'value') {
+        Guard.notNull(value, fieldName);
+        if (!Array.isArray(value) || value.length === 0) {
+            Guard.#fail(fieldName, 'must be a non-empty array');
+        }
+        return value;
+    }
+}
+
+export { Guard };

package/src/guards/index.js

@@ -0,0 +1 @@
+export * from "./Guard.js";

package/src/index.js

@@ -2,4 +2,6 @@ export * from "./abc/index.js";
 export * from "./mixins/index.js";
 export * from "./microkernel/index.js";
 export * from "./exceptions/index.js";
-export * from "./pipeline/index.js";
+export * from "./pipeline/index.js";
+export * from "./result/index.js";
+export * from "./guards/index.js";

package/test/guard.test.js

@@ -0,0 +1,94 @@
+import { describe, it, expect } from 'vitest';
+import { Guard } from '../src/guards/index.js';
+
+describe('Guard', () => {
+    describe('notNull', () => {
+        it('should pass for a valid value', () => {
+            expect(() => Guard.notNull('hello', 'field')).not.toThrow();
+        });
+        it('should throw for null', () => {
+            expect(() => Guard.notNull(null, 'field')).toThrow('[Guard] field: must not be null or undefined');
+        });
+        it('should throw for undefined', () => {
+            expect(() => Guard.notNull(undefined, 'field')).toThrow();
+        });
+    });
+
+    describe('notEmpty', () => {
+        it('should pass for a non-empty string', () => {
+            expect(() => Guard.notEmpty('hello', 'name')).not.toThrow();
+        });
+        it('should throw for an empty string', () => {
+            expect(() => Guard.notEmpty('', 'name')).toThrow();
+        });
+        it('should throw for a whitespace-only string', () => {
+            expect(() => Guard.notEmpty('   ', 'name')).toThrow();
+        });
+    });
+
+    describe('minLength', () => {
+        it('should pass when length >= min', () => {
+            expect(() => Guard.minLength('abc', 3, 'field')).not.toThrow();
+        });
+        it('should throw when length < min', () => {
+            expect(() => Guard.minLength('ab', 3, 'field')).toThrow();
+        });
+    });
+
+    describe('maxLength', () => {
+        it('should pass when length <= max', () => {
+            expect(() => Guard.maxLength('abc', 5, 'field')).not.toThrow();
+        });
+        it('should throw when length > max', () => {
+            expect(() => Guard.maxLength('abcdef', 5, 'field')).toThrow();
+        });
+    });
+
+    describe('positiveNumber', () => {
+        it('should pass for a positive number', () => {
+            expect(() => Guard.positiveNumber(1, 'price')).not.toThrow();
+        });
+        it('should throw for zero', () => {
+            expect(() => Guard.positiveNumber(0, 'price')).toThrow();
+        });
+        it('should throw for negative', () => {
+            expect(() => Guard.positiveNumber(-5, 'price')).toThrow();
+        });
+    });
+
+    describe('inRange', () => {
+        it('should pass for value within range', () => {
+            expect(() => Guard.inRange(5, 1, 10, 'score')).not.toThrow();
+        });
+        it('should throw for value outside range', () => {
+            expect(() => Guard.inRange(11, 1, 10, 'score')).toThrow();
+        });
+    });
+
+    describe('isEmail', () => {
+        it('should pass for a valid email', () => {
+            expect(() => Guard.isEmail('user@example.com', 'email')).not.toThrow();
+        });
+        it('should throw for an invalid email', () => {
+            expect(() => Guard.isEmail('not-an-email', 'email')).toThrow();
+        });
+    });
+
+    describe('oneOf', () => {
+        it('should pass when value is in options', () => {
+            expect(() => Guard.oneOf('active', ['active', 'inactive'], 'status')).not.toThrow();
+        });
+        it('should throw when value is not in options', () => {
+            expect(() => Guard.oneOf('pending', ['active', 'inactive'], 'status')).toThrow();
+        });
+    });
+
+    describe('notEmptyArray', () => {
+        it('should pass for a non-empty array', () => {
+            expect(() => Guard.notEmptyArray([1, 2], 'items')).not.toThrow();
+        });
+        it('should throw for an empty array', () => {
+            expect(() => Guard.notEmptyArray([], 'items')).toThrow();
+        });
+    });
+});