@revealui/contracts 1.0.0

package/dist/foundation/contract.d.ts

@@ -0,0 +1,221 @@
+/**
+ * Unified Contract System
+ *
+ * A Contract is a single source of truth that combines:
+ * 1. TypeScript Type (compile-time safety)
+ * 2. Zod Schema (runtime validation)
+ * 3. Validation Functions (runtime validation)
+ * 4. Type Guards (runtime type checking)
+ * 5. Metadata (documentation, versioning)
+ *
+ * This unified approach ensures that types, schemas, and validation
+ * never drift apart, providing both compile-time and runtime safety.
+ *
+ * @module @revealui/contracts/foundation
+ */
+import type { ZodError, z } from 'zod/v4';
+/**
+ * Validation result from contract validation
+ */
+export interface ContractValidationSuccess<T> {
+    success: true;
+    data: T;
+    errors?: never;
+}
+export interface ContractValidationFailure {
+    success: false;
+    data?: never;
+    errors: ZodError;
+}
+export type ContractValidationResult<T> = ContractValidationSuccess<T> | ContractValidationFailure;
+/**
+ * Contract metadata for documentation and versioning
+ */
+export interface ContractMetadata {
+    /** Contract name/identifier */
+    name: string;
+    /** Contract version for migration support */
+    version: string;
+    /** Human-readable description */
+    description?: string;
+    /** Documentation URL */
+    docsUrl?: string;
+    /** Tags for categorization */
+    tags?: string[];
+    /** Deprecation notice if applicable */
+    deprecated?: boolean;
+    /** Deprecation message */
+    deprecatedMessage?: string;
+}
+/**
+ * Unified Contract Interface
+ *
+ * A Contract binds together TypeScript types, Zod schemas, and validation
+ * into a single source of truth.
+ *
+ * @template T - The TypeScript type this contract validates
+ *
+ * @example
+ * ```typescript
+ * const UserContract = createContract({
+ *   name: 'User',
+ *   version: '1.0.0',
+ *   schema: z.object({
+ *     id: z.string(),
+ *     email: z.string().email(),
+ *     name: z.string().min(1),
+ *   }),
+ * })
+ *
+ * // Type inference
+ * type User = ContractType<typeof UserContract>
+ *
+ * // Runtime validation
+ * const result = UserContract.validate(rawData)
+ * if (result.success) {
+ *   // result.data is fully typed as User
+ *   console.log(result.data.email)
+ * }
+ *
+ * // Type guard
+ * if (UserContract.isType(unknownData)) {
+ *   // unknownData is now typed as User
+ *   console.log(unknownData.email)
+ * }
+ * ```
+ */
+export interface Contract<T> {
+    /** Contract metadata */
+    readonly metadata: ContractMetadata;
+    /**
+     * Zod schema for runtime validation
+     * This is the single source of truth for the data structure
+     */
+    readonly schema: z.ZodSchema<T>;
+    /**
+     * Validate data against the contract
+     * Returns a result object with success flag and typed data or errors
+     *
+     * @param data - Unknown data to validate
+     * @returns Validation result with typed data on success, errors on failure
+     */
+    validate(data: unknown): ContractValidationResult<T>;
+    /**
+     * Type guard function
+     * Returns true if data matches the contract, false otherwise
+     * When true, TypeScript narrows the type to T
+     *
+     * @param data - Unknown data to check
+     * @returns True if data is valid, false otherwise
+     */
+    isType(data: unknown): data is T;
+    /**
+     * Parse data and throw on validation failure
+     * Use this when you're certain data should be valid
+     *
+     * @param data - Unknown data to parse
+     * @returns Typed data
+     * @throws ZodError if validation fails
+     */
+    parse(data: unknown): T;
+    /**
+     * Safe parse - returns result without throwing
+     * Alias for validate() for consistency with Zod API
+     *
+     * @param data - Unknown data to parse
+     * @returns Validation result
+     */
+    safeParse(data: unknown): ContractValidationResult<T>;
+}
+/**
+ * Extract the TypeScript type from a Contract
+ *
+ * @template C - The contract type
+ *
+ * @example
+ * ```typescript
+ * type User = ContractType<typeof UserContract>
+ * ```
+ */
+export type ContractType<C extends Contract<unknown>> = C extends Contract<infer T> ? T : never;
+/**
+ * Options for creating a contract
+ */
+export interface CreateContractOptions<T> {
+    /** Contract name/identifier */
+    name: string;
+    /** Contract version */
+    version: string;
+    /** Zod schema for validation */
+    schema: z.ZodSchema<T>;
+    /** Optional description */
+    description?: string;
+    /** Optional documentation URL */
+    docsUrl?: string;
+    /** Optional tags */
+    tags?: string[];
+    /** Optional deprecation flag */
+    deprecated?: boolean;
+    /** Optional deprecation message */
+    deprecatedMessage?: string;
+}
+/**
+ * Create a unified contract from a Zod schema
+ *
+ * This factory function creates a Contract that binds together:
+ * - TypeScript type inference from the schema
+ * - Runtime validation via Zod
+ * - Type guards for type narrowing
+ * - Metadata for documentation
+ *
+ * @template T - The type inferred from the schema
+ * @param options - Contract creation options
+ * @returns A complete Contract instance
+ *
+ * @example
+ * ```typescript
+ * const UserContract = createContract({
+ *   name: 'User',
+ *   version: '1.0.0',
+ *   schema: z.object({
+ *     id: z.string(),
+ *     email: z.string().email(),
+ *     name: z.string().min(1),
+ *   }),
+ * })
+ * ```
+ */
+export declare function createContract<T>(options: CreateContractOptions<T>): Contract<T>;
+/**
+ * Contract registry for managing all contracts
+ * Allows lookup and versioning of contracts
+ */
+declare class ContractRegistry {
+    private contracts;
+    /**
+     * Register a contract
+     */
+    register<T>(contract: Contract<T>): void;
+    /**
+     * Get a contract by name and version
+     */
+    get<T>(name: string, version: string): Contract<T> | undefined;
+    /**
+     * Get the latest version of a contract
+     */
+    getLatest<T>(name: string): Contract<T> | undefined;
+    /**
+     * List all registered contracts
+     */
+    list(): Contract<unknown>[];
+    /**
+     * Clear all contracts (useful for testing)
+     */
+    clear(): void;
+}
+/**
+ * Global contract registry instance
+ */
+export declare const contractRegistry: ContractRegistry;
+export {};
+//# sourceMappingURL=contract.d.ts.map

package/dist/foundation/contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../../src/foundation/contract.ts"],"names":[],"mappings":"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"}

package/dist/foundation/contract.js

@@ -0,0 +1,133 @@
+/**
+ * Unified Contract System
+ *
+ * A Contract is a single source of truth that combines:
+ * 1. TypeScript Type (compile-time safety)
+ * 2. Zod Schema (runtime validation)
+ * 3. Validation Functions (runtime validation)
+ * 4. Type Guards (runtime type checking)
+ * 5. Metadata (documentation, versioning)
+ *
+ * This unified approach ensures that types, schemas, and validation
+ * never drift apart, providing both compile-time and runtime safety.
+ *
+ * @module @revealui/contracts/foundation
+ */
+/**
+ * Create a unified contract from a Zod schema
+ *
+ * This factory function creates a Contract that binds together:
+ * - TypeScript type inference from the schema
+ * - Runtime validation via Zod
+ * - Type guards for type narrowing
+ * - Metadata for documentation
+ *
+ * @template T - The type inferred from the schema
+ * @param options - Contract creation options
+ * @returns A complete Contract instance
+ *
+ * @example
+ * ```typescript
+ * const UserContract = createContract({
+ *   name: 'User',
+ *   version: '1.0.0',
+ *   schema: z.object({
+ *     id: z.string(),
+ *     email: z.string().email(),
+ *     name: z.string().min(1),
+ *   }),
+ * })
+ * ```
+ */
+export function createContract(options) {
+    const { name, version, schema, description, docsUrl, tags, deprecated, deprecatedMessage } = options;
+    const metadata = {
+        name,
+        version,
+        ...(description && { description }),
+        ...(docsUrl && { docsUrl }),
+        ...(tags && { tags }),
+        ...(deprecated !== undefined && { deprecated }),
+        ...(deprecatedMessage && { deprecatedMessage }),
+    };
+    return {
+        metadata,
+        schema,
+        validate(data) {
+            const result = schema.safeParse(data);
+            if (result.success) {
+                return {
+                    success: true,
+                    data: result.data,
+                };
+            }
+            return {
+                success: false,
+                errors: result.error,
+            };
+        },
+        isType(data) {
+            return schema.safeParse(data).success;
+        },
+        parse(data) {
+            return schema.parse(data);
+        },
+        safeParse(data) {
+            return this.validate(data);
+        },
+    };
+}
+/**
+ * Contract registry for managing all contracts
+ * Allows lookup and versioning of contracts
+ */
+class ContractRegistry {
+    contracts = new Map();
+    /**
+     * Register a contract
+     */
+    register(contract) {
+        const key = `${contract.metadata.name}@${contract.metadata.version}`;
+        this.contracts.set(key, contract);
+    }
+    /**
+     * Get a contract by name and version
+     */
+    get(name, version) {
+        const key = `${name}@${version}`;
+        return this.contracts.get(key);
+    }
+    /**
+     * Get the latest version of a contract
+     */
+    getLatest(name) {
+        let latest;
+        let latestVersion = '0.0.0';
+        for (const contract of Array.from(this.contracts.values())) {
+            if (contract.metadata.name === name) {
+                if (contract.metadata.version > latestVersion) {
+                    latestVersion = contract.metadata.version;
+                    latest = contract;
+                }
+            }
+        }
+        return latest;
+    }
+    /**
+     * List all registered contracts
+     */
+    list() {
+        return Array.from(this.contracts.values());
+    }
+    /**
+     * Clear all contracts (useful for testing)
+     */
+    clear() {
+        this.contracts.clear();
+    }
+}
+/**
+ * Global contract registry instance
+ */
+export const contractRegistry = new ContractRegistry();
+//# sourceMappingURL=contract.js.map

package/dist/foundation/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../../src/foundation/contract.ts"],"names":[],"mappings":"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"}

package/dist/foundation/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @revealui/contracts/foundation
+ *
+ * Foundation contract system - core Contract<T> interface and utilities
+ */
+export { type Contract, type ContractMetadata, type ContractType, type ContractValidationFailure, type ContractValidationResult, type ContractValidationSuccess, type CreateContractOptions, contractRegistry, createContract, } from './contract.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/foundation/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/foundation/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,KAAK,QAAQ,EACb,KAAK,gBAAgB,EACrB,KAAK,YAAY,EACjB,KAAK,yBAAyB,EAC9B,KAAK,wBAAwB,EAC7B,KAAK,yBAAyB,EAC9B,KAAK,qBAAqB,EAC1B,gBAAgB,EAChB,cAAc,GACf,MAAM,eAAe,CAAA"}

package/dist/foundation/index.js

@@ -0,0 +1,7 @@
+/**
+ * @revealui/contracts/foundation
+ *
+ * Foundation contract system - core Contract<T> interface and utilities
+ */
+export { contractRegistry, createContract, } from './contract.js';
+//# sourceMappingURL=index.js.map

package/dist/foundation/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/foundation/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAQL,gBAAgB,EAChB,cAAc,GACf,MAAM,eAAe,CAAA"}