Merge pull request #38 from aidanm3341/gh-pages-2

created github pages directory

.github/dependabot.yml

@@ -15,3 +15,12 @@ updates:
     directory: "/"
     schedule:
       interval: "weekly"  
+
+  - package-ecosystem: npm
+     directory: /site
+     schedule:
+       interval: "monthly"
+     groups:
+       gatsby:
+         patterns:
+           - "gatsby*"

.github/workflows/site-deploy.yml

@@ -0,0 +1,35 @@
+name: GH Page Deploy
+
+on:
+  push:
+    branches:
+      - main
+
+defaults:
+  run:
+    working-directory: ./site
+
+permissions:
+  contents: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: "npm"
+          cache-dependency-path: "./site/package-lock.json"
+      - run: npm ci
+      - run: npm run build
+      - name: Deploy
+        uses: crazy-max/ghaction-github-pages@v4
+        with:
+          target_branch: gh-pages
+          build_dir: docs
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/site-pr-build.yml

@@ -0,0 +1,25 @@
+name: GH Page PR Build
+
+on:
+  pull_request:
+    branches:
+      - main
+
+defaults:
+  run:
+    working-directory: ./site
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: "npm"
+          cache-dependency-path: "./site/package-lock.json"
+      - run: npm ci
+      - run: npm run build

.gitignore

@@ -6,4 +6,4 @@ reports/
 *.tgz
 npm-debug.log
 npm
-package-lock.json
+/package-lock.json

site/.gitignore

@@ -0,0 +1,69 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Runtime data
+pids
+*.pid
+*.seed
+*.pid.lock
+
+# Directory for instrumented libs generated by jscoverage/JSCover
+lib-cov
+
+# Coverage directory used by tools like istanbul
+coverage
+
+# nyc test coverage
+.nyc_output
+
+# Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files)
+.grunt
+
+# Bower dependency directory (https://bower.io/)
+bower_components
+
+# node-waf configuration
+.lock-wscript
+
+# Compiled binary addons (http://nodejs.org/api/addons.html)
+build/Release
+
+# Dependency directories
+node_modules/
+jspm_packages/
+
+# Typescript v1 declaration files
+typings/
+
+# Optional npm cache directory
+.npm
+
+# Optional eslint cache
+.eslintcache
+
+# Optional REPL history
+.node_repl_history
+
+# Output of 'npm pack'
+*.tgz
+
+# dotenv environment variable files
+.env*
+
+# gatsby files
+.cache/
+public
+
+# Mac files
+.DS_Store
+
+# Yarn
+yarn-error.log
+.pnp/
+.pnp.js
+# Yarn Integrity file
+.yarn-integrity

site/.prettierignore

@@ -0,0 +1,4 @@
+.cache
+package.json
+package-lock.json
+public

site/.prettierrc

@@ -0,0 +1,7 @@
+{
+  "endOfLine": "lf",
+  "semi": true,
+  "singleQuote": true,
+  "tabWidth": 2,
+  "trailingComma": "es5"
+}

site/.vscode/extensions.json

@@ -0,0 +1,12 @@
+{
+  // See https://go.microsoft.com/fwlink/?LinkId=827846 to learn about workspace recommendations.
+  // Extension identifier format: ${publisher}.${name}. Example: vscode.csharp
+  // List of extensions which should be recommended for users of this workspace.
+  "recommendations": [
+    "dbaeumer.vscode-eslint",
+    "mquandalle.graphql",
+    "ecmel.vscode-html-css"
+  ],
+  // List of extensions recommended by VS Code that should not be recommended for users of this workspace.
+  "unwantedRecommendations": []
+}

site/.vscode/settings.json

@@ -0,0 +1,15 @@
+{
+  "diffEditor.codeLens": true,
+  "files.trimTrailingWhitespace": true,
+  "html.format.indentInnerHtml": true,
+  "html.format.wrapAttributes": "force-aligned",
+  "eslint.format.enable": true,
+  "editor.codeActionsOnSave": {
+    "source.fixAll.eslint": "explicit"
+  },
+  "eslint.validate": ["javascript"],
+  "editor.formatOnSave": true,
+  "search.exclude": {
+    "**/node_modules": true
+  }
+}

site/content/alternatives.mdx

@@ -0,0 +1,13 @@
+---
+description: List of alternatives and how they differ from this project
+title: Alternatives
+date: 2024-04-24
+---
+
+List of alternatives to the Message Broker.
+
+- [BullMQ](https://docs.bullmq.io)
+    - Relies on Redis
+- [@node-ts/bus](https://bus.node-ts.com)
+
+Both of these alternatives lack the same level of type safety that the Message Broker provides.

site/content/background.mdx

@@ -0,0 +1,7 @@
+---
+description: Background and origin story of the Message Broker
+title: Background
+---
+
+This project was written at Morgan Stanley to provide an internal messaging system for large scale UI systems.
+The project was later Open Sourced so others could benefit from it.

site/content/documentation-hero.mdx

@@ -0,0 +1,11 @@
+---
+description: Contribute content hero
+title: Hero
+---
+
+<Hero title="Documentation">
+  Open source is more than just code. There is planning before code is written,
+  the process on how to contribute or release that code, and fostering an
+  inclusive environment and community. Please review the guidelines below to
+  learn how to best contribute.
+</Hero>

site/content/documentation/intro-doc.mdx

@@ -0,0 +1,51 @@
+---
+order: 1
+title: Development
+---
+
+## Prerequisites
+
+You must use Typescript version: >3.4
+
+The library depends on TypeScript's support for decorators.
+Therefore you must enable `experimentalDecorators` and `emitDecoratorMetadata`.
+
+```typescript
+{
+    "compilerOptions": {
+        "experimentalDecorators": true,
+        "emitDecoratorMetadata": true
+    }
+}
+```
+
+### Polyfills
+
+This library will work with modern browsers and JavaScript run-times without the need for polyfills, however if targeting older browsers you will need to provide a polyfill for the following types:
+
+- Map. Read about the Map type [here](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map).
+
+This library also makes use of the `reflect-metadata` API for performing runtime introspection.
+Most browsers will not support this therefore you must install this yourself.
+
+```bash
+npm install reflect-metadata
+```
+
+And you should import this module at the root of your application.
+
+```typescript
+import "reflect-metadata";
+```
+
+## Quick Start
+
+import GettingStarted from '../getting-started.mdx';
+
+<GettingStarted />
+
+## Dependency Injection
+
+The MessageBroker class is decorated with @Injectable from @morgan-stanley/needle.
+This means that it can be constructed by different DI frameworks.
+For more information please refer to the [documentation for the Needle framework](https://github.com/morganstanley/needle).

site/content/documentation/message-replaying.mdx

@@ -0,0 +1,18 @@
+---
+order: 3
+title: Message Replaying
+---
+
+Replaying will allow new subscriptions to receive the latest "n" number of messages. Using the messagebroker config the user can configure how many messages they want to be cached when subscriptions are made. Configs can only be provided when the messagebroker channels are created.
+
+```typescript
+import { messagebroker } from "@morgan-stanley/message-broker";
+
+messagebroker()
+    .create('myCachedChannel', { replayCacheSize: 2 })
+    .publish({
+        payload: 'a message to all new Subscribers!'
+    });
+```
+
+It is important to note that creating a channel with the same name but with different configurations will throw an error.

site/content/documentation/rsvp.mdx

@@ -0,0 +1,67 @@
+---
+order: 4
+title: RSVP
+---
+
+The RSVP methods allow developers to define a request/response model using the messagebroker.
+Unlike a normal publish, publishing on an RSVP channel is a synchronous call that will ask all subscribers to respond with some value.
+
+An RSVP message must be sent on a special RSVP channel.
+In order to create on of those, you should extend the IRSVPConfig interface in your Contract interface, which will require you to specify an `rsvp` section.
+In this section, you can provide a channel name as usual, and it must have a `payload` and `response` section in it.
+
+```typescript
+interface IContract extends IRSVPConfig {
+    nonRSVPChannel : string;
+    rsvp: {
+        myRSVPChannel: {
+            payload: { data: string };
+            response: number;
+        };
+    };
+}
+```
+
+### Publish
+
+With your contract defined, you can now publish a message.
+
+Remember, this call will be *synchronous*, so it will block until all the subscribers have completed their work and returned a value.
+
+When all return values have been gathered, they will be returned by the rsvp method.
+
+```typescript
+const results: number[] = messagebroker<IMessageChannels>()
+                            .rsvp('myRSVPChannel', { data: 'abcde'});
+```
+
+### Respond
+
+Subscribing to an RSVP channel looks much the same as publishing, with the key difference being that the second parameter is a **function** rather than an object.
+This function must take a parameter of the type that matches the `payload` type in your contract.
+It must then return a value which is of the same type as the `response` type in your contract.
+
+```typescript
+messagebroker<IMessageChannels>()
+    .rsvp('myRSVPChannel', payload => {
+        // Perform some work on payload
+        return len(payload.data);
+    }
+);
+```
+
+### Respond with manual disconnect
+
+If for some reason you would like to stop responding to RSVP messages on a certain channel, the `rsvp` function returns a responder handler which has a `disconnect` method on it.
+Calling this method will prevent any further messages being received.
+
+```typescript
+const responder = messagebroker<IMessageChannels>()
+                    .rsvp('myRSVPChannel', payload => {
+                        return len(payload.data);
+                    });
+
+// Manually disconnect the responder to
+// avoid handling further rsvp requests.
+responder.disconnect();
+```