n4s 6.1.12 → 6.2.0

package/src/rules/schemaRules/__tests__/isArrayOf.test.ts

@@ -1,4 +1,4 @@
-import { describe, it, expect } from 'vitest';
+import { describe, it, expect, expectTypeOf } from 'vitest';
 
 import { enforce } from '../../../n4s';
 
@@ -70,6 +70,42 @@ describe('isArrayOf', () => {
   });
 });
 
+describe('enforce.list() - alias for isArrayOf', () => {
+  it('should validate arrays identically to isArrayOf', () => {
+    const rule = enforce.list(enforce.isNumber());
+    expect(rule.run([1, 2, 3]).pass).toBe(true);
+    expect(runArrayRule(rule, [1, 'x']).pass).toBe(false);
+  });
+
+  it('should support multiple rules', () => {
+    const rule = enforce.list(enforce.isNumber(), enforce.isString());
+    expect(rule.run([1, '2', 3]).pass).toBe(true);
+  });
+
+  it('should chain array methods', () => {
+    const rule = enforce.list(enforce.isNumber()).minLength(1).maxLength(5);
+    expect(rule.run([1, 2]).pass).toBe(true);
+    expect(rule.run([]).pass).toBe(false);
+  });
+
+  it('should infer the same types as isArrayOf', () => {
+    const viaIsArrayOf = enforce.isArrayOf(enforce.isString());
+    const viaList = enforce.list(enforce.isString());
+    expectTypeOf(viaList.infer).toEqualTypeOf(viaIsArrayOf.infer);
+    // eslint-disable-next-line vitest/valid-expect
+    expectTypeOf(viaList.parse).returns.toEqualTypeOf<string[]>();
+  });
+
+  it('should work in the eager API', () => {
+    expect(() => {
+      enforce([1, 2, 3]).list(enforce.isNumber());
+    }).not.toThrow();
+    expect(() => {
+      enforce(['x']).list(enforce.isNumber());
+    }).toThrow();
+  });
+});
+
 describe('isArrayOf - eager API', () => {
   it('should chain array methods after isArrayOf (eager API)', () => {
     expect(() => {

package/src/rules/schemaRules/__tests__/lazy.test.ts

@@ -0,0 +1,312 @@
+import { describe, it, expect } from 'vitest';
+
+import { enforce, compose } from '../../../n4s';
+import type { RuleInstance } from '../../../utils/RuleInstance';
+
+describe('enforce.lazy()', () => {
+  describe('recursive shape validation', () => {
+    it('validates a simple recursive tree', () => {
+      const treeSchema: RuleInstance<any> = enforce.shape({
+        value: enforce.isNumber(),
+        children: enforce.isArrayOf(enforce.lazy(() => treeSchema)),
+      });
+
+      expect(
+        treeSchema.test({
+          value: 1,
+          children: [
+            { value: 2, children: [] },
+            {
+              value: 3,
+              children: [{ value: 4, children: [] }],
+            },
+          ],
+        }),
+      ).toBe(true);
+    });
+
+    it('fails on invalid nested node', () => {
+      const treeSchema: RuleInstance<any> = enforce.shape({
+        value: enforce.isNumber(),
+        children: enforce.isArrayOf(enforce.lazy(() => treeSchema)),
+      });
+
+      expect(
+        treeSchema.test({
+          value: 1,
+          children: [{ value: 'not a number', children: [] }],
+        }),
+      ).toBe(false);
+    });
+
+    it('validates leaf nodes (empty children array)', () => {
+      const treeSchema: RuleInstance<any> = enforce.shape({
+        value: enforce.isString(),
+        children: enforce.isArrayOf(enforce.lazy(() => treeSchema)),
+      });
+
+      expect(treeSchema.test({ value: 'leaf', children: [] })).toBe(true);
+    });
+
+    it('fails when nested node is missing required fields', () => {
+      const treeSchema: RuleInstance<any> = enforce.shape({
+        value: enforce.isNumber(),
+        children: enforce.isArrayOf(enforce.lazy(() => treeSchema)),
+      });
+
+      expect(
+        treeSchema.test({
+          value: 1,
+          children: [{ value: 2 }],
+        }),
+      ).toBe(false);
+    });
+  });
+
+  describe('optional recursive fields', () => {
+    it('validates a binary tree with optional left/right', () => {
+      const binaryTree: RuleInstance<any> = enforce.shape({
+        value: enforce.isNumber(),
+        left: enforce.optional(enforce.lazy(() => binaryTree)),
+        right: enforce.optional(enforce.lazy(() => binaryTree)),
+      });
+
+      expect(binaryTree.test({ value: 1 })).toBe(true);
+      expect(binaryTree.test({ value: 1, left: { value: 2 } })).toBe(true);
+      expect(
+        binaryTree.test({
+          value: 1,
+          left: { value: 2, right: { value: 3 } },
+        }),
+      ).toBe(true);
+    });
+
+    it('fails on invalid optional nested node', () => {
+      const binaryTree: RuleInstance<any> = enforce.shape({
+        value: enforce.isNumber(),
+        left: enforce.optional(enforce.lazy(() => binaryTree)),
+        right: enforce.optional(enforce.lazy(() => binaryTree)),
+      });
+
+      expect(
+        binaryTree.test({
+          value: 1,
+          left: { value: 'invalid' },
+        }),
+      ).toBe(false);
+    });
+  });
+
+  describe('factory caching', () => {
+    it('calls the factory only once across recursive calls', () => {
+      let callCount = 0;
+      const schema: RuleInstance<any> = enforce.shape({
+        val: enforce.isNumber(),
+        next: enforce.optional(
+          enforce.lazy(() => {
+            callCount++;
+            return schema;
+          }),
+        ),
+      });
+
+      schema.test({ val: 1, next: { val: 2, next: { val: 3 } } });
+      expect(callCount).toBe(1);
+    });
+
+    it('reuses cached schema across multiple validations', () => {
+      let callCount = 0;
+      const schema: RuleInstance<any> = enforce.shape({
+        val: enforce.isNumber(),
+        next: enforce.optional(
+          enforce.lazy(() => {
+            callCount++;
+            return schema;
+          }),
+        ),
+      });
+
+      schema.test({ val: 1, next: { val: 2 } });
+      schema.test({ val: 3, next: { val: 4 } });
+      expect(callCount).toBe(1);
+    });
+  });
+
+  describe('deep nesting', () => {
+    it('validates a deeply nested structure (5+ levels)', () => {
+      const nodeSchema: RuleInstance<any> = enforce.shape({
+        id: enforce.isNumber(),
+        child: enforce.optional(enforce.lazy(() => nodeSchema)),
+      });
+
+      expect(
+        nodeSchema.test({
+          id: 1,
+          child: {
+            id: 2,
+            child: {
+              id: 3,
+              child: {
+                id: 4,
+                child: {
+                  id: 5,
+                  child: { id: 6 },
+                },
+              },
+            },
+          },
+        }),
+      ).toBe(true);
+    });
+
+    it('detects failure deep in nested structure', () => {
+      const nodeSchema: RuleInstance<any> = enforce.shape({
+        id: enforce.isNumber(),
+        child: enforce.optional(enforce.lazy(() => nodeSchema)),
+      });
+
+      expect(
+        nodeSchema.test({
+          id: 1,
+          child: {
+            id: 2,
+            child: {
+              id: 3,
+              child: {
+                id: 'invalid',
+              },
+            },
+          },
+        }),
+      ).toBe(false);
+    });
+  });
+
+  describe('RuleInstance methods', () => {
+    it('.test() returns boolean', () => {
+      const schema: RuleInstance<any> = enforce.shape({
+        val: enforce.isNumber(),
+        children: enforce.isArrayOf(enforce.lazy(() => schema)),
+      });
+
+      expect(typeof schema.test({ val: 1, children: [] })).toBe('boolean');
+    });
+
+    it('.run() returns RuleRunReturn', () => {
+      const schema: RuleInstance<any> = enforce.shape({
+        val: enforce.isNumber(),
+        children: enforce.isArrayOf(enforce.lazy(() => schema)),
+      });
+
+      const passing = schema.run({ val: 1, children: [] });
+      expect(passing.pass).toBe(true);
+
+      const failing = schema.run({ val: 'bad', children: [] });
+      expect(failing.pass).toBe(false);
+    });
+
+    it('.validate() returns StandardSchema result', () => {
+      const schema: RuleInstance<any> = enforce.shape({
+        val: enforce.isNumber(),
+        children: enforce.isArrayOf(enforce.lazy(() => schema)),
+      });
+
+      const passing = schema.validate({ val: 1, children: [] });
+      expect(passing).toHaveProperty('value');
+      expect(passing).not.toHaveProperty('issues');
+
+      const failing = schema.validate({ val: 'bad', children: [] });
+      expect(failing).toHaveProperty('issues');
+    });
+
+    it('.parse() returns value on success and throws on failure', () => {
+      const schema: RuleInstance<any> = enforce.shape({
+        val: enforce.isNumber(),
+        children: enforce.isArrayOf(enforce.lazy(() => schema)),
+      });
+
+      const data = { val: 1, children: [] };
+      expect(schema.parse(data)).toEqual(data);
+
+      expect(() => schema.parse({ val: 'bad', children: [] })).toThrow();
+    });
+  });
+
+  describe('.message() override', () => {
+    it('supports custom message on lazy wrapper', () => {
+      const inner = enforce.shape({
+        val: enforce.isNumber(),
+      });
+
+      const lazyInner = enforce.lazy(() => inner).message('Custom lazy error');
+      const result = lazyInner.run({ val: 'bad' });
+
+      expect(result.pass).toBe(false);
+      expect(result.message).toBe('Custom lazy error');
+    });
+  });
+
+  describe('compose + lazy', () => {
+    it('works with compose()', () => {
+      const nodeSchema: RuleInstance<any> = enforce.shape({
+        id: enforce.isString(),
+        children: enforce.isArrayOf(enforce.lazy(() => nodeSchema)),
+      });
+
+      const validatedNode = compose(nodeSchema, enforce.isNotEmpty());
+
+      expect(
+        validatedNode.test({
+          id: 'root',
+          children: [{ id: 'a', children: [] }],
+        }),
+      ).toBe(true);
+
+      expect(validatedNode.test({})).toBe(false);
+    });
+  });
+
+  describe('eager API integration', () => {
+    it('works when lazy is used inside an eager shape call', () => {
+      const treeSchema: RuleInstance<any> = enforce.shape({
+        value: enforce.isNumber(),
+        children: enforce.isArrayOf(enforce.lazy(() => treeSchema)),
+      });
+
+      expect(() => {
+        enforce({
+          value: 1,
+          children: [{ value: 2, children: [] }],
+        }).shape(treeSchema.__schema);
+      }).not.toThrow();
+    });
+  });
+
+  describe('standalone lazy', () => {
+    it('works as a standalone rule', () => {
+      const numberRule = enforce.isNumber();
+      const lazyNumber = enforce.lazy(() => numberRule);
+
+      expect(lazyNumber.test(42)).toBe(true);
+      // @ts-expect-error - testing runtime failure with invalid type
+      expect(lazyNumber.test('not a number')).toBe(false);
+    });
+  });
+
+  describe('error path propagation', () => {
+    it('propagates error path through lazy boundary', () => {
+      const schema: RuleInstance<any> = enforce.shape({
+        name: enforce.isString(),
+        children: enforce.isArrayOf(enforce.lazy(() => schema)),
+      });
+
+      const result = schema.run({
+        name: 'root',
+        children: [{ name: 123, children: [] }],
+      });
+
+      expect(result.pass).toBe(false);
+      expect(result.path).toBeDefined();
+    });
+  });
+});

package/src/rules/schemaRules/__tests__/record.test.ts

@@ -0,0 +1,205 @@
+import { describe, it, expect } from 'vitest';
+
+import { enforce } from '../../../n4s';
+
+describe('enforce.record()', () => {
+  describe('lazy', () => {
+    it('should return a rule instance', () => {
+      const rule = enforce.record(enforce.isNumber());
+      expect(rule).toHaveProperty('run');
+      expect(rule).toHaveProperty('infer');
+    });
+
+    describe('value-only validation', () => {
+      it('passes when all values match rule', () => {
+        const rule = enforce.record(enforce.isNumber());
+        expect(rule.run({ a: 1, b: 2, c: 3 }).pass).toBe(true);
+      });
+
+      it('fails when any value does not match', () => {
+        const rule = enforce.record(enforce.isNumber());
+        // @ts-expect-error - testing runtime with invalid value type
+        expect(rule.run({ a: 1, b: 'two', c: 3 }).pass).toBe(false);
+      });
+
+      it('passes for empty objects', () => {
+        const rule = enforce.record(enforce.isNumber());
+        expect(rule.run({}).pass).toBe(true);
+      });
+
+      it('fails for non-object values', () => {
+        const rule = enforce.record(enforce.isNumber());
+        // @ts-expect-error - testing runtime with non-object
+        expect(rule.run('not an object').pass).toBe(false);
+      });
+
+      it('fails for arrays', () => {
+        const rule = enforce.record(enforce.isNumber());
+        // @ts-expect-error - testing runtime with array
+        expect(rule.run([1, 2, 3]).pass).toBe(false);
+      });
+
+      it('skips prototype keys', () => {
+        const obj = Object.create({ inherited: 'bad' });
+        obj.own = 42;
+        const rule = enforce.record(enforce.isNumber());
+        expect(rule.run(obj).pass).toBe(true);
+      });
+
+      it('fails on prototype pollution keys', () => {
+        const rule = enforce.record(enforce.isNumber());
+        const polluter = JSON.parse('{"__proto__": {"malicious": true}}');
+        const res = rule.run(polluter);
+        expect(res.pass).toBe(false);
+        expect(res.path).toEqual(['__proto__']);
+      });
+    });
+
+    describe('key + value validation', () => {
+      it('validates both keys and values', () => {
+        const rule = enforce.record(
+          enforce.isString().matches(/^[a-z]+$/),
+          enforce.isNumber(),
+        );
+        expect(rule.run({ abc: 1, def: 2 }).pass).toBe(true);
+      });
+
+      it('fails when key does not match', () => {
+        const rule = enforce.record(
+          enforce.isString().matches(/^[a-z]+$/),
+          enforce.isNumber(),
+        );
+        const res = rule.run({ INVALID: 1 });
+        expect(res.pass).toBe(false);
+        expect(res.path).toEqual(['INVALID']);
+      });
+
+      it('fails when value does not match', () => {
+        const rule = enforce.record(
+          enforce.isString().matches(/^[a-z]+$/),
+          enforce.isNumber(),
+        );
+        // @ts-expect-error - testing runtime with invalid value type
+        const res = rule.run({ valid: 'text' });
+        expect(res.pass).toBe(false);
+        expect(res.path).toEqual(['valid']);
+      });
+    });
+
+    describe('nested schemas', () => {
+      it('validates nested shapes as values', () => {
+        const rule = enforce.record(
+          enforce.shape({
+            name: enforce.isString(),
+            age: enforce.isNumber(),
+          }),
+        );
+
+        expect(
+          rule.run({
+            user1: { name: 'Alice', age: 30 },
+            user2: { name: 'Bob', age: 25 },
+          }).pass,
+        ).toBe(true);
+
+        const failing = rule.run({
+          user1: { name: 'Alice', age: 30 },
+          // @ts-expect-error - testing runtime with invalid nested value
+          user2: { name: 'Bob', age: '25' },
+        });
+
+        expect(failing.pass).toBe(false);
+        expect(failing.path).toEqual(['user2', 'age']);
+      });
+
+      it('validates nested records', () => {
+        const rule = enforce.record(enforce.record(enforce.isBoolean()));
+
+        expect(
+          rule.run({
+            group1: { a: true, b: false },
+            group2: { c: true },
+          }).pass,
+        ).toBe(true);
+      });
+    });
+
+    describe('lazy chain type tests', () => {
+      it('works with .test()', () => {
+        const rule = enforce.record(enforce.isString());
+        expect(rule.test({ a: 'hello' })).toBe(true);
+      });
+
+      it('chains with message() correctly', () => {
+        const rule = enforce.record(enforce.isNumber().message('custom error'));
+        const result = rule.run({ a: 1, b: 'err' });
+        expect(result.pass).toBe(false);
+        expect(result.message).toEqual('custom error');
+      });
+    });
+  });
+
+  describe('eager', () => {
+    describe('value-only validation', () => {
+      it('passes when all values match rule', () => {
+        expect(() => {
+          enforce({ a: 1, b: 2, c: 3 }).record(enforce.isNumber());
+        }).not.toThrow();
+      });
+
+      it('fails when any value does not match', () => {
+        expect(() => {
+          enforce({ a: 1, b: 'two', c: 3 }).record(enforce.isNumber());
+        }).toThrow();
+      });
+
+      it('passes for empty objects', () => {
+        expect(() => {
+          enforce({}).record(enforce.isNumber());
+        }).not.toThrow();
+      });
+
+      it('fails for non-object values', () => {
+        expect(() => {
+          // @ts-expect-error - testing runtime with non-object
+          enforce('not an object').record(enforce.isNumber());
+        }).toThrow();
+      });
+
+      it('fails for arrays', () => {
+        expect(() => {
+          // @ts-expect-error - testing runtime with array
+          enforce([1, 2, 3]).record(enforce.isNumber());
+        }).toThrow();
+      });
+
+      it('skips prototype keys', () => {
+        const obj = Object.create({ inherited: 'bad' });
+        obj.own = 42;
+        expect(() => {
+          enforce(obj).record(enforce.isNumber());
+        }).not.toThrow();
+      });
+    });
+
+    describe('key + value validation', () => {
+      it('validates both keys and values', () => {
+        expect(() => {
+          enforce({ abc: 1, def: 2 }).record(
+            enforce.isString().matches(/^[a-z]+$/),
+            enforce.isNumber(),
+          );
+        }).not.toThrow();
+      });
+
+      it('fails when key does not match', () => {
+        expect(() => {
+          enforce({ INVALID: 1 }).record(
+            enforce.isString().matches(/^[a-z]+$/),
+            enforce.isNumber(),
+          );
+        }).toThrow();
+      });
+    });
+  });
+});

package/src/rules/schemaRules/__tests__/schema.parse.integration.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, it } from 'vitest';
 
 import { enforce } from '../../../n4s';
+import type { RuleInstance } from '../../../utils/RuleInstance';
 
 declare global {
   namespace n4s {
@@ -155,4 +156,82 @@ describe('schema parse integration', () => {
     expect(schema.parse({ label: undefined })).toEqual({ label: 'N/A' });
     expect(schema.parse({ label: 'hello' })).toEqual({ label: 'hello' });
   });
+
+  it('lazy propagates parse transformations from inner schema', () => {
+    const inner = enforce.shape({
+      name: enforce.trimString(),
+      age: enforce.toNumber(),
+    });
+
+    const schema = enforce.lazy(() => inner);
+    // @ts-expect-error - input type differs from output due to coercions
+    const result = schema.parse({ name: '  Jane  ', age: '34' });
+    expect(result).toEqual({ name: 'Jane', age: 34 });
+  });
+
+  it('tuple parses element values with custom coercions', () => {
+    const schema = enforce.tuple(enforce.trimString(), enforce.toNumber());
+    const result = schema.parse(['  hello  ', '42']);
+    expect(result).toEqual(['hello', 42]);
+  });
+
+  it('tuple parses nested shape elements', () => {
+    const schema = enforce.tuple(
+      enforce.trimString(),
+      enforce.shape({
+        name: enforce.trimString(),
+        age: enforce.toNumber(),
+      }),
+    );
+
+    const result = schema.parse(['  label  ', { name: '  Jane  ', age: '34' }]);
+    expect(result).toEqual(['label', { name: 'Jane', age: 34 }]);
+  });
+
+  it('tuple parses with built-in parser chains', () => {
+    const schema = enforce.tuple(
+      enforce.isString().trim().toTitle(),
+      enforce.isNumeric().toNumber().clamp(0, 100),
+    );
+
+    const result = schema.parse(['  jANE DOE ', '180']);
+    expect(result).toEqual(['Jane Doe', 100]);
+  });
+
+  it('tuple inside shape preserves parse transformations', () => {
+    const schema = enforce.shape({
+      label: enforce.trimString(),
+      coords: enforce.tuple(enforce.toNumber(), enforce.toNumber()),
+    });
+
+    const result = schema.parse({ label: '  origin  ', coords: ['10', '20'] });
+    expect(result).toEqual({ label: 'origin', coords: [10, 20] });
+  });
+
+  it('lazy propagates parse transformations through recursive schemas', () => {
+    const schema: RuleInstance<any> = enforce.shape({
+      name: enforce.trimString(),
+      children: enforce.isArrayOf(enforce.lazy(() => schema)),
+    });
+
+    const result = schema.parse({
+      name: '  Root  ',
+      children: [
+        {
+          name: '  Child  ',
+          children: [{ name: '  Grandchild  ', children: [] }],
+        },
+      ],
+    });
+
+    expect(result).toEqual({
+      name: 'Root',
+      children: [
+        {
+          name: 'Child',
+          children: [{ name: 'Grandchild', children: [] }],
+        },
+      ],
+    });
+  });
 });