@modulify/validator 0.2.1 → 0.3.1

package/dist/types/json-schema.d.cts

@@ -0,0 +1,75 @@
+import type {
+  Constraint,
+  ConstraintDescriptor,
+  MaybeMany,
+} from './index.cjs'
+
+/** JSON Schema primitive `type` values used by `toJsonSchema(...)`. */
+export type JsonSchemaTypeName =
+  | 'string'
+  | 'number'
+  | 'integer'
+  | 'boolean'
+  | 'object'
+  | 'array'
+  | 'null'
+
+/** Minimal JSON Schema object shape emitted by the built-in exporter. */
+export interface JsonSchema {
+  readonly $schema?: string;
+  readonly $id?: string;
+  readonly $comment?: string;
+  readonly title?: string;
+  readonly description?: string;
+  readonly format?: string;
+  readonly default?: unknown;
+  readonly examples?: readonly unknown[];
+  readonly deprecated?: boolean;
+  readonly readOnly?: boolean;
+  readonly writeOnly?: boolean;
+  readonly type?: JsonSchemaTypeName | readonly JsonSchemaTypeName[];
+  readonly const?: unknown;
+  readonly enum?: readonly unknown[];
+  readonly allOf?: readonly JsonSchema[];
+  readonly anyOf?: readonly JsonSchema[];
+  readonly oneOf?: readonly JsonSchema[];
+  readonly properties?: Readonly<Record<string, JsonSchema>>;
+  readonly required?: readonly string[];
+  readonly additionalProperties?: boolean | JsonSchema;
+  readonly items?: JsonSchema;
+  readonly prefixItems?: readonly JsonSchema[];
+  readonly minItems?: number;
+  readonly maxItems?: number;
+  readonly minLength?: number;
+  readonly maxLength?: number;
+  readonly pattern?: string;
+  readonly minimum?: number;
+  readonly maximum?: number;
+  readonly multipleOf?: number;
+}
+
+/** Controls how `toJsonSchema(...)` handles constraints that cannot be represented faithfully. */
+export type JsonSchemaExportMode = 'bestEffort' | 'strict'
+
+/** Options for the JSON Schema exporter. */
+export interface ToJsonSchemaOptions {
+  readonly mode?: JsonSchemaExportMode
+}
+
+/** Error thrown by `toJsonSchema(...)` in strict mode when a node cannot be exported faithfully. */
+export declare class JsonSchemaExportError extends Error {
+  constructor(message: string, options: {
+    descriptor: ConstraintDescriptor
+    reason: string
+    path?: readonly PropertyKey[]
+  })
+  readonly descriptor: ConstraintDescriptor
+  readonly reason: string
+  readonly path: readonly PropertyKey[]
+}
+
+/** Derives a JSON Schema object from one or many public constraint descriptors. */
+export declare const toJsonSchema: <const C extends MaybeMany<Constraint>>(
+  constraints: C,
+  options?: ToJsonSchemaOptions
+) => JsonSchema

package/dist/types/json-schema.d.mts

@@ -0,0 +1,75 @@
+import type {
+  Constraint,
+  ConstraintDescriptor,
+  MaybeMany,
+} from './index.mjs'
+
+/** JSON Schema primitive `type` values used by `toJsonSchema(...)`. */
+export type JsonSchemaTypeName =
+  | 'string'
+  | 'number'
+  | 'integer'
+  | 'boolean'
+  | 'object'
+  | 'array'
+  | 'null'
+
+/** Minimal JSON Schema object shape emitted by the built-in exporter. */
+export interface JsonSchema {
+  readonly $schema?: string;
+  readonly $id?: string;
+  readonly $comment?: string;
+  readonly title?: string;
+  readonly description?: string;
+  readonly format?: string;
+  readonly default?: unknown;
+  readonly examples?: readonly unknown[];
+  readonly deprecated?: boolean;
+  readonly readOnly?: boolean;
+  readonly writeOnly?: boolean;
+  readonly type?: JsonSchemaTypeName | readonly JsonSchemaTypeName[];
+  readonly const?: unknown;
+  readonly enum?: readonly unknown[];
+  readonly allOf?: readonly JsonSchema[];
+  readonly anyOf?: readonly JsonSchema[];
+  readonly oneOf?: readonly JsonSchema[];
+  readonly properties?: Readonly<Record<string, JsonSchema>>;
+  readonly required?: readonly string[];
+  readonly additionalProperties?: boolean | JsonSchema;
+  readonly items?: JsonSchema;
+  readonly prefixItems?: readonly JsonSchema[];
+  readonly minItems?: number;
+  readonly maxItems?: number;
+  readonly minLength?: number;
+  readonly maxLength?: number;
+  readonly pattern?: string;
+  readonly minimum?: number;
+  readonly maximum?: number;
+  readonly multipleOf?: number;
+}
+
+/** Controls how `toJsonSchema(...)` handles constraints that cannot be represented faithfully. */
+export type JsonSchemaExportMode = 'bestEffort' | 'strict'
+
+/** Options for the JSON Schema exporter. */
+export interface ToJsonSchemaOptions {
+  readonly mode?: JsonSchemaExportMode
+}
+
+/** Error thrown by `toJsonSchema(...)` in strict mode when a node cannot be exported faithfully. */
+export declare class JsonSchemaExportError extends Error {
+  constructor(message: string, options: {
+    descriptor: ConstraintDescriptor
+    reason: string
+    path?: readonly PropertyKey[]
+  })
+  readonly descriptor: ConstraintDescriptor
+  readonly reason: string
+  readonly path: readonly PropertyKey[]
+}
+
+/** Derives a JSON Schema object from one or many public constraint descriptors. */
+export declare const toJsonSchema: <const C extends MaybeMany<Constraint>>(
+  constraints: C,
+  options?: ToJsonSchemaOptions
+) => JsonSchema

package/dist/types/json-schema.d.ts

@@ -0,0 +1,75 @@
+import type {
+  Constraint,
+  ConstraintDescriptor,
+  MaybeMany,
+} from './index.js'
+
+/** JSON Schema primitive `type` values used by `toJsonSchema(...)`. */
+export type JsonSchemaTypeName =
+  | 'string'
+  | 'number'
+  | 'integer'
+  | 'boolean'
+  | 'object'
+  | 'array'
+  | 'null'
+
+/** Minimal JSON Schema object shape emitted by the built-in exporter. */
+export interface JsonSchema {
+  readonly $schema?: string;
+  readonly $id?: string;
+  readonly $comment?: string;
+  readonly title?: string;
+  readonly description?: string;
+  readonly format?: string;
+  readonly default?: unknown;
+  readonly examples?: readonly unknown[];
+  readonly deprecated?: boolean;
+  readonly readOnly?: boolean;
+  readonly writeOnly?: boolean;
+  readonly type?: JsonSchemaTypeName | readonly JsonSchemaTypeName[];
+  readonly const?: unknown;
+  readonly enum?: readonly unknown[];
+  readonly allOf?: readonly JsonSchema[];
+  readonly anyOf?: readonly JsonSchema[];
+  readonly oneOf?: readonly JsonSchema[];
+  readonly properties?: Readonly<Record<string, JsonSchema>>;
+  readonly required?: readonly string[];
+  readonly additionalProperties?: boolean | JsonSchema;
+  readonly items?: JsonSchema;
+  readonly prefixItems?: readonly JsonSchema[];
+  readonly minItems?: number;
+  readonly maxItems?: number;
+  readonly minLength?: number;
+  readonly maxLength?: number;
+  readonly pattern?: string;
+  readonly minimum?: number;
+  readonly maximum?: number;
+  readonly multipleOf?: number;
+}
+
+/** Controls how `toJsonSchema(...)` handles constraints that cannot be represented faithfully. */
+export type JsonSchemaExportMode = 'bestEffort' | 'strict'
+
+/** Options for the JSON Schema exporter. */
+export interface ToJsonSchemaOptions {
+  readonly mode?: JsonSchemaExportMode
+}
+
+/** Error thrown by `toJsonSchema(...)` in strict mode when a node cannot be exported faithfully. */
+export declare class JsonSchemaExportError extends Error {
+  constructor(message: string, options: {
+    descriptor: ConstraintDescriptor
+    reason: string
+    path?: readonly PropertyKey[]
+  })
+  readonly descriptor: ConstraintDescriptor
+  readonly reason: string
+  readonly path: readonly PropertyKey[]
+}
+
+/** Derives a JSON Schema object from one or many public constraint descriptors. */
+export declare const toJsonSchema: <const C extends MaybeMany<Constraint>>(
+  constraints: C,
+  options?: ToJsonSchemaOptions
+) => JsonSchema

package/dist/violations.cjs

@@ -0,0 +1,81 @@
+//#region src/violations.ts
+var ROOT_PATH = Object.freeze([]);
+var normalizePath = (path) => path ?? ROOT_PATH;
+var isSamePath = (left, right = ROOT_PATH) => {
+	const normalizedLeft = normalizePath(left);
+	if (normalizedLeft.length !== right.length) return false;
+	return normalizedLeft.every((part, index) => Object.is(part, right[index]));
+};
+var isPathPrefix = (path, prefix) => {
+	if (prefix.length > path.length) return false;
+	return prefix.every((part, index) => Object.is(part, path[index]));
+};
+var createTreeState = (path) => ({
+	path: Object.freeze([...path]),
+	self: [],
+	subtree: [],
+	children: /* @__PURE__ */ new Map()
+});
+var TreeNode = class TreeNode {
+	constructor(state) {
+		this.path = state.path;
+		this.self = new ViolationCollection(state.self);
+		this.subtree = new ViolationCollection(state.subtree);
+		this.children = new Map([...state.children.entries()].map(([key, child]) => [key, new TreeNode(child)]));
+	}
+	at(path) {
+		if (!isPathPrefix(path, this.path)) return;
+		if (path.length === this.path.length) return this;
+		return this.children.get(path[this.path.length])?.at(path);
+	}
+};
+var buildTree = (violations) => {
+	const root = createTreeState(ROOT_PATH);
+	violations.forEach((violation) => {
+		const path = normalizePath(violation.path);
+		root.subtree.push(violation);
+		if (path.length === 0) {
+			root.self.push(violation);
+			return;
+		}
+		let current = root;
+		const currentPath = [];
+		path.forEach((segment, index) => {
+			currentPath.push(segment);
+			let child = current.children.get(segment);
+			if (!child) {
+				child = createTreeState(currentPath);
+				current.children.set(segment, child);
+			}
+			child.subtree.push(violation);
+			if (index === path.length - 1) child.self.push(violation);
+			current = child;
+		});
+	});
+	return new TreeNode(root);
+};
+var ViolationCollection = class ViolationCollection {
+	constructor(violations) {
+		this.violations = [...violations];
+		this.size = this.violations.length;
+	}
+	[Symbol.iterator]() {
+		return this.violations[Symbol.iterator]();
+	}
+	forEach(callback) {
+		this.violations.forEach((violation, index) => callback(violation, index, this));
+	}
+	map(callback) {
+		return this.violations.map((violation, index) => callback(violation, index, this));
+	}
+	at(path) {
+		return new ViolationCollection(this.violations.filter((violation) => isSamePath(violation.path, path)));
+	}
+	tree() {
+		return buildTree(this.violations);
+	}
+};
+var collection = (violations) => new ViolationCollection(violations);
+//#endregion
+exports.ViolationCollection = ViolationCollection;
+exports.collection = collection;

package/dist/violations.d.cts

@@ -0,0 +1,29 @@
+import { Violation } from './types/index.cjs';
+type ViolationPath = readonly PropertyKey[];
+type ViolationTreeState<V extends Violation = Violation> = {
+    readonly path: ViolationPath;
+    readonly self: V[];
+    readonly subtree: V[];
+    readonly children: Map<PropertyKey, ViolationTreeState<V>>;
+};
+declare class TreeNode<V extends Violation = Violation> {
+    readonly path: readonly PropertyKey[];
+    readonly self: ViolationCollection<V>;
+    readonly subtree: ViolationCollection<V>;
+    readonly children: ReadonlyMap<PropertyKey, TreeNode<V>>;
+    constructor(state: ViolationTreeState<V>);
+    at(path: readonly PropertyKey[]): TreeNode<V> | undefined;
+}
+export declare class ViolationCollection<V extends Violation = Violation> implements Iterable<V> {
+    readonly size: number;
+    private readonly violations;
+    constructor(violations: readonly V[]);
+    [Symbol.iterator](): Iterator<V>;
+    forEach(callback: (violation: V, index: number, collection: ViolationCollection<V>) => void): void;
+    map<T>(callback: (violation: V, index: number, collection: ViolationCollection<V>) => T): T[];
+    at(path: readonly PropertyKey[]): ViolationCollection<V>;
+    tree(): TreeNode<V>;
+}
+export type ViolationTreeNode<V extends Violation = Violation> = TreeNode<V>;
+export declare const collection: <V extends Violation>(violations: readonly V[]) => ViolationCollection<V>;
+export {};

package/dist/violations.d.mts

@@ -0,0 +1,29 @@
+import { Violation } from './types/index.mjs';
+type ViolationPath = readonly PropertyKey[];
+type ViolationTreeState<V extends Violation = Violation> = {
+    readonly path: ViolationPath;
+    readonly self: V[];
+    readonly subtree: V[];
+    readonly children: Map<PropertyKey, ViolationTreeState<V>>;
+};
+declare class TreeNode<V extends Violation = Violation> {
+    readonly path: readonly PropertyKey[];
+    readonly self: ViolationCollection<V>;
+    readonly subtree: ViolationCollection<V>;
+    readonly children: ReadonlyMap<PropertyKey, TreeNode<V>>;
+    constructor(state: ViolationTreeState<V>);
+    at(path: readonly PropertyKey[]): TreeNode<V> | undefined;
+}
+export declare class ViolationCollection<V extends Violation = Violation> implements Iterable<V> {
+    readonly size: number;
+    private readonly violations;
+    constructor(violations: readonly V[]);
+    [Symbol.iterator](): Iterator<V>;
+    forEach(callback: (violation: V, index: number, collection: ViolationCollection<V>) => void): void;
+    map<T>(callback: (violation: V, index: number, collection: ViolationCollection<V>) => T): T[];
+    at(path: readonly PropertyKey[]): ViolationCollection<V>;
+    tree(): TreeNode<V>;
+}
+export type ViolationTreeNode<V extends Violation = Violation> = TreeNode<V>;
+export declare const collection: <V extends Violation>(violations: readonly V[]) => ViolationCollection<V>;
+export {};

package/dist/violations.d.ts

@@ -1,4 +1,4 @@
-import { Violation } from '../types';
+import { Violation } from './types/index.js';
 type ViolationPath = readonly PropertyKey[];
 type ViolationTreeState<V extends Violation = Violation> = {
     readonly path: ViolationPath;

package/dist/violations.mjs

@@ -0,0 +1,80 @@
+//#region src/violations.ts
+var ROOT_PATH = Object.freeze([]);
+var normalizePath = (path) => path ?? ROOT_PATH;
+var isSamePath = (left, right = ROOT_PATH) => {
+	const normalizedLeft = normalizePath(left);
+	if (normalizedLeft.length !== right.length) return false;
+	return normalizedLeft.every((part, index) => Object.is(part, right[index]));
+};
+var isPathPrefix = (path, prefix) => {
+	if (prefix.length > path.length) return false;
+	return prefix.every((part, index) => Object.is(part, path[index]));
+};
+var createTreeState = (path) => ({
+	path: Object.freeze([...path]),
+	self: [],
+	subtree: [],
+	children: /* @__PURE__ */ new Map()
+});
+var TreeNode = class TreeNode {
+	constructor(state) {
+		this.path = state.path;
+		this.self = new ViolationCollection(state.self);
+		this.subtree = new ViolationCollection(state.subtree);
+		this.children = new Map([...state.children.entries()].map(([key, child]) => [key, new TreeNode(child)]));
+	}
+	at(path) {
+		if (!isPathPrefix(path, this.path)) return;
+		if (path.length === this.path.length) return this;
+		return this.children.get(path[this.path.length])?.at(path);
+	}
+};
+var buildTree = (violations) => {
+	const root = createTreeState(ROOT_PATH);
+	violations.forEach((violation) => {
+		const path = normalizePath(violation.path);
+		root.subtree.push(violation);
+		if (path.length === 0) {
+			root.self.push(violation);
+			return;
+		}
+		let current = root;
+		const currentPath = [];
+		path.forEach((segment, index) => {
+			currentPath.push(segment);
+			let child = current.children.get(segment);
+			if (!child) {
+				child = createTreeState(currentPath);
+				current.children.set(segment, child);
+			}
+			child.subtree.push(violation);
+			if (index === path.length - 1) child.self.push(violation);
+			current = child;
+		});
+	});
+	return new TreeNode(root);
+};
+var ViolationCollection = class ViolationCollection {
+	constructor(violations) {
+		this.violations = [...violations];
+		this.size = this.violations.length;
+	}
+	[Symbol.iterator]() {
+		return this.violations[Symbol.iterator]();
+	}
+	forEach(callback) {
+		this.violations.forEach((violation, index) => callback(violation, index, this));
+	}
+	map(callback) {
+		return this.violations.map((violation, index) => callback(violation, index, this));
+	}
+	at(path) {
+		return new ViolationCollection(this.violations.filter((violation) => isSamePath(violation.path, path)));
+	}
+	tree() {
+		return buildTree(this.violations);
+	}
+};
+var collection = (violations) => new ViolationCollection(violations);
+//#endregion
+export { ViolationCollection, collection };

package/docs/RELEASING.md

@@ -0,0 +1,66 @@
+# Releasing @modulify/validator
+
+Use Node.js 22.14+ or 24+ and the Yarn version pinned in `package.json`.
+Install dependencies with `yarn install --immutable`.
+
+The repository uses `@modulify/conventional-release` to calculate the version,
+update `package.json` and `CHANGELOG.md`, and create a release commit with an
+annotated `v<version>` tag. npm publication and GitHub Releases belong to CI.
+
+Preview a release without changing files, commits, or tags:
+
+```sh
+yarn release:dry
+yarn release:dry --prerelease rc
+yarn release:dry --release-as minor
+```
+
+Automatic version recommendations below 1.0 follow pre-major semantics:
+breaking changes advance the minor version; features and fixes advance the patch.
+Explicit `--release-as major` produces 1.0.0. Release configuration lives in
+`release.config.mjs`; dependencies are installed before releasing, so the version
+bump does not rerun installation or update the lockfile.
+
+## GitHub Actions
+
+Start the `Release` workflow manually:
+
+- `release`: `auto`, `patch`, `minor`, or `major`;
+- `prerelease`: `none`, `alpha`, `beta`, or `rc`;
+- `npm_tag`: `auto` selects `latest` for stable releases and the prerelease channel
+  otherwise; an explicit dist-tag can override it.
+
+Stable releases run only from `main`. Prereleases may run from other branches,
+but cannot publish to `latest`. Releases are serialized across branches.
+
+CI runs lint, strict type checks, runtime and type tests, and packed consumer
+checks before creating the release. It atomically pushes the release commit and
+its tag. A separate job checks out that exact tag, repeats the checks, builds the
+package, and publishes through npm OIDC. A GitHub Release is created after npm
+publication succeeds; prereleases are marked accordingly.
+
+If publication or GitHub Release creation fails after the tag was pushed, use
+GitHub Actions **Re-run failed jobs** on the original run. Publication checks the
+registry for the exact version and skips a version already published. Registry
+lookup errors stop the job. Starting a new workflow run prepares another release.
+
+## npm Trusted Publisher
+
+The package already has this trusted publisher configured (verified 2026-09-26):
+
+| Field | Value |
+| --- | --- |
+| Provider | GitHub Actions |
+| Organization | `modulify` |
+| Repository | `validator` |
+| Workflow filename | `release.yml` |
+| Allowed actions | `npm publish`, `npm stage publish` |
+
+Keep the workflow filename aligned with this package-level configuration.
+The publishing job uses a GitHub-hosted runner, Node.js 24, npm 11.5.1 or newer,
+and `id-token: write`. No `NPM_TOKEN` or `NODE_AUTH_TOKEN` secret is used for
+publication. npm generates provenance automatically for this public package
+and repository. See [npm Trusted Publishing](https://docs.npmjs.com/trusted-publishers/).
+
+A local authenticated npm session is separate from CI OIDC. Release previews
+and repository-local versioning do not require npm authentication.

package/docs/en/00-index.md

@@ -9,6 +9,8 @@
 - [AI Reference](./07-ai-reference.md) - Compact contract summary for AI agents, tooling, and quick lookup of stable library semantics.
 - [Violation Code Types](./08-violation-code-types.md) - Detailed guide to `ViolationCodeRegistry`, `ViolationCode`, literal code preservation in descriptors, and external registry augmentation.
 
+- [Migration From 0.2.1](./09-migration.md) - Breaking changes, renamed types, and updated validation contracts.
+
 ## Translations
 
 - [Russian](../ru/00-index.md)

package/docs/en/01-shape-api.md

@@ -49,6 +49,8 @@ Each field in the descriptor may contain:
 - an array of constraints that run sequentially;
 - another structural validator such as `shape(...)`, `each(...)`, `tuple(...)`, `record(...)`, `union(...)`, or `discriminatedUnion(...)`.
 
+For assertion arrays, sequencing is stage-aware: guard assertions establish the field domain first, and refinement assertions must be compatible with that domain.
+
 That means object validation stays aligned with the rest of the library:
 
 - field-level checks reuse the same assertions and combinators;
@@ -79,6 +81,11 @@ Runtime behavior:
 - nested violations are reported on the field path;
 - unknown keys are allowed by default.
 
+Type-level behavior:
+
+- `[isString, hasLength({ min: 8 })]` is valid;
+- `[isNumber, hasLength({ min: 8 })]` is rejected by TypeScript before runtime.
+
 ## Unknown Keys
 
 Shapes have two unknown-key modes:
@@ -190,13 +197,36 @@ Shapes can express cross-field invariants without introducing a second schema la
 
 ### `refine(...)`
 
-`refine(...)` adds a synchronous object-level rule that runs only after the base shape has already validated successfully as an object.
+`refine(...)` adds an async-first object-level rule that runs only after the base shape has already validated successfully as an object.
+
+```typescript
+const registration = shape({
+  email: isString,
+}).refine(async value => {
+  const taken = await users.has(value.email)
+
+  return taken
+    ? [{ path: ['email'], code: 'user.email.taken' }]
+    : []
+})
+```
+
+`refine(...)` is intentionally thin:
+
+- it accepts sync or async callbacks;
+- it returns `[]`, `null`, or `undefined` when the rule passes;
+- it returns one issue or an array of issues when it fails;
+- `path` is relative to the current shape and defaults to `[]`;
+- `value` is optional and defaults to the object value at that relative path;
+- `code` stays machine-readable.
+
+If you need an explicitly sync-safe object rule for `validate.sync(...)`, use `refine.sync(...)`:
 
 ```typescript
 const registration = shape({
   password: isString,
   confirmPassword: isString,
-}).refine(value => {
+}).refine.sync(value => {
   return value.password === value.confirmPassword
     ? []
     : [{
@@ -207,14 +237,7 @@ const registration = shape({
 })
 ```
 
-`refine(...)` is intentionally thin:
-
-- it is sync-only;
-- it returns `[]`, `null`, or `undefined` when the rule passes;
-- it returns one issue or an array of issues when it fails;
-- `path` is relative to the current shape and defaults to `[]`;
-- `value` is optional and defaults to the object value at that relative path;
-- `code` stays machine-readable.
+`validate.sync(...)`, `matches.sync(...)`, and `shape.check(...)` throw explicitly if they encounter an async `refine(...)` callback.
 
 Produced violations use:
 
@@ -243,6 +266,8 @@ const registration = shape({
 
 This shows up later in `describe(...)` under the shape `rules` array.
 
+Rules registered through async-first `refine(...)` are marked with `async: true` in that descriptor array.
+
 ### `fieldsMatch(...)`
 
 `fieldsMatch(...)` is a small helper for the common confirmation-field case.

package/docs/en/02-metadata-and-introspection.md

@@ -182,7 +182,8 @@ Instead, shapes keep lightweight rule descriptors in `rules`.
 Built-in examples:
 
 - `fieldsMatch(...)` produces a compact `fieldsMatch` rule descriptor;
-- `refine(...)` can accept a custom compact rule descriptor object.
+- `refine(...)` can accept a custom compact rule descriptor object;
+- async-first `refine(...)` rules are marked with `async: true`.
 
 This keeps the public descriptor tree stable and serializable enough for tooling, while avoiding the impossible task of serializing arbitrary callbacks.
 

package/docs/en/03-violations.md

@@ -120,7 +120,7 @@ This is one of the reasons the library can stay adapter-friendly without stringi
 `validate(...)` and `validate.sync(...)` return:
 
 ```typescript
-type ValidationTuple<T> =
+type ValidationResult<T> =
   | [ok: true, validated: T, violations: []]
   | [ok: false, validated: unknown, violations: Violation[]]
 ```

package/docs/en/04-json-schema-export.md

@@ -69,6 +69,9 @@ Supported practical mappings include:
 
 - `isString` -> `type: 'string'`
 - `isNumber` -> `type: 'number'`
+- `isFiniteNumber` -> `type: 'number'`
+- `isInteger` -> `type: 'integer'`
+- `isSafeInteger` -> `type: 'integer'`, `minimum: Number.MIN_SAFE_INTEGER`, `maximum: Number.MAX_SAFE_INTEGER`
 - `isBoolean` -> `type: 'boolean'`
 - `isNull` -> `type: 'null'`
 - `isEmail` -> `type: 'string'` plus `format: 'email'`
@@ -202,6 +205,8 @@ Important examples:
 
 The exporter keeps these boundaries explicit instead of guessing.
 
+`isValidDate`, `isError`, `isRegExp`, and `isPromiseLike` describe runtime values without a faithful JSON Schema representation. Strict mode throws `JsonSchemaExportError`; best-effort mode emits an unconstrained node. JSON numeric values are finite, so `isFiniteNumber` needs no additional schema keyword.
+
 ## Relationship To `describe(...)`
 
 `toJsonSchema(...)` is downstream from `describe(...)`.