inu-light 1.0.0 → 1.0.1

package/README.md

@@ -1,17 +1,18 @@
 # inu-light
 
-A lightweight, zero-dependency schema validation library for TypeScript and JavaScript.
+A lightweight, zero-dependency schema validation library for TypeScript. Designed to improve runtime data safety with schema-driven validation and strict avoidance of the any type.
 
 ## Design philosophy
 
-inu-light focuses on predictable schemas and strict typing, avoiding magic behavior and unnecessary runtime dependencies.
+Most schema libraries are either heavy or rely on opaque runtime magic. inu-light is intentionally minimal and predictable: the schema is the single source of truth. Advanced TypeScript generics provide precise inference, so external data cannot silently break your types at runtime.
 
-## Features
+- **Zero Dependencies**: minimal footprint, no runtime bloat
 
-- **Zero Dependencies**: Minimum footprint for your project.
-- **Type Safe**: Automatically infers TypeScript types from your schemas without using explicit any.
-- **ESM Native**: Built for modern environments.
-- **Lightweight**: Focused on core validation primitives.
+- **True Type Safety**: no any in the inference engine
+
+- **Runtime Validation**: Strict validation for primitives and nested object structures
+
+- **ESM Native**: optimized for Vite, Webpack 5, and Next.js
 
 ### Complex Types & Modifiers
 
@@ -30,32 +31,66 @@ npm install inu-light
 
 ## Usage
 
-### Basic Example
+### 1. Basic Example
 
-Define a schema and validate data against it. The `parse` method returns a result object containing either the validated data or an error message.
+The library uses the .parse() method to validate data. Instead of throwing unpredictable exceptions, it returns a result object containing either the validated data or a clear error message.
 
 ```typescript
 import { inu } from 'inu-light';
 
-const userSchema = inu.object({
-  name: inu.string(),
-  age: inu.number(),
-  isActive: inu.boolean(),
+const UserSchema = inu.object({
+  username: inu.string(),
+  priority: inu.number(),
+  isAdmin: inu.boolean(),
 });
 
-const result = userSchema.parse({
-  name: 'John Doe',
-  age: 30,
-  isActive: true,
-});
+const result = UserSchema.parse(apiResponse);
 
 if (result.success) {
-  console.log(result.value); // Type-safe data
+  // TypeScript automatically knows 'result.value' type
+  console.log(result.value.username);
 } else {
-  console.error(result.error);
+  console.error('Validation failed:', result.error);
 }
 ```
 
+### 2. Complex Types & Modifiers
+
+inu-light handles real-world data structures with ease:
+
+- **Optional & Nullable**: Explicitly allow undefined or null values.
+
+- **Unions**: Validate input against multiple possible schemas.
+
+- **Literals**: Enforce exact values (perfect for status codes or specific flags).
+
+```typescript
+const ProjectSchema = inu.object({
+  id: inu.string(),
+  description: inu.string().optional(), // Accepts string | undefined
+  status: inu.union([inu.literal('open'), inu.literal('closed')]),
+  tags: inu.array(inu.string()).nullable(), // Accepts string[] | null
+});
+```
+
+### 3. Type Inference (The "No Any" Rule)
+
+Avoid redundancy. You don't need to manually write interfaces; the schema generates them for you.
+
+```typescript
+import { inu, ShapeToType } from 'inu-light';
+
+const ProductSchema = inu.object({
+  sku: inu.string(),
+  price: inu.number(),
+});
+
+// Automatically extract the TypeScript type
+type Product = ShapeToType<typeof ProductSchema>;
+
+// Resulting type: { sku: string; price: number; }
+```
+
 ### Type Inference
 
 You can extract the TypeScript type directly from a schema using `ShapeToType`.
@@ -74,30 +109,46 @@ type User = ShapeToType<typeof schema>;
 
 ### Primitives
 
-- `inu.string()`: Validates that the input is a string.
-- `inu.number()`: Validates that the input is a number.
-- `inu.boolean()`: Validates that the input is a boolean.
+| Method          | Description           |
+| :-------------- | :-------------------- |
+| `inu.string()`  | Validates a `string`  |
+| `inu.number()`  | Validates a `number`  |
+| `inu.boolean()` | Validates a `boolean` |
 
-### Complex Types
+### Structural
 
-- `inu.object(shape)`: Validates an object based on the provided shape.
+| Method                | Description                                                 |
+| :-------------------- | :---------------------------------------------------------- |
+| `inu.object(shape)`   | Validates an object based on the provided shape.            |
+| `inu.array(schema)`   | Validates an array where every item matches the `schema`.   |
+| `inu.tuple([s1, s2])` | Validates a fixed-length array with positional types.       |
+| `inu.union([s1, s2])` | Validates if the input matches at least one of the schemas. |
+| `inu.literal(value)`  | Validates strict equality against the provided `value`.     |
 
-## Development
+### Modifiers (Available on all schemas)
 
-### Build
+- `.optional()`: Transforms the type to `T | undefined`.
+- `.nullable()`: Transforms the type to `T | null`.
 
-To compile the library from source:
+## Development
 
-```
+```bash
+# Install dependencies
+npm install
+
+# Build (Outputs to /dist)
 npm run build
+
+# Run local tests
+npx tsx test-local.ts
 ```
 
-### Testing
+### Build
 
-To run local tests during development:
+To compile the library from source:
 
 ```
-npx tsx test-local.ts
+npm run build
 ```
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "inu-light",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "A ultra-lightweight TypeScript validation library with zero dependencies.",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",