@actor-system/ask 0.0.1

package/dist/__bundle__/shared/dist/monotonicULID.js

@@ -0,0 +1,56 @@
+const ENCODING = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+const TIME_LEN = 10; // 48 bits encoded in 10 Base32 chars
+const RAND_LEN = 16; // 80 bits encoded in 16 Base32 chars
+const ENCODING_LEN = ENCODING.length;
+let lastTime = -1;
+let lastRand = [];
+function encodeTime(num, len) {
+    let str = "";
+    for (let i = len - 1; i >= 0; i--) {
+        const mod = num % ENCODING_LEN;
+        str = ENCODING[mod] + str;
+        num = Math.floor(num / ENCODING_LEN);
+    }
+    return str;
+}
+function getRandomBytes(size) {
+    if (typeof crypto !== "undefined" &&
+        typeof crypto.getRandomValues === "function") {
+        const buf = new Uint8Array(size);
+        crypto.getRandomValues(buf);
+        return buf;
+    }
+    throw new Error("crypto.getRandomValues is not available in this environment.");
+}
+function incrementRandom(rand) {
+    for (let i = rand.length - 1; i >= 0; i--) {
+        rand[i]++;
+        if (rand[i] < ENCODING_LEN) {
+            break;
+        }
+        rand[i] = 0;
+    }
+    return rand;
+}
+const generateMonotonicULID = () => {
+    const now = Date.now();
+    const timePart = encodeTime(now, TIME_LEN);
+    let randBytes;
+    if (now === lastTime) {
+        lastRand = incrementRandom(lastRand);
+        randBytes = lastRand;
+    }
+    else {
+        const bytes = getRandomBytes(RAND_LEN);
+        randBytes = Array.from(bytes).map((b) => b % ENCODING_LEN);
+        lastRand = randBytes.slice();
+        lastTime = now;
+    }
+    let randPart = "";
+    for (let i = 0; i < RAND_LEN; i++) {
+        randPart += ENCODING[randBytes[i]];
+    }
+    return timePart + randPart;
+};
+
+export { generateMonotonicULID };

package/dist/ask-sync.d.ts

@@ -0,0 +1,17 @@
+import { ActorRef } from '@actor-system/core';
+import { CreateRequest } from './ask-with-callback.js';
+
+interface AskSyncOptions<out Req, in Res> {
+    to: ActorRef<Req>;
+    request: CreateRequest<Req, 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.
+ */
+declare const askSync: <const Req, Res>(options: AskSyncOptions<Req, Res>) => Res;
+
+export { askSync };
+export type { AskSyncOptions };

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

@@ -0,0 +1,17 @@
+import { ActorRef } from '@actor-system/core/internal';
+import { CreateRequest } from './ask-with-callback.internal.js';
+
+interface AskSyncOptions<out Req, in Res> {
+    to: ActorRef<Req>;
+    request: CreateRequest<Req, 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.
+ */
+declare const askSync: <const Req, Res>(options: AskSyncOptions<Req, Res>) => Res;
+
+export { askSync };
+export type { AskSyncOptions };

package/dist/ask-sync.js

@@ -0,0 +1,41 @@
+import { PriorityScheduler } from '@actor-system/core';
+import { _askWithCallback } from './ask-with-callback.js';
+import { AskTimeoutError } from './timeout.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.
+ */
+const askSync = (options) => {
+    const { to } = options;
+    let msgRef = null;
+    let error;
+    _askWithCallback({
+        ...options,
+        timeout: undefined,
+        callback: (response) => {
+            if (response instanceof AskTimeoutError) {
+                error = response;
+            }
+            else {
+                msgRef = { msg: response };
+            }
+        },
+        props: {
+            mailboxConfig: {
+                scheduler: PriorityScheduler.create("sync"),
+            },
+        },
+    });
+    if (error) {
+        throw error;
+    }
+    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);
+    }
+    return msgRef.msg;
+};
+
+export { askSync };

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

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

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

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

package/dist/ask-with-callback.js

@@ -0,0 +1,41 @@
+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';
+
+/**
+ * @internal
+ *
+ * Internal function to perform an ask operation with a callback.
+ * This function creates a temporary actor to handle the response and
+ * invokes the provided callback with the response or an AskTimeoutError.
+ */
+const _askWithCallback = (options) => {
+    const { to, callback, request: createRequest, timeout, props } = options;
+    let done = false;
+    let timer;
+    if (timeout !== undefined) {
+        timer = setTimeout(() => {
+            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);
+    }
+    const replyTo = to[$system].systemActorOf(receiveMessage((msg) => {
+        if (!(msg instanceof AskTimeoutError) && !done) {
+            clearTimeout(timer);
+            callback(msg);
+            done = true; // Mark as done to prevent further processing
+        }
+        return stopped;
+    }).receiveSignal((post) => {
+        if (signal.isPostStop(post) && !done) {
+            clearTimeout(timer);
+            callback(new AskTimeoutError(`Ask to '${to.path}' timed out after ${timeout ?? Number.POSITIVE_INFINITY}ms`, to, timeout ?? Number.POSITIVE_INFINITY));
+            done = true; // Mark as done to prevent further processing
+        }
+    }), `ask-temp-${generateMonotonicULID()}`, props);
+    to.tell(createRequest(replyTo));
+};
+
+export { _askWithCallback };

package/dist/ask.d.ts

@@ -0,0 +1,12 @@
+import { ActorRef } from '@actor-system/core';
+import { CreateRequest } from './ask-with-callback.js';
+
+interface AskOptions<Req, Res> {
+    timeout?: number;
+    to: ActorRef<Req>;
+    request: CreateRequest<Req, Res>;
+}
+declare const ask: <const Req, Res>(options: AskOptions<Req, Res>) => Promise<Res>;
+
+export { ask };
+export type { AskOptions };

package/dist/ask.internal.d.ts

@@ -0,0 +1,12 @@
+import { ActorRef } from '@actor-system/core/internal';
+import { CreateRequest } from './ask-with-callback.internal.js';
+
+interface AskOptions<Req, Res> {
+    timeout?: number;
+    to: ActorRef<Req>;
+    request: CreateRequest<Req, Res>;
+}
+declare const ask: <const Req, Res>(options: AskOptions<Req, Res>) => Promise<Res>;
+
+export { ask };
+export type { AskOptions };

package/dist/ask.js

@@ -0,0 +1,17 @@
+import { _askWithCallback } from './ask-with-callback.js';
+import { AskTimeoutError } from './timeout.js';
+
+const ask = (options) => new Promise((resolve, reject) => _askWithCallback({
+    timeout: 1000,
+    ...options,
+    callback: (response) => {
+        if (response instanceof AskTimeoutError) {
+            reject(response);
+        }
+        else {
+            resolve(response);
+        }
+    },
+}));
+
+export { ask };

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { AskSyncOptions, askSync } from './ask-sync.js';
+export { AskOptions, ask } from './ask.js';
+export { $timeoutError, AskTimeoutError } from './timeout.js';
+export { Ask, MapResponse, WithAskOptions, withAsk } from './use-ask.js';

package/dist/index.internal.d.ts

@@ -0,0 +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 { Ask, MapResponse, WithAskOptions, withAsk } from './use-ask.internal.js';

package/dist/index.js

@@ -0,0 +1,4 @@
+export { askSync } from './ask-sync.js';
+export { ask } from './ask.js';
+export { $timeoutError, AskTimeoutError } from './timeout.js';
+export { withAsk } from './use-ask.js';

package/dist/timeout.d.ts

@@ -0,0 +1,13 @@
+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

@@ -0,0 +1,13 @@
+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

@@ -0,0 +1,16 @@
+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 };

package/dist/use-ask.d.ts

@@ -0,0 +1,25 @@
+import { ActorRef, ActorContext, behavior } from '@actor-system/core';
+import { AskTimeoutError } from './timeout.js';
+import { CreateRequest } from './ask-with-callback.js';
+
+type MapResponse<in Res, out T> = (response: Res | AskTimeoutError) => T;
+type WithAskOptions<T, Req, Res> = T extends AskTimeoutError ? WithAskOptions.WithPartialMapResponse<T, Req, Res> : WithAskOptions.WithMapResponse<T, Req, Res>;
+declare namespace WithAskOptions {
+    interface WithMapResponse<T, Req, Res> {
+        to: ActorRef<Req>;
+        request: CreateRequest<Req, Res>;
+        timeout?: number;
+        mapResponse: MapResponse<Res, T>;
+    }
+    interface WithPartialMapResponse<T, Req, Res> {
+        to: ActorRef<Req>;
+        request: CreateRequest<Req, Res>;
+        timeout?: number;
+        mapResponse?: MapResponse<Res, T>;
+    }
+}
+type Ask<T> = <const Req, Res>(options: WithAskOptions<T, Req, Res>) => void;
+declare const withAsk: <T>(factory: (ask: Ask<T>, context: ActorContext<T>) => behavior.Behavior<T>) => behavior.Behavior<T>;
+
+export { WithAskOptions, withAsk };
+export type { Ask, MapResponse };

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

@@ -0,0 +1,25 @@
+import { ActorRef, ActorContext, behavior } from '@actor-system/core/internal';
+import { AskTimeoutError } from './timeout.internal.js';
+import { CreateRequest } from './ask-with-callback.internal.js';
+
+type MapResponse<in Res, out T> = (response: Res | AskTimeoutError) => T;
+type WithAskOptions<T, Req, Res> = T extends AskTimeoutError ? WithAskOptions.WithPartialMapResponse<T, Req, Res> : WithAskOptions.WithMapResponse<T, Req, Res>;
+declare namespace WithAskOptions {
+    interface WithMapResponse<T, Req, Res> {
+        to: ActorRef<Req>;
+        request: CreateRequest<Req, Res>;
+        timeout?: number;
+        mapResponse: MapResponse<Res, T>;
+    }
+    interface WithPartialMapResponse<T, Req, Res> {
+        to: ActorRef<Req>;
+        request: CreateRequest<Req, Res>;
+        timeout?: number;
+        mapResponse?: MapResponse<Res, T>;
+    }
+}
+type Ask<T> = <const Req, Res>(options: WithAskOptions<T, Req, Res>) => void;
+declare const withAsk: <T>(factory: (ask: Ask<T>, context: ActorContext<T>) => behavior.Behavior<T>) => behavior.Behavior<T>;
+
+export { WithAskOptions, withAsk };
+export type { Ask, MapResponse };

package/dist/use-ask.js

@@ -0,0 +1,23 @@
+import { _askWithCallback } from './ask-with-callback.js';
+import * as behaviors from '@actor-system/behaviors';
+
+const $ask = Symbol("ask");
+const withAsk = (factory) => behaviors.setup((context) => factory(useAsk(context), context));
+const useAsk = (context) => {
+    if (context[$ask])
+        return context[$ask];
+    const ask = (options) => {
+        const mapResponse = ("mapResponse" in options ? options.mapResponse : undefined) ??
+            ((response) => response);
+        _askWithCallback({
+            timeout: 1000,
+            ...options,
+            callback: (response) => {
+                context.self.tell(mapResponse(response));
+            },
+        });
+    };
+    return (context[$ask] = ask);
+};
+
+export { withAsk };

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@actor-system/ask",
+  "version": "0.0.1",
+  "type": "module",
+  "scripts": {
+    "type-check": "tsc -b src",
+    "lint": "eslint src",
+    "lint:fix": "eslint src --fix",
+    "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"
+  },
+  "module": "./dist/index.js",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "bundleDependencies": [
+    "@actor-system/shared"
+  ],
+  "dependencies": {
+    "@actor-system/behaviors": "0.0.1",
+    "@actor-system/core": "0.0.1",
+    "@actor-system/mail": "0.0.1"
+  },
+  "devDependencies": {
+    "@actor-system/testing": "0.0.1",
+    "@actor-system/shared": "0.0.1",
+    "config": "^1.0.0"
+  }
+}