@langchain/langgraph/dist/state/values/delta.cjs.map

LangGraph

{"version":3,"file":"delta.cjs","names":[],"sources":["../../../src/state/values/delta.ts"],"sourcesContent":["import type { SerializableSchema } from \"../types.js\";\nimport type { DeltaReducer } from \"../../channels/delta.js\";\n\n/**\n * Symbol for runtime identification of DeltaValue instances.\n */\nexport const DELTA_VALUE_SYMBOL: symbol = Symbol.for(\n  \"langgraph.state.delta_value\"\n);\n\ninterface DeltaValueInitBase<Value = unknown> {\n  /**\n   * Batch reducer that combines the current accumulated value with a batch of\n   * writes in a single call: `reducer(state, [w1, w2, ...]) -> newState`.\n   *\n   * Reducers must be deterministic and batching-invariant (associative across\n   * folds), because {@link DeltaChannel} replays checkpointed writes in larger\n   * batches than they were originally produced:\n   * `reducer(reducer(state, xs), ys) === reducer(state, xs.concat(ys))`.\n   */\n  reducer: DeltaReducer<Value, Value>;\n\n  /**\n   * How often (in per-channel updates) to persist a full `DeltaSnapshot` blob\n   * instead of relying purely on replayed deltas. Defaults to the channel's\n   * own default (1000) when omitted.\n   */\n  snapshotFrequency?: number;\n\n  /**\n   * Optional extra fields merged into the generated JSON Schema (e.g.\n   * `langgraph_type`) for documentation, Studio hints, or external tooling.\n   */\n  jsonSchemaExtra?: Record<string, unknown>;\n}\n\ninterface DeltaValueInitWithSchema<Value = unknown, Input = Value> {\n  /**\n   * Schema describing the type and validation logic for reducer input values.\n   *\n   * When provided, the reducer may accept inputs distinct from the stored\n   * (output) type. Each write is validated against this schema before reduction.\n   */\n  inputSchema: SerializableSchema<unknown, Input>;\n\n  /**\n   * Batch reducer that combines the current accumulated value with a batch of\n   * validated writes: `reducer(state, [w1, w2, ...]) -> newState`.\n   *\n   * Must be deterministic and batching-invariant — see\n   * {@link DeltaValueInitBase.reducer}.\n   */\n  reducer: DeltaReducer<Value, Input>;\n\n  /**\n   * How often (in per-channel updates) to persist a full `DeltaSnapshot` blob.\n   * Defaults to the channel's own default (1000) when omitted.\n   */\n  snapshotFrequency?: number;\n\n  /**\n   * Optional extra fields merged into the generated JSON Schema (e.g.\n   * `langgraph_type`) for documentation, Studio hints, or external tooling.\n   */\n  jsonSchemaExtra?: Record<string, unknown>;\n}\n\n/**\n * Initialization options for {@link DeltaValue}.\n *\n * Two forms are supported:\n * 1. Provide only a reducer (and optionally `snapshotFrequency` /\n *    `jsonSchemaExtra`) — the reducer's inputs are validated using the value\n *    schema.\n * 2. Provide an explicit `inputSchema` to distinguish the reducer's input type\n *    from the stored/output type.\n *\n * @template Value - The type of value stored and produced after reduction.\n * @template Input - The type of inputs accepted by the reducer.\n */\nexport type DeltaValueInit<Value = unknown, Input = Value> =\n  | DeltaValueInitWithSchema<Value, Input>\n  | DeltaValueInitBase<Value>;\n\n/**\n * Represents a state field backed by a {@link DeltaChannel}.\n *\n * Unlike {@link ReducedValue} (which stores the full accumulated value in every\n * checkpoint blob via `BinaryOperatorAggregate`), a `DeltaValue` field persists\n * only per-step deltas (plus periodic snapshots) and reconstructs its state on\n * read by replaying ancestor writes through a batch reducer. This avoids\n * re-serializing large accumulators (e.g. long message histories) at every step.\n *\n * @remarks Beta. The on-disk representation backing `DeltaChannel` may change in\n * future releases.\n *\n * @template Value - The type of the value stored in state and produced by reduction.\n * @template Input - The type of updates accepted by the reducer.\n *\n * @example\n * ```ts\n * import { z } from \"zod\";\n * import { StateSchema, DeltaValue } from \"@langchain/langgraph\";\n *\n * const State = new StateSchema({\n *   history: new DeltaValue(z.array(z.string()).default(() => []), {\n *     inputSchema: z.string(),\n *     reducer: (current, writes) => [...current, ...writes],\n *   }),\n * });\n * ```\n */\nexport class DeltaValue<Value = unknown, Input = Value> {\n  /**\n   * Instance marker for runtime identification.\n   * @internal\n   */\n  protected readonly [DELTA_VALUE_SYMBOL] = true as const;\n\n  /**\n   * The schema that describes the type of value stored in state (after\n   * reduction). Its default (if any) seeds the channel's initial value.\n   */\n  readonly valueSchema: SerializableSchema<unknown, Value>;\n\n  /**\n   * The schema used to validate reducer inputs. Defaults to `valueSchema` when\n   * not specified explicitly.\n   */\n  readonly inputSchema: SerializableSchema<unknown, Input | Value>;\n\n  /**\n   * The batch reducer that folds a list of incoming writes into the current\n   * accumulated value.\n   */\n  readonly reducer: DeltaReducer<Value, Input>;\n\n  /**\n   * Snapshot cadence forwarded to the underlying {@link DeltaChannel}.\n   */\n  readonly snapshotFrequency?: number;\n\n  /**\n   * Optional extra fields to merge into the generated JSON Schema.\n   */\n  readonly jsonSchemaExtra?: Record<string, unknown>;\n\n  /**\n   * Represents the value stored after all reductions.\n   */\n  declare ValueType: Value;\n\n  /**\n   * Represents the type that may be provided as input on each update.\n   */\n  declare InputType: Input;\n\n  /**\n   * Constructs a DeltaValue, pairing a value schema with a batch reducer (and an\n   * optional distinct input schema).\n   *\n   * @param valueSchema - The schema describing the stored/output value.\n   * @param init - The reducer (required), `inputSchema`, `snapshotFrequency`,\n   *   and `jsonSchemaExtra` (all optional except the reducer).\n   */\n  constructor(\n    valueSchema: SerializableSchema<unknown, Value>,\n    init: DeltaValueInitWithSchema<Value, Input>\n  );\n\n  constructor(\n    valueSchema: SerializableSchema<Input, Value>,\n    init: DeltaValueInitBase<Value>\n  );\n\n  constructor(\n    valueSchema: SerializableSchema<unknown, Value>,\n    init: DeltaValueInit<Value, Input>\n  ) {\n    this.reducer = init.reducer as DeltaReducer<Value, Input>;\n    this.valueSchema = valueSchema;\n    this.inputSchema = \"inputSchema\" in init ? init.inputSchema : valueSchema;\n    this.snapshotFrequency = init.snapshotFrequency;\n    this.jsonSchemaExtra = init.jsonSchemaExtra;\n  }\n\n  /**\n   * Type guard to check if a value is a DeltaValue instance.\n   */\n  static isInstance<Value = unknown, Input = Value>(\n    value: DeltaValue<Value, Input>\n  ): value is DeltaValue<Value, Input>;\n\n  static isInstance(value: unknown): value is DeltaValue;\n\n  static isInstance<Value = unknown, Input = Value>(\n    value: DeltaValue<Value, Input> | unknown\n  ): value is DeltaValue<Value, Input> {\n    return (\n      typeof value === \"object\" &&\n      value !== null &&\n      DELTA_VALUE_SYMBOL in value &&\n      (value as Record<symbol, unknown>)[DELTA_VALUE_SYMBOL] === true\n    );\n  }\n}\n"],"mappings":";;;;AAMA,MAAa,qBAA6B,OAAO,IAC/C,8BACD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwGD,IAAa,aAAb,MAAwD;;;;;CAKtD,CAAoB,sBAAsB;;;;;CAM1C;;;;;CAMA;;;;;CAMA;;;;CAKA;;;;CAKA;CA8BA,YACE,aACA,MACA;AACA,OAAK,UAAU,KAAK;AACpB,OAAK,cAAc;AACnB,OAAK,cAAc,iBAAiB,OAAO,KAAK,cAAc;AAC9D,OAAK,oBAAoB,KAAK;AAC9B,OAAK,kBAAkB,KAAK;;CAY9B,OAAO,WACL,OACmC;AACnC,SACE,OAAO,UAAU,YACjB,UAAU,QACV,sBAAsB,SACrB,MAAkC,wBAAwB"}