valrs 0.1.0

package/README.md

@@ -0,0 +1,197 @@
+# valrs
+
+[![npm](https://img.shields.io/npm/v/valrs)](https://www.npmjs.com/package/valrs)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](../../LICENSE)
+
+High-performance schema validation powered by Rust and WebAssembly. Implements the [Standard Schema](https://standardschema.dev/) specification.
+
+## Features
+
+- Full Standard Schema v1 compliance
+- WASM-powered validation for high performance
+- JSON Schema generation (Draft 2020-12, Draft 07, OpenAPI 3.0)
+- Type-safe TypeScript API
+- Pure JS fallback when WASM is unavailable
+
+## Installation
+
+```bash
+npm install valrs
+```
+
+## Quick Start
+
+```typescript
+import { init, StringSchema, Int32Schema, isValidationSuccess } from 'valrs';
+
+async function main() {
+  // Initialize the WASM module (required before validation)
+  await init();
+
+  // Validate values
+  const stringResult = StringSchema['~standard'].validate('hello');
+  if (isValidationSuccess(stringResult)) {
+    console.log(stringResult.value); // 'hello'
+  }
+
+  const intResult = Int32Schema['~standard'].validate(42);
+  if (isValidationSuccess(intResult)) {
+    console.log(intResult.value); // 42
+  }
+
+  // Handle validation errors
+  const invalidResult = Int32Schema['~standard'].validate('not a number');
+  if (!isValidationSuccess(invalidResult)) {
+    console.log(invalidResult.issues); // [{ message: 'Expected i32' }]
+  }
+
+  // Generate JSON Schema
+  const schema = StringSchema['~standard'].jsonSchema.input({ target: 'draft-2020-12' });
+  console.log(schema); // { type: 'string' }
+}
+```
+
+## Available Schemas
+
+### Primitive Types
+
+| Schema | TypeScript Type | Description |
+|--------|-----------------|-------------|
+| `StringSchema` | `string` | Any string value |
+| `NumberSchema` | `number` | IEEE 754 double-precision float |
+| `BooleanSchema` | `boolean` | `true` or `false` |
+| `Int32Schema` | `number` | 32-bit signed integer |
+| `Int64Schema` | `number` | 64-bit signed integer* |
+| `Uint32Schema` | `number` | 32-bit unsigned integer |
+| `Uint64Schema` | `number` | 64-bit unsigned integer* |
+| `Float32Schema` | `number` | 32-bit float |
+| `Float64Schema` | `number` | 64-bit float (same as `NumberSchema`) |
+
+*Note: JavaScript numbers can only safely represent integers up to 2^53 - 1.
+
+### Aliases
+
+- `IntegerSchema` - Alias for `Int32Schema`
+- `DoubleSchema` - Alias for `Float64Schema`
+
+## Creating Custom Schemas
+
+### Basic Schema
+
+```typescript
+import { createSchema } from 'valrs';
+
+const PositiveNumber = createSchema<number>((value) => {
+  if (typeof value !== 'number') {
+    return { issues: [{ message: 'Expected a number' }] };
+  }
+  if (value <= 0) {
+    return { issues: [{ message: 'Must be positive' }] };
+  }
+  return { value };
+});
+```
+
+### Schema with JSON Schema Support
+
+```typescript
+import { createSchemaWithJsonSchema } from 'valrs';
+
+const EmailSchema = createSchemaWithJsonSchema<string>(
+  (value) => {
+    if (typeof value !== 'string') {
+      return { issues: [{ message: 'Expected string' }] };
+    }
+    if (!value.includes('@')) {
+      return { issues: [{ message: 'Invalid email format' }] };
+    }
+    return { value };
+  },
+  (target) => ({
+    type: 'string',
+    format: 'email',
+  })
+);
+```
+
+## Type Inference
+
+```typescript
+import type { InferInput, InferOutput, StandardSchemaV1 } from 'valrs';
+
+// Infer types from a schema
+type StringInput = InferInput<typeof StringSchema>; // string
+type StringOutput = InferOutput<typeof StringSchema>; // string
+
+// Use as a type constraint
+function validate<T extends StandardSchemaV1>(
+  schema: T,
+  value: unknown
+): InferOutput<T> | null {
+  const result = schema['~standard'].validate(value);
+  if ('value' in result) {
+    return result.value;
+  }
+  return null;
+}
+```
+
+## JSON Schema Generation
+
+All schemas with `StandardJSONSchemaV1` support can generate JSON Schema:
+
+```typescript
+// Generate for different targets
+const draft2020 = StringSchema['~standard'].jsonSchema.input({ target: 'draft-2020-12' });
+const draft07 = StringSchema['~standard'].jsonSchema.input({ target: 'draft-07' });
+const openapi = StringSchema['~standard'].jsonSchema.input({ target: 'openapi-3.0' });
+```
+
+## Standard Schema Compliance
+
+This library implements the [Standard Schema](https://standardschema.dev/) specification v1:
+
+```typescript
+interface StandardSchemaV1<Input = unknown, Output = Input> {
+  readonly '~standard': {
+    readonly version: 1;
+    readonly vendor: string;
+    readonly validate: (value: unknown) => ValidationResult<Output>;
+  };
+}
+```
+
+Any schema from this library can be used with tools that support Standard Schema.
+
+## API Reference
+
+### Initialization
+
+- `init()` - Initialize the WASM module (required before validation)
+- `isInitialized()` - Check if WASM is ready
+
+### Type Guards
+
+- `isValidationSuccess(result)` - Check if validation succeeded
+- `isValidationFailure(result)` - Check if validation failed
+
+### Schema Factories
+
+- `createSchema(validateFn)` - Create a basic schema
+- `createSchemaWithJsonSchema(validateFn, jsonSchemaFn)` - Create schema with JSON Schema support
+- `createSchemaWithSeparateJsonSchemas(validateFn, inputSchemaFn, outputSchemaFn)` - Create schema with different input/output JSON Schemas
+
+### Result Helpers
+
+- `success(value)` - Create a success result
+- `failure(issues)` - Create a failure result with multiple issues
+- `fail(message, path?)` - Create a failure result with a single issue
+
+### Constants
+
+- `VENDOR` - The vendor name (`'valrs'`)
+- `VERSION` - The Standard Schema version (`1`)
+
+## License
+
+MIT

package/dist/compiler.d.ts

@@ -0,0 +1,195 @@
+/**
+ * JSON Schema to JavaScript Compiler
+ *
+ * Compiles JSON Schema definitions into optimized JavaScript validation functions.
+ * This approach generates direct property checks similar to TypeBox's TypeCompiler,
+ * providing high-performance validation without WASM overhead.
+ *
+ * @packageDocumentation
+ */
+/**
+ * JSON Schema type definition for compiler input.
+ * Supports a subset of JSON Schema draft-07/2020-12 features.
+ */
+export interface JsonSchema {
+    readonly type?: string;
+    readonly properties?: Record<string, JsonSchema>;
+    readonly required?: readonly string[];
+    readonly items?: JsonSchema;
+    readonly minLength?: number;
+    readonly maxLength?: number;
+    readonly minimum?: number;
+    readonly maximum?: number;
+    readonly exclusiveMinimum?: number;
+    readonly exclusiveMaximum?: number;
+    readonly minItems?: number;
+    readonly maxItems?: number;
+    readonly pattern?: string;
+    readonly format?: string;
+    readonly enum?: readonly unknown[];
+    readonly const?: unknown;
+    readonly multipleOf?: number;
+    readonly uniqueItems?: boolean;
+    readonly additionalProperties?: boolean | JsonSchema;
+    readonly allOf?: readonly JsonSchema[];
+    readonly anyOf?: readonly JsonSchema[];
+    readonly oneOf?: readonly JsonSchema[];
+    readonly not?: JsonSchema;
+    readonly $ref?: string;
+    readonly [key: string]: unknown;
+}
+/**
+ * Compiled validator function type.
+ * Returns true if data is valid, false otherwise.
+ */
+export type CompiledValidator = (data: unknown) => boolean;
+/**
+ * Compiles a JSON Schema into an optimized JavaScript validation function.
+ *
+ * This generates direct property checks like TypeBox's TypeCompiler,
+ * creating highly efficient validators without the overhead of schema
+ * interpretation at runtime.
+ *
+ * @param schema - The JSON Schema to compile
+ * @returns A compiled validation function
+ *
+ * @example
+ * ```typescript
+ * import { compileSchema } from 'valrs';
+ *
+ * const userSchema = {
+ *   type: 'object',
+ *   properties: {
+ *     name: { type: 'string', minLength: 1 },
+ *     age: { type: 'integer', minimum: 0 },
+ *   },
+ *   required: ['name', 'age'],
+ * };
+ *
+ * const validate = compileSchema(userSchema);
+ *
+ * validate({ name: 'John', age: 30 }); // true
+ * validate({ name: '', age: 30 });     // false (minLength violation)
+ * validate({ name: 'John', age: -1 }); // false (minimum violation)
+ * ```
+ */
+export declare function compileSchema(schema: JsonSchema): CompiledValidator;
+/**
+ * Generates the JavaScript source code for a validator function.
+ *
+ * Useful for debugging or generating static validator files.
+ *
+ * @param schema - The JSON Schema to compile
+ * @returns The JavaScript function body as a string
+ *
+ * @example
+ * ```typescript
+ * import { compileSchemaToCode } from 'valrs';
+ *
+ * const code = compileSchemaToCode({
+ *   type: 'string',
+ *   minLength: 1,
+ * });
+ * // Returns: "return (typeof data === 'string' && data.length >= 1)"
+ * ```
+ */
+export declare function compileSchemaToCode(schema: JsonSchema): string;
+/**
+ * Schema registry with pre-compiled validators.
+ *
+ * Provides a convenient way to register schemas by name and validate
+ * data against them. All schemas are compiled on registration for
+ * optimal validation performance.
+ *
+ * @example
+ * ```typescript
+ * import { CompiledRegistry } from 'valrs';
+ *
+ * const registry = new CompiledRegistry();
+ *
+ * registry.register('User', {
+ *   type: 'object',
+ *   properties: {
+ *     name: { type: 'string' },
+ *     email: { type: 'string' },
+ *   },
+ *   required: ['name', 'email'],
+ * });
+ *
+ * registry.validate('User', { name: 'John', email: 'john@example.com' }); // true
+ * registry.validate('User', { name: 'John' }); // false (missing email)
+ * ```
+ */
+export declare class CompiledRegistry {
+    private readonly validators;
+    private readonly schemas;
+    private readonly generatedCode;
+    /**
+     * Registers a schema with the registry.
+     *
+     * The schema is immediately compiled for optimal validation performance.
+     *
+     * @param name - The name to register the schema under
+     * @param schema - The JSON Schema to register
+     */
+    register(name: string, schema: JsonSchema): void;
+    /**
+     * Validates data against a registered schema.
+     *
+     * @param name - The name of the registered schema
+     * @param data - The data to validate
+     * @returns true if valid, false otherwise
+     * @throws Error if schema is not registered
+     */
+    validate(name: string, data: unknown): boolean;
+    /**
+     * Gets a registered schema by name.
+     *
+     * @param name - The name of the schema
+     * @returns The schema, or undefined if not registered
+     */
+    getSchema(name: string): JsonSchema | undefined;
+    /**
+     * Gets the compiled validator function for a schema.
+     *
+     * @param name - The name of the schema
+     * @returns The compiled validator, or undefined if not registered
+     */
+    getValidator(name: string): CompiledValidator | undefined;
+    /**
+     * Gets the generated JavaScript code for a schema.
+     *
+     * Useful for debugging or static code generation.
+     *
+     * @param name - The name of the schema
+     * @returns The generated code, or undefined if not registered
+     */
+    getGeneratedCode(name: string): string | undefined;
+    /**
+     * Checks if a schema is registered.
+     *
+     * @param name - The name to check
+     * @returns true if registered, false otherwise
+     */
+    has(name: string): boolean;
+    /**
+     * Removes a schema from the registry.
+     *
+     * @param name - The name of the schema to remove
+     * @returns true if removed, false if not found
+     */
+    delete(name: string): boolean;
+    /**
+     * Removes all schemas from the registry.
+     */
+    clear(): void;
+    /**
+     * Gets the names of all registered schemas.
+     */
+    get names(): string[];
+    /**
+     * Gets the number of registered schemas.
+     */
+    get size(): number;
+}
+//# sourceMappingURL=compiler.d.ts.map

package/dist/compiler.d.ts.map

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