@actor-system/behaviors 0.0.17 → 0.0.18

package/dist/__bundle__/shared/dist/index.js

@@ -0,0 +1,3 @@
+const identity = (x) => x;
+
+export { identity };

package/dist/index.d.ts

@@ -1,13 +1,20 @@
-export { empty } from './empty.js';
-export { intercept } from './intercept.js';
+export { BehaviorInterceptor, intercept } from './intercept.js';
 export { named } from './named.js';
 export { ReceiveMessage, ReceiveSignal, receive, receiveMessage, receiveSignal } from './receive.js';
-export { restart } from './restart.js';
-export { same } from './same.js';
 export { setup } from './setup.js';
-export { stopped } from './stopped.js';
-export { supervise } from './supervise.js';
-export { unhandled } from './unhandled.js';
-export { Stash, withStash } from './with-stash.js';
+export { supervise } from './supervision/supervise.js';
+export { SupervisorStrategy, SupervisorStrategyContext } from './supervision/SupervisorStrategy.js';
+export { NoSuchElementError, StashBuffer, StashOverflowError, UnstashOptions, withStash } from './with-stash.js';
 export { Timers, withTimers } from './with-timers.js';
-export { Behavior } from '@actor-system/core';
+import { behavior, $restartBehavior } from '@actor-system/core';
+
+declare const empty: behavior.EmptyBehavior<never> & (<T>() => behavior.EmptyBehavior<T>);
+declare const restart: {
+    <T>(checkpoint: behavior.Behavior<T>): behavior.RestartBehavior<T>;
+    _tag: typeof $restartBehavior;
+};
+declare const same: behavior.SameBehavior<never> & (<T>() => behavior.SameBehavior<T>);
+declare const stopped: behavior.StoppedBehavior<never> & (<T>() => behavior.StoppedBehavior<T>);
+declare const unhandled: behavior.UnhandledBehavior<never> & (<T>() => behavior.UnhandledBehavior<T>);
+
+export { empty, restart, same, stopped, unhandled };

package/dist/index.internal.d.ts

@@ -1,13 +1,20 @@
-export { empty } from './empty.internal.js';
-export { intercept } from './intercept.internal.js';
+export { BehaviorInterceptor, intercept } from './intercept.internal.js';
 export { named } from './named.internal.js';
 export { ReceiveMessage, ReceiveSignal, receive, receiveMessage, receiveSignal } from './receive.internal.js';
-export { restart } from './restart.internal.js';
-export { same } from './same.internal.js';
 export { setup } from './setup.internal.js';
-export { stopped } from './stopped.internal.js';
-export { supervise } from './supervise.internal.js';
-export { unhandled } from './unhandled.internal.js';
-export { Stash, withStash } from './with-stash.internal.js';
+export { supervise } from './supervision/supervise.internal.js';
+export { SupervisorStrategy, SupervisorStrategyContext } from './supervision/SupervisorStrategy.internal.js';
+export { NoSuchElementError, StashBuffer, StashOverflowError, UnstashOptions, withStash } from './with-stash.internal.js';
 export { Timers, withTimers } from './with-timers.internal.js';
-export { Behavior } from '@actor-system/core/internal';
+import { behavior, $restartBehavior } from '@actor-system/core/internal';
+
+declare const empty: behavior.EmptyBehavior<never> & (<T>() => behavior.EmptyBehavior<T>);
+declare const restart: {
+    <T>(checkpoint: behavior.Behavior<T>): behavior.RestartBehavior<T>;
+    _tag: typeof $restartBehavior;
+};
+declare const same: behavior.SameBehavior<never> & (<T>() => behavior.SameBehavior<T>);
+declare const stopped: behavior.StoppedBehavior<never> & (<T>() => behavior.StoppedBehavior<T>);
+declare const unhandled: behavior.UnhandledBehavior<never> & (<T>() => behavior.UnhandledBehavior<T>);
+
+export { empty, restart, same, stopped, unhandled };

package/dist/index.js

@@ -1,12 +1,18 @@
-export { empty } from './empty.js';
 export { intercept } from './intercept.js';
 export { named } from './named.js';
 export { receive, receiveMessage, receiveSignal } from './receive.js';
-export { restart } from './restart.js';
-export { same } from './same.js';
 export { setup } from './setup.js';
-export { stopped } from './stopped.js';
-export { supervise } from './supervise.js';
-export { unhandled } from './unhandled.js';
-export { withStash } from './with-stash.js';
+export { supervise } from './supervision/supervise.js';
+export { SupervisorStrategy } from './supervision/SupervisorStrategy.js';
+export { NoSuchElementError, StashOverflowError, withStash } from './with-stash.js';
 export { withTimers } from './with-timers.js';
+import { behavior } from '@actor-system/core';
+
+/* eslint-enable @typescript-eslint/no-unused-vars */
+const empty = behavior._empty;
+const restart = behavior._restart;
+const same = behavior._same;
+const stopped = behavior._stopped;
+const unhandled = behavior._unhandled;
+
+export { empty, restart, same, stopped, unhandled };

package/dist/intercept.d.ts

@@ -1,10 +1,8 @@
-import { behavior, signal, ActorContext } from '@actor-system/core';
-import { Bivariant } from './__bundle__/shared/dist/types.js';
+import { signal, behavior, ActorContext } from '@actor-system/core';
 
-type Interceptor<Input, Output = Input> = Bivariant<(post: Output | signal.Signal, context: ActorContext<Output>) => Input | signal.Signal | behavior.Behavior<Input>>;
-declare function intercept<Input, Output = Input>(inner: behavior.Folded<Input>, interceptor: Interceptor<Input, Output>): behavior.Folded<Output>;
-declare function intercept<Input, Output = Input>(inner: behavior.Control<Input>, interceptor: Interceptor<Input, Output>): behavior.Control<Output>;
-declare function intercept<Input, Output = Input>(inner: behavior.Receive<Input>, interceptor: Interceptor<Input, Output>): behavior.Receive<Output>;
-declare function intercept<Input, Output = Input>(inner: behavior.Behavior<Input>, interceptor: Interceptor<Input, Output>): behavior.Behavior<Output>;
+type ReceiveTarget<T> = (message: T | signal.Signal) => behavior.Behavior<T>;
+type BehaviorInterceptor<Outer, Inner = Outer> = (message: Outer | signal.Signal, innerReceive: ReceiveTarget<Inner>, context: ActorContext<Inner | Outer>) => behavior.Behavior<Inner>;
+declare const intercept: <Outer, Inner = Outer>(interceptor: BehaviorInterceptor<Outer, Inner>) => (innerBehavior: behavior.Behavior<Inner>) => behavior.Behavior<Outer>;
 
 export { intercept };
+export type { BehaviorInterceptor, ReceiveTarget };

package/dist/intercept.internal.d.ts

@@ -1,10 +1,8 @@
-import { behavior, signal, ActorContext } from '@actor-system/core/internal';
-import { Bivariant } from './__bundle__/shared/dist/types.internal.js';
+import { signal, behavior, ActorContext } from '@actor-system/core/internal';
 
-type Interceptor<Input, Output = Input> = Bivariant<(post: Output | signal.Signal, context: ActorContext<Output>) => Input | signal.Signal | behavior.Behavior<Input>>;
-declare function intercept<Input, Output = Input>(inner: behavior.Folded<Input>, interceptor: Interceptor<Input, Output>): behavior.Folded<Output>;
-declare function intercept<Input, Output = Input>(inner: behavior.Control<Input>, interceptor: Interceptor<Input, Output>): behavior.Control<Output>;
-declare function intercept<Input, Output = Input>(inner: behavior.Receive<Input>, interceptor: Interceptor<Input, Output>): behavior.Receive<Output>;
-declare function intercept<Input, Output = Input>(inner: behavior.Behavior<Input>, interceptor: Interceptor<Input, Output>): behavior.Behavior<Output>;
+type ReceiveTarget<T> = (message: T | signal.Signal) => behavior.Behavior<T>;
+type BehaviorInterceptor<Outer, Inner = Outer> = (message: Outer | signal.Signal, innerReceive: ReceiveTarget<Inner>, context: ActorContext<Inner | Outer>) => behavior.Behavior<Inner>;
+declare const intercept: <Outer, Inner = Outer>(interceptor: BehaviorInterceptor<Outer, Inner>) => (innerBehavior: behavior.Behavior<Inner>) => behavior.Behavior<Outer>;
 
 export { intercept };
+export type { BehaviorInterceptor, ReceiveTarget };

package/dist/intercept.js

@@ -2,22 +2,16 @@ import { behavior } from '@actor-system/core';
 import { receive } from './receive.js';
 import { setup } from './setup.js';
 
-function intercept(inner, interceptor) {
-    if (behavior.isControl(inner)) {
-        return inner;
+const intercept = (interceptor) => (innerBehavior) => {
+    // if the inner behavior is a folded behavior, unfold it and intercept the result
+    if (behavior.isFolded(innerBehavior)) {
+        return setup((context) => intercept(interceptor)(behavior.unfold(innerBehavior, context)));
     }
-    if (behavior.isFolded(inner)) {
-        return setup((ctx) => intercept(behavior.unfold(inner, ctx), interceptor));
+    // if the inner behavior is a receive behavior, create a new receive behavior that applies the interceptor
+    if (behavior.isReceive(innerBehavior)) {
+        return receive((message, context) => intercept(interceptor)(interceptor(message, (msg) => innerBehavior._receive(msg, context), context)));
     }
-    if (behavior.isReceive(inner)) {
-        return receive((message, context) => {
-            const intercepted = interceptor(message, context);
-            return behavior.isBehavior(intercepted)
-                ? intercept(intercepted, interceptor)
-                : intercept(behavior.delegate(inner, intercepted, context), interceptor);
-        });
-    }
-    throw new Error(`Cannot intercept behavior of type ${inner} with interceptor`);
-}
+    return innerBehavior;
+};
 
 export { intercept };

package/dist/named.d.ts

@@ -1,9 +1,9 @@
-import { Behavior } from '@actor-system/core';
+import { behavior } from '@actor-system/core';
 
 /**
  * Creates a named version of a behavior using template literal syntax.
  * This is useful for debugging and behavior change tracking.
  */
-declare const named: (strings: TemplateStringsArray, ...values: unknown[]) => <B extends Behavior<unknown>>(targetBehavior: B) => B;
+declare const named: (strings: TemplateStringsArray, ...values: unknown[]) => <B extends behavior.Behavior<unknown>>(targetBehavior: B) => B;
 
 export { named };

package/dist/named.internal.d.ts

@@ -1,9 +1,9 @@
-import { Behavior } from '@actor-system/core/internal';
+import { behavior } from '@actor-system/core/internal';
 
 /**
  * Creates a named version of a behavior using template literal syntax.
  * This is useful for debugging and behavior change tracking.
  */
-declare const named: (strings: TemplateStringsArray, ...values: unknown[]) => <B extends Behavior<unknown>>(targetBehavior: B) => B;
+declare const named: (strings: TemplateStringsArray, ...values: unknown[]) => <B extends behavior.Behavior<unknown>>(targetBehavior: B) => B;
 
 export { named };

package/dist/receive.d.ts

@@ -1,15 +1,15 @@
 import { signal, ActorContext, behavior } from '@actor-system/core';
 import { Bivariant } from './__bundle__/shared/dist/types.js';
 
-interface ReceiveMessage<T> extends behavior.Receive<T> {
-    receiveSignal(handler: Bivariant<(signal: signal.Signal, ctx: ActorContext<T>) => behavior.Behavior<T> | void>): behavior.Receive<T>;
+interface ReceiveMessage<T = unknown> extends behavior.ReceiveBehavior<T> {
+    receiveSignal(handler: Bivariant<(signal: signal.Signal, ctx: ActorContext<T>) => behavior.Behavior<T> | void>): behavior.ReceiveBehavior<T>;
 }
-interface ReceiveSignal<T> extends behavior.Receive<T> {
-    receiveMessage(handler: Bivariant<(message: T, ctx: ActorContext<T>) => behavior.Behavior<T> | void>): behavior.Receive<T>;
+interface ReceiveSignal<T> extends behavior.ReceiveBehavior<T> {
+    receiveMessage(handler: Bivariant<(message: T, ctx: ActorContext<T>) => behavior.Behavior<T> | void>): behavior.ReceiveBehavior<T>;
 }
 declare const receiveMessage: <T>(onMessage: Bivariant<(message: T, context: ActorContext<T>) => behavior.Behavior<T> | void>) => ReceiveMessage<T>;
 declare const receiveSignal: <T>(onSignal: Bivariant<(signal: signal.Signal, context: ActorContext<T>) => behavior.Behavior<T> | void>) => ReceiveSignal<T>;
-declare const receive: <T>(handler: Bivariant<(messageOrSignal: T | signal.Signal, context: ActorContext<T>) => behavior.Behavior<T> | void>) => behavior.Receive<T>;
+declare const receive: <T>(handler: Bivariant<(messageOrSignal: T | signal.Signal, context: ActorContext<T>) => behavior.Behavior<T> | void>) => behavior.ReceiveBehavior<T>;
 
 export { receive, receiveMessage, receiveSignal };
 export type { ReceiveMessage, ReceiveSignal };

package/dist/receive.internal.d.ts

@@ -1,15 +1,15 @@
 import { signal, ActorContext, behavior } from '@actor-system/core/internal';
 import { Bivariant } from './__bundle__/shared/dist/types.internal.js';
 
-interface ReceiveMessage<T> extends behavior.Receive<T> {
-    receiveSignal(handler: Bivariant<(signal: signal.Signal, ctx: ActorContext<T>) => behavior.Behavior<T> | void>): behavior.Receive<T>;
+interface ReceiveMessage<T = unknown> extends behavior.ReceiveBehavior<T> {
+    receiveSignal(handler: Bivariant<(signal: signal.Signal, ctx: ActorContext<T>) => behavior.Behavior<T> | void>): behavior.ReceiveBehavior<T>;
 }
-interface ReceiveSignal<T> extends behavior.Receive<T> {
-    receiveMessage(handler: Bivariant<(message: T, ctx: ActorContext<T>) => behavior.Behavior<T> | void>): behavior.Receive<T>;
+interface ReceiveSignal<T> extends behavior.ReceiveBehavior<T> {
+    receiveMessage(handler: Bivariant<(message: T, ctx: ActorContext<T>) => behavior.Behavior<T> | void>): behavior.ReceiveBehavior<T>;
 }
 declare const receiveMessage: <T>(onMessage: Bivariant<(message: T, context: ActorContext<T>) => behavior.Behavior<T> | void>) => ReceiveMessage<T>;
 declare const receiveSignal: <T>(onSignal: Bivariant<(signal: signal.Signal, context: ActorContext<T>) => behavior.Behavior<T> | void>) => ReceiveSignal<T>;
-declare const receive: <T>(handler: Bivariant<(messageOrSignal: T | signal.Signal, context: ActorContext<T>) => behavior.Behavior<T> | void>) => behavior.Receive<T>;
+declare const receive: <T>(handler: Bivariant<(messageOrSignal: T | signal.Signal, context: ActorContext<T>) => behavior.Behavior<T> | void>) => behavior.ReceiveBehavior<T>;
 
 export { receive, receiveMessage, receiveSignal };
 export type { ReceiveMessage, ReceiveSignal };

package/dist/receive.js

@@ -1,19 +1,21 @@
 import { behavior, signal } from '@actor-system/core';
-import { same } from './same.js';
-import { unhandled } from './unhandled.js';
 
 const receiveMessage = (onMessage) => ({
-    ...behavior.receive((message, ctx) => !signal.isSignal(message) ? (onMessage(message, ctx) ?? unhandled) : same),
-    receiveSignal: (onSignal) => behavior.receive((message, context) => !signal.isSignal(message)
-        ? (onMessage(message, context) ?? unhandled)
-        : (onSignal(message, context) ?? unhandled)),
+    ...behavior._receive((message, ctx) => !signal.isSignal(message)
+        ? (onMessage(message, ctx) ?? behavior._unhandled)
+        : behavior._same),
+    receiveSignal: (onSignal) => behavior._receive((message, context) => !signal.isSignal(message)
+        ? (onMessage(message, context) ?? behavior._unhandled)
+        : (onSignal(message, context) ?? behavior._unhandled)),
 });
 const receiveSignal = (onSignal) => ({
-    ...behavior.receive((message, ctx) => signal.isSignal(message) ? (onSignal(message, ctx) ?? unhandled) : same),
-    receiveMessage: (onMessage) => behavior.receive((message, context) => signal.isSignal(message)
-        ? (onSignal(message, context) ?? unhandled)
-        : (onMessage(message, context) ?? unhandled)),
+    ...behavior._receive((message, ctx) => signal.isSignal(message)
+        ? (onSignal(message, ctx) ?? behavior._unhandled)
+        : behavior._same),
+    receiveMessage: (onMessage) => behavior._receive((message, context) => signal.isSignal(message)
+        ? (onSignal(message, context) ?? behavior._unhandled)
+        : (onMessage(message, context) ?? behavior._unhandled)),
 });
-const receive = (handler) => behavior.receive((message, ctx) => handler(message, ctx) ?? unhandled);
+const receive = (handler) => behavior._receive((message, ctx) => handler(message, ctx) ?? behavior._unhandled);
 
 export { receive, receiveMessage, receiveSignal };

package/dist/setup.d.ts

@@ -2,7 +2,7 @@ import { ActorContext, behavior } from '@actor-system/core';
 import { Bivariant } from './__bundle__/shared/dist/types.js';
 
 type SetupFactory<T> = Bivariant<(context: ActorContext<T>) => behavior.Behavior<T> | void>;
-declare const setup: <T>(factory: SetupFactory<T>) => behavior.Folded<T>;
+declare const setup: <T>(factory: SetupFactory<T>) => behavior.FoldedBehavior<T>;
 
 export { setup };
 export type { SetupFactory };

package/dist/setup.internal.d.ts

@@ -2,7 +2,7 @@ import { ActorContext, behavior } from '@actor-system/core/internal';
 import { Bivariant } from './__bundle__/shared/dist/types.internal.js';
 
 type SetupFactory<T> = Bivariant<(context: ActorContext<T>) => behavior.Behavior<T> | void>;
-declare const setup: <T>(factory: SetupFactory<T>) => behavior.Folded<T>;
+declare const setup: <T>(factory: SetupFactory<T>) => behavior.FoldedBehavior<T>;
 
 export { setup };
 export type { SetupFactory };

package/dist/setup.js

@@ -1,6 +1,5 @@
 import { behavior } from '@actor-system/core';
-import { empty } from './empty.js';
 
-const setup = (factory) => behavior.folded((ctx) => factory(ctx) ?? empty);
+const setup = (factory) => behavior._folded((ctx) => factory(ctx) ?? behavior._empty);
 
 export { setup };

package/dist/supervision/SupervisorStrategy.d.ts

@@ -0,0 +1,14 @@
+import { ActorContext, behavior } from '@actor-system/core';
+
+interface SupervisorStrategyContext<T = unknown> extends ActorContext<T> {
+    readonly supervisedBehavior: behavior.Behavior<T>;
+}
+type SupervisorStrategy = <T = any>(error: unknown, context: SupervisorStrategyContext<T>) => behavior.Behavior<T>;
+declare const SupervisorStrategy: {
+    readonly stop: SupervisorStrategy;
+    readonly resume: SupervisorStrategy;
+    readonly restart: SupervisorStrategy;
+};
+
+export { SupervisorStrategy };
+export type { SupervisorStrategyContext };

package/dist/supervision/SupervisorStrategy.internal.d.ts

@@ -0,0 +1,14 @@
+import { ActorContext, behavior } from '@actor-system/core/internal';
+
+interface SupervisorStrategyContext<T = unknown> extends ActorContext<T> {
+    readonly supervisedBehavior: behavior.Behavior<T>;
+}
+type SupervisorStrategy = <T = any>(error: unknown, context: SupervisorStrategyContext<T>) => behavior.Behavior<T>;
+declare const SupervisorStrategy: {
+    readonly stop: SupervisorStrategy;
+    readonly resume: SupervisorStrategy;
+    readonly restart: SupervisorStrategy;
+};
+
+export { SupervisorStrategy };
+export type { SupervisorStrategyContext };

package/dist/supervision/SupervisorStrategy.js

@@ -0,0 +1,12 @@
+import { behavior } from '@actor-system/core';
+
+const resume = (_e, { supervisedBehavior }) => supervisedBehavior;
+const stop = () => behavior._stopped;
+const restart = (_error, { supervisedBehavior }) => behavior._restart(supervisedBehavior);
+const SupervisorStrategy = {
+    stop,
+    resume,
+    restart,
+};
+
+export { SupervisorStrategy };

package/dist/supervision/supervise.d.ts

@@ -0,0 +1,10 @@
+import { behavior } from '@actor-system/core';
+import { SupervisorStrategy } from './SupervisorStrategy.js';
+
+interface Supervised<T> {
+    onFailure(strategy: SupervisorStrategy): behavior.Behavior<T>;
+}
+declare const supervise: <T>(inner: behavior.Behavior<T>) => Supervised<T>;
+
+export { supervise };
+export type { Supervised };

package/dist/supervision/supervise.internal.d.ts

@@ -0,0 +1,10 @@
+import { behavior } from '@actor-system/core/internal';
+import { SupervisorStrategy } from './SupervisorStrategy.internal.js';
+
+interface Supervised<T> {
+    onFailure(strategy: SupervisorStrategy): behavior.Behavior<T>;
+}
+declare const supervise: <T>(inner: behavior.Behavior<T>) => Supervised<T>;
+
+export { supervise };
+export type { Supervised };

package/dist/supervision/supervise.js

@@ -0,0 +1,44 @@
+import { behavior } from '@actor-system/core';
+
+const supervise = (inner) => ({
+    onFailure: (strategy) => {
+        switch (inner._tag) {
+            case behavior._folded._tag:
+                return behavior._folded((context) => {
+                    try {
+                        const unfolded = behavior.unfold(inner, context);
+                        return supervise(unfolded).onFailure(strategy);
+                    }
+                    catch (error) {
+                        return strategy(error, {
+                            ...context,
+                            supervisedBehavior: supervise(inner).onFailure(strategy),
+                        });
+                    }
+                });
+            case behavior._receive._tag:
+                return behavior._receive((message, context) => {
+                    try {
+                        const next = behavior.interpret(inner, context, message);
+                        switch (next) {
+                            case behavior._same:
+                            case behavior._unhandled:
+                                return next;
+                            default:
+                                return supervise(next).onFailure(strategy);
+                        }
+                    }
+                    catch (error) {
+                        return strategy(error, {
+                            ...context,
+                            supervisedBehavior: supervise(inner).onFailure(strategy),
+                        });
+                    }
+                });
+            default:
+                return inner;
+        }
+    },
+});
+
+export { supervise };

package/dist/with-stash.d.ts

@@ -1,12 +1,67 @@
+import { Letter } from '@actor-system/mail';
 import { ActorContext, behavior } from '@actor-system/core';
 
-interface Stash<T> {
-    push(msg: T): void;
-    dropAll(): void;
-    popAll(): void;
-    readonly size: number;
+declare const withStash: <T>(capacity: number, factory: (stashBuffer: StashBuffer<T>) => behavior.Behavior<T>) => behavior.Behavior<T>;
+interface UnstashOptions<T> {
+    /**
+     * Number of messages to unstash.
+     * @default Number.POSITIVE_INFINITY
+     */
+    amount?: number;
+    /**
+     * Function to transform messages when unstashing.
+     */
+    map?: (msg: T) => T;
+}
+declare class StashBuffer<T> {
+    #private;
+    readonly capacity: number;
+    static create<T>(capacity: number, context: ActorContext<T>): StashBuffer<T>;
+    private constructor();
+    get size(): number;
+    /**
+     * Return the first element of the message buffer without removing it.
+     * @returns the first element or throws NoSuchElementError if the buffer is empty
+     * @throws {NoSuchElementError} if the buffer is empty
+     */
+    get head(): T;
+    /**
+     * Returns an iterable of messages in the buffer in insertion order.
+     * @returns An iterable of messages.
+     */
+    values(): SetIterator<T>;
+    /**
+     * Removes all messages from the buffer.
+     */
+    clear(): void;
+    /**
+     * Add one element to the end of the message buffer.
+     * @throws {StashOverflowError} if the buffer is full.
+     */
+    stash(msg: T): this;
+    /**
+     * Request replay of up to `numberOfMessages` messages using `map`.
+     *
+     * If called while another unstash is in progress, it does not replay
+     * immediately; it just marks that another replay is requested.
+     *
+     * Once the current replay finishes, any pending requests are bundled
+     * and a single replay pass is run again.
+     */
+    unstash(behavior: behavior.Behavior<T>, options?: UnstashOptions<T>): behavior.Behavior<T>;
+}
+declare const $noSuchElementError = "@@with-stash.no-such-element-error";
+declare class NoSuchElementError extends Error implements Letter<typeof $noSuchElementError> {
+    static readonly label = "@@with-stash.no-such-element-error";
+    readonly label: typeof $noSuchElementError;
+    constructor();
+}
+declare const $stashOverflowError = "@@with-stash.stash-overflow-error";
+declare class StashOverflowError extends Error implements Letter<typeof $stashOverflowError> {
+    static readonly label = "@@with-stash.stash-overflow-error";
+    readonly label: typeof $stashOverflowError;
+    constructor(message: string);
 }
-declare const withStash: <T>(factory: (stash: Stash<T>, context: ActorContext<T>) => behavior.Behavior<T>) => behavior.Behavior<T>;
 
-export { withStash };
-export type { Stash };
+export { NoSuchElementError, StashBuffer, StashOverflowError, withStash };
+export type { UnstashOptions };

package/dist/with-stash.internal.d.ts

@@ -1,12 +1,67 @@
+import { Letter } from '@actor-system/mail/internal';
 import { ActorContext, behavior } from '@actor-system/core/internal';
 
-interface Stash<T> {
-    push(msg: T): void;
-    dropAll(): void;
-    popAll(): void;
-    readonly size: number;
+declare const withStash: <T>(capacity: number, factory: (stashBuffer: StashBuffer<T>) => behavior.Behavior<T>) => behavior.Behavior<T>;
+interface UnstashOptions<T> {
+    /**
+     * Number of messages to unstash.
+     * @default Number.POSITIVE_INFINITY
+     */
+    amount?: number;
+    /**
+     * Function to transform messages when unstashing.
+     */
+    map?: (msg: T) => T;
+}
+declare class StashBuffer<T> {
+    #private;
+    readonly capacity: number;
+    static create<T>(capacity: number, context: ActorContext<T>): StashBuffer<T>;
+    private constructor();
+    get size(): number;
+    /**
+     * Return the first element of the message buffer without removing it.
+     * @returns the first element or throws NoSuchElementError if the buffer is empty
+     * @throws {NoSuchElementError} if the buffer is empty
+     */
+    get head(): T;
+    /**
+     * Returns an iterable of messages in the buffer in insertion order.
+     * @returns An iterable of messages.
+     */
+    values(): SetIterator<T>;
+    /**
+     * Removes all messages from the buffer.
+     */
+    clear(): void;
+    /**
+     * Add one element to the end of the message buffer.
+     * @throws {StashOverflowError} if the buffer is full.
+     */
+    stash(msg: T): this;
+    /**
+     * Request replay of up to `numberOfMessages` messages using `map`.
+     *
+     * If called while another unstash is in progress, it does not replay
+     * immediately; it just marks that another replay is requested.
+     *
+     * Once the current replay finishes, any pending requests are bundled
+     * and a single replay pass is run again.
+     */
+    unstash(behavior: behavior.Behavior<T>, options?: UnstashOptions<T>): behavior.Behavior<T>;
+}
+declare const $noSuchElementError = "@@with-stash.no-such-element-error";
+declare class NoSuchElementError extends Error implements Letter<typeof $noSuchElementError> {
+    static readonly label = "@@with-stash.no-such-element-error";
+    readonly label: typeof $noSuchElementError;
+    constructor();
+}
+declare const $stashOverflowError = "@@with-stash.stash-overflow-error";
+declare class StashOverflowError extends Error implements Letter<typeof $stashOverflowError> {
+    static readonly label = "@@with-stash.stash-overflow-error";
+    readonly label: typeof $stashOverflowError;
+    constructor(message: string);
 }
-declare const withStash: <T>(factory: (stash: Stash<T>, context: ActorContext<T>) => behavior.Behavior<T>) => behavior.Behavior<T>;
 
-export { withStash };
-export type { Stash };
+export { NoSuchElementError, StashBuffer, StashOverflowError, withStash };
+export type { UnstashOptions };

package/dist/with-stash.js

@@ -1,45 +1,112 @@
-import { signal } from '@actor-system/core';
 import { setup } from './setup.js';
-import { intercept } from './intercept.js';
+import { identity } from './__bundle__/shared/dist/index.js';
 
-const $stash = Symbol("stash");
-const withStash = (factory) => setup((context) => {
-    const stash = useStash(context);
-    const innerBehavior = factory(stash, context);
-    return intercept(innerBehavior, (post) => {
-        if (signal.isPostStop(post)) {
-            stash.dropAll();
+const withStash = (capacity, factory) => setup((context) => factory(StashBuffer.create(capacity, context)));
+class StashBuffer {
+    capacity;
+    #stash = [];
+    #context;
+    // replay control
+    #isReplaying = false;
+    #pendingReplays = [];
+    static create(capacity, context) {
+        return new StashBuffer(capacity, context);
+    }
+    constructor(capacity, context) {
+        this.capacity = capacity;
+        this.#context = context;
+    }
+    get size() {
+        return this.#stash.length;
+    }
+    /**
+     * Return the first element of the message buffer without removing it.
+     * @returns the first element or throws NoSuchElementError if the buffer is empty
+     * @throws {NoSuchElementError} if the buffer is empty
+     */
+    get head() {
+        if (this.#stash.length === 0) {
+            throw new NoSuchElementError();
         }
-        return post;
-    });
-});
-const useStash = (context, capacity = 100) => {
-    if (context[$stash])
-        return context[$stash];
-    const stack = [];
-    const stash = {
-        /** Stash a message for later processing */
-        push: (msg) => {
-            if (stack.length < capacity) {
-                stack.push(msg);
+        return this.#stash[0];
+    }
+    /**
+     * Returns an iterable of messages in the buffer in insertion order.
+     * @returns An iterable of messages.
+     */
+    values() {
+        return this.#stash.values();
+    }
+    /**
+     * Removes all messages from the buffer.
+     */
+    clear() {
+        this.#stash.length = 0;
+    }
+    /**
+     * Add one element to the end of the message buffer.
+     * @throws {StashOverflowError} if the buffer is full.
+     */
+    stash(msg) {
+        if (this.#stash.length >= this.capacity) {
+            throw new StashOverflowError(`Stash overflow: max capacity is ${this.capacity}`);
+        }
+        this.#stash.push(msg);
+        return this;
+    }
+    /**
+     * Request replay of up to `numberOfMessages` messages using `map`.
+     *
+     * If called while another unstash is in progress, it does not replay
+     * immediately; it just marks that another replay is requested.
+     *
+     * Once the current replay finishes, any pending requests are bundled
+     * and a single replay pass is run again.
+     */
+    unstash(behavior, options = {}) {
+        this.#pendingReplays.push(options);
+        if (this.#isReplaying)
+            return behavior;
+        this.#isReplaying = true;
+        return this.#unstashBehavior(behavior);
+    }
+    #unstashBehavior = (behavior) => {
+        let nextBehavior = behavior;
+        try {
+            while (this.#pendingReplays.length > 0 && this.#stash.length > 0) {
+                const { amount = Number.POSITIVE_INFINITY, map = identity } = this.#pendingReplays.shift();
+                const limit = Math.min(amount, this.#stash.length);
+                for (let index = 0; index < limit; index++) {
+                    if (this.#stash.length === 0)
+                        break;
+                    nextBehavior = this.#context.delegate(nextBehavior, map(this.#stash.shift()));
+                }
             }
-        },
-        /** Drop all stashed messages */
-        dropAll: () => {
-            stack.length = 0;
-        },
-        /** Unstash all messages, sending them to the actor's mailbox */
-        popAll: () => {
-            stack.forEach((msg) => context.self.tell(msg));
-            stack.length = 0;
-        },
-        /** Get current stash size */
-        get size() {
-            return stack.length;
-        },
+            return nextBehavior;
+        }
+        finally {
+            this.#isReplaying = false;
+            this.#pendingReplays.length = 0;
+        }
     };
-    context[$stash] = stash;
-    return stash;
-};
+}
+const $noSuchElementError = "@@with-stash.no-such-element-error";
+class NoSuchElementError extends Error {
+    static label = $noSuchElementError;
+    label = $noSuchElementError;
+    constructor() {
+        super("StashBuffer is empty");
+        this.name = "NoSuchElementError";
+    }
+}
+const $stashOverflowError = "@@with-stash.stash-overflow-error";
+class StashOverflowError extends Error {
+    static label = $stashOverflowError;
+    label = $stashOverflowError;
+    constructor(message) {
+        super(message);
+        this.name = "StashOverflowError";
+    }
+}
 
-export { useStash, withStash };
+export { NoSuchElementError, StashBuffer, StashOverflowError, withStash };

package/dist/with-timers.d.ts

@@ -5,7 +5,7 @@ interface Timers<T> {
     cancel(key: PropertyKey): void;
     cancelAll(): void;
 }
-declare const withTimers: <T>(factory: (timers: Timers<T>, context: ActorContext<T>) => behavior.Behavior<T>) => behavior.Folded<T>;
+declare const withTimers: <T>(factory: (timers: Timers<T>, context: ActorContext<T>) => behavior.Behavior<T>) => behavior.FoldedBehavior<T>;
 
 export { withTimers };
 export type { Timers };

package/dist/with-timers.internal.d.ts

@@ -5,7 +5,7 @@ interface Timers<T> {
     cancel(key: PropertyKey): void;
     cancelAll(): void;
 }
-declare const withTimers: <T>(factory: (timers: Timers<T>, context: ActorContext<T>) => behavior.Behavior<T>) => behavior.Folded<T>;
+declare const withTimers: <T>(factory: (timers: Timers<T>, context: ActorContext<T>) => behavior.Behavior<T>) => behavior.FoldedBehavior<T>;
 
 export { withTimers };
 export type { Timers };

package/dist/with-timers.js

@@ -5,13 +5,14 @@ import { setup } from './setup.js';
 const $timers = Symbol("timers");
 const withTimers = (factory) => setup((context) => {
     const timers = useTimers(context);
-    const innerBehavior = factory(timers, context);
-    return intercept(innerBehavior, (post) => {
-        if (signal.isPostStop(post)) {
+    const interceptor = (msg, next) => {
+        const nextBehavior = next(msg);
+        if (signal.isPostStop(msg)) {
             timers.cancelAll();
         }
-        return post;
-    });
+        return nextBehavior;
+    };
+    return intercept(interceptor)(factory(timers, context));
 });
 const useTimers = (context) => {
     if (context[$timers])

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@actor-system/behaviors",
-  "version": "0.0.17",
+  "version": "0.0.18",
   "type": "module",
   "scripts": {
     "type-check": "tsc -b src",
@@ -34,11 +34,11 @@
     "@actor-system/shared"
   ],
   "dependencies": {
-    "@actor-system/core": "0.1.1"
+    "@actor-system/core": "0.1.2"
   },
   "devDependencies": {
     "@actor-system/testing": "0.0.2",
-    "@actor-system/shared": "0.0.2",
+    "@actor-system/shared": "0.0.3",
     "config": "^1.0.0"
   }
 }

package/dist/empty.d.ts

@@ -1,5 +0,0 @@
-import { behavior } from '@actor-system/core';
-
-declare const empty: behavior.Receive<never>;
-
-export { empty };

package/dist/empty.internal.d.ts

@@ -1,5 +0,0 @@
-import { behavior } from '@actor-system/core/internal';
-
-declare const empty: behavior.Receive<never>;
-
-export { empty };

package/dist/empty.js

@@ -1,5 +0,0 @@
-import { behavior } from '@actor-system/core';
-
-const empty = behavior._empty;
-
-export { empty };

package/dist/restart.d.ts

@@ -1,5 +0,0 @@
-import { behavior } from '@actor-system/core';
-
-declare const restart: <T>(checkpoint: behavior.Behavior<T>) => behavior.Control<T>;
-
-export { restart };

package/dist/restart.internal.d.ts

@@ -1,5 +0,0 @@
-import { behavior } from '@actor-system/core/internal';
-
-declare const restart: <T>(checkpoint: behavior.Behavior<T>) => behavior.Control<T>;
-
-export { restart };

package/dist/restart.js

@@ -1,11 +0,0 @@
-import { behavior, $type } from '@actor-system/core';
-
-const restart = (checkpoint) => ({
-    [$type]: undefined,
-    _tag: behavior.$control,
-    _operation: "restart",
-    _checkpoint: checkpoint,
-    _name: "restart",
-});
-
-export { restart };

package/dist/same.d.ts

@@ -1,5 +0,0 @@
-import { behavior } from '@actor-system/core';
-
-declare const same: behavior.Control<never>;
-
-export { same };

package/dist/same.internal.d.ts

@@ -1,5 +0,0 @@
-import { behavior } from '@actor-system/core/internal';
-
-declare const same: behavior.Control<never>;
-
-export { same };

package/dist/same.js

@@ -1,5 +0,0 @@
-import { behavior } from '@actor-system/core';
-
-const same = behavior._same;
-
-export { same };

package/dist/stopped.d.ts

@@ -1,5 +0,0 @@
-import { behavior } from '@actor-system/core';
-
-declare const stopped: behavior.Control<never>;
-
-export { stopped };

package/dist/stopped.internal.d.ts

@@ -1,5 +0,0 @@
-import { behavior } from '@actor-system/core/internal';
-
-declare const stopped: behavior.Control<never>;
-
-export { stopped };

package/dist/stopped.js

@@ -1,10 +0,0 @@
-import { behavior, $type } from '@actor-system/core';
-
-const stopped = {
-    [$type]: undefined,
-    _tag: behavior.$control,
-    _operation: "stop",
-    _name: "stop",
-};
-
-export { stopped };

package/dist/supervise.d.ts

@@ -1,14 +0,0 @@
-import { behavior, ActorContext } from '@actor-system/core';
-
-/**
- * Supervision Decision Types
- */
-type SupervisionDecision = "restart" | "resume" | "stop" | "escalate";
-type SupervisionStrategy<T> = (error: unknown, ctx: ActorContext<T>) => SupervisionDecision;
-declare function supervise<T>(inner: behavior.Control<T>, strategy: SupervisionStrategy<T> | SupervisionDecision): behavior.Control<T>;
-declare function supervise<T>(inner: behavior.Receive<T>, strategy: SupervisionStrategy<T> | SupervisionDecision): behavior.Receive<T>;
-declare function supervise<T>(inner: behavior.Folded<T>, strategy: SupervisionStrategy<T> | SupervisionDecision): behavior.Folded<T>;
-declare function supervise<T>(inner: behavior.Behavior<T>, strategy: SupervisionStrategy<T> | SupervisionDecision): behavior.Behavior<T>;
-
-export { supervise };
-export type { SupervisionDecision, SupervisionStrategy };

package/dist/supervise.internal.d.ts

@@ -1,14 +0,0 @@
-import { behavior, ActorContext } from '@actor-system/core/internal';
-
-/**
- * Supervision Decision Types
- */
-type SupervisionDecision = "restart" | "resume" | "stop" | "escalate";
-type SupervisionStrategy<T> = (error: unknown, ctx: ActorContext<T>) => SupervisionDecision;
-declare function supervise<T>(inner: behavior.Control<T>, strategy: SupervisionStrategy<T> | SupervisionDecision): behavior.Control<T>;
-declare function supervise<T>(inner: behavior.Receive<T>, strategy: SupervisionStrategy<T> | SupervisionDecision): behavior.Receive<T>;
-declare function supervise<T>(inner: behavior.Folded<T>, strategy: SupervisionStrategy<T> | SupervisionDecision): behavior.Folded<T>;
-declare function supervise<T>(inner: behavior.Behavior<T>, strategy: SupervisionStrategy<T> | SupervisionDecision): behavior.Behavior<T>;
-
-export { supervise };
-export type { SupervisionDecision, SupervisionStrategy };

package/dist/supervise.js

@@ -1,36 +0,0 @@
-import { behavior } from '@actor-system/core';
-import { restart } from './restart.js';
-import { stopped } from './stopped.js';
-
-function supervise(inner, strategy) {
-    if (behavior.isControl(inner)) {
-        return inner;
-    }
-    if (behavior.isFolded(inner)) {
-        return behavior.folded((context) => supervise(behavior.unfold(inner, context), strategy));
-    }
-    if (behavior.isReceive(inner)) {
-        return behavior.receive((message, context) => {
-            try {
-                const nextBehavior = inner._receive(message, context);
-                return supervise(nextBehavior, strategy);
-            }
-            catch (error) {
-                const decision = typeof strategy === "string" ? strategy : strategy(error, context);
-                switch (decision) {
-                    case "restart":
-                        return restart(supervise(inner, strategy));
-                    case "resume":
-                        return supervise(inner, strategy);
-                    case "stop":
-                        return stopped;
-                    case "escalate":
-                        throw error;
-                }
-            }
-        });
-    }
-    throw new Error(`Unknown behavior type: ${inner}`);
-}
-
-export { supervise };

package/dist/unhandled.d.ts

@@ -1,5 +0,0 @@
-import { behavior } from '@actor-system/core';
-
-declare const unhandled: behavior.Control<never>;
-
-export { unhandled };

package/dist/unhandled.internal.d.ts

@@ -1,5 +0,0 @@
-import { behavior } from '@actor-system/core/internal';
-
-declare const unhandled: behavior.Control<never>;
-
-export { unhandled };

package/dist/unhandled.js

@@ -1,5 +0,0 @@
-import { behavior } from '@actor-system/core';
-
-const unhandled = behavior._unhandled;
-
-export { unhandled };