wysiwyv 0.1.0 → 0.1.1

package/README-INCLUDED-PLUGINS.md

@@ -0,0 +1,576 @@
+| [README](README.md) | [USAGE](README-USAGE.md) | _INCLUDED PLUGINS_ | [PLUGIN AUTHORING](README-PLUGIN-AUTHORING.md) | [INTEGRATION](README-INTEGRATION.md) |
+| :------------------ | :----------------------- | :----------------- | :--------------------------------------------- | :----------------------------------- |
+
+# Included Plugins
+
+- [Basic Syntax](#basic-syntax)
+- [$and](#and) / [$or](#or)
+- [$any](#any)
+- [$array](#array) / [$object](#object) / [$plainobject](#plain-object)
+- [$basicisodate](#basic-iso-date) / [$isodate](#iso-date) / [$strictisodate](#strict-iso-date)
+- [$bool](#bool)
+- [$email](#email)
+- [$int](#int) / [$number](#number)
+- [$string](#string)
+- [$uuid](#uuid)
+- [$val](#val)
+
+## BASIC SYNTAX
+
+Each plugin has a unique tag starting with a dollar sign, e.g. `$myplugin`.
+
+Syntax varies by number of parameters being passed to the plugin.
+
+### No Parameters
+
+Matcher is a simple string with just the plugin tag:
+
+```js
+{ "id": "$uuid" }
+```
+
+### One Parameter
+
+Matcher is an object with the tag as its only key, and parameter as its value. (Here, the UUID version)
+
+```js
+{ "id": { "$uuid": 4 } }
+```
+
+### Named Parameters
+
+Matcher is an object with the tag as its only key, and a sub-object with the named parameters. Parameter names also start with `$`
+
+```js
+{ "age": {
+    "$int": {
+        "$min": 20,
+        "$max": 80
+    }
+}}
+```
+
+[↑ top](#included-plugins)
+
+## AND
+
+Key: `$and`
+
+Takes an array of predicates.
+
+- If array is empty, returns success
+- If ALL predicates are passed, returns success
+- If ANY predicates fail:
+  - One error is recorded for the $and block itself
+  - All errors from failed predicates are returned
+  - The same path will be set for all for easy association
+- No short-circuiting; all predicates are evaluated
+
+```js
+{
+  "id": {
+      "$and": [
+          "$uuid",
+          { "$val": "store_id" }
+      ],
+  },
+}
+```
+
+See [and-plugin.test.ts](tests/plugins/and-plugin.test.ts) for exhaustive cases
+
+[↑ top](#included-plugins)
+
+## ANY
+
+Key: `$any`
+
+Succeeds on any input value.
+
+```js
+{ "biography": "$any" }
+```
+
+See [any-plugin.test.ts](tests/plugins/any-plugin.test.ts) for exhaustive cases
+
+[↑ top](#included-plugins)
+
+## ARRAY
+
+Key: `$array`
+
+Validates that the input is an array.
+
+- No parameters: accepts any array
+- Optional named parameters:
+  - `$length` — exact length match
+  - `$minlength` — minimum length (inclusive)
+  - `$maxlength` — maximum length (inclusive)
+  - `$each` — validate every element against a template  
+    If _none_ of these are present, any parameter provided will be treated as `$each`
+- All length constraints are checked independently; a value can fail multiple constraints
+- ⚠️ Unknown parameters alongside recognized ones generate a config error
+
+```js
+// bare — any array
+{ "tags": "$array" }
+```
+
+```js
+// length constraints
+{ "tags": { "$array": { "$minlength": 1, "$maxlength": 10 } } }
+```
+
+```js
+// explicit $each — validate every element
+{ "tags": {
+    "$array": {
+        "$each": "$string"
+    }
+}}
+```
+
+```js
+// implicit $each — validate every element
+{ "ages": {
+    "$array": "$number"
+}}
+```
+
+```js
+// implicit each shorthand — if no recognized parameters are present,
+// the params object itself becomes the element template
+{ "team": {
+    "$array": {
+        "name": "$string",
+        "role": "$string"
+    }
+}}
+```
+
+**Note:** The implicit shorthand only activates when _no_ recognized parameters (`$length`, `$minlength`, `$maxlength`, `$each`) are present. Mixing recognized parameters with extra keys produces a config error.
+
+See [array-plugin.test.ts](tests/plugins/array-plugin.test.ts) for exhaustive cases
+
+[↑ top](#included-plugins)
+
+## BASIC ISO DATE
+
+Key: `$basicisodate`
+
+Validates ISO 8601 Basic format — the compact form with no separators.
+
+- Must be a string
+- Format: `YYYYMMDDTHHmmssZ` (no dashes or colons)
+- Seconds and fractional seconds are optional
+- Timezone designator is required (`Z` or `±HHmm`)
+- Case-insensitive `T` separator
+- Validates numeric ranges for date/time components
+
+```js
+// accepts "20201209T160953Z"
+{ "timestamp": "$basicisodate" }
+```
+
+See [datetime-plugin.test.ts](tests/plugins/datetime-plugin.test.ts) for exhaustive cases
+
+[↑ top](#included-plugins)
+
+## BOOL
+
+Key: `$bool`
+
+Validates that the input is a boolean.
+
+- Accepts `true` and `false` only
+- Rejects truthy/falsy stand-ins: `"true"`, `"false"`, `0`, `1`, etc.
+- No parameters
+
+```js
+{ "active": "$bool" }
+```
+
+See [bool-plugin.test.ts](tests/plugins/bool-plugin.test.ts) for exhaustive cases
+
+[↑ top](#included-plugins)
+
+## EMAIL
+
+Key: `$email`
+
+Validates email address format.
+
+- Must be a string
+- Covers common email formats; not an exhaustive RFC 5322 implementation
+- Rejects: missing `@`, double `@`, trailing dot in domain, consecutive dots in local part, spaces, bare addresses without a domain dot
+- No parameters
+
+```js
+{ "contact": "$email" }
+```
+
+See [email-plugin.test.ts](tests/plugins/email-plugin.test.ts) for exhaustive cases
+
+[↑ top](#included-plugins)
+
+## INT
+
+Key: `$int`
+
+Validates that the input is an integer.
+
+- Uses `Number.isInteger()` under the hood
+- Accepts whole-valued floats like `1.0` and `-0`
+- Rejects floats, NaN, Infinity, bigints, and non-numbers
+- Optional named parameters:
+  - `$min` — inclusive lower bound (≥)
+  - `$max` — inclusive upper bound (≤)
+- Both constraints are checked independently; a value can fail both
+
+```js
+// bare — any integer
+{ "count": "$int" }
+```
+
+```js
+// with bounds
+{ "age": {
+    "$int": {
+        "$min": 0,
+        "$max": 150
+    }
+}}
+```
+
+See [int-plugin.test.ts](tests/plugins/int-plugin.test.ts) for exhaustive cases
+
+[↑ top](#included-plugins)
+
+## ISO DATE
+
+Key: `$isodate`
+
+Validates ISO 8601 Extended format — the common form with separators.
+
+- Must be a string
+- Format: `YYYY-MM-DDTHH:mm:ssZ` (with dashes and colons)
+- Seconds and fractional seconds are optional
+- Timezone designator is required (`Z` or `±HH:mm`)
+- Case-insensitive `T` separator
+- Validates numeric ranges for date/time components
+- Also checks that the string parses to a valid JS Date (catches things like Feb 30)
+
+```js
+// accepts "2026-05-05T20:41:00Z", "2026-05-05T13:41:00-07:00"
+{ "createdAt": "$isodate" }
+```
+
+See [datetime-plugin.test.ts](tests/plugins/datetime-plugin.test.ts) for exhaustive cases
+
+[↑ top](#included-plugins)
+
+## NUMBER
+
+Key: `$number`
+
+Validates that the input is a finite number.
+
+- Accepts integers, floats, `-0`
+- Rejects NaN, Infinity, -Infinity, bigints, and non-numbers
+- Optional named parameters:
+  - `$min` — inclusive lower bound (≥)
+  - `$max` — inclusive upper bound (≤)
+  - `$gt` — exclusive lower bound (>)
+  - `$lt` — exclusive upper bound (<)
+- All constraints are checked independently
+
+```js
+// bare — any finite number
+{ "score": "$number" }
+```
+
+```js
+// inclusive bounds
+{ "rating": {
+    "$number": {
+        "$min": 0,
+        "$max": 5
+    }
+}}
+```
+
+```js
+// exclusive bounds
+{ "temperature": {
+    "$number": {
+        "$gt": -273.15
+    }
+}}
+```
+
+See [number-plugin.test.ts](tests/plugins/number-plugin.test.ts) for exhaustive cases
+
+[↑ top](#included-plugins)
+
+## OBJECT
+
+Key: `$object`
+
+Validates that the input is an object in the broad sense — includes Date, RegExp, Map, Set, wrapped primitives, etc.
+
+- Rejects `null`, arrays, functions, and classes
+- For plain objects only, see [$plainobject](#plain-object)
+- Optional named parameters (mutually exclusive):
+  - `$partial` — validate a subset of keys; extra keys in the candidate are allowed; missing expected keys produce errors
+  - `$eachElement` — validate every value in the object against a template
+- Using both `$partial` and `$eachElement` together produces a config error
+- Unknown parameters produce a config error
+
+```js
+// bare — accepts any object, including Date, Map, Set, etc.
+{ "metadata": "$object" }
+```
+
+```js
+// partial match — only check specified keys, ignore extras
+{ "user": {
+    "$object": {
+        "$partial": {
+            "name": "$string",
+            "email": "$email"
+        }
+    }
+}}
+```
+
+```js
+// each element — every value must match the template
+{ "scores": {
+    "$object": {
+        "$eachElement": "$number"
+    }
+}}
+```
+
+```js
+// each element with nesting
+{ "teams": {
+    "$object": {
+        "$eachElement": { "$array": { "$length": 2 } }
+    }
+}}
+```
+
+See [object-plugin.test.ts](tests/plugins/object-plugin.test.ts) for exhaustive cases
+
+[↑ top](#included-plugins)
+
+## OR
+
+Key: `$or`
+
+Takes an array of predicates.
+
+- If array is empty, returns an error
+  - Boolean algebra defines the OR identity as false
+- If ANY predicates are passed, returns success
+  - Short-Circuiting: Further predicates are not evaluated
+- If ALL predicates fail:
+  - One error is recorded for the $or block itself
+  - All errors from all predicates are returned
+  - The same path will be set for all for easy association
+
+```js
+{
+  "id": {
+      "$or": [
+          "$uuid",
+          "$number"
+      ]
+  }
+}
+```
+
+See [or-plugin.test.ts](tests/plugins/or-plugin.test.ts) for exhaustive cases
+
+[↑ top](#included-plugins)
+
+## PLAIN OBJECT
+
+Key: `$plainobject`
+
+Validates that the input is a plain object — only literal `{}`, `new Object()`, and `Object.create(null)`.
+
+- Rejects Date, RegExp, Map, Set, wrapped primitives, and other non-plain objects
+- Stricter than [$object](#object), which accepts any object type
+- Same optional parameters as `$object`:
+  - `$partial` — validate a subset of keys
+  - `$eachElement` — validate every value
+- `$partial` and `$eachElement` are mutually exclusive
+
+```js
+// bare — any plain object
+{ "config": "$plainobject" }
+```
+
+```js
+// with $partial
+{ "config": {
+    "$plainobject": {
+        "$partial": {
+            "debug": "$bool",
+            "port": "$int"
+        }
+    }
+}}
+```
+
+See [object-plugin.test.ts](tests/plugins/object-plugin.test.ts) for exhaustive cases
+
+[↑ top](#included-plugins)
+
+## STRICT ISO DATE
+
+Key: `$strictisodate`
+
+Validates RFC 3339 format — a strict profile of ISO 8601 commonly used in APIs.
+
+- Must be a string
+- Format: `YYYY-MM-DDTHH:mm:ss.sssZ`
+- Allows space as date/time separator (not just `T`)
+- Seconds and fractional seconds are optional
+- Timezone designator is required (`Z` or `±HH:mm`, including `-00:00`)
+- Case-insensitive `T`/`t` separator
+- Also checks that the string parses to a valid JS Date
+
+```js
+// accepts "2026-05-05T20:41:00Z", "2026-05-05 20:41:00Z"
+{ "timestamp": "$strictisodate" }
+```
+
+See [datetime-plugin.test.ts](tests/plugins/datetime-plugin.test.ts) for exhaustive cases
+
+[↑ top](#included-plugins)
+
+## STRING
+
+Key: `$string`
+
+Validates that the input is a string.
+
+- Accepts any primitive string value
+- Rejects non-strings, including numbers, booleans, null, undefined, and boxed `new String()` objects
+- No parameters
+
+```js
+{ "name": "$string" }
+```
+
+See [string-plugin.test.ts](tests/plugins/string-plugin.test.ts) for exhaustive cases
+
+[↑ top](#included-plugins)
+
+## UUID
+
+Key: `$uuid`
+
+Validates UUID format.
+
+- No parameter: accepts any valid UUID (versions 1–8, NIL, and max)
+- Single parameter (version): validates a specific UUID version
+  - `0` — NIL UUID (all zeros)
+  - `1` through `8` — specific version
+  - `"F"` — max UUID (all f's)
+- Invalid version numbers produce a config error
+- Must be a string
+- Case-insensitive
+
+```js
+// any UUID
+{ "id": "$uuid" }
+```
+
+```js
+// specific version
+{ "id": { "$uuid": 4 } }
+```
+
+```js
+// NIL UUID
+{ "id": { "$uuid": 0 } }
+```
+
+See [uuid-plugin.test.ts](tests/plugins/uuid-plugin.test.ts) for exhaustive cases
+
+[↑ top](#included-plugins)
+
+## VAL
+
+Key: `$val`
+
+Matches values by name — either against predefined values supplied at setup time, or by capturing and back-referencing values seen during validation.
+
+### Predefined Values
+
+Supply known values when creating the validator. The template checks that candidate values match.
+
+```js
+const wyv = makeWysiwyv({
+  pluginSetups: {
+    $val: {
+      expectedTeam: "Yankees",
+      fruit: "apple",
+    },
+  },
+});
+
+const expected = {
+  team: { $val: "expectedTeam" },
+  snack: { $val: "fruit" },
+};
+
+// passes if team === "Yankees" and snack === "apple"
+```
+
+### Back-References
+
+If a val name hasn't been predefined, the first occurrence captures whatever value appears in the candidate. Subsequent uses of the same name check that the value matches.
+
+```js
+const expected = {
+  billing: {
+    customerId: { $val: "cid" },
+  },
+  shipping: {
+    customerId: { $val: "cid" },
+  },
+};
+
+// passes if billing.customerId === shipping.customerId
+// (whatever the value is)
+```
+
+### Combined
+
+Predefined values and back-references work together. Predefined keys are checked immediately; undefined keys are captured on first encounter and enforced on subsequent encounters.
+
+```js
+const wyv = makeWysiwyv({
+  pluginSetups: {
+    $val: { region: "us-east-1" },
+  },
+});
+
+const expected = {
+  region: { $val: "region" },
+  primaryId: { $val: "id" },
+  backupId: { $val: "id" },
+};
+
+// region must be "us-east-1" (predefined)
+// primaryId and backupId must match each other (back-reference)
+```
+
+See [vals-plugin.test.ts](tests/plugins/vals-plugin.test.ts) for exhaustive cases
+
+[↑ top](#included-plugins)

package/README-INTEGRATION.md

@@ -0,0 +1,45 @@
+| [README](README.md) | [USAGE](README-USAGE.md) | [INCLUDED PLUGINS](README-INCLUDED-PLUGINS.md) | [PLUGIN AUTHORING](README-PLUGIN-AUTHORING.md) | _INTEGRATION_ |
+| :------------------ | :----------------------- | :--------------------------------------------- | :--------------------------------------------- | ------------- |
+
+# Integration
+
+## jest
+
+See [test-util](./test-util.ts)
+
+## express
+
+```ts
+const wyv = makeWysiwyv();
+
+export const validateBody =
+  (template: HookValue) =>
+  (req: Request, res: Response, next: NextFunction) => {
+    const result = wyv.validate(template, req.body);
+    if (result.success) return next();
+    res.status(400).json({
+      error: "Validation failed",
+      details: result.errors,
+    });
+  };
+
+const newUserTemplate = {
+  name: "$string",
+  email: "$email",
+  age: { $int: { $min: 18 } },
+};
+
+app.post("/users", validateBody(newUserTemplate), createUserHandler);
+```
+
+## zod
+
+```ts
+const toZodLike = (assessment: HookAssessment) => ({
+  success: assessment.success,
+  issues: assessment.errors.map((e) => ({
+    message: e.message,
+    path: e.path.split(".").filter(Boolean), // convert ".age" to ["age"]
+  })),
+});
+```

package/README-PLUGIN-AUTHORING.md

@@ -0,0 +1,177 @@
+| [README](README.md) | [USAGE](README-USAGE.md) | [INCLUDED PLUGINS](README-INCLUDED-PLUGINS.md) | _PLUGIN AUTHORING_ | [INTEGRATION](README-INTEGRATION.md) |
+| :------------------ | :----------------------- | :--------------------------------------------- | :----------------- | :----------------------------------- |
+
+# Plugin Authoring
+
+## 1. Pick a key.
+
+Select a string to identify your plugin. It should start with a dollar sign and should be unique among loaded plugins. We can use `$us-ssn` as an example.
+Your key will be used in several contexts:
+
+1. In a matching template, to select your plugin for matching a given node.
+2. In initial Wysiwyv factory, to specify plugin setup data.
+3. When the engine is calling your plugin, to give you exclusive access to setup and scratch data.
+
+[↑ top](#plugin-authoring)
+
+## 2. Scaffold your plugin.
+
+1. Start with a `WyvPlugin` object.
+2. Populate `handles` with a function that will return true when passed your key.
+3. Populate `handlers` with an object that maps your key to a function that should evaluate the node being evaluated.
+
+```ts
+export const WYV_KEY_US_SSN = "$us-ssn";
+const ssnWyvern: WyvPlugin = {
+  handles: (value) => [WYV_KEY_US_SSN].includes(value),
+  handlers: {
+    [WYV_KEY_US_SSN]: (value, expected, options) => {
+      // ...
+    },
+  },
+};
+```
+
+[↑ top](#plugin-authoring)
+
+## 3. Evaluate data and return your assessment.
+
+1. The `value` parameter is the value to be evaluated.  
+   The `expected` parameter is the template node the value should be assessed against.
+1. If you have determined the value is acceptable, just  
+   `return HookAssessor.SUCCESS;`
+1. If you have one reason for rejecting a value
+   1. create an error with one of the helpers from `HookError.ts`:  
+      `const e = errValue(3, 6, '.employee[3].id');`
+   2. return it with  
+      `return HookAssessor.fault(myError);`
+1. If you have multiple reasons for rejecting a value
+   1. start an assessement with:  
+      `const errors = HookAssessment.start()`
+   2. add encountered errors one at a time with `errors.fault(myNextError);`
+   3. incorporate another assessent into your open one with `errors.include(myOtherErrors);`
+   4. when finished, just `return errors;`
+1. All assessments follow the same format:
+
+if no issues encountered:
+
+```ts
+{
+  success: true,
+  errors: [],
+}
+```
+
+if faults are found:
+
+```ts
+{
+  success: false,
+  errors: [
+    {message: '...', path: '...'},
+    ...,
+  ],
+}
+```
+
+[↑ top](#plugin-authoring)
+
+## 4. Know your Options
+
+The `options` parameter has several fields.
+
+```ts
+options = {
+  path: string;
+  params: ParamsType;
+  setup: SetupType;
+  context: ContextType;
+  shared: Record<string, unknown>;
+  evaluate: WysiwyvEvaluatorFunction;
+}
+```
+
+- `path`:
+  - Your current path in the original data structure.
+  - Components look like `.fieldname` for objects or `[#]` for arrays.
+  - Use this as the path value when making HookErrors
+- `params`:
+  - Parameters to your plugin specified at the current position in the matching template object.
+  - Customize by defining a `MyHookParams` type reflecting how they should be passed.
+  - This can be any kind of data representable in JSON since it comes from the template.  
+    `type WyvParams = { version: number }`
+- `setup`:
+  - Parameters to your plugin specified at the time the matching engine is instantiated (makeWysiwyv)
+  - Customize by defining a `MyHookSetup` type similar to that for `params`
+  - How to provide the data is shown below, at [Register Plugin](#6-register-plugin)
+- `context`:
+  - A private data store for any information your plugin needs to track from one instance to the next.
+  - Only plugins with the same `key` will see this data.
+  - Customize with a `MyHookContext` type similar to that for `params`.
+- `shared`:
+  - A shared data store for any information that needs to be reused across multiple plugin types.
+  - This is the Wild West. No type enforcement, no privacy.
+- `evaluate`:
+  - A callback function provided by the engine. See [Recurse and Descend](#5-recurse-and-descend)
+
+⚠️ If you customize any types, all should be provided as type params when defining your plugin:
+
+```ts
+const ssnWyvern: WyvPlugin<MyParams, MySetup, MyContext> = {...};
+```
+
+[↑ top](#plugin-authoring)
+
+## 5. Recurse and Descend
+
+Your plugin can behave like `$array` or `$object`, descending recursively into a subtree of the data. This could even be a virtual tree, generated during validation by your custom logic.
+
+1. Open an assessment:  
+   `const errors = HookAssessment.start();`
+
+2. Call `options.evaluate` on the subtree:
+
+- This is a function provided by the engine for recursive descent. Call it when you need to hand control back, for example in the case of evaluating individual array or object children.
+- Call with the following arguments:
+  - `expected` A Wysiwyv template object to be evaluated on the subtree
+  - `candidate` The child (or derived) field or subtree being evaluated
+  - `path` Use the `options.path` parameter you received, appending information about how the child element is being selected (key, index, hash, etc)
+
+  `const subErrors = options.evaluate(subTemplate, subTree, path + 'my selector');`
+
+3. Include any errors back into your assessment:
+
+   `errors.include(subErrors);`
+
+4. Return your final assessment with errors from your level plus any errors from the recursion.
+
+   `return errors;`
+
+[↑ top](#plugin-authoring)
+
+## 6. Register Plugin
+
+Pass your plugin into `config.plugins` when making your engine instance.
+
+If you have preconfig data to provide, pass it in to `config.pluginSetups.$myPlugin`.
+
+```ts
+import { makeWysiwyv } from "./src/wysiwyv-core";
+// or, if you want to include all default plugins:
+// import { makeWysiwyv } from "./src/wysiwyv";
+
+import usSsnWyvern from "./src/hooks/us-ssn";
+
+const wyv = makeWysiwyv({
+  plugins: [usSsnWyvern],
+  pluginSetups: {
+    "$us-ssn": {
+      defaultFormat: "###-##-####",
+    },
+  },
+});
+
+const result = wyv.validate(myExpected, myCandidate);
+```
+
+[↑ top](#plugin-authoring)

package/README-USAGE.md

@@ -0,0 +1,352 @@
+| [README](README.md) | _USAGE_ | [INCLUDED PLUGINS](README-INCLUDED-PLUGINS.md) | [PLUGIN AUTHORING](README-PLUGIN-AUTHORING.md) | [INTEGRATION](README-INTEGRATION.md) |
+| :------------------ | :------ | :--------------------------------------------- | :--------------------------------------------- | :----------------------------------- |
+
+# WYSIWYV - Usage
+
+- [Basics](#basics)
+- [Result Format](#result-format)
+- [Literal Matching](#literal-matching)
+- [Plugins](#plugins)
+- [Escaping](#escaping)
+- [Plugin Parameters](#plugin-parameters)
+- [Initialization](#initialization)
+- [Template Parameters](#template-parameters)
+- [Composition](#composition)
+
+## Basics
+
+1. Get your data.
+
+   Any data will do; it does not need to be an object at root.
+
+   `const data = {name: "Joe"};`
+
+2. Write your template.
+
+   You can start by copy-pasting your data, if that helps.
+
+   Anything that should be dynamic, replace with a matcher.
+
+   `const template = {name: "$string"};`
+
+3. Make your validator
+
+   You can select custom plugin sets, add your own, or initialize data for smart plugins
+
+   `const wyv = makeWysiwyv();`
+
+4. Run the validation
+
+   `const result = wyv.validate(template, data);`
+
+5. Enjoy Success!
+
+   `console.log(result.success);`
+
+   ```json
+   true
+   ```
+
+[↑ top](#wysiwyv---usage)
+
+## Result Format
+
+The result format is consistent whether successful, partially successful, or if a validation is fully rejected.
+
+Every error includes a detailed message and a full path to where in the comparison the error was encountered.
+
+- Object keys look like `.key`
+- Array indexes look like `[10]`
+
+On success:
+
+```js
+{ success: true, errors: [] }
+```
+
+On errors:
+
+```js
+{
+  success: false,
+  errors:[
+    {
+      message: "Type: Expected 'number', got value 'old enough'",
+      path: ".age"
+    },
+    {
+      message: "Value: Expected 'Sales', got value 'Delivery'",
+      path: ".jobs[1].dept.name"
+    }
+  ]
+}
+```
+
+[↑ top](#wysiwyv---usage)
+
+## Literal Matching
+
+The core behavior is just a simple deep-comparison matcher. Your data should look exactly like your template. Only an exact match will achieve `success`!
+
+All templates must consist only of values representable by JSON; the data being matched can be arbitrary, but plugins must be used to validate anything not representable in JSON.
+
+### Valid Types:
+
+- _scalars_: null, number, string, boolean
+- _arrays_ with elements of any valid type
+- _objects_ with string keys and values of any valid type
+
+### Example
+
+data:
+
+```js
+{
+  name: "Jawn Deaux",
+  jobs:[
+    {
+      title: "CEO",
+      dept: {
+        name: "Delivery"
+      }
+    },
+    {
+      title: "Director",
+      dept: {
+        name: "Sales"
+        }
+    }
+  ]
+}
+```
+
+template:
+
+```json
+{
+  "name": "Jawn Deaux",
+  "jobs": [
+    {
+      "title": "CEO",
+      "dept": {
+        "name": "Delivery"
+      }
+    },
+    {
+      "title": "Director",
+      "dept": {
+        "name": "Sales"
+      }
+    }
+  ]
+}
+```
+
+[↑ top](#wysiwyv---usage)
+
+## Plugins
+
+Plugins are where everything gets flexible. You can assess data types, sub-object shapes, array length, array elements, combine assessments with boolean logic, or write your own plugins for anything we didn't think of.
+
+We will gladly include or link any plugins you care to share!
+
+- Every plugin is identified by a `key` -- a string starting with a dollar sign (`$`). For example: `$and`, `$uuid`.
+
+- Plugins are used in place of values in the matching template.
+
+static:
+
+```json
+{
+  "id": "John"
+}
+```
+
+loose:
+
+```json
+{
+  "id": "$string"
+}
+```
+
+[↑ top](#wysiwyv---usage)
+
+## Escaping
+
+Sometimes you really will want to match a string starting with a dollar sign. Just use a second dollar sign (`$$`) in your matching string to indicate it's not meant to be a plugin key.
+
+data (starts with single dollar):
+
+```json
+{
+  "name": "$heka"
+}
+```
+
+matching template (double dollar):
+
+```json
+{
+  "name": "$$heka"
+}
+```
+
+[↑ top](#wysiwyv---usage)
+
+## Plugin Parameters
+
+When referencing a plugin, it can be passed 0, 1, or more parameters.
+
+0 Params: Just use the plugin key as a string.
+
+```json
+{
+  "datum-list": "$array"
+}
+```
+
+1 Param: Use a simple object with plugin as key and parameter as value. The plugin's docs will tell you what argument a single parameter will correspond to, if there are multiple.
+
+```js
+{
+  // default arg is $uuid.$version
+  "id": { "$uuid": 4 },
+}
+```
+
+More Params: Use a nested object. The outer just has the plugin key, and the inner has the parameters paired with named keys.
+
+```json
+{
+  "datum-list": {
+    "$array": {
+      "$minlength": 2,
+      "$maxlength": 10
+    }
+  }
+}
+```
+
+[↑ top](#wysiwyv---usage)
+
+## Initialization
+
+Plugins can accept pre-filled setup objects. For example, when matching values, you could have some that you got from another source during a test, but after setting up the validation template.
+
+```js
+const wyv = makeWysiwyv({
+  pluginSetups: {
+    $val: {
+      entityId: 24601,
+    },
+  },
+});
+
+const data = {
+  id: 24601,
+};
+
+const template = {
+  id: { $val: "entityId" },
+};
+
+const result = wyv.validate(template, data);
+
+// result.success === true
+```
+
+[↑ top](#wysiwyv---usage)
+
+## Template Parameters
+
+### (Meta-Plugins)
+
+Some plugins accept matcher templates as parameters.
+
+- `$and` and `$or` each take an array of templates to evaluate
+- `$array.$each` is an optional template that every element of an array must individually match
+- `$object.$eachElement` and `$plainobject.$eachElement` are similar, every value (regardless of key) must match
+- `$object.$partial` and `$plainobject.$partial` are optional (mutually exclusive with `.$eachElement`) templates. Every k-v present in the provided template must be present in the candidate data being evaluated. Extra candidate-object keys beyond those listed are ignored (accepted).
+
+### $or template:
+
+```json
+{
+  "department": {
+    "$or": ["Sales", "Marketing", "Ideation", "Finance"]
+  }
+}
+```
+
+### $object.$partial
+
+#### candidate data:
+
+```js
+{
+  id: 24680,
+  name: "Jane Doe-Smith",
+}
+```
+
+#### matcher template:
+
+```json
+{
+  "$object": {
+    "$partial": {
+      "id": 24680
+      // ignores .name
+    }
+  }
+}
+```
+
+[↑ top](#wysiwyv---usage)
+
+## Composition
+
+Any Meta-Plugins can be nested and alternated arbitrarily with other plugins and with core behavior. Because control is handed back to the engine for each node in descent, nested claims are treated identically to ones in the base tree.
+
+data:
+
+```js
+{
+  people: [
+    {
+      name: "Jon Deo",
+      title: "CEO",
+      salary: 800_000,
+    },
+    {
+      name: "Don Jo",
+      department: "Burger-Flippin",
+      wage: 3.75,
+    },
+  ],
+}
+```
+
+template:
+
+```js
+{
+  people: {
+    $array: { $each: {
+        $and: [
+          { $object: { $partial:
+            { name: "$string" }
+          }},
+          { $or: [
+            { name: "$any", title: "$string", salary: "$number" },
+            { name: "$any", department: "$string", wage: "$number" },
+          ]},
+        ],
+      },
+    },
+  },
+}
+```
+
+[↑ top](#wysiwyv---usage)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wysiwyv",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "main": "./dist/wysiwyv.js",
   "devDependencies": {
     "@eslint/js": "^10.0.1",
@@ -15,6 +15,11 @@
   "peerDependencies": {
     "typescript": "^5"
   },
+  "peerDependenciesMeta": {
+    "typescript": {
+      "optional": true
+    }
+  },
   "exports": {
     ".": {
       "types": "./dist/wysiwyv.d.ts",
@@ -28,7 +33,7 @@
   "files": [
     "dist",
     "LICENSE",
-    "README.md"
+    "README*.md"
   ],
   "jsdelivr": "./dist/wysiwyv.min.js",
   "scripts": {