@actor-system/ask 0.0.16 → 0.0.18

package/dist/ask-sync.d.ts

@@ -9,7 +9,12 @@ interface AskSyncOptions<out Req, in Res> {
  * If an actor's mailbox uses a synchronous processing strategy,
  * this function can be used to perform an ask operation synchronously.
  *
- * This method will throw an error if the actor does not respond synchronously.
+ * This method will throw an error if:
+ * - The target actor is not a local actor reference.
+ * - The target actor's mailbox does not support synchronous processing.
+ * - The actor is currently busy processing another message (reentrancy).
+ * - The actor is dead/stopped (and no tombstone response is available).
+ * - The ask operation does not receive a response immediately.
  */
 declare const askSync: <const Req, Res>(options: AskSyncOptions<Req, Res>) => Res;
 

package/dist/ask-sync.internal.d.ts

@@ -9,7 +9,12 @@ interface AskSyncOptions<out Req, in Res> {
  * If an actor's mailbox uses a synchronous processing strategy,
  * this function can be used to perform an ask operation synchronously.
  *
- * This method will throw an error if the actor does not respond synchronously.
+ * This method will throw an error if:
+ * - The target actor is not a local actor reference.
+ * - The target actor's mailbox does not support synchronous processing.
+ * - The actor is currently busy processing another message (reentrancy).
+ * - The actor is dead/stopped (and no tombstone response is available).
+ * - The ask operation does not receive a response immediately.
  */
 declare const askSync: <const Req, Res>(options: AskSyncOptions<Req, Res>) => Res;
 

package/dist/ask-sync.js

@@ -1,15 +1,21 @@
-import { PriorityScheduler } from '@actor-system/core';
+import { PriorityScheduler, LocalActorRef, SchedulerType } from '@actor-system/core';
 import { _askWithCallback } from './ask-with-callback.js';
-import { AskTimeoutError } from './timeout.js';
+import { UnsupportedSyncOperationError, ReentryError, DisconnectedError, NoSynchronousResponseError, AskTimeoutError } from './errors.js';
 
 /**
  * If an actor's mailbox uses a synchronous processing strategy,
  * this function can be used to perform an ask operation synchronously.
  *
- * This method will throw an error if the actor does not respond synchronously.
+ * This method will throw an error if:
+ * - The target actor is not a local actor reference.
+ * - The target actor's mailbox does not support synchronous processing.
+ * - The actor is currently busy processing another message (reentrancy).
+ * - The actor is dead/stopped (and no tombstone response is available).
+ * - The ask operation does not receive a response immediately.
  */
 const askSync = (options) => {
-    const { to } = options;
+    assertsActorSupportsSync(options.to);
+    assertsActorIsIdle(options.to);
     let msgRef = null;
     let error;
     _askWithCallback({
@@ -29,13 +35,31 @@ const askSync = (options) => {
             },
         },
     });
-    if (error) {
+    if (error)
         throw error;
+    assertsSynchronousResponse(options.to, msgRef);
+    return msgRef.msg;
+};
+const assertsSynchronousResponse = (to, response) => {
+    if (response === null) {
+        throw new NoSynchronousResponseError(`Synchronous ask received no response.`, to);
     }
-    if (!msgRef) {
-        throw new AskTimeoutError(`Ask to '${to.path}' did not respond synchronously. Ensure the actor's mailbox is set to synchronous processing.`, to, NaN, undefined);
+};
+const assertsActorSupportsSync = (to) => {
+    if (!(to instanceof LocalActorRef)) {
+        throw new UnsupportedSyncOperationError(`Synchronous ask operations are only supported for local actors. Actor '${to.path}' is not a local actor reference.`, to);
+    }
+    if (to._mailbox.schedulerType !== SchedulerType.Sync) {
+        throw new UnsupportedSyncOperationError(`Actor '${to.path}' does not support synchronous processing. Ensure the actor's mailbox is configured with a synchronous scheduler.`, to);
+    }
+};
+const assertsActorIsIdle = (to) => {
+    if (to._mailbox.ongoingProcess !== undefined) {
+        throw new ReentryError(`Synchronous ask cannot be performed because actor '${to.path}' is currently processing another message (reentrancy).`, to);
+    }
+    if (to._mailbox.state !== "connected") {
+        throw new DisconnectedError(`Synchronous ask cannot be performed because actor '${to.path}' is not in a connected state.`, to);
     }
-    return msgRef.msg;
 };
 
 export { askSync };

package/dist/ask-with-callback.d.ts

@@ -1,5 +1,5 @@
 import { ActorRef } from '@actor-system/core';
-import { AskTimeoutError } from './timeout.js';
+import { AskTimeoutError } from './errors.js';
 
 type CreateRequest<out Req, in Res> = (replyTo: ActorRef<Res | AskTimeoutError>) => Req;
 

package/dist/ask-with-callback.internal.d.ts

@@ -1,5 +1,5 @@
 import { ActorRef } from '@actor-system/core/internal';
-import { AskTimeoutError } from './timeout.internal.js';
+import { AskTimeoutError } from './errors.internal.js';
 
 type CreateRequest<out Req, in Res> = (replyTo: ActorRef<Res | AskTimeoutError>) => Req;
 

package/dist/ask-with-callback.js

@@ -1,7 +1,7 @@
 import { receiveMessage, stopped } from '@actor-system/behaviors';
 import { $system, signal } from '@actor-system/core';
 import { generateMonotonicULID } from './__bundle__/shared/dist/monotonicULID.js';
-import { AskTimeoutError } from './timeout.js';
+import { AskTimeoutError } from './errors.js';
 
 /**
  * @internal
@@ -19,7 +19,7 @@ const _askWithCallback = (options) => {
             if (done)
                 return; // If already done, do not proceed
             replyTo.tell(new AskTimeoutError(`Ask to '${to.path}' timed out after ${timeout}ms`, to, timeout));
-        }, timeout);
+        }, Math.max(0, timeout));
     }
     const replyTo = to[$system].systemActorOf(receiveMessage((msg) => {
         if (!(msg instanceof AskTimeoutError) && !done) {

package/dist/ask.js

@@ -1,5 +1,5 @@
 import { _askWithCallback } from './ask-with-callback.js';
-import { AskTimeoutError } from './timeout.js';
+import { AskTimeoutError } from './errors.js';
 
 const ask = (options) => new Promise((resolve, reject) => _askWithCallback({
     timeout: 1000,

package/dist/errors.d.ts

@@ -0,0 +1,51 @@
+import { ActorRef } from '@actor-system/core';
+import { Letter } from '@actor-system/mail';
+
+declare const $timeoutError = "@@ask.timeout-error";
+declare const $unsupportedSyncOperationError = "@@ask.unsupported-sync-operation-error";
+declare const $noSynchronousResponseError = "@@ask.no-synchronous-response-error";
+declare const $reentryError = "@@ask.reentry-error";
+declare const $disconnectedError = "@@ask.disconnected-error";
+declare class AskTimeoutError extends Error implements Letter<typeof $timeoutError> {
+    readonly label: typeof $timeoutError;
+    readonly from?: ActorRef;
+    readonly to: ActorRef;
+    readonly timeout: number;
+    constructor(message: string, to: ActorRef, timeout: number, from?: ActorRef);
+}
+/**
+ * Error thrown when attempting a synchronous ask operation on an actor
+ * that does not support synchronous processing (e.g., actor with async-only mailbox).
+ */
+declare class UnsupportedSyncOperationError extends Error implements Letter<typeof $unsupportedSyncOperationError> {
+    readonly label: typeof $unsupportedSyncOperationError;
+    readonly from?: ActorRef;
+    readonly to: ActorRef;
+    constructor(message: string, to: ActorRef, from?: ActorRef);
+}
+/**
+ * Thrown when a synchronous ask operation receives no response. This can occur
+ * in several scenarios: the actor is busy processing another message (reentrancy),
+ * the actor is dead/stopped, or the actor has some other condition preventing
+ * immediate synchronous response.
+ */
+declare class NoSynchronousResponseError extends Error implements Letter<typeof $noSynchronousResponseError> {
+    readonly label: typeof $noSynchronousResponseError;
+    readonly from?: ActorRef;
+    readonly to: ActorRef;
+    constructor(message: string, to: ActorRef, from?: ActorRef);
+}
+declare class ReentryError extends Error implements Letter<typeof $reentryError> {
+    readonly label: typeof $reentryError;
+    readonly from?: ActorRef;
+    readonly to: ActorRef;
+    constructor(message: string, to: ActorRef, from?: ActorRef);
+}
+declare class DisconnectedError extends Error implements Letter<typeof $disconnectedError> {
+    readonly label: typeof $disconnectedError;
+    readonly from?: ActorRef;
+    readonly to: ActorRef;
+    constructor(message: string, to: ActorRef, from?: ActorRef);
+}
+
+export { $disconnectedError, $noSynchronousResponseError, $reentryError, $timeoutError, $unsupportedSyncOperationError, AskTimeoutError, DisconnectedError, NoSynchronousResponseError, ReentryError, UnsupportedSyncOperationError };

package/dist/errors.internal.d.ts

@@ -0,0 +1,51 @@
+import { ActorRef } from '@actor-system/core/internal';
+import { Letter } from '@actor-system/mail/internal';
+
+declare const $timeoutError = "@@ask.timeout-error";
+declare const $unsupportedSyncOperationError = "@@ask.unsupported-sync-operation-error";
+declare const $noSynchronousResponseError = "@@ask.no-synchronous-response-error";
+declare const $reentryError = "@@ask.reentry-error";
+declare const $disconnectedError = "@@ask.disconnected-error";
+declare class AskTimeoutError extends Error implements Letter<typeof $timeoutError> {
+    readonly label: typeof $timeoutError;
+    readonly from?: ActorRef;
+    readonly to: ActorRef;
+    readonly timeout: number;
+    constructor(message: string, to: ActorRef, timeout: number, from?: ActorRef);
+}
+/**
+ * Error thrown when attempting a synchronous ask operation on an actor
+ * that does not support synchronous processing (e.g., actor with async-only mailbox).
+ */
+declare class UnsupportedSyncOperationError extends Error implements Letter<typeof $unsupportedSyncOperationError> {
+    readonly label: typeof $unsupportedSyncOperationError;
+    readonly from?: ActorRef;
+    readonly to: ActorRef;
+    constructor(message: string, to: ActorRef, from?: ActorRef);
+}
+/**
+ * Thrown when a synchronous ask operation receives no response. This can occur
+ * in several scenarios: the actor is busy processing another message (reentrancy),
+ * the actor is dead/stopped, or the actor has some other condition preventing
+ * immediate synchronous response.
+ */
+declare class NoSynchronousResponseError extends Error implements Letter<typeof $noSynchronousResponseError> {
+    readonly label: typeof $noSynchronousResponseError;
+    readonly from?: ActorRef;
+    readonly to: ActorRef;
+    constructor(message: string, to: ActorRef, from?: ActorRef);
+}
+declare class ReentryError extends Error implements Letter<typeof $reentryError> {
+    readonly label: typeof $reentryError;
+    readonly from?: ActorRef;
+    readonly to: ActorRef;
+    constructor(message: string, to: ActorRef, from?: ActorRef);
+}
+declare class DisconnectedError extends Error implements Letter<typeof $disconnectedError> {
+    readonly label: typeof $disconnectedError;
+    readonly from?: ActorRef;
+    readonly to: ActorRef;
+    constructor(message: string, to: ActorRef, from?: ActorRef);
+}
+
+export { $disconnectedError, $noSynchronousResponseError, $reentryError, $timeoutError, $unsupportedSyncOperationError, AskTimeoutError, DisconnectedError, NoSynchronousResponseError, ReentryError, UnsupportedSyncOperationError };

package/dist/errors.js

@@ -0,0 +1,74 @@
+const $timeoutError = "@@ask.timeout-error";
+const $unsupportedSyncOperationError = "@@ask.unsupported-sync-operation-error";
+const $noSynchronousResponseError = "@@ask.no-synchronous-response-error";
+const $reentryError = "@@ask.reentry-error";
+const $disconnectedError = "@@ask.disconnected-error";
+class AskTimeoutError extends Error {
+    label = $timeoutError;
+    from;
+    to;
+    timeout;
+    constructor(message, to, timeout, from) {
+        super(message);
+        this.name = "AskTimeoutError";
+        this.from = from;
+        this.to = to;
+        this.timeout = timeout;
+    }
+}
+/**
+ * Error thrown when attempting a synchronous ask operation on an actor
+ * that does not support synchronous processing (e.g., actor with async-only mailbox).
+ */
+class UnsupportedSyncOperationError extends Error {
+    label = $unsupportedSyncOperationError;
+    from;
+    to;
+    constructor(message, to, from) {
+        super(message);
+        this.name = "UnsupportedSyncOperationError";
+        this.from = from;
+        this.to = to;
+    }
+}
+/**
+ * Thrown when a synchronous ask operation receives no response. This can occur
+ * in several scenarios: the actor is busy processing another message (reentrancy),
+ * the actor is dead/stopped, or the actor has some other condition preventing
+ * immediate synchronous response.
+ */
+class NoSynchronousResponseError extends Error {
+    label = $noSynchronousResponseError;
+    from;
+    to;
+    constructor(message, to, from) {
+        super(message);
+        this.name = "NoSynchronousResponseError";
+        this.from = from;
+        this.to = to;
+    }
+}
+class ReentryError extends Error {
+    label = $reentryError;
+    from;
+    to;
+    constructor(message, to, from) {
+        super(message);
+        this.name = "ReentryError";
+        this.from = from;
+        this.to = to;
+    }
+}
+class DisconnectedError extends Error {
+    label = $disconnectedError;
+    from;
+    to;
+    constructor(message, to, from) {
+        super(message);
+        this.name = "DisconnectedError";
+        this.from = from;
+        this.to = to;
+    }
+}
+
+export { $disconnectedError, $noSynchronousResponseError, $reentryError, $timeoutError, $unsupportedSyncOperationError, AskTimeoutError, DisconnectedError, NoSynchronousResponseError, ReentryError, UnsupportedSyncOperationError };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
 export { AskSyncOptions, askSync } from './ask-sync.js';
 export { AskOptions, ask } from './ask.js';
-export { $timeoutError, AskTimeoutError } from './timeout.js';
+export { $disconnectedError, $noSynchronousResponseError, $reentryError, $timeoutError, $unsupportedSyncOperationError, AskTimeoutError, DisconnectedError, NoSynchronousResponseError, ReentryError, UnsupportedSyncOperationError } from './errors.js';
 export { Ask, MapResponse, WithAskOptions, withAsk } from './use-ask.js';

package/dist/index.internal.d.ts

@@ -1,4 +1,4 @@
 export { AskSyncOptions, askSync } from './ask-sync.internal.js';
 export { AskOptions, ask } from './ask.internal.js';
-export { $timeoutError, AskTimeoutError } from './timeout.internal.js';
+export { $disconnectedError, $noSynchronousResponseError, $reentryError, $timeoutError, $unsupportedSyncOperationError, AskTimeoutError, DisconnectedError, NoSynchronousResponseError, ReentryError, UnsupportedSyncOperationError } from './errors.internal.js';
 export { Ask, MapResponse, WithAskOptions, withAsk } from './use-ask.internal.js';

package/dist/index.js

@@ -1,4 +1,4 @@
 export { askSync } from './ask-sync.js';
 export { ask } from './ask.js';
-export { $timeoutError, AskTimeoutError } from './timeout.js';
+export { $disconnectedError, $noSynchronousResponseError, $reentryError, $timeoutError, $unsupportedSyncOperationError, AskTimeoutError, DisconnectedError, NoSynchronousResponseError, ReentryError, UnsupportedSyncOperationError } from './errors.js';
 export { withAsk } from './use-ask.js';

package/dist/use-ask.d.ts

@@ -1,5 +1,5 @@
 import { ActorRef, ActorContext, behavior } from '@actor-system/core';
-import { AskTimeoutError } from './timeout.js';
+import { AskTimeoutError } from './errors.js';
 import { CreateRequest } from './ask-with-callback.js';
 
 type MapResponse<in Res, out T> = (response: Res | AskTimeoutError) => T;

package/dist/use-ask.internal.d.ts

@@ -1,5 +1,5 @@
 import { ActorRef, ActorContext, behavior } from '@actor-system/core/internal';
-import { AskTimeoutError } from './timeout.internal.js';
+import { AskTimeoutError } from './errors.internal.js';
 import { CreateRequest } from './ask-with-callback.internal.js';
 
 type MapResponse<in Res, out T> = (response: Res | AskTimeoutError) => T;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@actor-system/ask",
-  "version": "0.0.16",
+  "version": "0.0.18",
   "type": "module",
   "scripts": {
     "type-check": "tsc -b src",
@@ -9,7 +9,13 @@
     "publint": "publint",
     "build:tsc:internal": "tsc -b src/tsconfig.lib.json",
     "build:tsc:trimmed": "tsc -b src/tsconfig.lib.trimmed.json",
-    "build:rollup": "rollup -c node:config/rollup-config"
+    "build:rollup": "rollup -c node:config/rollup-config",
+    "test": "NODE_OPTIONS=\"--expose-gc\" vitest run",
+    "test:browser": "vitest run --browser.enabled",
+    "test:browser:watch": "vitest --browser.enabled",
+    "test:browser:coverage": "vitest run --coverage --browser.enabled",
+    "test:extensive": "npm run test && npm run test -- --mode sync && npm run test:browser && npm run test:browser -- --mode sync",
+    "test:coverage": "vitest run --coverage"
   },
   "module": "./dist/index.js",
   "main": "./dist/index.js",
@@ -28,13 +34,13 @@
     "@actor-system/shared"
   ],
   "dependencies": {
-    "@actor-system/behaviors": "0.0.16",
-    "@actor-system/core": "0.1.0",
-    "@actor-system/mail": "0.0.2"
+    "@actor-system/behaviors": "0.0.18",
+    "@actor-system/core": "0.1.2",
+    "@actor-system/mail": "0.0.3"
   },
   "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/timeout.d.ts

@@ -1,13 +0,0 @@
-import { ActorRef } from '@actor-system/core';
-import { Letter } from '@actor-system/mail';
-
-declare const $timeoutError = "@@ask.timeout-error";
-declare class AskTimeoutError extends Error implements Letter<typeof $timeoutError> {
-    readonly label: typeof $timeoutError;
-    readonly from?: ActorRef;
-    readonly to: ActorRef;
-    readonly timeout: number;
-    constructor(message: string, to: ActorRef, timeout: number, from?: ActorRef);
-}
-
-export { $timeoutError, AskTimeoutError };

package/dist/timeout.internal.d.ts

@@ -1,13 +0,0 @@
-import { ActorRef } from '@actor-system/core/internal';
-import { Letter } from '@actor-system/mail/internal';
-
-declare const $timeoutError = "@@ask.timeout-error";
-declare class AskTimeoutError extends Error implements Letter<typeof $timeoutError> {
-    readonly label: typeof $timeoutError;
-    readonly from?: ActorRef;
-    readonly to: ActorRef;
-    readonly timeout: number;
-    constructor(message: string, to: ActorRef, timeout: number, from?: ActorRef);
-}
-
-export { $timeoutError, AskTimeoutError };

package/dist/timeout.js

@@ -1,16 +0,0 @@
-const $timeoutError = "@@ask.timeout-error";
-class AskTimeoutError extends Error {
-    label = $timeoutError;
-    from;
-    to;
-    timeout;
-    constructor(message, to, timeout, from) {
-        super(message);
-        this.name = "AskTimeoutError";
-        this.from = from;
-        this.to = to;
-        this.timeout = timeout;
-    }
-}
-
-export { $timeoutError, AskTimeoutError };