@schema-ts/core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,412 @@
+type Schema = {
+    $schema?: string;
+    $id?: string;
+    $anchor?: string;
+    $dynamicAnchor?: string;
+    $ref?: string;
+    $dynamicRef?: string;
+    $defs?: Record<string, Schema>;
+    $comment?: string;
+    title?: string;
+    description?: string;
+    default?: unknown;
+    deprecated?: boolean;
+    readOnly?: boolean;
+    writeOnly?: boolean;
+    examples?: unknown[];
+    type?: string | string[];
+    enum?: unknown[];
+    const?: unknown;
+    multipleOf?: number;
+    maximum?: number;
+    exclusiveMaximum?: number;
+    minimum?: number;
+    exclusiveMinimum?: number;
+    maxLength?: number;
+    minLength?: number;
+    pattern?: string;
+    format?: string;
+    maxItems?: number;
+    minItems?: number;
+    uniqueItems?: boolean;
+    maxContains?: number;
+    minContains?: number;
+    maxProperties?: number;
+    minProperties?: number;
+    required?: string[];
+    dependentRequired?: Record<string, string[]>;
+    allOf?: Schema[];
+    anyOf?: Schema[];
+    oneOf?: Schema[];
+    not?: Schema;
+    if?: Schema;
+    then?: Schema;
+    else?: Schema;
+    dependentSchemas?: Record<string, Schema>;
+    prefixItems?: Schema[];
+    items?: Schema;
+    contains?: Schema;
+    properties?: Record<string, Schema>;
+    patternProperties?: Record<string, Schema>;
+    additionalProperties?: boolean | Schema;
+    propertyNames?: Schema;
+    unevaluatedItems?: Schema;
+    unevaluatedProperties?: Schema;
+    contentEncoding?: string;
+    contentMediaType?: string;
+    contentSchema?: Schema;
+    [key: string]: unknown;
+};
+/**
+ * Result of schema validation
+ */
+interface Output {
+    valid: boolean;
+    keywordLocation: string;
+    instanceLocation: string;
+    absoluteKeywordLocation?: string;
+    absoluteInstanceLocation?: string;
+    error?: string;
+    errors: Output[];
+    annotations?: Output[];
+}
+/**
+ * Structured error message for i18n support.
+ * Used internally by ErrorFormatter to produce localized error strings.
+ */
+interface ErrorMessage {
+    key: string;
+    params?: Record<string, unknown>;
+}
+/**
+ * JSON Schema type values
+ */
+type SchemaType = "string" | "number" | "integer" | "boolean" | "object" | "array" | "null" | "unknown";
+
+declare function matchSchemaType(value: unknown, type: string): boolean;
+declare function detectSchemaType(value: unknown): string;
+declare function parseJsonPointer(jsonPointer: string): string[];
+declare function getJsonPointer(obj: unknown, jsonPointer: string): unknown;
+declare function removeJsonPointer(obj: unknown, jsonPointer: string): boolean;
+declare function setJsonPointer(obj: unknown, jsonPointer: string, value: unknown): boolean;
+declare function get(obj: unknown, path: string[]): unknown;
+/**
+ * Deep equality comparison for two values.
+ * Supports primitives, arrays, plain objects, Date, Map, Set, and RegExp.
+ */
+declare function deepEqual(a: unknown, b: unknown): boolean;
+declare function jsonPointerEscape(str: string): string;
+declare function jsonPointerUnescape(str: string): string;
+declare function jsonPointerJoin(base: string, token: string): string;
+/**
+ * Convert a relative path to an absolute path
+ * @param nodePath The node's jsonPointer, e.g. "/a/b"
+ * @param relativePath Relative path, e.g. "/c" means /a/b/c
+ */
+declare function resolveAbsolutePath(nodePath: string, relativePath: string): string;
+/**
+ * Safely test a regex pattern against a string.
+ * Returns false if the pattern is invalid instead of throwing.
+ * Uses caching to avoid creating RegExp objects repeatedly.
+ */
+declare function safeRegexTest(pattern: string, value: string): boolean;
+
+interface StringFormatValidatorInterface {
+    validate(format: string, value: string): boolean;
+}
+declare class StringFormatValidator implements StringFormatValidatorInterface {
+    validate(format: string, value: string): boolean;
+    private isDateTime;
+    private isDate;
+    private isEmail;
+    private isHostname;
+    private isIPv4;
+    private isIPv6;
+    private isUri;
+    private isUuid;
+    private isDuration;
+}
+declare const stringFormatValidator: StringFormatValidator;
+
+/**
+ * Default error message templates for i18n support.
+ * Keys are translation keys, values are English templates with {param} placeholders.
+ */
+declare const MESSAGES: Record<string, string>;
+/**
+ * Formats ErrorMessage to string for Output.error.
+ * Provide a custom implementation for i18n support.
+ */
+type ErrorFormatter = (msg: ErrorMessage) => string;
+/**
+ * Default error formatter: looks up template from MESSAGES and interpolates params.
+ */
+declare const defaultErrorFormatter: ErrorFormatter;
+
+interface ValidatorOptions {
+    fastFail?: boolean;
+    shallow?: boolean;
+}
+interface ValidatorConfig {
+    formatValidator?: StringFormatValidatorInterface;
+    errorFormatter?: ErrorFormatter;
+}
+declare class Validator {
+    private formatValidator;
+    private errorFormatter;
+    constructor(config?: ValidatorConfig);
+    /**
+     * Format an ErrorMessage to a localized string.
+     */
+    formatError(msg: ErrorMessage): string;
+    validate(schema: Schema, value: unknown, keywordLocation?: string, instanceLocation?: string, options?: ValidatorOptions): Output;
+    private validateNumber;
+    private validateString;
+    private validateArray;
+    private validateObject;
+    private detectType;
+    private checkType;
+    private validateFormat;
+}
+/**
+ * Validates a value against a JSON Schema.
+ * Support multiple JSON Schema drafts (04, 07, 2019-09, 2020-12) by normalizing
+ * the schema to draft 2020-12 format before validation.
+ */
+declare function validateSchema(schema: Schema | unknown, value: unknown, instancePath?: string, schemaPath?: string, fastFail?: boolean): Output;
+
+/**
+ * Represents a node in the schema tree.
+ * Each node corresponds to a location in both the schema and the instance data.
+ */
+interface FieldNode {
+    type: SchemaType;
+    schema: Schema;
+    originalSchema: Schema;
+    error?: Output;
+    children?: FieldNode[];
+    instanceLocation: string;
+    keywordLocation: string;
+    version: number;
+    dependencies?: Set<string>;
+    canRemove: boolean;
+    canAdd: boolean;
+}
+type SchemaChangeEvent = {
+    type: "schema" | "value" | "error";
+    path: string;
+};
+declare class SchemaRuntime {
+    private validator;
+    private watchers;
+    private globalWatchers;
+    private dependentsMap;
+    private updatingNodes;
+    root: FieldNode;
+    private value;
+    private version;
+    private rootSchema;
+    /**
+     * Create a new SchemaRuntime instance.
+     *
+     * @param validator - The validator instance for schema validation
+     * @param schema - The JSON Schema definition (will be normalized and dereferenced)
+     * @param value - The initial data value to manage
+     *
+     * @example
+     * const validator = new Validator();
+     * const schema = { type: "object", properties: { name: { type: "string" } } };
+     * const runtime = new SchemaRuntime(validator, schema, { name: "Alice" });
+     */
+    constructor(validator: Validator, schema: Schema | unknown, value: unknown);
+    /**
+     * Collect all dependencies for a node's schema.
+     *
+     * Key insight: We extract paths from condition keywords (if, oneOf, anyOf)
+     * using extractReferencedPaths, but for then/else/allOf keywords, we recursively
+     * call collectDependencies to ensure proper dependency isolation between
+     * parent and child nodes.
+     */
+    private collectDependencies;
+    /**
+     * Register a node as dependent on a path
+     */
+    private registerDependent;
+    /**
+     * Unregister a node from a dependency path
+     */
+    private unregisterDependent;
+    /**
+     * Unregister all dependencies for a node and its children.
+     * Note: Does NOT clean up external watchers - callers are responsible
+     * for calling unsubscribe() when they no longer need updates.
+     */
+    private unregisterNodeDependencies;
+    /**
+     * Create an empty FieldNode with default values.
+     */
+    private createEmptyNode;
+    /**
+     * Reconcile the tree starting from the specified path.
+     * Uses findNearestExistingNode to find the target node (or parent if path doesn't exist).
+     * Only rebuilds the affected subtree, not the entire tree.
+     */
+    private reconcile;
+    /**
+     * Get the current version number.
+     * The version increments on every notify call (value, schema, or error changes).
+     * Useful for detecting if the runtime state has changed.
+     *
+     * @returns The current version number
+     */
+    getVersion(): number;
+    /**
+     * Subscribe to changes at a specific path.
+     * The callback is invoked when the value, schema, or error at the path changes.
+     *
+     * @param path - The JSON Pointer path to watch (e.g., "/user/name", "" for root)
+     * @param cb - Callback function invoked with the change event
+     * @returns Unsubscribe function to remove the listener
+     *
+     * @example
+     * const unsubscribe = runtime.subscribe("/name", (event) => {
+     *   console.log(`${event.type} changed at ${event.path}`);
+     * });
+     * // Later: unsubscribe();
+     */
+    subscribe(path: string, cb: (e: SchemaChangeEvent) => void): () => void;
+    /**
+     * Subscribe to all events in the runtime.
+     * The callback is invoked for any change at any path.
+     *
+     * @param cb - Callback function invoked with every change event
+     * @returns Unsubscribe function to remove the listener
+     */
+    subscribeAll(cb: (e: SchemaChangeEvent) => void): () => void;
+    /**
+     * Emit a change event to all relevant subscribers.
+     * Increments the version number and notifies both path-specific and global watchers.
+     *
+     * @param event - The change event containing type and path
+     */
+    notify(event: SchemaChangeEvent): void;
+    /**
+     * Update the entire schema.
+     * This triggers a full rebuild of the node tree while preserving the current value.
+     */
+    setSchema(schema: Schema | unknown): void;
+    /**
+     * Get the value at a specific path.
+     *
+     * @param path - The JSON Pointer path (e.g., "/user/name", "" for root)
+     * @returns The value at the path, or undefined if not found
+     *
+     * @example
+     * runtime.getValue(""); // returns entire root value
+     * runtime.getValue("/name"); // returns value at /name
+     */
+    getValue(path: string): unknown;
+    /**
+     * Remove a node at the specified path.
+     * This deletes the value from the data structure (array splice or object delete).
+     * @param path - The path to remove
+     * @returns true if successful, false if the path cannot be removed
+     */
+    removeValue(path: string): boolean;
+    /**
+     * Add a new child to an array or object at the specified parent path.
+     * For arrays, appends a new item with default value based on items schema.
+     * For objects, adds a new property with the given key and default value based on additionalProperties schema.
+     * @param parentPath - The path to the parent array or object
+     * @param key - For objects: the property key. For arrays: optional, ignored (appends to end)
+     * @param initialValue - Optional initial value to set. If not provided, uses default from schema.
+     * @returns true if successful, false if cannot add
+     */
+    addValue(parentPath: string, key?: string, initialValue?: unknown): boolean;
+    /**
+     * Set the value at a specific path.
+     * Creates intermediate containers (objects/arrays) as needed.
+     * Triggers reconciliation and notifies subscribers.
+     *
+     * @param path - The JSON Pointer path (e.g., "/user/name", "" for root)
+     * @param value - The new value to set
+     * @returns true if successful, false if the path cannot be set
+     *
+     * @example
+     * runtime.setValue("/name", "Bob"); // set name to "Bob"
+     * runtime.setValue("", { name: "Alice" }); // replace entire root value
+     */
+    setValue(path: string, value: unknown): boolean;
+    /**
+     * Find the FieldNode at a specific path.
+     * Returns the node tree representation that includes schema, type, error, and children.
+     *
+     * @param path - The JSON Pointer path (e.g., "/user/name", "" for root)
+     * @returns The FieldNode at the path, or undefined if not found
+     *
+     * @example
+     * const node = runtime.findNode("/name");
+     * console.log(node?.schema, node?.type, node?.error);
+     */
+    findNode(path: string): FieldNode | undefined;
+    private findNearestExistingNode;
+    /**
+     * Build/update a FieldNode in place.
+     * Updates the node's schema, type, error, and children based on the current value.
+     * @param schema - Optional. If provided, updates node.originalSchema. Otherwise uses existing.
+     */
+    private buildNode;
+}
+
+/**
+ * JSON Schema draft version definitions and detection utilities.
+ */
+/**
+ * Supported JSON Schema draft versions.
+ */
+type SchemaDraft = "draft-04" | "draft-07" | "draft-2019-09" | "draft-2020-12";
+/**
+ * Standard $schema URI patterns for each draft version.
+ */
+declare const DRAFT_URIS: Record<SchemaDraft, string[]>;
+/**
+ * Detect the JSON Schema draft version from a schema.
+ * Detection is based on:
+ * 1. The $schema URI if present
+ * 2. Heuristics based on keywords used
+ *
+ * @param schema - The schema to detect the version of (can be object, boolean, or unknown)
+ * @returns The detected draft version, defaults to "draft-2020-12" if unknown
+ */
+declare function detectSchemaDraft(schema: unknown): SchemaDraft;
+
+/**
+ * Schema normalizer that transforms older JSON Schema drafts to draft-2020-12.
+ *
+ * This allows the validator to only implement draft-2020-12 semantics
+ * while still supporting schemas written for older drafts.
+ */
+
+interface NormalizerOptions {
+    /**
+     * Source draft version. If not specified, will be auto-detected.
+     */
+    sourceDraft?: SchemaDraft;
+}
+/**
+ * Normalize a JSON Schema from any supported draft to draft-2020-12 format.
+ *
+ * Transformations performed:
+ * - `id` → `$id` (draft-04)
+ * - Boolean `exclusiveMaximum`/`exclusiveMinimum` → numeric values (draft-04)
+ * - Array `items` + `additionalItems` → `prefixItems` + `items` (draft-04/07/2019-09)
+ * - `dependencies` → `dependentRequired`/`dependentSchemas` (draft-04/07)
+ * - `$recursiveRef`/`$recursiveAnchor` → `$dynamicRef`/`$dynamicAnchor` (draft-2019-09)
+ *
+ * @param schema - The schema to normalize (can be object, boolean, or unknown)
+ * @param options - Optional configuration
+ * @returns A new schema object in draft-2020-12 format (always returns an object)
+ */
+declare function normalizeSchema(schema: unknown, options?: NormalizerOptions): Schema;
+
+export { DRAFT_URIS, type ErrorFormatter, type ErrorMessage, type FieldNode, MESSAGES, type NormalizerOptions, type Output, type Schema, type SchemaChangeEvent, type SchemaDraft, SchemaRuntime, type SchemaType, StringFormatValidator, type StringFormatValidatorInterface, Validator, type ValidatorConfig, type ValidatorOptions, deepEqual, defaultErrorFormatter, detectSchemaDraft, detectSchemaType, get, getJsonPointer, jsonPointerEscape, jsonPointerJoin, jsonPointerUnescape, matchSchemaType, normalizeSchema, parseJsonPointer, removeJsonPointer, resolveAbsolutePath, safeRegexTest, setJsonPointer, stringFormatValidator, validateSchema };