effect-machine 0.16.0 → 0.17.0

package/v3/dist/schema.d.ts

@@ -49,16 +49,23 @@ type VariantReplyBrand<Fields extends Schema.Struct.Fields> = Fields extends {
  * 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.
+ * Each variant also has a `with` method for constructing from a source object,
+ * copying matching fields and overriding with a partial.
  * 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 & VariantReplyBrand<D[K]> & {
-  readonly derive: (source: object) => TaggedStructType<K, D[K]> & Brand;
+  readonly with: (source: object) => TaggedStructType<K, D[K]> & Brand;
 } : ((args: Schema.Struct.Type<PayloadFields<D[K]>>) => TaggedStructType<K, D[K]> & Brand & VariantReplyBrand<D[K]>) & {
-  readonly derive: (source: object, partial?: Partial<Schema.Struct.Type<PayloadFields<D[K]>>>) => TaggedStructType<K, D[K]> & Brand;
+  readonly with: (source: object, partial?: Partial<Schema.Struct.Type<PayloadFields<D[K]>>>) => TaggedStructType<K, D[K]> & Brand;
   readonly _tag: K;
 } };
+/**
+ * Keys present in ALL variants (intersection of field names).
+ * Used by union-level `with` to accept only fields safe to update
+ * regardless of which variant the source is.
+ */
+type SharedKeys<D extends Record<string, Schema.Struct.Fields>> = keyof D[keyof D & string] & string;
 /**
  * Pattern matching cases type
  */
@@ -87,19 +94,23 @@ interface MachineSchemaBase<D extends Record<string, Schema.Struct.Fields>, Bran
     <R>(value: VariantsUnion<D> & Brand, cases: MatchCases<D, R>): R;
   };
   /**
-   * Union-level derive: copies fields from `source` into the same variant,
-   * overriding with `partial`. Preserves the specific variant subtype.
+   * Copy fields from `source` into the same variant, overriding with `partial`.
+   * Preserves the specific variant subtype in the return.
    *
-   * Dispatches to the per-variant `derive` based on `source._tag`.
+   * The partial accepts fields common to all variants, so it works safely
+   * when `S` is a generic type parameter (e.g., `<S extends MyState>`).
    *
    * @example
    * ```ts
-   * // Instead of switching on _tag to call per-variant derive:
-   * const updated = AgentLoopState.derive(state, { queue: newQueue })
-   * // If state is StreamingState, returns StreamingState (not LoopState)
+   * // Per-variant field update
+   * const next = MyState.Streaming.with(state, { draft: newDraft })
+   *
+   * // Cross-variant shared field — works with generic state
+   * const updateQueue = <S extends MyState>(state: S, queue: Queue): S =>
+   *   MyState.with(state, { queue })
    * ```
    */
-  readonly derive: <S extends VariantsUnion<D> & Brand>(source: S, partial?: Partial<Omit<S, "_tag">>) => S;
+  readonly with: <S extends VariantsUnion<D> & Brand>(source: S, partial?: Partial<Record<SharedKeys<D>, unknown>>) => S;
   /**
    * Reply schemas per variant tag. Only populated for event schemas
    * with variants defined via `Event.reply()`.
@@ -116,14 +127,16 @@ interface MachineSchemaBase<D extends Record<string, Schema.Struct.Fields>, Bran
  * The D type parameter captures the definition, creating a unique brand
  * per distinct schema definition shape.
  */
-type MachineStateSchema<D extends Record<string, Schema.Struct.Fields>> = Schema.Schema<VariantsUnion<D> & FullStateBrand<D>, unknown, never> & MachineSchemaBase<D, FullStateBrand<D>> & VariantConstructors<D, FullStateBrand<D>>;
+type MachineStateSchema<D extends Record<string, Schema.Struct.Fields>> = Schema.Schema<VariantsUnion<D> & FullStateBrand<D>, unknown> & MachineSchemaBase<D, FullStateBrand<D>> & VariantConstructors<D, FullStateBrand<D>> & {
+  /** Schema for persistence, config, and registration. */readonly schema: Schema.Schema<VariantsUnion<D> & FullStateBrand<D>>;
+};
 /**
  * Schema-first event definition (same structure as state, different brand)
  *
  * The D type parameter captures the definition, creating a unique brand
  * per distinct schema definition shape.
  */
-type MachineEventSchema<D extends Record<string, Schema.Struct.Fields>> = Schema.Schema<VariantsUnion<D> & FullEventBrand<D>, unknown, never> & MachineSchemaBase<D, FullEventBrand<D>> & VariantConstructors<D, FullEventBrand<D>>;
+type MachineEventSchema<D extends Record<string, Schema.Struct.Fields>> = Schema.Schema<VariantsUnion<D> & FullEventBrand<D>, unknown> & MachineSchemaBase<D, FullEventBrand<D>> & VariantConstructors<D, FullEventBrand<D>>;
 /**
  * Create a schema-first State definition.
  *

package/v3/dist/schema.js

@@ -62,7 +62,7 @@ const buildMachineSchema = (definition) => {
 				_tag: tag
 			});
 			constructor._tag = tag;
-			constructor.derive = (source, partial) => {
+			constructor.with = (source, partial) => {
 				const result = { _tag: tag };
 				for (const key of fieldNames) if (key in source) result[key] = source[key];
 				if (partial !== void 0) for (const [key, value] of Object.entries(partial)) {
@@ -75,7 +75,7 @@ const buildMachineSchema = (definition) => {
 			constructors[tag] = constructor;
 		} else constructors[tag] = {
 			_tag: tag,
-			derive: () => ({ _tag: tag })
+			with: () => ({ _tag: tag })
 		};
 	}
 	const variantArray = Object.values(variants);
@@ -112,20 +112,21 @@ const buildMachineSchema = (definition) => {
 */
 const createMachineSchema = (definition) => {
 	const { schema, variants, constructors, _definition, replySchemas, $is, $match } = buildMachineSchema(definition);
-	const derive = (source, partial) => {
+	const withFn = (source, partial) => {
 		const ctor = constructors[source._tag];
 		if (ctor === void 0) throw new MissingMatchHandlerError({ tag: source._tag });
-		const deriveFn = ctor.derive;
-		if (deriveFn === void 0) throw new MissingMatchHandlerError({ tag: source._tag });
-		return deriveFn(source, partial);
+		const fn = ctor.with;
+		if (fn === void 0) throw new MissingMatchHandlerError({ tag: source._tag });
+		return fn(source, partial);
 	};
 	return Object.assign(Object.create(schema), {
 		variants,
 		_definition,
 		_replySchemas: replySchemas,
+		schema,
 		$is,
 		$match,
-		derive,
+		with: withFn,
 		...constructors
 	});
 };

package/v3/dist/slot.d.ts

@@ -40,7 +40,7 @@ interface SlotFnDef<F extends Fields = Fields, _Return = void> {
  */
 declare const fn: {
   <F extends Fields, S extends Schema.Schema.Any>(fields: F, returnSchema: S): SlotFnDef<F, Schema.Schema.Type<S>>;
-  <F extends Fields>(fields: F): SlotFnDef<F, void>;
+  <F extends Fields>(fields: F): SlotFnDef<F>;
 };
 /**
  * Record of slot definitions. Keys are slot names, values are SlotFnDef.
@@ -149,9 +149,10 @@ declare const define: <D extends SlotsDef>(definitions: D) => SlotsSchema<D>;
 declare const Slot: {
   readonly fn: {
     <F extends Fields, S extends Schema.Schema.Any>(fields: F, returnSchema: S): SlotFnDef<F, Schema.Schema.Type<S>>;
-    <F extends Fields>(fields: F): SlotFnDef<F, void>;
+    <F extends Fields>(fields: F): SlotFnDef<F>;
   };
   readonly define: <D extends SlotsDef>(definitions: D) => SlotsSchema<D>;
+  readonly of: <D extends SlotsDef>(slotsSchema: SlotsSchema<D>, provided: ProvideSlots<D>) => SlotCalls<D>;
 };
 //#endregion
 export { HasSlotKeys, MachineContext, MachineContextTag, ProvideSlots, Slot, SlotCall, SlotCalls, SlotFnDef, SlotHandler, SlotInvocation, SlotRequest, SlotResult, SlotsDef, SlotsSchema, define, fn };

package/v3/dist/slot.js

@@ -1,4 +1,4 @@
-import { Context, Schema } from "effect";
+import { Context, Effect, Schema } from "effect";
 //#region src/slot.ts
 /**
 * Slot module — unified, schema-based parameterized slots.
@@ -122,9 +122,44 @@ const define = (definitions) => {
 		}
 	};
 };
+/**
+* Convert raw slot handler implementations into the callable `SlotCalls` form.
+*
+* Handlers that return plain values are wrapped in `Effect.succeed`.
+* Handlers that return Effects are called directly inside `Effect.suspend`.
+*
+* @example
+* ```ts
+* const provided = yield* myExtension.slots(ctx)
+* const slots = Slot.of(slotsSchema, provided)
+* // slots.mySlot({ param: 1 }) returns Effect<ReturnType>
+* ```
+*/
+const of = (slotsSchema, provided) => {
+	const slots = {};
+	for (const name of Object.keys(slotsSchema.definitions)) {
+		const handler = provided[name];
+		if (handler === void 0) continue;
+		const call = (params) => Effect.suspend(() => {
+			const result = handler(params);
+			return Effect.isEffect(result) ? result : Effect.succeed(result);
+		});
+		Object.defineProperty(call, "_tag", {
+			value: "Slot",
+			enumerable: true
+		});
+		Object.defineProperty(call, "name", {
+			value: name,
+			enumerable: true
+		});
+		slots[name] = call;
+	}
+	return slots;
+};
 const Slot = {
 	fn,
-	define
+	define,
+	of
 };
 //#endregion
 export { MachineContextTag, Slot, define, fn };