@langchain/langgraph 1.0.14 → 1.1.0

package/dist/state/types.d.ts

@@ -0,0 +1,128 @@
+import { StandardJSONSchemaV1, StandardSchemaV1, StandardTypedV1 } from "@standard-schema/spec";
+
+//#region src/state/types.d.ts
+interface CombinedProps<Input = unknown, Output = Input> extends StandardSchemaV1.Props<Input, Output>, StandardJSONSchemaV1.Props<Input, Output> {}
+/**
+ * SerializableSchema is the core interface for any schema used by LangGraph state.
+ *
+ * @template Input - The type of input data the schema can be used to validate.
+ * @template Output - The type of output produced after validation, post-refinement/coercion.
+ *
+ * @remarks
+ * - SerializableSchema provides a single property, `~standard`, which must conform to
+ *   both `StandardSchemaV1.Props` and `StandardJSONSchemaV1.Props`.
+ * - This ensures all schemas are compatible with both runtime validation (e.g., type checks,
+ *   coercion, custom refinements) and structured schema export/generation (e.g., producing
+ *   a compatible JSON Schema).
+ * - A value matching SerializableSchema can be passed directly to LangGraph state
+ *   definitions, reducers, or other schema-accepting APIs.
+ *
+ * @example
+ * ```ts
+ * import { z } from "zod";
+ *
+ * // complies with SerializableSchema
+ * const zodSchema = z.object({ x: z.string() });
+ *
+ * // Use in a StateObject definition:
+ * const AgentState = new StateObject({
+ *   data: schema
+ * });
+ * ```
+ */
+interface SerializableSchema<Input = unknown, Output = Input> {
+  "~standard": CombinedProps<Input, Output>;
+}
+declare namespace SerializableSchema {
+  /**
+   * Infers the type of input expected by a SerializableSchema.
+   *
+   * @template T - A SerializableSchema instance.
+   * @returns The type of data that may be passed to the schema for validation.
+   *
+   * @example
+   * ```ts
+   * type MyInput = SerializableSchema.InferInput<typeof schema>;
+   * ```
+   */
+  type InferInput<T extends SerializableSchema> = StandardTypedV1.InferInput<T>;
+  /**
+   * Infers the output type yielded by a SerializableSchema, after parsing or coercion.
+   *
+   * @template T - A SerializableSchema instance.
+   * @returns The type produced by successfully validating/coercing input data.
+   *
+   * @example
+   * ```ts
+   * type MyOutput = SerializableSchema.InferOutput<typeof schema>;
+   * ```
+   */
+  type InferOutput<T extends SerializableSchema> = StandardTypedV1.InferOutput<T>;
+}
+/**
+ * Type guard to check if a given value is a Standard Schema V1 object.
+ *
+ * @remarks
+ * A Standard Schema object is expected to have a `~standard` property with a `validate` function.
+ * This guard does NOT check for JSON schema support.
+ *
+ * @typeParam Input - The type of input validated by this schema.
+ * @typeParam Output - The type of output produced after validation.
+ * @param schema - The value to test.
+ * @returns True if the schema conforms to the Standard Schema interface.
+ *
+ * @example
+ * ```ts
+ * if (isStandardSchema(mySchema)) {
+ *   const result = mySchema["~standard"].validate(input);
+ * }
+ * ```
+ */
+declare function isStandardSchema<Input = unknown, Output = Input>(schema: StandardSchemaV1<Input, Output>): schema is StandardSchemaV1<Input, Output>;
+declare function isStandardSchema<Input = unknown, Output = Input>(schema: unknown): schema is StandardSchemaV1<Input, Output>;
+/**
+ * Type guard to check if a given value is a Standard JSON Schema V1 object.
+ *
+ * @remarks
+ * A Standard JSON Schema object is expected to have a `~standard` property with a `jsonSchema` function.
+ * This may be used to generate a JSON Schema (for UI/form tooling, documentation, etc).
+ *
+ * @typeParam Input - The type of input described by this JSON schema.
+ * @typeParam Output - The type of output described by this JSON schema.
+ * @param schema - The value to test.
+ * @returns True if the schema exposes JSON schema generation.
+ *
+ * @example
+ * ```ts
+ * if (isStandardJSONSchema(mySchema)) {
+ *   const jschema = mySchema["~standard"].jsonSchema();
+ * }
+ * ```
+ */
+
+/**
+ * Type guard to check if a given value is a `SerializableSchema`, i.e.
+ * both a Standard Schema and a Standard JSON Schema object.
+ *
+ * @remarks
+ * This checks for both the presence of a Standard Schema V1 interface
+ * and the ability to generate a JSON schema.
+ *
+ * @typeParam Input - The type of input described by the schema.
+ * @typeParam Output - The type of output described by the schema.
+ * @param schema - The value to test.
+ * @returns True if the schema is a valid `SerializableSchema`.
+ *
+ * @example
+ * ```ts
+ * if (isSerializableSchema(schema)) {
+ *   schema["~standard"].validate(data);
+ *   const json = schema["~standard"].jsonSchema();
+ * }
+ * ```
+ */
+declare function isSerializableSchema<Input = unknown, Output = Input>(schema: SerializableSchema<Input, Output>): schema is SerializableSchema<Input, Output>;
+declare function isSerializableSchema<Input = unknown, Output = Input>(schema: unknown): schema is SerializableSchema<Input, Output>;
+//#endregion
+export { SerializableSchema, isSerializableSchema, isStandardSchema };
+//# sourceMappingURL=types.d.ts.map

package/dist/state/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","names":["StandardSchemaV1","StandardJSONSchemaV1","StandardTypedV1","CombinedProps","Input","Output","Props","SerializableSchema","T","InferInput","InferOutput","isStandardSchema","isStandardJSONSchema","isSerializableSchema"],"sources":["../../src/state/types.d.ts"],"sourcesContent":["import type { StandardSchemaV1, StandardJSONSchemaV1, StandardTypedV1 } from \"@standard-schema/spec\";\ninterface CombinedProps<Input = unknown, Output = Input> extends StandardSchemaV1.Props<Input, Output>, StandardJSONSchemaV1.Props<Input, Output> {\n}\n/**\n * SerializableSchema is the core interface for any schema used by LangGraph state.\n *\n * @template Input - The type of input data the schema can be used to validate.\n * @template Output - The type of output produced after validation, post-refinement/coercion.\n *\n * @remarks\n * - SerializableSchema provides a single property, `~standard`, which must conform to\n *   both `StandardSchemaV1.Props` and `StandardJSONSchemaV1.Props`.\n * - This ensures all schemas are compatible with both runtime validation (e.g., type checks,\n *   coercion, custom refinements) and structured schema export/generation (e.g., producing\n *   a compatible JSON Schema).\n * - A value matching SerializableSchema can be passed directly to LangGraph state\n *   definitions, reducers, or other schema-accepting APIs.\n *\n * @example\n * ```ts\n * import { z } from \"zod\";\n *\n * // complies with SerializableSchema\n * const zodSchema = z.object({ x: z.string() });\n *\n * // Use in a StateObject definition:\n * const AgentState = new StateObject({\n *   data: schema\n * });\n * ```\n */\nexport interface SerializableSchema<Input = unknown, Output = Input> {\n    \"~standard\": CombinedProps<Input, Output>;\n}\nexport declare namespace SerializableSchema {\n    /**\n     * Infers the type of input expected by a SerializableSchema.\n     *\n     * @template T - A SerializableSchema instance.\n     * @returns The type of data that may be passed to the schema for validation.\n     *\n     * @example\n     * ```ts\n     * type MyInput = SerializableSchema.InferInput<typeof schema>;\n     * ```\n     */\n    type InferInput<T extends SerializableSchema> = StandardTypedV1.InferInput<T>;\n    /**\n     * Infers the output type yielded by a SerializableSchema, after parsing or coercion.\n     *\n     * @template T - A SerializableSchema instance.\n     * @returns The type produced by successfully validating/coercing input data.\n     *\n     * @example\n     * ```ts\n     * type MyOutput = SerializableSchema.InferOutput<typeof schema>;\n     * ```\n     */\n    type InferOutput<T extends SerializableSchema> = StandardTypedV1.InferOutput<T>;\n}\n/**\n * Type guard to check if a given value is a Standard Schema V1 object.\n *\n * @remarks\n * A Standard Schema object is expected to have a `~standard` property with a `validate` function.\n * This guard does NOT check for JSON schema support.\n *\n * @typeParam Input - The type of input validated by this schema.\n * @typeParam Output - The type of output produced after validation.\n * @param schema - The value to test.\n * @returns True if the schema conforms to the Standard Schema interface.\n *\n * @example\n * ```ts\n * if (isStandardSchema(mySchema)) {\n *   const result = mySchema[\"~standard\"].validate(input);\n * }\n * ```\n */\nexport declare function isStandardSchema<Input = unknown, Output = Input>(schema: StandardSchemaV1<Input, Output>): schema is StandardSchemaV1<Input, Output>;\nexport declare function isStandardSchema<Input = unknown, Output = Input>(schema: unknown): schema is StandardSchemaV1<Input, Output>;\n/**\n * Type guard to check if a given value is a Standard JSON Schema V1 object.\n *\n * @remarks\n * A Standard JSON Schema object is expected to have a `~standard` property with a `jsonSchema` function.\n * This may be used to generate a JSON Schema (for UI/form tooling, documentation, etc).\n *\n * @typeParam Input - The type of input described by this JSON schema.\n * @typeParam Output - The type of output described by this JSON schema.\n * @param schema - The value to test.\n * @returns True if the schema exposes JSON schema generation.\n *\n * @example\n * ```ts\n * if (isStandardJSONSchema(mySchema)) {\n *   const jschema = mySchema[\"~standard\"].jsonSchema();\n * }\n * ```\n */\nexport declare function isStandardJSONSchema<Input = unknown, Output = Input>(schema: StandardJSONSchemaV1<Input, Output>): schema is StandardJSONSchemaV1<Input, Output>;\nexport declare function isStandardJSONSchema<Input = unknown, Output = Input>(schema: unknown): schema is StandardJSONSchemaV1<Input, Output>;\n/**\n * Type guard to check if a given value is a `SerializableSchema`, i.e.\n * both a Standard Schema and a Standard JSON Schema object.\n *\n * @remarks\n * This checks for both the presence of a Standard Schema V1 interface\n * and the ability to generate a JSON schema.\n *\n * @typeParam Input - The type of input described by the schema.\n * @typeParam Output - The type of output described by the schema.\n * @param schema - The value to test.\n * @returns True if the schema is a valid `SerializableSchema`.\n *\n * @example\n * ```ts\n * if (isSerializableSchema(schema)) {\n *   schema[\"~standard\"].validate(data);\n *   const json = schema[\"~standard\"].jsonSchema();\n * }\n * ```\n */\nexport declare function isSerializableSchema<Input = unknown, Output = Input>(schema: SerializableSchema<Input, Output>): schema is SerializableSchema<Input, Output>;\nexport declare function isSerializableSchema<Input = unknown, Output = Input>(schema: unknown): schema is SerializableSchema<Input, Output>;\nexport {};\n"],"mappings":";;;UACUG,wCAAwCC,eAAeJ,gBAAAA,CAAiBM,MAAMF,OAAOC,SAASJ,oBAAAA,CAAqBK,MAAMF,OAAOC;AADrC;;;;;;;;;;AA+BrG;;;;;;;AAGA;;;;;;;;;AA6CA;;AAAmED,UAhDlDG,kBAgDkDH,CAAAA,QAAAA,OAAAA,EAAAA,SAhDLA,KAgDKA,CAAAA,CAAAA;aAAgCA,EA/ClFD,aA+CkFC,CA/CpEA,KA+CoEA,EA/C7DC,MA+C6DD,CAAAA;;AAAjBJ,kBA7CzDO,kBAAAA,CA6CyDP;;;;;AAClF;;;;;;;EA2CwBa,KAAAA,UAAAA,CAAAA,UA7EMN,kBA6Ec,CAAA,GA7EQL,eAAAA,CAAgBO,UA6ExB,CA7EmCD,CA6EnC,CAAA;EAAA;;;;;;;;;AAC5C;;OAAuEJ,WAAAA,CAAAA,UAlExCG,kBAkEwCH,CAAAA,GAlElBF,eAAAA,CAAgBQ,WAkEEN,CAlEUI,CAkEVJ,CAAAA;;;;;;;;;;;;;;;;;;;;;iBA7C/CO,2CAA2CP,eAAeJ,iBAAiBI,OAAOC,oBAAoBL,iBAAiBI,OAAOC;iBAC9HM,2CAA2CP,mCAAmCJ,iBAAiBI,OAAOC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA2CtGQ,+CAA+CT,eAAeG,mBAAmBH,OAAOC,oBAAoBE,mBAAmBH,OAAOC;iBACtIQ,+CAA+CT,mCAAmCG,mBAAmBH,OAAOC"}

package/dist/state/types.js

@@ -0,0 +1,14 @@
+//#region src/state/types.ts
+function isStandardSchema(schema) {
+	return typeof schema === "object" && schema !== null && "~standard" in schema && typeof schema["~standard"] === "object" && schema["~standard"] !== null && "validate" in schema["~standard"];
+}
+function isStandardJSONSchema(schema) {
+	return typeof schema === "object" && schema !== null && "~standard" in schema && typeof schema["~standard"] === "object" && schema["~standard"] !== null && "jsonSchema" in schema["~standard"];
+}
+function isSerializableSchema(schema) {
+	return isStandardSchema(schema) && isStandardJSONSchema(schema);
+}
+
+//#endregion
+export { isSerializableSchema, isStandardJSONSchema, isStandardSchema };
+//# sourceMappingURL=types.js.map

package/dist/state/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","names":[],"sources":["../../src/state/types.ts"],"sourcesContent":["import type {\n  StandardSchemaV1,\n  StandardJSONSchemaV1,\n  StandardTypedV1,\n} from \"@standard-schema/spec\";\n\ninterface CombinedProps<Input = unknown, Output = Input>\n  extends StandardSchemaV1.Props<Input, Output>,\n    StandardJSONSchemaV1.Props<Input, Output> {}\n\n/**\n * SerializableSchema is the core interface for any schema used by LangGraph state.\n *\n * @template Input - The type of input data the schema can be used to validate.\n * @template Output - The type of output produced after validation, post-refinement/coercion.\n *\n * @remarks\n * - SerializableSchema provides a single property, `~standard`, which must conform to\n *   both `StandardSchemaV1.Props` and `StandardJSONSchemaV1.Props`.\n * - This ensures all schemas are compatible with both runtime validation (e.g., type checks,\n *   coercion, custom refinements) and structured schema export/generation (e.g., producing\n *   a compatible JSON Schema).\n * - A value matching SerializableSchema can be passed directly to LangGraph state\n *   definitions, reducers, or other schema-accepting APIs.\n *\n * @example\n * ```ts\n * import { z } from \"zod\";\n *\n * // complies with SerializableSchema\n * const zodSchema = z.object({ x: z.string() });\n *\n * // Use in a StateObject definition:\n * const AgentState = new StateObject({\n *   data: schema\n * });\n * ```\n */\nexport interface SerializableSchema<Input = unknown, Output = Input> {\n  \"~standard\": CombinedProps<Input, Output>;\n}\n\n// eslint-disable-next-line @typescript-eslint/no-namespace\nexport declare namespace SerializableSchema {\n  /**\n   * Infers the type of input expected by a SerializableSchema.\n   *\n   * @template T - A SerializableSchema instance.\n   * @returns The type of data that may be passed to the schema for validation.\n   *\n   * @example\n   * ```ts\n   * type MyInput = SerializableSchema.InferInput<typeof schema>;\n   * ```\n   */\n  export type InferInput<T extends SerializableSchema> =\n    StandardTypedV1.InferInput<T>;\n\n  /**\n   * Infers the output type yielded by a SerializableSchema, after parsing or coercion.\n   *\n   * @template T - A SerializableSchema instance.\n   * @returns The type produced by successfully validating/coercing input data.\n   *\n   * @example\n   * ```ts\n   * type MyOutput = SerializableSchema.InferOutput<typeof schema>;\n   * ```\n   */\n  export type InferOutput<T extends SerializableSchema> =\n    StandardTypedV1.InferOutput<T>;\n}\n\n/**\n * Type guard to check if a given value is a Standard Schema V1 object.\n *\n * @remarks\n * A Standard Schema object is expected to have a `~standard` property with a `validate` function.\n * This guard does NOT check for JSON schema support.\n *\n * @typeParam Input - The type of input validated by this schema.\n * @typeParam Output - The type of output produced after validation.\n * @param schema - The value to test.\n * @returns True if the schema conforms to the Standard Schema interface.\n *\n * @example\n * ```ts\n * if (isStandardSchema(mySchema)) {\n *   const result = mySchema[\"~standard\"].validate(input);\n * }\n * ```\n */\nexport function isStandardSchema<Input = unknown, Output = Input>(\n  schema: StandardSchemaV1<Input, Output>\n): schema is StandardSchemaV1<Input, Output>;\nexport function isStandardSchema<Input = unknown, Output = Input>(\n  schema: unknown\n): schema is StandardSchemaV1<Input, Output>;\nexport function isStandardSchema<Input = unknown, Output = Input>(\n  schema: StandardSchemaV1<Input, Output> | unknown\n): schema is StandardSchemaV1<Input, Output> {\n  return (\n    typeof schema === \"object\" &&\n    schema !== null &&\n    \"~standard\" in schema &&\n    typeof schema[\"~standard\"] === \"object\" &&\n    schema[\"~standard\"] !== null &&\n    \"validate\" in schema[\"~standard\"]\n  );\n}\n\n/**\n * Type guard to check if a given value is a Standard JSON Schema V1 object.\n *\n * @remarks\n * A Standard JSON Schema object is expected to have a `~standard` property with a `jsonSchema` function.\n * This may be used to generate a JSON Schema (for UI/form tooling, documentation, etc).\n *\n * @typeParam Input - The type of input described by this JSON schema.\n * @typeParam Output - The type of output described by this JSON schema.\n * @param schema - The value to test.\n * @returns True if the schema exposes JSON schema generation.\n *\n * @example\n * ```ts\n * if (isStandardJSONSchema(mySchema)) {\n *   const jschema = mySchema[\"~standard\"].jsonSchema();\n * }\n * ```\n */\nexport function isStandardJSONSchema<Input = unknown, Output = Input>(\n  schema: StandardJSONSchemaV1<Input, Output>\n): schema is StandardJSONSchemaV1<Input, Output>;\nexport function isStandardJSONSchema<Input = unknown, Output = Input>(\n  schema: unknown\n): schema is StandardJSONSchemaV1<Input, Output>;\nexport function isStandardJSONSchema<Input = unknown, Output = Input>(\n  schema: StandardJSONSchemaV1<Input, Output> | unknown\n): schema is StandardJSONSchemaV1<Input, Output> {\n  return (\n    typeof schema === \"object\" &&\n    schema !== null &&\n    \"~standard\" in schema &&\n    typeof schema[\"~standard\"] === \"object\" &&\n    schema[\"~standard\"] !== null &&\n    \"jsonSchema\" in schema[\"~standard\"]\n  );\n}\n\n/**\n * Type guard to check if a given value is a `SerializableSchema`, i.e.\n * both a Standard Schema and a Standard JSON Schema object.\n *\n * @remarks\n * This checks for both the presence of a Standard Schema V1 interface\n * and the ability to generate a JSON schema.\n *\n * @typeParam Input - The type of input described by the schema.\n * @typeParam Output - The type of output described by the schema.\n * @param schema - The value to test.\n * @returns True if the schema is a valid `SerializableSchema`.\n *\n * @example\n * ```ts\n * if (isSerializableSchema(schema)) {\n *   schema[\"~standard\"].validate(data);\n *   const json = schema[\"~standard\"].jsonSchema();\n * }\n * ```\n */\nexport function isSerializableSchema<Input = unknown, Output = Input>(\n  schema: SerializableSchema<Input, Output>\n): schema is SerializableSchema<Input, Output>;\nexport function isSerializableSchema<Input = unknown, Output = Input>(\n  schema: unknown\n): schema is SerializableSchema<Input, Output>;\nexport function isSerializableSchema<Input = unknown, Output = Input>(\n  schema: SerializableSchema<Input, Output> | unknown\n): schema is SerializableSchema<Input, Output> {\n  return isStandardSchema(schema) && isStandardJSONSchema(schema);\n}\n"],"mappings":";AAkGA,SAAgB,iBACd,QAC2C;AAC3C,QACE,OAAO,WAAW,YAClB,WAAW,QACX,eAAe,UACf,OAAO,OAAO,iBAAiB,YAC/B,OAAO,iBAAiB,QACxB,cAAc,OAAO;;AA6BzB,SAAgB,qBACd,QAC+C;AAC/C,QACE,OAAO,WAAW,YAClB,WAAW,QACX,eAAe,UACf,OAAO,OAAO,iBAAiB,YAC/B,OAAO,iBAAiB,QACxB,gBAAgB,OAAO;;AA+B3B,SAAgB,qBACd,QAC6C;AAC7C,QAAO,iBAAiB,OAAO,IAAI,qBAAqB,OAAO"}

package/dist/state/values/index.cjs

@@ -0,0 +1,2 @@
+const require_reduced = require('./reduced.cjs');
+const require_untracked = require('./untracked.cjs');

package/dist/state/values/index.js

@@ -0,0 +1,4 @@
+import { ReducedValue } from "./reduced.js";
+import { UntrackedValue } from "./untracked.js";
+
+export {  };

package/dist/state/values/reduced.cjs

@@ -0,0 +1,72 @@
+
+//#region src/state/values/reduced.ts
+/**
+* Symbol for runtime identification of ReducedValue instances.
+*/
+const REDUCED_VALUE_SYMBOL = Symbol.for("langgraph.state.reduced_value");
+/**
+* Represents a state field whose value is computed and updated using a reducer function.
+*
+* {@link ReducedValue} allows you to define accumulators, counters, aggregators, or other fields
+* whose value is determined incrementally by applying a reducer to incoming updates.
+*
+* Each time a new input is provided, the reducer function is called with the current output
+* and the new input, producing an updated value. Input validation can be controlled separately
+* from output validation by providing an explicit input schema.
+*
+* @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
+* // Accumulator with distinct input validation
+* const Sum = new ReducedValue(z.number(), {
+*   inputSchema: z.number().min(1),
+*   reducer: (total, toAdd) => total + toAdd
+* });
+*
+* @example
+* // Simple running max, using only the value schema
+* const Max = new ReducedValue(z.number(), {
+*   reducer: (current, next) => Math.max(current, next)
+* });
+*/
+var ReducedValue = class {
+	/**
+	* Instance marker for runtime identification.
+	* @internal
+	*/
+	[REDUCED_VALUE_SYMBOL] = true;
+	/**
+	* The schema that describes the type of value stored in state (i.e., after reduction).
+	* Note: We use `unknown` for the input type to allow schemas with `.default()` wrappers,
+	* where the input type includes `undefined`.
+	*/
+	valueSchema;
+	/**
+	* The schema used to validate reducer inputs.
+	* If not specified explicitly, this defaults to `valueSchema`.
+	*/
+	inputSchema;
+	/**
+	* The reducer function that combines a current output value and an incoming input.
+	*/
+	reducer;
+	/**
+	* Optional extra fields to merge into the generated JSON Schema (e.g., for documentation or constraints).
+	*/
+	jsonSchemaExtra;
+	constructor(valueSchema, init) {
+		this.reducer = init.reducer;
+		this.jsonSchemaExtra = init.jsonSchemaExtra;
+		this.valueSchema = valueSchema;
+		this.inputSchema = "inputSchema" in init ? init.inputSchema : valueSchema;
+		this.jsonSchemaExtra = init.jsonSchemaExtra;
+	}
+	static isInstance(value) {
+		return typeof value === "object" && value !== null && REDUCED_VALUE_SYMBOL in value && value[REDUCED_VALUE_SYMBOL] === true;
+	}
+};
+
+//#endregion
+exports.ReducedValue = ReducedValue;
+//# sourceMappingURL=reduced.cjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"reduced.cjs","names":[],"sources":["../../../src/state/values/reduced.ts"],"sourcesContent":["import type { SerializableSchema } from \"../types.js\";\n\n/**\n * Symbol for runtime identification of ReducedValue instances.\n */\nexport const REDUCED_VALUE_SYMBOL = Symbol.for(\"langgraph.state.reduced_value\");\n\ninterface ReducedValueInitBase<Value = unknown> {\n  /**\n   * The reducer function that determines how new input values are combined with the current state.\n   * Receives the current output value and a new input value, and must return the updated output.\n   *\n   * @param current - The current value held in state.\n   * @param next - The new input value to apply to the reducer.\n   * @returns The next value to be stored in state.\n   *\n   * @remarks\n   * - The logic for updating state in response to new inputs lives in this function.\n   */\n  reducer: (current: Value, next: Value) => Value;\n\n  /**\n   * Optional extra fields to be added to the exported JSON Schema for documentation or additional constraints.\n   *\n   * @remarks\n   * - Use this property to attach metadata or documentation to the generated JSON Schema representation\n   *   of this value.\n   * - These fields are merged into the generated schema, which can assist with code generation, UI hints,\n   *   or external documentation.\n   */\n  jsonSchemaExtra?: Record<string, unknown>;\n}\n\ninterface ReducedValueInitWithSchema<Value = unknown, Input = Value> {\n  /**\n   * Schema describing the type and validation logic for reducer input values.\n   *\n   * @remarks\n   * - If provided, new values passed to the reducer will be validated using this schema before reduction.\n   * - This allows the reducer to accept inputs distinct from the type stored in the state (output type).\n   */\n  inputSchema: SerializableSchema<unknown, Input>;\n\n  /**\n   * The reducer function that determines how new input values are combined with the current state.\n   * Receives the current output value and a new input value (validated using `inputSchema`), and returns the updated output.\n   *\n   * @param current - The current value held in state.\n   * @param next - The new validated input value to be applied.\n   * @returns The next value to be stored in state.\n   *\n   * @remarks\n   * - The logic for updating state in response to new inputs lives in this function.\n   */\n  reducer: (current: Value, next: Input) => Value;\n\n  /**\n   * Optional extra fields to be added to the exported JSON Schema for documentation or additional constraints.\n   *\n   * @remarks\n   * - Use this property to attach metadata or documentation to the generated JSON Schema representation\n   *   of this value.\n   * - These fields are merged into the generated schema, which can assist with code generation, UI hints,\n   *   or external documentation.\n   */\n  jsonSchemaExtra?: Record<string, unknown>;\n}\n\n/**\n * Initialization options for {@link ReducedValue}.\n *\n * Two forms are supported:\n * 1. Provide only a reducer (and optionally `jsonSchemaExtra`)—in this case, the reducer's inputs are validated using the output value schema.\n * 2. Provide an explicit `inputSchema` field to distinguish the reducer's input type 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 *\n * @property inputSchema - The schema describing reducer inputs. If omitted, will use the value schema.\n * @property reducer - A function that receives the current output value and a new input, and returns the new output.\n * @property jsonSchemaExtra - (Optional) Extra fields to merge into the exported JSON Schema for documentation or additional constraints.\n */\nexport type ReducedValueInit<Value = unknown, Input = Value> =\n  | ReducedValueInitWithSchema<Value, Input>\n  | ReducedValueInitBase<Value>;\n\n/**\n * Represents a state field whose value is computed and updated using a reducer function.\n *\n * {@link ReducedValue} allows you to define accumulators, counters, aggregators, or other fields\n * whose value is determined incrementally by applying a reducer to incoming updates.\n *\n * Each time a new input is provided, the reducer function is called with the current output\n * and the new input, producing an updated value. Input validation can be controlled separately\n * from output validation by providing an explicit input schema.\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 * // Accumulator with distinct input validation\n * const Sum = new ReducedValue(z.number(), {\n *   inputSchema: z.number().min(1),\n *   reducer: (total, toAdd) => total + toAdd\n * });\n *\n * @example\n * // Simple running max, using only the value schema\n * const Max = new ReducedValue(z.number(), {\n *   reducer: (current, next) => Math.max(current, next)\n * });\n */\nexport class ReducedValue<Value = unknown, Input = Value> {\n  /**\n   * Instance marker for runtime identification.\n   * @internal\n   */\n  protected readonly [REDUCED_VALUE_SYMBOL] = true as const;\n\n  /**\n   * The schema that describes the type of value stored in state (i.e., after reduction).\n   * Note: We use `unknown` for the input type to allow schemas with `.default()` wrappers,\n   * where the input type includes `undefined`.\n   */\n  readonly valueSchema: SerializableSchema<unknown, Value>;\n\n  /**\n   * The schema used to validate reducer inputs.\n   * If not specified explicitly, this defaults to `valueSchema`.\n   */\n  readonly inputSchema: SerializableSchema<unknown, Input | Value>;\n\n  /**\n   * The reducer function that combines a current output value and an incoming input.\n   */\n  readonly reducer: (current: Value, next: Input) => Value;\n\n  /**\n   * Optional extra fields to merge into the generated JSON Schema (e.g., for documentation or constraints).\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 ReducedValue instance, which combines a value schema and a reducer function (plus optional input schema).\n   *\n   * @param valueSchema - The schema that describes the type of value stored in state (the \"running total\").\n   * @param init - An object specifying the reducer function (required), inputSchema (optional), and jsonSchemaExtra (optional).\n   */\n  constructor(\n    valueSchema: SerializableSchema<unknown, Value>,\n    init: ReducedValueInitWithSchema<Value, Input>\n  );\n\n  constructor(\n    valueSchema: SerializableSchema<unknown, Value>,\n    init: ReducedValueInitBase<Value>\n  );\n\n  constructor(\n    valueSchema: SerializableSchema<unknown, Value>,\n    init: ReducedValueInit<Value, Input>\n  ) {\n    this.reducer = init.reducer as (current: Value, next: Input) => Value;\n    this.jsonSchemaExtra = init.jsonSchemaExtra;\n    this.valueSchema = valueSchema;\n    this.inputSchema = \"inputSchema\" in init ? init.inputSchema : valueSchema;\n    this.jsonSchemaExtra = init.jsonSchemaExtra;\n  }\n\n  /**\n   * Type guard to check if a value is a ReducedValue instance.\n   */\n  static isInstance<Value = unknown, Input = Value>(\n    value: ReducedValue<Value, Input>\n  ): value is ReducedValue<Value, Input>;\n\n  static isInstance(value: unknown): value is ReducedValue;\n\n  static isInstance<Value = unknown, Input = Value>(\n    value: ReducedValue<Value, Input> | unknown\n  ): value is ReducedValue<Value, Input> {\n    return (\n      typeof value === \"object\" &&\n      value !== null &&\n      REDUCED_VALUE_SYMBOL in value &&\n      value[REDUCED_VALUE_SYMBOL] === true\n    );\n  }\n}\n"],"mappings":";;;;;AAKA,MAAa,uBAAuB,OAAO,IAAI,gCAAgC;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2G/E,IAAa,eAAb,MAA0D;;;;;CAKxD,CAAoB,wBAAwB;;;;;;CAO5C,AAAS;;;;;CAMT,AAAS;;;;CAKT,AAAS;;;;CAKT,AAAS;CA4BT,YACE,aACA,MACA;AACA,OAAK,UAAU,KAAK;AACpB,OAAK,kBAAkB,KAAK;AAC5B,OAAK,cAAc;AACnB,OAAK,cAAc,iBAAiB,OAAO,KAAK,cAAc;AAC9D,OAAK,kBAAkB,KAAK;;CAY9B,OAAO,WACL,OACqC;AACrC,SACE,OAAO,UAAU,YACjB,UAAU,QACV,wBAAwB,SACxB,MAAM,0BAA0B"}

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

@@ -0,0 +1,155 @@
+import { SerializableSchema } from "../types.cjs";
+
+//#region src/state/values/reduced.d.ts
+
+/**
+ * Symbol for runtime identification of ReducedValue instances.
+ */
+declare const REDUCED_VALUE_SYMBOL: unique symbol;
+interface ReducedValueInitBase<Value = unknown> {
+  /**
+   * The reducer function that determines how new input values are combined with the current state.
+   * Receives the current output value and a new input value, and must return the updated output.
+   *
+   * @param current - The current value held in state.
+   * @param next - The new input value to apply to the reducer.
+   * @returns The next value to be stored in state.
+   *
+   * @remarks
+   * - The logic for updating state in response to new inputs lives in this function.
+   */
+  reducer: (current: Value, next: Value) => Value;
+  /**
+   * Optional extra fields to be added to the exported JSON Schema for documentation or additional constraints.
+   *
+   * @remarks
+   * - Use this property to attach metadata or documentation to the generated JSON Schema representation
+   *   of this value.
+   * - These fields are merged into the generated schema, which can assist with code generation, UI hints,
+   *   or external documentation.
+   */
+  jsonSchemaExtra?: Record<string, unknown>;
+}
+interface ReducedValueInitWithSchema<Value = unknown, Input = Value> {
+  /**
+   * Schema describing the type and validation logic for reducer input values.
+   *
+   * @remarks
+   * - If provided, new values passed to the reducer will be validated using this schema before reduction.
+   * - This allows the reducer to accept inputs distinct from the type stored in the state (output type).
+   */
+  inputSchema: SerializableSchema<unknown, Input>;
+  /**
+   * The reducer function that determines how new input values are combined with the current state.
+   * Receives the current output value and a new input value (validated using `inputSchema`), and returns the updated output.
+   *
+   * @param current - The current value held in state.
+   * @param next - The new validated input value to be applied.
+   * @returns The next value to be stored in state.
+   *
+   * @remarks
+   * - The logic for updating state in response to new inputs lives in this function.
+   */
+  reducer: (current: Value, next: Input) => Value;
+  /**
+   * Optional extra fields to be added to the exported JSON Schema for documentation or additional constraints.
+   *
+   * @remarks
+   * - Use this property to attach metadata or documentation to the generated JSON Schema representation
+   *   of this value.
+   * - These fields are merged into the generated schema, which can assist with code generation, UI hints,
+   *   or external documentation.
+   */
+  jsonSchemaExtra?: Record<string, unknown>;
+}
+/**
+ * Initialization options for {@link ReducedValue}.
+ *
+ * Two forms are supported:
+ * 1. Provide only a reducer (and optionally `jsonSchemaExtra`)—in this case, the reducer's inputs are validated using the output value schema.
+ * 2. Provide an explicit `inputSchema` field 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.
+ *
+ * @property inputSchema - The schema describing reducer inputs. If omitted, will use the value schema.
+ * @property reducer - A function that receives the current output value and a new input, and returns the new output.
+ * @property jsonSchemaExtra - (Optional) Extra fields to merge into the exported JSON Schema for documentation or additional constraints.
+ */
+type ReducedValueInit<Value = unknown, Input = Value> = ReducedValueInitWithSchema<Value, Input> | ReducedValueInitBase<Value>;
+/**
+ * Represents a state field whose value is computed and updated using a reducer function.
+ *
+ * {@link ReducedValue} allows you to define accumulators, counters, aggregators, or other fields
+ * whose value is determined incrementally by applying a reducer to incoming updates.
+ *
+ * Each time a new input is provided, the reducer function is called with the current output
+ * and the new input, producing an updated value. Input validation can be controlled separately
+ * from output validation by providing an explicit input schema.
+ *
+ * @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
+ * // Accumulator with distinct input validation
+ * const Sum = new ReducedValue(z.number(), {
+ *   inputSchema: z.number().min(1),
+ *   reducer: (total, toAdd) => total + toAdd
+ * });
+ *
+ * @example
+ * // Simple running max, using only the value schema
+ * const Max = new ReducedValue(z.number(), {
+ *   reducer: (current, next) => Math.max(current, next)
+ * });
+ */
+declare class ReducedValue<Value = unknown, Input = Value> {
+  /**
+   * Instance marker for runtime identification.
+   * @internal
+   */
+  protected readonly [REDUCED_VALUE_SYMBOL]: true;
+  /**
+   * The schema that describes the type of value stored in state (i.e., after reduction).
+   * Note: We use `unknown` for the input type to allow schemas with `.default()` wrappers,
+   * where the input type includes `undefined`.
+   */
+  readonly valueSchema: SerializableSchema<unknown, Value>;
+  /**
+   * The schema used to validate reducer inputs.
+   * If not specified explicitly, this defaults to `valueSchema`.
+   */
+  readonly inputSchema: SerializableSchema<unknown, Input | Value>;
+  /**
+   * The reducer function that combines a current output value and an incoming input.
+   */
+  readonly reducer: (current: Value, next: Input) => Value;
+  /**
+   * Optional extra fields to merge into the generated JSON Schema (e.g., for documentation or constraints).
+   */
+  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 ReducedValue instance, which combines a value schema and a reducer function (plus optional input schema).
+   *
+   * @param valueSchema - The schema that describes the type of value stored in state (the "running total").
+   * @param init - An object specifying the reducer function (required), inputSchema (optional), and jsonSchemaExtra (optional).
+   */
+  constructor(valueSchema: SerializableSchema<unknown, Value>, init: ReducedValueInitWithSchema<Value, Input>);
+  constructor(valueSchema: SerializableSchema<unknown, Value>, init: ReducedValueInitBase<Value>);
+  /**
+   * Type guard to check if a value is a ReducedValue instance.
+   */
+  static isInstance<Value = unknown, Input = Value>(value: ReducedValue<Value, Input>): value is ReducedValue<Value, Input>;
+  static isInstance(value: unknown): value is ReducedValue;
+}
+//#endregion
+export { ReducedValue, ReducedValueInit };
+//# sourceMappingURL=reduced.d.cts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"reduced.d.cts","names":["SerializableSchema","REDUCED_VALUE_SYMBOL","ReducedValueInitBase","Value","Record","ReducedValueInitWithSchema","Input","ReducedValueInit","ReducedValue"],"sources":["../../../src/state/values/reduced.d.ts"],"sourcesContent":["import type { SerializableSchema } from \"../types.js\";\n/**\n * Symbol for runtime identification of ReducedValue instances.\n */\nexport declare const REDUCED_VALUE_SYMBOL: unique symbol;\ninterface ReducedValueInitBase<Value = unknown> {\n    /**\n     * The reducer function that determines how new input values are combined with the current state.\n     * Receives the current output value and a new input value, and must return the updated output.\n     *\n     * @param current - The current value held in state.\n     * @param next - The new input value to apply to the reducer.\n     * @returns The next value to be stored in state.\n     *\n     * @remarks\n     * - The logic for updating state in response to new inputs lives in this function.\n     */\n    reducer: (current: Value, next: Value) => Value;\n    /**\n     * Optional extra fields to be added to the exported JSON Schema for documentation or additional constraints.\n     *\n     * @remarks\n     * - Use this property to attach metadata or documentation to the generated JSON Schema representation\n     *   of this value.\n     * - These fields are merged into the generated schema, which can assist with code generation, UI hints,\n     *   or external documentation.\n     */\n    jsonSchemaExtra?: Record<string, unknown>;\n}\ninterface ReducedValueInitWithSchema<Value = unknown, Input = Value> {\n    /**\n     * Schema describing the type and validation logic for reducer input values.\n     *\n     * @remarks\n     * - If provided, new values passed to the reducer will be validated using this schema before reduction.\n     * - This allows the reducer to accept inputs distinct from the type stored in the state (output type).\n     */\n    inputSchema: SerializableSchema<unknown, Input>;\n    /**\n     * The reducer function that determines how new input values are combined with the current state.\n     * Receives the current output value and a new input value (validated using `inputSchema`), and returns the updated output.\n     *\n     * @param current - The current value held in state.\n     * @param next - The new validated input value to be applied.\n     * @returns The next value to be stored in state.\n     *\n     * @remarks\n     * - The logic for updating state in response to new inputs lives in this function.\n     */\n    reducer: (current: Value, next: Input) => Value;\n    /**\n     * Optional extra fields to be added to the exported JSON Schema for documentation or additional constraints.\n     *\n     * @remarks\n     * - Use this property to attach metadata or documentation to the generated JSON Schema representation\n     *   of this value.\n     * - These fields are merged into the generated schema, which can assist with code generation, UI hints,\n     *   or external documentation.\n     */\n    jsonSchemaExtra?: Record<string, unknown>;\n}\n/**\n * Initialization options for {@link ReducedValue}.\n *\n * Two forms are supported:\n * 1. Provide only a reducer (and optionally `jsonSchemaExtra`)—in this case, the reducer's inputs are validated using the output value schema.\n * 2. Provide an explicit `inputSchema` field to distinguish the reducer's input type 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 *\n * @property inputSchema - The schema describing reducer inputs. If omitted, will use the value schema.\n * @property reducer - A function that receives the current output value and a new input, and returns the new output.\n * @property jsonSchemaExtra - (Optional) Extra fields to merge into the exported JSON Schema for documentation or additional constraints.\n */\nexport type ReducedValueInit<Value = unknown, Input = Value> = ReducedValueInitWithSchema<Value, Input> | ReducedValueInitBase<Value>;\n/**\n * Represents a state field whose value is computed and updated using a reducer function.\n *\n * {@link ReducedValue} allows you to define accumulators, counters, aggregators, or other fields\n * whose value is determined incrementally by applying a reducer to incoming updates.\n *\n * Each time a new input is provided, the reducer function is called with the current output\n * and the new input, producing an updated value. Input validation can be controlled separately\n * from output validation by providing an explicit input schema.\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 * // Accumulator with distinct input validation\n * const Sum = new ReducedValue(z.number(), {\n *   inputSchema: z.number().min(1),\n *   reducer: (total, toAdd) => total + toAdd\n * });\n *\n * @example\n * // Simple running max, using only the value schema\n * const Max = new ReducedValue(z.number(), {\n *   reducer: (current, next) => Math.max(current, next)\n * });\n */\nexport declare class ReducedValue<Value = unknown, Input = Value> {\n    /**\n     * Instance marker for runtime identification.\n     * @internal\n     */\n    protected readonly [REDUCED_VALUE_SYMBOL]: true;\n    /**\n     * The schema that describes the type of value stored in state (i.e., after reduction).\n     * Note: We use `unknown` for the input type to allow schemas with `.default()` wrappers,\n     * where the input type includes `undefined`.\n     */\n    readonly valueSchema: SerializableSchema<unknown, Value>;\n    /**\n     * The schema used to validate reducer inputs.\n     * If not specified explicitly, this defaults to `valueSchema`.\n     */\n    readonly inputSchema: SerializableSchema<unknown, Input | Value>;\n    /**\n     * The reducer function that combines a current output value and an incoming input.\n     */\n    readonly reducer: (current: Value, next: Input) => Value;\n    /**\n     * Optional extra fields to merge into the generated JSON Schema (e.g., for documentation or constraints).\n     */\n    readonly jsonSchemaExtra?: Record<string, unknown>;\n    /**\n     * Represents the value stored after all reductions.\n     */\n    ValueType: Value;\n    /**\n     * Represents the type that may be provided as input on each update.\n     */\n    InputType: Input;\n    /**\n     * Constructs a ReducedValue instance, which combines a value schema and a reducer function (plus optional input schema).\n     *\n     * @param valueSchema - The schema that describes the type of value stored in state (the \"running total\").\n     * @param init - An object specifying the reducer function (required), inputSchema (optional), and jsonSchemaExtra (optional).\n     */\n    constructor(valueSchema: SerializableSchema<unknown, Value>, init: ReducedValueInitWithSchema<Value, Input>);\n    constructor(valueSchema: SerializableSchema<unknown, Value>, init: ReducedValueInitBase<Value>);\n    /**\n     * Type guard to check if a value is a ReducedValue instance.\n     */\n    static isInstance<Value = unknown, Input = Value>(value: ReducedValue<Value, Input>): value is ReducedValue<Value, Input>;\n    static isInstance(value: unknown): value is ReducedValue;\n}\nexport {};\n"],"mappings":";;;;;;AAIA;AACUE,cADWD,oBACS,EAAA,OAAA,MAAA;UAApBC,oBAAoB,CAAA,QAAA,OAAA,CAAA,CAAA;;;;;;AAsBF;;;;;;SAsBQI,EAAAA,CAAAA,OAAAA,EAhCbH,KAgCaG,EAAAA,IAAAA,EAhCAH,KAgCAG,EAAAA,GAhCUH,KAgCVG;;;;AA0BpC;;;;;;iBAA+HH,CAAAA,EAhDzGC,MAgDyGD,CAAAA,MAAAA,EAAAA,OAAAA,CAAAA;;UA9CrHE,0BA8CoH,CAAA,QAAA,OAAA,EAAA,QA9ChEF,KA8CgE,CAAA,CAAA;EA2BzGK;;;;;;;aAgByCL,EAjF7CH,kBAiF6CG,CAAAA,OAAAA,EAjFjBG,KAiFiBH,CAAAA;;;;;;;;;;;;SAuBSE,EAAAA,CAAAA,OAAAA,EA5FhDF,KA4FgDE,EAAAA,IAAAA,EA5FnCC,KA4FmCD,EAAAA,GA5FzBF,KA4FyBE;;;;;;;;;;iBAKgDC,CAAAA,EAvFjGF,MAuFiGE,CAAAA,MAAAA,EAAAA,OAAAA,CAAAA;;;;;;;;;;;;;;;;KAvE3GC,0CAA0CJ,SAASE,2BAA2BF,OAAOG,SAASJ,qBAAqBC;;;;;;;;;;;;;;;;;;;;;;;;;;;cA2B1GK,sCAAsCL;;;;;sBAKnCF,oBAAAA;;;;;;wBAMED,4BAA4BG;;;;;wBAK5BH,4BAA4BM,QAAQH;;;;8BAI9BA,aAAaG,UAAUH;;;;6BAIxBC;;;;aAIhBD;;;;aAIAG;;;;;;;2BAOcN,4BAA4BG,cAAcE,2BAA2BF,OAAOG;2BAC5EN,4BAA4BG,cAAcD,qBAAqBC;;;;6CAI7CA,cAAcK,aAAaL,OAAOG,kBAAkBE,aAAaL,OAAOG;8CACvEE"}

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

@@ -0,0 +1,155 @@
+import { SerializableSchema } from "../types.js";
+
+//#region src/state/values/reduced.d.ts
+
+/**
+ * Symbol for runtime identification of ReducedValue instances.
+ */
+declare const REDUCED_VALUE_SYMBOL: unique symbol;
+interface ReducedValueInitBase<Value = unknown> {
+  /**
+   * The reducer function that determines how new input values are combined with the current state.
+   * Receives the current output value and a new input value, and must return the updated output.
+   *
+   * @param current - The current value held in state.
+   * @param next - The new input value to apply to the reducer.
+   * @returns The next value to be stored in state.
+   *
+   * @remarks
+   * - The logic for updating state in response to new inputs lives in this function.
+   */
+  reducer: (current: Value, next: Value) => Value;
+  /**
+   * Optional extra fields to be added to the exported JSON Schema for documentation or additional constraints.
+   *
+   * @remarks
+   * - Use this property to attach metadata or documentation to the generated JSON Schema representation
+   *   of this value.
+   * - These fields are merged into the generated schema, which can assist with code generation, UI hints,
+   *   or external documentation.
+   */
+  jsonSchemaExtra?: Record<string, unknown>;
+}
+interface ReducedValueInitWithSchema<Value = unknown, Input = Value> {
+  /**
+   * Schema describing the type and validation logic for reducer input values.
+   *
+   * @remarks
+   * - If provided, new values passed to the reducer will be validated using this schema before reduction.
+   * - This allows the reducer to accept inputs distinct from the type stored in the state (output type).
+   */
+  inputSchema: SerializableSchema<unknown, Input>;
+  /**
+   * The reducer function that determines how new input values are combined with the current state.
+   * Receives the current output value and a new input value (validated using `inputSchema`), and returns the updated output.
+   *
+   * @param current - The current value held in state.
+   * @param next - The new validated input value to be applied.
+   * @returns The next value to be stored in state.
+   *
+   * @remarks
+   * - The logic for updating state in response to new inputs lives in this function.
+   */
+  reducer: (current: Value, next: Input) => Value;
+  /**
+   * Optional extra fields to be added to the exported JSON Schema for documentation or additional constraints.
+   *
+   * @remarks
+   * - Use this property to attach metadata or documentation to the generated JSON Schema representation
+   *   of this value.
+   * - These fields are merged into the generated schema, which can assist with code generation, UI hints,
+   *   or external documentation.
+   */
+  jsonSchemaExtra?: Record<string, unknown>;
+}
+/**
+ * Initialization options for {@link ReducedValue}.
+ *
+ * Two forms are supported:
+ * 1. Provide only a reducer (and optionally `jsonSchemaExtra`)—in this case, the reducer's inputs are validated using the output value schema.
+ * 2. Provide an explicit `inputSchema` field 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.
+ *
+ * @property inputSchema - The schema describing reducer inputs. If omitted, will use the value schema.
+ * @property reducer - A function that receives the current output value and a new input, and returns the new output.
+ * @property jsonSchemaExtra - (Optional) Extra fields to merge into the exported JSON Schema for documentation or additional constraints.
+ */
+type ReducedValueInit<Value = unknown, Input = Value> = ReducedValueInitWithSchema<Value, Input> | ReducedValueInitBase<Value>;
+/**
+ * Represents a state field whose value is computed and updated using a reducer function.
+ *
+ * {@link ReducedValue} allows you to define accumulators, counters, aggregators, or other fields
+ * whose value is determined incrementally by applying a reducer to incoming updates.
+ *
+ * Each time a new input is provided, the reducer function is called with the current output
+ * and the new input, producing an updated value. Input validation can be controlled separately
+ * from output validation by providing an explicit input schema.
+ *
+ * @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
+ * // Accumulator with distinct input validation
+ * const Sum = new ReducedValue(z.number(), {
+ *   inputSchema: z.number().min(1),
+ *   reducer: (total, toAdd) => total + toAdd
+ * });
+ *
+ * @example
+ * // Simple running max, using only the value schema
+ * const Max = new ReducedValue(z.number(), {
+ *   reducer: (current, next) => Math.max(current, next)
+ * });
+ */
+declare class ReducedValue<Value = unknown, Input = Value> {
+  /**
+   * Instance marker for runtime identification.
+   * @internal
+   */
+  protected readonly [REDUCED_VALUE_SYMBOL]: true;
+  /**
+   * The schema that describes the type of value stored in state (i.e., after reduction).
+   * Note: We use `unknown` for the input type to allow schemas with `.default()` wrappers,
+   * where the input type includes `undefined`.
+   */
+  readonly valueSchema: SerializableSchema<unknown, Value>;
+  /**
+   * The schema used to validate reducer inputs.
+   * If not specified explicitly, this defaults to `valueSchema`.
+   */
+  readonly inputSchema: SerializableSchema<unknown, Input | Value>;
+  /**
+   * The reducer function that combines a current output value and an incoming input.
+   */
+  readonly reducer: (current: Value, next: Input) => Value;
+  /**
+   * Optional extra fields to merge into the generated JSON Schema (e.g., for documentation or constraints).
+   */
+  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 ReducedValue instance, which combines a value schema and a reducer function (plus optional input schema).
+   *
+   * @param valueSchema - The schema that describes the type of value stored in state (the "running total").
+   * @param init - An object specifying the reducer function (required), inputSchema (optional), and jsonSchemaExtra (optional).
+   */
+  constructor(valueSchema: SerializableSchema<unknown, Value>, init: ReducedValueInitWithSchema<Value, Input>);
+  constructor(valueSchema: SerializableSchema<unknown, Value>, init: ReducedValueInitBase<Value>);
+  /**
+   * Type guard to check if a value is a ReducedValue instance.
+   */
+  static isInstance<Value = unknown, Input = Value>(value: ReducedValue<Value, Input>): value is ReducedValue<Value, Input>;
+  static isInstance(value: unknown): value is ReducedValue;
+}
+//#endregion
+export { ReducedValue, ReducedValueInit };
+//# sourceMappingURL=reduced.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"reduced.d.ts","names":["SerializableSchema","REDUCED_VALUE_SYMBOL","ReducedValueInitBase","Value","Record","ReducedValueInitWithSchema","Input","ReducedValueInit","ReducedValue"],"sources":["../../../src/state/values/reduced.d.ts"],"sourcesContent":["import type { SerializableSchema } from \"../types.js\";\n/**\n * Symbol for runtime identification of ReducedValue instances.\n */\nexport declare const REDUCED_VALUE_SYMBOL: unique symbol;\ninterface ReducedValueInitBase<Value = unknown> {\n    /**\n     * The reducer function that determines how new input values are combined with the current state.\n     * Receives the current output value and a new input value, and must return the updated output.\n     *\n     * @param current - The current value held in state.\n     * @param next - The new input value to apply to the reducer.\n     * @returns The next value to be stored in state.\n     *\n     * @remarks\n     * - The logic for updating state in response to new inputs lives in this function.\n     */\n    reducer: (current: Value, next: Value) => Value;\n    /**\n     * Optional extra fields to be added to the exported JSON Schema for documentation or additional constraints.\n     *\n     * @remarks\n     * - Use this property to attach metadata or documentation to the generated JSON Schema representation\n     *   of this value.\n     * - These fields are merged into the generated schema, which can assist with code generation, UI hints,\n     *   or external documentation.\n     */\n    jsonSchemaExtra?: Record<string, unknown>;\n}\ninterface ReducedValueInitWithSchema<Value = unknown, Input = Value> {\n    /**\n     * Schema describing the type and validation logic for reducer input values.\n     *\n     * @remarks\n     * - If provided, new values passed to the reducer will be validated using this schema before reduction.\n     * - This allows the reducer to accept inputs distinct from the type stored in the state (output type).\n     */\n    inputSchema: SerializableSchema<unknown, Input>;\n    /**\n     * The reducer function that determines how new input values are combined with the current state.\n     * Receives the current output value and a new input value (validated using `inputSchema`), and returns the updated output.\n     *\n     * @param current - The current value held in state.\n     * @param next - The new validated input value to be applied.\n     * @returns The next value to be stored in state.\n     *\n     * @remarks\n     * - The logic for updating state in response to new inputs lives in this function.\n     */\n    reducer: (current: Value, next: Input) => Value;\n    /**\n     * Optional extra fields to be added to the exported JSON Schema for documentation or additional constraints.\n     *\n     * @remarks\n     * - Use this property to attach metadata or documentation to the generated JSON Schema representation\n     *   of this value.\n     * - These fields are merged into the generated schema, which can assist with code generation, UI hints,\n     *   or external documentation.\n     */\n    jsonSchemaExtra?: Record<string, unknown>;\n}\n/**\n * Initialization options for {@link ReducedValue}.\n *\n * Two forms are supported:\n * 1. Provide only a reducer (and optionally `jsonSchemaExtra`)—in this case, the reducer's inputs are validated using the output value schema.\n * 2. Provide an explicit `inputSchema` field to distinguish the reducer's input type 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 *\n * @property inputSchema - The schema describing reducer inputs. If omitted, will use the value schema.\n * @property reducer - A function that receives the current output value and a new input, and returns the new output.\n * @property jsonSchemaExtra - (Optional) Extra fields to merge into the exported JSON Schema for documentation or additional constraints.\n */\nexport type ReducedValueInit<Value = unknown, Input = Value> = ReducedValueInitWithSchema<Value, Input> | ReducedValueInitBase<Value>;\n/**\n * Represents a state field whose value is computed and updated using a reducer function.\n *\n * {@link ReducedValue} allows you to define accumulators, counters, aggregators, or other fields\n * whose value is determined incrementally by applying a reducer to incoming updates.\n *\n * Each time a new input is provided, the reducer function is called with the current output\n * and the new input, producing an updated value. Input validation can be controlled separately\n * from output validation by providing an explicit input schema.\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 * // Accumulator with distinct input validation\n * const Sum = new ReducedValue(z.number(), {\n *   inputSchema: z.number().min(1),\n *   reducer: (total, toAdd) => total + toAdd\n * });\n *\n * @example\n * // Simple running max, using only the value schema\n * const Max = new ReducedValue(z.number(), {\n *   reducer: (current, next) => Math.max(current, next)\n * });\n */\nexport declare class ReducedValue<Value = unknown, Input = Value> {\n    /**\n     * Instance marker for runtime identification.\n     * @internal\n     */\n    protected readonly [REDUCED_VALUE_SYMBOL]: true;\n    /**\n     * The schema that describes the type of value stored in state (i.e., after reduction).\n     * Note: We use `unknown` for the input type to allow schemas with `.default()` wrappers,\n     * where the input type includes `undefined`.\n     */\n    readonly valueSchema: SerializableSchema<unknown, Value>;\n    /**\n     * The schema used to validate reducer inputs.\n     * If not specified explicitly, this defaults to `valueSchema`.\n     */\n    readonly inputSchema: SerializableSchema<unknown, Input | Value>;\n    /**\n     * The reducer function that combines a current output value and an incoming input.\n     */\n    readonly reducer: (current: Value, next: Input) => Value;\n    /**\n     * Optional extra fields to merge into the generated JSON Schema (e.g., for documentation or constraints).\n     */\n    readonly jsonSchemaExtra?: Record<string, unknown>;\n    /**\n     * Represents the value stored after all reductions.\n     */\n    ValueType: Value;\n    /**\n     * Represents the type that may be provided as input on each update.\n     */\n    InputType: Input;\n    /**\n     * Constructs a ReducedValue instance, which combines a value schema and a reducer function (plus optional input schema).\n     *\n     * @param valueSchema - The schema that describes the type of value stored in state (the \"running total\").\n     * @param init - An object specifying the reducer function (required), inputSchema (optional), and jsonSchemaExtra (optional).\n     */\n    constructor(valueSchema: SerializableSchema<unknown, Value>, init: ReducedValueInitWithSchema<Value, Input>);\n    constructor(valueSchema: SerializableSchema<unknown, Value>, init: ReducedValueInitBase<Value>);\n    /**\n     * Type guard to check if a value is a ReducedValue instance.\n     */\n    static isInstance<Value = unknown, Input = Value>(value: ReducedValue<Value, Input>): value is ReducedValue<Value, Input>;\n    static isInstance(value: unknown): value is ReducedValue;\n}\nexport {};\n"],"mappings":";;;;;;AAIA;AACUE,cADWD,oBACS,EAAA,OAAA,MAAA;UAApBC,oBAAoB,CAAA,QAAA,OAAA,CAAA,CAAA;;;;;;AAsBF;;;;;;SAsBQI,EAAAA,CAAAA,OAAAA,EAhCbH,KAgCaG,EAAAA,IAAAA,EAhCAH,KAgCAG,EAAAA,GAhCUH,KAgCVG;;;;AA0BpC;;;;;;iBAA+HH,CAAAA,EAhDzGC,MAgDyGD,CAAAA,MAAAA,EAAAA,OAAAA,CAAAA;;UA9CrHE,0BA8CoH,CAAA,QAAA,OAAA,EAAA,QA9ChEF,KA8CgE,CAAA,CAAA;EA2BzGK;;;;;;;aAgByCL,EAjF7CH,kBAiF6CG,CAAAA,OAAAA,EAjFjBG,KAiFiBH,CAAAA;;;;;;;;;;;;SAuBSE,EAAAA,CAAAA,OAAAA,EA5FhDF,KA4FgDE,EAAAA,IAAAA,EA5FnCC,KA4FmCD,EAAAA,GA5FzBF,KA4FyBE;;;;;;;;;;iBAKgDC,CAAAA,EAvFjGF,MAuFiGE,CAAAA,MAAAA,EAAAA,OAAAA,CAAAA;;;;;;;;;;;;;;;;KAvE3GC,0CAA0CJ,SAASE,2BAA2BF,OAAOG,SAASJ,qBAAqBC;;;;;;;;;;;;;;;;;;;;;;;;;;;cA2B1GK,sCAAsCL;;;;;sBAKnCF,oBAAAA;;;;;;wBAMED,4BAA4BG;;;;;wBAK5BH,4BAA4BM,QAAQH;;;;8BAI9BA,aAAaG,UAAUH;;;;6BAIxBC;;;;aAIhBD;;;;aAIAG;;;;;;;2BAOcN,4BAA4BG,cAAcE,2BAA2BF,OAAOG;2BAC5EN,4BAA4BG,cAAcD,qBAAqBC;;;;6CAI7CA,cAAcK,aAAaL,OAAOG,kBAAkBE,aAAaL,OAAOG;8CACvEE"}