@warlock.js/seal 5.34.0 → 5.34.2
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 +6 -0
- package/llms-full.txt +57 -84
- package/llms.txt +1 -1
- package/package.json +1 -1
- package/skills/index.md +30 -1
- package/skills/overview/SKILL.md +0 -80
package/CHANGELOG.md
CHANGED
|
@@ -4,6 +4,12 @@ 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.2 - 2026-10-19
|
|
8
|
+
|
|
9
|
+
### Fixed
|
|
10
|
+
|
|
11
|
+
- Merge package orientation into the grouped skill index and remove the duplicate overview topic; preserve that orientation in generated LLM projections.
|
|
12
|
+
|
|
7
13
|
## 5.34.0 - 2026-10-19
|
|
8
14
|
|
|
9
15
|
### Changed
|
package/llms-full.txt
CHANGED
|
@@ -4,6 +4,63 @@
|
|
|
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
|
+
## Package orientation
|
|
8
|
+
|
|
9
|
+
---
|
|
10
|
+
description: 'Type-safe, framework-agnostic validation for Warlock.js: schemas, coercion, modifiers, JSON Schema, Standard Schema. Exports `v`, `validate`, `ObjectValidator`, `StringValidator`, `Infer`, reached as `v.object`, `v.string`, `v.array`, `v.enum`, `v.union`. Use for: "validate this request body", "require an email and a min-length password", "infer the TypeScript type from a schema", "make a field optional or give it a default", "generate JSON Schema", "write a custom rule". Not this package: database rules and file validators live in @warlock.js/core; model schemas and persistence are @warlock.js/cascade.'
|
|
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
|
+
|
|
7
64
|
## bridge-standard-schema `@warlock.js/seal/bridge-standard-schema/SKILL.md`
|
|
8
65
|
|
|
9
66
|
---
|
|
@@ -1447,90 +1504,6 @@ 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
|
-
## overview `@warlock.js/seal/overview/SKILL.md`
|
|
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
1507
|
## pick-seal-primitive `@warlock.js/seal/pick-seal-primitive/SKILL.md`
|
|
1535
1508
|
|
|
1536
1509
|
---
|
package/llms.txt
CHANGED
|
@@ -6,12 +6,12 @@
|
|
|
6
6
|
|
|
7
7
|
## Skills
|
|
8
8
|
|
|
9
|
+
- [Package orientation](@warlock.js/seal/skills/index.md): Type-safe, framework-agnostic validation for Warlock.js: schemas, coercion, modifiers, JSON Schema, Standard Schema. Exports `v`, `validate`, `ObjectValidator`, `StringValidator`, `Infer`, reached as `v.object`, `v.string`, `v.array`, `v.enum`, `v.union`. Use for: "validate this request body", "require an email and a min-length password", "infer the TypeScript type from a schema", "make a field optional or give it a default", "generate JSON Schema", "write a custom rule". Not this package: database rules and file validators live in @warlock.js/core; model schemas and persistence are @warlock.js/cascade.
|
|
9
10
|
- [bridge-standard-schema](@warlock.js/seal/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`.
|
|
10
11
|
- [compose-seal-modifiers](@warlock.js/seal/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`.
|
|
11
12
|
- [define-structural-shape](@warlock.js/seal/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`.
|
|
12
13
|
- [extend-seal-with-plugins](@warlock.js/seal/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`.
|
|
13
14
|
- [generate-json-schema](@warlock.js/seal/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`.
|
|
14
15
|
- [handle-seal-errors](@warlock.js/seal/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`.
|
|
15
|
-
- [overview](@warlock.js/seal/overview/SKILL.md): @warlock.js/seal overview for orientation and choosing the focused skill for the task.
|
|
16
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
17
|
- [seal-basics](@warlock.js/seal/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
|
@@ -6,9 +6,11 @@ description: 'Type-safe, framework-agnostic validation for Warlock.js: schemas,
|
|
|
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/`.
|