@forgehive/schema 0.1.4 → 0.2.0

package/src/test/from.test.ts

@@ -0,0 +1,191 @@
+import { Schema, type SchemaDescription } from '../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: SchemaDescription = {
+      type: 'object',
+      properties: {
+        name: { type: 'string' },
+        age: { type: 'number' },
+        active: { type: 'boolean' },
+      },
+      required: ['name', 'age', 'active'],
+    }
+
+    const schema = 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: SchemaDescription = {
+      type: 'object',
+      properties: {
+        username: {
+          type: 'string',
+          minLength: 3,
+          maxLength: 20,
+          pattern: '^[a-zA-Z0-9_]+$',
+        },
+      },
+      required: ['username'],
+    }
+
+    const schema = 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: SchemaDescription = {
+      type: 'object',
+      properties: {
+        age: { type: 'number', minimum: 18, maximum: 100 },
+      },
+      required: ['age'],
+    }
+
+    const schema = 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: SchemaDescription = {
+      type: 'object',
+      properties: {
+        name: { type: 'string' },
+        age: { type: 'number' },
+      },
+      required: ['name'], // age is optional
+    }
+
+    const schema = 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: SchemaDescription = {
+      type: 'object',
+      properties: {
+        tags: { type: 'array', items: { type: 'string' } },
+      },
+      required: ['tags'],
+    }
+
+    const schema = 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: SchemaDescription = {
+      type: 'object',
+      properties: {
+        data: {
+          type: 'object',
+          propertyNames: { type: 'string' },
+          additionalProperties: { type: 'number' },
+        },
+      },
+      required: ['data'],
+    }
+
+    const schema = 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: SchemaDescription = {
+      type: 'object',
+      properties: {
+        data: {
+          type: 'object',
+          propertyNames: { type: 'string' },
+          additionalProperties: {
+            anyOf: [{ type: 'string' }, { type: 'number' }, { type: 'boolean' }],
+          },
+        },
+      },
+      required: ['data'],
+    }
+
+    const schema = 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: SchemaDescription = {
+      type: 'object',
+      properties: {
+        user: {
+          type: 'object',
+          properties: {
+            name: { type: 'string', minLength: 2 },
+            age: { type: 'number' },
+          },
+          required: ['name'],
+        },
+      },
+      required: ['user'],
+    }
+
+    const schema = 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: SchemaDescription = {
+      type: 'object',
+      properties: {
+        email: { type: 'string', format: 'email' },
+      },
+      required: ['email'],
+    }
+
+    const schema = 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: SchemaDescription = {
+      type: 'object',
+      properties: {
+        createdAt: { type: 'string', format: 'date-time' },
+      },
+      required: ['createdAt'],
+    }
+
+    const schema = Schema.from(jsonSchema)
+
+    expect(schema.validate({ createdAt: '2024-03-20T12:00:00Z' })).toBe(true)
+    expect(schema.validate({ createdAt: 'not-a-date' })).toBe(false)
+  })
+})

package/src/test/index.test.ts

@@ -1,4 +1,4 @@
-import Schema, { type SchemaDescription } from '../index'
+import Schema from '../index'
 
 describe('Schema basic types', () => {
   it('should validate a string', () => {
@@ -28,16 +28,18 @@ describe('Schema basic types', () => {
   })
 })
 
-describe('Schema description', () => {
+describe('Schema description (JSON Schema)', () => {
   it('should describe a string', () => {
     const schema = new Schema({
       name: Schema.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', () => {
@@ -47,26 +49,29 @@ describe('Schema description', () => {
     })
 
     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: SchemaDescription = {
-      name: { type: 'string' },
-      age: { type: 'number' },
-    }
-    const schema = Schema.from(description)
+  it('should rebuild a schema from its description', () => {
+    const original = new Schema({
+      name: Schema.string(),
+      age: Schema.number(),
+    })
+
+    const schema = Schema.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'])
   })
 })
 
@@ -96,20 +101,31 @@ describe('Schema validation errors', () => {
   })
 })
 
-// describe('Schema optional fields', () => {
-//   it('should validate with missing optional field', () => {
-//     const schema = new Schema({
-//       name: Schema.string(),
-//       age: Schema.number().optional(),
-//     })
+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)
+  })
 
-//     const result = schema.validate({
-//       name: 'World',
-//     })
+  it('should omit optional fields from the required list', () => {
+    const schema = new Schema({
+      name: Schema.string(),
+      age: Schema.number().optional(),
+    })
 
-//     expect(result).toBe(true)
-//   })
-// })
+    const result = schema.describe()
+    expect(result.required).toEqual(['name'])
+    expect(result.properties).toHaveProperty('age')
+  })
+})
 
 describe('Schema arrays', () => {
   it('should validate array of strings', () => {
@@ -167,32 +183,102 @@ describe('Schema arrays', () => {
     })
 
     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: SchemaDescription = {
-      tags: { type: 'array', items: { type: 'string' } },
-      scores: { type: 'array', items: { type: 'number' } },
-    }
-    const schema = Schema.from(description)
+    const original = new Schema({
+      tags: Schema.array(Schema.string()),
+      scores: Schema.array(Schema.number()),
+    })
+    const schema = Schema.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 Schema({
+      user: Schema.object({
+        name: Schema.string(),
+        age: Schema.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 Schema({
+      user: Schema.object({
+        name: Schema.string().min(3),
+      }),
+    })
+
+    const clone = Schema.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 Schema({
+      name: Schema.string().describe('The name of the user'),
+      address: Schema.object({
+        street: Schema.string(),
+        city: Schema.string(),
+        state: Schema.string(),
+        zip: Schema.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: string = withoutAddress.data.name
+      const street: string = 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 Schema({
       age: Schema.number().min(0).max(120),
-      email: Schema.string().email(),
+      email: Schema.email(),
     })
 
     const result = schema.validate({
@@ -202,4 +288,35 @@ describe('Schema custom validation', () => {
 
     expect(result).toBe(true)
   })
+
+  it('should serialize element descriptions', () => {
+    const schema = new Schema({
+      name: Schema.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 Schema({
+      name: Schema.string().describe('The name of the user'),
+      age: Schema.number().describe('The age of the user'),
+    })
+
+    const clone = Schema.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/src/test/optionals.test.ts

@@ -1,11 +1,11 @@
 import { Schema } from '../index'
 
-describe('Schema Custom Validations', () => {
+describe('Schema Optional Fields', () => {
   describe('Optional Fields', () => {
     it('should handle optional string fields', () => {
-      const schema = Schema.from({
-        name: { type: 'string', optional: true },
-        age: { type: 'number' }
+      const schema = new Schema({
+        name: Schema.string().optional(),
+        age: Schema.number()
       })
 
       // Valid with optional field present
@@ -19,9 +19,9 @@ describe('Schema Custom Validations', () => {
     })
 
     it('should handle optional array fields', () => {
-      const schema = Schema.from({
-        tags: { type: 'array', items: { type: 'string' }, optional: true },
-        scores: { type: 'array', items: { type: 'number' } }
+      const schema = new Schema({
+        tags: Schema.array(Schema.string()).optional(),
+        scores: Schema.array(Schema.number())
       })
 
       // Valid with optional array present
@@ -35,26 +35,28 @@ describe('Schema Custom Validations', () => {
     })
 
     it('should correctly describe optional fields', () => {
-      const schema = Schema.from({
-        name: { type: 'string', optional: true },
-        age: { type: 'number' },
-        tags: { type: 'array', items: { type: 'string' }, optional: true }
+      const schema = new Schema({
+        name: Schema.string().optional(),
+        age: Schema.number(),
+        tags: Schema.array(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 = Schema.from({
-        name: { type: 'string', optional: true },
-        age: { type: 'number' },
-        tags: { type: 'array', items: { type: 'string' }, optional: true }
+      const originalSchema = new Schema({
+        name: Schema.string().optional(),
+        age: Schema.number(),
+        tags: Schema.array(Schema.string()).optional()
       })
 
       const description = originalSchema.describe()
@@ -68,6 +70,9 @@ 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/src/test/parse.test.ts

@@ -0,0 +1,160 @@
+import { Schema } from '../index'
+
+describe('Schema.parse()', () => {
+  it('returns typed data on success', () => {
+    const schema = new Schema({
+      name: Schema.string(),
+      age: Schema.number(),
+    })
+
+    const data = schema.parse({ name: 'John', age: 30 })
+
+    expect(data).toEqual({ name: 'John', age: 30 })
+    // Type-level: the result is { name: string; age: number }
+    const name: string = data.name
+    const age: number = data.age
+    expect(name).toBe('John')
+    expect(age).toBe(30)
+  })
+
+  it('strips unknown keys', () => {
+    const schema = new Schema({
+      name: Schema.string(),
+    })
+
+    const data = schema.parse({ name: 'John', extra: 'ignored' })
+
+    expect(data).toEqual({ name: 'John' })
+    expect(data).not.toHaveProperty('extra')
+  })
+
+  it('coerces nothing and throws ZodError on invalid data', () => {
+    const schema = new Schema({
+      name: Schema.string(),
+      age: Schema.number(),
+    })
+
+    expect(() => schema.parse({ name: 'John', age: 'thirty' })).toThrow()
+  })
+
+  it('throws a ZodError exposing issues with path and message', () => {
+    const schema = new Schema({
+      name: Schema.string(),
+      age: Schema.number().min(18),
+    })
+
+    try {
+      schema.parse({ name: 123, age: 10 })
+      throw new Error('expected parse to throw')
+    } catch (err) {
+      const zodError = err as { issues?: Array<{ path: PropertyKey[]; message: string }> }
+      expect(Array.isArray(zodError.issues)).toBe(true)
+      const paths = (zodError.issues ?? []).map((issue) => issue.path.join('.'))
+      expect(paths).toContain('name')
+      expect(paths).toContain('age')
+    }
+  })
+
+  it('parses nested objects and optionals', () => {
+    const schema = new Schema({
+      user: Schema.object({
+        name: Schema.string(),
+        nickname: Schema.string().optional(),
+      }),
+    })
+
+    expect(schema.parse({ user: { name: 'John' } })).toEqual({ user: { name: 'John' } })
+    expect(schema.parse({ user: { name: 'John', nickname: 'JJ' } })).toEqual({
+      user: { name: 'John', nickname: 'JJ' },
+    })
+    expect(() => schema.parse({ user: {} })).toThrow()
+  })
+})
+
+describe('Schema.safeParse()', () => {
+  it('returns success: true with data on valid input', () => {
+    const schema = new Schema({
+      name: Schema.string(),
+      age: Schema.number(),
+    })
+
+    const result = schema.safeParse({ name: 'John', age: 30 })
+
+    expect(result.success).toBe(true)
+    if (result.success) {
+      expect(result.data).toEqual({ name: 'John', age: 30 })
+      // Type-level: result.data is fully typed
+      const name: string = result.data.name
+      expect(name).toBe('John')
+    }
+  })
+
+  it('returns success: false with an error on invalid input', () => {
+    const schema = new Schema({
+      name: Schema.string(),
+      age: Schema.number(),
+    })
+
+    const result = schema.safeParse({ name: 'John', age: 'thirty' })
+
+    expect(result.success).toBe(false)
+    if (!result.success) {
+      expect(result.error).toBeDefined()
+      expect(Array.isArray(result.error.issues)).toBe(true)
+      const paths = result.error.issues.map((issue) => issue.path.join('.'))
+      expect(paths).toContain('age')
+    }
+  })
+
+  it('does not throw on invalid input', () => {
+    const schema = new Schema({
+      age: Schema.number(),
+    })
+
+    expect(() => schema.safeParse({ age: 'nope' })).not.toThrow()
+  })
+
+  it('reports each failing field in the issues list', () => {
+    const schema = new Schema({
+      email: Schema.email(),
+      age: Schema.number().min(18),
+      username: Schema.string().min(3),
+    })
+
+    const result = schema.safeParse({ email: 'nope', age: 5, username: 'ab' })
+
+    expect(result.success).toBe(false)
+    if (!result.success) {
+      const paths = result.error.issues.map((issue) => issue.path.join('.'))
+      expect(paths).toEqual(expect.arrayContaining(['email', 'age', 'username']))
+    }
+  })
+
+  it('strips unknown keys on success', () => {
+    const schema = new Schema({
+      name: Schema.string(),
+    })
+
+    const result = schema.safeParse({ name: 'John', extra: true })
+
+    expect(result.success).toBe(true)
+    if (result.success) {
+      expect(result.data).toEqual({ name: 'John' })
+    }
+  })
+
+  it('infers optional fields as possibly undefined', () => {
+    const schema = new Schema({
+      name: Schema.string(),
+      age: Schema.number().optional(),
+    })
+
+    const result = schema.safeParse({ name: 'John' })
+
+    expect(result.success).toBe(true)
+    if (result.success) {
+      const age: number | undefined = result.data.age
+      expect(age).toBeUndefined()
+    }
+  })
+})