effect-machine 0.2.4 → 0.3.0

package/src/schema.ts

@@ -74,11 +74,30 @@ type IsEmptyFields<Fields extends Schema.Struct.Fields> = keyof Fields extends n
  * 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.
+ */
+/**
+ * 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.
+ * The source type uses `object` to accept branded state types without index signature issues.
  */
 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
-    : (args: Schema.Struct.Constructor<D[K]>) => TaggedStructType<K, D[K]> & Brand;
+    ? TaggedStructType<K, D[K]> &
+        Brand & {
+          readonly derive: (source: object) => TaggedStructType<K, D[K]> & Brand;
+        }
+    : ((args: Schema.Struct.Constructor<D[K]>) => TaggedStructType<K, D[K]> & Brand) & {
+        readonly derive: (
+          source: object,
+          partial?: Partial<Schema.Struct.Constructor<D[K]>>,
+        ) => TaggedStructType<K, D[K]> & Brand;
+        readonly _tag: K;
+      };
 };
 
 /**
@@ -92,6 +111,11 @@ type MatchCases<D extends Record<string, Schema.Struct.Fields>, R> = {
  * Base schema interface with pattern matching helpers
  */
 interface MachineSchemaBase<D extends Record<string, Schema.Struct.Fields>, Brand> {
+  /**
+   * Raw definition record for introspection
+   */
+  readonly _definition: D;
+
   /**
    * Per-variant schemas for fine-grained operations
    */
@@ -164,6 +188,7 @@ const buildMachineSchema = <D extends Record<string, Schema.Struct.Fields>>(
   schema: Schema.Schema<VariantsUnion<D>, VariantsUnion<D>, never>;
   variants: VariantSchemas<D>;
   constructors: Record<string, (args: Record<string, unknown>) => Record<string, unknown>>;
+  _definition: D;
   $is: <Tag extends string>(tag: Tag) => (u: unknown) => boolean;
   $match: (valueOrCases: unknown, maybeCases?: unknown) => unknown;
 } => {
@@ -184,16 +209,29 @@ const buildMachineSchema = <D extends Record<string, Schema.Struct.Fields>>(
     // Create constructor that builds tagged struct directly
     // Like Data.taggedEnum, this doesn't validate at construction time
     // Use Schema.decode for validation when needed
-    const hasFields = Object.keys(fields).length > 0;
+    const fieldNames = new Set(Object.keys(fields));
+    const hasFields = fieldNames.size > 0;
 
     if (hasFields) {
       // Non-empty: constructor function requiring args
       const constructor = (args: Record<string, unknown>) => ({ ...args, _tag: tag });
       constructor._tag = tag;
+      constructor.derive = (source: Record<string, unknown>, partial?: Record<string, unknown>) => {
+        const result: Record<string, unknown> = { _tag: tag };
+        for (const key of fieldNames) {
+          if (key in source) result[key] = source[key];
+        }
+        if (partial !== undefined) {
+          for (const [key, value] of Object.entries(partial)) {
+            result[key] = value;
+          }
+        }
+        return result;
+      };
       constructors[tag] = constructor;
     } else {
       // Empty: plain value, not callable
-      constructors[tag] = { _tag: tag } as never;
+      constructors[tag] = { _tag: tag, derive: () => ({ _tag: tag }) } as never;
     }
   }
 
@@ -244,6 +282,7 @@ const buildMachineSchema = <D extends Record<string, Schema.Struct.Fields>>(
     schema: unionSchema as unknown as Schema.Schema<VariantsUnion<D>, VariantsUnion<D>, never>,
     variants: variants as unknown as VariantSchemas<D>,
     constructors,
+    _definition: definition,
     $is,
     $match,
   };
@@ -254,8 +293,15 @@ const buildMachineSchema = <D extends Record<string, Schema.Struct.Fields>>(
  * Builds the schema object with variants, constructors, $is, and $match.
  */
 const createMachineSchema = <D extends Record<string, Schema.Struct.Fields>>(definition: D) => {
-  const { schema, variants, constructors, $is, $match } = buildMachineSchema(definition);
-  return Object.assign(Object.create(schema), { variants, $is, $match, ...constructors });
+  const { schema, variants, constructors, _definition, $is, $match } =
+    buildMachineSchema(definition);
+  return Object.assign(Object.create(schema), {
+    variants,
+    _definition,
+    $is,
+    $match,
+    ...constructors,
+  });
 };
 
 /**

package/src/testing.ts

@@ -1,10 +1,17 @@
 import { Effect, SubscriptionRef } from "effect";
 
 import type { Machine, MachineRef } from "./machine.js";
+import { BuiltMachine } from "./machine.js";
 import { AssertionError } from "./errors.js";
 import type { GuardsDef, EffectsDef } from "./slot.js";
 import { executeTransition } from "./internal/transition.js";
 
+/** Accept either Machine or BuiltMachine for testing utilities. */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type MachineInput<S, E, R, GD extends GuardsDef, EFD extends EffectsDef> =
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  Machine<S, E, R, any, any, GD, EFD> | BuiltMachine<S, E, R>;
+
 /**
  * Result of simulating events through a machine
  */
@@ -39,11 +46,17 @@ export const simulate = Effect.fn("effect-machine.simulate")(function* <
   R,
   GD extends GuardsDef = Record<string, never>,
   EFD extends EffectsDef = Record<string, never>,
->(
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Schema fields need wide acceptance
-  machine: Machine<S, E, R, any, any, GD, EFD>,
-  events: ReadonlyArray<E>,
-) {
+>(input: MachineInput<S, E, R, GD, EFD>, events: ReadonlyArray<E>) {
+  const machine = (input instanceof BuiltMachine ? input._inner : input) as Machine<
+    S,
+    E,
+    R,
+    Record<string, never>,
+    Record<string, never>,
+    GD,
+    EFD
+  >;
+
   // Create a dummy self for slot accessors
   const dummySelf: MachineRef<E> = {
     send: Effect.fn("effect-machine.testing.simulate.send")((_event: E) => Effect.void),
@@ -83,13 +96,8 @@ export const assertReaches = Effect.fn("effect-machine.assertReaches")(function*
   R,
   GD extends GuardsDef = Record<string, never>,
   EFD extends EffectsDef = Record<string, never>,
->(
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Schema fields need wide acceptance
-  machine: Machine<S, E, R, any, any, GD, EFD>,
-  events: ReadonlyArray<E>,
-  expectedTag: string,
-) {
-  const result = yield* simulate(machine, events);
+>(input: MachineInput<S, E, R, GD, EFD>, events: ReadonlyArray<E>, expectedTag: string) {
+  const result = yield* simulate(input, events);
   if (result.finalState._tag !== expectedTag) {
     return yield* new AssertionError({
       message:
@@ -119,12 +127,11 @@ export const assertPath = Effect.fn("effect-machine.assertPath")(function* <
   GD extends GuardsDef = Record<string, never>,
   EFD extends EffectsDef = Record<string, never>,
 >(
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Schema fields need wide acceptance
-  machine: Machine<S, E, R, any, any, GD, EFD>,
+  input: MachineInput<S, E, R, GD, EFD>,
   events: ReadonlyArray<E>,
   expectedPath: ReadonlyArray<string>,
 ) {
-  const result = yield* simulate(machine, events);
+  const result = yield* simulate(input, events);
   const actualPath = result.states.map((s) => s._tag);
 
   if (actualPath.length !== expectedPath.length) {
@@ -169,13 +176,8 @@ export const assertNeverReaches = Effect.fn("effect-machine.assertNeverReaches")
   R,
   GD extends GuardsDef = Record<string, never>,
   EFD extends EffectsDef = Record<string, never>,
->(
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Schema fields need wide acceptance
-  machine: Machine<S, E, R, any, any, GD, EFD>,
-  events: ReadonlyArray<E>,
-  forbiddenTag: string,
-) {
-  const result = yield* simulate(machine, events);
+>(input: MachineInput<S, E, R, GD, EFD>, events: ReadonlyArray<E>, forbiddenTag: string) {
+  const result = yield* simulate(input, events);
 
   const visitedIndex = result.states.findIndex((s) => s._tag === forbiddenTag);
   if (visitedIndex !== -1) {
@@ -236,11 +238,17 @@ export const createTestHarness = Effect.fn("effect-machine.createTestHarness")(f
   R,
   GD extends GuardsDef = Record<string, never>,
   EFD extends EffectsDef = Record<string, never>,
->(
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Schema fields need wide acceptance
-  machine: Machine<S, E, R, any, any, GD, EFD>,
-  options?: TestHarnessOptions<S, E>,
-) {
+>(input: MachineInput<S, E, R, GD, EFD>, options?: TestHarnessOptions<S, E>) {
+  const machine = (input instanceof BuiltMachine ? input._inner : input) as Machine<
+    S,
+    E,
+    R,
+    Record<string, never>,
+    Record<string, never>,
+    GD,
+    EFD
+  >;
+
   // Create a dummy self for slot accessors
   const dummySelf: MachineRef<E> = {
     send: Effect.fn("effect-machine.testing.harness.send")((_event: E) => Effect.void),