@warlock.js/seal 5.34.1 → 5.34.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +12 -0
- package/llms-full.txt +71 -98
- package/llms.txt +9 -9
- package/package.json +1 -1
- package/skills/index.md +31 -2
- package/skills/overview/SKILL.md +0 -80
package/CHANGELOG.md
CHANGED
|
@@ -4,6 +4,18 @@ All notable changes to `@warlock.js/seal` are documented in this file.
|
|
|
4
4
|
|
|
5
5
|
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). `@warlock.js/*` packages are released in lockstep — every package shares the same version number, so a version below may list only the changes that affected this package.
|
|
6
6
|
|
|
7
|
+
## 5.34.3 - 2026-10-20
|
|
8
|
+
|
|
9
|
+
### Changed
|
|
10
|
+
|
|
11
|
+
- Condensed the package agent skill description to at most 450 characters, with API names and package routing guidance.
|
|
12
|
+
|
|
13
|
+
## 5.34.2 - 2026-10-19
|
|
14
|
+
|
|
15
|
+
### Fixed
|
|
16
|
+
|
|
17
|
+
- Merge package orientation into the grouped skill index and remove the duplicate overview topic; preserve that orientation in generated LLM projections.
|
|
18
|
+
|
|
7
19
|
## 5.34.0 - 2026-10-19
|
|
8
20
|
|
|
9
21
|
### Changed
|
package/llms-full.txt
CHANGED
|
@@ -4,7 +4,64 @@
|
|
|
4
4
|
|
|
5
5
|
> Generated artifact. Concatenates every SKILL.md and reference file under `@warlock.js/seal/skills/`. Re-run `node scripts/generate-llms.mjs` after any change.
|
|
6
6
|
|
|
7
|
-
##
|
|
7
|
+
## Package orientation
|
|
8
|
+
|
|
9
|
+
---
|
|
10
|
+
description: 'Framework-independent typed validation: `v`, `validate`, `ObjectValidator`, `StringValidator` and `Infer`. Use for "validate a request body", "require an email", optional fields and defaults, schema type inference, custom rules, JSON Schema or Standard Schema. Not this package → @warlock.js/core for database rules and upload validators; @warlock.js/cascade for model schemas and persistence.'
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
# @warlock.js/seal
|
|
14
|
+
|
|
15
|
+
Compose validators from the `v` factory (`v.object({ email: v.string().email() })`), run them with `validate(schema, data)`, and infer static types with `Infer`. Validators chain rules, mutators (transforms) and modifiers; the same schema works as a Standard Schema.
|
|
16
|
+
|
|
17
|
+
Works standalone and ships with core. `Infer.Input` and `Infer.Output` distinguish pre-transform and post-transform shapes.
|
|
18
|
+
|
|
19
|
+
## The 80% path
|
|
20
|
+
|
|
21
|
+
1. Start with `seal-basics.md`.
|
|
22
|
+
2. Choose the right primitive: `pick-seal-primitive.md`.
|
|
23
|
+
3. Shape nested data: `define-structural-shape.md`.
|
|
24
|
+
4. Refine with optional, defaults, nullable and transforms: `compose-seal-modifiers.md`.
|
|
25
|
+
5. Handle failures and messages: `handle-seal-errors.md`.
|
|
26
|
+
6. Interop: `bridge-standard-schema.md`, `generate-json-schema.md`; extend via `extend-seal-with-plugins.md`.
|
|
27
|
+
|
|
28
|
+
## Conventions and pitfalls
|
|
29
|
+
|
|
30
|
+
- Validation is async; always `await validate(...)`.
|
|
31
|
+
- The package root is framework-agnostic; database-backed rules (unique, exists) and `FileValidator` come from `@warlock.js/core`, not here.
|
|
32
|
+
- Derive types with `Infer` instead of hand-writing parallel interfaces.
|
|
33
|
+
- Mutators change the data (trim, cast); order in the chain matters.
|
|
34
|
+
- Keep reusable schemas in shared modules so controllers and clients agree.
|
|
35
|
+
|
|
36
|
+
## When to reach for it
|
|
37
|
+
|
|
38
|
+
- You want a single source of truth for a shape — runtime validation, the TS type, and JSON Schema all from one declaration.
|
|
39
|
+
- You'd reach for **zod** / **yup** / **valibot** but want the library the rest of Warlock already speaks (request validation, AI tool inputs, Cascade model schemas).
|
|
40
|
+
- You need **JSON Schema output** for OpenAI structured outputs or an OpenAPI spec.
|
|
41
|
+
|
|
42
|
+
Skip if you only need framework-bound validators (file uploads, DB rules) — those live in `@warlock.js/core/v`, which extends this package.
|
|
43
|
+
|
|
44
|
+
## The mental model in one paragraph
|
|
45
|
+
|
|
46
|
+
`v` is a builder: `v.string()`, `v.int()`, `v.object({...})`, `v.array(...)`, and so on, chained with modifiers (`.optional()`, `.nullable()`, `.default(...)`, `.min(...)`). `validate(schema, data)` returns a `ValidationResult` with `isValid`, `data` (the validated value), and `errors[]`. `Infer<typeof schema>` gives you the static type (with `Infer.Input` / `Infer.Output` distinguishing pre- and post-transform shapes). Because every schema implements Standard Schema, it slots into any `StandardSchemaV1<T>` consumer — and `schema.toJsonSchema(target)` emits JSON Schema for external tools.
|
|
47
|
+
|
|
48
|
+
## Configuration
|
|
49
|
+
|
|
50
|
+
`configureSeal({ ... })` sets global behavior (translation hooks, first-error-only mode); `getSealConfig()` reads it; `resetSealConfig()` clears it. Most apps call `configureSeal` once at boot to wire i18n.
|
|
51
|
+
|
|
52
|
+
## What this package deliberately doesn't do
|
|
53
|
+
|
|
54
|
+
- **Framework-bound validation.** File-upload and database (exists/unique) rules live in `@warlock.js/core/v`, which builds on this package.
|
|
55
|
+
- **Coercion by default.** Seal validates the shape you declare; reshaping is explicit via mutators/transformers, not silent coercion.
|
|
56
|
+
- **Async-everywhere.** `validate()` is async to support rules that need it, but the core primitives are synchronous checks.
|
|
57
|
+
|
|
58
|
+
## See also
|
|
59
|
+
|
|
60
|
+
- `@warlock.js/cascade` (the `cascade-basics` topic of the `warlock-js-cascade` skill) — uses seal schemas as `Model.schema`.
|
|
61
|
+
- `@warlock.js/core` (the `validate-input` topic of the `warlock-js-core` skill) — adds framework validators through `core/v`; import the base `v` from seal.
|
|
62
|
+
|
|
63
|
+
|
|
64
|
+
## bridge-standard-schema `@warlock.js/seal/skills/bridge-standard-schema/SKILL.md`
|
|
8
65
|
|
|
9
66
|
---
|
|
10
67
|
name: bridge-standard-schema
|
|
@@ -170,7 +227,7 @@ Seal forks the types locally. Reasons:
|
|
|
170
227
|
If V2 lands, re-fork. Until then the local copy is the right call.
|
|
171
228
|
|
|
172
229
|
|
|
173
|
-
## compose-seal-modifiers `@warlock.js/seal/compose-seal-modifiers/SKILL.md`
|
|
230
|
+
## compose-seal-modifiers `@warlock.js/seal/skills/compose-seal-modifiers/SKILL.md`
|
|
174
231
|
|
|
175
232
|
---
|
|
176
233
|
name: compose-seal-modifiers
|
|
@@ -479,7 +536,7 @@ Switch back with `.immutable`. Default is fine 99% of the time. Reach for `.muta
|
|
|
479
536
|
- Don't mutate a schema you handed to a Model. Default immutability protects you; opting into `.mutable` on shared schemas is asking for confusion.
|
|
480
537
|
|
|
481
538
|
|
|
482
|
-
## define-structural-shape `@warlock.js/seal/define-structural-shape/SKILL.md`
|
|
539
|
+
## define-structural-shape `@warlock.js/seal/skills/define-structural-shape/SKILL.md`
|
|
483
540
|
|
|
484
541
|
---
|
|
485
542
|
name: define-structural-shape
|
|
@@ -654,7 +711,7 @@ rename entries; present keys are validated as strings. Literal keys are optional
|
|
|
654
711
|
in the inferred dictionary; use `v.object` for required named fields.
|
|
655
712
|
|
|
656
713
|
|
|
657
|
-
### define-structural-shape/array-methods.md `@warlock.js/seal/define-structural-shape/array-methods.md`
|
|
714
|
+
### define-structural-shape/array-methods.md `@warlock.js/seal/skills/define-structural-shape/array-methods.md`
|
|
658
715
|
|
|
659
716
|
# `v.array(itemValidator)` — method reference
|
|
660
717
|
|
|
@@ -736,7 +793,7 @@ v.array(v.string()).default([]).optional();
|
|
|
736
793
|
```
|
|
737
794
|
|
|
738
795
|
|
|
739
|
-
### define-structural-shape/object-methods.md `@warlock.js/seal/define-structural-shape/object-methods.md`
|
|
796
|
+
### define-structural-shape/object-methods.md `@warlock.js/seal/skills/define-structural-shape/object-methods.md`
|
|
740
797
|
|
|
741
798
|
# `v.object({...})` — method reference
|
|
742
799
|
|
|
@@ -934,7 +991,7 @@ const signupSchema = v.object({
|
|
|
934
991
|
```
|
|
935
992
|
|
|
936
993
|
|
|
937
|
-
## extend-seal-with-plugins `@warlock.js/seal/extend-seal-with-plugins/SKILL.md`
|
|
994
|
+
## extend-seal-with-plugins `@warlock.js/seal/skills/extend-seal-with-plugins/SKILL.md`
|
|
938
995
|
|
|
939
996
|
---
|
|
940
997
|
name: extend-seal-with-plugins
|
|
@@ -1150,7 +1207,7 @@ const bothDates: SchemaRule = {
|
|
|
1150
1207
|
```
|
|
1151
1208
|
|
|
1152
1209
|
|
|
1153
|
-
## generate-json-schema `@warlock.js/seal/generate-json-schema/SKILL.md`
|
|
1210
|
+
## generate-json-schema `@warlock.js/seal/skills/generate-json-schema/SKILL.md`
|
|
1154
1211
|
|
|
1155
1212
|
---
|
|
1156
1213
|
name: generate-json-schema
|
|
@@ -1297,7 +1354,7 @@ If the schema validator itself accepts data but the _generated_ JSON Schema reje
|
|
|
1297
1354
|
Generating JSON Schema is cheap (pure-function tree walk), so don't worry about caching the result for schemas that change at startup. For dynamic schemas built per-request, generate per-request — there's no shared mutable state.
|
|
1298
1355
|
|
|
1299
1356
|
|
|
1300
|
-
## handle-seal-errors `@warlock.js/seal/handle-seal-errors/SKILL.md`
|
|
1357
|
+
## handle-seal-errors `@warlock.js/seal/skills/handle-seal-errors/SKILL.md`
|
|
1301
1358
|
|
|
1302
1359
|
---
|
|
1303
1360
|
name: handle-seal-errors
|
|
@@ -1447,91 +1504,7 @@ Avoid leaking `result.data` back to the client when rejecting — it might conta
|
|
|
1447
1504
|
For server-side logs, log `errors[]` with the field paths and rule types; redact values unless you're certain the field isn't sensitive. The `@warlock.js/logger` redaction layer is the right place to enforce that.
|
|
1448
1505
|
|
|
1449
1506
|
|
|
1450
|
-
##
|
|
1451
|
-
|
|
1452
|
-
---
|
|
1453
|
-
name: overview
|
|
1454
|
-
description: "@warlock.js/seal overview for orientation and choosing the focused skill for the task."
|
|
1455
|
-
---
|
|
1456
|
-
|
|
1457
|
-
# `@warlock.js/seal` — overview
|
|
1458
|
-
|
|
1459
|
-
A type-safe, framework-agnostic validation library. You build a schema with the `v` factory, run it with `validate(schema, data)`, and pull the static type out with `Infer<typeof schema>`. One schema is the runtime check _and_ the TypeScript type _and_ (optionally) a JSON Schema.
|
|
1460
|
-
|
|
1461
|
-
Standalone — no framework required. Ships built-in with `@warlock.js/core`, which adds framework-specific validators (file uploads, database existence/uniqueness rules) on top.
|
|
1462
|
-
|
|
1463
|
-
## When to reach for it
|
|
1464
|
-
|
|
1465
|
-
- You want a single source of truth for a shape — runtime validation, the TS type, and JSON Schema all from one declaration.
|
|
1466
|
-
- You'd reach for **zod** / **yup** / **valibot** but want the library the rest of Warlock already speaks (request validation, AI tool inputs, Cascade model schemas).
|
|
1467
|
-
- You need **JSON Schema output** for OpenAI structured outputs or an OpenAPI spec.
|
|
1468
|
-
|
|
1469
|
-
Skip if you only need framework-bound validators (file uploads, DB rules) — those live in `@warlock.js/core/v`, which extends this package.
|
|
1470
|
-
|
|
1471
|
-
## The mental model in one paragraph
|
|
1472
|
-
|
|
1473
|
-
`v` is a builder: `v.string()`, `v.int()`, `v.object({...})`, `v.array(...)`, and so on, chained with modifiers (`.optional()`, `.nullable()`, `.default(...)`, `.min(...)`). `validate(schema, data)` returns a `ValidationResult` with `isValid`, `data` (the validated value), and `errors[]`. `Infer<typeof schema>` gives you the static type (with `Infer.Input` / `Infer.Output` distinguishing pre- and post-transform shapes). Because every schema implements Standard Schema, it slots into any `StandardSchemaV1<T>` consumer — and `schema.toJsonSchema(target)` emits JSON Schema for external tools.
|
|
1474
|
-
|
|
1475
|
-
## Skills index
|
|
1476
|
-
|
|
1477
|
-
Eight task skills. Most schemas only need `seal-basics` + `pick-seal-primitive` + `define-structural-shape`.
|
|
1478
|
-
|
|
1479
|
-
### Foundations
|
|
1480
|
-
|
|
1481
|
-
#### `seal-basics`
|
|
1482
|
-
|
|
1483
|
-
Start here. The `v` factory, `validate(schema, data)`, and `Infer<typeof schema>`.
|
|
1484
|
-
|
|
1485
|
-
### Building schemas
|
|
1486
|
-
|
|
1487
|
-
#### `pick-seal-primitive`
|
|
1488
|
-
|
|
1489
|
-
Choose the right primitive — `string` / `int` / `literal` / `date` / `enum` / `computed` / `managed` / `instanceof` / `any`. Covers the close calls (`string` vs `scalar`, `int` vs `number`, `literal` vs `enum`).
|
|
1490
|
-
|
|
1491
|
-
#### `define-structural-shape`
|
|
1492
|
-
|
|
1493
|
-
Compose `v.object` / `v.array` / `v.record` / `v.tuple` / `v.union` / `v.discriminatedUnion` / `v.lazy` — object schemas, dynamic-keyed records, tagged unions, recursive shapes.
|
|
1494
|
-
|
|
1495
|
-
#### `compose-seal-modifiers`
|
|
1496
|
-
|
|
1497
|
-
Cross-cutting modifiers — `.optional` / `.nullable` / `.default` / `.catch` / `.omit` / membership rules — plus the mutator-vs-transformer pipeline and `Infer.Input` vs `Infer.Output`.
|
|
1498
|
-
|
|
1499
|
-
### Output + interop
|
|
1500
|
-
|
|
1501
|
-
#### `handle-seal-errors`
|
|
1502
|
-
|
|
1503
|
-
Read a `ValidationResult` — `isValid`, `errors[]`, `data`. Branch on `error.type`, customize messages, hook translation.
|
|
1504
|
-
|
|
1505
|
-
#### `generate-json-schema`
|
|
1506
|
-
|
|
1507
|
-
`schema.toJsonSchema(target)` — draft-2020-12 / draft-07 / openapi-3.0 / openai-strict. For OpenAI structured outputs, OpenAPI specs, any JSON-Schema consumer.
|
|
1508
|
-
|
|
1509
|
-
#### `bridge-standard-schema`
|
|
1510
|
-
|
|
1511
|
-
Standard Schema interop — why a `StandardSchemaV1<T>` slot might reject a schema, object input/output class parameters and primitive factory intersections, Cascade `Model<TSchema>` variance. For migrating off `as unknown as` casts.
|
|
1512
|
-
|
|
1513
|
-
#### `extend-seal-with-plugins`
|
|
1514
|
-
|
|
1515
|
-
Author a plugin to add validator methods (`.slug`, `.postalCode`, …) — the `SealPlugin` shape, `registerPlugin` lifecycle, TS prototype augmentation.
|
|
1516
|
-
|
|
1517
|
-
## Configuration
|
|
1518
|
-
|
|
1519
|
-
`configureSeal({ ... })` sets global behavior (translation hooks, first-error-only mode); `getSealConfig()` reads it; `resetSealConfig()` clears it. Most apps call `configureSeal` once at boot to wire i18n.
|
|
1520
|
-
|
|
1521
|
-
## What this package deliberately doesn't do
|
|
1522
|
-
|
|
1523
|
-
- **Framework-bound validation.** File-upload and database (exists/unique) rules live in `@warlock.js/core/v`, which builds on this package.
|
|
1524
|
-
- **Coercion by default.** Seal validates the shape you declare; reshaping is explicit via mutators/transformers, not silent coercion.
|
|
1525
|
-
- **Async-everywhere.** `validate()` is async to support rules that need it, but the core primitives are synchronous checks.
|
|
1526
|
-
|
|
1527
|
-
## See also
|
|
1528
|
-
|
|
1529
|
-
- `@warlock.js/cascade` (the `cascade-basics` topic of the `warlock-js-cascade` skill) — uses seal schemas as `Model.schema`.
|
|
1530
|
-
- `@warlock.js/core` (the `validate-input` topic of the `warlock-js-core` skill) — re-exports `v` (aliased) and adds framework validators in `core/v`.
|
|
1531
|
-
- [`mongez-agent-kit-authoring-skills`](../../../../domains/shared/skills/) (load via agent-kit sync) — how this becomes `.claude/skills/warlock-js-seal-overview/`.
|
|
1532
|
-
|
|
1533
|
-
|
|
1534
|
-
## pick-seal-primitive `@warlock.js/seal/pick-seal-primitive/SKILL.md`
|
|
1507
|
+
## pick-seal-primitive `@warlock.js/seal/skills/pick-seal-primitive/SKILL.md`
|
|
1535
1508
|
|
|
1536
1509
|
---
|
|
1537
1510
|
name: pick-seal-primitive
|
|
@@ -1688,7 +1661,7 @@ For cross-cutting modifiers (`.optional`/`.nullable`/`.default`/`.catch`/`.in`/`
|
|
|
1688
1661
|
- Don't expect `v.computed` / `v.managed` to validate input — they ignore input shape entirely. Reach for them only when _producing_ a value.
|
|
1689
1662
|
|
|
1690
1663
|
|
|
1691
|
-
### pick-seal-primitive/boolean-methods.md `@warlock.js/seal/pick-seal-primitive/boolean-methods.md`
|
|
1664
|
+
### pick-seal-primitive/boolean-methods.md `@warlock.js/seal/skills/pick-seal-primitive/boolean-methods.md`
|
|
1692
1665
|
|
|
1693
1666
|
# `v.boolean()` — method reference
|
|
1694
1667
|
|
|
@@ -1796,7 +1769,7 @@ v.object({
|
|
|
1796
1769
|
```
|
|
1797
1770
|
|
|
1798
1771
|
|
|
1799
|
-
### pick-seal-primitive/date-methods.md `@warlock.js/seal/pick-seal-primitive/date-methods.md`
|
|
1772
|
+
### pick-seal-primitive/date-methods.md `@warlock.js/seal/skills/pick-seal-primitive/date-methods.md`
|
|
1800
1773
|
|
|
1801
1774
|
# `v.date()` — method reference
|
|
1802
1775
|
|
|
@@ -1975,7 +1948,7 @@ v.date().toEndOfDay().toDateOnly();
|
|
|
1975
1948
|
```
|
|
1976
1949
|
|
|
1977
1950
|
|
|
1978
|
-
### pick-seal-primitive/number-methods.md `@warlock.js/seal/pick-seal-primitive/number-methods.md`
|
|
1951
|
+
### pick-seal-primitive/number-methods.md `@warlock.js/seal/skills/pick-seal-primitive/number-methods.md`
|
|
1979
1952
|
|
|
1980
1953
|
# `v.number()` / `v.int()` / `v.float()` / `v.numeric()` — method reference
|
|
1981
1954
|
|
|
@@ -2117,7 +2090,7 @@ v.int().min(0).default(0).optional();
|
|
|
2117
2090
|
```
|
|
2118
2091
|
|
|
2119
2092
|
|
|
2120
|
-
### pick-seal-primitive/string-methods.md `@warlock.js/seal/pick-seal-primitive/string-methods.md`
|
|
2093
|
+
### pick-seal-primitive/string-methods.md `@warlock.js/seal/skills/pick-seal-primitive/string-methods.md`
|
|
2121
2094
|
|
|
2122
2095
|
# `v.string()` — method reference
|
|
2123
2096
|
|
|
@@ -2295,7 +2268,7 @@ The standalone `replaceMutator` and `replaceAllMutator` preserve the stringified
|
|
|
2295
2268
|
value when called without a context or replacement options.
|
|
2296
2269
|
|
|
2297
2270
|
|
|
2298
|
-
## seal-basics `@warlock.js/seal/seal-basics/SKILL.md`
|
|
2271
|
+
## seal-basics `@warlock.js/seal/skills/seal-basics/SKILL.md`
|
|
2299
2272
|
|
|
2300
2273
|
---
|
|
2301
2274
|
name: seal-basics
|
package/llms.txt
CHANGED
|
@@ -6,12 +6,12 @@
|
|
|
6
6
|
|
|
7
7
|
## Skills
|
|
8
8
|
|
|
9
|
-
- [
|
|
10
|
-
- [
|
|
11
|
-
- [
|
|
12
|
-
- [
|
|
13
|
-
- [
|
|
14
|
-
- [
|
|
15
|
-
- [
|
|
16
|
-
- [pick-seal-primitive](@warlock.js/seal/pick-seal-primitive/SKILL.md): Pick the right `v` factory primitive — string / int / literal / date / enum / computed / managed / instanceof / any. Triggers: `v.string`, `v.email`, `v.number`, `v.int`, `v.float`, `v.numeric`, `v.boolean`, `v.scalar`, `v.date`, `v.literal`, `v.enum`, `v.instanceof`, `v.computed`, `v.managed`, `v.any`; "v.string vs v.scalar", "v.literal vs v.enum", "v.date vs v.instanceof(Date)", "what is v.computed"; typical import `import { v } from "@warlock.js/seal"`. Skip: structural shapes — the `define-structural-shape` topic; modifiers — the `compose-seal-modifiers` topic; competing libs `zod`, `valibot`, `yup`.
|
|
17
|
-
- [seal-basics](@warlock.js/seal/seal-basics/SKILL.md): Start here for @warlock.js/seal schemas, validation, parsing, and typed structural contracts.
|
|
9
|
+
- [Package orientation](@warlock.js/seal/skills/index.md): Framework-independent typed validation: `v`, `validate`, `ObjectValidator`, `StringValidator` and `Infer`. Use for "validate a request body", "require an email", optional fields and defaults, schema type inference, custom rules, JSON Schema or Standard Schema. Not this package → @warlock.js/core for database rules and upload validators; @warlock.js/cascade for model schemas and persistence.
|
|
10
|
+
- [bridge-standard-schema](@warlock.js/seal/skills/bridge-standard-schema/SKILL.md): Diagnose `StandardSchemaV1` interop — input/output class parameters and primitive factory intersections, why typed slots reject a schema, cascade `Model<TSchema>` variance. Triggers: `StandardSchemaV1`, `~standard`, `Infer`, `ObjectValidator`, `StringValidator`, `LiteralValidator`, `BaseValidator`, `Model<TSchema>`, `StandardJSONSchemaV1`, `Result<unknown>`; "StandardSchemaV1 slot rejecting my schema", "Result<unknown> error", "drop as unknown as cast", "cascade Model schema variance"; typical import `import { v, type Infer } from "@warlock.js/seal"`. Skip: foundations — the `seal-basics` topic; JSON Schema gen — the `generate-json-schema` topic; competing spec `@standard-schema/spec`.
|
|
11
|
+
- [compose-seal-modifiers](@warlock.js/seal/skills/compose-seal-modifiers/SKILL.md): Apply cross-cutting modifiers — `.optional` / `.nullable` / `.default` / `.catch` / `.omit` / membership rules — plus the mutator-vs-transformer pipeline and `Infer.Input` vs `Infer.Output`. Triggers: `.optional`, `.required`, `.nullable`, `.default`, `.catch`, `.present`, `.requiredIf`, `.requiredWith`, `.in`, `.oneOf`, `.notIn`, `.omit`, `.attribute`, `.mutable`, `.addMutator`, `Infer.Input`, `Infer.Output`; "mark field optional in seal", "default value in schema", "mutator vs transformer", "when does .catch fire"; typical import `import { v, type Infer } from "@warlock.js/seal"`. Skip: primitives — the `pick-seal-primitive` topic; containers — the `define-structural-shape` topic; errors — the `handle-seal-errors` topic; competing `zod` `.optional`/`.default`.
|
|
12
|
+
- [define-structural-shape](@warlock.js/seal/skills/define-structural-shape/SKILL.md): Compose `v.object` / `v.array` / `v.record` / `v.tuple` / `v.union` / `v.discriminatedUnion` / `v.lazy`. Triggers: `v.object`, `v.array`, `v.record`, `v.tuple`, `v.union`, `v.discriminatedUnion`, `v.lazy`, `ObjectValidator`; "how do I build an object schema", "dynamic-keyed record", "tagged union with discriminator", "recursive schema", "self-referencing schema"; typical import `import { v, type Infer } from "@warlock.js/seal"`. Skip: leaf primitives — the `pick-seal-primitive` topic; modifiers — the `compose-seal-modifiers` topic; standard-schema bridge — the `bridge-standard-schema` topic; competing libs `zod`, `valibot`.
|
|
13
|
+
- [extend-seal-with-plugins](@warlock.js/seal/skills/extend-seal-with-plugins/SKILL.md): Author a custom seal plugin to add validator methods (`.slug`, `.postalCode`, etc) — `SealPlugin` shape, `registerPlugin` lifecycle, TS prototype augmentation. Triggers: `SealPlugin`, `registerPlugin`, `unregisterPlugin`, `hasPlugin`, `getInstalledPlugins`, `StringValidator`, `NumberValidator`, `DateValidator`, `BaseValidator`, `install`, `uninstall`; "how do I add a custom validator method", "write a seal plugin", "extend v.string with .slug", "module augmentation for seal"; typical import `import { StringValidator, registerPlugin, type SealPlugin } from "@warlock.js/seal"`. Skip: built-in primitives — the `pick-seal-primitive` topic; bridge typing — the `bridge-standard-schema` topic; competing `zod` `.refine`/`.transform`.
|
|
14
|
+
- [generate-json-schema](@warlock.js/seal/skills/generate-json-schema/SKILL.md): Generate JSON Schema via `schema.toJsonSchema(target)` — `draft-2020-12` / `draft-07` / `openapi-3.0` / `openai-strict`. Triggers: `toJsonSchema`, `JsonSchemaTarget`, `draft-2020-12`, `draft-07`, `openapi-3.0`, `openai-strict`, `response_format`, `additionalProperties`, `nullable`; "how do I generate JSON Schema from seal", "OpenAI structured outputs from schema", "OpenAPI 3.0 nullable", "json_schema strict mode"; typical import `import { v } from "@warlock.js/seal"`. Skip: foundations — the `seal-basics` topic; bridge typing — the `bridge-standard-schema` topic; competing libs `zod-to-json-schema`, `ajv`, `@anatine/zod-openapi`.
|
|
15
|
+
- [handle-seal-errors](@warlock.js/seal/skills/handle-seal-errors/SKILL.md): Read `ValidationResult` — `isValid`, `errors[]`, `data`. Branch on `error.type`, customize messages, hook translation. Triggers: `ValidationResult`, `ValidationError`, `validate`, `isValid`, `errors`, `data`, `error.type`, `error.input`, `error.error`, `translationParams`, `.attribute`, `SealConfig`; "how to read seal errors", "branch on a specific rule failure", "customize validation error message", "translate seal error", "surface validation errors as 422"; typical import `import { validate, v } from "@warlock.js/seal"`. Skip: modifiers — the `compose-seal-modifiers` topic; structural shapes — the `define-structural-shape` topic; competing libs `zod` `.safeParse`, `yup` `ValidationError`, `joi`.
|
|
16
|
+
- [pick-seal-primitive](@warlock.js/seal/skills/pick-seal-primitive/SKILL.md): Pick the right `v` factory primitive — string / int / literal / date / enum / computed / managed / instanceof / any. Triggers: `v.string`, `v.email`, `v.number`, `v.int`, `v.float`, `v.numeric`, `v.boolean`, `v.scalar`, `v.date`, `v.literal`, `v.enum`, `v.instanceof`, `v.computed`, `v.managed`, `v.any`; "v.string vs v.scalar", "v.literal vs v.enum", "v.date vs v.instanceof(Date)", "what is v.computed"; typical import `import { v } from "@warlock.js/seal"`. Skip: structural shapes — the `define-structural-shape` topic; modifiers — the `compose-seal-modifiers` topic; competing libs `zod`, `valibot`, `yup`.
|
|
17
|
+
- [seal-basics](@warlock.js/seal/skills/seal-basics/SKILL.md): Start here for @warlock.js/seal schemas, validation, parsing, and typed structural contracts.
|
package/package.json
CHANGED
package/skills/index.md
CHANGED
|
@@ -1,14 +1,16 @@
|
|
|
1
1
|
---
|
|
2
|
-
description: '
|
|
2
|
+
description: 'Framework-independent typed validation: `v`, `validate`, `ObjectValidator`, `StringValidator` and `Infer`. Use for "validate a request body", "require an email", optional fields and defaults, schema type inference, custom rules, JSON Schema or Standard Schema. Not this package → @warlock.js/core for database rules and upload validators; @warlock.js/cascade for model schemas and persistence.'
|
|
3
3
|
---
|
|
4
4
|
|
|
5
5
|
# @warlock.js/seal
|
|
6
6
|
|
|
7
7
|
Compose validators from the `v` factory (`v.object({ email: v.string().email() })`), run them with `validate(schema, data)`, and infer static types with `Infer`. Validators chain rules, mutators (transforms) and modifiers; the same schema works as a Standard Schema.
|
|
8
8
|
|
|
9
|
+
Works standalone and ships with core. `Infer.Input` and `Infer.Output` distinguish pre-transform and post-transform shapes.
|
|
10
|
+
|
|
9
11
|
## The 80% path
|
|
10
12
|
|
|
11
|
-
1.
|
|
13
|
+
1. Start with `seal-basics.md`.
|
|
12
14
|
2. Choose the right primitive: `pick-seal-primitive.md`.
|
|
13
15
|
3. Shape nested data: `define-structural-shape.md`.
|
|
14
16
|
4. Refine with optional, defaults, nullable and transforms: `compose-seal-modifiers.md`.
|
|
@@ -22,3 +24,30 @@ Compose validators from the `v` factory (`v.object({ email: v.string().email() }
|
|
|
22
24
|
- Derive types with `Infer` instead of hand-writing parallel interfaces.
|
|
23
25
|
- Mutators change the data (trim, cast); order in the chain matters.
|
|
24
26
|
- Keep reusable schemas in shared modules so controllers and clients agree.
|
|
27
|
+
|
|
28
|
+
## When to reach for it
|
|
29
|
+
|
|
30
|
+
- You want a single source of truth for a shape — runtime validation, the TS type, and JSON Schema all from one declaration.
|
|
31
|
+
- You'd reach for **zod** / **yup** / **valibot** but want the library the rest of Warlock already speaks (request validation, AI tool inputs, Cascade model schemas).
|
|
32
|
+
- You need **JSON Schema output** for OpenAI structured outputs or an OpenAPI spec.
|
|
33
|
+
|
|
34
|
+
Skip if you only need framework-bound validators (file uploads, DB rules) — those live in `@warlock.js/core/v`, which extends this package.
|
|
35
|
+
|
|
36
|
+
## The mental model in one paragraph
|
|
37
|
+
|
|
38
|
+
`v` is a builder: `v.string()`, `v.int()`, `v.object({...})`, `v.array(...)`, and so on, chained with modifiers (`.optional()`, `.nullable()`, `.default(...)`, `.min(...)`). `validate(schema, data)` returns a `ValidationResult` with `isValid`, `data` (the validated value), and `errors[]`. `Infer<typeof schema>` gives you the static type (with `Infer.Input` / `Infer.Output` distinguishing pre- and post-transform shapes). Because every schema implements Standard Schema, it slots into any `StandardSchemaV1<T>` consumer — and `schema.toJsonSchema(target)` emits JSON Schema for external tools.
|
|
39
|
+
|
|
40
|
+
## Configuration
|
|
41
|
+
|
|
42
|
+
`configureSeal({ ... })` sets global behavior (translation hooks, first-error-only mode); `getSealConfig()` reads it; `resetSealConfig()` clears it. Most apps call `configureSeal` once at boot to wire i18n.
|
|
43
|
+
|
|
44
|
+
## What this package deliberately doesn't do
|
|
45
|
+
|
|
46
|
+
- **Framework-bound validation.** File-upload and database (exists/unique) rules live in `@warlock.js/core/v`, which builds on this package.
|
|
47
|
+
- **Coercion by default.** Seal validates the shape you declare; reshaping is explicit via mutators/transformers, not silent coercion.
|
|
48
|
+
- **Async-everywhere.** `validate()` is async to support rules that need it, but the core primitives are synchronous checks.
|
|
49
|
+
|
|
50
|
+
## See also
|
|
51
|
+
|
|
52
|
+
- `@warlock.js/cascade` (the `cascade-basics` topic of the `warlock-js-cascade` skill) — uses seal schemas as `Model.schema`.
|
|
53
|
+
- `@warlock.js/core` (the `validate-input` topic of the `warlock-js-core` skill) — adds framework validators through `core/v`; import the base `v` from seal.
|
package/skills/overview/SKILL.md
DELETED
|
@@ -1,80 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: overview
|
|
3
|
-
description: "@warlock.js/seal overview for orientation and choosing the focused skill for the task."
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# `@warlock.js/seal` — overview
|
|
7
|
-
|
|
8
|
-
A type-safe, framework-agnostic validation library. You build a schema with the `v` factory, run it with `validate(schema, data)`, and pull the static type out with `Infer<typeof schema>`. One schema is the runtime check _and_ the TypeScript type _and_ (optionally) a JSON Schema.
|
|
9
|
-
|
|
10
|
-
Standalone — no framework required. Ships built-in with `@warlock.js/core`, which adds framework-specific validators (file uploads, database existence/uniqueness rules) on top.
|
|
11
|
-
|
|
12
|
-
## When to reach for it
|
|
13
|
-
|
|
14
|
-
- You want a single source of truth for a shape — runtime validation, the TS type, and JSON Schema all from one declaration.
|
|
15
|
-
- You'd reach for **zod** / **yup** / **valibot** but want the library the rest of Warlock already speaks (request validation, AI tool inputs, Cascade model schemas).
|
|
16
|
-
- You need **JSON Schema output** for OpenAI structured outputs or an OpenAPI spec.
|
|
17
|
-
|
|
18
|
-
Skip if you only need framework-bound validators (file uploads, DB rules) — those live in `@warlock.js/core/v`, which extends this package.
|
|
19
|
-
|
|
20
|
-
## The mental model in one paragraph
|
|
21
|
-
|
|
22
|
-
`v` is a builder: `v.string()`, `v.int()`, `v.object({...})`, `v.array(...)`, and so on, chained with modifiers (`.optional()`, `.nullable()`, `.default(...)`, `.min(...)`). `validate(schema, data)` returns a `ValidationResult` with `isValid`, `data` (the validated value), and `errors[]`. `Infer<typeof schema>` gives you the static type (with `Infer.Input` / `Infer.Output` distinguishing pre- and post-transform shapes). Because every schema implements Standard Schema, it slots into any `StandardSchemaV1<T>` consumer — and `schema.toJsonSchema(target)` emits JSON Schema for external tools.
|
|
23
|
-
|
|
24
|
-
## Skills index
|
|
25
|
-
|
|
26
|
-
Eight task skills. Most schemas only need `seal-basics` + `pick-seal-primitive` + `define-structural-shape`.
|
|
27
|
-
|
|
28
|
-
### Foundations
|
|
29
|
-
|
|
30
|
-
#### `seal-basics`
|
|
31
|
-
|
|
32
|
-
Start here. The `v` factory, `validate(schema, data)`, and `Infer<typeof schema>`.
|
|
33
|
-
|
|
34
|
-
### Building schemas
|
|
35
|
-
|
|
36
|
-
#### `pick-seal-primitive`
|
|
37
|
-
|
|
38
|
-
Choose the right primitive — `string` / `int` / `literal` / `date` / `enum` / `computed` / `managed` / `instanceof` / `any`. Covers the close calls (`string` vs `scalar`, `int` vs `number`, `literal` vs `enum`).
|
|
39
|
-
|
|
40
|
-
#### `define-structural-shape`
|
|
41
|
-
|
|
42
|
-
Compose `v.object` / `v.array` / `v.record` / `v.tuple` / `v.union` / `v.discriminatedUnion` / `v.lazy` — object schemas, dynamic-keyed records, tagged unions, recursive shapes.
|
|
43
|
-
|
|
44
|
-
#### `compose-seal-modifiers`
|
|
45
|
-
|
|
46
|
-
Cross-cutting modifiers — `.optional` / `.nullable` / `.default` / `.catch` / `.omit` / membership rules — plus the mutator-vs-transformer pipeline and `Infer.Input` vs `Infer.Output`.
|
|
47
|
-
|
|
48
|
-
### Output + interop
|
|
49
|
-
|
|
50
|
-
#### `handle-seal-errors`
|
|
51
|
-
|
|
52
|
-
Read a `ValidationResult` — `isValid`, `errors[]`, `data`. Branch on `error.type`, customize messages, hook translation.
|
|
53
|
-
|
|
54
|
-
#### `generate-json-schema`
|
|
55
|
-
|
|
56
|
-
`schema.toJsonSchema(target)` — draft-2020-12 / draft-07 / openapi-3.0 / openai-strict. For OpenAI structured outputs, OpenAPI specs, any JSON-Schema consumer.
|
|
57
|
-
|
|
58
|
-
#### `bridge-standard-schema`
|
|
59
|
-
|
|
60
|
-
Standard Schema interop — why a `StandardSchemaV1<T>` slot might reject a schema, object input/output class parameters and primitive factory intersections, Cascade `Model<TSchema>` variance. For migrating off `as unknown as` casts.
|
|
61
|
-
|
|
62
|
-
#### `extend-seal-with-plugins`
|
|
63
|
-
|
|
64
|
-
Author a plugin to add validator methods (`.slug`, `.postalCode`, …) — the `SealPlugin` shape, `registerPlugin` lifecycle, TS prototype augmentation.
|
|
65
|
-
|
|
66
|
-
## Configuration
|
|
67
|
-
|
|
68
|
-
`configureSeal({ ... })` sets global behavior (translation hooks, first-error-only mode); `getSealConfig()` reads it; `resetSealConfig()` clears it. Most apps call `configureSeal` once at boot to wire i18n.
|
|
69
|
-
|
|
70
|
-
## What this package deliberately doesn't do
|
|
71
|
-
|
|
72
|
-
- **Framework-bound validation.** File-upload and database (exists/unique) rules live in `@warlock.js/core/v`, which builds on this package.
|
|
73
|
-
- **Coercion by default.** Seal validates the shape you declare; reshaping is explicit via mutators/transformers, not silent coercion.
|
|
74
|
-
- **Async-everywhere.** `validate()` is async to support rules that need it, but the core primitives are synchronous checks.
|
|
75
|
-
|
|
76
|
-
## See also
|
|
77
|
-
|
|
78
|
-
- `@warlock.js/cascade` (the `cascade-basics` topic of the `warlock-js-cascade` skill) — uses seal schemas as `Model.schema`.
|
|
79
|
-
- `@warlock.js/core` (the `validate-input` topic of the `warlock-js-core` skill) — re-exports `v` (aliased) and adds framework validators in `core/v`.
|
|
80
|
-
- [`mongez-agent-kit-authoring-skills`](../../../../domains/shared/skills/) (load via agent-kit sync) — how this becomes `.claude/skills/warlock-js-seal-overview/`.
|