@forgehive/schema 0.1.0

package/dist/test/record.test.js

@@ -0,0 +1,303 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_1 = __importDefault(require("../index"));
+describe('Schema Record Types', () => {
+    describe('String Record', () => {
+        it('should validate a record with string values', () => {
+            const schema = new index_1.default({
+                data: index_1.default.stringRecord(),
+            });
+            const result = schema.validate({
+                data: {
+                    firstName: 'John',
+                    lastName: 'Doe',
+                    occupation: 'Developer'
+                }
+            });
+            expect(result).toBe(true);
+        });
+        it('should reject a record with non-string values', () => {
+            const schema = new index_1.default({
+                data: index_1.default.stringRecord(),
+            });
+            const result = schema.validate({
+                data: {
+                    name: 'John',
+                    age: 30, // Number is not allowed
+                    isActive: true // Boolean is not allowed
+                }
+            });
+            expect(result).toBe(false);
+        });
+        it('should create a schema from description with string record type', () => {
+            const description = {
+                data: {
+                    type: 'stringRecord',
+                    optional: false
+                }
+            };
+            const schema = index_1.default.from(description);
+            const validData = {
+                data: {
+                    firstName: 'John',
+                    lastName: 'Doe'
+                }
+            };
+            const result = schema.validate(validData);
+            expect(result).toBe(true);
+        });
+    });
+    describe('Number Record', () => {
+        it('should validate a record with number values', () => {
+            const schema = new index_1.default({
+                data: index_1.default.numberRecord(),
+            });
+            const result = schema.validate({
+                data: {
+                    age: 30,
+                    experience: 5,
+                    salary: 100000
+                }
+            });
+            expect(result).toBe(true);
+        });
+        it('should reject a record with non-number values', () => {
+            const schema = new index_1.default({
+                data: index_1.default.numberRecord(),
+            });
+            const result = schema.validate({
+                data: {
+                    age: 30,
+                    name: 'John', // String is not allowed
+                    isActive: true // Boolean is not allowed
+                }
+            });
+            expect(result).toBe(false);
+        });
+        it('should create a schema from description with number record type', () => {
+            const description = {
+                data: {
+                    type: 'numberRecord',
+                    optional: false
+                }
+            };
+            const schema = index_1.default.from(description);
+            const validData = {
+                data: {
+                    age: 30,
+                    experience: 5
+                }
+            };
+            const result = schema.validate(validData);
+            expect(result).toBe(true);
+        });
+    });
+    describe('Boolean Record', () => {
+        it('should validate a record with boolean values', () => {
+            const schema = new index_1.default({
+                data: index_1.default.booleanRecord(),
+            });
+            const result = schema.validate({
+                data: {
+                    isActive: true,
+                    isAdmin: false,
+                    hasAccess: true
+                }
+            });
+            expect(result).toBe(true);
+        });
+        it('should reject a record with non-boolean values', () => {
+            const schema = new index_1.default({
+                data: index_1.default.booleanRecord(),
+            });
+            const result = schema.validate({
+                data: {
+                    isActive: true,
+                    name: 'John', // String is not allowed
+                    age: 30 // Number is not allowed
+                }
+            });
+            expect(result).toBe(false);
+        });
+        it('should create a schema from description with boolean record type', () => {
+            const description = {
+                data: {
+                    type: 'booleanRecord',
+                    optional: false
+                }
+            };
+            const schema = index_1.default.from(description);
+            const validData = {
+                data: {
+                    isActive: true,
+                    isAdmin: false
+                }
+            };
+            const result = schema.validate(validData);
+            expect(result).toBe(true);
+        });
+    });
+    describe('Mixed Record', () => {
+        it('should validate a record with mixed values (string, number, boolean)', () => {
+            const schema = new index_1.default({
+                data: index_1.default.mixedRecord(),
+            });
+            const result = schema.validate({
+                data: {
+                    name: 'John',
+                    age: 30,
+                    isActive: true
+                }
+            });
+            expect(result).toBe(true);
+        });
+        it('should validate a record with only string values', () => {
+            const schema = new index_1.default({
+                data: index_1.default.mixedRecord(),
+            });
+            const result = schema.validate({
+                data: {
+                    firstName: 'John',
+                    lastName: 'Doe',
+                    occupation: 'Developer'
+                }
+            });
+            expect(result).toBe(true);
+        });
+        it('should validate a record with only number values', () => {
+            const schema = new index_1.default({
+                data: index_1.default.mixedRecord(),
+            });
+            const result = schema.validate({
+                data: {
+                    age: 30,
+                    experience: 5,
+                    salary: 100000
+                }
+            });
+            expect(result).toBe(true);
+        });
+        it('should validate a record with only boolean values', () => {
+            const schema = new index_1.default({
+                data: index_1.default.mixedRecord(),
+            });
+            const result = schema.validate({
+                data: {
+                    isActive: true,
+                    isAdmin: false,
+                    hasAccess: true
+                }
+            });
+            expect(result).toBe(true);
+        });
+        it('should reject a record with invalid value types', () => {
+            const schema = new index_1.default({
+                data: index_1.default.mixedRecord(),
+            });
+            const result = schema.validate({
+                data: {
+                    name: 'John',
+                    createdAt: new Date(), // Date is not allowed
+                    items: [1, 2, 3] // Array is not allowed
+                }
+            });
+            expect(result).toBe(false);
+        });
+        it('should create a schema from description with mixed record type', () => {
+            const description = {
+                data: {
+                    type: 'mixedRecord',
+                    optional: false
+                }
+            };
+            const schema = index_1.default.from(description);
+            const validData = {
+                data: {
+                    name: 'John',
+                    age: 30,
+                    isActive: true
+                }
+            };
+            const result = schema.validate(validData);
+            expect(result).toBe(true);
+        });
+    });
+    describe('Common Record Functionality', () => {
+        it('should reject a record with non-string keys', () => {
+            const schema = new index_1.default({
+                data: index_1.default.stringRecord(),
+            });
+            // TypeScript would catch this at compile time, but we're testing runtime behavior
+            const invalidData = {
+                data: {
+                    name: 'John',
+                }
+            };
+            // Add a non-string key using Object.defineProperty
+            Object.defineProperty(invalidData.data, 123, {
+                value: 'test',
+                enumerable: true
+            });
+            // Note: Zod's record validation doesn't actually check for non-string keys at runtime
+            // This is a limitation of JavaScript/TypeScript, as all object keys are converted to strings
+            // So this test will actually pass, not fail
+            const result = schema.validate(invalidData);
+            expect(result).toBe(true);
+        });
+        it('should create a schema from description with optional record type', () => {
+            const description = {
+                data: {
+                    type: 'stringRecord',
+                    optional: true
+                }
+            };
+            const schema = index_1.default.from(description);
+            // Test with record present
+            const validData1 = {
+                data: {
+                    name: 'John'
+                }
+            };
+            // Test with record missing
+            const validData2 = {};
+            expect(schema.validate(validData1)).toBe(true);
+            expect(schema.validate(validData2)).toBe(true);
+        });
+        it('should describe a schema with string record type', () => {
+            const schema = new index_1.default({
+                data: index_1.default.stringRecord(),
+            });
+            const description = schema.describe();
+            expect(description).toHaveProperty('data');
+            expect(description.data).toHaveProperty('type', 'stringRecord');
+            // The optional property is only included when it's true, not when it's false
+        });
+        it('should describe a schema with number record type', () => {
+            const schema = new index_1.default({
+                data: index_1.default.numberRecord(),
+            });
+            const description = schema.describe();
+            expect(description).toHaveProperty('data');
+            expect(description.data).toHaveProperty('type', 'numberRecord');
+        });
+        it('should describe a schema with boolean record type', () => {
+            const schema = new index_1.default({
+                data: index_1.default.booleanRecord(),
+            });
+            const description = schema.describe();
+            expect(description).toHaveProperty('data');
+            expect(description.data).toHaveProperty('type', 'booleanRecord');
+        });
+        it('should describe a schema with mixed record type', () => {
+            const schema = new index_1.default({
+                data: index_1.default.mixedRecord(),
+            });
+            const description = schema.describe();
+            expect(description).toHaveProperty('data');
+            expect(description.data).toHaveProperty('type', 'mixedRecord');
+        });
+    });
+});

package/jest.config.js

@@ -0,0 +1,11 @@
+/** @type {import('jest').Config} */
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  roots: ['<rootDir>/src'],
+  testMatch: ['**/src/test/**/*.ts', '**/?(*.)+(spec|test).ts'],
+  transform: {
+    '^.+\\.ts$': 'ts-jest'
+  },
+  moduleFileExtensions: ['ts', 'js', 'json', 'node']
+} 

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@forgehive/schema",
+  "version": "0.1.0",
+  "license": "MIT",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "devDependencies": {
+    "@types/jest": "^29.5.14",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.1.2"
+  },
+  "dependencies": {
+    "zod": "^3.24.2"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "jest",
+    "test:watch": "jest --watch"
+  }
+}

package/src/index.ts

@@ -0,0 +1,361 @@
+import { z } from 'zod'
+
+// Export a type alias for Schema fields
+export type SchemaType = z.ZodType<string | boolean | number | Date | string[] | boolean[] | number[] | Date[] | Record<string, string | number | boolean>> | z.ZodOptional<z.ZodType<string | boolean | number | Date | string[] | boolean[] | number[] | Date[] | Record<string, string | number | boolean>>>;
+
+type AllowedBaseTypes = 'string' | 'boolean' | 'number' | 'date' | 'stringRecord' | 'numberRecord' | 'booleanRecord' | 'mixedRecord'
+type ArrayTypes = z.ZodString | z.ZodBoolean | z.ZodNumber | z.ZodDate
+
+type NumberValidations = {
+  min?: number
+  max?: number
+}
+
+type StringValidations = {
+  email?: boolean
+  minLength?: number
+  maxLength?: number
+  regex?: string
+}
+
+// Export extended Zod types for use throughout the app
+export type ShadowString = z.ZodString
+export type ShadowBoolean = z.ZodBoolean
+export type ShadowNumber = z.ZodNumber
+export type ShadowDate = z.ZodDate
+export type ShadowArray<T extends ArrayTypes> = z.ZodArray<T>
+export type ShadowStringRecord = z.ZodRecord<z.ZodString, z.ZodString>
+export type ShadowNumberRecord = z.ZodRecord<z.ZodString, z.ZodNumber>
+export type ShadowBooleanRecord = z.ZodRecord<z.ZodString, z.ZodBoolean>
+export type ShadowMixedRecord = z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean]>>
+
+// Export inferred types for use throughout the app
+export type InferShadowString = z.infer<ShadowString>
+export type InferShadowBoolean = z.infer<ShadowBoolean>
+export type InferShadowNumber = z.infer<ShadowNumber>
+export type InferShadowDate = z.infer<ShadowDate>
+export type InferShadowArray<T extends ArrayTypes> = z.infer<ShadowArray<T>>
+export type InferShadowStringRecord = z.infer<ShadowStringRecord>
+export type InferShadowNumberRecord = z.infer<ShadowNumberRecord>
+export type InferShadowBooleanRecord = z.infer<ShadowBooleanRecord>
+export type InferShadowMixedRecord = z.infer<ShadowMixedRecord>
+
+// Export a type utility for inferring schema types
+export type InferSchema<S extends Schema<Record<string, SchemaType>>> = z.infer<S['schema']>
+
+type BaseSchemaDescription = {
+  type: AllowedBaseTypes
+  optional?: boolean
+  validations?: NumberValidations | StringValidations
+}
+
+type ArraySchemaDescription = {
+  type: 'array'
+  items: {
+    type: AllowedBaseTypes
+  }
+  optional?: boolean
+}
+
+export type SchemaDescription = Record<string, BaseSchemaDescription | ArraySchemaDescription>
+
+// Static methods for type definitions
+export class Schema<T extends Record<string, z.ZodType<string | boolean | number | Date | string[] | boolean[] | number[] | Date[] | Record<string, string | number | boolean>> | z.ZodOptional<z.ZodType<string | boolean | number | Date | string[] | boolean[] | number[] | Date[] | Record<string, string | number | boolean>>>>> {
+  readonly schema: z.ZodObject<T>
+
+  constructor(fields: T) {
+    this.schema = z.object(fields)
+  }
+
+  /**
+   * Creates a string schema
+   * @returns A string schema
+   */
+  static string(): ShadowString {
+    return z.string()
+  }
+
+  /**
+   * Creates a boolean schema
+   * @returns A boolean schema
+   */
+  static boolean(): ShadowBoolean {
+    return z.boolean()
+  }
+
+  /**
+   * Creates a number schema
+   * @returns A number schema
+   */
+  static number(): ShadowNumber {
+    return z.number()
+  }
+
+  /**
+   * Creates a date schema
+   * @returns A date schema
+   */
+  static date(): ShadowDate {
+    return z.date()
+  }
+
+  /**
+   * Creates a record schema with string keys and string values
+   * @returns A record schema with string values
+   */
+  static stringRecord(): ShadowStringRecord {
+    return z.record(z.string(), z.string())
+  }
+
+  /**
+   * Creates a record schema with string keys and number values
+   * @returns A record schema with number values
+   */
+  static numberRecord(): ShadowNumberRecord {
+    return z.record(z.string(), z.number())
+  }
+
+  /**
+   * Creates a record schema with string keys and boolean values
+   * @returns A record schema with boolean values
+   */
+  static booleanRecord(): ShadowBooleanRecord {
+    return z.record(z.string(), z.boolean())
+  }
+
+  /**
+   * Creates a record schema with string keys and mixed values (string, number, or boolean)
+   * @returns A record schema with mixed values
+   */
+  static mixedRecord(): ShadowMixedRecord {
+    return z.record(z.string(), z.union([z.string(), z.number(), z.boolean()]))
+  }
+
+  /**
+   * Creates an array schema
+   * @param type The type of items in the array
+   * @returns An array schema
+   */
+  static array<T extends ArrayTypes>(type: T): ShadowArray<T> {
+    return z.array(type) as ShadowArray<T>
+  }
+
+  /**
+   * Infers the TypeScript type from a Schema instance
+   * @template S The Schema type
+   * @returns The inferred TypeScript type
+   */
+  static infer<S extends Schema<Record<string, z.ZodTypeAny>>>(_schema: S): z.infer<S['schema']> {
+    // This is a type-level utility, the implementation is not used at runtime
+    return {} as z.infer<S['schema']>
+  }
+
+  /**
+   * Creates a Schema instance from a description object
+   * @param description Object describing the schema structure with type information
+   * @returns A new Schema instance
+   */
+  static from(description: SchemaDescription): Schema<Record<string, z.ZodType<string | boolean | number | Date | string[] | boolean[] | number[] | Date[] | Record<string, string | number | boolean>> | z.ZodOptional<z.ZodType<string | boolean | number | Date | string[] | boolean[] | number[] | Date[] | Record<string, string | number | boolean>>>>> {
+    const fields: Record<string, z.ZodType<string | number | boolean | Date | string[] | number[] | boolean[] | Date[] | Record<string, string | number | boolean>> | z.ZodOptional<z.ZodType<string | number | boolean | Date | string[] | number[] | boolean[] | Date[] | Record<string, string | number | boolean>>>> = {}
+
+    for (const [key, field] of Object.entries(description)) {
+      const fieldType = field.type
+      let fieldSchema: z.ZodType<string | boolean | number | Date | string[] | boolean[] | number[] | Date[] | Record<string, string | number | boolean>>
+
+      switch (fieldType) {
+      case 'string': {
+        let stringSchema = Schema.string()
+        if (field.validations) {
+          const validations = field.validations as StringValidations
+          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 as NumberValidations
+          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 as ArraySchemaDescription
+        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
+    }
+
+    return new Schema(fields)
+  }
+
+  /**
+   * Validates the provided data against the schema
+   * @param data The data to validate
+   * @returns A boolean indicating whether the data is valid
+   */
+  validate(data: unknown): boolean {
+    const result = this.schema.safeParse(data)
+
+    return result.success
+  }
+
+  /**
+   * Parses and validates the provided data against the schema
+   * @param data The data to parse and validate
+   * @returns The parsed and typed data
+   * @throws {z.ZodError} If the data is invalid
+   */
+  parse(data: unknown): z.infer<z.ZodObject<T>> {
+    return this.schema.parse(data)
+  }
+
+  /**
+   * Safely parses and validates the provided data against the schema
+   * @param data The data to parse and validate
+   * @returns An object containing either the successfully parsed data or error information
+   */
+  safeParse(data: unknown): z.SafeParseReturnType<z.infer<z.ZodObject<T>>, z.infer<z.ZodObject<T>>> {
+    return this.schema.safeParse(data)
+  }
+
+  /**
+   * Describes the schema structure and allowed types
+   * @returns An object describing the schema structure with type information
+   */
+  describe(): SchemaDescription {
+    const shape = this.schema.shape
+    const description: SchemaDescription = {}
+
+    for (const [key, value] of Object.entries(shape)) {
+      const isOptional = value instanceof z.ZodOptional
+      const baseValue = isOptional ? value.unwrap() : value
+
+      if (baseValue instanceof z.ZodString) {
+        const validations: StringValidations = {}
+        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] = {
+          type: 'string',
+          ...(isOptional && { optional: true }),
+          ...(Object.keys(validations).length > 0 && { validations })
+        }
+      } else if (baseValue instanceof z.ZodBoolean) {
+        description[key] = { type: 'boolean', ...(isOptional && { optional: true }) }
+      } else if (baseValue instanceof z.ZodNumber) {
+        const validations: NumberValidations = {}
+        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] = {
+          type: 'number',
+          ...(isOptional && { optional: true }),
+          ...(Object.keys(validations).length > 0 && { validations })
+        }
+      } else if (baseValue instanceof z.ZodDate) {
+        description[key] = { type: 'date', ...(isOptional && { optional: true }) }
+      } else if (baseValue instanceof z.ZodArray) {
+        const element = baseValue.element
+        if (element instanceof z.ZodString) {
+          description[key] = { type: 'array', items: { type: 'string' }, ...(isOptional && { optional: true }) }
+        } else if (element instanceof z.ZodBoolean) {
+          description[key] = { type: 'array', items: { type: 'boolean' }, ...(isOptional && { optional: true }) }
+        } else if (element instanceof z.ZodNumber) {
+          description[key] = { type: 'array', items: { type: 'number' }, ...(isOptional && { optional: true }) }
+        } else if (element instanceof z.ZodDate) {
+          description[key] = { type: 'array', items: { type: 'date' }, ...(isOptional && { optional: true }) }
+        }
+      } else if (baseValue instanceof z.ZodRecord) {
+        // Check the value type of the record
+        const valueType = baseValue._def.valueType
+        if (valueType instanceof z.ZodString) {
+          description[key] = { type: 'stringRecord', ...(isOptional && { optional: true }) }
+        } else if (valueType instanceof z.ZodNumber) {
+          description[key] = { type: 'numberRecord', ...(isOptional && { optional: true }) }
+        } else if (valueType instanceof z.ZodBoolean) {
+          description[key] = { type: 'booleanRecord', ...(isOptional && { optional: true }) }
+        } else if (valueType instanceof z.ZodUnion) {
+          description[key] = { type: 'mixedRecord', ...(isOptional && { optional: true }) }
+        }
+      }
+    }
+
+    return description
+  }
+}
+
+export default Schema
+