@json-eval-rs/webcore 0.0.44 → 0.0.45

package/dist/index.d.ts

@@ -0,0 +1,520 @@
+/**
+ * @json-eval-rs/webcore
+ * High-level JavaScript API for JSON Eval RS WASM bindings
+ *
+ * This package provides a clean, ergonomic API that works with any WASM target:
+ */
+/**
+ * Get the library version from the WASM module
+ * @param wasmModule - WASM module
+ * @returns Version string
+ */
+export declare function getVersion(wasmModule: any): string;
+/**
+ * Return format for path-based methods
+ */
+export declare enum ReturnFormat {
+    /** Nested object preserving the path hierarchy (default) */
+    Nested = 0,
+    /** Flat object with dotted keys */
+    Flat = 1,
+    /** Array of values in the order of requested paths */
+    Array = 2
+}
+/**
+ * Validation error for a specific field
+ */
+export interface ValidationError {
+    /** Field path with the error */
+    path: string;
+    /** Type of validation rule that failed (e.g., 'required', 'min', 'max', 'pattern') */
+    rule_type: string;
+    /** Error message */
+    message: string;
+    /** Optional error code */
+    code?: string;
+    /** Optional regex pattern (for pattern validation errors) */
+    pattern?: string;
+    /** Optional field value that failed validation (as string) */
+    field_value?: string;
+    /** Optional additional data context for the error */
+    data?: any;
+}
+/**
+ * Result of validation operation
+ */
+export interface ValidationResult {
+    /** Whether any validation errors occurred */
+    has_error: boolean;
+    /** Array of validation errors */
+    errors: ValidationError[];
+}
+/**
+ * Dependent field change from evaluateDependents
+ */
+export interface DependentChange {
+    /** Path of the dependent field (in dot notation) */
+    $ref: string;
+    /** Schema definition of the changed field */
+    $field?: any;
+    /** Schema definition of the parent field */
+    $parentField: any;
+    /** Whether this is a transitive dependency */
+    transitive: boolean;
+    /** If true, the field was cleared */
+    clear?: boolean;
+    /** New value of the field (if changed) */
+    value?: any;
+}
+/**
+ * Options for creating a JSONEval instance
+ */
+export interface JSONEvalOptions {
+    /** JSON schema object */
+    schema: any;
+    /** Optional context data */
+    context?: any;
+    /** Optional initial data */
+    data?: any;
+    /** If true, schema is treated as a cache key */
+    fromCache?: boolean;
+}
+/**
+ * Options for validation
+ */
+export interface ValidateOptions {
+    /** JSON data to validate */
+    data: any;
+    /** Optional context data */
+    context?: any;
+}
+/**
+ * Options for evaluation
+ */
+export interface EvaluateOptions {
+    /** JSON data to evaluate */
+    data: any;
+    /** Optional context data */
+    context?: any;
+    /** Optional array of paths for selective evaluation */
+    paths?: string[];
+}
+/**
+ * Options for evaluating dependents
+ */
+export interface EvaluateDependentsOptions {
+    /** Array of field paths that changed */
+    changedPaths: string[];
+    /** Updated JSON data */
+    data?: any;
+    /** Optional context data */
+    context?: any;
+    /** If true, performs full evaluation after processing dependents */
+    reEvaluate?: boolean;
+}
+/**
+ * Options for getting evaluated schema
+ */
+export interface GetEvaluatedSchemaOptions {
+    /** Whether to skip layout resolution */
+    skipLayout?: boolean;
+}
+/**
+ * Options for getting a value by path from evaluated schema
+ */
+export interface GetValueByPathOptions {
+    /** Dotted path to the value */
+    path: string;
+    /** Whether to skip layout resolution */
+    skipLayout?: boolean;
+}
+/**
+ * Options for getting values by multiple paths from evaluated schema
+ */
+export interface GetValueByPathsOptions {
+    /** Array of dotted paths to retrieve */
+    paths: string[];
+    /** Whether to skip layout resolution */
+    skipLayout?: boolean;
+    /** Return format (Nested, Flat, or Array) */
+    format?: ReturnFormat;
+}
+/**
+ * Options for getting a value by path from schema
+ */
+export interface GetSchemaByPathOptions {
+    /** Dotted path to the value */
+    path: string;
+}
+/**
+ * Options for getting values by multiple paths from schema
+ */
+export interface GetSchemaByPathsOptions {
+    /** Array of dotted paths to retrieve */
+    paths: string[];
+    /** Return format (Nested, Flat, or Array) */
+    format?: ReturnFormat;
+}
+/**
+ * Options for reloading schema
+ */
+export interface ReloadSchemaOptions {
+    /** New JSON schema */
+    schema: any;
+    /** Optional new context */
+    context?: any;
+    /** Optional new data */
+    data?: any;
+}
+/**
+ * Cache statistics
+ */
+export interface CacheStats {
+    /** Number of cache hits */
+    hits: number;
+    /** Number of cache misses */
+    misses: number;
+    /** Number of cached entries */
+    entries: number;
+}
+/**
+ * Options for evaluating a subform
+ */
+export interface EvaluateSubformOptions {
+    /** Path to the subform */
+    subformPath: string;
+    /** JSON data to evaluate */
+    data: any;
+    /** Optional context data */
+    context?: any;
+    /** Optional array of paths to evaluate */
+    paths?: string[];
+}
+/**
+ * Options for validating a subform
+ */
+export interface ValidateSubformOptions {
+    /** Path to the subform */
+    subformPath: string;
+    /** JSON data to validate */
+    data: any;
+    /** Optional context data */
+    context?: any;
+}
+/**
+ * Options for evaluating dependents in a subform
+ */
+export interface EvaluateDependentsSubformOptions {
+    /** Path to the subform */
+    subformPath: string;
+    /** Array of field paths that changed */
+    changedPaths: string[];
+    /** Updated JSON data */
+    data?: any;
+    /** Optional context data */
+    context?: any;
+    /** If true, performs full evaluation after processing dependents */
+    reEvaluate?: boolean;
+}
+/**
+ * Options for resolving layout in a subform
+ */
+export interface ResolveLayoutSubformOptions {
+    /** Path to the subform */
+    subformPath: string;
+    /** Whether to evaluate after resolving layout */
+    evaluate?: boolean;
+}
+/**
+ * Options for getting evaluated schema from a subform
+ */
+export interface GetEvaluatedSchemaSubformOptions {
+    /** Path to the subform */
+    subformPath: string;
+    /** Whether to resolve layout */
+    resolveLayout?: boolean;
+}
+/**
+ * Options for getting schema value from a subform
+ */
+export interface GetSchemaValueSubformOptions {
+    /** Path to the subform */
+    subformPath: string;
+}
+/**
+ * Options for getting evaluated schema by path from a subform
+ */
+export interface GetEvaluatedSchemaByPathSubformOptions {
+    /** Path to the subform */
+    subformPath: string;
+    /** Dotted path to the value within the subform */
+    schemaPath: string;
+    /** Whether to skip layout resolution */
+    skipLayout?: boolean;
+}
+/**
+ * Options for getting evaluated schema by multiple paths from a subform
+ */
+export interface GetEvaluatedSchemaByPathsSubformOptions {
+    /** Path to the subform */
+    subformPath: string;
+    /** Array of dotted paths to retrieve within the subform */
+    schemaPaths: string[];
+    /** Whether to skip layout resolution */
+    skipLayout?: boolean;
+    /** Return format (Nested, Flat, or Array) */
+    format?: ReturnFormat;
+}
+/**
+ * Options for getting schema by path from a subform
+ */
+export interface GetSchemaByPathSubformOptions {
+    /** Path to the subform */
+    subformPath: string;
+    /** Dotted path to the value within the subform */
+    schemaPath: string;
+}
+/**
+ * Options for getting schema by multiple paths from a subform
+ */
+export interface GetSchemaByPathsSubformOptions {
+    /** Path to the subform */
+    subformPath: string;
+    /** Array of dotted paths to retrieve within the subform */
+    schemaPaths: string[];
+    /** Return format (Nested, Flat, or Array) */
+    format?: ReturnFormat;
+}
+/**
+ * Options for compiling and running logic
+ */
+export interface CompileAndRunLogicOptions {
+    /** Logic expression as string or object */
+    logicStr: string | object;
+    /** Optional data context */
+    data?: any;
+    /** Optional context data */
+    context?: any;
+}
+/**
+ * JSONEval - High-level JavaScript API for JSON Eval RS
+ *
+ * This is an internal abstraction layer. Use specific packages instead:
+ * - @json-eval-rs/bundler (for bundlers like Webpack, Vite, Next.js)
+ * - @json-eval-rs/vanilla (for direct browser usage)
+ * - @json-eval-rs/node (for Node.js/SSR)
+ *
+ * @example
+ * ```js
+ * import { JSONEval } from '@json-eval-rs/webcore';
+ *
+ * const evaluator = new JSONEval({
+ *   schema: { type: 'object', properties: { ... } }
+ * });
+ *
+ * await evaluator.init();
+ * const result = await evaluator.validate({ data: { name: 'John' } });
+ * ```
+ */
+export declare class JSONEvalCore {
+    private _schema;
+    private _wasmModule;
+    private _context;
+    private _data;
+    private _instance;
+    private _ready;
+    private _isMsgpackSchema;
+    private _isFromCache;
+    /**
+     * @param wasmModule - WASM module (injected by wrapper package)
+     * @param options
+     */
+    constructor(wasmModule: any, { schema, context, data, fromCache }: JSONEvalOptions);
+    /**
+     * Initialize the WASM instance
+     * Call this before using other methods, or use the async methods which call it automatically
+     */
+    init(): Promise<void>;
+    /**
+     * Create a new JSONEval instance from a cached ParsedSchema
+     * Static factory method for convenience
+     *
+     * @param wasmModule - WASM module
+     * @param cacheKey - Cache key to lookup in ParsedSchemaCache
+     * @param context - Optional context data
+     * @param data - Optional initial data
+     * @returns New instance
+     */
+    static fromCache(wasmModule: any, cacheKey: string, context?: any, data?: any): JSONEvalCore;
+    /**
+     * Validate data against schema (returns parsed JavaScript object)
+     * Uses validateJS for Worker-safe serialization
+     */
+    validate({ data, context }: ValidateOptions): Promise<ValidationResult>;
+    /**
+     * Evaluate schema with data (returns parsed JavaScript object)
+     */
+    evaluate({ data, context, paths }: EvaluateOptions): Promise<any>;
+    /**
+     * Evaluate dependent fields (returns parsed JavaScript object, processes transitively)
+     */
+    evaluateDependents({ changedPaths, data, context, reEvaluate }: EvaluateDependentsOptions): Promise<DependentChange[]>;
+    /**
+     * Get evaluated schema
+     */
+    getEvaluatedSchema({ skipLayout }?: GetEvaluatedSchemaOptions): Promise<any>;
+    /**
+     * Get evaluated schema as MessagePack binary data
+     */
+    getEvaluatedSchemaMsgpack({ skipLayout }?: GetEvaluatedSchemaOptions): Promise<Uint8Array>;
+    /**
+     * Get schema values (evaluations ending with .value)
+     */
+    getSchemaValue(): Promise<any>;
+    /**
+     * Get evaluated schema without $params field
+     */
+    getEvaluatedSchemaWithoutParams({ skipLayout }?: GetEvaluatedSchemaOptions): Promise<any>;
+    /**
+     * Get a value from the evaluated schema using dotted path notation
+     */
+    getEvaluatedSchemaByPath({ path, skipLayout }: GetValueByPathOptions): Promise<any | null>;
+    /**
+     * Get values from the evaluated schema using multiple dotted path notations
+     * Returns data in the specified format (skips paths that are not found)
+     */
+    getEvaluatedSchemaByPaths({ paths, skipLayout, format }: GetValueByPathsOptions): Promise<any>;
+    /**
+     * Get a value from the schema using dotted path notation
+     */
+    getSchemaByPath({ path }: GetSchemaByPathOptions): Promise<any | null>;
+    /**
+     * Get values from the schema using multiple dotted path notations
+     * Returns data in the specified format (skips paths that are not found)
+     */
+    getSchemaByPaths({ paths, format }: GetSchemaByPathsOptions): Promise<any>;
+    /**
+     * Reload schema with new data
+     */
+    reloadSchema({ schema, context, data }: ReloadSchemaOptions): Promise<void>;
+    /**
+     * Reload schema from MessagePack bytes
+     */
+    reloadSchemaMsgpack(schemaMsgpack: Uint8Array, context?: any, data?: any): Promise<void>;
+    /**
+     * Reload schema from ParsedSchemaCache using a cache key
+     */
+    reloadSchemaFromCache(cacheKey: string, context?: any, data?: any): Promise<void>;
+    /**
+     * Get cache statistics
+     */
+    cacheStats(): Promise<CacheStats>;
+    /**
+     * Clear the evaluation cache
+     */
+    clearCache(): Promise<void>;
+    /**
+     * Get the number of cached entries
+     */
+    cacheLen(): Promise<number>;
+    /**
+     * Enable evaluation caching
+     */
+    enableCache(): Promise<void>;
+    /**
+     * Disable evaluation caching
+     */
+    disableCache(): Promise<void>;
+    /**
+     * Check if evaluation caching is enabled
+     */
+    isCacheEnabled(): boolean;
+    /**
+     * Resolve layout with optional evaluation
+     */
+    resolveLayout(options?: {
+        evaluate?: boolean;
+    }): Promise<void>;
+    /**
+     * Set timezone offset for datetime operations (TODAY, NOW)
+     * @param offsetMinutes - Timezone offset in minutes from UTC
+     *                        (e.g., 420 for UTC+7, -300 for UTC-5)
+     *                        Pass null or undefined to reset to UTC
+     */
+    setTimezoneOffset(offsetMinutes: number | null | undefined): void;
+    /**
+     * Compile and run JSON logic from a JSON logic string
+     */
+    compileAndRunLogic({ logicStr, data, context }: CompileAndRunLogicOptions): Promise<any>;
+    /**
+     * Compile JSON logic and return a global ID
+     */
+    compileLogic(logicStr: string | object): Promise<number>;
+    /**
+     * Run pre-compiled logic by ID
+     */
+    runLogic(logicId: number, data?: any, context?: any): Promise<any>;
+    /**
+     * Validate data against schema rules with optional path filtering
+     */
+    validatePaths({ data, context, paths }: EvaluateOptions): Promise<ValidationResult>;
+    /**
+     * Evaluate a subform with data
+     */
+    evaluateSubform({ subformPath, data, context, paths }: EvaluateSubformOptions): Promise<void>;
+    /**
+     * Validate subform data against its schema rules
+     */
+    validateSubform({ subformPath, data, context }: ValidateSubformOptions): Promise<ValidationResult>;
+    /**
+     * Evaluate dependent fields in subform
+     */
+    evaluateDependentsSubform({ subformPath, changedPaths, data, context, reEvaluate }: EvaluateDependentsSubformOptions): Promise<DependentChange[]>;
+    /**
+     * Resolve layout for subform
+     */
+    resolveLayoutSubform({ subformPath, evaluate }: ResolveLayoutSubformOptions): Promise<void>;
+    /**
+     * Get evaluated schema from subform
+     */
+    getEvaluatedSchemaSubform({ subformPath, resolveLayout }: GetEvaluatedSchemaSubformOptions): Promise<any>;
+    /**
+     * Get schema value from subform (all .value fields)
+     */
+    getSchemaValueSubform({ subformPath }: GetSchemaValueSubformOptions): Promise<any>;
+    /**
+     * Get evaluated schema without $params from subform
+     */
+    getEvaluatedSchemaWithoutParamsSubform({ subformPath, resolveLayout }: GetEvaluatedSchemaSubformOptions): Promise<any>;
+    /**
+     * Get evaluated schema by specific path from subform
+     */
+    getEvaluatedSchemaByPathSubform({ subformPath, schemaPath, skipLayout }: GetEvaluatedSchemaByPathSubformOptions): Promise<any | null>;
+    /**
+     * Get evaluated schema by multiple paths from subform
+     * Returns data in the specified format (skips paths that are not found)
+     */
+    getEvaluatedSchemaByPathsSubform({ subformPath, schemaPaths, skipLayout, format }: GetEvaluatedSchemaByPathsSubformOptions): Promise<any>;
+    /**
+     * Get list of available subform paths
+     */
+    getSubformPaths(): Promise<string[]>;
+    /**
+     * Get schema by specific path from subform
+     */
+    getSchemaByPathSubform({ subformPath, schemaPath }: GetSchemaByPathSubformOptions): Promise<any | null>;
+    /**
+     * Get schema by multiple paths from subform
+     * Returns data in the specified format (skips paths that are not found)
+     */
+    getSchemaByPathsSubform({ subformPath, schemaPaths, format }: GetSchemaByPathsSubformOptions): Promise<any>;
+    /**
+     * Check if a subform exists at the given path
+     */
+    hasSubform(subformPath: string): Promise<boolean>;
+    /**
+     * Free WASM resources
+     */
+    free(): void;
+}
+export default JSONEvalCore;