First Public Release

Author: alphanull

.editorconfig

@@ -0,0 +1,14 @@
+# See editorconfig.org
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_size = 4
+indent_style = space
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.md]
+insert_final_newline = false
+trim_trailing_whitespace = false

.gitattributes

@@ -0,0 +1,5 @@
+# Ensure consistent line endings
+* text=auto
+
+# Ignore Handlebars for GitHub language stats
+*.hbs linguist-detectable=false

.gitignore

@@ -0,0 +1,2 @@
+.DS_Store
+node_modules

CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+This project adheres to [Semantic Versioning](https://semver.org) and follows the [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) format.
+
+---
+
+## [1.5.0] – 2025-04-06
+
+### Added
+
+- This marks the first public release of **Publisher**
+- Publish/Subscribe architecture with topic hierarchy
+- Wildcard support in subscriptions (`*`)
+- Persistent message storage and late delivery
+- Subscription priority and invocation limits
+- Conditional subscriptions via `condition` function
+- Global configuration via `configure()`
+- Support for both ES Modules and CommonJS (`require`) as well as UMD (global `publisher`)
+- Minified build output via Rollup (ESM + UMD)
+
+---

CONTRIBUTING.md

@@ -0,0 +1,16 @@
+# Contributing
+
+You're very welcome to submit issues or suggest improvements! However, for the moment, code changes will only be accepted by the project maintainer.
+
+## Project Maintainer
+
+- [Frank Kudermann](https://github.com/alphanull) ([@alphanull](https://github.com/alphanull)) – Author & Maintainer
+
+## How to Contribute?
+
+Feel free to:
+
+- Open issues with questions, suggestions, or bug reports.
+- Provide feedback and feature requests.
+
+Thank you for your understanding! 😊

LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright © 2015-present Frank Kudermann @ alphanull.de
+
+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.

README.md

@@ -0,0 +1,277 @@
+![License](https://img.shields.io/github/license/alphanull/publisher)
+![Version](https://img.shields.io/badge/version-1.5-blue)
+[![JSDoc](https://img.shields.io/badge/docs-JSDoc-blue)](./docs/publisher.md)
+![Size](https://img.shields.io/badge/gzipped~2kb-brightgreen)
+
+# @alphanull/publisher
+
+Publisher is a JavaScript Publish/Subscribe (Pub/Sub) library crafted to handle event-driven communication. Provides pub/sub functionality with extensive wildcard support, async/sync publishing, priority and invocation options, content based filtering & more.
+
+The heart of Publisher lies in its uniquely optimized hierarchical data structure, providing fast subscriber matching even with extensive subscription sets. Unlike traditional flat Pub/Sub systems, Publisher allows you to easily organize events into structured topics and leverage wildcard subscriptions for additional flexibility.
+
+Whether you're building scalable web applications or complex front-end architectures, Publisher ensures your events and notifications are handled gracefully and reliably, delivering ease of use combined with powerful features.
+
+## Features
+
+- **Topic Hierarchy & Wildcards**: Manage event complexity with a structured hierarchy and wildcard topic matching.
+- **Persisted Messages**: Ensure subscribers never miss critical events, delivering persistent messages immediately upon subscribing.
+- **Priority & Invocations**: Gain fine-grained control over execution order and limit subscription triggers, improving predictability and efficiency.
+- **Async & Exception Handling**: Dispatch events asynchronously or synchronously with built-in exception handling.
+- **Conditional Execution**: Execute subscriptions only when specific conditions are met.
+- **Global Configuration**: Configure default behavior globally for asynchronous dispatch, error handling, and unsubscribing behavior.
+
+---
+
+## Installation
+
+
+### via NPM
+
+**ATTN: Package is not on npm yet due to namespace clearance!**
+
+```bash
+npm install @alphanull/publisher <<< not here yet!
+```
+
+### via CDN
+
+**Also, no CDN (yet)**
+
+[Download latest version](https://??????) from ????????
+
+### via GitHub
+
+[Download release](https://github.com/alphanull/publisher/releases) from GitHub
+
+------
+
+## Usage
+
+### 1. Initialization
+
+publisher can be used as ES6 module (recommended) but also via `require` in NodeJS or with direct access to a global variable:
+
+## ES6
+
+```javascript
+import { publish, subscribe, unsubscribe } from '@alphanull/publisher';
+```
+
+## CommonJS
+
+```javascript
+const { publish, subscribe, unsubscribe } = require('@alphanull/publisher');
+```
+
+## Global Variable
+
+```html
+<script src="path/to/publisher.min.cjs"></script>
+```
+
+```javascript
+const { publish, subscribe, unsubscribe } = publisher;
+```
+
+
+### 2. Basic Usage
+
+Quickly set up a simple Pub/Sub interaction:
+
+```javascript
+import { publish, subscribe, unsubscribe } from '@alphanull/publisher';
+
+const handler = data => {
+      console.log(`User logged in: ${data.username}`);
+}
+
+// Receiver: subscribe to a specific topic
+const token = subscribe('login', handler);
+
+// Sender: publish an event
+publish('login', { username: 'Alice' });
+
+// Receiver: unsubscribe using the token (recommended)
+unsubscribe(token);
+
+// Receiver: alternatively, unsubscribe using topic and handler
+unsubscribe('login', handler);
+```
+
+---
+
+### 3. Hierarchy and Wildcards
+
+By utilizing topic hierarchies and wildcards, you can subscribe to multiple events. A hierachy is created by using the `/` delimiter to create topic segments, while a `*` is used to match any topic segment:
+
+```javascript
+// Subscribe to ALL topics
+subscribe('*', (data, topic) => {
+    console.log(`Event ${topic} received:`, data);
+});
+
+// Subscribe to all "user"-related topics, INCLUDING "user"
+subscribe('user', (data, topic) => {
+    console.log(`Event ${topic} received:`, data);
+});
+
+// Subscribe to all "user"-related topics, EXCLUDING "user"
+subscribe('user/*', (data, topic) => {
+    console.log(`Event ${topic} received:`, data);
+});
+
+// Matching multiple topics with wildcards
+subscribe('app/*/update', (data, topic) => {
+    console.log(`Update from ${topic}:`, data);
+});
+
+publish('user/logout', { username: 'Bob' }); // triggers first, second & third subscriber
+publish('app/profile/update', { username: 'Charlie' }); // triggers first and fourth subscribers
+publish('app/settings/update', { theme: 'dark' }); // triggers first and fourth subscribers
+```
+
+---
+
+### 4. Advanced Unsubscribe: Multiple Tokens, Lenient Unsubscribe
+
+You can also use an array of tokens to quickly unsubscribe multiple handlers. In addition, adding `true` to the second argument (or the third, in case you use topic/handler for unsubscribe) does not fail with an error if the matching token was not found.
+
+```javascript
+const tokens = [
+    subscribe('topic/1', handler),
+    subscribe('topic/2', handler)
+];
+
+// Batch unsubscribe
+unsubscribe(tokens);
+
+// Lenient unsubscribe, silently ignores non-existing tokens
+unsubscribe(9999, true);
+```
+
+---
+
+### 5. Async and Sync Usage, Cancellation
+
+By default, all events are sent asynchronously. You can override this behavior globally (see 10.) or with individual `publish` actions by using `async: false` as an option. In addition, when using synchronous `publish`, any subscriber is able to cancel an event, so that subsequent subscribers are not notified anymore. So basically, this works similar to the cancellation of DOM Events.
+
+```javascript
+// return false in a handler cancels the chain
+subscribe('sync/event', () => false); 
+
+// Synchronous event publishing can be canceled 
+publish('sync/event', {}, { async: false, cancelable: true });
+```
+
+---
+
+### 6. Priority
+
+Usually, subscribers are notifed in the order they subscribed, i.e. the first subscriber is receiving the first message. You can change this behavior adding a `priority` option, where higher numbers are executed first, with `0` being the default. 
+
+```javascript
+// Control subscriber order with priorities
+subscribe('priority/event', () => console.log('second'), { priority: 1 });
+subscribe('priority/event', () => console.log('first'), { priority: 2 });
+
+publish('priority/event');
+```
+
+---
+
+### 7. Invocations
+
+It is also possible to limit the number of handler invocations by adding the `invocations` option, this being a positive number counting down when the handler is called. Once the counter reaches `0` the handler is automatically unsubscribed. For example, the following code executes the handler only on the first `publish` occurence:
+
+```javascript
+// Limit subscription invocations
+subscribe('limited/event', () => console.log('I only execute once'), { invocations: 1 });
+
+publish('limited/event'); // triggers handler
+publish('limited/event'); // not triggered anymore, handler was unsubscribed
+```
+
+### 8. Conditional Execution
+
+Run subscriptions based on conditional logic, so that the handler is only invoked if the function specified by the `condition` option returns true:
+
+```javascript
+subscribe('data/event', data => {
+    console.log('Condition met:', data);
+}, {
+    condition: data => data.status === 'success'
+});
+
+publish('data/event', { status: 'success' }); // triggers subscriber
+publish('data/event', { status: 'error' }); // ignored
+```
+
+---
+
+### 9. Persistency
+
+Ensure certain messages are received even when the subscription is done after the actual message was already sent. For this to happen, _both_ `publish` and `subscribe` have to use the `persist: true` option. It is also possible to remove a perssitent message later on using `removePersistentMessage`.
+
+```javascript
+import { publish, subscribe, removePersistentMessage } from './publisher.js';
+
+// make message persistent
+publish('app/ready', { status: 'ready' }, { persist: true });
+
+// Subscribers immediately receive persistent messages upon subscription
+subscribe('app/ready', data => console.log('Persistently received:', data), { persist: true });
+
+// after removing, later subscriber don't receive the event anymore
+removePersistentMessage('app/ready');
+```
+
+---
+
+### 10. Error Handling
+
+By default, if a handler throws an Error, it is caught by the publisher so that subsequent subscribers are still being executed. Instead the error is output to the console (if possible). This behavior can be changed globally, or per `publish` so that exceptions are not caught anymore.
+
+```javascript
+subscribe('error/event', () => {
+    throw new Error('Subscriber error!');
+});
+
+subscribe('error/event', () => {
+    console.log('I still might be executed');
+});
+
+// Errors caught internally, other subscribers remain unaffected
+publish('error/event', data , { handleExceptions: true });
+
+// Throws an error, publishing is halted
+publish('error/event', data , { handleExceptions: false });
+```
+
+---
+
+### 11. Global Configuration
+
+Configure Publisher.js globally to tailor its behavior. All subsequent actions will use the newly set option(s), unless locally overidden.
+
+```javascript
+import { configure } from './publisher.js';
+
+// Equivalent to the default configuration
+configure({
+    async: true,                  // Global async dispatch
+    handleExceptions: true,       // Global error handling
+    lenientUnsubscribe: true      // No errors on unsubscribing non-existent subscribers
+});
+```
+
+---
+
+## Docs
+
+For more detailled docs, see [JSDoc Documentation](docs/publisher.md)
+
+## License
+
+[MIT](https://opensource.org/license/MIT) 
+
+Copyright © 2015-present Frank Kudermann @ alphanull.de

dist/publisher.min.cjs

@@ -0,0 +1,6 @@
+/*!
+* Publisher – Javascript Pub/Sub library
+* @license MIT
+* © 2013–2025 Frank Kudermann @ alphanull
+*/
+!function(e,i){"object"==typeof exports&&"undefined"!=typeof module?i(exports):"function"==typeof define&&define.amd?define(["exports"],i):i((e="undefined"!=typeof globalThis?globalThis:e||self).publisher={})}(this,(function(e){"use strict";const i={async:!0,handleExceptions:!1,lenientUnsubscribe:!1},n=new Map,o=new Map,t=new Map;let s=-1;function r(e,t,s){const r=t===Boolean(t)?t:s,c=void 0===r?i.lenientUnsubscribe:r,a=e=>{const i=n.get(e);if(void 0===i){if(!0===c)return;throw new Error(`Unsubscribe failed. Did not find subscriber for token: ${e}`)}l(i.topic.split("/"),i,o),n.delete(e)};if(void 0===e){if(!0===c)return;throw new Error("Unsubscribe failed. No Arguments specified.")}if(Array.isArray(e))e.forEach((e=>a(e)));else if(!isNaN(parseFloat(e))&&isFinite(e))a(e);else{if(void 0===t){if(!0===c)return;throw new Error(`Unsubscribe failed. No handler for topic based unsubscribe specified ${e}`)}for(const[,i]of n)if(i.handler===t&&i.topic===e){l(e.split("/"),i,o),n.delete(i.token);break}}}function c(e,o,t,s={}){if(!n.has(e.token))return;e.options.invocations>0&&(e.options.invocations-=1,e.options.invocations<=0&&r(e.token));const{handler:c}=e;if(!0!==s.handleExceptions&&!0!==i.handleExceptions)return c(t,o);try{return c(t,o)}catch(e){window.console&&window.console.error&&window.console.error("Exception while executing publish handler: ",e)}}function a(e,n,o={},t,s,r=[]){const c=t.get("subscribers")||new Map,d=t.get("topics");for(const[,e]of c){const{condition:t}=e.options;(void 0===t||"[object Function]"===Object.prototype.toString.call(t)&&!0===t(n,s))&&(e.position=r.push(e),e.priority=e.options.priority||0,e.async=Boolean(o.async||e.options.async||i.async))}if(e.length&&d){const i=d.get(e[0]),t=d.get("*");void 0===t&&void 0===i||(void 0!==t&&a(e.slice(1,e.length),n,o,t,s,r),void 0!==i&&a(e.slice(1,e.length),n,o,i,s,r),e.shift())}return r}function d(e,i,n){const[o]=e;void 0===n.get("topics")&&n.set("topics",new Map);const t=n.get("topics");let s=t.get(o);void 0===s&&(s=new Map,t.set(o,s)),e.length<2?(void 0===s.get("subscribers")&&s.set("subscribers",new Map),s.get("subscribers").set(i.token,i)):(e.shift(),d(e,i,s))}function l(e,i,n){const[o]=e,t=n.get("topics"),s=t.get(o),r=s.get("subscribers");e.length<2?(r.delete(i.token),0===r.size&&s.delete("subscribers")):(e.shift(),l(e,i,s)),s.has("topics")&&0===s.get("topics").size&&s.delete("topics"),0===t.get(o).size&&t.delete(o)}e.configure=function(e){if(!e)throw new Error("Publisher configure: no options specified");void 0!==e.async&&(i.async=e.async),void 0!==e.handleExceptions&&(i.handleExceptions=e.handleExceptions),void 0!==e.lenientUnsubscribe&&(i.lenientUnsubscribe=e.lenientUnsubscribe)},e.publish=function(e,n,s={}){if(!0===s.persist&&t.set(e,{data:n,options:s}),e.indexOf("*")>-1)throw new Error("Publish topic cannot contain any wildcards.");const r=a(e.split("/"),n,s,o,e);let d;r.sort(((e,i)=>e.priority===i.priority?e.position-i.position:e.priority>i.priority?-1:1));const l=void 0===s.async?i.async:s.async;for(;d=r.shift();)if(l)setTimeout(c.bind(null,d,e,n,s),0);else if(!1===c(d,e,n,s)&&!1!==s.cancelable)return!1},e.removePersistentMessage=function(e){t.delete(e)},e.subscribe=function(e,r,a={}){const l=s+=1;if(void 0===e)throw new Error('Subscribe failed - "undefined" Topic.');if(e.includes("undefined"))throw new Error(`Subscribe for '${e}' failed - found 'undefined' in topic, this is almost always an error: ${l}`);if(void 0===r)throw new Error(`Subscribe for '${e}' failed - "undefined" Handler`);const f={token:l,topic:e,handler:r,options:a};if(n.set(l,f),d(e.split("/"),f,o),!0!==a.persist)return l;const p=new RegExp(`^${e.replace("*","(.+)")}(/.+)?$`);for(const[e,n]of t){if(e.match(p)){if(void 0===n.options.async?i.async:n.options.async)setTimeout(c.bind(null,f,e,n.data,a),0);else if(!1===c(f,e,n.data,a)&&!0===a.cancelable)break}}return l},e.unsubscribe=r}));