@forgehive/schema 0.1.4 → 0.2.0

package/dist/test/describe.test.js

@@ -0,0 +1,172 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_1 = require("../index");
+// `describe()` serializes a Schema to standard JSON Schema (draft 2020-12).
+// Each test builds a Schema with the Schema.* helpers and asserts the EXACT
+// JSON Schema it produces, so the wire format is obvious at a glance.
+const $schema = 'https://json-schema.org/draft/2020-12/schema';
+describe('Schema.describe() -> JSON Schema', () => {
+    it('basic types', () => {
+        const schema = new index_1.Schema({
+            name: index_1.Schema.string(),
+            age: index_1.Schema.number(),
+            active: index_1.Schema.boolean(),
+        });
+        expect(schema.describe()).toEqual({
+            $schema,
+            type: 'object',
+            properties: {
+                name: { type: 'string' },
+                age: { type: 'number' },
+                active: { type: 'boolean' },
+            },
+            required: ['name', 'age', 'active'],
+            additionalProperties: false,
+        });
+    });
+    it('string validations', () => {
+        const schema = new index_1.Schema({
+            username: index_1.Schema.string().min(3).max(20).regex(/^[a-zA-Z0-9_]+$/),
+        });
+        expect(schema.describe()).toEqual({
+            $schema,
+            type: 'object',
+            properties: {
+                username: {
+                    type: 'string',
+                    minLength: 3,
+                    maxLength: 20,
+                    pattern: '^[a-zA-Z0-9_]+$',
+                },
+            },
+            required: ['username'],
+            additionalProperties: false,
+        });
+    });
+    it('number validations', () => {
+        const schema = new index_1.Schema({
+            age: index_1.Schema.number().min(18).max(100),
+        });
+        expect(schema.describe()).toEqual({
+            $schema,
+            type: 'object',
+            properties: {
+                age: { type: 'number', minimum: 18, maximum: 100 },
+            },
+            required: ['age'],
+            additionalProperties: false,
+        });
+    });
+    it('optional fields are omitted from `required`', () => {
+        const schema = new index_1.Schema({
+            name: index_1.Schema.string(),
+            age: index_1.Schema.number().optional(),
+        });
+        expect(schema.describe()).toEqual({
+            $schema,
+            type: 'object',
+            properties: {
+                name: { type: 'string' },
+                age: { type: 'number' },
+            },
+            required: ['name'], // age is optional, so it is not required
+            additionalProperties: false,
+        });
+    });
+    it('arrays', () => {
+        const schema = new index_1.Schema({
+            tags: index_1.Schema.array(index_1.Schema.string()),
+            scores: index_1.Schema.array(index_1.Schema.number()),
+        });
+        expect(schema.describe()).toEqual({
+            $schema,
+            type: 'object',
+            properties: {
+                tags: { type: 'array', items: { type: 'string' } },
+                scores: { type: 'array', items: { type: 'number' } },
+            },
+            required: ['tags', 'scores'],
+            additionalProperties: false,
+        });
+    });
+    it('records', () => {
+        const schema = new index_1.Schema({
+            strings: index_1.Schema.stringRecord(),
+            mixed: index_1.Schema.mixedRecord(),
+        });
+        expect(schema.describe()).toEqual({
+            $schema,
+            type: 'object',
+            properties: {
+                strings: {
+                    type: 'object',
+                    propertyNames: { type: 'string' },
+                    additionalProperties: { type: 'string' },
+                },
+                mixed: {
+                    type: 'object',
+                    propertyNames: { type: 'string' },
+                    additionalProperties: {
+                        anyOf: [{ type: 'string' }, { type: 'number' }, { type: 'boolean' }],
+                    },
+                },
+            },
+            required: ['strings', 'mixed'],
+            additionalProperties: false,
+        });
+    });
+    it('nested objects', () => {
+        const schema = new index_1.Schema({
+            user: index_1.Schema.object({
+                name: index_1.Schema.string(),
+                age: index_1.Schema.number().optional(),
+            }),
+        });
+        expect(schema.describe()).toEqual({
+            $schema,
+            type: 'object',
+            properties: {
+                user: {
+                    type: 'object',
+                    properties: {
+                        name: { type: 'string' },
+                        age: { type: 'number' },
+                    },
+                    required: ['name'],
+                    additionalProperties: false,
+                },
+            },
+            required: ['user'],
+            additionalProperties: false,
+        });
+    });
+    it('element descriptions', () => {
+        const schema = new index_1.Schema({
+            name: index_1.Schema.string().describe('The name of the user'),
+        });
+        expect(schema.describe()).toEqual({
+            $schema,
+            type: 'object',
+            properties: {
+                name: { type: 'string', description: 'The name of the user' },
+            },
+            required: ['name'],
+            additionalProperties: false,
+        });
+    });
+    it('string formats: email, uuid, url, date', () => {
+        const schema = new index_1.Schema({
+            email: index_1.Schema.email(),
+            id: index_1.Schema.uuid(),
+            site: index_1.Schema.url(),
+            when: index_1.Schema.date(),
+        });
+        // Format keywords are the stable part; the generated `pattern` strings are
+        // long and version-specific, so we assert the meaningful keys.
+        const properties = schema.describe().properties;
+        expect(properties?.email).toMatchObject({ type: 'string', format: 'email' });
+        expect(properties?.id).toMatchObject({ type: 'string', format: 'uuid' });
+        expect(properties?.site).toMatchObject({ type: 'string', format: 'uri' });
+        expect(properties?.when).toMatchObject({ type: 'string', format: 'date-time' });
+    });
+});

package/dist/test/from.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/from.test.js

@@ -0,0 +1,162 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_1 = require("../index");
+// `Schema.from()` rebuilds a Schema from standard JSON Schema. Each test feeds
+// an EXPLICIT JSON Schema object and then validates concrete data, so the
+// accepted input format and its effect are obvious at a glance.
+describe('Schema.from(JSON Schema) -> validation', () => {
+    it('basic types', () => {
+        const jsonSchema = {
+            type: 'object',
+            properties: {
+                name: { type: 'string' },
+                age: { type: 'number' },
+                active: { type: 'boolean' },
+            },
+            required: ['name', 'age', 'active'],
+        };
+        const schema = index_1.Schema.from(jsonSchema);
+        expect(schema.validate({ name: 'John', age: 30, active: true })).toBe(true);
+        expect(schema.validate({ name: 'John', age: '30', active: true })).toBe(false); // age not a number
+        expect(schema.validate({ name: 'John', age: 30 })).toBe(false); // active missing
+    });
+    it('string validations (min, max, pattern)', () => {
+        const jsonSchema = {
+            type: 'object',
+            properties: {
+                username: {
+                    type: 'string',
+                    minLength: 3,
+                    maxLength: 20,
+                    pattern: '^[a-zA-Z0-9_]+$',
+                },
+            },
+            required: ['username'],
+        };
+        const schema = index_1.Schema.from(jsonSchema);
+        expect(schema.validate({ username: 'john_doe' })).toBe(true);
+        expect(schema.validate({ username: 'ab' })).toBe(false); // too short
+        expect(schema.validate({ username: 'a'.repeat(21) })).toBe(false); // too long
+        expect(schema.validate({ username: 'john-doe' })).toBe(false); // pattern mismatch
+    });
+    it('number validations (minimum, maximum)', () => {
+        const jsonSchema = {
+            type: 'object',
+            properties: {
+                age: { type: 'number', minimum: 18, maximum: 100 },
+            },
+            required: ['age'],
+        };
+        const schema = index_1.Schema.from(jsonSchema);
+        expect(schema.validate({ age: 25 })).toBe(true);
+        expect(schema.validate({ age: 18 })).toBe(true);
+        expect(schema.validate({ age: 17 })).toBe(false); // below minimum
+        expect(schema.validate({ age: 101 })).toBe(false); // above maximum
+    });
+    it('optional fields (absent from `required`)', () => {
+        const jsonSchema = {
+            type: 'object',
+            properties: {
+                name: { type: 'string' },
+                age: { type: 'number' },
+            },
+            required: ['name'], // age is optional
+        };
+        const schema = index_1.Schema.from(jsonSchema);
+        expect(schema.validate({ name: 'John', age: 30 })).toBe(true);
+        expect(schema.validate({ name: 'John' })).toBe(true); // optional age omitted
+        expect(schema.validate({ age: 30 })).toBe(false); // required name omitted
+    });
+    it('arrays', () => {
+        const jsonSchema = {
+            type: 'object',
+            properties: {
+                tags: { type: 'array', items: { type: 'string' } },
+            },
+            required: ['tags'],
+        };
+        const schema = index_1.Schema.from(jsonSchema);
+        expect(schema.validate({ tags: ['a', 'b'] })).toBe(true);
+        expect(schema.validate({ tags: [] })).toBe(true);
+        expect(schema.validate({ tags: ['a', 2] })).toBe(false); // wrong item type
+    });
+    it('records (additionalProperties)', () => {
+        const jsonSchema = {
+            type: 'object',
+            properties: {
+                data: {
+                    type: 'object',
+                    propertyNames: { type: 'string' },
+                    additionalProperties: { type: 'number' },
+                },
+            },
+            required: ['data'],
+        };
+        const schema = index_1.Schema.from(jsonSchema);
+        expect(schema.validate({ data: { a: 1, b: 2 } })).toBe(true);
+        expect(schema.validate({ data: { a: 'x' } })).toBe(false); // value not a number
+    });
+    it('mixed records (anyOf additionalProperties)', () => {
+        const jsonSchema = {
+            type: 'object',
+            properties: {
+                data: {
+                    type: 'object',
+                    propertyNames: { type: 'string' },
+                    additionalProperties: {
+                        anyOf: [{ type: 'string' }, { type: 'number' }, { type: 'boolean' }],
+                    },
+                },
+            },
+            required: ['data'],
+        };
+        const schema = index_1.Schema.from(jsonSchema);
+        expect(schema.validate({ data: { a: 'x', b: 1, c: true } })).toBe(true);
+        expect(schema.validate({ data: { a: [1, 2] } })).toBe(false); // array not allowed
+    });
+    it('nested objects', () => {
+        const jsonSchema = {
+            type: 'object',
+            properties: {
+                user: {
+                    type: 'object',
+                    properties: {
+                        name: { type: 'string', minLength: 2 },
+                        age: { type: 'number' },
+                    },
+                    required: ['name'],
+                },
+            },
+            required: ['user'],
+        };
+        const schema = index_1.Schema.from(jsonSchema);
+        expect(schema.validate({ user: { name: 'John', age: 30 } })).toBe(true);
+        expect(schema.validate({ user: { name: 'John' } })).toBe(true); // nested age optional
+        expect(schema.validate({ user: { name: 'J' } })).toBe(false); // name too short
+        expect(schema.validate({ user: { age: 30 } })).toBe(false); // nested name required
+    });
+    it('string format: email', () => {
+        const jsonSchema = {
+            type: 'object',
+            properties: {
+                email: { type: 'string', format: 'email' },
+            },
+            required: ['email'],
+        };
+        const schema = index_1.Schema.from(jsonSchema);
+        expect(schema.validate({ email: 'john@example.com' })).toBe(true);
+        expect(schema.validate({ email: 'not-an-email' })).toBe(false);
+    });
+    it('string format: date-time', () => {
+        const jsonSchema = {
+            type: 'object',
+            properties: {
+                createdAt: { type: 'string', format: 'date-time' },
+            },
+            required: ['createdAt'],
+        };
+        const schema = index_1.Schema.from(jsonSchema);
+        expect(schema.validate({ createdAt: '2024-03-20T12:00:00Z' })).toBe(true);
+        expect(schema.validate({ createdAt: 'not-a-date' })).toBe(false);
+    });
+});

package/dist/test/index.test.js

@@ -26,15 +26,17 @@ describe('Schema basic types', () => {
         expect(result).toEqual(true);
     });
 });
-describe('Schema description', () => {
+describe('Schema description (JSON Schema)', () => {
     it('should describe a string', () => {
         const schema = new index_1.default({
             name: index_1.default.string(),
         });
         const result = schema.describe();
-        expect(result).toEqual({
+        expect(result.type).toBe('object');
+        expect(result.properties).toEqual({
             name: { type: 'string' },
         });
+        expect(result.required).toEqual(['name']);
     });
     it('should describe a string and number', () => {
         const schema = new index_1.default({
@@ -42,24 +44,26 @@ describe('Schema description', () => {
             age: index_1.default.number(),
         });
         const result = schema.describe();
-        expect(result).toEqual({
+        expect(result.properties).toEqual({
             name: { type: 'string' },
             age: { type: 'number' },
         });
+        expect(result.required).toEqual(['name', 'age']);
     });
 });
 describe('Schema hydrate', () => {
-    it('should describe a string', () => {
-        const description = {
-            name: { type: 'string' },
-            age: { type: 'number' },
-        };
-        const schema = index_1.default.from(description);
+    it('should rebuild a schema from its description', () => {
+        const original = new index_1.default({
+            name: index_1.default.string(),
+            age: index_1.default.number(),
+        });
+        const schema = index_1.default.from(original.describe());
         const result = schema.describe();
-        expect(result).toEqual({
+        expect(result.properties).toEqual({
             name: { type: 'string' },
             age: { type: 'number' },
         });
+        expect(result.required).toEqual(['name', 'age']);
     });
 });
 describe('Schema validation errors', () => {
@@ -82,18 +86,27 @@ describe('Schema validation errors', () => {
         expect(result).toBe(false);
     });
 });
-// describe('Schema optional fields', () => {
-//   it('should validate with missing optional field', () => {
-//     const schema = new Schema({
-//       name: Schema.string(),
-//       age: Schema.number().optional(),
-//     })
-//     const result = schema.validate({
-//       name: 'World',
-//     })
-//     expect(result).toBe(true)
-//   })
-// })
+describe('Schema optional fields', () => {
+    it('should validate with missing optional field', () => {
+        const schema = new index_1.default({
+            name: index_1.default.string(),
+            age: index_1.default.number().optional(),
+        });
+        const result = schema.validate({
+            name: 'World',
+        });
+        expect(result).toBe(true);
+    });
+    it('should omit optional fields from the required list', () => {
+        const schema = new index_1.default({
+            name: index_1.default.string(),
+            age: index_1.default.number().optional(),
+        });
+        const result = schema.describe();
+        expect(result.required).toEqual(['name']);
+        expect(result.properties).toHaveProperty('age');
+    });
+});
 describe('Schema arrays', () => {
     it('should validate array of strings', () => {
         const schema = new index_1.default({
@@ -137,29 +150,90 @@ describe('Schema arrays', () => {
             scores: index_1.default.array(index_1.default.number()),
         });
         const result = schema.describe();
-        expect(result).toEqual({
+        expect(result.properties).toEqual({
             tags: { type: 'array', items: { type: 'string' } },
             scores: { type: 'array', items: { type: 'number' } },
         });
     });
     it('should hydrate array schema from description', () => {
-        const description = {
-            tags: { type: 'array', items: { type: 'string' } },
-            scores: { type: 'array', items: { type: 'number' } },
-        };
-        const schema = index_1.default.from(description);
+        const original = new index_1.default({
+            tags: index_1.default.array(index_1.default.string()),
+            scores: index_1.default.array(index_1.default.number()),
+        });
+        const schema = index_1.default.from(original.describe());
         const result = schema.describe();
-        expect(result).toEqual({
+        expect(result.properties).toEqual({
             tags: { type: 'array', items: { type: 'string' } },
             scores: { type: 'array', items: { type: 'number' } },
         });
     });
 });
+describe('Schema nested objects', () => {
+    it('should validate and describe nested object fields', () => {
+        const schema = new index_1.default({
+            user: index_1.default.object({
+                name: index_1.default.string(),
+                age: index_1.default.number().optional(),
+            }),
+        });
+        expect(schema.validate({ user: { name: 'John', age: 30 } })).toBe(true);
+        expect(schema.validate({ user: { name: 'John' } })).toBe(true);
+        expect(schema.validate({ user: { age: 30 } })).toBe(false);
+        const result = schema.describe();
+        expect(result.properties?.user).toMatchObject({
+            type: 'object',
+            properties: { name: { type: 'string' }, age: { type: 'number' } },
+            required: ['name'],
+        });
+    });
+    it('should round-trip a nested object schema', () => {
+        const original = new index_1.default({
+            user: index_1.default.object({
+                name: index_1.default.string().min(3),
+            }),
+        });
+        const clone = index_1.default.from(original.describe());
+        expect(clone.validate({ user: { name: 'John' } })).toBe(true);
+        expect(clone.validate({ user: { name: 'Jo' } })).toBe(false);
+    });
+    it('should infer types through safeParse for an optional nested object', () => {
+        const base = new index_1.default({
+            name: index_1.default.string().describe('The name of the user'),
+            address: index_1.default.object({
+                street: index_1.default.string(),
+                city: index_1.default.string(),
+                state: index_1.default.string(),
+                zip: index_1.default.string(),
+            }).optional().describe('The address of the user'),
+        });
+        // Optional nested object omitted
+        const withoutAddress = base.safeParse({ name: 'World' });
+        expect(withoutAddress.success).toBe(true);
+        if (withoutAddress.success) {
+            // res.data.name is string, res.data.address is optional
+            const name = withoutAddress.data.name;
+            const street = withoutAddress.data.address?.street ?? '';
+            expect(name).toBe('World');
+            expect(street).toBe('');
+        }
+        // Optional nested object present
+        const withAddress = base.safeParse({
+            name: 'World',
+            address: { street: 'Main', city: 'Town', state: 'CA', zip: '00000' },
+        });
+        expect(withAddress.success).toBe(true);
+        if (withAddress.success) {
+            expect(withAddress.data.address?.street).toBe('Main');
+        }
+        // Partial nested object is rejected (street/city/... required when present)
+        expect(base.validate({ name: 'World', address: { street: 'Main' } })).toBe(false);
+    });
+});
 describe('Schema custom validation', () => {
     it('should validate with custom rules', () => {
         const schema = new index_1.default({
             age: index_1.default.number().min(0).max(120),
-            email: index_1.default.string().email(),
+            email: index_1.default.email(),
         });
         const result = schema.validate({
             age: 25,
@@ -167,4 +241,30 @@ describe('Schema custom validation', () => {
         });
         expect(result).toBe(true);
     });
+    it('should serialize element descriptions', () => {
+        const schema = new index_1.default({
+            name: index_1.default.string().describe('the user name'),
+        });
+        const result = schema.describe();
+        expect(result.properties?.name).toMatchObject({
+            type: 'string',
+            description: 'the user name',
+        });
+    });
+    it('should keep element descriptions through the describe/from round-trip', () => {
+        const schema = new index_1.default({
+            name: index_1.default.string().describe('The name of the user'),
+            age: index_1.default.number().describe('The age of the user'),
+        });
+        const clone = index_1.default.from(schema.describe());
+        const result = clone.describe();
+        expect(result.properties?.name).toMatchObject({
+            type: 'string',
+            description: 'The name of the user',
+        });
+        expect(result.properties?.age).toMatchObject({
+            type: 'number',
+            description: 'The age of the user',
+        });
+    });
 });

package/dist/test/optionals.test.js

@@ -1,12 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 const index_1 = require("../index");
-describe('Schema Custom Validations', () => {
+describe('Schema Optional Fields', () => {
     describe('Optional Fields', () => {
         it('should handle optional string fields', () => {
-            const schema = index_1.Schema.from({
-                name: { type: 'string', optional: true },
-                age: { type: 'number' }
+            const schema = new index_1.Schema({
+                name: index_1.Schema.string().optional(),
+                age: index_1.Schema.number()
             });
             // Valid with optional field present
             expect(schema.validate({ name: 'John', age: 30 })).toBe(true);
@@ -16,9 +16,9 @@ describe('Schema Custom Validations', () => {
             expect(schema.validate({ name: 'John' })).toBe(false);
         });
         it('should handle optional array fields', () => {
-            const schema = index_1.Schema.from({
-                tags: { type: 'array', items: { type: 'string' }, optional: true },
-                scores: { type: 'array', items: { type: 'number' } }
+            const schema = new index_1.Schema({
+                tags: index_1.Schema.array(index_1.Schema.string()).optional(),
+                scores: index_1.Schema.array(index_1.Schema.number())
             });
             // Valid with optional array present
             expect(schema.validate({ tags: ['tag1', 'tag2'], scores: [1, 2, 3] })).toBe(true);
@@ -28,23 +28,25 @@ describe('Schema Custom Validations', () => {
             expect(schema.validate({ tags: ['tag1'] })).toBe(false);
         });
         it('should correctly describe optional fields', () => {
-            const schema = index_1.Schema.from({
-                name: { type: 'string', optional: true },
-                age: { type: 'number' },
-                tags: { type: 'array', items: { type: 'string' }, optional: true }
+            const schema = new index_1.Schema({
+                name: index_1.Schema.string().optional(),
+                age: index_1.Schema.number(),
+                tags: index_1.Schema.array(index_1.Schema.string()).optional()
             });
             const description = schema.describe();
-            expect(description.name).toEqual({ type: 'string', optional: true });
-            expect(description.age).toEqual({ type: 'number' });
-            expect(description.tags).toEqual({ type: 'array', items: { type: 'string' }, optional: true });
+            // Optionality is expressed by absence from the `required` list
+            expect(description.required).toEqual(['age']);
+            expect(description.properties?.name).toEqual({ type: 'string' });
+            expect(description.properties?.age).toEqual({ type: 'number' });
+            expect(description.properties?.tags).toEqual({ type: 'array', items: { type: 'string' } });
         });
     });
     describe('Schema Roundtrip', () => {
         it('should maintain optional fields through describe/from cycle', () => {
-            const originalSchema = index_1.Schema.from({
-                name: { type: 'string', optional: true },
-                age: { type: 'number' },
-                tags: { type: 'array', items: { type: 'string' }, optional: true }
+            const originalSchema = new index_1.Schema({
+                name: index_1.Schema.string().optional(),
+                age: index_1.Schema.number(),
+                tags: index_1.Schema.array(index_1.Schema.string()).optional()
             });
             const description = originalSchema.describe();
             const reconstructedSchema = index_1.Schema.from(description);
@@ -55,6 +57,8 @@ describe('Schema Custom Validations', () => {
             expect(reconstructedSchema.validate(validData)).toBe(true);
             expect(originalSchema.validate(dataWithoutOptional)).toBe(true);
             expect(reconstructedSchema.validate(dataWithoutOptional)).toBe(true);
+            // The reconstructed schema preserves which field stayed required
+            expect(reconstructedSchema.describe().required).toEqual(['age']);
         });
     });
 });

package/dist/test/parse.test.d.ts

@@ -0,0 +1 @@
+export {};