@forgehive/schema 0.1.4 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 # @forgehive/schema
 
-A powerful schema validation library built on top of Zod, providing type-safe validation and type inference.
+A thin, type-safe wrapper around [Zod 4](https://zod.dev) that adds JSON Schema serialization and rehydration on top of native Zod validation.
 
 ## Installation
 
@@ -10,59 +10,68 @@ npm install @forgehive/schema
 
 ## Overview
 
-The `@forgehive/schema` package provides a wrapper around Zod with additional features:
+`@forgehive/schema` wraps a Zod object schema in a `Schema` class. Fields are created with the
+`Schema.*` helpers, which keeps your call sites independent of the underlying validation library —
+so Zod can be swapped or upgraded without touching consumer code. In return you get:
 
-- Type-safe schema definitions
-- Built-in validation methods
-- Schema description capabilities
-- Type inference utilities
+- **Type-safe validation** — `parse`, `safeParse`, `validate`
+- **Type inference** — `InferSchema<typeof schema>`
+- **JSON Schema serialization** — `describe()` emits standard [JSON Schema](https://zod.dev/json-schema) (draft 2020-12)
+- **Rehydration** — `Schema.from(jsonSchema)` rebuilds a `Schema` from JSON Schema
 
-## Basic Usage
+Helpers return real Zod types, so chaining (`.min()`, `.optional()`, `.describe()`, ...) works as
+usual. The full `z` namespace is also re-exported as an escape hatch for anything the helpers
+don't cover. See [`docs/specs/schema.md`](../../docs/specs/schema.md) for the design rationale.
 
-Here's a simple example of creating and using a schema:
+## Basic Usage
 
 ```typescript
 import { Schema } from '@forgehive/schema';
 
-// Create a schema with validation
 const userSchema = new Schema({
-  name: Schema.string(),
+  name: Schema.string().describe('The name of the user'),
   age: Schema.number().min(0).max(120),
-  email: Schema.string().email(),
-  tags: Schema.array(Schema.string())
+  email: Schema.email(),
+  tags: Schema.array(Schema.string()),
 });
 
-// Validate data
 const result = userSchema.safeParse({
   name: 'John Doe',
   age: 30,
   email: 'john@example.com',
-  tags: ['user', 'active']
+  tags: ['user', 'active'],
 });
 
 if (result.success) {
   // TypeScript knows the shape of the data
-  const user = result.data;
-  console.log(user.name); // TypeScript knows this is a string
+  console.log(result.data.name); // string
 }
 ```
 
-## Schema Types
+## Building Fields
 
-The package provides several schema types:
+Use the `Schema.*` helpers to declare fields:
 
 ```typescript
 // Basic types
 Schema.string()
 Schema.number()
 Schema.boolean()
-Schema.date()
+Schema.date()    // ISO 8601 date-time string (see note below)
+
+// String formats (serialize to JSON Schema `format`)
+Schema.email()   // format: "email"
+Schema.uuid()    // format: "uuid"
+Schema.url()     // format: "uri"
 
 // Arrays
 Schema.array(Schema.string())
-Schema.array(Schema.number())
-Schema.array(Schema.boolean())
-Schema.array(Schema.date())
+
+// Nested objects
+Schema.object({
+  street: Schema.string(),
+  zip: Schema.string().regex(/^[0-9]{5}$/),
+})
 
 // Records
 Schema.stringRecord()  // Record<string, string>
@@ -71,91 +80,128 @@ Schema.booleanRecord() // Record<string, boolean>
 Schema.mixedRecord()   // Record<string, string | number | boolean>
 ```
 
-## Validation
+Validations and metadata are added with chaining: `.min()`, `.max()`, `.regex()`, `.optional()`,
+`.describe('...')`, etc.
 
-Schemas provide several validation methods:
+For anything the helpers don't cover (enums, unions, refinements), reach for the re-exported `z`:
+
+```typescript
+import { Schema, z } from '@forgehive/schema';
+
+const schema = new Schema({
+  role: z.enum(['admin', 'user', 'guest']),
+});
+```
+
+> **Note on dates:** `Schema.date()` validates an ISO 8601 date-time **string**
+> (e.g. `"2024-03-20T12:00:00Z"`), not a `Date` instance. JSON Schema has no native date type,
+> so dates are represented as `{ type: "string", format: "date-time" }`.
+
+## Validation
 
 ```typescript
 const schema = new Schema({
   name: Schema.string(),
-  age: Schema.number()
+  age: Schema.number(),
 });
 
 // Parse and throw on error
 const data = schema.parse({ name: 'John', age: 30 });
 
-// Safe parse with result object
+// Safe parse with a result object
 const result = schema.safeParse({ name: 'John', age: 30 });
 if (result.success) {
   const data = result.data;
 } else {
-  const errors = result.error;
+  const issues = result.error.issues; // ZodError
 }
 
-// Validate without parsing
+// Validate without parsing (boolean)
 const isValid = schema.validate({ name: 'John', age: 30 });
 ```
 
-## Schema Description
+## Serialization (`describe`) and Rehydration (`from`)
 
-You can get a description of the schema structure:
+`describe()` returns standard JSON Schema. Every validation and `.describe()` on a field is
+included automatically:
 
 ```typescript
 const schema = new Schema({
-  name: Schema.string(),
+  name: Schema.string().describe('The name of the user'),
   age: Schema.number().min(0),
-  email: Schema.string().email()
+  email: Schema.email(),
+  nickname: Schema.string().optional(),
 });
 
 const description = schema.describe();
-// Returns:
 // {
-//   name: { type: 'string' },
-//   age: { type: 'number', validations: { min: 0 } },
-//   email: { type: 'string', validations: { email: true } }
+//   "$schema": "https://json-schema.org/draft/2020-12/schema",
+//   "type": "object",
+//   "properties": {
+//     "name":     { "type": "string", "description": "The name of the user" },
+//     "age":      { "type": "number", "minimum": 0 },
+//     "email":    { "type": "string", "format": "email", "pattern": "..." },
+//     "nickname": { "type": "string" }
+//   },
+//   "required": ["name", "age", "email"],   // optional fields are absent here
+//   "additionalProperties": false
 // }
 ```
 
-## Type Inference
+Optionality is expressed by the `required` array (JSON Schema semantics), not a per-field flag.
+
+`Schema.from()` rebuilds a `Schema` from JSON Schema. A `describe()` → `from()` round-trip
+preserves validations, descriptions, and which fields are optional:
+
+```typescript
+const clone = Schema.from(schema.describe());
+clone.validate({ name: 'Jane', age: 5, email: 'jane@example.com' }); // true
+```
+
+> `Schema.from()` is backed by `z.fromJSONSchema`, which Zod considers semi-experimental.
+> Round-trips of schemas produced by `describe()` are covered by this package's tests.
 
-The package provides type utilities for inferring types from schemas:
+## Type Inference
 
 ```typescript
 import { Schema, type InferSchema } from '@forgehive/schema';
 
 const schema = new Schema({
   name: Schema.string(),
-  age: Schema.number()
+  age: Schema.number(),
 });
 
-// Infer the type from the schema
 type User = InferSchema<typeof schema>;
-// Type is: { name: string; age: number }
+// { name: string; age: number }
 ```
 
 ## API Reference
 
-### `Schema` Class
+### `Schema` class
+
+- `constructor(fields)` — creates a schema from a map of field name → field type
+- `parse(data)` — parses and validates, throws `ZodError` on failure
+- `safeParse(data)` — returns a Zod `{ success, data | error }` result
+- `validate(data)` — validates without parsing, returns a boolean
+- `describe()` — returns the schema as JSON Schema (draft 2020-12)
+- `asZod()` — returns the underlying `z.ZodObject`
+
+### Static methods
 
-- `constructor(fields: Record<string, SchemaType>)`: Creates a new schema
-- `parse(data: unknown)`: Parses and validates data, throws on error
-- `safeParse(data: unknown)`: Safely parses and validates data
-- `validate(data: unknown)`: Validates data without parsing
-- `describe()`: Returns a description of the schema structure
-- `asZod()`: Returns the underlying Zod schema
+- `string()`, `number()`, `boolean()`, `date()` — basic field types
+- `email()`, `uuid()`, `url()` — string-format field types
+- `array(type)` — array of the given field type
+- `object(fields)` — nested object schema
+- `stringRecord()`, `numberRecord()`, `booleanRecord()`, `mixedRecord()` — record types
+- `from(jsonSchema)` — rebuilds a `Schema` from JSON Schema
+- `infer(schema)` — type-level inference helper
 
-### Static Methods
+### Exports
 
-- `string()`: Creates a string schema
-- `number()`: Creates a number schema
-- `boolean()`: Creates a boolean schema
-- `date()`: Creates a date schema
-- `array(type)`: Creates an array schema
-- `stringRecord()`: Creates a record schema with string values
-- `numberRecord()`: Creates a record schema with number values
-- `booleanRecord()`: Creates a record schema with boolean values
-- `mixedRecord()`: Creates a record schema with mixed values
+- `Schema` (also the default export)
+- `z` — the full Zod 4 namespace, re-exported as an escape hatch
+- Types: `SchemaType`, `SchemaDescription` (JSON Schema), `InferSchema`
 
 ## License
 
-MIT 
+MIT

package/dist/index.d.ts

@@ -1,110 +1,113 @@
 import { z } from 'zod';
-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 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 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 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>;
-export declare 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>>>>> {
+export { z };
+/**
+ * A single field within a schema. Any zod type is allowed, which enables
+ * nested objects, arrays, records, unions and the full range of zod validations.
+ */
+export type SchemaType = z.ZodType;
+/**
+ * The serialized form of a Schema. `describe()` produces standard JSON Schema
+ * (draft 2020-12) and `from()` consumes it.
+ */
+export type SchemaDescription = z.core.JSONSchema.BaseSchema;
+/**
+ * Infers the TypeScript type produced by a Schema instance.
+ */
+export type InferSchema<S extends Schema<z.ZodRawShape>> = z.infer<S['schema']>;
+/**
+ * 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`).
+ */
+export declare class Schema<T extends z.ZodRawShape = z.ZodRawShape> {
     readonly schema: z.ZodObject<T>;
     constructor(fields: T);
     /**
      * Creates a string schema
      * @returns A string schema
      */
-    static string(): ShadowString;
+    static string(): z.ZodString;
+    /**
+     * Creates a number schema
+     * @returns A number schema
+     */
+    static number(): z.ZodNumber;
     /**
      * Creates a boolean schema
      * @returns A boolean schema
      */
-    static boolean(): ShadowBoolean;
+    static boolean(): z.ZodBoolean;
     /**
-     * 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 date(): z.ZodISODateTime;
+    /**
+     * Creates an email string schema (serializes to JSON Schema `format: "email"`).
+     * @returns An email schema
+     */
+    static email(): z.ZodEmail;
+    /**
+     * Creates a UUID string schema (serializes to JSON Schema `format: "uuid"`).
+     * @returns A UUID schema
+     */
+    static uuid(): z.ZodUUID;
+    /**
+     * Creates a URL string schema (serializes to JSON Schema `format: "uri"`).
+     * @returns A URL schema
+     */
+    static url(): z.ZodURL;
+    /**
+     * Creates an array schema
+     * @param type The type of items in the array
+     * @returns An array schema
      */
-    static number(): ShadowNumber;
+    static array<E extends z.ZodType>(type: E): z.ZodArray<E>;
     /**
-     * Creates a date schema
-     * @returns A date schema
+     * Creates a nested object schema
+     * @param fields The fields of the object
+     * @returns An object schema
      */
-    static date(): ShadowDate;
+    static object<S extends z.ZodRawShape>(fields: S): z.ZodObject<S>;
     /**
      * Creates a record schema with string keys and string values
      * @returns A record schema with string values
      */
-    static stringRecord(): ShadowStringRecord;
+    static stringRecord(): z.ZodRecord<z.ZodString, z.ZodString>;
     /**
      * Creates a record schema with string keys and number values
      * @returns A record schema with number values
      */
-    static numberRecord(): ShadowNumberRecord;
+    static numberRecord(): z.ZodRecord<z.ZodString, z.ZodNumber>;
     /**
      * Creates a record schema with string keys and boolean values
      * @returns A record schema with boolean values
      */
-    static booleanRecord(): ShadowBooleanRecord;
+    static booleanRecord(): z.ZodRecord<z.ZodString, z.ZodBoolean>;
     /**
      * Creates a record schema with string keys and mixed values (string, number, or boolean)
      * @returns A record schema with mixed values
      */
-    static mixedRecord(): ShadowMixedRecord;
-    /**
-     * 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>;
+    static mixedRecord(): z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
     /**
      * 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']>;
+    static infer<S extends Schema<z.ZodRawShape>>(_schema: S): z.infer<S['schema']>;
     /**
-     * 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: 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>>>>>;
+    static from(description: SchemaDescription): Schema<z.ZodRawShape>;
     /**
      * Validates the provided data against the schema
      * @param data The data to validate
@@ -123,10 +126,10 @@ export declare class Schema<T extends Record<string, z.ZodType<string | boolean
      * @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>>>;
+    safeParse(data: unknown): z.ZodSafeParseResult<z.infer<z.ZodObject<T>>>;
     /**
-     * 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(): SchemaDescription;
     /**