@cratis/arc 20.24.14 → 20.26.1

package/index.ts

@@ -3,6 +3,7 @@
 
 import * as commands from './commands';
 import * as identity from './identity';
+import * as messaging from './messaging';
 import * as queries from './queries';
 import * as validation from './validation';
 import * as reflection from './reflection';
@@ -15,6 +16,7 @@ export * from './GetHttpHeaders';
 export {
     commands,
     identity,
+    messaging,
     queries,
     validation,
     reflection,

package/messaging/IMessenger.ts

@@ -0,0 +1,40 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { Constructor } from '@cratis/fundamentals';
+import { Subscription } from 'rxjs';
+
+/**
+ * Represents a message handler.
+ */
+export type MessageHandler<T> = (message: T) => void;
+
+/**
+ * Defines a system for publishing and subscribing to messages.
+ */
+export abstract class IMessenger {
+
+    /**
+     * Gets or sets whether published messages should bubble to the parent messenger.
+     * Defaults to false.
+     */
+    abstract bubbleToParent: boolean;
+
+    /**
+     * Gets or sets whether messages should trickle down to child messengers.
+     * Defaults to true.
+     */
+    abstract trickleDownToChildren: boolean;
+
+    /**
+     * Publish a message.
+     * @param {*} message Message to publish.
+     */
+    abstract publish<TMessage extends object>(message: TMessage): void;
+
+    /**
+     * Subscribe to a specific message type.
+     * @param {MessageHandler} callback Callback that gets called when message arrives.
+     */
+    abstract subscribe<TMessage extends object>(type: Constructor<TMessage>, callback: MessageHandler<TMessage>): Subscription;
+}

package/messaging/Message.ts

@@ -0,0 +1,18 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { Constructor } from '@cratis/fundamentals';
+
+/**
+ * Represents a message published on the {@link Messenger}.
+ */
+export class Message {
+
+    /**
+     * Initializes a new instance of {@link Message}.
+     * @param {Constructor} type Type of the content in the message.
+     * @param {*} content The actual content.
+     */
+    constructor(readonly type: Constructor, readonly content: object) {
+    }
+}

package/messaging/Messenger.ts

@@ -0,0 +1,87 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { Constructor } from '@cratis/fundamentals';
+import { filter, Subject, Subscription } from 'rxjs';
+import { IMessenger } from './IMessenger';
+import { Message } from './Message';
+
+/**
+ * Represents an implementation of {@link IMessenger}.
+ */
+export class Messenger extends IMessenger {
+    bubbleToParent = false;
+    trickleDownToChildren = true;
+
+    private readonly _messages = new Subject<Message>();
+    private readonly _children = new Set<Messenger>();
+
+    constructor(private readonly _parent?: Messenger) {
+        super();
+        this._parent?._children.add(this);
+    }
+
+    /**
+     * Dispose this messenger and remove it from its parent.
+     */
+    dispose() {
+        this._parent?._children.delete(this);
+    }
+
+    /** @inheritdoc */
+    publish<TMessage extends object>(message: TMessage): void {
+        this._publishFromSelf(message);
+    }
+
+    /** @inheritdoc */
+    subscribe<TMessage extends object>(type: Constructor<TMessage>, callback: (message: TMessage) => void): Subscription {
+        const observable = this._messages.pipe(filter(m => m.type === type));
+        const subscription = observable.subscribe(m => callback(m.content as TMessage));
+        return subscription;
+    }
+
+    private _publishFromSelf<TMessage extends object>(message: TMessage) {
+        this._publishLocally(message);
+
+        if (this.bubbleToParent && this._parent) {
+            this._parent._publishFromChild(message, this);
+        }
+
+        if (this.trickleDownToChildren) {
+            this._publishToChildren(message);
+        }
+    }
+
+    private _publishFromParent<TMessage extends object>(message: TMessage) {
+        this._publishLocally(message);
+
+        if (this.trickleDownToChildren) {
+            this._publishToChildren(message);
+        }
+    }
+
+    private _publishFromChild<TMessage extends object>(message: TMessage, child: Messenger) {
+        this._publishLocally(message);
+
+        if (this.bubbleToParent && this._parent) {
+            this._parent._publishFromChild(message, this);
+        }
+
+        if (this.trickleDownToChildren) {
+            this._publishToChildren(message, child);
+        }
+    }
+
+    private _publishLocally<TMessage extends object>(message: TMessage) {
+        this._messages.next(new Message(message.constructor as Constructor, message));
+    }
+
+    private _publishToChildren<TMessage extends object>(message: TMessage, excludedChild?: Messenger) {
+        this._children.forEach(child => {
+            if (child === excludedChild) {
+                return;
+            }
+            child._publishFromParent(message);
+        });
+    }
+}

package/messaging/for_Messenger/when_scoping_messages.ts

@@ -0,0 +1,74 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { Messenger } from '../Messenger';
+
+class MessageToSend {
+    constructor(readonly something: string) { }
+}
+
+describe('when scoping messages', () => {
+    let root: Messenger;
+    let child: Messenger;
+    let grandchild: Messenger;
+    let rootMessages: MessageToSend[];
+    let childMessages: MessageToSend[];
+    let grandchildMessages: MessageToSend[];
+
+    beforeEach(() => {
+        root = new Messenger();
+        child = new Messenger(root);
+        grandchild = new Messenger(child);
+        rootMessages = [];
+        childMessages = [];
+        grandchildMessages = [];
+
+        root.subscribe(MessageToSend, message => rootMessages.push(message));
+        child.subscribe(MessageToSend, message => childMessages.push(message));
+        grandchild.subscribe(MessageToSend, message => grandchildMessages.push(message));
+    });
+
+    afterEach(() => {
+        grandchild.dispose();
+        child.dispose();
+        root.dispose();
+    });
+
+    describe('and publishing from child with default options', () => {
+        beforeEach(() => child.publish(new MessageToSend('forty two')));
+
+        it('should publish locally', () => childMessages.length.should.equal(1));
+        it('should not bubble to parent', () => rootMessages.length.should.equal(0));
+        it('should trickle to child messengers', () => grandchildMessages.length.should.equal(1));
+    });
+
+    describe('and publishing from parent with default options', () => {
+        beforeEach(() => root.publish(new MessageToSend('forty two')));
+
+        it('should trickle recursively to child messengers', () => {
+            childMessages.length.should.equal(1);
+            grandchildMessages.length.should.equal(1);
+        });
+    });
+
+    describe('and child enables bubbling to parent', () => {
+        beforeEach(() => {
+            child.bubbleToParent = true;
+            child.publish(new MessageToSend('forty two'));
+        });
+
+        it('should bubble to parent', () => rootMessages.length.should.equal(1));
+    });
+
+    describe('and parent disables trickling to children', () => {
+        beforeEach(() => {
+            root.trickleDownToChildren = false;
+            root.publish(new MessageToSend('forty two'));
+        });
+
+        it('should not forward to any child messengers', () => {
+            childMessages.length.should.equal(0);
+            grandchildMessages.length.should.equal(0);
+        });
+    });
+});

package/messaging/index.ts

@@ -0,0 +1,6 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+export * from './IMessenger';
+export * from './Message';
+export * from './Messenger';

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cratis/arc",
-    "version": "20.24.14",
+    "version": "20.26.1",
     "description": "",
     "author": "Cratis",
     "license": "MIT",
@@ -36,6 +36,11 @@
             "import": "./dist/esm/identity/index.js",
             "require": "./dist/cjs/identity/index.js"
         },
+        "./messaging": {
+            "types": "./dist/esm/messaging/index.d.ts",
+            "import": "./dist/esm/messaging/index.js",
+            "require": "./dist/cjs/messaging/index.js"
+        },
         "./queries": {
             "types": "./dist/esm/queries/index.d.ts",
             "import": "./dist/esm/queries/index.js",
@@ -64,6 +69,7 @@
         "up": "yarn g:up"
     },
     "dependencies": {
-        "@cratis/fundamentals": "^7.9.2"
+        "@cratis/fundamentals": "^7.9.2",
+        "rxjs": "^7.8.2"
     }
 }