@forgehive/schema 0.1.4 → 0.2.0

package/dist/index.js

@@ -1,8 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Schema = void 0;
+exports.Schema = exports.z = void 0;
 const zod_1 = require("zod");
-// Static methods for type definitions
+Object.defineProperty(exports, "z", { enumerable: true, get: function () { return zod_1.z; } });
+/**
+ * A thin wrapper around a zod object schema. Fields are created with the static
+ * `Schema.*` helpers so call sites stay independent of the underlying validation
+ * library; the wrapper owns validation plus JSON Schema serialization
+ * (`describe`) and rehydration (`from`).
+ */
 class Schema {
     constructor(fields) {
         this.schema = zod_1.z.object(fields);
@@ -14,6 +20,13 @@ class Schema {
     static string() {
         return zod_1.z.string();
     }
+    /**
+     * Creates a number schema
+     * @returns A number schema
+     */
+    static number() {
+        return zod_1.z.number();
+    }
     /**
      * Creates a boolean schema
      * @returns A boolean schema
@@ -22,18 +35,49 @@ class Schema {
         return zod_1.z.boolean();
     }
     /**
-     * Creates a number schema
-     * @returns A number schema
+     * Creates an ISO 8601 date-time schema. The runtime value is a string
+     * (e.g. "2020-01-01T00:00:00Z"), which is natively representable in JSON Schema.
+     * @returns An ISO date-time schema
      */
-    static number() {
-        return zod_1.z.number();
+    static date() {
+        return zod_1.z.iso.datetime();
     }
     /**
-     * Creates a date schema
-     * @returns A date schema
+     * Creates an email string schema (serializes to JSON Schema `format: "email"`).
+     * @returns An email schema
      */
-    static date() {
-        return zod_1.z.date();
+    static email() {
+        return zod_1.z.email();
+    }
+    /**
+     * Creates a UUID string schema (serializes to JSON Schema `format: "uuid"`).
+     * @returns A UUID schema
+     */
+    static uuid() {
+        return zod_1.z.uuid();
+    }
+    /**
+     * Creates a URL string schema (serializes to JSON Schema `format: "uri"`).
+     * @returns A URL schema
+     */
+    static url() {
+        return zod_1.z.url();
+    }
+    /**
+     * Creates an array schema
+     * @param type The type of items in the array
+     * @returns An array schema
+     */
+    static array(type) {
+        return zod_1.z.array(type);
+    }
+    /**
+     * Creates a nested object schema
+     * @param fields The fields of the object
+     * @returns An object schema
+     */
+    static object(fields) {
+        return zod_1.z.object(fields);
     }
     /**
      * Creates a record schema with string keys and string values
@@ -63,14 +107,6 @@ class Schema {
     static mixedRecord() {
         return zod_1.z.record(zod_1.z.string(), zod_1.z.union([zod_1.z.string(), zod_1.z.number(), zod_1.z.boolean()]));
     }
-    /**
-     * Creates an array schema
-     * @param type The type of items in the array
-     * @returns An array schema
-     */
-    static array(type) {
-        return zod_1.z.array(type);
-    }
     /**
      * Infers the TypeScript type from a Schema instance
      * @template S The Schema type
@@ -81,94 +117,21 @@ class Schema {
         return {};
     }
     /**
-     * Creates a Schema instance from a description object
-     * @param description Object describing the schema structure with type information
+     * Creates a Schema instance from a JSON Schema description.
+     *
+     * Note: this relies on zod's `fromJSONSchema`, which zod considers
+     * semi-experimental. Round-trips of schemas produced by `describe()` are
+     * covered by the package tests.
+     *
+     * @param description A JSON Schema object describing an object schema
      * @returns A new Schema instance
      */
     static from(description) {
-        const fields = {};
-        for (const [key, field] of Object.entries(description)) {
-            const fieldType = field.type;
-            let fieldSchema;
-            switch (fieldType) {
-                case 'string': {
-                    let stringSchema = Schema.string();
-                    if (field.validations) {
-                        const validations = field.validations;
-                        if (validations.email) {
-                            stringSchema = stringSchema.email();
-                        }
-                        if (validations.minLength !== undefined) {
-                            stringSchema = stringSchema.min(validations.minLength);
-                        }
-                        if (validations.maxLength !== undefined) {
-                            stringSchema = stringSchema.max(validations.maxLength);
-                        }
-                        if (validations.regex !== undefined) {
-                            stringSchema = stringSchema.regex(new RegExp(validations.regex));
-                        }
-                    }
-                    fieldSchema = stringSchema;
-                    break;
-                }
-                case 'boolean':
-                    fieldSchema = Schema.boolean();
-                    break;
-                case 'number': {
-                    let numberSchema = Schema.number();
-                    if (field.validations) {
-                        const validations = field.validations;
-                        if (validations.min !== undefined) {
-                            numberSchema = numberSchema.min(validations.min);
-                        }
-                        if (validations.max !== undefined) {
-                            numberSchema = numberSchema.max(validations.max);
-                        }
-                    }
-                    fieldSchema = numberSchema;
-                    break;
-                }
-                case 'date':
-                    fieldSchema = Schema.date();
-                    break;
-                case 'stringRecord':
-                    fieldSchema = Schema.stringRecord();
-                    break;
-                case 'numberRecord':
-                    fieldSchema = Schema.numberRecord();
-                    break;
-                case 'booleanRecord':
-                    fieldSchema = Schema.booleanRecord();
-                    break;
-                case 'mixedRecord':
-                    fieldSchema = Schema.mixedRecord();
-                    break;
-                case 'array': {
-                    const arrayField = field;
-                    switch (arrayField.items.type) {
-                        case 'string':
-                            fieldSchema = Schema.array(Schema.string());
-                            break;
-                        case 'boolean':
-                            fieldSchema = Schema.array(Schema.boolean());
-                            break;
-                        case 'number':
-                            fieldSchema = Schema.array(Schema.number());
-                            break;
-                        case 'date':
-                            fieldSchema = Schema.array(Schema.date());
-                            break;
-                        default:
-                            throw new Error(`Unsupported array item type: ${arrayField.items.type}`);
-                    }
-                    break;
-                }
-                default:
-                    throw new Error(`Unsupported type: ${fieldType}`);
-            }
-            fields[key] = field.optional ? fieldSchema.optional() : fieldSchema;
+        const zodSchema = zod_1.z.fromJSONSchema(description);
+        if (!(zodSchema instanceof zod_1.z.ZodObject)) {
+            throw new Error('Schema.from expects a JSON Schema that describes an object');
         }
-        return new Schema(fields);
+        return new Schema(zodSchema.shape);
     }
     /**
      * Validates the provided data against the schema
@@ -197,88 +160,11 @@ class Schema {
         return this.schema.safeParse(data);
     }
     /**
-     * Describes the schema structure and allowed types
-     * @returns An object describing the schema structure with type information
+     * Serializes the schema to JSON Schema (draft 2020-12).
+     * @returns A JSON Schema object describing the schema structure
      */
     describe() {
-        const shape = this.schema.shape;
-        const description = {};
-        for (const [key, value] of Object.entries(shape)) {
-            const isOptional = value instanceof zod_1.z.ZodOptional;
-            const baseValue = isOptional ? value.unwrap() : value;
-            if (baseValue instanceof zod_1.z.ZodString) {
-                const validations = {};
-                if (baseValue._def.checks) {
-                    for (const check of baseValue._def.checks) {
-                        if (check.kind === 'email') {
-                            validations.email = true;
-                        }
-                        else if (check.kind === 'min') {
-                            validations.minLength = check.value;
-                        }
-                        else if (check.kind === 'max') {
-                            validations.maxLength = check.value;
-                        }
-                        else if (check.kind === 'regex') {
-                            validations.regex = check.regex.toString().replace(/^\/|\/$/g, '').replace(/\\\//g, '/');
-                        }
-                    }
-                }
-                description[key] = Object.assign(Object.assign({ type: 'string' }, (isOptional && { optional: true })), (Object.keys(validations).length > 0 && { validations }));
-            }
-            else if (baseValue instanceof zod_1.z.ZodBoolean) {
-                description[key] = Object.assign({ type: 'boolean' }, (isOptional && { optional: true }));
-            }
-            else if (baseValue instanceof zod_1.z.ZodNumber) {
-                const validations = {};
-                if (baseValue._def.checks) {
-                    for (const check of baseValue._def.checks) {
-                        if (check.kind === 'min') {
-                            validations.min = check.value;
-                        }
-                        else if (check.kind === 'max') {
-                            validations.max = check.value;
-                        }
-                    }
-                }
-                description[key] = Object.assign(Object.assign({ type: 'number' }, (isOptional && { optional: true })), (Object.keys(validations).length > 0 && { validations }));
-            }
-            else if (baseValue instanceof zod_1.z.ZodDate) {
-                description[key] = Object.assign({ type: 'date' }, (isOptional && { optional: true }));
-            }
-            else if (baseValue instanceof zod_1.z.ZodArray) {
-                const element = baseValue.element;
-                if (element instanceof zod_1.z.ZodString) {
-                    description[key] = Object.assign({ type: 'array', items: { type: 'string' } }, (isOptional && { optional: true }));
-                }
-                else if (element instanceof zod_1.z.ZodBoolean) {
-                    description[key] = Object.assign({ type: 'array', items: { type: 'boolean' } }, (isOptional && { optional: true }));
-                }
-                else if (element instanceof zod_1.z.ZodNumber) {
-                    description[key] = Object.assign({ type: 'array', items: { type: 'number' } }, (isOptional && { optional: true }));
-                }
-                else if (element instanceof zod_1.z.ZodDate) {
-                    description[key] = Object.assign({ type: 'array', items: { type: 'date' } }, (isOptional && { optional: true }));
-                }
-            }
-            else if (baseValue instanceof zod_1.z.ZodRecord) {
-                // Check the value type of the record
-                const valueType = baseValue._def.valueType;
-                if (valueType instanceof zod_1.z.ZodString) {
-                    description[key] = Object.assign({ type: 'stringRecord' }, (isOptional && { optional: true }));
-                }
-                else if (valueType instanceof zod_1.z.ZodNumber) {
-                    description[key] = Object.assign({ type: 'numberRecord' }, (isOptional && { optional: true }));
-                }
-                else if (valueType instanceof zod_1.z.ZodBoolean) {
-                    description[key] = Object.assign({ type: 'booleanRecord' }, (isOptional && { optional: true }));
-                }
-                else if (valueType instanceof zod_1.z.ZodUnion) {
-                    description[key] = Object.assign({ type: 'mixedRecord' }, (isOptional && { optional: true }));
-                }
-            }
-        }
-        return description;
+        return zod_1.z.toJSONSchema(this.schema, { target: 'draft-2020-12' });
     }
     /**
      * Returns the underlying Zod schema object

package/dist/test/custom-validations.test.js

@@ -3,21 +3,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const index_1 = require("../index");
 describe('Schema Custom Number Validations', () => {
     it('should validate number min/max constraints', () => {
-        const schema = index_1.Schema.from({
-            age: {
-                type: 'number',
-                validations: {
-                    min: 18,
-                    max: 100
-                }
-            },
-            score: {
-                type: 'number',
-                validations: {
-                    min: 0,
-                    max: 100
-                }
-            }
+        const schema = new index_1.Schema({
+            age: index_1.Schema.number().min(18).max(100),
+            score: index_1.Schema.number().min(0).max(100)
         });
         // Valid cases
         expect(schema.validate({ age: 25, score: 85 })).toBe(true);
@@ -29,35 +17,22 @@ describe('Schema Custom Number Validations', () => {
         expect(schema.validate({ age: 101, score: 85 })).toBe(false);
         expect(schema.validate({ age: 25, score: 101 })).toBe(false);
     });
-    it('should correctly describe number validations', () => {
-        const schema = index_1.Schema.from({
-            age: {
-                type: 'number',
-                validations: {
-                    min: 18,
-                    max: 100
-                }
-            }
+    it('should describe number validations as JSON Schema', () => {
+        const schema = new index_1.Schema({
+            age: index_1.Schema.number().min(18).max(100)
         });
         const description = schema.describe();
-        expect(description.age).toEqual({
+        expect(description.properties?.age).toEqual({
             type: 'number',
-            validations: {
-                min: 18,
-                max: 100
-            }
+            minimum: 18,
+            maximum: 100
         });
     });
 });
 describe('Schema Custom String Validations', () => {
     it('should validate string email format', () => {
-        const schema = index_1.Schema.from({
-            email: {
-                type: 'string',
-                validations: {
-                    email: true
-                }
-            }
+        const schema = new index_1.Schema({
+            email: index_1.Schema.email()
         });
         // Valid cases
         expect(schema.validate({ email: 'user@example.com' })).toBe(true);
@@ -69,14 +44,8 @@ describe('Schema Custom String Validations', () => {
         expect(schema.validate({ email: '@domain.com' })).toBe(false);
     });
     it('should validate string length constraints', () => {
-        const schema = index_1.Schema.from({
-            username: {
-                type: 'string',
-                validations: {
-                    minLength: 3,
-                    maxLength: 20
-                }
-            }
+        const schema = new index_1.Schema({
+            username: index_1.Schema.string().min(3).max(20)
         });
         // Valid cases
         expect(schema.validate({ username: 'abc' })).toBe(true);
@@ -87,13 +56,8 @@ describe('Schema Custom String Validations', () => {
         expect(schema.validate({ username: 'a'.repeat(21) })).toBe(false);
     });
     it('should validate string regex pattern', () => {
-        const schema = index_1.Schema.from({
-            username: {
-                type: 'string',
-                validations: {
-                    regex: '^[a-zA-Z0-9_]+$'
-                }
-            }
+        const schema = new index_1.Schema({
+            username: index_1.Schema.string().regex(/^[a-zA-Z0-9_]+$/)
         });
         // Valid cases
         expect(schema.validate({ username: 'john_doe123' })).toBe(true);
@@ -104,54 +68,31 @@ describe('Schema Custom String Validations', () => {
         expect(schema.validate({ username: 'user@123' })).toBe(false);
         expect(schema.validate({ username: 'user name' })).toBe(false);
     });
-    it('should correctly describe string validations', () => {
-        const schema = index_1.Schema.from({
-            email: {
-                type: 'string',
-                validations: {
-                    email: true,
-                    minLength: 5,
-                    maxLength: 100
-                }
-            }
+    it('should describe string length validations as JSON Schema', () => {
+        const schema = new index_1.Schema({
+            email: index_1.Schema.email().min(5).max(100)
         });
         const description = schema.describe();
-        expect(description.email).toEqual({
+        expect(description.properties?.email).toMatchObject({
             type: 'string',
-            validations: {
-                email: true,
-                minLength: 5,
-                maxLength: 100
-            }
+            format: 'email',
+            minLength: 5,
+            maxLength: 100
         });
     });
-    it('should correctly describe string regex validation', () => {
-        const schema = index_1.Schema.from({
-            username: {
-                type: 'string',
-                validations: {
-                    regex: '^[a-zA-Z0-9_]+$'
-                }
-            }
+    it('should describe string regex validation as a pattern', () => {
+        const schema = new index_1.Schema({
+            username: index_1.Schema.string().regex(/^[a-zA-Z0-9_]+$/)
         });
         const description = schema.describe();
-        expect(description.username).toEqual({
+        expect(description.properties?.username).toMatchObject({
             type: 'string',
-            validations: {
-                regex: '^[a-zA-Z0-9_]+$'
-            }
+            pattern: '^[a-zA-Z0-9_]+$'
         });
     });
     it('should handle regex with other string validations', () => {
-        const schema = index_1.Schema.from({
-            username: {
-                type: 'string',
-                validations: {
-                    regex: '^[a-zA-Z0-9_]+$',
-                    minLength: 3,
-                    maxLength: 20
-                }
-            }
+        const schema = new index_1.Schema({
+            username: index_1.Schema.string().regex(/^[a-zA-Z0-9_]+$/).min(3).max(20)
         });
         // Valid cases
         expect(schema.validate({ username: 'john_doe123' })).toBe(true);
@@ -164,13 +105,8 @@ describe('Schema Custom String Validations', () => {
         expect(schema.validate({ username: 'a'.repeat(21) })).toBe(false);
     });
     it('should handle regex patterns containing forward slashes', () => {
-        const schema = index_1.Schema.from({
-            path: {
-                type: 'string',
-                validations: {
-                    regex: '^/api/v[0-9]+/users/[0-9]+$'
-                }
-            }
+        const schema = new index_1.Schema({
+            path: index_1.Schema.string().regex(/^\/api\/v[0-9]+\/users\/[0-9]+$/)
         });
         // Valid cases
         expect(schema.validate({ path: '/api/v1/users/123' })).toBe(true);
@@ -180,23 +116,16 @@ describe('Schema Custom String Validations', () => {
         expect(schema.validate({ path: 'api/v1/users/123' })).toBe(false);
         expect(schema.validate({ path: '/api/v1/users' })).toBe(false);
         expect(schema.validate({ path: '/api/v1/users/abc' })).toBe(false);
-        // Verify the description preserves the slashes within the pattern
+        // Verify the description preserves the pattern (regex source keeps escaped slashes)
         const description = schema.describe();
-        expect(description.path).toEqual({
+        expect(description.properties?.path).toMatchObject({
             type: 'string',
-            validations: {
-                regex: '^/api/v[0-9]+/users/[0-9]+$'
-            }
+            pattern: '^\\/api\\/v[0-9]+\\/users\\/[0-9]+$'
         });
     });
     it('should handle round trip of regex patterns containing forward slashes', () => {
-        const schema = index_1.Schema.from({
-            path: {
-                type: 'string',
-                validations: {
-                    regex: '^/api/v[0-9]+/users/[0-9]+$'
-                }
-            }
+        const schema = new index_1.Schema({
+            path: index_1.Schema.string().regex(/^\/api\/v[0-9]+\/users\/[0-9]+$/)
         });
         const description = schema.describe();
         const cloneSchema = index_1.Schema.from(description);
@@ -208,35 +137,20 @@ describe('Schema Custom String Validations', () => {
         expect(cloneSchema.validate({ path: 'api/v1/users/123' })).toBe(false);
         expect(cloneSchema.validate({ path: '/api/v1/users' })).toBe(false);
         expect(cloneSchema.validate({ path: '/api/v1/users/abc' })).toBe(false);
-        // Verify the description preserves the slashes within the pattern
+        // Verify the description preserves the pattern (regex source keeps escaped slashes)
         const cloneDescription = cloneSchema.describe();
-        expect(cloneDescription).toMatchObject(description);
+        expect(cloneDescription.properties?.path).toMatchObject({
+            type: 'string',
+            pattern: '^\\/api\\/v[0-9]+\\/users\\/[0-9]+$'
+        });
     });
 });
 describe('Schema Roundtrip', () => {
     it('should maintain custom validations through describe/from cycle', () => {
-        const originalSchema = index_1.Schema.from({
-            age: {
-                type: 'number',
-                validations: {
-                    min: 18,
-                    max: 100
-                }
-            },
-            email: {
-                type: 'string',
-                validations: {
-                    email: true
-                }
-            },
-            username: {
-                type: 'string',
-                validations: {
-                    regex: '^[a-zA-Z0-9_]+$',
-                    minLength: 3,
-                    maxLength: 20
-                }
-            }
+        const originalSchema = new index_1.Schema({
+            age: index_1.Schema.number().min(18).max(100),
+            email: index_1.Schema.email(),
+            username: index_1.Schema.string().regex(/^[a-zA-Z0-9_]+$/).min(3).max(20)
         });
         const description = originalSchema.describe();
         const reconstructedSchema = index_1.Schema.from(description);

package/dist/test/dates.test.js

@@ -1,29 +1,37 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 const index_1 = require("../index");
+// Dates are represented as ISO 8601 date-time strings (Schema.date() ->
+// z.iso.datetime()), which are natively representable in JSON Schema.
 describe('Schema single date field', () => {
-    const schema = index_1.Schema.from({
-        createdAt: { type: 'date' }
+    const schema = new index_1.Schema({
+        createdAt: index_1.Schema.date()
     });
-    it('should validate a valid date', () => {
+    it('should validate a valid ISO date-time string', () => {
         const data = {
-            createdAt: new Date()
+            createdAt: new Date().toISOString()
         };
         expect(schema.validate(data)).toBe(true);
     });
-    it('should validate a valid date string', () => {
+    it('should validate a fixed ISO date-time string', () => {
         const data = {
-            createdAt: new Date('2024-03-20T12:00:00Z')
+            createdAt: '2024-03-20T12:00:00Z'
         };
         expect(schema.validate(data)).toBe(true);
     });
-    it('should reject invalid date', () => {
+    it('should reject an invalid date string', () => {
         const data = {
             createdAt: 'invalid-date'
         };
         expect(schema.validate(data)).toBe(false);
     });
-    it('should reject non-date value', () => {
+    it('should reject a Date instance (runtime type is a string now)', () => {
+        const data = {
+            createdAt: new Date()
+        };
+        expect(schema.validate(data)).toBe(false);
+    });
+    it('should reject a non-date value', () => {
         const data = {
             createdAt: 123
         };
@@ -31,28 +39,28 @@ describe('Schema single date field', () => {
     });
 });
 describe('Schema array of dates', () => {
-    const schema = index_1.Schema.from({
-        timestamps: { type: 'array', items: { type: 'date' } }
+    const schema = new index_1.Schema({
+        timestamps: index_1.Schema.array(index_1.Schema.date())
     });
-    it('should validate an array of valid dates', () => {
+    it('should validate an array of valid ISO date-time strings', () => {
         const data = {
-            timestamps: [new Date(), new Date()]
+            timestamps: [new Date().toISOString(), new Date().toISOString()]
         };
         expect(schema.validate(data)).toBe(true);
     });
-    it('should validate an array of valid date strings', () => {
+    it('should validate an array of fixed ISO date-time strings', () => {
         const data = {
-            timestamps: [new Date('2024-03-20T12:00:00Z'), new Date('2024-03-21T12:00:00Z')]
+            timestamps: ['2024-03-20T12:00:00Z', '2024-03-21T12:00:00Z']
         };
         expect(schema.validate(data)).toBe(true);
     });
-    it('should reject array with invalid date', () => {
+    it('should reject an array with an invalid date string', () => {
         const data = {
-            timestamps: [new Date(), 'invalid-date']
+            timestamps: [new Date().toISOString(), 'invalid-date']
         };
         expect(schema.validate(data)).toBe(false);
     });
-    it('should reject non-array value', () => {
+    it('should reject a non-array value', () => {
         const data = {
             timestamps: 'not-an-array'
         };
@@ -60,15 +68,27 @@ describe('Schema array of dates', () => {
     });
 });
 describe('Dates Schema description', () => {
-    it('should correctly describe date fields', () => {
+    it('should describe date fields as date-time formatted strings', () => {
         const schema = new index_1.Schema({
             createdAt: index_1.Schema.date(),
             timestamps: index_1.Schema.array(index_1.Schema.date())
         });
         const description = schema.describe();
-        expect(description).toEqual({
-            createdAt: { type: 'date' },
-            timestamps: { type: 'array', items: { type: 'date' } }
+        expect(description.properties?.createdAt).toMatchObject({
+            type: 'string',
+            format: 'date-time'
+        });
+        expect(description.properties?.timestamps).toMatchObject({
+            type: 'array',
+            items: { type: 'string', format: 'date-time' }
+        });
+    });
+    it('should round-trip date validation through describe/from', () => {
+        const schema = new index_1.Schema({
+            createdAt: index_1.Schema.date()
         });
+        const clone = index_1.Schema.from(schema.describe());
+        expect(clone.validate({ createdAt: '2024-03-20T12:00:00Z' })).toBe(true);
+        expect(clone.validate({ createdAt: 'invalid-date' })).toBe(false);
     });
 });

package/dist/test/describe.test.d.ts

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