rustica 1.0.0

package/dist/validator/index.d.ts

@@ -0,0 +1,71 @@
+import type { Schema, ValidationResult, ValidationError } from "../schema/types";
+import type { SchemaBuilder } from "../schema/builders";
+/**
+ * WASM module interface
+ * Auto-generated by wasm-pack
+ */
+export interface WasmModule {
+    WasmValidator: {
+        validate(schema_json: string, value_json: string): string;
+        validate_at_path(schema_json: string, value_json: string, path_json: string): string;
+    };
+}
+/**
+ * Initialize WASM module
+ * Can be called explicitly for eager loading, or will auto-initialize on first use
+ */
+export declare function initWasm(): Promise<void>;
+/**
+ * Core validator using WASM
+ */
+export declare class Validator {
+    /**
+     * Validate data against a schema
+     * Auto-initializes WASM on first use
+     *
+     * @param schema - Schema definition (builder or JSON)
+     * @param value - Data to validate
+     * @returns Validation result with errors if any
+     */
+    static validate<T>(schema: SchemaBuilder<T> | Schema, value: unknown): Promise<ValidationResult>;
+    /**
+     * Validate data at a specific path in the schema
+     * Useful for field-level validation in forms
+     * Auto-initializes WASM on first use
+     *
+     * @param schema - Schema definition
+     * @param value - Complete data object
+     * @param path - Path to validate (e.g., ['user', 'email'])
+     * @returns Validation result for the specific field
+     */
+    static validateAtPath<T>(schema: SchemaBuilder<T> | Schema, value: unknown, path: string[]): Promise<ValidationResult>;
+    /**
+     * Validate and throw on error (for convenience)
+     * Auto-initializes WASM on first use
+     */
+    static parse<T>(schema: SchemaBuilder<T> | Schema, value: unknown): Promise<T>;
+    /**
+     * Safe parse that returns result object
+     * Auto-initializes WASM on first use
+     */
+    static safeParse<T>(schema: SchemaBuilder<T> | Schema, value: unknown): Promise<{
+        success: true;
+        data: T;
+    } | {
+        success: false;
+        errors: ValidationError[];
+    }>;
+}
+/**
+ * Validation exception for parse() method
+ */
+export declare class ValidationException extends Error {
+    errors: ValidationError[];
+    constructor(errors: ValidationError[]);
+}
+/**
+ * Auto-initialization wrapper
+ * Automatically initializes WASM on first use
+ */
+export declare function createValidator(): Promise<typeof Validator>;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/validator/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,MAAM,EACN,gBAAgB,EAChB,eAAe,EAChB,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAExD;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,aAAa,EAAE;QACb,QAAQ,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAAC;QAC1D,gBAAgB,CACd,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,GAChB,MAAM,CAAC;KACX,CAAC;CACH;AAQD;;;GAGG;AACH,wBAAsB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAsC9C;AA0BD;;GAEG;AACH,qBAAa,SAAS;IACpB;;;;;;;OAOG;WACU,QAAQ,CAAC,CAAC,EACrB,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,MAAM,EACjC,KAAK,EAAE,OAAO,GACb,OAAO,CAAC,gBAAgB,CAAC;IAkB5B;;;;;;;;;OASG;WACU,cAAc,CAAC,CAAC,EAC3B,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,MAAM,EACjC,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,MAAM,EAAE,GACb,OAAO,CAAC,gBAAgB,CAAC;IAqB5B;;;OAGG;WACU,KAAK,CAAC,CAAC,EAClB,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,MAAM,EACjC,KAAK,EAAE,OAAO,GACb,OAAO,CAAC,CAAC,CAAC;IAUb;;;OAGG;WACU,SAAS,CAAC,CAAC,EACtB,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,MAAM,EACjC,KAAK,EAAE,OAAO,GACb,OAAO,CACR;QAAE,OAAO,EAAE,IAAI,CAAC;QAAC,IAAI,EAAE,CAAC,CAAA;KAAE,GAAG;QAAE,OAAO,EAAE,KAAK,CAAC;QAAC,MAAM,EAAE,eAAe,EAAE,CAAA;KAAE,CAC3E;CASF;AAED;;GAEG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;IACzB,MAAM,EAAE,eAAe,EAAE;gBAAzB,MAAM,EAAE,eAAe,EAAE;CAO7C;AAED;;;GAGG;AACH,wBAAsB,eAAe,IAAI,OAAO,CAAC,OAAO,SAAS,CAAC,CAGjE"}

package/dist/validator/index.js

@@ -0,0 +1,149 @@
+/**
+ * Lazy-loaded WASM module singleton
+ */
+let wasmModule = null;
+let wasmInitPromise = null;
+/**
+ * Initialize WASM module
+ * Can be called explicitly for eager loading, or will auto-initialize on first use
+ */
+export async function initWasm() {
+    if (wasmModule)
+        return;
+    if (wasmInitPromise)
+        return wasmInitPromise;
+    wasmInitPromise = (async () => {
+        try {
+            // Dynamic import of WASM module
+            // Use package-relative path that works both in development and when installed
+            const module = (await import("rustica/pkg/rustica.js"));
+            console.log("WASM module loaded:", module);
+            console.log("Has WasmValidator?", !!module.WasmValidator);
+            console.log("Has default?", typeof module.default);
+            // For bundler/web target with async init, call default function
+            if (typeof module.default === "function") {
+                await module.default();
+            }
+            // Always set wasmModule to the imported module (it has WasmValidator)
+            wasmModule = module;
+            // Verify WasmValidator is accessible
+            if (!module.WasmValidator) {
+                throw new Error("WasmValidator not found in WASM module");
+            }
+            console.log("WASM initialization complete");
+        }
+        catch (error) {
+            console.error("WASM initialization failed:", error);
+            wasmInitPromise = null; // Reset on error so it can be retried
+            throw new Error(`Failed to load WASM module. Make sure to run 'npm run build:wasm' first. Error: ${error}`);
+        }
+    })();
+    return wasmInitPromise;
+}
+/**
+ * Get initialized WASM module (auto-initializes if needed)
+ */
+async function getWasm() {
+    // If initialization is in progress, wait for it
+    if (wasmInitPromise && !wasmModule) {
+        await wasmInitPromise;
+    }
+    // If not initialized at all, start initialization
+    if (!wasmModule) {
+        await initWasm();
+    }
+    // Final check
+    if (!wasmModule) {
+        throw new Error("WASM module not initialized. Call initWasm() before validation.");
+    }
+    return wasmModule;
+}
+/**
+ * Core validator using WASM
+ */
+export class Validator {
+    /**
+     * Validate data against a schema
+     * Auto-initializes WASM on first use
+     *
+     * @param schema - Schema definition (builder or JSON)
+     * @param value - Data to validate
+     * @returns Validation result with errors if any
+     */
+    static async validate(schema, value) {
+        const wasm = await getWasm();
+        // Serialize schema to JSON
+        const schemaJson = JSON.stringify(schema instanceof Object && "toJSON" in schema ? schema.toJSON() : schema);
+        // Serialize value to JSON
+        const valueJson = JSON.stringify(value);
+        // Call WASM validator (single call, zero-copy)
+        const resultJson = wasm.WasmValidator.validate(schemaJson, valueJson);
+        // Parse result
+        return JSON.parse(resultJson);
+    }
+    /**
+     * Validate data at a specific path in the schema
+     * Useful for field-level validation in forms
+     * Auto-initializes WASM on first use
+     *
+     * @param schema - Schema definition
+     * @param value - Complete data object
+     * @param path - Path to validate (e.g., ['user', 'email'])
+     * @returns Validation result for the specific field
+     */
+    static async validateAtPath(schema, value, path) {
+        const wasm = await getWasm();
+        // Serialize inputs
+        const schemaJson = JSON.stringify(schema instanceof Object && "toJSON" in schema ? schema.toJSON() : schema);
+        const valueJson = JSON.stringify(value);
+        const pathJson = JSON.stringify(path);
+        // Call WASM validator (single call)
+        const resultJson = wasm.WasmValidator.validate_at_path(schemaJson, valueJson, pathJson);
+        // Parse result
+        return JSON.parse(resultJson);
+    }
+    /**
+     * Validate and throw on error (for convenience)
+     * Auto-initializes WASM on first use
+     */
+    static async parse(schema, value) {
+        const result = await this.validate(schema, value);
+        if (!result.success) {
+            throw new ValidationException(result.errors || []);
+        }
+        return value;
+    }
+    /**
+     * Safe parse that returns result object
+     * Auto-initializes WASM on first use
+     */
+    static async safeParse(schema, value) {
+        const result = await this.validate(schema, value);
+        if (result.success) {
+            return { success: true, data: value };
+        }
+        else {
+            return { success: false, errors: result.errors || [] };
+        }
+    }
+}
+/**
+ * Validation exception for parse() method
+ */
+export class ValidationException extends Error {
+    constructor(errors) {
+        super("Validation failed:\n" +
+            errors.map((e) => `  - ${e.path.join(".")}: ${e.message}`).join("\n"));
+        this.errors = errors;
+        this.name = "ValidationException";
+    }
+}
+/**
+ * Auto-initialization wrapper
+ * Automatically initializes WASM on first use
+ */
+export async function createValidator() {
+    await initWasm();
+    return Validator;
+}
+//# sourceMappingURL=index.js.map

package/dist/validator/index.js.map

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

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "rustica",
+  "version": "1.0.0",
+  "description": "Production-grade schema validation powered by Rust and WebAssembly",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./pkg/*": "./pkg/*"
+  },
+  "author": "fourth-ally",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fourth-ally/rustica.git"
+  },
+  "bugs": {
+    "url": "https://github.com/fourth-ally/rustica/issues"
+  },
+  "homepage": "https://github.com/fourth-ally/rustica#readme",
+  "files": [
+    "dist",
+    "pkg",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build:wasm": "wasm-pack build --target bundler --out-dir pkg",
+    "build:wasm:node": "wasm-pack build --target nodejs --out-dir pkg",
+    "build:ts": "tsc",
+    "build": "npm run build:wasm && npm run build:ts",
+    "dev": "tsc --watch",
+    "test": "cargo test && npm run test:ts",
+    "test:ts": "npm run build:wasm:node && node --import tsx --test tests/*.test.ts && npm run build:wasm",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "keywords": [
+    "validation",
+    "schema",
+    "wasm",
+    "rust",
+    "zod",
+    "forms",
+    "react",
+    "typescript",
+    "webassembly",
+    "form-validation"
+  ],
+  "devDependencies": {
+    "@types/node": "^25.0.9",
+    "@types/react": "^18.2.0",
+    "react": "^18.2.0",
+    "tsx": "^4.7.0",
+    "typescript": "^5.3.0"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/pkg/.gitignore

@@ -0,0 +1 @@
+*

package/pkg/.npmignore

@@ -0,0 +1,3 @@
+# Override the .gitignore for npm publishing
+# We want to include the WASM build artifacts in the npm package
+!*

package/pkg/README.md

@@ -0,0 +1,289 @@
+# Rustica
+
+![Rustica - Validate 'Em All'](./assets/rustica-banner.png)
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue)](https://www.typescriptlang.org/)
+[![Rust](https://img.shields.io/badge/Rust-1.70+-orange)](https://www.rust-lang.org/)
+[![WebAssembly](https://img.shields.io/badge/WebAssembly-✓-blueviolet)](https://webassembly.org/)
+
+Production-grade schema and form validation system powered by Rust and WebAssembly.
+
+## ✨ Features
+
+<table>
+<tr>
+<td width="50%">
+
+### 🦀 Rust Core
+
+- **WASM-powered** validation
+- **Zero-copy** architecture
+- **~0.1-0.5ms** per validation
+- **Single call** per validation
+
+</td>
+<td width="50%">
+
+### 📝 TypeScript API
+
+- **Fluent API** like Zod
+- **Full type inference**
+- **Schema serialization**
+- **UI metadata** support
+
+</td>
+</tr>
+<tr>
+<td width="50%">
+
+### ⚛️ React Integration
+
+- **useWasmForm** hook
+- **Field registration**
+- **Auto re-rendering**
+- **RHF-compatible** API
+
+</td>
+<td width="50%">
+
+### 🔧 Framework Agnostic
+
+- **createForm** for any framework
+- **Vanilla JS** support
+- **Node.js** compatible
+- **Browser** ready
+
+</td>
+</tr>
+</table>
+
+## Installation
+
+```bash
+npm install rustica
+```
+
+## Quick Start
+
+```typescript
+import { r, useWasmForm } from 'rustica';
+
+// Define schema with optional custom error messages
+// WASM auto-initializes on first validation - no setup needed!
+const loginSchema = r.object({
+  email: r.string()
+    .min(3)
+    .email()
+    .ui({ label: "Email" })
+    .messages({
+      email: "Please enter a valid email address",
+      min: "Email must be at least 3 characters"
+    }),
+  password: r.string()
+    .min(8)
+    .ui({ label: "Password" })
+    .messages({
+      min: "Password must be at least 8 characters for security"
+    })
+});
+
+// Infer types
+type LoginForm = r.Infer<typeof loginSchema>;
+
+// Use in React - works immediately!
+function LoginForm() {
+  const form = useWasmForm({
+    schema: loginSchema,
+    defaultValues: { email: '', password: '' },
+    onSubmit: async (data) => {
+      console.log('Valid data:', data);
+    }
+  });
+
+  return (
+    <form onSubmit={form.handleSubmit}>
+      <input {...form.register('email')} />
+      {form.errors.email && <span>{form.errors.email.message}</span>}
+
+      <input type="password" {...form.register('password')} />
+      {form.errors.password && <span>{form.errors.password.message}</span>}
+
+      <button type="submit">Login</button>
+    </form>
+  );
+}
+```
+
+**Note**: WASM auto-initializes on the first validation call. For eager loading (optional), you can manually call `await initWasm()` at app startup.
+
+````
+
+## Custom Error Messages (Optional)
+
+Customize validation error messages for better UX:
+
+```typescript
+// String validation with custom messages
+const usernameSchema = r.string().min(3).max(20).messages({
+  invalid_type: "Username must be text",
+  min: "Username is too short - minimum 3 characters",
+  max: "Username is too long - maximum 20 characters",
+});
+
+// Number validation with custom messages
+const ageSchema = r.number().min(18).integer().messages({
+  invalid_type: "Age must be a number",
+  min: "You must be at least 18 years old",
+  integer: "Age must be a whole number",
+});
+
+// Object validation with custom messages
+const formSchema = r
+  .object({
+    email: r.string().email().messages({
+      email: "Please enter a valid email like user@example.com",
+    }),
+    terms: r.boolean().messages({
+      invalid_type: "You must accept the terms and conditions",
+    }),
+  })
+  .messages({
+    invalid_type: "Form data must be an object",
+    required: "This field is required",
+  });
+````
+
+**Available message keys by type:**
+
+- **String**: `invalid_type`, `min`, `max`, `email`, `url`, `pattern`
+- **Number**: `invalid_type`, `min`, `max`, `integer`, `positive`
+- **Boolean**: `invalid_type`
+- **Object**: `invalid_type`, `required`
+
+If not provided, default messages are used. See [examples/custom-messages.ts](./examples/custom-messages.ts) for more examples.
+
+## Building from Source
+
+```bash
+# Quick setup (recommended)
+chmod +x scripts/setup.sh
+./scripts/setup.sh
+
+# Or manual setup
+npm install
+npm run build
+```
+
+See [Getting Started Guide](./docs/GETTING_STARTED.md) for detailed instructions.
+
+## Architecture
+
+- **Rust Core** (`src/lib.rs`, `src/schema.rs`, `src/validator.rs`) - Schema definitions and validation logic
+- **WASM Interface** (`src/wasm.rs`) - WebAssembly bindings with wasm-bindgen
+- **TypeScript Schema Builder** (`src/schema/`) - Fluent API for schema definition
+- **Form Runtime** (`src/form/`) - Form state management
+- **React Hook** (`src/react/`) - React integration
+
+## Documentation
+
+- 📖 **[Complete Documentation Index](./docs/INDEX.md)** - All docs in one place
+- 🚀 **[Getting Started Guide](./docs/GETTING_STARTED.md)** - Quick start tutorial
+- 📚 **[API Reference](./docs/API.md)** - Complete API documentation
+- 🏗️ **[Architecture Guide](./docs/ARCHITECTURE.md)** - How it works
+- 📊 **[Feature Comparison](./docs/COMPARISON.md)** - vs Zod, Yup, Joi
+- 🤝 **[Contributing Guide](./CONTRIBUTING.md)** - How to contribute
+
+## Project Structure
+
+```
+rustica/
+├── src/                      # Rust source (validation core)
+│   ├── lib.rs               # Module exports
+│   ├── schema.rs            # Schema AST types
+│   ├── validator.rs         # Validation engine
+│   └── wasm.rs              # WASM bindings
+├── src/                      # TypeScript source
+│   ├── schema/              # Schema builders (r.string(), etc.)
+│   ├── validator/           # WASM wrapper
+│   ├── form/                # Form runtime
+│   ├── react/               # React hooks
+│   └── index.ts             # Main entry point
+├── examples/                 # Usage examples
+│   ├── quick-test.ts        # Basic validation tests
+│   ├── standalone.ts        # Standalone examples
+│   ├── forms.tsx            # Form component examples
+│   └── react-form-app/      # Full React app with API integration
+├── tests/                    # Test suite
+├── docs/                     # Documentation
+└── scripts/                  # Build scripts
+```
+
+## Commands
+
+```bash
+# Development
+make install       # Install dependencies
+make build         # Build WASM + TypeScript
+make test          # Run all tests
+make dev           # Watch mode
+
+# Quick Commands
+make example       # Run quick test
+make clean         # Clean build artifacts
+make help          # Show all commands
+```
+
+## Performance
+
+<table>
+<tr>
+<td><b>Metric</b></td>
+<td><b>Value</b></td>
+<td><b>Notes</b></td>
+</tr>
+<tr>
+<td>Validation Speed</td>
+<td>~0.1-0.5ms</td>
+<td>Per validation (warm)</td>
+</tr>
+<tr>
+<td>Throughput</td>
+<td>5,000-10,000/sec</td>
+<td>1000 validations in ~100-200ms</td>
+</tr>
+<tr>
+<td>WASM Size</td>
+<td>~15-20KB</td>
+<td>Gzipped: ~8-10KB</td>
+</tr>
+<tr>
+<td>Overhead</td>
+<td>Single call</td>
+<td>Zero-copy where possible</td>
+</tr>
+</table>
+
+See [Performance Comparison](./docs/COMPARISON.md) for detailed benchmarks.
+
+## Contributing
+
+We welcome contributions! See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
+
+## Roadmap
+
+- [x] Core validation (string, number, boolean, object)
+- [x] React hooks
+- [x] Form runtime
+- [x] Type inference
+- [x] Custom error messages (optional)
+- [ ] Array/tuple schemas
+- [ ] Union/intersection types
+- [ ] Async validation helpers
+- [ ] i18n support
+
+See [CHANGELOG.md](./CHANGELOG.md) for version history.
+
+## License
+
+MIT

package/pkg/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "rustica",
+  "type": "module",
+  "version": "0.1.0",
+  "files": [
+    "rustica_bg.wasm",
+    "rustica.js",
+    "rustica_bg.js",
+    "rustica.d.ts"
+  ],
+  "main": "rustica.js",
+  "types": "rustica.d.ts",
+  "sideEffects": [
+    "./rustica.js",
+    "./snippets/*"
+  ]
+}

package/pkg/rustica.d.ts

@@ -0,0 +1,42 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/**
+ * WASM interface for validation
+ *
+ * This module exposes exactly two functions to JavaScript:
+ * - validate: validates entire data against schema
+ * - validate_at_path: validates data at a specific path
+ *
+ * Both functions accept and return JSON strings for zero-copy performance
+ */
+export class WasmValidator {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Validate data against a schema
+     *
+     * # Arguments
+     * * `schema_json` - JSON string representing the schema AST
+     * * `value_json` - JSON string representing the data to validate
+     *
+     * # Returns
+     * JSON string with validation result:
+     * - Success: `{"success": true}`
+     * - Error: `{"success": false, "errors": [...]}`
+     */
+    static validate(schema_json: string, value_json: string): string;
+    /**
+     * Validate data at a specific path in the schema
+     *
+     * # Arguments
+     * * `schema_json` - JSON string representing the schema AST
+     * * `value_json` - JSON string representing the data to validate
+     * * `path_json` - JSON array of path segments as strings
+     *
+     * # Returns
+     * JSON string with validation result (same format as validate)
+     */
+    static validate_at_path(schema_json: string, value_json: string, path_json: string): string;
+}

package/pkg/rustica.js

@@ -0,0 +1,9 @@
+/* @ts-self-types="./rustica.d.ts" */
+
+import * as wasm from "./rustica_bg.wasm";
+import { __wbg_set_wasm } from "./rustica_bg.js";
+__wbg_set_wasm(wasm);
+
+export {
+    WasmValidator
+} from "./rustica_bg.js";