architex-js 1.4.0 → 1.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "architex-js",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "main": "src/index.js",
   "exports": {
     ".": "./src/index.js",
@@ -8,7 +8,9 @@
     "./mixins": "./src/mixins/index.js",
     "./microkernel": "./src/microkernel/index.js",
     "./exceptions": "./src/exceptions/index.js",
-    "./pipeline": "./src/pipeline/index.js"
+    "./pipeline": "./src/pipeline/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/src/result/Result.js

@@ -0,0 +1,149 @@
+/**
+ * Represents the successful outcome of an operation.
+ * @template T
+ */
+class Ok {
+    /** @param {T} value */
+    constructor(value) {
+        this._value = value;
+    }
+
+    /** @returns {true} */
+    isOk() { return true; }
+
+    /** @returns {false} */
+    isFail() { return false; }
+
+    /** @returns {T} */
+    get value() { return this._value; }
+
+    /**
+     * Transforms the inner value with a function.
+     * @template U
+     * @param {(value: T) => U} fn
+     * @returns {Ok<U>}
+     */
+    map(fn) { return new Ok(fn(this._value)); }
+
+    /**
+     * Chains another Result-returning function.
+     * @template U
+     * @param {(value: T) => Result<U>} fn
+     * @returns {Result<U>}
+     */
+    flatMap(fn) { return fn(this._value); }
+
+    /**
+     * Returns the value or the fallback if this is a Fail.
+     * @param {T} _fallback
+     * @returns {T}
+     */
+    getOrElse(_fallback) { return this._value; }
+
+    toString() { return `Ok(${this._value})`; }
+}
+
+/**
+ * Represents the failed outcome of an operation.
+ * @template E
+ */
+class Fail {
+    /** @param {E} error */
+    constructor(error) {
+        this._error = error;
+    }
+
+    /** @returns {false} */
+    isOk() { return false; }
+
+    /** @returns {true} */
+    isFail() { return true; }
+
+    /** @returns {E} */
+    get error() { return this._error; }
+
+    /**
+     * Returns Fail unchanged (map is a no-op on failure).
+     * @returns {Fail<E>}
+     */
+    map(_fn) { return this; }
+
+    /**
+     * Returns Fail unchanged (flatMap is a no-op on failure).
+     * @returns {Fail<E>}
+     */
+    flatMap(_fn) { return this; }
+
+    /**
+     * Returns the fallback value since this is a failure.
+     * @template T
+     * @param {T} fallback
+     * @returns {T}
+     */
+    getOrElse(fallback) { return fallback; }
+
+    toString() { return `Fail(${this._error})`; }
+}
+
+/**
+ * Railway-Oriented Programming: wraps the result of an operation
+ * as either a success (Ok) or a failure (Fail), eliminating try/catch noise.
+ *
+ * @example
+ * const r = Result.ok(42);
+ * if (r.isOk()) console.log(r.value);   // 42
+ *
+ * const e = Result.fail(new Error("boom"));
+ * if (e.isFail()) console.error(e.error);
+ */
+class Result {
+    /**
+     * Creates a successful result.
+     * @template T
+     * @param {T} value
+     * @returns {Ok<T>}
+     */
+    static ok(value) {
+        return new Ok(value);
+    }
+
+    /**
+     * Creates a failed result.
+     * @template E
+     * @param {E} error
+     * @returns {Fail<E>}
+     */
+    static fail(error) {
+        return new Fail(error);
+    }
+
+    /**
+     * Wraps a function that may throw and returns a Result.
+     * @template T
+     * @param {() => T} fn
+     * @returns {Ok<T> | Fail<unknown>}
+     */
+    static try(fn) {
+        try {
+            return new Ok(fn());
+        } catch (e) {
+            return new Fail(e);
+        }
+    }
+
+    /**
+     * Wraps an async function that may throw and returns a Promise<Result>.
+     * @template T
+     * @param {() => Promise<T>} fn
+     * @returns {Promise<Ok<T> | Fail<unknown>>}
+     */
+    static async tryAsync(fn) {
+        try {
+            return new Ok(await fn());
+        } catch (e) {
+            return new Fail(e);
+        }
+    }
+}
+
+export { Result, Ok, Fail };

package/src/result/index.js

@@ -0,0 +1 @@
+export * from "./Result.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();
+        });
+    });
+});

package/test/result.test.js

@@ -0,0 +1,76 @@
+import { describe, it, expect } from 'vitest';
+import { Result, Ok, Fail } from '../src/result/index.js';
+
+describe('Result', () => {
+    it('Result.ok() should create an Ok instance', () => {
+        const r = Result.ok(42);
+        expect(r.isOk()).toBe(true);
+        expect(r.isFail()).toBe(false);
+        expect(r.value).toBe(42);
+    });
+
+    it('Result.fail() should create a Fail instance', () => {
+        const err = new Error('boom');
+        const r = Result.fail(err);
+        expect(r.isOk()).toBe(false);
+        expect(r.isFail()).toBe(true);
+        expect(r.error).toBe(err);
+    });
+
+    it('Ok.map() should transform the value', () => {
+        const r = Result.ok(5).map(x => x * 2);
+        expect(r.isOk()).toBe(true);
+        expect(r.value).toBe(10);
+    });
+
+    it('Fail.map() should be a no-op and preserve the error', () => {
+        const err = new Error('fail');
+        const r = Result.fail(err).map(x => x * 2);
+        expect(r.isFail()).toBe(true);
+        expect(r.error).toBe(err);
+    });
+
+    it('Ok.flatMap() should chain another Result', () => {
+        const r = Result.ok(5).flatMap(x => Result.ok(x + 10));
+        expect(r.value).toBe(15);
+    });
+
+    it('Fail.flatMap() should be a no-op', () => {
+        const err = new Error('fail');
+        const r = Result.fail(err).flatMap(x => Result.ok(x + 10));
+        expect(r.isFail()).toBe(true);
+        expect(r.error).toBe(err);
+    });
+
+    it('Ok.getOrElse() should return the value', () => {
+        expect(Result.ok('hello').getOrElse('fallback')).toBe('hello');
+    });
+
+    it('Fail.getOrElse() should return the fallback', () => {
+        expect(Result.fail(new Error()).getOrElse('fallback')).toBe('fallback');
+    });
+
+    it('Result.try() should wrap a throwing function in Fail', () => {
+        const r = Result.try(() => { throw new Error('oops'); });
+        expect(r.isFail()).toBe(true);
+        expect(r.error.message).toBe('oops');
+    });
+
+    it('Result.try() should wrap a successful function in Ok', () => {
+        const r = Result.try(() => 99);
+        expect(r.isOk()).toBe(true);
+        expect(r.value).toBe(99);
+    });
+
+    it('Result.tryAsync() should wrap a rejected promise in Fail', async () => {
+        const r = await Result.tryAsync(() => Promise.reject(new Error('async error')));
+        expect(r.isFail()).toBe(true);
+        expect(r.error.message).toBe('async error');
+    });
+
+    it('Result.tryAsync() should wrap a resolved promise in Ok', async () => {
+        const r = await Result.tryAsync(() => Promise.resolve('done'));
+        expect(r.isOk()).toBe(true);
+        expect(r.value).toBe('done');
+    });
+});