effect-machine 0.11.0 → 0.12.0

package/v3/dist/schema.d.ts

@@ -1,7 +1,17 @@
-import { FullEventBrand, FullStateBrand } from "./internal/brands.js";
+import { FullEventBrand, FullStateBrand, ReplyTypeBrand } from "./internal/brands.js";
 import { Schema } from "effect";
 
 //#region src/schema.d.ts
+declare const ReplySchemaSymbol: unique symbol;
+type ReplySchemaSymbol = typeof ReplySchemaSymbol;
+/**
+ * Fields annotated with a reply schema.
+ * Structurally identical to Schema.Struct.Fields at runtime,
+ * but carries the reply schema type at compile time.
+ */
+type ReplyFields<F extends Schema.Struct.Fields, RS extends Schema.Schema.Any> = F & {
+  readonly [ReplySchemaSymbol]: RS;
+};
 /**
  * Extract the TypeScript type from a TaggedStruct schema
  */
@@ -12,20 +22,23 @@ type TaggedStructType<Tag extends string, Fields extends Schema.Struct.Fields> =
 type VariantSchemas<D extends Record<string, Schema.Struct.Fields>> = { readonly [K in keyof D & string]: Schema.TaggedStruct<K, D[K]> };
 /**
  * Build union type from variant schemas.
- * Used for constraining fluent method type params.
+ * Reply-bearing variants carry ReplyTypeBrand<R> for ask() inference.
  */
-type VariantsUnion<D extends Record<string, Schema.Struct.Fields>> = { [K in keyof D & string]: TaggedStructType<K, D[K]> }[keyof D & string];
+type VariantsUnion<D extends Record<string, Schema.Struct.Fields>> = { [K in keyof D & string]: TaggedStructType<K, D[K]> & (D[K] extends {
+  readonly [ReplySchemaSymbol]: Schema.Schema<infer R, infer _I, infer _RR>;
+} ? ReplyTypeBrand<R> : unknown) }[keyof D & string];
 /**
- * Check if fields are empty (no required properties)
+ * Check if fields are empty (no required string properties).
+ * Symbol keys (like ReplySchemaSymbol) are metadata, not payload fields.
  */
-type IsEmptyFields<Fields extends Schema.Struct.Fields> = keyof Fields extends never ? true : false;
+type IsEmptyFields<Fields extends Schema.Struct.Fields> = string & keyof Fields extends never ? true : false;
 /**
- * Constructor functions for each variant.
- * Empty structs: plain values with `_tag`: `State.Idle`
- * Non-empty structs require args: `State.Loading({ url })`
- *
- * Each variant also has a `derive` method for constructing from a source object.
+ * Resolve the reply brand for a variant's fields.
+ * If fields carry ReplySchemaSymbol, adds ReplyTypeBrand<R>.
  */
+type VariantReplyBrand<Fields extends Schema.Struct.Fields> = Fields extends {
+  readonly [ReplySchemaSymbol]: Schema.Schema<infer R, infer _I, infer _RR>;
+} ? ReplyTypeBrand<R> : unknown;
 /**
  * Constructor functions for each variant.
  * Empty structs: plain values with `_tag`: `State.Idle`
@@ -33,10 +46,11 @@ type IsEmptyFields<Fields extends Schema.Struct.Fields> = keyof Fields extends n
  *
  * Each variant also has a `derive` method for constructing from a source object.
  * The source type uses `object` to accept branded state types without index signature issues.
+ * Reply-bearing variants carry ReplyTypeBrand<R> for ask() type inference.
  */
-type VariantConstructors<D extends Record<string, Schema.Struct.Fields>, Brand> = { readonly [K in keyof D & string]: IsEmptyFields<D[K]> extends true ? TaggedStructType<K, D[K]> & Brand & {
+type VariantConstructors<D extends Record<string, Schema.Struct.Fields>, Brand> = { readonly [K in keyof D & string]: IsEmptyFields<D[K]> extends true ? TaggedStructType<K, D[K]> & Brand & VariantReplyBrand<D[K]> & {
   readonly derive: (source: object) => TaggedStructType<K, D[K]> & Brand;
-} : ((args: Schema.Struct.Constructor<D[K]>) => TaggedStructType<K, D[K]> & Brand) & {
+} : ((args: Schema.Struct.Constructor<D[K]>) => TaggedStructType<K, D[K]> & Brand & VariantReplyBrand<D[K]>) & {
   readonly derive: (source: object, partial?: Partial<Schema.Struct.Constructor<D[K]>>) => TaggedStructType<K, D[K]> & Brand;
   readonly _tag: K;
 } };
@@ -56,6 +70,11 @@ interface MachineSchemaBase<D extends Record<string, Schema.Struct.Fields>, Bran
    * Per-variant schemas for fine-grained operations
    */
   readonly variants: VariantSchemas<D>;
+  /**
+   * Reply schemas per variant tag. Only populated for event schemas
+   * with variants defined via `Event.reply()`.
+   */
+  readonly _replySchemas: ReadonlyMap<string, Schema.Schema.Any>;
   /**
    * Type guard: `OrderState.$is("Pending")(value)`
    */
@@ -116,26 +135,8 @@ type MachineEventSchema<D extends Record<string, Schema.Struct.Fields>> = Schema
  * ```
  */
 declare const State: <const D extends Record<string, Schema.Struct.Fields>>(definition: D) => MachineStateSchema<D>;
-/**
- * Create a schema-first Event definition.
- *
- * The schema's definition type D creates a unique brand, preventing
- * accidental use of constructors from different event schemas
- * (unless they have identical definitions).
- *
- * @example
- * ```ts
- * const OrderEvent = MachineSchema.Event({
- *   Ship: { trackingId: Schema.String },
- *   Cancel: {},
- * })
- *
- * type OrderEvent = typeof OrderEvent.Type
- *
- * // Construct
- * const e = OrderEvent.Ship({ trackingId: "abc" })
- * ```
- */
-declare const Event: <const D extends Record<string, Schema.Struct.Fields>>(definition: D) => MachineEventSchema<D>;
+declare const Event: (<const D extends Record<string, Schema.Struct.Fields>>(definition: D) => MachineEventSchema<D>) & {
+  reply: <F extends Schema.Struct.Fields, RS extends Schema.Schema.Any>(fields: F, replySchema: RS) => ReplyFields<F, RS>;
+};
 //#endregion
-export { Event, MachineEventSchema, MachineStateSchema, State, VariantsUnion };
+export { Event, MachineEventSchema, MachineStateSchema, ReplyFields, ReplySchemaSymbol, State, VariantsUnion };

package/v3/dist/schema.js

@@ -38,15 +38,21 @@ import { Schema } from "effect";
 *
 * @module
 */
+const ReplySchemaSymbol = Symbol.for("effect-machine/ReplySchema");
 /**
 * Build a schema-first definition from a record of tag -> fields
 */
 const buildMachineSchema = (definition) => {
 	const variants = {};
 	const constructors = {};
+	const replySchemas = /* @__PURE__ */ new Map();
 	for (const tag of Object.keys(definition)) {
 		const fields = definition[tag];
 		if (fields === void 0) continue;
+		if (ReplySchemaSymbol in fields) {
+			const rs = fields[ReplySchemaSymbol];
+			if (rs !== void 0) replySchemas.set(tag, rs);
+		}
 		variants[tag] = Schema.TaggedStruct(tag, fields);
 		const fieldNames = new Set(Object.keys(fields));
 		if (fieldNames.size > 0) {
@@ -93,6 +99,7 @@ const buildMachineSchema = (definition) => {
 		variants,
 		constructors,
 		_definition: definition,
+		_replySchemas: replySchemas,
 		$is,
 		$match
 	};
@@ -102,10 +109,11 @@ const buildMachineSchema = (definition) => {
 * Builds the schema object with variants, constructors, $is, and $match.
 */
 const createMachineSchema = (definition) => {
-	const { schema, variants, constructors, _definition, $is, $match } = buildMachineSchema(definition);
+	const { schema, variants, constructors, _definition, _replySchemas, $is, $match } = buildMachineSchema(definition);
 	return Object.assign(Object.create(schema), {
 		variants,
 		_definition,
+		_replySchemas,
 		$is,
 		$match,
 		...constructors
@@ -148,11 +156,15 @@ const State = (definition) => createMachineSchema(definition);
 * accidental use of constructors from different event schemas
 * (unless they have identical definitions).
 *
+* Use `Event.reply(fields, replySchema)` to define events that support
+* typed `ask()` replies.
+*
 * @example
 * ```ts
-* const OrderEvent = MachineSchema.Event({
+* const OrderEvent = Event({
 *   Ship: { trackingId: Schema.String },
 *   Cancel: {},
+*   GetTotal: Event.reply({}, Schema.Number),
 * })
 *
 * type OrderEvent = typeof OrderEvent.Type
@@ -161,6 +173,20 @@ const State = (definition) => createMachineSchema(definition);
 * const e = OrderEvent.Ship({ trackingId: "abc" })
 * ```
 */
-const Event = (definition) => createMachineSchema(definition);
+const EventImpl = (definition) => createMachineSchema(definition);
+/**
+* Annotate event fields with a reply schema.
+* Events defined with `Event.reply(fields, replySchema)` enable typed `ask()`.
+*/
+const replyFieldsFn = (fields, replySchema) => {
+	const annotated = { ...fields };
+	Object.defineProperty(annotated, ReplySchemaSymbol, {
+		value: replySchema,
+		enumerable: false,
+		writable: false
+	});
+	return annotated;
+};
+const Event = Object.assign(EventImpl, { reply: replyFieldsFn });
 //#endregion
 export { Event, State };