agentic-qe 3.3.4 → 3.4.0

package/v3/dist/adapters/ag-ui/json-patch.d.ts

@@ -0,0 +1,241 @@
+/**
+ * JSON Patch Wrapper (RFC 6902)
+ *
+ * Provides a unified interface for JSON Patch operations using fast-json-patch
+ * for RFC 6902 compliance. This module wraps fast-json-patch with additional
+ * validation, error handling, and AQE-specific types.
+ *
+ * Reference: https://datatracker.ietf.org/doc/html/rfc6902
+ *
+ * @module adapters/ag-ui/json-patch
+ */
+import * as fastJsonPatch from 'fast-json-patch';
+import type { JsonPatchOperation as AQEJsonPatchOperation } from './event-types.js';
+/**
+ * JSON Patch operation type (RFC 6902)
+ */
+export type PatchOperationType = 'add' | 'remove' | 'replace' | 'move' | 'copy' | 'test';
+/**
+ * Re-export fast-json-patch types for compatibility
+ */
+export type Operation = fastJsonPatch.Operation;
+/**
+ * Result of applying a patch operation
+ */
+export interface PatchResult {
+    /** Whether the patch was applied successfully */
+    success: boolean;
+    /** The resulting document after patch application */
+    document: Record<string, unknown>;
+    /** Error message if patch failed */
+    error?: string;
+    /** Index of the failed operation (if any) */
+    failedOperationIndex?: number;
+    /** Validation errors if any */
+    validationErrors?: string[];
+}
+/**
+ * Configuration for diff computation
+ */
+export interface DiffConfig {
+    /** Whether to generate 'test' operations for validation */
+    generateTestOps?: boolean;
+    /** Whether to use 'move' operations when possible (fast-json-patch always detects moves) */
+    detectMoves?: boolean;
+    /** Maximum depth to compare objects (default: unlimited) */
+    maxDepth?: number;
+    /** Whether to use hash comparison for arrays (faster but less precise) */
+    hash?: boolean;
+    /** Whether to invert the diff (newState -> oldState) */
+    invertible?: boolean;
+}
+/**
+ * Validation result for a patch operation
+ */
+export interface ValidationResult {
+    /** Whether the operation is valid */
+    valid: boolean;
+    /** Error message if invalid */
+    error?: string;
+    /** Array of all validation errors */
+    errors?: string[];
+}
+/**
+ * Compliance check result for RFC 6902
+ */
+export interface ComplianceResult {
+    /** Whether the patch is RFC 6902 compliant */
+    compliant: boolean;
+    /** List of compliance issues found */
+    issues: ComplianceIssue[];
+}
+/**
+ * Individual compliance issue
+ */
+export interface ComplianceIssue {
+    /** Issue type */
+    type: 'invalid_op' | 'missing_path' | 'invalid_path' | 'missing_value' | 'missing_from' | 'invalid_from';
+    /** Operation index where issue was found */
+    operationIndex: number;
+    /** Human-readable description */
+    message: string;
+    /** RFC 6902 section reference */
+    rfcSection?: string;
+}
+/**
+ * Escape special characters in a JSON Pointer token (RFC 6901)
+ * ~ becomes ~0
+ * / becomes ~1
+ */
+export declare function escapePathToken(token: string): string;
+/**
+ * Unescape special characters in a JSON Pointer token (RFC 6901)
+ * ~0 becomes ~
+ * ~1 becomes /
+ */
+export declare function unescapePathToken(token: string): string;
+/**
+ * Parse a JSON Pointer path into tokens
+ */
+export declare function parsePath(path: string): string[];
+/**
+ * Build a JSON Pointer path from tokens
+ */
+export declare function buildPath(tokens: string[]): string;
+/**
+ * Get a value from an object using a JSON Pointer path
+ */
+export declare function getValueAtPath(document: Record<string, unknown>, path: string): unknown;
+/**
+ * Check if a path exists in the document
+ */
+export declare function pathExists(document: Record<string, unknown>, path: string): boolean;
+/**
+ * Set a value at a JSON Pointer path (mutates the document)
+ */
+export declare function setValueAtPath(document: Record<string, unknown>, path: string, value: unknown): void;
+/**
+ * Delete a value at a JSON Pointer path (mutates the document)
+ */
+export declare function deleteValueAtPath(document: Record<string, unknown>, path: string): void;
+/**
+ * Error codes for JSON Patch operations
+ */
+export type JsonPatchErrorCode = 'INVALID_OPERATION' | 'INVALID_PATH' | 'PATH_NOT_FOUND' | 'INVALID_INDEX' | 'TEST_FAILED' | 'VALIDATION_FAILED' | 'COMPLIANCE_FAILED' | 'APPLICATION_FAILED';
+/**
+ * Custom error class for JSON Patch operations
+ */
+export declare class JsonPatchError extends Error {
+    readonly code: JsonPatchErrorCode;
+    readonly details?: Record<string, unknown> | undefined;
+    constructor(message: string, code: JsonPatchErrorCode, details?: Record<string, unknown> | undefined);
+    /**
+     * Create error from fast-json-patch error
+     */
+    static fromFastJsonPatch(error: unknown, operationIndex?: number): JsonPatchError;
+    /**
+     * Create test failure error
+     */
+    static testFailed(path: string, expected: unknown, actual: unknown): JsonPatchError;
+}
+/**
+ * Validate a JSON Pointer path format (RFC 6901)
+ */
+export declare function validatePath(path: string): boolean;
+/**
+ * Validate a single patch operation against RFC 6902
+ */
+export declare function validateOperation(op: AQEJsonPatchOperation): ValidationResult;
+/**
+ * Validate an array of patch operations
+ */
+export declare function validatePatch(patch: AQEJsonPatchOperation[]): ValidationResult;
+/**
+ * Check RFC 6902 compliance of a patch
+ */
+export declare function checkCompliance(patch: AQEJsonPatchOperation[]): ComplianceResult;
+/**
+ * Validate compliance and throw if not compliant
+ */
+export declare function ensureCompliance(patch: AQEJsonPatchOperation[]): void;
+/**
+ * Apply a single patch operation to a document
+ * Returns a new document (immutable)
+ */
+export declare function applyOperation(document: Record<string, unknown>, op: AQEJsonPatchOperation): Record<string, unknown>;
+/**
+ * Apply a JSON Patch to a document
+ * Returns result with success status and either new document or error info
+ */
+export declare function applyPatch(document: Record<string, unknown>, patch: AQEJsonPatchOperation[]): PatchResult;
+/**
+ * Apply a JSON Patch atomically with automatic rollback on failure
+ * Returns the new document if successful, throws on error
+ */
+export declare function applyPatchAtomic(document: Record<string, unknown>, patch: AQEJsonPatchOperation[]): Record<string, unknown>;
+/**
+ * Validate a patch against a document (dry run)
+ * Returns true if the patch would apply successfully
+ */
+export declare function validate(document: Record<string, unknown>, patch: AQEJsonPatchOperation[]): boolean;
+/**
+ * Deep equality comparison for JSON values
+ */
+export declare function deepEqual(a: unknown, b: unknown): boolean;
+/**
+ * Compute the JSON Patch to transform oldState into newState
+ * Uses fast-json-patch's compare function for optimal diff generation
+ */
+export declare function computeDiff(oldState: Record<string, unknown>, newState: Record<string, unknown>, config?: DiffConfig): AQEJsonPatchOperation[];
+/**
+ * Generate an observer for watching document changes
+ * Returns a function to call when you want to generate the patch
+ */
+export declare function observe<T extends object>(document: T): {
+    observer: any;
+    generate: () => AQEJsonPatchOperation[];
+};
+/**
+ * Unobserve a document (cleanup)
+ */
+export declare function unobserve<T extends object>(document: T, observer: any): void;
+/**
+ * Create a test operation to validate state before applying patches
+ */
+export declare function createTestOperation(path: string, value: unknown): AQEJsonPatchOperation;
+/**
+ * Create an add operation
+ */
+export declare function createAddOperation(path: string, value: unknown): AQEJsonPatchOperation;
+/**
+ * Create a remove operation
+ */
+export declare function createRemoveOperation(path: string): AQEJsonPatchOperation;
+/**
+ * Create a replace operation
+ */
+export declare function createReplaceOperation(path: string, value: unknown): AQEJsonPatchOperation;
+/**
+ * Create a move operation
+ */
+export declare function createMoveOperation(from: string, path: string): AQEJsonPatchOperation;
+/**
+ * Create a copy operation
+ */
+export declare function createCopyOperation(from: string, path: string): AQEJsonPatchOperation;
+/**
+ * Re-export fast-json-patch internals for advanced usage
+ */
+export declare const fastJsonPatchLib: {
+    compare: typeof fastJsonPatch.compare;
+    generate: typeof fastJsonPatch.generate;
+    observe: typeof fastJsonPatch.observe;
+    unobserve: typeof fastJsonPatch.unobserve;
+    applyPatch: typeof fastJsonPatch.applyPatch;
+    applyOperation: typeof fastJsonPatch.applyOperation;
+    validate: typeof fastJsonPatch.validate;
+    getValueByPointer: typeof fastJsonPatch.getValueByPointer;
+    escapePathComponent: typeof fastJsonPatch.escapePathComponent;
+    unescapePathComponent: typeof fastJsonPatch.unescapePathComponent;
+};
+//# sourceMappingURL=json-patch.d.ts.map

package/v3/dist/adapters/ag-ui/json-patch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-patch.d.ts","sourceRoot":"","sources":["../../../src/adapters/ag-ui/json-patch.ts"],"names":[],"mappings":"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"}