@forgehive/schema 0.1.3 → 0.2.0

package/README.md

@@ -0,0 +1,207 @@
+# @forgehive/schema
+
+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
+
+```bash
+npm install @forgehive/schema
+```
+
+## Overview
+
+`@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 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
+
+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.
+
+## Basic Usage
+
+```typescript
+import { Schema } from '@forgehive/schema';
+
+const userSchema = new Schema({
+  name: Schema.string().describe('The name of the user'),
+  age: Schema.number().min(0).max(120),
+  email: Schema.email(),
+  tags: Schema.array(Schema.string()),
+});
+
+const result = userSchema.safeParse({
+  name: 'John Doe',
+  age: 30,
+  email: 'john@example.com',
+  tags: ['user', 'active'],
+});
+
+if (result.success) {
+  // TypeScript knows the shape of the data
+  console.log(result.data.name); // string
+}
+```
+
+## Building Fields
+
+Use the `Schema.*` helpers to declare fields:
+
+```typescript
+// Basic types
+Schema.string()
+Schema.number()
+Schema.boolean()
+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())
+
+// Nested objects
+Schema.object({
+  street: Schema.string(),
+  zip: Schema.string().regex(/^[0-9]{5}$/),
+})
+
+// Records
+Schema.stringRecord()  // Record<string, string>
+Schema.numberRecord()  // Record<string, number>
+Schema.booleanRecord() // Record<string, boolean>
+Schema.mixedRecord()   // Record<string, string | number | boolean>
+```
+
+Validations and metadata are added with chaining: `.min()`, `.max()`, `.regex()`, `.optional()`,
+`.describe('...')`, etc.
+
+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(),
+});
+
+// Parse and throw on error
+const data = schema.parse({ name: 'John', age: 30 });
+
+// Safe parse with a result object
+const result = schema.safeParse({ name: 'John', age: 30 });
+if (result.success) {
+  const data = result.data;
+} else {
+  const issues = result.error.issues; // ZodError
+}
+
+// Validate without parsing (boolean)
+const isValid = schema.validate({ name: 'John', age: 30 });
+```
+
+## Serialization (`describe`) and Rehydration (`from`)
+
+`describe()` returns standard JSON Schema. Every validation and `.describe()` on a field is
+included automatically:
+
+```typescript
+const schema = new Schema({
+  name: Schema.string().describe('The name of the user'),
+  age: Schema.number().min(0),
+  email: Schema.email(),
+  nickname: Schema.string().optional(),
+});
+
+const description = schema.describe();
+// {
+//   "$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
+// }
+```
+
+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.
+
+## Type Inference
+
+```typescript
+import { Schema, type InferSchema } from '@forgehive/schema';
+
+const schema = new Schema({
+  name: Schema.string(),
+  age: Schema.number(),
+});
+
+type User = InferSchema<typeof schema>;
+// { name: string; age: number }
+```
+
+## API Reference
+
+### `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
+
+- `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
+
+### Exports
+
+- `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

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 number(): ShadowNumber;
+    static url(): z.ZodURL;
     /**
-     * Creates a date schema
-     * @returns A date schema
+     * Creates an array schema
+     * @param type The type of items in the array
+     * @returns An array schema
      */
-    static date(): ShadowDate;
+    static array<E extends z.ZodType>(type: E): z.ZodArray<E>;
+    /**
+     * Creates a nested object schema
+     * @param fields The fields of the object
+     * @returns An object schema
+     */
+    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,11 +126,16 @@ 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;
+    /**
+     * Returns the underlying Zod schema object
+     * @returns The Zod schema object
+     */
+    asZod(): z.ZodObject<T>;
 }
 export default Schema;