Unify V2 helper API: remove split functions, add signal(), timer sugar

Remove startActivity(), startChild(), awaitWithTimeout(), awaitSignal(),
and parallel() from the V2 public API. The all() function now accepts
closures which are resolved via whileInactive(), replacing the start*
variants. awaitSignal() is renamed to signal(). awaitWithTimeout() is
merged into await() with an optional timeout: parameter. Timer sugar
helpers (seconds, minutes, hours, days, weeks, months, years) restored
from V1.

Closes #278

Author: durable-workflow-ops

src/V2/Support/QueryStateReplayer.php

@@ -544,7 +544,7 @@ public function replayState(WorkflowRun $run): ReplayState
 
             $this->syncWorkflowCursor($workflow, $sequence);
             throw new UnsupportedWorkflowYieldException(sprintf(
-                'Workflow %s yielded %s. v2 currently supports activity(), await(), awaitWithTimeout(), child(), all(), sideEffect(), getVersion(), timer(), awaitSignal(), and continueAsNew() only.',
+                'Workflow %s yielded %s. v2 currently supports activity(), child(), async(), all(), await(), signal(), timer(), sideEffect(), continueAsNew(), getVersion(), upsertMemo(), and upsertSearchAttributes() only.',
                 $run->workflow_class,
                 get_debug_type($current),
             ));

src/V2/Support/WorkflowExecutor.php

@@ -1136,7 +1136,7 @@ public function run(WorkflowRun $run, WorkflowTask $task): ?WorkflowTask
                 $run,
                 $task,
                 new UnsupportedWorkflowYieldException(sprintf(
-                    'Workflow %s yielded %s. v2 currently supports activity(), await(), awaitWithTimeout(), child(), all(), sideEffect(), getVersion(), timer(), awaitSignal(), and continueAsNew() only.',
+                    'Workflow %s yielded %s. v2 currently supports activity(), child(), async(), all(), await(), signal(), timer(), sideEffect(), continueAsNew(), getVersion(), upsertMemo(), and upsertSearchAttributes() only.',
                     $run->workflow_class,
                     get_debug_type($current),
                 )),

src/V2/functions.php

@@ -38,55 +38,6 @@ function activity(string $activity, mixed ...$arguments): mixed
     }
 }
 
-if (! function_exists(__NAMESPACE__ . '\\startActivity')) {
-    function startActivity(string $activity, mixed ...$arguments): ActivityCall
-    {
-        $options = null;
-
-        if (($arguments[0] ?? null) instanceof ActivityOptions) {
-            $options = array_shift($arguments);
-        }
-
-        return new ActivityCall($activity, $arguments, $options);
-    }
-}
-
-if (! function_exists(__NAMESPACE__ . '\\await')) {
-    function await(callable $condition, ?string $conditionKey = null): mixed
-    {
-        $condition = \Closure::fromCallable($condition);
-
-        return WorkflowFiberContext::suspend(new AwaitCall(
-            $condition,
-            Support\ConditionWaitKey::normalize($conditionKey),
-            Support\ConditionWaitDefinition::fingerprint($condition),
-        ));
-    }
-}
-
-if (! function_exists(__NAMESPACE__ . '\\awaitWithTimeout')) {
-    function awaitWithTimeout(
-        int|string|CarbonInterval $duration,
-        callable $condition,
-        ?string $conditionKey = null,
-    ): mixed {
-        if ($duration instanceof CarbonInterval) {
-            $duration = (int) ceil($duration->totalSeconds);
-        } elseif (is_string($duration)) {
-            $duration = (int) ceil(CarbonInterval::fromString($duration)->totalSeconds);
-        }
-
-        $condition = \Closure::fromCallable($condition);
-
-        return WorkflowFiberContext::suspend(new AwaitWithTimeoutCall(
-            max(0, $duration),
-            $condition,
-            Support\ConditionWaitKey::normalize($conditionKey),
-            Support\ConditionWaitDefinition::fingerprint($condition),
-        ));
-    }
-}
-
 if (! function_exists(__NAMESPACE__ . '\\child')) {
     function child(string $workflow, mixed ...$arguments): mixed
     {
@@ -100,55 +51,73 @@ function child(string $workflow, mixed ...$arguments): mixed
     }
 }
 
-if (! function_exists(__NAMESPACE__ . '\\startChild')) {
-    function startChild(string $workflow, mixed ...$arguments): ChildWorkflowCall
+if (! function_exists(__NAMESPACE__ . '\\async')) {
+    function async(callable $callback): mixed
     {
-        $options = null;
+        $reflection = match (true) {
+            is_array($callback) => new ReflectionMethod($callback[0], $callback[1]),
+            is_string($callback) && str_contains($callback, '::') => new ReflectionMethod($callback),
+            is_object($callback) && ! $callback instanceof \Closure => new ReflectionMethod($callback, '__invoke'),
+            default => new ReflectionFunction($callback),
+        };
 
-        if (($arguments[0] ?? null) instanceof ChildWorkflowOptions) {
-            $options = array_shift($arguments);
+        if ($reflection->isGenerator()) {
+            throw StraightLineWorkflowRequiredException::forAsyncCallback();
         }
 
-        return new ChildWorkflowCall($workflow, $arguments, $options);
+        return child(AsyncWorkflow::class, new SerializableClosure(\Closure::fromCallable($callback)));
     }
 }
 
 if (! function_exists(__NAMESPACE__ . '\\all')) {
     function all(iterable $calls): mixed
     {
-        return WorkflowFiberContext::suspend(new AllCall($calls));
-    }
-}
+        $resolved = [];
+
+        foreach ($calls as $call) {
+            if ($call instanceof \Closure) {
+                $resolved[] = WorkflowFiberContext::whileInactive($call);
+            } else {
+                $resolved[] = $call;
+            }
+        }
 
-if (! function_exists(__NAMESPACE__ . '\\parallel')) {
-    function parallel(iterable $calls): AllCall
-    {
-        return new AllCall($calls);
+        return WorkflowFiberContext::suspend(new AllCall($resolved));
     }
 }
 
-if (! function_exists(__NAMESPACE__ . '\\async')) {
-    function async(callable $callback): mixed
+if (! function_exists(__NAMESPACE__ . '\\await')) {
+    function await(callable $condition, int|string|CarbonInterval|null $timeout = null, ?string $conditionKey = null): mixed
     {
-        $reflection = match (true) {
-            is_array($callback) => new ReflectionMethod($callback[0], $callback[1]),
-            is_string($callback) && str_contains($callback, '::') => new ReflectionMethod($callback),
-            is_object($callback) && ! $callback instanceof \Closure => new ReflectionMethod($callback, '__invoke'),
-            default => new ReflectionFunction($callback),
-        };
+        $condition = \Closure::fromCallable($condition);
 
-        if ($reflection->isGenerator()) {
-            throw StraightLineWorkflowRequiredException::forAsyncCallback();
+        if ($timeout !== null) {
+            if ($timeout instanceof CarbonInterval) {
+                $timeout = (int) ceil($timeout->totalSeconds);
+            } elseif (is_string($timeout)) {
+                $timeout = (int) ceil(CarbonInterval::fromString($timeout)->totalSeconds);
+            }
+
+            return WorkflowFiberContext::suspend(new AwaitWithTimeoutCall(
+                max(0, $timeout),
+                $condition,
+                Support\ConditionWaitKey::normalize($conditionKey),
+                Support\ConditionWaitDefinition::fingerprint($condition),
+            ));
         }
 
-        return child(AsyncWorkflow::class, new SerializableClosure(\Closure::fromCallable($callback)));
+        return WorkflowFiberContext::suspend(new AwaitCall(
+            $condition,
+            Support\ConditionWaitKey::normalize($conditionKey),
+            Support\ConditionWaitDefinition::fingerprint($condition),
+        ));
     }
 }
 
-if (! function_exists(__NAMESPACE__ . '\\sideEffect')) {
-    function sideEffect(callable $callback): mixed
+if (! function_exists(__NAMESPACE__ . '\\signal')) {
+    function signal(string $name): mixed
     {
-        return WorkflowFiberContext::suspend(new SideEffectCall(\Closure::fromCallable($callback)));
+        return WorkflowFiberContext::suspend(new SignalCall($name));
     }
 }
 
@@ -165,10 +134,10 @@ function timer(int|string|CarbonInterval $duration): mixed
     }
 }
 
-if (! function_exists(__NAMESPACE__ . '\\awaitSignal')) {
-    function awaitSignal(string $name): mixed
+if (! function_exists(__NAMESPACE__ . '\\sideEffect')) {
+    function sideEffect(callable $callback): mixed
     {
-        return WorkflowFiberContext::suspend(new SignalCall($name));
+        return WorkflowFiberContext::suspend(new SideEffectCall(\Closure::fromCallable($callback)));
     }
 }
 
@@ -224,3 +193,54 @@ function getVersion(
         return WorkflowFiberContext::suspend(new VersionCall($changeId, $minSupported, $maxSupported));
     }
 }
+
+// Timer sugar
+
+if (! function_exists(__NAMESPACE__ . '\\seconds')) {
+    function seconds(int $seconds): mixed
+    {
+        return timer($seconds);
+    }
+}
+
+if (! function_exists(__NAMESPACE__ . '\\minutes')) {
+    function minutes(int $minutes): mixed
+    {
+        return timer($minutes * 60);
+    }
+}
+
+if (! function_exists(__NAMESPACE__ . '\\hours')) {
+    function hours(int $hours): mixed
+    {
+        return timer($hours * 3600);
+    }
+}
+
+if (! function_exists(__NAMESPACE__ . '\\days')) {
+    function days(int $days): mixed
+    {
+        return timer($days * 86400);
+    }
+}
+
+if (! function_exists(__NAMESPACE__ . '\\weeks')) {
+    function weeks(int $weeks): mixed
+    {
+        return timer($weeks * 604800);
+    }
+}
+
+if (! function_exists(__NAMESPACE__ . '\\months')) {
+    function months(int $months): mixed
+    {
+        return timer("{$months} months");
+    }
+}
+
+if (! function_exists(__NAMESPACE__ . '\\years')) {
+    function years(int $years): mixed
+    {
+        return timer("{$years} years");
+    }
+}

tests/Fixtures/V2/TestAliasedUpdateWorkflow.php

@@ -8,7 +8,7 @@
 use Workflow\UpdateMethod;
 use Workflow\V2\Attributes\Signal;
 use Workflow\V2\Attributes\Type;
-use function Workflow\V2\awaitSignal;
+use function Workflow\V2\signal;
 use Workflow\V2\Workflow;
 
 #[Type('test-aliased-update-workflow')]
@@ -29,7 +29,7 @@ public function handle(): array
         $this->stage = 'waiting-for-name';
         $this->events[] = 'started';
 
-        awaitSignal('name-provided');
+        signal('name-provided');
 
         $this->stage = 'completed';
         $this->events[] = 'signal:received';

tests/Fixtures/V2/TestAwaitWithTimeoutWorkflow.php

@@ -7,7 +7,7 @@
 use Workflow\QueryMethod;
 use Workflow\UpdateMethod;
 use Workflow\V2\Attributes\Type;
-use function Workflow\V2\awaitWithTimeout;
+use function Workflow\V2\await;
 use Workflow\V2\Workflow;
 
 #[Type('test-await-timeout-workflow')]
@@ -23,7 +23,7 @@ public function handle(): array
     {
         $this->stage = 'waiting-for-approval';
 
-        $approved = awaitWithTimeout(5, fn (): bool => $this->approved);
+        $approved = await(fn (): bool => $this->approved, timeout: 5);
 
         if (! $approved) {
             $this->timedOut = true;

tests/Fixtures/V2/TestBroadChildFailureCatchWorkflow.php

@@ -7,7 +7,7 @@
 use RuntimeException;
 use Workflow\QueryMethod;
 use Workflow\V2\Attributes\Signal;
-use function Workflow\V2\awaitSignal;
+use function Workflow\V2\signal;
 use function Workflow\V2\child;
 use Workflow\V2\Workflow;
 
@@ -36,7 +36,7 @@ public function handle(string $orderId): array
             ];
         }
 
-        $resume = awaitSignal('resume');
+        $resume = signal('resume');
         $this->stage = 'completed';
 
         return [

tests/Fixtures/V2/TestBroadFailureCatchWorkflow.php

@@ -8,7 +8,7 @@
 use Workflow\QueryMethod;
 use function Workflow\V2\activity;
 use Workflow\V2\Attributes\Signal;
-use function Workflow\V2\awaitSignal;
+use function Workflow\V2\signal;
 use Workflow\V2\Workflow;
 
 #[Signal('resume')]
@@ -36,7 +36,7 @@ public function handle(string $orderId): array
             ];
         }
 
-        $resume = awaitSignal('resume');
+        $resume = signal('resume');
         $this->stage = 'completed';
 
         return [

tests/Fixtures/V2/TestChildHandleChildWorkflow.php

@@ -7,7 +7,7 @@
 use Workflow\QueryMethod;
 use Workflow\V2\Attributes\Signal;
 use Workflow\V2\Attributes\Type;
-use function Workflow\V2\awaitSignal;
+use function Workflow\V2\signal;
 use Workflow\V2\Workflow;
 
 #[Type('test-child-handle-child-workflow')]
@@ -20,7 +20,7 @@ public function handle(): array
     {
         $this->stage = 'waiting-for-approval';
 
-        $approvedBy = awaitSignal('approved-by');
+        $approvedBy = signal('approved-by');
 
         $this->stage = 'approved';
 

tests/Fixtures/V2/TestCommandTargetWorkflow.php

@@ -8,7 +8,7 @@
 use Workflow\UpdateMethod;
 use Workflow\V2\Attributes\Signal;
 use Workflow\V2\Attributes\Type;
-use function Workflow\V2\awaitSignal;
+use function Workflow\V2\signal;
 use Workflow\V2\Workflow;
 
 #[Type('test-command-target-workflow')]
@@ -23,7 +23,7 @@ final class TestCommandTargetWorkflow extends Workflow
 {
     public function handle(): array
     {
-        awaitSignal('approved-by');
+        signal('approved-by');
 
         return [
             'workflow_id' => $this->workflowId(),

tests/Fixtures/V2/TestConfiguredContinueSignalWorkflow.php

@@ -7,7 +7,7 @@
 use Workflow\QueryMethod;
 use Workflow\UpdateMethod;
 use Workflow\V2\Attributes\Signal;
-use function Workflow\V2\awaitSignal;
+use function Workflow\V2\signal;
 use function Workflow\V2\continueAsNew;
 use Workflow\V2\Workflow;
 
@@ -29,7 +29,7 @@ public function handle(int $count = 0): mixed
             return continueAsNew($count + 1);
         }
 
-        $name = awaitSignal('name-provided');
+        $name = signal('name-provided');
 
         return [
             'name' => $name,