Merge pull request #193 from podium-lib/ts-semrel-stuff

fix: generate types from JSDoc

Author: wkillerud

.github/workflows/pull-request.yml

@@ -0,0 +1,35 @@
+name: Run all tests on PR
+
+permissions:
+  id-token: write
+  contents: read
+
+on:
+  pull_request:
+    branches:
+      - main
+      - next
+
+jobs:
+  run-all-tests:
+    runs-on: [ubuntu-latest]
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Lint
+        run: npm run lint
+
+      - name: Run all tests
+        run: npm test
+
+      - name: Generate and check types
+        run: npm run types

.github/workflows/release.yml

@@ -0,0 +1,50 @@
+name: Release on main
+
+permissions:
+  contents: write # to be able to publish a GitHub release
+  issues: write # to be able to comment on released issues
+  pull-requests: write # to be able to comment on released pull requests
+  id-token: write # to enable use of OIDC for npm provenance
+
+on:
+  push:
+    branches:
+      - main
+      - next
+
+# Cancel previous workflows which might still be running
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
+
+jobs:
+  release:
+    name: Release
+    runs-on: [ubuntu-latest]
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Lint
+        run: npm run lint
+
+      - name: Run all tests
+        run: npm test
+
+      - name: Generate and check types
+        run: npm run types
+
+      - name: Release and publish
+        run: npx semantic-release
+        env:
+          ARTIFACTORY_NPM_SECRET: ${{ env.ARTIFACTORY_NPM_SECRET }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          NPM_TOKEN: ${{ env.ARTIFACTORY_NPM_SECRET }}

.github/workflows/test.yml

@@ -1,3 +1,4 @@
+dist/
 coverage/
 .nyc_output/
 .idea/
@@ -14,3 +15,4 @@ tmp/**/*
 .idea/**/*
 coverage
 .tap/
+*.d.ts

.gitignore

@@ -0,0 +1,50 @@
+# Contributing
+
+Welcome, and thanks for showing an interest in contributing 💜
+
+## 🧞 Commands
+
+| Command         | Action                                                     |
+| --------------- | ---------------------------------------------------------- |
+| `npm install`   | Installs dependencies                                      |
+| `npm test`      | Runs unit tests                                            |
+| `npm run lint`  | Does a check with [ESLint](./.eslintrc)                    |
+| `npm run types` | Generates type definitions from JSDoc and does a typecheck |
+
+## 🚚 Continuous deployment
+
+This repo [uses conventional commits](https://www.conventionalcommits.org/en/v1.0.0/#summary) to automate releases with [Semantic Release][semantic-release].
+
+Some example commits and their release type:
+
+| Commit message                                                                                         | Release type                                                                                                                          |
+| ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `fix: update a non-development dependency`                                                             | Patch. Bugfix release, updates for runtime dependencies.                                                                              |
+| `feat: added a new option Foo`                                                                         | Minor. New feature release.                                                                                                           |
+| `refactor: removed a deprecated option Bar`<br><br>`BREAKING CHANGE: The Bar option has been removed.` | Major. Breaking release, like removing an option.<br /> (Note that the `BREAKING CHANGE: ` token must be in the footer of the commit) |
+
+[workspace]: https://docs.npmjs.com/cli/using-npm/workspaces
+[semantic-release]: https://semantic-release.gitbook.io/semantic-release/
+
+### Working with next releases
+
+When making larger changes that needs thorough testing or modules widely used, you can create a `next` release. Here is how:
+
+1. Create a branch `next` if one does not exist
+2. Make changes (or push whatever changes you have on a different branch onto `next`)
+3. When you are done, commit your changes with semantic-release in mind
+4. The workflows will run and publish a new version on the format: `major.minor.patch-next.<next version>
+Where `next version` is incremented each time you push a feat, fix or patch to the branch.
+
+### GitHub Actions
+
+GitHub Actions workflows:
+
+-   [Build and test pull requests](./.github/workflows/pull-request.yml)
+-   [Build and release changes on `main`](./.github/workflows/release.yml)
+
+You'll find the workflow logs and results in the Actions tab.
+
+## On MessageBus
+
+MessageBus uses a global singleton to coordinate message passing between different instances. This is something you need to be aware of, for instance, if writing unit tests. See [MessageBus.test.js](test/MessageBus.test.js) for an example.

CONTRIBUTING.md

@@ -1,56 +1,61 @@
 # @podium/browser
 
-Podium browser library.
+This is a client-side library designed to send and receive messages between different podlets in a layout.
 
-[![Dependencies](https://img.shields.io/david/podium-lib/browser.svg)](https://david-dm.org/podium-lib/browser)
-[![GitHub Actions status](https://github.com/podium-lib/browser/workflows/Run%20Lint%20and%20Tests/badge.svg)](https://github.com/podium-lib/browser/actions?query=workflow%3A%22Run+Lint+and+Tests%22)
-[![Known Vulnerabilities](https://snyk.io/test/github/podium-lib/browser/badge.svg)](https://snyk.io/test/github/podium-lib/browser)
+## Usage
 
-Currently this module only includes [MessageBus](#MessageBus), but it is possible that it will include more features in the future.
+To install:
 
-## Installation
-
-```bash
-$ npm install @podium/browser
+```sh
+npm install @podium/browser
 ```
 
-## MessageBus
+Include the library in your client-side application.
 
-Cross podlet communication and message passing.
+```js
+import Podium from '@podium/browser';
+```
 
-### Simple usage
+### Send messages between podlets
+
+Use the [MessageBus](#messagebus) to send messages between podlets in a layout.
 
 ```javascript
-// In podlet A. Broadcast an event
+// In podlet A. Broadcast a message.
 import { MessageBus } from '@podium/browser';
 
 const messageBus = new MessageBus();
 
 messageBus.publish('search', 'query', 'couch');
+```
 
-// In podlet B. Subscribe to an event
+```js
+// In podlet B. Subscribe to a message.
 import { MessageBus } from '@podium/browser';
 
 const messageBus = new MessageBus();
 
-messageBus.subscribe('search', 'query', event => {
+messageBus.subscribe('search', 'query', (event) => {
     console.log(event.payload);
 });
 ```
 
-### Constructor
+## API
 
-Create a new MessageBus instance.
+### MessageBus
+
+Cross podlet communication and message passing.
+Create a new MessageBus instance to use the API.
 
 ```javascript
+import { MessageBus } from '@podium/browser';
+
 const messageBus = new MessageBus();
 ```
 
-### API
+#### `.publish(channel, topic, payload)`
 
-#### .publish(channel, topic, payload)
-
-Publish an event for a channel and topic combination. Returns the event object passed to subscribers.
+Publish a message for a channel and topic combination. Returns the `Event` object passed to subscribers.
 
 This method takes the following arguments:
 
@@ -68,9 +73,9 @@ messageBus.publish('search', 'query', 'laptop');
 messageBus.publish('auth', 'logout');
 ```
 
-#### .subscribe(channel, topic, callback)
+#### `.subscribe(channel, topic, callback)`
 
-Subscribe to events for a channel and topic combination.
+Subscribe to messages for a channel and topic combination.
 
 This method takes the following arguments:
 
@@ -83,12 +88,12 @@ This method takes the following arguments:
 Example:
 
 ```javascript
-messageBus.subscribe('channel', 'topic', event => {
+messageBus.subscribe('channel', 'topic', (event) => {
     console.log(event.payload);
 });
 ```
 
-#### .unsubscribe(channel, topic, callback)
+#### `.unsubscribe(channel, topic, callback)`
 
 Unsubscribe to events for a channel and topic combination.
 
@@ -112,7 +117,7 @@ messageBus.subscribe('channel', 'topic', cb);
 messageBus.unsubscribe('channel', 'topic', cb);
 ```
 
-#### .peek(channel, topic)
+#### `.peek(channel, topic)`
 
 Get the latest event for a channel and topic combination.
 
@@ -123,7 +128,7 @@ This method takes the following arguments:
 | channel | `null`  | `string` | `true`   | Name of the channel |
 | topic   | `null`  | `string` | `true`   | Name of the topic   |
 
-#### .log(channel, topic)
+#### `.log(channel, topic)`
 
 Returns an array of the 10 latest events for a channel and topic combination.
 The array is ordered such that the the latest/newest events is at the front of the array.
@@ -140,33 +145,7 @@ Example:
 ```javascript
 const events = messageBus.log('channel', 'topic');
 
-events.forEach(event => {
+events.forEach((event) => {
     console.log(event.payload);
 });
 ```
-
-### Implementation
-
-MessageBus uses a global singleton to coordinate message passing between different instances. This is something you need to be aware of, for instance, if writing unit tests. See [MessageBus.test.js](test/MessageBus.test.js) for an example.
-
-## License
-
-Copyright (c) 2019 FINN.no
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.