exisjs 0.7.4 → 0.7.6

package/dist/validator/tex.js

@@ -8,8 +8,12 @@ const tex_types_1 = require("./tex-types");
 class TexBuilder {
     string(opts) {
         let base = 'string';
-        if (opts?.optional)
+        if (opts?.optional || opts?.default !== undefined)
             base += '?';
+        if (opts?.nullable)
+            base += ' | nullable';
+        if (opts?.nullish)
+            base += ' | nullish';
         if (opts?.min !== undefined)
             base += ` | min:${opts.min}`;
         if (opts?.max !== undefined)
@@ -34,68 +38,94 @@ class TexBuilder {
             base += ' | preventSql';
         if (opts?.preventTraversal)
             base += ' | preventTraversal';
-        return new tex_types_1.TexType(base);
+        return new tex_types_1.TexType(base, opts?.default);
     }
     number(opts) {
         let base = 'number';
-        if (opts?.optional)
+        if (opts?.optional || opts?.default !== undefined)
             base += '?';
+        if (opts?.nullable)
+            base += ' | nullable';
+        if (opts?.nullish)
+            base += ' | nullish';
         if (opts?.coerce)
             base += ' | coerce';
         if (opts?.min !== undefined)
             base += ` | min:${opts.min}`;
         if (opts?.max !== undefined)
             base += ` | max:${opts.max}`;
-        if (opts?.default !== undefined)
-            base += ` | default:${opts.default}`;
-        return new tex_types_1.TexType(base);
+        return new tex_types_1.TexType(base, opts?.default);
     }
     boolean(opts) {
         let base = 'boolean';
-        if (opts?.optional)
+        if (opts?.optional || opts?.default !== undefined)
             base += '?';
+        if (opts?.nullable)
+            base += ' | nullable';
+        if (opts?.nullish)
+            base += ' | nullish';
         if (opts?.coerce)
             base += ' | coerce';
-        return new tex_types_1.TexType(base);
+        return new tex_types_1.TexType(base, opts?.default);
     }
     email(opts) {
         let base = 'email';
-        if (opts?.optional)
+        if (opts?.optional || opts?.default !== undefined)
             base += '?';
+        if (opts?.nullable)
+            base += ' | nullable';
+        if (opts?.nullish)
+            base += ' | nullish';
         if (opts?.trim)
             base += ' | trim';
         if (opts?.toLowerCase)
             base += ' | lowercase';
         if (opts?.mask)
             base += ' | mask';
-        return new tex_types_1.TexType(base);
+        return new tex_types_1.TexType(base, opts?.default);
     }
     uuid(opts) {
         let base = 'uuid';
-        if (opts?.optional)
+        if (opts?.optional || opts?.default !== undefined)
             base += '?';
+        if (opts?.nullable)
+            base += ' | nullable';
+        if (opts?.nullish)
+            base += ' | nullish';
         if (opts?.version)
             base += ` | version:${opts.version}`;
-        return new tex_types_1.TexType(base);
+        return new tex_types_1.TexType(base, opts?.default);
     }
     cuid(opts) {
         let base = 'cuid';
-        if (opts?.optional)
+        if (opts?.optional || opts?.default !== undefined)
             base += '?';
-        return new tex_types_1.TexType(base);
+        if (opts?.nullable)
+            base += ' | nullable';
+        if (opts?.nullish)
+            base += ' | nullish';
+        return new tex_types_1.TexType(base, opts?.default);
     }
     creditCard(opts) {
         let base = 'creditcard';
-        if (opts?.optional)
+        if (opts?.optional || opts?.default !== undefined)
             base += '?';
+        if (opts?.nullable)
+            base += ' | nullable';
+        if (opts?.nullish)
+            base += ' | nullish';
         if (opts?.mask)
             base += ' | mask';
-        return new tex_types_1.TexType(base);
+        return new tex_types_1.TexType(base, opts?.default);
     }
     password(opts) {
         let base = 'password';
-        if (opts?.optional)
+        if (opts?.optional || opts?.default !== undefined)
             base += '?';
+        if (opts?.nullable)
+            base += ' | nullable';
+        if (opts?.nullish)
+            base += ' | nullish';
         if (opts?.min !== undefined)
             base += ` | min:${opts.min}`;
         if (opts?.max !== undefined)
@@ -108,7 +138,7 @@ class TexBuilder {
             base += ' | requireUppercase';
         if (opts?.requireLowercase)
             base += ' | requireLowercase';
-        return new tex_types_1.TexType(base);
+        return new tex_types_1.TexType(base, opts?.default);
     }
     array(schema, opts) {
         let resolvedItem = schema;
@@ -124,7 +154,7 @@ class TexBuilder {
                 ? resolvedItem._raw
                 : resolvedItem;
         let base = `array<${itemSchema}>`;
-        if (opts?.optional)
+        if (opts?.optional || opts?.default !== undefined)
             base += '?';
         if (opts?.nullable)
             base += ' | nullable';
@@ -136,22 +166,30 @@ class TexBuilder {
             base += ` | max:${opts.max}`;
         if (opts?.dedupe)
             base += ' | dedupe';
-        const res = new tex_types_1.TexType(base);
+        if (opts?.coerce)
+            base += ' | coerce';
+        const res = new tex_types_1.TexType(base, opts?.default);
         res._item = resolvedItem;
         return res;
     }
     enum(values, opts) {
         let base = `enum:${values.join(',')}`;
-        if (opts?.optional)
+        if (opts?.optional || opts?.default !== undefined)
             base += '?';
-        if (opts?.default)
-            base += ` | default:${opts.default}`;
-        return new tex_types_1.TexType(base);
+        if (opts?.nullable)
+            base += ' | nullable';
+        if (opts?.nullish)
+            base += ' | nullish';
+        return new tex_types_1.TexType(base, opts?.default);
     }
     literal(value, opts) {
         let base = `literal:${value}`;
         if (opts?.optional)
             base += '?';
+        if (opts?.nullable)
+            base += ' | nullable';
+        if (opts?.nullish)
+            base += ' | nullish';
         return new tex_types_1.TexType(base);
     }
     union(schemas, opts) {
@@ -159,35 +197,57 @@ class TexBuilder {
         let base = items.join(' || ');
         if (opts?.optional)
             base = `(${base})?`;
+        if (opts?.nullable)
+            base += ' | nullable';
+        if (opts?.nullish)
+            base += ' | nullish';
         return new tex_types_1.TexType(base);
     }
     date(opts) {
         let base = 'date';
-        if (opts?.optional)
+        if (opts?.optional || opts?.default !== undefined)
             base += '?';
+        if (opts?.nullable)
+            base += ' | nullable';
+        if (opts?.nullish)
+            base += ' | nullish';
+        if (opts?.coerce)
+            base += ' | coerce';
         if (opts?.minDate)
             base += ` | minDate:${opts.minDate}`;
         if (opts?.maxDate)
             base += ` | maxDate:${opts.maxDate}`;
-        return new tex_types_1.TexType(base);
+        return new tex_types_1.TexType(base, opts?.default);
     }
     record(schema, opts) {
         const itemSchema = schema instanceof tex_types_1.TexType ? schema._raw : schema;
         let base = `record<${itemSchema}>`;
         if (opts?.optional)
             base += '?';
+        if (opts?.nullable)
+            base += ' | nullable';
+        if (opts?.nullish)
+            base += ' | nullish';
         return new tex_types_1.TexType(base);
     }
     any(opts) {
         let base = 'any';
         if (opts?.optional)
             base += '?';
+        if (opts?.nullable)
+            base += ' | nullable';
+        if (opts?.nullish)
+            base += ' | nullish';
         return new tex_types_1.TexType(base);
     }
     file(opts) {
         let base = 'file';
         if (opts?.optional)
             base += '?';
+        if (opts?.nullable)
+            base += ' | nullable';
+        if (opts?.nullish)
+            base += ' | nullish';
         if (opts?.maxSize)
             base += ` | maxSize:${opts.maxSize}`;
         if (opts?.mimeTypes)
@@ -210,6 +270,53 @@ class TexBuilder {
         }
         return new TexEngine(compiledSchema, schema, opts?.strict);
     }
+    /**
+     * Dedicated Environment Schema parser (tex.env).
+     * Automatically coerces numbers, booleans, dates, and arrays from process.env string values,
+     * while preserving strict type validation and defaults.
+     */
+    env(schema, opts) {
+        const coercedSchema = {};
+        for (const [key, value] of Object.entries(schema)) {
+            if (value instanceof tex_types_1.TexType) {
+                let raw = value._raw;
+                // Auto-inject coercion if not already present
+                if ((raw.startsWith('number') ||
+                    raw.startsWith('boolean') ||
+                    raw.startsWith('date') ||
+                    raw.startsWith('array<')) &&
+                    !raw.includes('coerce')) {
+                    raw = `${raw} | coerce`;
+                }
+                const cloned = new tex_types_1.TexType(raw, value.defaultValue);
+                cloned.sanitizers = [...value.sanitizers];
+                cloned.refinements = [...value.refinements];
+                if (value._item) {
+                    ;
+                    cloned._item = value._item;
+                }
+                coercedSchema[key] = cloned;
+            }
+            else if (value instanceof TexEngine) {
+                coercedSchema[key] = value;
+            }
+            else if (typeof value === 'string') {
+                let raw = value;
+                if ((raw.startsWith('number') ||
+                    raw.startsWith('boolean') ||
+                    raw.startsWith('date') ||
+                    raw.startsWith('array<')) &&
+                    !raw.includes('coerce')) {
+                    raw = `${raw} | coerce`;
+                }
+                coercedSchema[key] = new tex_types_1.TexType(raw);
+            }
+            else {
+                coercedSchema[key] = value;
+            }
+        }
+        return this.object(coercedSchema, opts);
+    }
     pagination(options) {
         const defaultLimit = options?.defaultLimit ?? 10;
         const maxLimit = options?.maxLimit ?? 100;
@@ -228,12 +335,60 @@ class TexBuilder {
     }
 }
 exports.TexBuilder = TexBuilder;
+function getNestedValue(obj, path) {
+    if (!obj || typeof obj !== 'object' || !path)
+        return undefined;
+    if (path in obj)
+        return obj[path];
+    try {
+        const keys = path.replace(/\[(\w+)\]/g, '.$1').split('.');
+        let curr = obj;
+        for (const k of keys) {
+            if (curr === undefined || curr === null)
+                return undefined;
+            curr = curr[k];
+        }
+        return curr;
+    }
+    catch {
+        return undefined;
+    }
+}
+function formatReceivedValue(val) {
+    if (val === undefined)
+        return 'undefined';
+    if (val === null)
+        return 'null';
+    if (typeof val === 'string')
+        return JSON.stringify(val);
+    if (typeof val === 'number' || typeof val === 'boolean')
+        return String(val);
+    if (Array.isArray(val)) {
+        try {
+            const str = JSON.stringify(val);
+            return str.length > 30 ? `Array(${val.length})` : str;
+        }
+        catch {
+            return `Array(${val.length})`;
+        }
+    }
+    if (typeof val === 'object') {
+        try {
+            const str = JSON.stringify(val);
+            return str.length > 30 ? '[object Object]' : str;
+        }
+        catch {
+            return '[object Object]';
+        }
+    }
+    return String(val);
+}
 class ValidatorError extends Error {
     constructor(errors) {
         super('Validation Error: ' +
             errors.map((e) => `${e.path}: ${e.message}`).join(', '));
-        this.errors = errors;
         this.name = 'ValidatorError';
+        this.errors = errors;
     }
 }
 exports.ValidatorError = ValidatorError;
@@ -295,9 +450,18 @@ class TexEngine {
         return new TexEngine(newSchema, newRaw, this.strict, this._isOptional);
     }
     parse(data) {
-        // 1. Run pre-validation sanitizers on the raw payload (if it's an object)
+        // 1. Apply defaults and run pre-validation sanitizers on the raw payload (if it's an object)
         if (data && typeof data === 'object') {
             for (const [key, val] of Object.entries(this.rawSchema)) {
+                // Apply default value / lazy factory function if field is omitted or undefined
+                if (data[key] === undefined) {
+                    if (val instanceof tex_types_1.TexType && val.defaultValue !== undefined) {
+                        data[key] =
+                            typeof val.defaultValue === 'function'
+                                ? val.defaultValue()
+                                : val.defaultValue;
+                    }
+                }
                 if (typeof data[key] === 'string' && data[key].trim() === '') {
                     const raw = val instanceof tex_types_1.TexType ? val._raw : String(val);
                     if (raw.includes('optional') ||
@@ -312,12 +476,149 @@ class TexEngine {
                         }
                         else {
                             delete data[key];
+                            // If deleted but default is defined, apply default
+                            if (val instanceof tex_types_1.TexType && val.defaultValue !== undefined) {
+                                data[key] =
+                                    typeof val.defaultValue === 'function'
+                                        ? val.defaultValue()
+                                        : val.defaultValue;
+                            }
                         }
                     }
                 }
                 if (data[key] !== undefined && data[key] !== null) {
+                    if (val instanceof tex_types_1.TexType && val._raw.startsWith('date')) {
+                        if (val._raw.includes('coerce')) {
+                            if (typeof data[key] === 'string' ||
+                                typeof data[key] === 'number') {
+                                const d = new Date(data[key]);
+                                if (isNaN(d.getTime())) {
+                                    throw new ValidatorError([
+                                        {
+                                            path: key,
+                                            message: 'Must be a valid date',
+                                            expected: 'valid date string or timestamp',
+                                            received: formatReceivedValue(data[key]),
+                                            code: 'INVALID_DATE',
+                                        },
+                                    ]);
+                                }
+                                data[key] = d;
+                            }
+                        }
+                        if (!(data[key] instanceof Date) &&
+                            typeof data[key] !== 'string' &&
+                            typeof data[key] !== 'number') {
+                            throw new ValidatorError([
+                                {
+                                    path: key,
+                                    message: 'Must be a valid date',
+                                    expected: 'valid date or date string',
+                                    received: formatReceivedValue(data[key]),
+                                    code: 'INVALID_TYPE',
+                                },
+                            ]);
+                        }
+                        if (data[key] instanceof Date && isNaN(data[key].getTime())) {
+                            throw new ValidatorError([
+                                {
+                                    path: key,
+                                    message: 'Must be a valid date',
+                                    expected: 'valid date string or timestamp',
+                                    received: formatReceivedValue(data[key]),
+                                    code: 'INVALID_DATE',
+                                },
+                            ]);
+                        }
+                        if (val._raw.includes('minDate:')) {
+                            const minStr = val._raw.match(/minDate:([^\s|]+)/)?.[1];
+                            if (minStr &&
+                                new Date(data[key]).getTime() < new Date(minStr).getTime()) {
+                                throw new ValidatorError([
+                                    {
+                                        path: key,
+                                        message: `Date must be after ${minStr}`,
+                                        expected: `>= ${minStr}`,
+                                        received: formatReceivedValue(data[key]),
+                                        code: 'DATE_TOO_EARLY',
+                                    },
+                                ]);
+                            }
+                        }
+                        if (val._raw.includes('maxDate:')) {
+                            const maxStr = val._raw.match(/maxDate:([^\s|]+)/)?.[1];
+                            if (maxStr &&
+                                new Date(data[key]).getTime() > new Date(maxStr).getTime()) {
+                                throw new ValidatorError([
+                                    {
+                                        path: key,
+                                        message: `Date must be before ${maxStr}`,
+                                        expected: `<= ${maxStr}`,
+                                        received: formatReceivedValue(data[key]),
+                                        code: 'DATE_TOO_LATE',
+                                    },
+                                ]);
+                            }
+                        }
+                    }
+                    if (val instanceof tex_types_1.TexType &&
+                        val._raw.startsWith('array<') &&
+                        val._raw.includes('coerce')) {
+                        if (!Array.isArray(data[key])) {
+                            if (typeof data[key] === 'string') {
+                                const parts = data[key].includes(',')
+                                    ? data[key].split(',').map((s) => s.trim())
+                                    : [data[key]];
+                                if (val._raw.startsWith('array<number')) {
+                                    data[key] = parts.map((p) => {
+                                        const n = Number(p);
+                                        return isNaN(n) ? p : n;
+                                    });
+                                }
+                                else if (val._raw.startsWith('array<boolean')) {
+                                    data[key] = parts.map((p) => {
+                                        if (p.toLowerCase() === 'true')
+                                            return true;
+                                        if (p.toLowerCase() === 'false')
+                                            return false;
+                                        return p;
+                                    });
+                                }
+                                else {
+                                    data[key] = parts;
+                                }
+                            }
+                            else {
+                                data[key] = [data[key]];
+                            }
+                        }
+                        else {
+                            if (val._raw.startsWith('array<number')) {
+                                data[key] = data[key].map((item) => {
+                                    if (typeof item === 'string') {
+                                        const n = Number(item);
+                                        return isNaN(n) ? item : n;
+                                    }
+                                    return item;
+                                });
+                            }
+                            else if (val._raw.startsWith('array<boolean')) {
+                                data[key] = data[key].map((item) => {
+                                    if (typeof item === 'string') {
+                                        if (item.toLowerCase() === 'true')
+                                            return true;
+                                        if (item.toLowerCase() === 'false')
+                                            return false;
+                                    }
+                                    return item;
+                                });
+                            }
+                        }
+                    }
                     if (val instanceof tex_types_1.TexType && val.sanitizers.length > 0) {
                         for (const s of val.sanitizers) {
+                            if (data[key] === undefined || data[key] === null)
+                                break;
                             data[key] = s(data[key]);
                         }
                     }
@@ -326,8 +627,12 @@ class TexEngine {
                         if (itemSchema instanceof tex_types_1.TexType &&
                             itemSchema.sanitizers.length > 0) {
                             for (let i = 0; i < data[key].length; i++) {
-                                for (const s of itemSchema.sanitizers) {
-                                    data[key][i] = s(data[key][i]);
+                                if (data[key][i] !== undefined && data[key][i] !== null) {
+                                    for (const s of itemSchema.sanitizers) {
+                                        if (data[key][i] === undefined || data[key][i] === null)
+                                            break;
+                                        data[key][i] = s(data[key][i]);
+                                    }
                                 }
                             }
                         }
@@ -341,40 +646,164 @@ class TexEngine {
             parsedData = this.validator.parse(data);
         }
         catch (err) {
+            if (data === process.env &&
+                (process.env.__EXIS_SKIP_ENV_CHECK === 'true' ||
+                    process.env.EXIS_SKIP_ENV_CHECK === 'true')) {
+                const mock = { ...data };
+                for (const [key, val] of Object.entries(this.rawSchema)) {
+                    if (mock[key] === undefined) {
+                        const raw = val instanceof tex_types_1.TexType ? val._raw : String(val);
+                        if (raw.includes('number'))
+                            mock[key] = 0;
+                        else if (raw.includes('boolean'))
+                            mock[key] = false;
+                        else if (raw.includes('array'))
+                            mock[key] = [];
+                        else
+                            mock[key] = `mock_${key}`;
+                    }
+                }
+                return mock;
+            }
             let path = 'root';
             let message = err.message || 'Validation failed';
+            let expected;
+            let code = 'VALIDATION_ERROR';
             if (message.startsWith('Missing required field: ')) {
                 path = message.replace('Missing required field: ', '').trim();
                 message = 'Expected value, received undefined';
+                expected = 'defined';
+                code = 'MISSING_REQUIRED_FIELD';
             }
             else if (message.startsWith("Field '")) {
                 const match = message.match(/Field '([^']+)' (.+)/);
                 if (match) {
                     path = match[1];
-                    message = match[2].charAt(0).toUpperCase() + match[2].slice(1);
+                    const constraint = match[2];
+                    message = constraint.charAt(0).toUpperCase() + constraint.slice(1);
+                    if (constraint.startsWith('must be a string')) {
+                        expected = 'string';
+                        code = 'INVALID_TYPE';
+                    }
+                    else if (constraint.startsWith('must be a number')) {
+                        expected = 'number';
+                        code = 'INVALID_TYPE';
+                    }
+                    else if (constraint.startsWith('must be a boolean')) {
+                        expected = 'boolean';
+                        code = 'INVALID_TYPE';
+                    }
+                    else if (constraint.startsWith('must be an array') ||
+                        constraint.includes('array must have') ||
+                        constraint.includes('array exceeds')) {
+                        expected = 'array';
+                        code = constraint.includes('array must have')
+                            ? 'ARRAY_TOO_SHORT'
+                            : constraint.includes('array exceeds')
+                                ? 'ARRAY_TOO_LONG'
+                                : 'INVALID_TYPE';
+                    }
+                    else if (constraint.startsWith('must be an object')) {
+                        expected = 'object';
+                        code = 'INVALID_TYPE';
+                    }
+                    else if (constraint.startsWith('must be a valid email')) {
+                        expected = 'valid email address';
+                        code = 'INVALID_EMAIL';
+                    }
+                    else if (constraint.startsWith('must be one of')) {
+                        expected = constraint.replace('must be one of', '').trim();
+                        code = 'INVALID_ENUM_VALUE';
+                    }
+                    else if (constraint.startsWith('must be at least') ||
+                        constraint.startsWith('must be >=')) {
+                        expected = constraint;
+                        code = 'VALUE_TOO_SMALL';
+                    }
+                    else if (constraint.startsWith('must be at most') ||
+                        constraint.startsWith('must be <=')) {
+                        expected = constraint;
+                        code = 'VALUE_TOO_LARGE';
+                    }
+                    else if (constraint.startsWith('must contain a number')) {
+                        expected = 'must contain at least one digit';
+                        code = 'PASSWORD_REQUIRES_NUMBER';
+                    }
+                    else if (constraint.startsWith('must contain an uppercase')) {
+                        expected = 'must contain at least one uppercase letter';
+                        code = 'PASSWORD_REQUIRES_UPPERCASE';
+                    }
+                    else if (constraint.startsWith('must contain a lowercase')) {
+                        expected = 'must contain at least one lowercase letter';
+                        code = 'PASSWORD_REQUIRES_LOWERCASE';
+                    }
+                    else if (constraint.startsWith('must contain a symbol')) {
+                        expected = 'must contain at least one symbol';
+                        code = 'PASSWORD_REQUIRES_SYMBOL';
+                    }
+                    else {
+                        expected = constraint;
+                    }
                 }
             }
             else if (message.startsWith("Strict mode error: Unknown field '")) {
-                const match = message.match(/Strict mode error: Unknown field '([^']+)'/);
+                const match = message.match(/Strict mode error: Unknown field '([^']+)'(?: at path '([^']*)')?/);
                 if (match) {
-                    path = match[1];
+                    const key = match[1];
+                    const parentPath = match[2];
+                    path =
+                        parentPath && parentPath.length > 0 ? `${parentPath}.${key}` : key;
                     message = 'Unknown field not allowed in strict mode';
+                    expected = 'undefined (field omitted)';
+                    code = 'UNRECOGNIZED_KEYS';
+                }
+            }
+            const receivedRaw = getNestedValue(data, path);
+            const received = formatReceivedValue(receivedRaw);
+            throw new ValidatorError([{ path, message, expected, received, code }]);
+        }
+        // Preserve Date objects and ensure defaults are applied
+        if (parsedData && typeof parsedData === 'object') {
+            for (const [key, val] of Object.entries(this.rawSchema)) {
+                if (parsedData[key] === undefined &&
+                    val instanceof tex_types_1.TexType &&
+                    val.defaultValue !== undefined) {
+                    parsedData[key] =
+                        typeof val.defaultValue === 'function'
+                            ? val.defaultValue()
+                            : val.defaultValue;
+                }
+                if (val instanceof tex_types_1.TexType &&
+                    val._raw.startsWith('date') &&
+                    data &&
+                    data[key] instanceof Date) {
+                    parsedData[key] = data[key];
                 }
             }
-            throw new ValidatorError([{ path, message }]);
         }
         // 3. Post-validation synchronous refinements
         const errors = [];
         if (parsedData && typeof parsedData === 'object') {
             for (const [key, val] of Object.entries(this.rawSchema)) {
                 if (parsedData[key] !== undefined) {
+                    const isNullableField = val instanceof tex_types_1.TexType &&
+                        (val._raw.includes('nullable') || val._raw.includes('nullish'));
+                    if (parsedData[key] === null && isNullableField) {
+                        continue;
+                    }
                     if (val instanceof tex_types_1.TexType && val.refinements.length > 0) {
                         for (const r of val.refinements) {
                             if (!r.async && !r.fn(parsedData[key])) {
                                 const msg = typeof r.message === 'function'
                                     ? r.message(parsedData[key])
                                     : r.message || 'Invalid value';
-                                errors.push({ path: key, message: msg });
+                                errors.push({
+                                    path: key,
+                                    message: msg,
+                                    expected: 'custom refinement rule',
+                                    received: formatReceivedValue(parsedData[key]),
+                                    code: 'CUSTOM_VALIDATION',
+                                });
                             }
                         }
                     }
@@ -382,13 +811,23 @@ class TexEngine {
                     if (itemSchema && Array.isArray(parsedData[key])) {
                         if (itemSchema instanceof tex_types_1.TexType &&
                             itemSchema.refinements.length > 0) {
+                            const isItemNullable = itemSchema._raw.includes('nullable') ||
+                                itemSchema._raw.includes('nullish');
                             for (let i = 0; i < parsedData[key].length; i++) {
+                                if (parsedData[key][i] === null && isItemNullable)
+                                    continue;
                                 for (const r of itemSchema.refinements) {
                                     if (!r.async && !r.fn(parsedData[key][i])) {
                                         const msg = typeof r.message === 'function'
                                             ? r.message(parsedData[key][i])
                                             : r.message || 'Invalid value';
-                                        errors.push({ path: `${key}[${i}]`, message: msg });
+                                        errors.push({
+                                            path: `${key}[${i}]`,
+                                            message: msg,
+                                            expected: 'custom refinement rule',
+                                            received: formatReceivedValue(parsedData[key][i]),
+                                            code: 'CUSTOM_VALIDATION',
+                                        });
                                     }
                                 }
                             }
@@ -406,15 +845,26 @@ class TexEngine {
         const errors = [];
         if (parsed && typeof parsed === 'object') {
             await Promise.all(Object.entries(this.rawSchema).map(async ([key, val]) => {
-                if (parsed[key] !== undefined &&
+                const valData = parsed[key];
+                const isNullableField = val instanceof tex_types_1.TexType &&
+                    (val._raw.includes('nullable') || val._raw.includes('nullish'));
+                if (valData === null && isNullableField)
+                    return;
+                if (valData !== undefined &&
                     val instanceof tex_types_1.TexType &&
                     val.refinements.length > 0) {
                     for (const r of val.refinements) {
-                        if (r.async && !(await r.fn(parsed[key]))) {
+                        if (r.async && !(await r.fn(valData))) {
                             const msg = typeof r.message === 'function'
-                                ? r.message(parsed[key])
+                                ? r.message(valData)
                                 : r.message || 'Invalid value';
-                            errors.push({ path: key, message: msg });
+                            errors.push({
+                                path: key,
+                                message: msg,
+                                expected: 'custom async refinement rule',
+                                received: formatReceivedValue(valData),
+                                code: 'CUSTOM_VALIDATION',
+                            });
                         }
                     }
                 }