@langchain/langgraph 1.4.2 → 1.4.4

package/dist/state/schema.js

@@ -3,10 +3,12 @@ import { BinaryOperatorAggregate } from "../channels/binop.js";
 import { LastValue } from "../channels/last_value.js";
 import { isStandardSchema } from "./types.js";
 import { getJsonSchemaFromSchema, getSchemaDefaultGetter } from "./adapter.js";
+import { DeltaChannel } from "../channels/delta.js";
 import { UntrackedValueChannel } from "../channels/untracked_value.js";
 import "../channels/index.js";
 import { ReducedValue } from "./values/reduced.js";
 import { UntrackedValue } from "./values/untracked.js";
+import { DeltaValue } from "./values/delta.js";
 //#region src/state/schema.ts
 const STATE_SCHEMA_SYMBOL = Symbol.for("langgraph.state.state_schema");
 /**
@@ -57,7 +59,13 @@ var StateSchema = class {
 	*/
 	getChannels() {
 		const channels = {};
-		for (const [key, value] of Object.entries(this.fields)) if (ReducedValue.isInstance(value)) {
+		for (const [key, value] of Object.entries(this.fields)) if (DeltaValue.isInstance(value)) {
+			const defaultGetter = getSchemaDefaultGetter(value.valueSchema);
+			channels[key] = new DeltaChannel(value.reducer, {
+				snapshotFrequency: value.snapshotFrequency,
+				initialValueFactory: defaultGetter
+			});
+		} else if (ReducedValue.isInstance(value)) {
 			const defaultGetter = getSchemaDefaultGetter(value.valueSchema);
 			channels[key] = new BinaryOperatorAggregate(value.reducer, defaultGetter);
 		} else if (UntrackedValue.isInstance(value)) {
@@ -67,7 +75,7 @@ var StateSchema = class {
 				initialValueFactory: defaultGetter
 			});
 		} else if (isStandardSchema(value)) channels[key] = new LastValue(getSchemaDefaultGetter(value));
-		else throw new Error(`Invalid state field "${key}": must be a schema, ReducedValue, UntrackedValue, or ManagedValue`);
+		else throw new Error(`Invalid state field "${key}": must be a schema, ReducedValue, DeltaValue, UntrackedValue, or ManagedValue`);
 		return channels;
 	}
 	/**
@@ -79,7 +87,7 @@ var StateSchema = class {
 		const required = [];
 		for (const [key, value] of Object.entries(this.fields)) {
 			let fieldSchema;
-			if (ReducedValue.isInstance(value)) {
+			if (DeltaValue.isInstance(value) || ReducedValue.isInstance(value)) {
 				fieldSchema = getJsonSchemaFromSchema(value.valueSchema);
 				if (value.jsonSchemaExtra) fieldSchema = {
 					...fieldSchema ?? {},
@@ -90,7 +98,7 @@ var StateSchema = class {
 			if (fieldSchema) {
 				properties[key] = fieldSchema;
 				let hasDefault = false;
-				if (ReducedValue.isInstance(value)) hasDefault = getSchemaDefaultGetter(value.valueSchema) !== void 0;
+				if (DeltaValue.isInstance(value) || ReducedValue.isInstance(value)) hasDefault = getSchemaDefaultGetter(value.valueSchema) !== void 0;
 				else if (UntrackedValue.isInstance(value)) hasDefault = value.schema ? getSchemaDefaultGetter(value.schema) !== void 0 : false;
 				else hasDefault = getSchemaDefaultGetter(value) !== void 0;
 				if (!hasDefault) required.push(key);
@@ -110,7 +118,7 @@ var StateSchema = class {
 		const properties = {};
 		for (const [key, value] of Object.entries(this.fields)) {
 			let fieldSchema;
-			if (ReducedValue.isInstance(value)) {
+			if (DeltaValue.isInstance(value) || ReducedValue.isInstance(value)) {
 				fieldSchema = getJsonSchemaFromSchema(value.inputSchema);
 				if (value.jsonSchemaExtra) fieldSchema = {
 					...fieldSchema ?? {},
@@ -154,7 +162,7 @@ var StateSchema = class {
 				continue;
 			}
 			let schema;
-			if (ReducedValue.isInstance(fieldDef)) {
+			if (DeltaValue.isInstance(fieldDef) || ReducedValue.isInstance(fieldDef)) {
 				const [isOverwrite, overwriteValue] = _getOverwriteValue(value);
 				if (isOverwrite) {
 					schema = fieldDef.valueSchema;

package/dist/state/schema.js.map

@@ -1 +1 @@
-{"version":3,"file":"schema.js","names":[],"sources":["../../src/state/schema.ts"],"sourcesContent":["/* eslint-disable @typescript-eslint/no-explicit-any */\nimport type { JSONSchema } from \"@langchain/core/utils/json_schema\";\nimport type { StandardSchemaV1 } from \"@standard-schema/spec\";\n\nimport type { RunnableLike } from \"../pregel/runnable_types.js\";\nimport {\n  BaseChannel,\n  LastValue,\n  BinaryOperatorAggregate,\n} from \"../channels/index.js\";\nimport { UntrackedValueChannel } from \"../channels/untracked_value.js\";\n\nimport type { SerializableSchema } from \"./types.js\";\nimport { isStandardSchema } from \"./types.js\";\nimport { getJsonSchemaFromSchema, getSchemaDefaultGetter } from \"./adapter.js\";\nimport {\n  _getOverwriteValue,\n  OVERWRITE,\n  type OverwriteValue,\n} from \"../constants.js\";\nimport { ReducedValue } from \"./values/reduced.js\";\nimport { UntrackedValue } from \"./values/untracked.js\";\n\nconst STATE_SCHEMA_SYMBOL = Symbol.for(\"langgraph.state.state_schema\");\n\n/**\n * Maps a single StateSchema field definition to its corresponding Channel type.\n *\n * This utility type inspects the type of the field and returns an appropriate\n * `BaseChannel` type, parameterized with the state \"value\" and \"input\" types according to the field's shape.\n *\n * Rules:\n * - If the field (`F`) is a `ReducedValue<V, I>`, the channel will store values of type `V`\n *   and accept input of type `I`.\n * - If the field is a `UntrackedValue<V>`, the channel will store and accept values of type `V`.\n * - If the field is a `SerializableSchema<I, O>`, the channel will store values of type `O`\n *   (the schema's output/validated value) and accept input of type `I`.\n * - For all other types, a generic `BaseChannel<unknown, unknown>` is used as fallback.\n *\n * @template F - The StateSchema field type to map to a Channel type.\n *\n * @example\n * ```typescript\n * type MyField = ReducedValue<number, string>;\n * type ChannelType = StateSchemaFieldToChannel<MyField>;\n * // ChannelType is BaseChannel<number, string>\n * ```\n */\nexport type StateSchemaFieldToChannel<F> =\n  F extends ReducedValue<infer V, infer I>\n    ? BaseChannel<V, OverwriteValue<V> | I>\n    : F extends UntrackedValue<infer V>\n      ? BaseChannel<V, V>\n      : F extends SerializableSchema<infer I, infer O>\n        ? BaseChannel<O, I>\n        : BaseChannel<unknown, unknown>;\n\n/**\n * Converts StateSchema fields into a strongly-typed\n * State Definition object, where each field is mapped to its channel type.\n *\n * This utility type is used internally to create the shape of the state channels for a given schema,\n * substituting each field with the result of `StateSchemaFieldToChannel`.\n *\n * If you define a state schema as:\n * ```typescript\n * const fields = {\n *   a: ReducedValue<number, string>(),\n *   b: UntrackedValue<boolean>(),\n *   c: SomeSerializableSchemaType, // SerializableSchema<in, out>\n * }\n * ```\n * then `StateSchemaFieldsToStateDefinition<typeof fields>` yields:\n * ```typescript\n * {\n *   a: BaseChannel<number, string>;\n *   b: BaseChannel<boolean, boolean>;\n *   c: BaseChannel<typeof schema's output type, typeof schema's input type>;\n * }\n * ```\n *\n * @template TFields - The mapping of field names to StateSchema field types.\n * @returns An object type mapping field names to channel types.\n *\n * @see StateSchemaFieldToChannel\n */\nexport type StateSchemaFieldsToStateDefinition<\n  TFields extends StateSchemaFields,\n> = {\n  [K in keyof TFields]: StateSchemaFieldToChannel<TFields[K]>;\n};\n\n/**\n * Valid field types for StateSchema.\n * Either a LangGraph state value type or a raw schema (e.g., Zod schema).\n */\nexport type StateSchemaField<Input = unknown, Output = Input> =\n  | ReducedValue<Input, Output>\n  | UntrackedValue<Output>\n  | SerializableSchema<Input, Output>;\n\n/**\n * Init object for StateSchema constructor.\n * Uses `any` to allow variance in generic types (e.g., ReducedValue<string, string[]>).\n */\nexport type StateSchemaFields = {\n  [key: string]: StateSchemaField<any, any>;\n};\n\n/**\n * Infer the State type from a StateSchemaFields.\n * This is the type of the full state object.\n *\n * - ReducedValue<Value, Input> → Value (the stored type)\n * - UntrackedValue<Value> → Value\n * - SerializableSchema<Input, Output> → Output (the validated type)\n */\nexport type InferStateSchemaValue<TFields extends StateSchemaFields> = {\n  [K in keyof TFields]: TFields[K] extends ReducedValue<any, any>\n    ? TFields[K][\"ValueType\"]\n    : TFields[K] extends UntrackedValue<any>\n      ? TFields[K][\"ValueType\"]\n      : TFields[K] extends SerializableSchema<any, infer TOutput>\n        ? TOutput\n        : never;\n};\n\n/**\n * Infer the Update type from a StateSchemaFields.\n * This is the type for partial updates to state.\n *\n * - ReducedValue<Value, Input> → Input (the reducer input type)\n * - UntrackedValue<Value> → Value\n * - SerializableSchema<Input, Output> → Input (what you provide)\n */\nexport type InferStateSchemaUpdate<TFields extends StateSchemaFields> = {\n  [K in keyof TFields]?: TFields[K] extends ReducedValue<infer V, infer I>\n    ? OverwriteValue<V> | I\n    : TFields[K] extends UntrackedValue<any>\n      ? TFields[K][\"ValueType\"]\n      : TFields[K] extends SerializableSchema<infer TInput, any>\n        ? TInput\n        : never;\n};\n\n/**\n * StateSchema provides a unified API for defining LangGraph state schemas.\n *\n * @example\n * ```ts\n * import { z } from \"zod\";\n * import { StateSchema, ReducedValue, MessagesValue } from \"@langchain/langgraph\";\n *\n * const AgentState = new StateSchema({\n *   // Prebuilt messages value\n *   messages: MessagesValue,\n *   // Basic LastValue channel from any standard schema\n *   currentStep: z.string(),\n *   // LastValue with native default\n *   count: z.number().default(0),\n *   // ReducedValue for fields needing reducers\n *   history: new ReducedValue(\n *     z.array(z.string()).default(() => []),\n *     {\n *       inputSchema: z.string(),\n *       reducer: (current, next) => [...current, next],\n *     }\n *   ),\n * });\n *\n * // Extract types\n * type State = typeof AgentState.State;\n * type Update = typeof AgentState.Update;\n *\n * // Use in StateGraph\n * const graph = new StateGraph(AgentState);\n * ```\n */\nexport class StateSchema<TFields extends StateSchemaFields> {\n  /**\n   * Symbol for runtime identification.\n   * @internal Used by isInstance for runtime type checking\n   */\n  // @ts-expect-error - Symbol is read via `in` operator in isInstance\n  private readonly [STATE_SCHEMA_SYMBOL] = true;\n\n  /**\n   * Type declaration for the full state type.\n   * Use: `typeof myState.State`\n   */\n  declare State: InferStateSchemaValue<TFields>;\n\n  /**\n   * Type declaration for the update type.\n   * Use: `typeof myState.Update`\n   */\n  declare Update: InferStateSchemaUpdate<TFields>;\n\n  /**\n   * Type declaration for node functions.\n   * Use: `typeof myState.Node` to type node functions outside the graph builder.\n   *\n   * @example\n   * ```typescript\n   * const AgentState = new StateSchema({\n   *   count: z.number().default(0),\n   * });\n   *\n   * const myNode: typeof AgentState.Node = (state) => {\n   *   return { count: state.count + 1 };\n   * };\n   * ```\n   */\n  declare Node: RunnableLike<\n    InferStateSchemaValue<TFields>,\n    InferStateSchemaUpdate<TFields>\n  >;\n\n  constructor(readonly fields: TFields) {}\n\n  /**\n   * Get the channel definitions for use with StateGraph.\n   * This converts the StateSchema fields into BaseChannel instances.\n   */\n  getChannels(): Record<string, BaseChannel> {\n    const channels: Record<string, BaseChannel> = {};\n\n    for (const [key, value] of Object.entries(this.fields)) {\n      if (ReducedValue.isInstance(value)) {\n        // ReducedValue -> BinaryOperatorAggregate\n        const defaultGetter = getSchemaDefaultGetter(value.valueSchema);\n        channels[key] = new BinaryOperatorAggregate(\n          value.reducer,\n          defaultGetter\n        );\n      } else if (UntrackedValue.isInstance(value)) {\n        // UntrackedValue -> UntrackedValueChannel\n        const defaultGetter = value.schema\n          ? getSchemaDefaultGetter(value.schema)\n          : undefined;\n        channels[key] = new UntrackedValueChannel({\n          guard: value.guard,\n          initialValueFactory: defaultGetter,\n        });\n      } else if (isStandardSchema(value)) {\n        // Plain schema -> LastValue channel\n        const defaultGetter = getSchemaDefaultGetter(value);\n        channels[key] = new LastValue(defaultGetter);\n      } else {\n        throw new Error(\n          `Invalid state field \"${key}\": must be a schema, ReducedValue, UntrackedValue, or ManagedValue`\n        );\n      }\n    }\n\n    return channels;\n  }\n\n  /**\n   * Get the JSON schema for the full state type.\n   * Used by Studio and API for schema introspection.\n   */\n  getJsonSchema(): JSONSchema {\n    const properties: Record<string, JSONSchema> = {};\n    const required: string[] = [];\n\n    for (const [key, value] of Object.entries(this.fields)) {\n      let fieldSchema: JSONSchema | undefined;\n\n      if (ReducedValue.isInstance(value)) {\n        fieldSchema = getJsonSchemaFromSchema(value.valueSchema) as JSONSchema;\n        // Merge jsonSchemaExtra (e.g. langgraph_type) into the field schema,\n        // even if base schema is undefined\n        if (value.jsonSchemaExtra) {\n          fieldSchema = { ...(fieldSchema ?? {}), ...value.jsonSchemaExtra };\n        }\n      } else if (UntrackedValue.isInstance(value)) {\n        fieldSchema = value.schema\n          ? (getJsonSchemaFromSchema(value.schema) as JSONSchema)\n          : undefined;\n      } else if (isStandardSchema(value)) {\n        fieldSchema = getJsonSchemaFromSchema(value) as JSONSchema;\n      }\n\n      if (fieldSchema) {\n        properties[key] = fieldSchema;\n\n        // Field is required if it doesn't have a default\n        let hasDefault = false;\n        if (ReducedValue.isInstance(value)) {\n          hasDefault = getSchemaDefaultGetter(value.valueSchema) !== undefined;\n        } else if (UntrackedValue.isInstance(value)) {\n          hasDefault = value.schema\n            ? getSchemaDefaultGetter(value.schema) !== undefined\n            : false;\n        } else {\n          hasDefault = getSchemaDefaultGetter(value) !== undefined;\n        }\n\n        if (!hasDefault) {\n          required.push(key);\n        }\n      }\n    }\n\n    return {\n      type: \"object\",\n      properties,\n      required: required.length > 0 ? required : undefined,\n    };\n  }\n\n  /**\n   * Get the JSON schema for the update/input type.\n   * All fields are optional in updates.\n   */\n  getInputJsonSchema(): JSONSchema {\n    const properties: Record<string, JSONSchema> = {};\n\n    for (const [key, value] of Object.entries(this.fields)) {\n      let fieldSchema: JSONSchema | undefined;\n\n      if (ReducedValue.isInstance(value)) {\n        // Use input schema for updates\n        fieldSchema = getJsonSchemaFromSchema(value.inputSchema) as JSONSchema;\n        // Merge jsonSchemaExtra (e.g. langgraph_type) into the field schema,\n        // even if base schema is undefined\n        if (value.jsonSchemaExtra) {\n          fieldSchema = { ...(fieldSchema ?? {}), ...value.jsonSchemaExtra };\n        }\n      } else if (UntrackedValue.isInstance(value)) {\n        fieldSchema = value.schema\n          ? (getJsonSchemaFromSchema(value.schema) as JSONSchema)\n          : undefined;\n      } else if (isStandardSchema(value)) {\n        fieldSchema = getJsonSchemaFromSchema(value) as JSONSchema;\n      }\n\n      if (fieldSchema) {\n        properties[key] = fieldSchema;\n      }\n    }\n\n    return {\n      type: \"object\",\n      properties,\n    };\n  }\n\n  /**\n   * Get the list of channel keys (excluding managed values).\n   */\n  getChannelKeys(): string[] {\n    return Object.entries(this.fields).map(([key]) => key);\n  }\n\n  /**\n   * Get all keys (channels + managed values).\n   */\n  getAllKeys(): string[] {\n    return Object.keys(this.fields);\n  }\n\n  /**\n   * Validate input data against the schema.\n   * This validates each field using its corresponding schema.\n   *\n   * @param data - The input data to validate\n   * @returns The validated data with coerced types\n   */\n  async validateInput<T>(data: T): Promise<T> {\n    if (data == null || typeof data !== \"object\") {\n      return data;\n    }\n\n    const result: Record<string, unknown> = {};\n\n    for (const [key, value] of Object.entries(data)) {\n      const fieldDef = this.fields[key];\n\n      if (fieldDef === undefined) {\n        // Unknown field, pass through\n        result[key] = value;\n        continue;\n      }\n\n      // Get the schema to use for validation\n      let schema: StandardSchemaV1 | undefined;\n\n      if (ReducedValue.isInstance(fieldDef)) {\n        const [isOverwrite, overwriteValue] = _getOverwriteValue(value);\n        if (isOverwrite) {\n          schema = fieldDef.valueSchema;\n          const validationResult =\n            await schema[\"~standard\"].validate(overwriteValue);\n          if (validationResult.issues) {\n            throw new Error(\n              `Validation failed for field \"${key}\": ${JSON.stringify(\n                validationResult.issues\n              )}`\n            );\n          }\n          result[key] = { [OVERWRITE]: validationResult.value };\n          continue;\n        }\n\n        schema = fieldDef.inputSchema;\n      } else if (UntrackedValue.isInstance(fieldDef)) {\n        schema = fieldDef.schema;\n      } else if (isStandardSchema(fieldDef)) {\n        schema = fieldDef;\n      }\n\n      if (schema) {\n        // Validate using standard schema\n        const validationResult = await schema[\"~standard\"].validate(value);\n        if (validationResult.issues) {\n          throw new Error(\n            `Validation failed for field \"${key}\": ${JSON.stringify(\n              validationResult.issues\n            )}`\n          );\n        }\n        result[key] = validationResult.value;\n      } else {\n        // No schema or not a standard schema, pass through\n        result[key] = value;\n      }\n    }\n\n    return result as T;\n  }\n\n  /**\n   * Type guard to check if a value is a StateSchema instance.\n   *\n   * @param value - The value to check.\n   * @returns True if the value is a StateSchema instance with the correct runtime tag.\n   */\n  static isInstance<TFields extends StateSchemaFields>(\n    value: StateSchema<TFields>\n  ): value is StateSchema<TFields>;\n\n  static isInstance(value: unknown): value is StateSchema<any>;\n\n  static isInstance<TFields extends StateSchemaFields>(\n    value: unknown\n  ): value is StateSchema<TFields> {\n    return (\n      typeof value === \"object\" &&\n      value !== null &&\n      STATE_SCHEMA_SYMBOL in value &&\n      value[STATE_SCHEMA_SYMBOL] === true\n    );\n  }\n}\n\nexport type AnyStateSchema = StateSchema<any>;\n"],"mappings":"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"}
+{"version":3,"file":"schema.js","names":[],"sources":["../../src/state/schema.ts"],"sourcesContent":["/* eslint-disable @typescript-eslint/no-explicit-any */\nimport type { JSONSchema } from \"@langchain/core/utils/json_schema\";\nimport type { StandardSchemaV1 } from \"@standard-schema/spec\";\n\nimport type { RunnableLike } from \"../pregel/runnable_types.js\";\nimport {\n  BaseChannel,\n  LastValue,\n  BinaryOperatorAggregate,\n  DeltaChannel,\n} from \"../channels/index.js\";\nimport { UntrackedValueChannel } from \"../channels/untracked_value.js\";\n\nimport type { SerializableSchema } from \"./types.js\";\nimport { isStandardSchema } from \"./types.js\";\nimport { getJsonSchemaFromSchema, getSchemaDefaultGetter } from \"./adapter.js\";\nimport {\n  _getOverwriteValue,\n  OVERWRITE,\n  type OverwriteValue,\n} from \"../constants.js\";\nimport { ReducedValue } from \"./values/reduced.js\";\nimport { UntrackedValue } from \"./values/untracked.js\";\nimport { DeltaValue } from \"./values/delta.js\";\n\nconst STATE_SCHEMA_SYMBOL = Symbol.for(\"langgraph.state.state_schema\");\n\n/**\n * Maps a single StateSchema field definition to its corresponding Channel type.\n *\n * This utility type inspects the type of the field and returns an appropriate\n * `BaseChannel` type, parameterized with the state \"value\" and \"input\" types according to the field's shape.\n *\n * Rules:\n * - If the field (`F`) is a `DeltaValue<V, I>`, the channel will store values of type `V`\n *   and accept input of type `I` (or an `Overwrite`).\n * - If the field (`F`) is a `ReducedValue<V, I>`, the channel will store values of type `V`\n *   and accept input of type `I`.\n * - If the field is a `UntrackedValue<V>`, the channel will store and accept values of type `V`.\n * - If the field is a `SerializableSchema<I, O>`, the channel will store values of type `O`\n *   (the schema's output/validated value) and accept input of type `I`.\n * - For all other types, a generic `BaseChannel<unknown, unknown>` is used as fallback.\n *\n * @template F - The StateSchema field type to map to a Channel type.\n *\n * @example\n * ```typescript\n * type MyField = ReducedValue<number, string>;\n * type ChannelType = StateSchemaFieldToChannel<MyField>;\n * // ChannelType is BaseChannel<number, string>\n * ```\n */\nexport type StateSchemaFieldToChannel<F> =\n  F extends DeltaValue<infer V, infer I>\n    ? BaseChannel<V, OverwriteValue<V> | I>\n    : F extends ReducedValue<infer V, infer I>\n      ? BaseChannel<V, OverwriteValue<V> | I>\n      : F extends UntrackedValue<infer V>\n        ? BaseChannel<V, V>\n        : F extends SerializableSchema<infer I, infer O>\n          ? BaseChannel<O, I>\n          : BaseChannel<unknown, unknown>;\n\n/**\n * Converts StateSchema fields into a strongly-typed\n * State Definition object, where each field is mapped to its channel type.\n *\n * This utility type is used internally to create the shape of the state channels for a given schema,\n * substituting each field with the result of `StateSchemaFieldToChannel`.\n *\n * If you define a state schema as:\n * ```typescript\n * const fields = {\n *   a: ReducedValue<number, string>(),\n *   b: UntrackedValue<boolean>(),\n *   c: SomeSerializableSchemaType, // SerializableSchema<in, out>\n * }\n * ```\n * then `StateSchemaFieldsToStateDefinition<typeof fields>` yields:\n * ```typescript\n * {\n *   a: BaseChannel<number, string>;\n *   b: BaseChannel<boolean, boolean>;\n *   c: BaseChannel<typeof schema's output type, typeof schema's input type>;\n * }\n * ```\n *\n * @template TFields - The mapping of field names to StateSchema field types.\n * @returns An object type mapping field names to channel types.\n *\n * @see StateSchemaFieldToChannel\n */\nexport type StateSchemaFieldsToStateDefinition<\n  TFields extends StateSchemaFields,\n> = {\n  [K in keyof TFields]: StateSchemaFieldToChannel<TFields[K]>;\n};\n\n/**\n * Valid field types for StateSchema.\n * Either a LangGraph state value type or a raw schema (e.g., Zod schema).\n */\nexport type StateSchemaField<Input = unknown, Output = Input> =\n  | DeltaValue<Input, Output>\n  | ReducedValue<Input, Output>\n  | UntrackedValue<Output>\n  | SerializableSchema<Input, Output>;\n\n/**\n * Init object for StateSchema constructor.\n * Uses `any` to allow variance in generic types (e.g., ReducedValue<string, string[]>).\n */\nexport type StateSchemaFields = {\n  [key: string]: StateSchemaField<any, any>;\n};\n\n/**\n * Infer the State type from a StateSchemaFields.\n * This is the type of the full state object.\n *\n * - ReducedValue<Value, Input> → Value (the stored type)\n * - UntrackedValue<Value> → Value\n * - SerializableSchema<Input, Output> → Output (the validated type)\n */\nexport type InferStateSchemaValue<TFields extends StateSchemaFields> = {\n  [K in keyof TFields]: TFields[K] extends DeltaValue<any, any>\n    ? TFields[K][\"ValueType\"]\n    : TFields[K] extends ReducedValue<any, any>\n      ? TFields[K][\"ValueType\"]\n      : TFields[K] extends UntrackedValue<any>\n        ? TFields[K][\"ValueType\"]\n        : TFields[K] extends SerializableSchema<any, infer TOutput>\n          ? TOutput\n          : never;\n};\n\n/**\n * Infer the Update type from a StateSchemaFields.\n * This is the type for partial updates to state.\n *\n * - ReducedValue<Value, Input> → Input (the reducer input type)\n * - UntrackedValue<Value> → Value\n * - SerializableSchema<Input, Output> → Input (what you provide)\n */\nexport type InferStateSchemaUpdate<TFields extends StateSchemaFields> = {\n  [K in keyof TFields]?: TFields[K] extends DeltaValue<infer V, infer I>\n    ? OverwriteValue<V> | I\n    : TFields[K] extends ReducedValue<infer V, infer I>\n      ? OverwriteValue<V> | I\n      : TFields[K] extends UntrackedValue<any>\n        ? TFields[K][\"ValueType\"]\n        : TFields[K] extends SerializableSchema<infer TInput, any>\n          ? TInput\n          : never;\n};\n\n/**\n * StateSchema provides a unified API for defining LangGraph state schemas.\n *\n * @example\n * ```ts\n * import { z } from \"zod\";\n * import { StateSchema, ReducedValue, MessagesValue } from \"@langchain/langgraph\";\n *\n * const AgentState = new StateSchema({\n *   // Prebuilt messages value\n *   messages: MessagesValue,\n *   // Basic LastValue channel from any standard schema\n *   currentStep: z.string(),\n *   // LastValue with native default\n *   count: z.number().default(0),\n *   // ReducedValue for fields needing reducers\n *   history: new ReducedValue(\n *     z.array(z.string()).default(() => []),\n *     {\n *       inputSchema: z.string(),\n *       reducer: (current, next) => [...current, next],\n *     }\n *   ),\n * });\n *\n * // Extract types\n * type State = typeof AgentState.State;\n * type Update = typeof AgentState.Update;\n *\n * // Use in StateGraph\n * const graph = new StateGraph(AgentState);\n * ```\n */\nexport class StateSchema<TFields extends StateSchemaFields> {\n  /**\n   * Symbol for runtime identification.\n   * @internal Used by isInstance for runtime type checking\n   */\n  // @ts-expect-error - Symbol is read via `in` operator in isInstance\n  private readonly [STATE_SCHEMA_SYMBOL] = true;\n\n  /**\n   * Type declaration for the full state type.\n   * Use: `typeof myState.State`\n   */\n  declare State: InferStateSchemaValue<TFields>;\n\n  /**\n   * Type declaration for the update type.\n   * Use: `typeof myState.Update`\n   */\n  declare Update: InferStateSchemaUpdate<TFields>;\n\n  /**\n   * Type declaration for node functions.\n   * Use: `typeof myState.Node` to type node functions outside the graph builder.\n   *\n   * @example\n   * ```typescript\n   * const AgentState = new StateSchema({\n   *   count: z.number().default(0),\n   * });\n   *\n   * const myNode: typeof AgentState.Node = (state) => {\n   *   return { count: state.count + 1 };\n   * };\n   * ```\n   */\n  declare Node: RunnableLike<\n    InferStateSchemaValue<TFields>,\n    InferStateSchemaUpdate<TFields>\n  >;\n\n  constructor(readonly fields: TFields) {}\n\n  /**\n   * Get the channel definitions for use with StateGraph.\n   * This converts the StateSchema fields into BaseChannel instances.\n   */\n  getChannels(): Record<string, BaseChannel> {\n    const channels: Record<string, BaseChannel> = {};\n\n    for (const [key, value] of Object.entries(this.fields)) {\n      if (DeltaValue.isInstance(value)) {\n        // DeltaValue -> DeltaChannel. The value schema's default (if any) seeds\n        // the channel's initial value; otherwise DeltaChannel falls back to [].\n        const defaultGetter = getSchemaDefaultGetter(value.valueSchema);\n        channels[key] = new DeltaChannel(value.reducer, {\n          snapshotFrequency: value.snapshotFrequency,\n          initialValueFactory: defaultGetter,\n        });\n      } else if (ReducedValue.isInstance(value)) {\n        // ReducedValue -> BinaryOperatorAggregate\n        const defaultGetter = getSchemaDefaultGetter(value.valueSchema);\n        channels[key] = new BinaryOperatorAggregate(\n          value.reducer,\n          defaultGetter\n        );\n      } else if (UntrackedValue.isInstance(value)) {\n        // UntrackedValue -> UntrackedValueChannel\n        const defaultGetter = value.schema\n          ? getSchemaDefaultGetter(value.schema)\n          : undefined;\n        channels[key] = new UntrackedValueChannel({\n          guard: value.guard,\n          initialValueFactory: defaultGetter,\n        });\n      } else if (isStandardSchema(value)) {\n        // Plain schema -> LastValue channel\n        const defaultGetter = getSchemaDefaultGetter(value);\n        channels[key] = new LastValue(defaultGetter);\n      } else {\n        throw new Error(\n          `Invalid state field \"${key}\": must be a schema, ReducedValue, DeltaValue, UntrackedValue, or ManagedValue`\n        );\n      }\n    }\n\n    return channels;\n  }\n\n  /**\n   * Get the JSON schema for the full state type.\n   * Used by Studio and API for schema introspection.\n   */\n  getJsonSchema(): JSONSchema {\n    const properties: Record<string, JSONSchema> = {};\n    const required: string[] = [];\n\n    for (const [key, value] of Object.entries(this.fields)) {\n      let fieldSchema: JSONSchema | undefined;\n\n      if (DeltaValue.isInstance(value) || ReducedValue.isInstance(value)) {\n        fieldSchema = getJsonSchemaFromSchema(value.valueSchema) as JSONSchema;\n        // Merge jsonSchemaExtra (e.g. langgraph_type) into the field schema,\n        // even if base schema is undefined\n        if (value.jsonSchemaExtra) {\n          fieldSchema = { ...(fieldSchema ?? {}), ...value.jsonSchemaExtra };\n        }\n      } else if (UntrackedValue.isInstance(value)) {\n        fieldSchema = value.schema\n          ? (getJsonSchemaFromSchema(value.schema) as JSONSchema)\n          : undefined;\n      } else if (isStandardSchema(value)) {\n        fieldSchema = getJsonSchemaFromSchema(value) as JSONSchema;\n      }\n\n      if (fieldSchema) {\n        properties[key] = fieldSchema;\n\n        // Field is required if it doesn't have a default\n        let hasDefault = false;\n        if (DeltaValue.isInstance(value) || ReducedValue.isInstance(value)) {\n          hasDefault = getSchemaDefaultGetter(value.valueSchema) !== undefined;\n        } else if (UntrackedValue.isInstance(value)) {\n          hasDefault = value.schema\n            ? getSchemaDefaultGetter(value.schema) !== undefined\n            : false;\n        } else {\n          hasDefault = getSchemaDefaultGetter(value) !== undefined;\n        }\n\n        if (!hasDefault) {\n          required.push(key);\n        }\n      }\n    }\n\n    return {\n      type: \"object\",\n      properties,\n      required: required.length > 0 ? required : undefined,\n    };\n  }\n\n  /**\n   * Get the JSON schema for the update/input type.\n   * All fields are optional in updates.\n   */\n  getInputJsonSchema(): JSONSchema {\n    const properties: Record<string, JSONSchema> = {};\n\n    for (const [key, value] of Object.entries(this.fields)) {\n      let fieldSchema: JSONSchema | undefined;\n\n      if (DeltaValue.isInstance(value) || ReducedValue.isInstance(value)) {\n        // Use input schema for updates\n        fieldSchema = getJsonSchemaFromSchema(value.inputSchema) as JSONSchema;\n        // Merge jsonSchemaExtra (e.g. langgraph_type) into the field schema,\n        // even if base schema is undefined\n        if (value.jsonSchemaExtra) {\n          fieldSchema = { ...(fieldSchema ?? {}), ...value.jsonSchemaExtra };\n        }\n      } else if (UntrackedValue.isInstance(value)) {\n        fieldSchema = value.schema\n          ? (getJsonSchemaFromSchema(value.schema) as JSONSchema)\n          : undefined;\n      } else if (isStandardSchema(value)) {\n        fieldSchema = getJsonSchemaFromSchema(value) as JSONSchema;\n      }\n\n      if (fieldSchema) {\n        properties[key] = fieldSchema;\n      }\n    }\n\n    return {\n      type: \"object\",\n      properties,\n    };\n  }\n\n  /**\n   * Get the list of channel keys (excluding managed values).\n   */\n  getChannelKeys(): string[] {\n    return Object.entries(this.fields).map(([key]) => key);\n  }\n\n  /**\n   * Get all keys (channels + managed values).\n   */\n  getAllKeys(): string[] {\n    return Object.keys(this.fields);\n  }\n\n  /**\n   * Validate input data against the schema.\n   * This validates each field using its corresponding schema.\n   *\n   * @param data - The input data to validate\n   * @returns The validated data with coerced types\n   */\n  async validateInput<T>(data: T): Promise<T> {\n    if (data == null || typeof data !== \"object\") {\n      return data;\n    }\n\n    const result: Record<string, unknown> = {};\n\n    for (const [key, value] of Object.entries(data)) {\n      const fieldDef = this.fields[key];\n\n      if (fieldDef === undefined) {\n        // Unknown field, pass through\n        result[key] = value;\n        continue;\n      }\n\n      // Get the schema to use for validation\n      let schema: StandardSchemaV1 | undefined;\n\n      if (\n        DeltaValue.isInstance(fieldDef) ||\n        ReducedValue.isInstance(fieldDef)\n      ) {\n        const [isOverwrite, overwriteValue] = _getOverwriteValue(value);\n        if (isOverwrite) {\n          schema = fieldDef.valueSchema;\n          const validationResult =\n            await schema[\"~standard\"].validate(overwriteValue);\n          if (validationResult.issues) {\n            throw new Error(\n              `Validation failed for field \"${key}\": ${JSON.stringify(\n                validationResult.issues\n              )}`\n            );\n          }\n          result[key] = { [OVERWRITE]: validationResult.value };\n          continue;\n        }\n\n        schema = fieldDef.inputSchema;\n      } else if (UntrackedValue.isInstance(fieldDef)) {\n        schema = fieldDef.schema;\n      } else if (isStandardSchema(fieldDef)) {\n        schema = fieldDef;\n      }\n\n      if (schema) {\n        // Validate using standard schema\n        const validationResult = await schema[\"~standard\"].validate(value);\n        if (validationResult.issues) {\n          throw new Error(\n            `Validation failed for field \"${key}\": ${JSON.stringify(\n              validationResult.issues\n            )}`\n          );\n        }\n        result[key] = validationResult.value;\n      } else {\n        // No schema or not a standard schema, pass through\n        result[key] = value;\n      }\n    }\n\n    return result as T;\n  }\n\n  /**\n   * Type guard to check if a value is a StateSchema instance.\n   *\n   * @param value - The value to check.\n   * @returns True if the value is a StateSchema instance with the correct runtime tag.\n   */\n  static isInstance<TFields extends StateSchemaFields>(\n    value: StateSchema<TFields>\n  ): value is StateSchema<TFields>;\n\n  static isInstance(value: unknown): value is StateSchema<any>;\n\n  static isInstance<TFields extends StateSchemaFields>(\n    value: unknown\n  ): value is StateSchema<TFields> {\n    return (\n      typeof value === \"object\" &&\n      value !== null &&\n      STATE_SCHEMA_SYMBOL in value &&\n      value[STATE_SCHEMA_SYMBOL] === true\n    );\n  }\n}\n\nexport type AnyStateSchema = StateSchema<any>;\n"],"mappings":"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"}

package/dist/state/values/delta.cjs

@@ -0,0 +1,77 @@
+//#region src/state/values/delta.ts
+/**
+* Symbol for runtime identification of DeltaValue instances.
+*/
+const DELTA_VALUE_SYMBOL = Symbol.for("langgraph.state.delta_value");
+/**
+* Represents a state field backed by a {@link DeltaChannel}.
+*
+* Unlike {@link ReducedValue} (which stores the full accumulated value in every
+* checkpoint blob via `BinaryOperatorAggregate`), a `DeltaValue` field persists
+* only per-step deltas (plus periodic snapshots) and reconstructs its state on
+* read by replaying ancestor writes through a batch reducer. This avoids
+* re-serializing large accumulators (e.g. long message histories) at every step.
+*
+* @remarks Beta. The on-disk representation backing `DeltaChannel` may change in
+* future releases.
+*
+* @template Value - The type of the value stored in state and produced by reduction.
+* @template Input - The type of updates accepted by the reducer.
+*
+* @example
+* ```ts
+* import { z } from "zod";
+* import { StateSchema, DeltaValue } from "@langchain/langgraph";
+*
+* const State = new StateSchema({
+*   history: new DeltaValue(z.array(z.string()).default(() => []), {
+*     inputSchema: z.string(),
+*     reducer: (current, writes) => [...current, ...writes],
+*   }),
+* });
+* ```
+*/
+var DeltaValue = class {
+	/**
+	* Instance marker for runtime identification.
+	* @internal
+	*/
+	[DELTA_VALUE_SYMBOL] = true;
+	/**
+	* The schema that describes the type of value stored in state (after
+	* reduction). Its default (if any) seeds the channel's initial value.
+	*/
+	valueSchema;
+	/**
+	* The schema used to validate reducer inputs. Defaults to `valueSchema` when
+	* not specified explicitly.
+	*/
+	inputSchema;
+	/**
+	* The batch reducer that folds a list of incoming writes into the current
+	* accumulated value.
+	*/
+	reducer;
+	/**
+	* Snapshot cadence forwarded to the underlying {@link DeltaChannel}.
+	*/
+	snapshotFrequency;
+	/**
+	* Optional extra fields to merge into the generated JSON Schema.
+	*/
+	jsonSchemaExtra;
+	constructor(valueSchema, init) {
+		this.reducer = init.reducer;
+		this.valueSchema = valueSchema;
+		this.inputSchema = "inputSchema" in init ? init.inputSchema : valueSchema;
+		this.snapshotFrequency = init.snapshotFrequency;
+		this.jsonSchemaExtra = init.jsonSchemaExtra;
+	}
+	static isInstance(value) {
+		return typeof value === "object" && value !== null && DELTA_VALUE_SYMBOL in value && value[DELTA_VALUE_SYMBOL] === true;
+	}
+};
+//#endregion
+exports.DeltaValue = DeltaValue;
+
+//# sourceMappingURL=delta.cjs.map

package/dist/state/values/delta.cjs.map

@@ -0,0 +1 @@
+{"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"}

package/dist/state/values/delta.d.cts

@@ -0,0 +1,152 @@
+import { DeltaReducer } from "../../channels/delta.cjs";
+import { SerializableSchema } from "../types.cjs";
+
+//#region src/state/values/delta.d.ts
+/**
+ * Symbol for runtime identification of DeltaValue instances.
+ */
+declare const DELTA_VALUE_SYMBOL: symbol;
+interface DeltaValueInitBase<Value = unknown> {
+  /**
+   * Batch reducer that combines the current accumulated value with a batch of
+   * writes in a single call: `reducer(state, [w1, w2, ...]) -> newState`.
+   *
+   * Reducers must be deterministic and batching-invariant (associative across
+   * folds), because {@link DeltaChannel} replays checkpointed writes in larger
+   * batches than they were originally produced:
+   * `reducer(reducer(state, xs), ys) === reducer(state, xs.concat(ys))`.
+   */
+  reducer: DeltaReducer<Value, Value>;
+  /**
+   * How often (in per-channel updates) to persist a full `DeltaSnapshot` blob
+   * instead of relying purely on replayed deltas. Defaults to the channel's
+   * own default (1000) when omitted.
+   */
+  snapshotFrequency?: number;
+  /**
+   * Optional extra fields merged into the generated JSON Schema (e.g.
+   * `langgraph_type`) for documentation, Studio hints, or external tooling.
+   */
+  jsonSchemaExtra?: Record<string, unknown>;
+}
+interface DeltaValueInitWithSchema<Value = unknown, Input = Value> {
+  /**
+   * Schema describing the type and validation logic for reducer input values.
+   *
+   * When provided, the reducer may accept inputs distinct from the stored
+   * (output) type. Each write is validated against this schema before reduction.
+   */
+  inputSchema: SerializableSchema<unknown, Input>;
+  /**
+   * Batch reducer that combines the current accumulated value with a batch of
+   * validated writes: `reducer(state, [w1, w2, ...]) -> newState`.
+   *
+   * Must be deterministic and batching-invariant — see
+   * {@link DeltaValueInitBase.reducer}.
+   */
+  reducer: DeltaReducer<Value, Input>;
+  /**
+   * How often (in per-channel updates) to persist a full `DeltaSnapshot` blob.
+   * Defaults to the channel's own default (1000) when omitted.
+   */
+  snapshotFrequency?: number;
+  /**
+   * Optional extra fields merged into the generated JSON Schema (e.g.
+   * `langgraph_type`) for documentation, Studio hints, or external tooling.
+   */
+  jsonSchemaExtra?: Record<string, unknown>;
+}
+/**
+ * Initialization options for {@link DeltaValue}.
+ *
+ * Two forms are supported:
+ * 1. Provide only a reducer (and optionally `snapshotFrequency` /
+ *    `jsonSchemaExtra`) — the reducer's inputs are validated using the value
+ *    schema.
+ * 2. Provide an explicit `inputSchema` to distinguish the reducer's input type
+ *    from the stored/output type.
+ *
+ * @template Value - The type of value stored and produced after reduction.
+ * @template Input - The type of inputs accepted by the reducer.
+ */
+type DeltaValueInit<Value = unknown, Input = Value> = DeltaValueInitWithSchema<Value, Input> | DeltaValueInitBase<Value>;
+/**
+ * Represents a state field backed by a {@link DeltaChannel}.
+ *
+ * Unlike {@link ReducedValue} (which stores the full accumulated value in every
+ * checkpoint blob via `BinaryOperatorAggregate`), a `DeltaValue` field persists
+ * only per-step deltas (plus periodic snapshots) and reconstructs its state on
+ * read by replaying ancestor writes through a batch reducer. This avoids
+ * re-serializing large accumulators (e.g. long message histories) at every step.
+ *
+ * @remarks Beta. The on-disk representation backing `DeltaChannel` may change in
+ * future releases.
+ *
+ * @template Value - The type of the value stored in state and produced by reduction.
+ * @template Input - The type of updates accepted by the reducer.
+ *
+ * @example
+ * ```ts
+ * import { z } from "zod";
+ * import { StateSchema, DeltaValue } from "@langchain/langgraph";
+ *
+ * const State = new StateSchema({
+ *   history: new DeltaValue(z.array(z.string()).default(() => []), {
+ *     inputSchema: z.string(),
+ *     reducer: (current, writes) => [...current, ...writes],
+ *   }),
+ * });
+ * ```
+ */
+declare class DeltaValue<Value = unknown, Input = Value> {
+  readonly [DELTA_VALUE_SYMBOL]: true;
+  /**
+   * The schema that describes the type of value stored in state (after
+   * reduction). Its default (if any) seeds the channel's initial value.
+   */
+  readonly valueSchema: SerializableSchema<unknown, Value>;
+  /**
+   * The schema used to validate reducer inputs. Defaults to `valueSchema` when
+   * not specified explicitly.
+   */
+  readonly inputSchema: SerializableSchema<unknown, Input | Value>;
+  /**
+   * The batch reducer that folds a list of incoming writes into the current
+   * accumulated value.
+   */
+  readonly reducer: DeltaReducer<Value, Input>;
+  /**
+   * Snapshot cadence forwarded to the underlying {@link DeltaChannel}.
+   */
+  readonly snapshotFrequency?: number;
+  /**
+   * Optional extra fields to merge into the generated JSON Schema.
+   */
+  readonly jsonSchemaExtra?: Record<string, unknown>;
+  /**
+   * Represents the value stored after all reductions.
+   */
+  ValueType: Value;
+  /**
+   * Represents the type that may be provided as input on each update.
+   */
+  InputType: Input;
+  /**
+   * Constructs a DeltaValue, pairing a value schema with a batch reducer (and an
+   * optional distinct input schema).
+   *
+   * @param valueSchema - The schema describing the stored/output value.
+   * @param init - The reducer (required), `inputSchema`, `snapshotFrequency`,
+   *   and `jsonSchemaExtra` (all optional except the reducer).
+   */
+  constructor(valueSchema: SerializableSchema<unknown, Value>, init: DeltaValueInitWithSchema<Value, Input>);
+  constructor(valueSchema: SerializableSchema<Input, Value>, init: DeltaValueInitBase<Value>);
+  /**
+   * Type guard to check if a value is a DeltaValue instance.
+   */
+  static isInstance<Value = unknown, Input = Value>(value: DeltaValue<Value, Input>): value is DeltaValue<Value, Input>;
+  static isInstance(value: unknown): value is DeltaValue;
+}
+//#endregion
+export { DeltaValue, DeltaValueInit };
+//# sourceMappingURL=delta.d.cts.map

package/dist/state/values/delta.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delta.d.cts","names":[],"sources":["../../../src/state/values/delta.ts"],"mappings":";;;;;;AAMA;cAAa,kBAAA;AAAA,UAIH,kBAAA;EAFT;;AAAC;;;;;;;EAYA,OAAA,EAAS,YAAA,CAAa,KAAA,EAAO,KAAA;EAaL;;;;;EANxB,iBAAA;EAAA;;;;EAMA,eAAA,GAAkB,MAAA;AAAA;AAAA,UAGV,wBAAA,0BAAkD,KAAA;EAA1B;;;;;;EAOhC,WAAA,EAAa,kBAAA,UAA4B,KAAA;EAqBvB;;;;;;;EAZlB,OAAA,EAAS,YAAA,CAAa,KAAA,EAAO,KAAA;EATY;;;;EAezC,iBAAA;EAAA;;;;EAMA,eAAA,GAAkB,MAAA;AAAA;;;;;;;;;;;;;;KAgBR,cAAA,0BAAwC,KAAA,IAChD,wBAAA,CAAyB,KAAA,EAAO,KAAA,IAChC,kBAAA,CAAmB,KAAA;;;;;;;AA8BvB;;;;;;;;;;;;;;;;;;;;;;cAAa,UAAA,0BAAoC,KAAA;EAAA,UAK3B,kBAAA;EAuDO;;;;EAAA,SAjDlB,WAAA,EAAa,kBAAA,UAA4B,KAAA;EAmEzC;;;;EAAA,SA7DA,WAAA,EAAa,kBAAA,UAA4B,KAAA,GAAQ,KAAA;EAgEJ;;;;EAAA,SA1D7C,OAAA,EAAS,YAAA,CAAa,KAAA,EAAO,KAAA;EAlBlB;;;EAAA,SAuBX,iBAAA;EAXA;;;EAAA,SAgBA,eAAA,GAAkB,MAAA;EAVlB;;;EAeD,SAAA,EAAW,KAAA;EAVV;;;EAeD,SAAA,EAAW,KAAA;EALA;;;;;;;;EAenB,WAAA,CACE,WAAA,EAAa,kBAAA,UAA4B,KAAA,GACzC,IAAA,EAAM,wBAAA,CAAyB,KAAA,EAAO,KAAA;EAGxC,WAAA,CACE,WAAA,EAAa,kBAAA,CAAmB,KAAA,EAAO,KAAA,GACvC,IAAA,EAAM,kBAAA,CAAmB,KAAA;EALzB;;;EAAA,OAsBK,UAAA,0BAAoC,KAAA,CAAA,CACzC,KAAA,EAAO,UAAA,CAAW,KAAA,EAAO,KAAA,IACxB,KAAA,IAAS,UAAA,CAAW,KAAA,EAAO,KAAA;EAAA,OAEvB,UAAA,CAAW,KAAA,YAAiB,KAAA,IAAS,UAAA;AAAA"}

package/dist/state/values/delta.d.ts

@@ -0,0 +1,152 @@
+import { DeltaReducer } from "../../channels/delta.js";
+import { SerializableSchema } from "../types.js";
+
+//#region src/state/values/delta.d.ts
+/**
+ * Symbol for runtime identification of DeltaValue instances.
+ */
+declare const DELTA_VALUE_SYMBOL: symbol;
+interface DeltaValueInitBase<Value = unknown> {
+  /**
+   * Batch reducer that combines the current accumulated value with a batch of
+   * writes in a single call: `reducer(state, [w1, w2, ...]) -> newState`.
+   *
+   * Reducers must be deterministic and batching-invariant (associative across
+   * folds), because {@link DeltaChannel} replays checkpointed writes in larger
+   * batches than they were originally produced:
+   * `reducer(reducer(state, xs), ys) === reducer(state, xs.concat(ys))`.
+   */
+  reducer: DeltaReducer<Value, Value>;
+  /**
+   * How often (in per-channel updates) to persist a full `DeltaSnapshot` blob
+   * instead of relying purely on replayed deltas. Defaults to the channel's
+   * own default (1000) when omitted.
+   */
+  snapshotFrequency?: number;
+  /**
+   * Optional extra fields merged into the generated JSON Schema (e.g.
+   * `langgraph_type`) for documentation, Studio hints, or external tooling.
+   */
+  jsonSchemaExtra?: Record<string, unknown>;
+}
+interface DeltaValueInitWithSchema<Value = unknown, Input = Value> {
+  /**
+   * Schema describing the type and validation logic for reducer input values.
+   *
+   * When provided, the reducer may accept inputs distinct from the stored
+   * (output) type. Each write is validated against this schema before reduction.
+   */
+  inputSchema: SerializableSchema<unknown, Input>;
+  /**
+   * Batch reducer that combines the current accumulated value with a batch of
+   * validated writes: `reducer(state, [w1, w2, ...]) -> newState`.
+   *
+   * Must be deterministic and batching-invariant — see
+   * {@link DeltaValueInitBase.reducer}.
+   */
+  reducer: DeltaReducer<Value, Input>;
+  /**
+   * How often (in per-channel updates) to persist a full `DeltaSnapshot` blob.
+   * Defaults to the channel's own default (1000) when omitted.
+   */
+  snapshotFrequency?: number;
+  /**
+   * Optional extra fields merged into the generated JSON Schema (e.g.
+   * `langgraph_type`) for documentation, Studio hints, or external tooling.
+   */
+  jsonSchemaExtra?: Record<string, unknown>;
+}
+/**
+ * Initialization options for {@link DeltaValue}.
+ *
+ * Two forms are supported:
+ * 1. Provide only a reducer (and optionally `snapshotFrequency` /
+ *    `jsonSchemaExtra`) — the reducer's inputs are validated using the value
+ *    schema.
+ * 2. Provide an explicit `inputSchema` to distinguish the reducer's input type
+ *    from the stored/output type.
+ *
+ * @template Value - The type of value stored and produced after reduction.
+ * @template Input - The type of inputs accepted by the reducer.
+ */
+type DeltaValueInit<Value = unknown, Input = Value> = DeltaValueInitWithSchema<Value, Input> | DeltaValueInitBase<Value>;
+/**
+ * Represents a state field backed by a {@link DeltaChannel}.
+ *
+ * Unlike {@link ReducedValue} (which stores the full accumulated value in every
+ * checkpoint blob via `BinaryOperatorAggregate`), a `DeltaValue` field persists
+ * only per-step deltas (plus periodic snapshots) and reconstructs its state on
+ * read by replaying ancestor writes through a batch reducer. This avoids
+ * re-serializing large accumulators (e.g. long message histories) at every step.
+ *
+ * @remarks Beta. The on-disk representation backing `DeltaChannel` may change in
+ * future releases.
+ *
+ * @template Value - The type of the value stored in state and produced by reduction.
+ * @template Input - The type of updates accepted by the reducer.
+ *
+ * @example
+ * ```ts
+ * import { z } from "zod";
+ * import { StateSchema, DeltaValue } from "@langchain/langgraph";
+ *
+ * const State = new StateSchema({
+ *   history: new DeltaValue(z.array(z.string()).default(() => []), {
+ *     inputSchema: z.string(),
+ *     reducer: (current, writes) => [...current, ...writes],
+ *   }),
+ * });
+ * ```
+ */
+declare class DeltaValue<Value = unknown, Input = Value> {
+  readonly [DELTA_VALUE_SYMBOL]: true;
+  /**
+   * The schema that describes the type of value stored in state (after
+   * reduction). Its default (if any) seeds the channel's initial value.
+   */
+  readonly valueSchema: SerializableSchema<unknown, Value>;
+  /**
+   * The schema used to validate reducer inputs. Defaults to `valueSchema` when
+   * not specified explicitly.
+   */
+  readonly inputSchema: SerializableSchema<unknown, Input | Value>;
+  /**
+   * The batch reducer that folds a list of incoming writes into the current
+   * accumulated value.
+   */
+  readonly reducer: DeltaReducer<Value, Input>;
+  /**
+   * Snapshot cadence forwarded to the underlying {@link DeltaChannel}.
+   */
+  readonly snapshotFrequency?: number;
+  /**
+   * Optional extra fields to merge into the generated JSON Schema.
+   */
+  readonly jsonSchemaExtra?: Record<string, unknown>;
+  /**
+   * Represents the value stored after all reductions.
+   */
+  ValueType: Value;
+  /**
+   * Represents the type that may be provided as input on each update.
+   */
+  InputType: Input;
+  /**
+   * Constructs a DeltaValue, pairing a value schema with a batch reducer (and an
+   * optional distinct input schema).
+   *
+   * @param valueSchema - The schema describing the stored/output value.
+   * @param init - The reducer (required), `inputSchema`, `snapshotFrequency`,
+   *   and `jsonSchemaExtra` (all optional except the reducer).
+   */
+  constructor(valueSchema: SerializableSchema<unknown, Value>, init: DeltaValueInitWithSchema<Value, Input>);
+  constructor(valueSchema: SerializableSchema<Input, Value>, init: DeltaValueInitBase<Value>);
+  /**
+   * Type guard to check if a value is a DeltaValue instance.
+   */
+  static isInstance<Value = unknown, Input = Value>(value: DeltaValue<Value, Input>): value is DeltaValue<Value, Input>;
+  static isInstance(value: unknown): value is DeltaValue;
+}
+//#endregion
+export { DeltaValue, DeltaValueInit };
+//# sourceMappingURL=delta.d.ts.map

package/dist/state/values/delta.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delta.d.ts","names":[],"sources":["../../../src/state/values/delta.ts"],"mappings":";;;;;;AAMA;cAAa,kBAAA;AAAA,UAIH,kBAAA;EAFT;;AAAC;;;;;;;EAYA,OAAA,EAAS,YAAA,CAAa,KAAA,EAAO,KAAA;EAaL;;;;;EANxB,iBAAA;EAAA;;;;EAMA,eAAA,GAAkB,MAAA;AAAA;AAAA,UAGV,wBAAA,0BAAkD,KAAA;EAA1B;;;;;;EAOhC,WAAA,EAAa,kBAAA,UAA4B,KAAA;EAqBvB;;;;;;;EAZlB,OAAA,EAAS,YAAA,CAAa,KAAA,EAAO,KAAA;EATY;;;;EAezC,iBAAA;EAAA;;;;EAMA,eAAA,GAAkB,MAAA;AAAA;;;;;;;;;;;;;;KAgBR,cAAA,0BAAwC,KAAA,IAChD,wBAAA,CAAyB,KAAA,EAAO,KAAA,IAChC,kBAAA,CAAmB,KAAA;;;;;;;AA8BvB;;;;;;;;;;;;;;;;;;;;;;cAAa,UAAA,0BAAoC,KAAA;EAAA,UAK3B,kBAAA;EAuDO;;;;EAAA,SAjDlB,WAAA,EAAa,kBAAA,UAA4B,KAAA;EAmEzC;;;;EAAA,SA7DA,WAAA,EAAa,kBAAA,UAA4B,KAAA,GAAQ,KAAA;EAgEJ;;;;EAAA,SA1D7C,OAAA,EAAS,YAAA,CAAa,KAAA,EAAO,KAAA;EAlBlB;;;EAAA,SAuBX,iBAAA;EAXA;;;EAAA,SAgBA,eAAA,GAAkB,MAAA;EAVlB;;;EAeD,SAAA,EAAW,KAAA;EAVV;;;EAeD,SAAA,EAAW,KAAA;EALA;;;;;;;;EAenB,WAAA,CACE,WAAA,EAAa,kBAAA,UAA4B,KAAA,GACzC,IAAA,EAAM,wBAAA,CAAyB,KAAA,EAAO,KAAA;EAGxC,WAAA,CACE,WAAA,EAAa,kBAAA,CAAmB,KAAA,EAAO,KAAA,GACvC,IAAA,EAAM,kBAAA,CAAmB,KAAA;EALzB;;;EAAA,OAsBK,UAAA,0BAAoC,KAAA,CAAA,CACzC,KAAA,EAAO,UAAA,CAAW,KAAA,EAAO,KAAA,IACxB,KAAA,IAAS,UAAA,CAAW,KAAA,EAAO,KAAA;EAAA,OAEvB,UAAA,CAAW,KAAA,YAAiB,KAAA,IAAS,UAAA;AAAA"}

package/dist/state/values/delta.js

@@ -0,0 +1,77 @@
+//#region src/state/values/delta.ts
+/**
+* Symbol for runtime identification of DeltaValue instances.
+*/
+const DELTA_VALUE_SYMBOL = Symbol.for("langgraph.state.delta_value");
+/**
+* Represents a state field backed by a {@link DeltaChannel}.
+*
+* Unlike {@link ReducedValue} (which stores the full accumulated value in every
+* checkpoint blob via `BinaryOperatorAggregate`), a `DeltaValue` field persists
+* only per-step deltas (plus periodic snapshots) and reconstructs its state on
+* read by replaying ancestor writes through a batch reducer. This avoids
+* re-serializing large accumulators (e.g. long message histories) at every step.
+*
+* @remarks Beta. The on-disk representation backing `DeltaChannel` may change in
+* future releases.
+*
+* @template Value - The type of the value stored in state and produced by reduction.
+* @template Input - The type of updates accepted by the reducer.
+*
+* @example
+* ```ts
+* import { z } from "zod";
+* import { StateSchema, DeltaValue } from "@langchain/langgraph";
+*
+* const State = new StateSchema({
+*   history: new DeltaValue(z.array(z.string()).default(() => []), {
+*     inputSchema: z.string(),
+*     reducer: (current, writes) => [...current, ...writes],
+*   }),
+* });
+* ```
+*/
+var DeltaValue = class {
+	/**
+	* Instance marker for runtime identification.
+	* @internal
+	*/
+	[DELTA_VALUE_SYMBOL] = true;
+	/**
+	* The schema that describes the type of value stored in state (after
+	* reduction). Its default (if any) seeds the channel's initial value.
+	*/
+	valueSchema;
+	/**
+	* The schema used to validate reducer inputs. Defaults to `valueSchema` when
+	* not specified explicitly.
+	*/
+	inputSchema;
+	/**
+	* The batch reducer that folds a list of incoming writes into the current
+	* accumulated value.
+	*/
+	reducer;
+	/**
+	* Snapshot cadence forwarded to the underlying {@link DeltaChannel}.
+	*/
+	snapshotFrequency;
+	/**
+	* Optional extra fields to merge into the generated JSON Schema.
+	*/
+	jsonSchemaExtra;
+	constructor(valueSchema, init) {
+		this.reducer = init.reducer;
+		this.valueSchema = valueSchema;
+		this.inputSchema = "inputSchema" in init ? init.inputSchema : valueSchema;
+		this.snapshotFrequency = init.snapshotFrequency;
+		this.jsonSchemaExtra = init.jsonSchemaExtra;
+	}
+	static isInstance(value) {
+		return typeof value === "object" && value !== null && DELTA_VALUE_SYMBOL in value && value[DELTA_VALUE_SYMBOL] === true;
+	}
+};
+//#endregion
+export { DeltaValue };
+
+//# sourceMappingURL=delta.js.map