canonize 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Steve Kinney
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,629 @@
+# canonize
+
+**Aggressive type coercion for Zod schemas.**
+
+## The Problem
+
+You've defined a beautiful Zod schema:
+
+```typescript
+const userSchema = z.object({
+  age: z.number(),
+  active: z.boolean(),
+  tags: z.array(z.string()),
+});
+```
+
+Then reality hits. Your API receives:
+
+```typescript
+{ age: "30", active: "yes", tags: "admin,user" }
+```
+
+Zod's built-in `z.coerce` helps with simple cases, but it won't parse `"yes"` as `true`, split `"admin,user"` into an array, or handle the dozen other formats your data might arrive in.
+
+You're left writing preprocessing logic, custom transforms, or wrapper functions for every schema. The business logic gets buried under input normalization.
+
+## The Solution
+
+Wrap your schema with `canonize()` and move on:
+
+```typescript
+import { canonize } from 'canonize';
+
+const userSchema = canonize(
+  z.object({
+    age: z.number(),
+    active: z.boolean(),
+    tags: z.array(z.string()),
+  }),
+);
+
+// All of these now work:
+userSchema.parse({ age: '30', active: 'yes', tags: 'admin,user' });
+userSchema.parse({ age: 30.5, active: 1, tags: ['admin'] });
+userSchema.parse({ age: '30px', active: 'enabled', tags: '["admin"]' });
+```
+
+Canonize handles the messy real-world inputs so your schema can focus on validation:
+
+- `"30"`, `"30px"`, `"30.5"` → `30` (number)
+- `"yes"`, `"true"`, `"on"`, `"1"`, `1` → `true` (boolean)
+- `"admin,user"`, `'["admin","user"]'` → `["admin", "user"]` (array)
+- `"2024-01-15"`, `1705276800000`, `"now"` → `Date` object
+- Nested objects, unions, discriminated unions, intersections—all coerced recursively
+
+## When to Use Canonize
+
+- **API endpoints** receiving form data, query strings, or JSON from unknown clients
+- **Configuration files** where users write `enabled: yes` instead of `enabled: true`
+- **LLM tool calls** where the model outputs `"42"` instead of `42`
+- **Legacy system integration** with inconsistent data formats
+- **CSV/spreadsheet imports** where everything is a string
+
+## Installation
+
+```bash
+npm install canonize zod
+# or
+bun add canonize zod
+# or
+pnpm add canonize zod
+```
+
+## Quick Start
+
+```typescript
+import { canonize } from 'canonize';
+import { z } from 'zod';
+
+// Wrap any Zod schema
+const schema = canonize(
+  z.object({
+    name: z.string(),
+    age: z.number(),
+    active: z.boolean(),
+    tags: z.array(z.string()),
+  }),
+);
+
+// Coercion happens automatically
+schema.parse({ name: 123, age: '30', active: 'yes', tags: 'a,b,c' });
+// { name: '123', age: 30, active: true, tags: ['a', 'b', 'c'] }
+```
+
+---
+
+## API Reference
+
+### Core Function
+
+#### `canonize<T>(schema: T): T`
+
+Wraps a Zod schema with aggressive type coercion. Returns the same schema type for full TypeScript inference.
+
+```typescript
+import { canonize } from 'canonize';
+import { z } from 'zod';
+
+const numberSchema = canonize(z.number());
+numberSchema.parse('42'); // 42
+numberSchema.parse('42px'); // 42
+numberSchema.parse('1,234'); // 1234
+
+const boolSchema = canonize(z.boolean());
+boolSchema.parse('yes'); // true
+boolSchema.parse('0'); // false
+boolSchema.parse('enabled'); // true
+
+const arraySchema = canonize(z.array(z.number()));
+arraySchema.parse('1,2,3'); // [1, 2, 3]
+arraySchema.parse('[1,2,3]'); // [1, 2, 3]
+arraySchema.parse(42); // [42]
+```
+
+**Supported Zod types:**
+
+- Primitives: `string`, `number`, `boolean`, `bigint`, `date`, `null`, `nan`
+- Collections: `array`, `object`, `tuple`, `record`, `map`, `set`
+- Composites: `union`, `discriminatedUnion`, `intersection`
+- Special: `enum`, `literal`, `any`, `unknown`, `custom`
+- Wrappers: `optional`, `nullable`, `default`, `catch`, `readonly`, `lazy`
+
+---
+
+### Type Detection Utilities
+
+#### `getZodTypeName(schema: ZodTypeAny): string`
+
+Returns the Zod type name for a schema. Useful for building custom coercion logic.
+
+```typescript
+import { getZodTypeName } from 'canonize';
+import { z } from 'zod';
+
+getZodTypeName(z.string()); // 'string'
+getZodTypeName(z.array(z.number())); // 'array'
+getZodTypeName(z.object({})); // 'object'
+getZodTypeName(z.string().optional()); // 'optional'
+```
+
+#### `unwrapSchema(schema: ZodTypeAny): ZodTypeAny`
+
+Removes wrapper types (`optional`, `nullable`, `default`, `catch`, `readonly`) to get the inner schema.
+
+```typescript
+import { unwrapSchema, getZodTypeName } from 'canonize';
+import { z } from 'zod';
+
+const wrapped = z.string().optional().nullable().default('hello');
+const inner = unwrapSchema(wrapped);
+getZodTypeName(inner); // 'string'
+```
+
+---
+
+### Circular Reference Tracking
+
+#### `CircularTracker`
+
+A `WeakSet`-based tracker for detecting circular references during coercion. Prevents infinite loops when processing self-referential data structures.
+
+```typescript
+import { CircularTracker } from 'canonize';
+
+const tracker = new CircularTracker();
+const obj = { self: null };
+obj.self = obj; // circular reference
+
+tracker.has(obj); // false
+tracker.add(obj);
+tracker.has(obj); // true
+```
+
+---
+
+### Schema Creation Helpers
+
+#### `createCanonizePrimitive(primitive: CanonizePrimitive): ZodTypeAny`
+
+Creates a coerced Zod schema for a primitive type.
+
+```typescript
+import { createCanonizePrimitive } from 'canonize';
+
+const stringSchema = createCanonizePrimitive('string');
+const numberSchema = createCanonizePrimitive('number');
+const booleanSchema = createCanonizePrimitive('boolean');
+const nullSchema = createCanonizePrimitive('null');
+```
+
+**Supported primitives:** `'string' | 'number' | 'boolean' | 'null'`
+
+#### `createCanonizeSchema<T>(schema: T): ZodObject`
+
+Creates a Zod object schema from a record of primitive type names.
+
+```typescript
+import { createCanonizeSchema } from 'canonize';
+
+const schema = createCanonizeSchema({
+  name: 'string',
+  age: 'number',
+  active: 'boolean',
+});
+
+schema.parse({ name: 123, age: '30', active: 'yes' });
+// { name: '123', age: 30, active: true }
+```
+
+---
+
+### Constants
+
+#### `ZodType`
+
+Object containing Zod type name constants for use in type detection.
+
+```typescript
+import { ZodType } from 'canonize';
+
+ZodType.STRING; // 'string'
+ZodType.NUMBER; // 'number'
+ZodType.ARRAY; // 'array'
+ZodType.OBJECT; // 'object'
+ZodType.UNION; // 'union'
+// ... and more
+```
+
+**Available constants:**
+
+| Category    | Constants                                                                   |
+| ----------- | --------------------------------------------------------------------------- |
+| Primitives  | `STRING`, `NUMBER`, `BOOLEAN`, `DATE`, `BIGINT`, `NULL`, `UNDEFINED`, `NAN` |
+| Collections | `ARRAY`, `OBJECT`, `TUPLE`, `RECORD`, `MAP`, `SET`                          |
+| Composites  | `UNION`, `DISCRIMINATED_UNION`, `INTERSECTION`                              |
+| Enums       | `ENUM`, `NATIVE_ENUM`, `LITERAL`                                            |
+| Wrappers    | `OPTIONAL`, `NULLABLE`, `DEFAULT`, `CATCH`, `LAZY`, `READONLY`, `BRANDED`   |
+| Special     | `ANY`, `UNKNOWN`, `NEVER`, `CUSTOM`                                         |
+
+---
+
+### Types
+
+#### `CanonizeSchema<T>`
+
+Type alias representing a canonized schema. Preserves the original schema's type information.
+
+```typescript
+import type { CanonizeSchema } from 'canonize';
+import { z } from 'zod';
+
+type MySchema = CanonizeSchema<z.ZodObject<{ name: z.ZodString }>>;
+```
+
+#### `CanonizePrimitive`
+
+Union type for primitive type names accepted by `createCanonizePrimitive`.
+
+```typescript
+import type { CanonizePrimitive } from 'canonize';
+
+const primitive: CanonizePrimitive = 'string'; // 'string' | 'number' | 'boolean' | 'null'
+```
+
+---
+
+## Coercion Rules
+
+### String
+
+| Input               | Output         |
+| ------------------- | -------------- |
+| `"hello"`           | `"hello"`      |
+| `123`               | `"123"`        |
+| `true`              | `"true"`       |
+| `null`, `undefined` | `""`           |
+| `[1, 2, 3]`         | `"1, 2, 3"`    |
+| `{ key: "value" }`  | `"key: value"` |
+| `new Date()`        | ISO string     |
+
+### Number
+
+| Input                | Output    |
+| -------------------- | --------- |
+| `"42"`               | `42`      |
+| `"42px"`, `"42em"`   | `42`      |
+| `"1,234"`, `"1_234"` | `1234`    |
+| `"1e5"`              | `100000`  |
+| `true` / `false`     | `1` / `0` |
+| `[42]`               | `42`      |
+
+### Boolean
+
+| Input                                                         | Output  |
+| ------------------------------------------------------------- | ------- |
+| `"true"`, `"yes"`, `"on"`, `"y"`, `"t"`, `"enabled"`, `"1"`   | `true`  |
+| `"false"`, `"no"`, `"off"`, `"n"`, `"f"`, `"disabled"`, `"0"` | `false` |
+| `1`, non-zero numbers                                         | `true`  |
+| `0`                                                           | `false` |
+
+### Date
+
+| Input               | Output             |
+| ------------------- | ------------------ |
+| ISO string          | `new Date(string)` |
+| Unix timestamp (ms) | `new Date(number)` |
+| `"now"`             | Current time       |
+| `"today"`           | Start of today     |
+| `"yesterday"`       | Start of yesterday |
+| `"tomorrow"`        | Start of tomorrow  |
+
+### Array
+
+| Input              | Output            |
+| ------------------ | ----------------- |
+| `"1,2,3"`          | `["1", "2", "3"]` |
+| `"[1,2,3]"` (JSON) | `[1, 2, 3]`       |
+| `null`, `""`       | `[]`              |
+| `Set`, `Map`       | Array from values |
+| Single value       | `[value]`         |
+
+### Object
+
+| Input               | Output                 |
+| ------------------- | ---------------------- |
+| JSON string         | Parsed object          |
+| `Map`               | `Object.fromEntries()` |
+| `null`, `undefined` | `{}`                   |
+
+### Union
+
+Coercion tries options in order:
+
+1. Exact primitive match (preserves numbers in `string | number`)
+2. Object/record schemas for plain objects
+3. Array schemas for arrays and CSV strings
+4. Boolean schemas for boolean-like strings
+5. First union member, then remaining members
+
+### Discriminated Union
+
+Uses the discriminator field to select the variant, then coerces fields:
+
+```typescript
+const schema = canonize(
+  z.discriminatedUnion('type', [
+    z.object({ type: z.literal('a'), value: z.number() }),
+    z.object({ type: z.literal('b'), value: z.string() }),
+  ]),
+);
+
+schema.parse({ type: 'a', value: '42' }); // { type: 'a', value: 42 }
+```
+
+---
+
+## Tool Parameter Helpers
+
+The `canonize/tool-parameters` module provides schema builders for LLM tool definitions. These handle malformed AI outputs gracefully with sensible defaults.
+
+```typescript
+import {
+  boolean,
+  number,
+  string,
+  selector,
+  containerSelector,
+  collection,
+  numbers,
+  choices,
+  count,
+  url,
+  exportFormat,
+  imageFormat,
+  links,
+  linkMetadataSchema,
+  type LinkMetadata,
+} from 'canonize/tool-parameters';
+```
+
+### `boolean(defaultValue)`
+
+```typescript
+const enabled = boolean(true);
+enabled.parse('yes'); // true
+enabled.parse('FALSE'); // false
+enabled.parse(1); // true
+enabled.parse(undefined); // true (default)
+```
+
+### `number(defaultValue, options?)`
+
+```typescript
+const count = number(10, { min: 1, max: 100, int: true });
+count.parse('42px'); // 42
+count.parse('1,234'); // 1234
+count.parse(undefined); // 10 (default)
+```
+
+### `string()`
+
+```typescript
+const name = string();
+name.parse('  hello  '); // 'hello' (trimmed)
+name.parse(123); // '123'
+```
+
+### `selector()`
+
+CSS selector string, trimmed and validated non-empty.
+
+```typescript
+const sel = selector();
+sel.parse('  .class  '); // '.class'
+```
+
+### `containerSelector()`
+
+Container selector with intelligent coercion for common LLM mistakes:
+
+```typescript
+const container = containerSelector();
+container.parse('main'); // 'main'
+container.parse('*'); // null (wildcard → entire document)
+container.parse('null'); // null
+container.parse('a'); // null (link selector → entire document)
+container.parse('body a'); // 'body' (extracts container)
+container.parse('all'); // null (natural language)
+```
+
+### `collection(...defaultValues)`
+
+String array with flexible separators (comma, semicolon, pipe, newline):
+
+```typescript
+const tags = collection('default');
+tags.parse('foo,bar'); // ['foo', 'bar']
+tags.parse('foo;bar'); // ['foo', 'bar']
+tags.parse('foo|bar'); // ['foo', 'bar']
+tags.parse('foo\nbar'); // ['foo', 'bar']
+tags.parse(undefined); // ['default']
+```
+
+### `numbers(options?)`
+
+Number array with flexible input handling:
+
+```typescript
+const ids = numbers({ int: true, min: 0 });
+ids.parse('1,2,3'); // [1, 2, 3]
+ids.parse([1, '2', 3]); // [1, 2, 3]
+ids.parse(undefined); // []
+```
+
+### `choices(values, defaultValue?)`
+
+Enum with fuzzy matching (case-insensitive, prefix, contains):
+
+```typescript
+const sort = choices(['date', 'name', 'size'], 'date');
+sort.parse('Date'); // 'date' (case-insensitive)
+sort.parse('nam'); // 'name' (prefix match)
+sort.parse('date_desc'); // 'date' (contains match)
+```
+
+### `count()`
+
+Number for count/statistic values (defaults to 0):
+
+```typescript
+const total = count();
+total.parse('42'); // 42
+total.parse(null); // 0
+```
+
+### `url()`
+
+URL string with cleanup (removes wrapping quotes, brackets):
+
+```typescript
+const link = url();
+link.parse('"https://example.com"'); // 'https://example.com'
+link.parse('<https://example.com>'); // 'https://example.com'
+```
+
+### `exportFormat(options?)`
+
+Export format enum (`markdown`, `csv`, `json`):
+
+```typescript
+exportFormat(); // defaults to 'markdown'
+exportFormat({ defaultValue: 'csv' }); // defaults to 'csv'
+exportFormat({ includeJson: false }); // 'markdown' | 'csv' only
+```
+
+### `imageFormat(defaultValue?)`
+
+Image format enum (`jpeg`, `png`):
+
+```typescript
+imageFormat(); // defaults to 'png'
+imageFormat('jpeg'); // defaults to 'jpeg'
+```
+
+### `links()` and `linkMetadataSchema`
+
+Array of link metadata objects:
+
+```typescript
+const linkList = links();
+linkList.parse([{ title: 'Example', url: 'https://example.com' }]);
+
+// Or use the schema directly
+import { linkMetadataSchema, type LinkMetadata } from 'canonize/tool-parameters';
+
+const link: LinkMetadata = {
+  title: 'Example',
+  url: 'https://example.com',
+  source: 'html', // optional: 'html' | 'markdown' | 'element' | 'link'
+  rel: 'noopener', // optional
+  target: '_blank', // optional
+  referrerPolicy: null, // optional
+  text: 'Click here', // optional: raw link text
+};
+```
+
+---
+
+## Advanced Usage
+
+### Lazy Schemas (Recursive Types)
+
+```typescript
+const TreeNode = canonize(
+  z.lazy(() =>
+    z.object({
+      value: z.number(),
+      children: z.array(TreeNode).optional(),
+    }),
+  ),
+);
+
+TreeNode.parse({
+  value: '1',
+  children: [{ value: '2' }, { value: '3' }],
+});
+```
+
+### Intersection Types
+
+```typescript
+const schema = canonize(
+  z.intersection(z.object({ a: z.number() }), z.object({ b: z.string() })),
+);
+
+schema.parse({ a: '1', b: 2 }); // { a: 1, b: '2' }
+```
+
+### Map and Set
+
+```typescript
+const mapSchema = canonize(z.map(z.string(), z.number()));
+mapSchema.parse([
+  ['a', '1'],
+  ['b', '2'],
+]); // Map { 'a' => 1, 'b' => 2 }
+mapSchema.parse({ a: '1', b: '2' }); // Map { 'a' => 1, 'b' => 2 }
+
+const setSchema = canonize(z.set(z.number()));
+setSchema.parse([1, '2', 3]); // Set { 1, 2, 3 }
+setSchema.parse('1,2,3'); // Set { 1, 2, 3 }
+```
+
+---
+
+## Error Handling
+
+Coercion errors are caught internally—the original value passes through to Zod for validation:
+
+```typescript
+const schema = canonize(z.number());
+
+schema.parse('42'); // 42 (coercion succeeds)
+schema.parse('not a number'); // throws ZodError (coercion fails, Zod validates original)
+```
+
+Circular references throw immediately:
+
+```typescript
+const obj = { self: null };
+obj.self = obj;
+
+const schema = canonize(z.object({ self: z.any() }));
+schema.parse(obj); // throws Error: Circular reference detected
+```
+
+---
+
+## StandardSchema Compatibility
+
+Canonize is fully compatible with [StandardSchema](https://standardschema.dev/), the interoperability spec implemented by Zod, Valibot, ArkType, and others.
+
+Since Zod v4 implements StandardSchema, all canonized schemas have the `~standard` property:
+
+```typescript
+const schema = canonize(z.object({ count: z.number() }));
+
+// Use with any StandardSchema-aware tool
+const result = await schema['~standard'].validate({ count: '42' });
+// { value: { count: 42 } }
+```
+
+Canonize is Zod-specific because intelligent coercion requires schema introspection (knowing field types). StandardSchema only provides a `validate()` function without type information.
+
+---
+
+## License
+
+MIT

package/dist/coercers/array.d.ts

@@ -0,0 +1,7 @@
+import * as z from 'zod';
+import { CircularTracker } from '../utilities/circular.js';
+/**
+ * Coerce value to array with element type coercion
+ */
+export declare function coerceToArray(value: unknown, _elementSchema: z.ZodTypeAny, coerceElement: (v: unknown, tracker: CircularTracker) => unknown, tracker?: CircularTracker): unknown[];
+//# sourceMappingURL=array.d.ts.map

package/dist/coercers/array.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"array.d.ts","sourceRoot":"","sources":["../../src/coercers/array.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AAEzB,OAAO,EAAiB,eAAe,EAAiB,MAAM,0BAA0B,CAAC;AAIzF;;GAEG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,OAAO,EACd,cAAc,EAAE,CAAC,CAAC,UAAU,EAC5B,aAAa,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,eAAe,KAAK,OAAO,EAChE,OAAO,kBAAwB,GAC9B,OAAO,EAAE,CA4FX"}

package/dist/coercers/bigint.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Coerce any value to BigInt
+ */
+export declare function coerceToBigInt(value: unknown): bigint;
+//# sourceMappingURL=bigint.d.ts.map

package/dist/coercers/bigint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bigint.d.ts","sourceRoot":"","sources":["../../src/coercers/bigint.ts"],"names":[],"mappings":"AAGA;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAsErD"}

package/dist/coercers/boolean.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Coerce any value to boolean
+ */
+export declare function coerceToBoolean(value: unknown): boolean;
+//# sourceMappingURL=boolean.d.ts.map

package/dist/coercers/boolean.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"boolean.d.ts","sourceRoot":"","sources":["../../src/coercers/boolean.ts"],"names":[],"mappings":"AAIA;;GAEG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAwDvD"}

package/dist/coercers/date.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Coerce any value to Date
+ */
+export declare function coerceToDate(value: unknown): Date;
+//# sourceMappingURL=date.d.ts.map

package/dist/coercers/date.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"date.d.ts","sourceRoot":"","sources":["../../src/coercers/date.ts"],"names":[],"mappings":"AAIA;;GAEG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CA4HjD"}

package/dist/coercers/discriminated-union.d.ts

@@ -0,0 +1,7 @@
+import * as z from 'zod';
+import { CircularTracker } from '../utilities/circular.js';
+/**
+ * Coerce value to discriminated union (intelligently matches based on discriminator)
+ */
+export declare function coerceToDiscriminatedUnion(value: unknown, discriminatorKey: string, options: z.ZodTypeAny[], coerceOption: (index: number, v: unknown, tracker: CircularTracker) => unknown, tracker?: CircularTracker): unknown;
+//# sourceMappingURL=discriminated-union.d.ts.map

package/dist/coercers/discriminated-union.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discriminated-union.d.ts","sourceRoot":"","sources":["../../src/coercers/discriminated-union.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AAEzB,OAAO,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAK3D;;GAEG;AACH,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,OAAO,EACd,gBAAgB,EAAE,MAAM,EACxB,OAAO,EAAE,CAAC,CAAC,UAAU,EAAE,EACvB,YAAY,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,eAAe,KAAK,OAAO,EAC9E,OAAO,kBAAwB,GAC9B,OAAO,CAqFT"}