@genkit-ai/ai/lib/json-patch.d.mts

Genkit AI framework generative AI APIs.

/**
 * Copyright 2026 Google LLC
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
/**
 * A tiny, dependency-free RFC 6902 (JSON Patch) implementation.
 *
 * This module is intentionally self-contained and browser-safe (no Node APIs,
 * no runtime dependencies) so it can be shared by the in-process server agent
 * and the browser-facing agent client.
 *
 * Genkit uses JSON Patch to stream incremental changes to a session's custom
 * state (`AgentStreamChunk.customPatch`). The {@link diff} helper only emits
 * `add` / `remove` / `replace` operations (a valid RFC 6902 subset - `move` /
 * `copy` are optimizations we deliberately skip), while {@link applyPatch}
 * understands the full operation set for interoperability.
 *
 * @module json-patch
 */
/**
 * A single RFC 6902 (JSON Patch) operation.
 */
interface JsonPatchOperation {
    op: 'add' | 'remove' | 'replace' | 'move' | 'copy' | 'test';
    /** A JSON Pointer (RFC 6901) to the target location, e.g. `"/agentStatus"`. */
    path: string;
    /** Source pointer; required for `move` and `copy`. */
    from?: string;
    /** New value; required for `add`, `replace`, and `test`. */
    value?: any;
}
/**
 * An RFC 6902 JSON Patch: an ordered list of operations.
 */
type JsonPatch = JsonPatchOperation[];
/**
 * Computes an RFC 6902 JSON Patch that transforms `from` into `to`.
 *
 * The diff is rooted at the document, so pointers are bare (e.g. `/agentStatus`,
 * `/items/0`). Only `add` / `remove` / `replace` operations are emitted.
 *
 * When the two documents differ at the root in a way that cannot be expressed
 * as member-level changes (e.g. an object becomes an array, or a primitive
 * changes), a single whole-document `replace` at path `""` is returned.
 */
declare function diff(from: unknown, to: unknown): JsonPatch;
/**
 * Applies an RFC 6902 JSON Patch to `document`, returning the new value.
 *
 * The input is not mutated; a clone is patched and returned. Operating on the
 * root pointer (`""`) replaces / adds the whole document.
 *
 * Apply is intentionally lenient to keep streaming robust: applying an `add` /
 * `replace` whose parent container is missing initializes the parent as an
 * object, and a `remove` / `replace` targeting a missing member is a no-op
 * rather than an error. `test` operations are honored and throw on mismatch.
 */
declare function applyPatch<T = any>(document: T, patch: JsonPatch): T;

export { type JsonPatch, type JsonPatchOperation, applyPatch, diff };