guarden 1.0.0

package/dist/cjs/env/schema.js

@@ -0,0 +1,313 @@
+"use strict";
+// ============================================================================
+// Guarden — Environment Variable Validation
+// ============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EnvField = void 0;
+exports.envString = envString;
+exports.envNumber = envNumber;
+exports.envBoolean = envBoolean;
+exports.envEnum = envEnum;
+exports.createEnv = createEnv;
+const errors_js_1 = require("../utils/errors.js");
+// -- Field Builder -----------------------------------------------------------
+/**
+ * A builder for defining environment variable validation rules.
+ */
+class EnvField {
+    /** @internal */
+    _config;
+    constructor(config) {
+        this._config = config;
+    }
+    /** Mark the field as required (default). */
+    required() {
+        return new EnvField({ ...this._config, required: true });
+    }
+    /** Mark the field as optional with a default value. */
+    default(value) {
+        return new EnvField({ ...this._config, required: false, defaultValue: value });
+    }
+    /** Add a custom validation rule. */
+    validate(fn) {
+        return new EnvField({
+            ...this._config,
+            validators: [...this._config.validators, fn],
+        });
+    }
+}
+exports.EnvField = EnvField;
+// -- Field Constructors ------------------------------------------------------
+/**
+ * Define a string environment variable.
+ *
+ * @example
+ * ```ts
+ * const env = createEnv({
+ *   DATABASE_URL: envString().url().required(),
+ * });
+ * ```
+ */
+function envString() {
+    return new StringEnvField({
+        type: 'string',
+        required: true,
+        validators: [],
+        transformer: (raw) => raw,
+    });
+}
+class StringEnvField extends EnvField {
+    /** Validate that the string is a valid URL. */
+    url() {
+        return new StringEnvField({
+            ...this._config,
+            validators: [
+                ...this._config.validators,
+                (value) => {
+                    try {
+                        new URL(value);
+                        return null;
+                    }
+                    catch {
+                        return `must be a valid URL`;
+                    }
+                },
+            ],
+        });
+    }
+    /** Validate minimum length. */
+    minLength(min) {
+        return new StringEnvField({
+            ...this._config,
+            validators: [
+                ...this._config.validators,
+                (value) => value.length >= min ? null : `must be at least ${min} characters`,
+            ],
+        });
+    }
+    /** Validate that the string matches a pattern. */
+    matches(pattern) {
+        return new StringEnvField({
+            ...this._config,
+            validators: [
+                ...this._config.validators,
+                (value) => pattern.test(value) ? null : `must match pattern ${pattern.toString()}`,
+            ],
+        });
+    }
+    /** Set a default value. */
+    default(value) {
+        return new StringEnvField({
+            ...this._config,
+            required: false,
+            defaultValue: value,
+        });
+    }
+    /** Mark as required. */
+    required() {
+        return new StringEnvField({ ...this._config, required: true });
+    }
+}
+/**
+ * Define a numeric environment variable.
+ * Automatically coerces the string value to a number.
+ *
+ * @example
+ * ```ts
+ * const env = createEnv({
+ *   PORT: envNumber().port().default(3000),
+ * });
+ * ```
+ */
+function envNumber() {
+    return new NumberEnvField({
+        type: 'number',
+        required: true,
+        validators: [],
+        transformer: (raw) => {
+            const n = Number(raw);
+            if (Number.isNaN(n))
+                throw new Error(`Cannot parse "${raw}" as number`);
+            return n;
+        },
+    });
+}
+class NumberEnvField extends EnvField {
+    /** Validate that the number is a valid port (1-65535). */
+    port() {
+        return new NumberEnvField({
+            ...this._config,
+            validators: [
+                ...this._config.validators,
+                (value) => Number.isInteger(value) && value >= 1 && value <= 65535
+                    ? null
+                    : `must be a valid port (1-65535)`,
+            ],
+        });
+    }
+    /** Validate minimum value. */
+    min(min) {
+        return new NumberEnvField({
+            ...this._config,
+            validators: [
+                ...this._config.validators,
+                (value) => (value >= min ? null : `must be at least ${min}`),
+            ],
+        });
+    }
+    /** Validate maximum value. */
+    max(max) {
+        return new NumberEnvField({
+            ...this._config,
+            validators: [
+                ...this._config.validators,
+                (value) => (value <= max ? null : `must be at most ${max}`),
+            ],
+        });
+    }
+    /** Set a default value. */
+    default(value) {
+        return new NumberEnvField({
+            ...this._config,
+            required: false,
+            defaultValue: value,
+        });
+    }
+    /** Mark as required. */
+    required() {
+        return new NumberEnvField({ ...this._config, required: true });
+    }
+}
+/**
+ * Define a boolean environment variable.
+ * Recognizes: "true", "1", "yes", "on" as true.
+ *
+ * @example
+ * ```ts
+ * const env = createEnv({
+ *   DEBUG: envBoolean().default(false),
+ * });
+ * ```
+ */
+function envBoolean() {
+    return new BooleanEnvField({
+        type: 'boolean',
+        required: true,
+        validators: [],
+        transformer: (raw) => {
+            const lower = raw.trim().toLowerCase();
+            return ['true', '1', 'yes', 'on'].includes(lower);
+        },
+    });
+}
+class BooleanEnvField extends EnvField {
+    /** Set a default value. */
+    default(value) {
+        return new BooleanEnvField({
+            ...this._config,
+            required: false,
+            defaultValue: value,
+        });
+    }
+    /** Mark as required. */
+    required() {
+        return new BooleanEnvField({ ...this._config, required: true });
+    }
+}
+/**
+ * Define an enum environment variable.
+ * Value must be one of the specified options.
+ *
+ * @example
+ * ```ts
+ * const env = createEnv({
+ *   NODE_ENV: envEnum(['development', 'production', 'test'] as const),
+ * });
+ * // env.NODE_ENV is 'development' | 'production' | 'test'
+ * ```
+ */
+function envEnum(values) {
+    return new EnvField({
+        type: 'enum',
+        required: true,
+        validators: [
+            (value) => values.includes(value)
+                ? null
+                : `must be one of: ${values.join(', ')}`,
+        ],
+        transformer: (raw) => raw,
+        enumValues: values,
+    });
+}
+// -- createEnv ---------------------------------------------------------------
+/**
+ * Validate and type-safe environment variables.
+ * Throws `EnvConfigError` at startup if validation fails.
+ *
+ * @example
+ * ```ts
+ * import { createEnv, envString, envNumber, envBoolean, envEnum } from 'guarden/env';
+ *
+ * export const env = createEnv({
+ *   DATABASE_URL: envString().url().required(),
+ *   PORT: envNumber().port().default(3000),
+ *   DEBUG: envBoolean().default(false),
+ *   NODE_ENV: envEnum(['development', 'production', 'test']),
+ * });
+ *
+ * // Fully typed!
+ * env.DATABASE_URL // string
+ * env.PORT         // number
+ * env.DEBUG        // boolean
+ * env.NODE_ENV     // 'development' | 'production' | 'test'
+ * ```
+ */
+function createEnv(schema, source) {
+    const envSource = source ?? (typeof process !== 'undefined' ? process.env : {});
+    const result = {};
+    const errors = [];
+    for (const [key, field] of Object.entries(schema)) {
+        const raw = envSource[key];
+        const config = field._config;
+        // Check if required
+        if (raw === undefined || raw === '') {
+            if (config.required) {
+                errors.push(new errors_js_1.EnvValidationError(key, ['is required but not set']));
+                continue;
+            }
+            if (config.defaultValue !== undefined) {
+                result[key] = config.defaultValue;
+                continue;
+            }
+        }
+        // Transform
+        let value;
+        try {
+            value = config.transformer(raw ?? '');
+        }
+        catch (e) {
+            errors.push(new errors_js_1.EnvValidationError(key, [
+                `transformation failed: ${e instanceof Error ? e.message : String(e)}`,
+            ]));
+            continue;
+        }
+        // Validate
+        const fieldErrors = [];
+        for (const validator of config.validators) {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const error = validator(value);
+            if (error)
+                fieldErrors.push(error);
+        }
+        if (fieldErrors.length > 0) {
+            errors.push(new errors_js_1.EnvValidationError(key, fieldErrors));
+            continue;
+        }
+        result[key] = value;
+    }
+    if (errors.length > 0) {
+        throw new errors_js_1.EnvConfigError(errors);
+    }
+    return result;
+}
+//# sourceMappingURL=schema.js.map

package/dist/cjs/env/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../../src/env/schema.ts"],"names":[],"mappings":"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"}

package/dist/cjs/guards/advanced.js

@@ -0,0 +1,190 @@
+"use strict";
+// ============================================================================
+// Guarden — Advanced Type Guards
+// ============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isNonEmptyString = isNonEmptyString;
+exports.isEmail = isEmail;
+exports.isURL = isURL;
+exports.isUUID = isUUID;
+exports.isISO8601 = isISO8601;
+exports.isJSONString = isJSONString;
+exports.isHexColor = isHexColor;
+exports.isPositiveNumber = isPositiveNumber;
+exports.isNegativeNumber = isNegativeNumber;
+exports.isInteger = isInteger;
+exports.isSafeInteger = isSafeInteger;
+exports.isNonEmptyArray = isNonEmptyArray;
+exports.isInRange = isInRange;
+exports.isOneOf = isOneOf;
+exports.isMatch = isMatch;
+exports.isMinLength = isMinLength;
+exports.isMaxLength = isMaxLength;
+exports.isInstanceOf = isInstanceOf;
+// -- String guards ----------------------------------------------------------
+/**
+ * Check if a value is a non-empty string.
+ */
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.length > 0;
+}
+/**
+ * Check if a value is a string matching an email pattern.
+ */
+function isEmail(value) {
+    if (typeof value !== 'string')
+        return false;
+    // RFC 5322 simplified pattern
+    return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value);
+}
+/**
+ * Check if a value is a valid URL string.
+ */
+function isURL(value) {
+    if (typeof value !== 'string')
+        return false;
+    try {
+        new URL(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Check if a value is a valid UUID (v1-v5).
+ */
+function isUUID(value) {
+    if (typeof value !== 'string')
+        return false;
+    return /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value);
+}
+/**
+ * Check if a value is a valid ISO 8601 date string.
+ */
+function isISO8601(value) {
+    if (typeof value !== 'string')
+        return false;
+    const date = new Date(value);
+    return !Number.isNaN(date.getTime()) && /^\d{4}-\d{2}-\d{2}/.test(value);
+}
+/**
+ * Check if a value is a valid JSON string.
+ */
+function isJSONString(value) {
+    if (typeof value !== 'string')
+        return false;
+    try {
+        JSON.parse(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Check if a value is a string matching a hex color (#fff or #ffffff).
+ */
+function isHexColor(value) {
+    if (typeof value !== 'string')
+        return false;
+    return /^#(?:[0-9a-f]{3}|[0-9a-f]{6}|[0-9a-f]{8})$/i.test(value);
+}
+// -- Number guards ----------------------------------------------------------
+/**
+ * Check if a value is a positive number (> 0).
+ */
+function isPositiveNumber(value) {
+    return typeof value === 'number' && !Number.isNaN(value) && value > 0;
+}
+/**
+ * Check if a value is a negative number (< 0).
+ */
+function isNegativeNumber(value) {
+    return typeof value === 'number' && !Number.isNaN(value) && value < 0;
+}
+/**
+ * Check if a value is an integer.
+ */
+function isInteger(value) {
+    return typeof value === 'number' && Number.isInteger(value);
+}
+/**
+ * Check if a value is a safe integer (within Number.MAX_SAFE_INTEGER bounds).
+ */
+function isSafeInteger(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value);
+}
+// -- Array guards -----------------------------------------------------------
+/**
+ * Check if a value is a non-empty array.
+ */
+function isNonEmptyArray(value) {
+    return Array.isArray(value) && value.length > 0;
+}
+// -- Factory guards ---------------------------------------------------------
+/**
+ * Create a guard that checks if a number is within a range [min, max].
+ *
+ * @example
+ * ```ts
+ * const isPercent = isInRange(0, 100);
+ * isPercent(50)   // true
+ * isPercent(150)  // false
+ * ```
+ */
+function isInRange(min, max) {
+    return (value) => typeof value === 'number' && !Number.isNaN(value) && value >= min && value <= max;
+}
+/**
+ * Create a guard that checks if a value is one of the specified values.
+ *
+ * @example
+ * ```ts
+ * const isDirection = isOneOf(['up', 'down', 'left', 'right'] as const);
+ * if (isDirection(input)) {
+ *   // input is 'up' | 'down' | 'left' | 'right'
+ * }
+ * ```
+ */
+function isOneOf(values) {
+    const valueSet = new Set(values);
+    return (value) => valueSet.has(value);
+}
+/**
+ * Create a guard that checks if a string matches a pattern.
+ *
+ * @example
+ * ```ts
+ * const isSlug = isMatch(/^[a-z0-9-]+$/);
+ * isSlug("hello-world") // true
+ * isSlug("Hello World") // false
+ * ```
+ */
+function isMatch(pattern) {
+    return (value) => typeof value === 'string' && pattern.test(value);
+}
+/**
+ * Create a guard that checks if a string has a minimum length.
+ */
+function isMinLength(min) {
+    return (value) => typeof value === 'string' && value.length >= min;
+}
+/**
+ * Create a guard that checks if a string has a maximum length.
+ */
+function isMaxLength(max) {
+    return (value) => typeof value === 'string' && value.length <= max;
+}
+/**
+ * Check if a value is an instance of a given class.
+ *
+ * @example
+ * ```ts
+ * const isMyError = isInstanceOf(TypeError);
+ * ```
+ */
+function isInstanceOf(constructor) {
+    return (value) => value instanceof constructor;
+}
+//# sourceMappingURL=advanced.js.map

package/dist/cjs/guards/advanced.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"advanced.js","sourceRoot":"","sources":["../../../src/guards/advanced.ts"],"names":[],"mappings":"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"}