SugarCraft — CandyAsync

🍬 CandyAsync

Shared async vocabulary for ReactPHP

pioneering (no upstream) async cancellation reactphp foundation

Shared async vocabulary unifying ReactPHP usage across the SugarCraft monorepo. CancellationToken (owner/source pattern), Subscription interface, Subscriptions::compose() for atomic disposal, and AsyncOps static helpers for common async patterns.

Install

composer require sugarcraft/candy-async

Quickstart

use SugarCraft\Async\{AsyncOps, CancellationSource};

$source = CancellationSource::new();

// Attach a cancellation callback
$source->token()->onCancel(fn() => echo "Cancelled!\n");

$source->cancel(); // prints "Cancelled!"

// Timeout wrapper
$loop = \React\EventLoop\Loop::get();
$promise = AsyncOps::withTimeout($loop, $somePromise, 5.0);

// Retry with backoff
$promise = AsyncOps::retry(
    fn() => $httpClient->request('GET', 'https://example.com'),
    attempts: 3,
    baseBackoffSeconds: 0.5,
);

What's in the box

CancellationTokenRead-only view of a cancellation state. Consumers can observe isCancelled() and register onCancel() callbacks but cannot trigger cancellation.

CancellationSourceOwns the mutable cancellation flag. Create via CancellationSource::new(). Call cancel() to flip the flag and fire all registered callbacks.

Cancellable interfaceContract for components that can be cancelled. Implemented by CancellationSource. Callbacks fire exactly once, even on repeated cancel() calls.

Subscription interfaceDisposal handle returned by subscribe()-style APIs. unsubscribe() disposes the subscription; isActive() reports whether it is still live.

Subscriptions::compose()Combine multiple subscriptions into a single atomic handle. Calling unsubscribe() on the composite disposes all underlying subscriptions.

AsyncOps::withTimeout()Wrap a promise with a timeout. Rejects with TimeoutException if the timeout fires before the promise settles.

AsyncOps::retry()Retry a failed operation up to N times with exponential backoff. Respects CancellationToken — cancelling aborts remaining retries.

AsyncOps::debounce()Wrap a callable so only the last call within the window fires, after silence.

AsyncOps::throttle()Wrap a callable so it fires at most once per interval, ignoring excess calls.

Use it for

Unified cancellation — replace ad-hoc cancellation scattered across candy-core, candy-forms, sugar-prompt with a shared pattern.
TEA subscriptions lifecycle — Subscriptions::compose() lets the runtime dispose all subscriptions atomically.
Async operation helpers — withTimeout, retry, debounce, throttle built on top of react/promise and react/event-loop.

Source & demos

Source on GitHub
Full README
Runnable examples
Pioneering — no upstream parallel

Try the quickstart →

API

Class	Method	Description
CancellationSource	new(): self	Factory: create a new source with its own token
CancellationSource	token(): CancellationToken	Returns the read-only token for this source
CancellationSource	cancel(): void	Request cancellation. Idempotent.
CancellationSource	isCancelled(): bool	Returns true if cancel() has been called
CancellationToken	isCancelled(): bool	Returns true if the source has been cancelled
CancellationToken	onCancel(callable): void	Register a callback; fires immediately if already cancelled
Subscriptions	compose(Subscription ...): self	Combine multiple subscriptions into one atomic handle
Subscriptions	unsubscribe(): void	Dispose all underlying subscriptions
Subscriptions	isActive(): bool	Returns false after unsubscribe()
AsyncOps	withTimeout(LoopInterface, PromiseInterface, float): PromiseInterface	Wrap a promise with a timeout; rejects with TimeoutException
AsyncOps	retry(callable, int, float, ?CancellationToken): PromiseInterface	Retry with exponential backoff; respects cancellation
AsyncOps	debounce(callable, float, ?LoopInterface): callable	Debounce wrapper; only last call fires after window
AsyncOps	throttle(callable, float, ?LoopInterface): callable	Throttle wrapper; fires at most once per interval