@quenk/potoo 3.1.7-0 → 4.0.3

package/README.md

@@ -1,34 +1,36 @@
 Potoo
 =====
 
-In application message passing system inspired by the actor model.
-
-[!Diagram of Potoo internals](v3.png)
+In app message passing framework inspired the actor model.
 
 # Introduction
 
-Potoo provides a framework for constructing an actor system within frontend or
-backend applications.
+Potoo provides a framework for creating a network of actors within your 
+applications for easy message passing.
+
+## Why?
+
+Message passing allows us to de-couple our applications and thus scale more
+effectively. This is true for traditional networks and distributed computing
+but it can also be applied to the UI components of an ordinary web app.
 
-It is implemented as a virtual machine (PVM) that is usually embeded into the 
-main class of an application. PVM is used to spawn child "actors" that each 
-execute some unit of work on behalf of the application. Actors are able to 
-communicate with each other via message passing.
+## How?
 
-Actors can either be "resident" or "remote". Resident actors share the JS event
-loop with the VM and use its API to execute message passing instructions. Remote
-actors that do not share the event loop and can be in another process or even
-another machine.
+This framework allows you to create 1 or more actors that together form a system.
+Behind the scenes, the framework provides machinery to deliver messages to and
+from actors given the respective address.
 
-The [API](src/resident/index.ts) interface describes the methods available to
-resident actors. Extend the `Immutable` or `Mutable` classes to create an 
-implementation or `AbstractResident` if you need more customisation.
+Think of an actor as a unit of computation or the refinement of a feature within
+your application. Each actor has its own state that it does not share with other
+actors, instead they communicate via messages.
 
-Currently the only remote actors supported are [Process](src/actor/process/index.ts)
-which uses the Node.js child_process API to run a separate `PVM` instance.
+When an actor receives a message, it can typically:
+1. Spawn a new actor to handle the message.
+2. Change it's internally behaviour based on the contents of the message.
+3. Send a message to another actor.
 
-There are plans however to support web sockets, web workers and possibly green
-thread actors.
+By honoring these 3 points we are able to distribute the work of our applications
+in a scalable way, without the complexity.
 
 # Installation
 
@@ -38,8 +40,45 @@ npm install --save @quenk/potoo
 
 # Usage
 
-Consult the tests folder for now.
+```js
+import { PVM } from '@quenk/potoo';
+
+// This is your system and serves as the root actor.
+let vm = PVM.create();
+
+vm.spawn({
+
+    id: 'a', 
+
+    run: async actor => {
+
+        await actor.tell('b', 'ready');
+
+        while(actor.isValid()) {
+            let msg = await actor.receive();
+            if(msg === 'done') {
+              await actor.exit();
+            }
+        }
+    }
+})
+
+vm.spawn({
+    id: 'b',
+
+    run: async actor => {
+
+        setTimeout(()=> { actor.tell('a', 'done'); }, 5000);
+
+    }
+})
+
+
+```
+
+More examples in the test folder.
+
 
 # License
 
-Apache-2.0 (C) 2022 Quenk Technologies Limited
+Apache-2.0 (C) 2024 Quenk Technologies Limited

package/lib/actor/address.d.ts

@@ -9,7 +9,7 @@ export declare const ADDRESS_RESTRICTED: string[];
  * Addresses are used to properly route messages between actors in the system
  * and conform to the path part of a URL.
  */
-export declare type Address = string;
+export type Address = string;
 /**
  * AddressMap
  */

package/lib/actor/address.js

@@ -7,45 +7,41 @@ exports.SEPERATOR = '/';
 exports.ADDRESS_DISCARD = '?';
 exports.ADDRESS_SYSTEM = '$';
 exports.ADDRESS_EMPTY = '';
-exports.ADDRESS_RESTRICTED = [
-    exports.ADDRESS_DISCARD,
-    exports.ADDRESS_SYSTEM,
-    exports.SEPERATOR
-];
+exports.ADDRESS_RESTRICTED = [exports.ADDRESS_DISCARD, exports.ADDRESS_SYSTEM, exports.SEPERATOR];
 /**
  * isRestricted indicates whether an actor id is restricted or not.
  */
-const isRestricted = (id) => ((exports.ADDRESS_RESTRICTED.some(a => id.indexOf(a) > -1)) && (id !== exports.SEPERATOR));
+const isRestricted = (id) => exports.ADDRESS_RESTRICTED.some(a => id.indexOf(a) > -1) && id !== exports.SEPERATOR;
 exports.isRestricted = isRestricted;
 /**
  * make a child address given its id and parent address.
  */
-const make = (parent, id) => ((parent === exports.SEPERATOR) || (parent === exports.ADDRESS_EMPTY)) ?
-    `${parent}${id}` :
-    (parent === exports.ADDRESS_SYSTEM) ?
-        id :
-        `${parent}${exports.SEPERATOR}${id}`;
+const make = (parent, id) => {
+    id = id.trim();
+    return parent === exports.SEPERATOR || parent === exports.ADDRESS_EMPTY
+        ? `${parent}${id}`
+        : parent === exports.ADDRESS_SYSTEM
+            ? id
+            : `${parent}${exports.SEPERATOR}${id}`;
+};
 exports.make = make;
 /**
  * getParent computes the parent of an Address.
  */
 const getParent = (addr) => {
-    if (((addr === exports.ADDRESS_SYSTEM) ||
-        (addr === exports.ADDRESS_EMPTY) ||
-        (addr === exports.ADDRESS_DISCARD) || (addr === exports.SEPERATOR))) {
+    if (addr === exports.ADDRESS_SYSTEM ||
+        addr === exports.ADDRESS_EMPTY ||
+        addr === exports.ADDRESS_DISCARD ||
+        addr === exports.SEPERATOR) {
         return exports.ADDRESS_SYSTEM;
     }
     else {
         let b4 = addr.split(exports.SEPERATOR);
-        if ((b4.length === 2) && (b4[0] === '')) {
+        if (b4.length === 2 && b4[0] === '') {
             return exports.SEPERATOR;
         }
         else {
-            let a = b4
-                .reverse()
-                .slice(1)
-                .reverse()
-                .join(exports.SEPERATOR);
+            let a = b4.reverse().slice(1).reverse().join(exports.SEPERATOR);
             return a === exports.ADDRESS_EMPTY ? exports.ADDRESS_SYSTEM : a;
         }
     }
@@ -54,22 +50,22 @@ exports.getParent = getParent;
 /**
  * getId provides the id part of an actor address.
  */
-const getId = (addr) => ((addr === exports.ADDRESS_SYSTEM) ||
-    (addr === exports.ADDRESS_DISCARD) ||
-    (addr === exports.ADDRESS_EMPTY) ||
-    (addr === exports.SEPERATOR)) ?
-    addr :
-    (0, array_1.tail)(addr.split(exports.SEPERATOR));
+const getId = (addr) => addr === exports.ADDRESS_SYSTEM ||
+    addr === exports.ADDRESS_DISCARD ||
+    addr === exports.ADDRESS_EMPTY ||
+    addr === exports.SEPERATOR
+    ? addr
+    : (0, array_1.tail)(addr.split(exports.SEPERATOR));
 exports.getId = getId;
 /**
  * isChild tests whether an address is a child of the parent address.
  */
-const isChild = (parent, child) => ((parent === exports.ADDRESS_SYSTEM) && (child !== parent)) ||
+const isChild = (parent, child) => (parent === exports.ADDRESS_SYSTEM && child !== parent) ||
     (0, string_1.startsWith)(child, `${parent}${exports.SEPERATOR}`);
 exports.isChild = isChild;
 /**
  * isGroup determines if an address is a group reference.
  */
-const isGroup = (addr) => ((addr[0] === '$') && (addr !== '$'));
+const isGroup = (addr) => addr[0] === '$' && addr !== '$';
 exports.isGroup = isGroup;
 //# sourceMappingURL=address.js.map

package/lib/actor/address.js.map

@@ -1 +1 @@
-{"version":3,"file":"address.js","sourceRoot":"","sources":["address.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"address.js","sourceRoot":"","sources":["address.ts"],"names":[],"mappings":";;;AAAA,sDAAkD;AAClD,wDAAyD;AAE5C,QAAA,SAAS,GAAG,GAAG,CAAC;AAEhB,QAAA,eAAe,GAAG,GAAG,CAAC;AACtB,QAAA,cAAc,GAAG,GAAG,CAAC;AACrB,QAAA,aAAa,GAAG,EAAE,CAAC;AACnB,QAAA,kBAAkB,GAAG,CAAC,uBAAe,EAAE,sBAAc,EAAE,iBAAS,CAAC,CAAC;AAiB/E;;GAEG;AACI,MAAM,YAAY,GAAG,CAAC,EAAU,EAAE,EAAE,CACvC,0BAAkB,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,KAAK,iBAAS,CAAC;AAD5D,QAAA,YAAY,gBACgD;AAEzE;;GAEG;AACI,MAAM,IAAI,GAAG,CAAC,MAAe,EAAE,EAAU,EAAW,EAAE;IACzD,EAAE,GAAG,EAAE,CAAC,IAAI,EAAE,CAAC;IACf,OAAO,MAAM,KAAK,iBAAS,IAAI,MAAM,KAAK,qBAAa;QACnD,CAAC,CAAC,GAAG,MAAM,GAAG,EAAE,EAAE;QAClB,CAAC,CAAC,MAAM,KAAK,sBAAc;YACzB,CAAC,CAAC,EAAE;YACJ,CAAC,CAAC,GAAG,MAAM,GAAG,iBAAS,GAAG,EAAE,EAAE,CAAC;AACzC,CAAC,CAAC;AAPW,QAAA,IAAI,QAOf;AAEF;;GAEG;AACI,MAAM,SAAS,GAAG,CAAC,IAAa,EAAW,EAAE;IAChD,IACI,IAAI,KAAK,sBAAc;QACvB,IAAI,KAAK,qBAAa;QACtB,IAAI,KAAK,uBAAe;QACxB,IAAI,KAAK,iBAAS,EACpB,CAAC;QACC,OAAO,sBAAc,CAAC;IAC1B,CAAC;SAAM,CAAC;QACJ,IAAI,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,iBAAS,CAAC,CAAC;QAE/B,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC;YAClC,OAAO,iBAAS,CAAC;QACrB,CAAC;aAAM,CAAC;YACJ,IAAI,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,IAAI,CAAC,iBAAS,CAAC,CAAC;YAExD,OAAO,CAAC,KAAK,qBAAa,CAAC,CAAC,CAAC,sBAAc,CAAC,CAAC,CAAC,CAAC,CAAC;QACpD,CAAC;IACL,CAAC;AACL,CAAC,CAAC;AAnBW,QAAA,SAAS,aAmBpB;AAEF;;GAEG;AACI,MAAM,KAAK,GAAG,CAAC,IAAa,EAAU,EAAE,CAC3C,IAAI,KAAK,sBAAc;IACvB,IAAI,KAAK,uBAAe;IACxB,IAAI,KAAK,qBAAa;IACtB,IAAI,KAAK,iBAAS;IACd,CAAC,CAAC,IAAI;IACN,CAAC,CAAC,IAAA,YAAI,EAAC,IAAI,CAAC,KAAK,CAAC,iBAAS,CAAC,CAAC,CAAC;AANzB,QAAA,KAAK,SAMoB;AAEtC;;GAEG;AACI,MAAM,OAAO,GAAG,CAAC,MAAe,EAAE,KAAc,EAAW,EAAE,CAChE,CAAC,MAAM,KAAK,sBAAc,IAAI,KAAK,KAAK,MAAM,CAAC;IAC/C,IAAA,mBAAU,EAAC,KAAK,EAAE,GAAG,MAAM,GAAG,iBAAS,EAAE,CAAC,CAAC;AAFlC,QAAA,OAAO,WAE2B;AAE/C;;GAEG;AACI,MAAM,OAAO,GAAG,CAAC,IAAa,EAAW,EAAE,CAC9C,IAAI,CAAC,CAAC,CAAC,KAAK,GAAG,IAAI,IAAI,KAAK,GAAG,CAAC;AADvB,QAAA,OAAO,WACgB"}

package/lib/actor/address.ts

@@ -6,11 +6,7 @@ export const SEPERATOR = '/';
 export const ADDRESS_DISCARD = '?';
 export const ADDRESS_SYSTEM = '$';
 export const ADDRESS_EMPTY = '';
-export const ADDRESS_RESTRICTED = [
-    ADDRESS_DISCARD,
-    ADDRESS_SYSTEM,
-    SEPERATOR
-];
+export const ADDRESS_RESTRICTED = [ADDRESS_DISCARD, ADDRESS_SYSTEM, SEPERATOR];
 
 /**
  * Address of an actor.
@@ -24,83 +20,71 @@ export type Address = string;
  * AddressMap
  */
 export interface AddressMap {
-
-    [key: string]: Address
-
+    [key: string]: Address;
 }
 
 /**
  * isRestricted indicates whether an actor id is restricted or not.
  */
 export const isRestricted = (id: string) =>
-    ((ADDRESS_RESTRICTED.some(a => id.indexOf(a) > -1)) && (id !== SEPERATOR));
+    ADDRESS_RESTRICTED.some(a => id.indexOf(a) > -1) && id !== SEPERATOR;
 
 /**
  * make a child address given its id and parent address.
  */
-export const make = (parent: Address, id: string): Address =>
-    ((parent === SEPERATOR) || (parent === ADDRESS_EMPTY)) ?
-        `${parent}${id}` :
-        (parent === ADDRESS_SYSTEM) ?
-            id :
-            `${parent}${SEPERATOR}${id}`;
+export const make = (parent: Address, id: string): Address => {
+    id = id.trim();
+    return parent === SEPERATOR || parent === ADDRESS_EMPTY
+        ? `${parent}${id}`
+        : parent === ADDRESS_SYSTEM
+          ? id
+          : `${parent}${SEPERATOR}${id}`;
+};
 
 /**
  * getParent computes the parent of an Address.
  */
 export const getParent = (addr: Address): Address => {
-
-    if (((addr === ADDRESS_SYSTEM) ||
-        (addr === ADDRESS_EMPTY) ||
-        (addr === ADDRESS_DISCARD) || (addr === SEPERATOR))) {
-
+    if (
+        addr === ADDRESS_SYSTEM ||
+        addr === ADDRESS_EMPTY ||
+        addr === ADDRESS_DISCARD ||
+        addr === SEPERATOR
+    ) {
         return ADDRESS_SYSTEM;
-
     } else {
-
         let b4 = addr.split(SEPERATOR);
 
-        if ((b4.length === 2) && (b4[0] === '')) {
-
+        if (b4.length === 2 && b4[0] === '') {
             return SEPERATOR;
-
         } else {
-
-            let a = b4
-                .reverse()
-                .slice(1)
-                .reverse()
-                .join(SEPERATOR);
+            let a = b4.reverse().slice(1).reverse().join(SEPERATOR);
 
             return a === ADDRESS_EMPTY ? ADDRESS_SYSTEM : a;
-
-
         }
-
     }
-
-}
+};
 
 /**
  * getId provides the id part of an actor address.
  */
 export const getId = (addr: Address): string =>
-    ((addr === ADDRESS_SYSTEM) ||
-        (addr === ADDRESS_DISCARD) ||
-        (addr === ADDRESS_EMPTY) ||
-        (addr === SEPERATOR)) ?
-        addr :
-        tail(addr.split(SEPERATOR));
+    addr === ADDRESS_SYSTEM ||
+    addr === ADDRESS_DISCARD ||
+    addr === ADDRESS_EMPTY ||
+    addr === SEPERATOR
+        ? addr
+        : tail(addr.split(SEPERATOR));
 
 /**
  * isChild tests whether an address is a child of the parent address.
  */
 export const isChild = (parent: Address, child: Address): boolean =>
-    ((parent === ADDRESS_SYSTEM) && (child !== parent)) || 
+    (parent === ADDRESS_SYSTEM && child !== parent) ||
     startsWith(child, `${parent}${SEPERATOR}`);
 
 /**
  * isGroup determines if an address is a group reference.
  */
 export const isGroup = (addr: Address): boolean =>
-    ((addr[0] === '$') && (addr !== '$'))
+    addr[0] === '$' && addr !== '$';

package/lib/actor/api.d.ts

@@ -0,0 +1,47 @@
+import { Err } from '@quenk/noni/lib/control/error';
+import { Address } from './address';
+import { Spawnable } from './template';
+import { Message } from '.';
+import { TypeCase } from '@quenk/noni/lib/control/match/case';
+/**
+ * Parent is any object capable of spawning a child actor.
+ */
+export interface Parent {
+    /**
+     * spawn an actor give its template.
+     */
+    spawn(t: Spawnable): Promise<Address>;
+}
+/**
+ * Api is the interface provided by objects that can send/receive messages to
+ * actors within the system.
+ *
+ * This interface is separate from the Actor interface because the system is
+ * not directly concerned with their implementation. Instead, they exist to
+ * provide a way for user land code to interact with other actors within the
+ * system.
+ */
+export interface Api extends Parent {
+    self: Address;
+    /**
+     * raise an error triggering the system's error handling machinery.
+     */
+    raise(e: Err): Promise<void>;
+    /**
+     * kill sends a stop signal to a child actor.
+     *
+     * An actor can only specify itself or a child as the target.
+     */
+    kill(target: Address): Promise<void>;
+    /**
+     * tell a message to an actor address.
+     */
+    tell(ref: string, msg: Message): Promise<void>;
+    /**
+     * receive a message from the actor's mailbox.
+     *
+     * If TypeCases are provided, the message will be matched against them
+     * first and the result provided.
+     */
+    receive<T>(cases?: TypeCase<T>[]): Promise<T>;
+}

package/lib/actor/api.ts

@@ -0,0 +1,57 @@
+import { Err } from '@quenk/noni/lib/control/error';
+
+import { Address } from './address';
+import { Spawnable } from './template';
+import { Message } from '.';
+import { TypeCase } from '@quenk/noni/lib/control/match/case';
+
+/**
+ * Parent is any object capable of spawning a child actor.
+ */
+export interface Parent {
+    /**
+     * spawn an actor give its template.
+     */
+    spawn(t: Spawnable): Promise<Address>;
+}
+
+/**
+ * Api is the interface provided by objects that can send/receive messages to
+ * actors within the system.
+ *
+ * This interface is separate from the Actor interface because the system is
+ * not directly concerned with their implementation. Instead, they exist to
+ * provide a way for user land code to interact with other actors within the
+ * system.
+ */
+export interface Api extends Parent {
+    /*
+     * self is the address for the actor within the system
+     */
+    self: Address;
+
+    /**
+     * raise an error triggering the system's error handling machinery.
+     */
+    raise(e: Err): Promise<void>;
+
+    /**
+     * kill sends a stop signal to a child actor.
+     *
+     * An actor can only specify itself or a child as the target.
+     */
+    kill(target: Address): Promise<void>;
+
+    /**
+     * tell a message to an actor address.
+     */
+    tell(ref: string, msg: Message): Promise<void>;
+
+    /**
+     * receive a message from the actor's mailbox.
+     *
+     * If TypeCases are provided, the message will be matched against them
+     * first and the result provided.
+     */
+    receive<T>(cases?: TypeCase<T>[]): Promise<T>;
+}

package/lib/actor/framework/index.d.ts

@@ -0,0 +1 @@
+export { TypeCase, Case, Default } from '@quenk/noni/lib/control/match/case';

package/lib/actor/framework/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Default = exports.Case = void 0;
+var case_1 = require("@quenk/noni/lib/control/match/case");
+Object.defineProperty(exports, "Case", { enumerable: true, get: function () { return case_1.Case; } });
+Object.defineProperty(exports, "Default", { enumerable: true, get: function () { return case_1.Default; } });
+//# sourceMappingURL=index.js.map

package/lib/actor/framework/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":";;;AAAA,2DAA6E;AAA1D,4FAAA,IAAI,OAAA;AAAE,+FAAA,OAAO,OAAA"}

package/lib/actor/framework/index.ts

@@ -0,0 +1 @@
+export { TypeCase, Case, Default } from '@quenk/noni/lib/control/match/case';

package/lib/actor/framework/process.d.ts

@@ -0,0 +1,31 @@
+import { TypeCase } from '@quenk/noni/lib/control/match/case';
+import { Address } from '../address';
+/**
+ * init should be called as early as possible in the child process if using the
+ * direct API (Process).
+ *
+ * It sets up a listener for incoming messages to the child_process that can
+ * be read later via receive() or select().
+ */
+export declare const init: () => void;
+/**
+ * self provides the address for this child actor.
+ */
+export declare const self: string;
+/**
+ * tell sends a message to another actor in the system using the VM in the
+ * parent process.
+ */
+export declare const tell: <M>(to: Address, message: M) => any;
+/**
+ * receive the next message in the message queue.
+ *
+ * TODO: drop messages that do not match any cases.
+ */
+export declare const receive: <T>(cases?: TypeCase<T>[]) => Promise<T>;
+/**
+ * exit the actor, ending the process as a result.
+ *
+ * This is simply a wrapper around process.exit();
+ */
+export declare const exit: () => never;

package/lib/actor/framework/process.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.exit = exports.receive = exports.tell = exports.self = exports.init = void 0;
+const array_1 = require("@quenk/noni/lib/data/array");
+const case_1 = require("@quenk/noni/lib/control/match/case");
+const function_1 = require("@quenk/noni/lib/data/function");
+const address_1 = require("../address");
+const messages = [];
+/**
+ * init should be called as early as possible in the child process if using the
+ * direct API (Process).
+ *
+ * It sets up a listener for incoming messages to the child_process that can
+ * be read later via receive() or select().
+ */
+const init = () => {
+    if (!process.send)
+        throw new Error('process: direct API is meant to ' + 'be used in a child process!');
+    process.on('message', (m) => {
+        messages.unshift(m);
+        drain();
+    });
+    process.on('uncaughtExceptionMonitor', err => process.send(err));
+};
+exports.init = init;
+/**
+ * self provides the address for this child actor.
+ */
+exports.self = process.env.POTOO_ACTOR_ADDRESS || address_1.ADDRESS_DISCARD;
+/**
+ * tell sends a message to another actor in the system using the VM in the
+ * parent process.
+ */
+const tell = (to, message) => process.send({ from: exports.self, to, message });
+exports.tell = tell;
+const receivers = [];
+const defaultCases = [new case_1.Default(function_1.identity)];
+/**
+ * receive the next message in the message queue.
+ *
+ * TODO: drop messages that do not match any cases.
+ */
+const receive = async (cases = defaultCases) => new Promise(resolve => {
+    let matcher = new case_1.CaseFunction(cases || defaultCases);
+    let receiver = async (msg) => {
+        if (matcher.test(msg)) {
+            resolve(await matcher.apply(msg));
+        }
+        else {
+            receivers.push(receiver);
+        }
+    };
+    receivers.push(receiver);
+    drain();
+});
+exports.receive = receive;
+const drain = () => {
+    if (!(0, array_1.empty)(messages) && !(0, array_1.empty)(receivers))
+        receivers.pop()(messages.shift());
+};
+/**
+ * exit the actor, ending the process as a result.
+ *
+ * This is simply a wrapper around process.exit();
+ */
+const exit = () => process.exit();
+exports.exit = exit;
+//# sourceMappingURL=process.js.map

package/lib/actor/framework/process.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"process.js","sourceRoot":"","sources":["process.ts"],"names":[],"mappings":";;;AACA,sDAAmD;AACnD,6DAI4C;AAC5C,4DAAyD;AAEzD,wCAAsD;AAGtD,MAAM,QAAQ,GAAc,EAAE,CAAC;AAE/B;;;;;;GAMG;AACI,MAAM,IAAI,GAAG,GAAG,EAAE;IACrB,IAAI,CAAC,OAAO,CAAC,IAAI;QACb,MAAM,IAAI,KAAK,CACX,kCAAkC,GAAG,6BAA6B,CACrE,CAAC;IAEN,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,CAAC,CAAU,EAAE,EAAE;QACjC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;QACpB,KAAK,EAAE,CAAC;IACZ,CAAC,CAAC,CAAC;IAEH,OAAO,CAAC,EAAE,CAAC,0BAA0B,EAAE,GAAG,CAAC,EAAE,CAC9B,OAAO,CAAC,IAAK,CAAC,GAAG,CAAC,CAChC,CAAC;AACN,CAAC,CAAC;AAdW,QAAA,IAAI,QAcf;AAEF;;GAEG;AACU,QAAA,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,mBAAmB,IAAI,yBAAe,CAAC;AAEvE;;;GAGG;AACI,MAAM,IAAI,GAAG,CAAI,EAAW,EAAE,OAAU,EAAE,EAAE,CACpC,OAAO,CAAC,IAAK,CAAC,EAAE,IAAI,EAAE,YAAI,EAAE,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;AAD7C,QAAA,IAAI,QACyC;AAI1D,MAAM,SAAS,GAAc,EAAE,CAAC;AAEhC,MAAM,YAAY,GAAG,CAAC,IAAI,cAAO,CAAC,mBAAQ,CAAC,CAAC,CAAC;AAE7C;;;;GAIG;AACI,MAAM,OAAO,GAAG,KAAK,EACxB,QAAuB,YAAY,EACzB,EAAE,CACZ,IAAI,OAAO,CAAC,OAAO,CAAC,EAAE;IAClB,IAAI,OAAO,GAAG,IAAI,mBAAY,CAAC,KAAK,IAAI,YAAY,CAAC,CAAC;IACtD,IAAI,QAAQ,GAAG,KAAK,EAAE,GAAY,EAAE,EAAE;QAClC,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;YACpB,OAAO,CAAC,MAAM,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;QACtC,CAAC;aAAM,CAAC;YACJ,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC7B,CAAC;IACL,CAAC,CAAC;IACF,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACzB,KAAK,EAAE,CAAC;AACZ,CAAC,CAAC,CAAC;AAdM,QAAA,OAAO,WAcb;AAEP,MAAM,KAAK,GAAG,GAAG,EAAE;IACf,IAAI,CAAC,IAAA,aAAK,EAAC,QAAQ,CAAC,IAAI,CAAC,IAAA,aAAK,EAAC,SAAS,CAAC;QAC3B,SAAS,CAAC,GAAG,EAAG,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;AACrD,CAAC,CAAC;AAEF;;;;GAIG;AACI,MAAM,IAAI,GAAG,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;AAA5B,QAAA,IAAI,QAAwB"}

package/lib/actor/framework/process.ts

@@ -0,0 +1,87 @@
+import { Type } from '@quenk/noni/lib/data/type';
+import { empty } from '@quenk/noni/lib/data/array';
+import {
+    CaseFunction,
+    Default,
+    TypeCase
+} from '@quenk/noni/lib/control/match/case';
+import { identity } from '@quenk/noni/lib/data/function';
+
+import { Address, ADDRESS_DISCARD } from '../address';
+import { Message } from '../';
+
+const messages: Message[] = [];
+
+/**
+ * init should be called as early as possible in the child process if using the
+ * direct API (Process).
+ *
+ * It sets up a listener for incoming messages to the child_process that can
+ * be read later via receive() or select().
+ */
+export const init = () => {
+    if (!process.send)
+        throw new Error(
+            'process: direct API is meant to ' + 'be used in a child process!'
+        );
+
+    process.on('message', (m: Message) => {
+        messages.unshift(m);
+        drain();
+    });
+
+    process.on('uncaughtExceptionMonitor', err =>
+        (<Function>process.send)(err)
+    );
+};
+
+/**
+ * self provides the address for this child actor.
+ */
+export const self = process.env.POTOO_ACTOR_ADDRESS || ADDRESS_DISCARD;
+
+/**
+ * tell sends a message to another actor in the system using the VM in the
+ * parent process.
+ */
+export const tell = <M>(to: Address, message: M) =>
+    (<Function>process.send)({ from: self, to, message });
+
+type Handler = (value: Type) => Promise<void>;
+
+const receivers: Handler[] = [];
+
+const defaultCases = [new Default(identity)];
+
+/**
+ * receive the next message in the message queue.
+ *
+ * TODO: drop messages that do not match any cases.
+ */
+export const receive = async <T>(
+    cases: TypeCase<T>[] = defaultCases
+): Promise<T> =>
+    new Promise(resolve => {
+        let matcher = new CaseFunction(cases || defaultCases);
+        let receiver = async (msg: Message) => {
+            if (matcher.test(msg)) {
+                resolve(await matcher.apply(msg));
+            } else {
+                receivers.push(receiver);
+            }
+        };
+        receivers.push(receiver);
+        drain();
+    });
+
+const drain = () => {
+    if (!empty(messages) && !empty(receivers))
+        (<Handler>receivers.pop())(messages.shift());
+};
+
+/**
+ * exit the actor, ending the process as a result.
+ *
+ * This is simply a wrapper around process.exit();
+ */
+export const exit = () => process.exit();