vbstyle-event-models 1.0.5

package/BasicEventModel.d.ts

@@ -0,0 +1,32 @@
+/**
+ * A type for event arguments that can be any array of values.
+ */
+export type EventArgs = any[];
+
+/**
+ * A delegate type for event handlers that take any sender and event arguments.
+ */
+export type EventHandler = (sender: any, e: EventArgs) => void;
+
+/**
+ * A basic event model that allows registration and invocation of event handlers.
+ */
+export declare class BasicEventModel {
+    #eventHandlers: EventHandler[];
+    /**
+     * Add an event handler to the event model.
+     * @param {EventHandler} handler - The event handler to add.
+     */
+    addHandler(handler: EventHandler): void;
+    /**
+     * Remove an event handler from the event model.
+     * @param {EventHandler} handler - The event handler to remove.
+     */
+    removeHandler(handler: EventHandler): void;
+    /**
+     * Raise the event from the event model, invoking all registered event handlers.
+     * @param {any} sender - The event sender.
+     * @param {EventArgs} e - The event arguments.
+     */
+    raiseEvent(sender: any, e: EventArgs): void;
+}

package/BasicEventModel.js

@@ -0,0 +1,37 @@
+"use strict";
+/**
+ * @typedef {any[]} EventArgs A type for event arguments that can be any array of values.
+ */
+
+/**
+ * @typedef {(sender: any, e: EventArgs) => void} EventHandler
+ * A delegate type for event handlers that take any sender and event arguments.
+ */
+
+/**
+ * A basic event model that allows registration and invocation of event handlers.
+ */
+export class BasicEventModel {
+    #eventHandlers = [];
+
+    /**
+     * Add an event handler to the event model.
+     */
+    addHandler(handler) {
+        this.#eventHandlers.push(handler);
+    }
+
+    /**
+     * Remove an event handler from the event model.
+     */
+    removeHandler(handler) {
+        this.#eventHandlers = this.#eventHandlers.filter(h => h !== handler);
+    }
+
+    /**
+     * Raise the event from the event model, invoking all registered event handlers.
+     */
+    raiseEvent(sender, e) {
+        this.#eventHandlers.forEach(handler => handler(sender, e));
+    }
+}

package/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, pac-dessert1436
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/MessageRouter.d.ts

@@ -0,0 +1,50 @@
+import { MutexLock } from './MutexLock';
+
+/**
+ * Type alias for a message handler function.
+ */
+export type MessageHandler = (content: any) => void;
+
+/**
+ * A singleton class for message routing, using a mutex lock for thread safety.
+ */
+export declare class MessageRouter {
+    static #instance: MessageRouter | null;
+    #subscribers: Map<string, Set<MessageHandler>>;
+    #lock: MutexLock;
+    constructor();
+
+    /**
+     * Get the singleton instance of the MessageRouter class.
+     * @returns {MessageRouter} The singleton instance.
+     */
+    static get instance(): MessageRouter;
+    /**
+     * Subscribe to a message type.
+     * @param {string} messageType - The type of message to subscribe to.
+     * @param {MessageHandler} handler - The message handler to call when a message of the specified type is sent.
+     */
+    subscribe(messageType: string, handler: MessageHandler): Promise<void>;
+    /**
+     * Send a message of a specific type.
+     * @param {string} messageType - The type of message to send.
+     * @param {*} content - The content of the message to send.
+     */
+    send(messageType: string, content: any): Promise<void>;
+    /**
+     * Unsubscribe from a message type.
+     * @param {string} messageType - The type of message to unsubscribe from.
+     * @param {MessageHandler} handler - The message handler to remove from the subscribers list.
+     */
+    unsubscribe(messageType: string, handler: MessageHandler): Promise<void>;
+    /**
+     * Clear all subscribers for a specific message type.
+     * @param {string} messageType - The type of message to clear subscribers for.
+     */
+    clearSubscribers(messageType: string): Promise<void>;
+    /**
+     * Get the total number of subscribers across all message types.
+     * @returns {number} The total number of subscribers.
+     */
+    getSubscriberCount(): Promise<number>;
+}

package/MessageRouter.js

@@ -0,0 +1,131 @@
+"use strict";
+import { MutexLock } from "./MutexLock.js";
+
+/**
+ * @typedef {(content: any) => void} MessageHandler Type alias for a message handler function.
+ */
+
+/**
+ * A singleton class for message routing, using a mutex lock for thread safety.
+ */
+export class MessageRouter {
+    static #instance = null;
+    #subscribers = new Map();
+    #lock = new MutexLock();
+
+    constructor() {
+        if (MessageRouter.#instance)
+            throw new Error("Use MessageRouter.instance to get the singleton instance.");
+    }
+
+    /**
+     * Get the singleton instance of the MessageRouter class.
+     * @returns {MessageRouter} The singleton instance.
+     */
+    static get instance() {
+        if (!MessageRouter.#instance)
+            MessageRouter.#instance = new MessageRouter();
+
+        return MessageRouter.#instance;
+    }
+
+    /**
+     * Subscribe to a message type.
+     * @param {string} messageType - The type of message to subscribe to.
+     * @param {MessageHandler} handler - The message handler to call when a message of the specified type is sent.
+     */
+    async subscribe(messageType, handler) {
+        await this.#lock.acquireLock();
+        try {
+            if (!messageType) throw new Error("Message type cannot be empty.");
+            if (typeof handler !== "function") throw new Error("Handler must be a function.");
+
+            if (!this.#subscribers.has(messageType)) {
+                this.#subscribers.set(messageType, new Set());
+            }
+            this.#subscribers.get(messageType).add(handler);
+        } finally {
+            this.#lock.releaseLock();
+        }
+    }
+
+    /**
+     * Send a message of a specific type.
+     * @param {string} messageType - The type of message to send.
+     * @param {*} content - The content of the message to send.
+     */
+    async send(messageType, content) {
+        let handlers = null;
+
+        await this.#lock.acquireLock();
+        try {
+            if (!messageType) throw new Error("Message type cannot be empty.");
+
+            if (this.#subscribers.has(messageType)) {
+                handlers = this.#subscribers.get(messageType);
+            }
+        } finally {
+            this.#lock.releaseLock();
+        }
+
+        if (handlers) {
+            for (const handler of handlers) {
+                try {
+                    handler(content);
+                } catch (ex) {
+                    // Log but don't crash the message pump
+                    console.debug(`Handler error: ${ex.message}`);
+                }
+            }
+        }
+    }
+
+    /**
+     * Unsubscribe from a message type.
+     * @param {string} messageType - The type of message to unsubscribe from.
+     * @param {MessageHandler} handler - The message handler to remove from the subscribers list.
+     */
+    async unsubscribe(messageType, handler) {
+        await this.#lock.acquireLock();
+        try {
+            if (this.#subscribers.has(messageType)) {
+                /** @type {Set<MessageHandler>} */
+                const handlers = this.#subscribers.get(messageType);
+                if (handlers.has(handler))
+                    handlers.delete(handler);
+            }
+        } finally {
+            this.#lock.releaseLock();
+        }
+    }
+
+    /**
+     * Clear all subscribers for a specific message type.
+     * @param {string} messageType - The type of message to clear subscribers for.
+     */
+    async clearSubscribers(messageType) {
+        await this.#lock.acquireLock();
+        try {
+            if (this.#subscribers.has(messageType)) {
+                /** @type {Set<MessageHandler>} */
+                const handlers = this.#subscribers.get(messageType);
+                // Clear the handlers set
+                handlers.clear();
+            }
+        } finally {
+            this.#lock.releaseLock();
+        }
+    }
+
+    /**
+     * Get the total number of subscribers across all message types.
+     * @returns {number} The total number of subscribers.
+     */
+    get subscriberCount() {
+        let count = 0;
+        for (const handlers of this.#subscribers.values()) {
+            count += handlers.length;
+        }
+        return count;
+    }
+}

package/MutexLock.d.ts

@@ -0,0 +1,24 @@
+/**
+ * A simple mutex lock implementation using a queue.
+ */
+export declare class MutexLock {
+    #locked: boolean;
+    #waitingQueue: Promise<void>[];
+    
+    /**
+     * Acquire the lock. If the lock is already held, queue the request.
+     */
+    async acquireLock(): Promise<void>;
+    /**
+     * Release the lock. If there are waiting acquisitions, pass the lock to the next in line.
+     */
+    releaseLock(): void;
+    /**
+     * Check if the lock is currently held.
+     */
+    get isLocked(): boolean;
+    /**
+     * Get the number of waiters.
+     */
+    get waiterCount(): number;
+}

package/MutexLock.js

@@ -0,0 +1,60 @@
+"use strict";
+
+/**
+ * A simple mutex lock implementation using a queue.
+ */
+export class MutexLock {
+    #locked = false;
+    #waitingQueue = [];
+
+    /**
+     * Acquire the lock. If the lock is already held, queue the request.
+     */
+    async acquireLock() {
+        // If lock is free, acquire it immediately
+        if (!this.#locked) {
+            this.#locked = true;
+            return Promise.resolve();
+        }
+
+        // Otherwise, queue this request
+        return new Promise(resolve => {
+            this.#waitingQueue.push(resolve);
+        });
+    }
+
+    /**
+     * Release the lock. If there are waiting acquisitions, pass the lock to the next in line.
+     */
+    releaseLock() {
+        if (!this.#locked && this.#waitingQueue.length === 0) {
+            throw new Error("Lock is not held.");
+        }
+
+        // If there are waiting acquisitions, pass the lock to the next one
+        if (this.#waitingQueue.length > 0) {
+            /** @type {() => void} */
+            const nextResolve = this.#waitingQueue.shift();
+            // The lock remains locked, but now the next waiter has it
+            // We don't set locked = false because it's immediately re-acquired
+            nextResolve();
+        } else {
+            // No waiters, release the lock
+            this.#locked = false;
+        }
+    }
+
+    /**
+     * Check if the lock is currently held.
+     */
+    get isLocked() {
+        return this.#locked;
+    }
+
+    /**
+     * Get the number of waiters.
+     */
+    get waiterCount() {
+        return this.#waitingQueue.length;
+    }
+}

package/QueueEventScheduler.d.ts

@@ -0,0 +1,29 @@
+import { EventArgs, EventHandler } from "./BasicEventModel";
+import { MutexLock } from "./MutexLock";
+
+/**
+ * A simple event scheduler that uses a queue and a mutex lock for thread safety.
+ */
+export declare class QueueEventScheduler {
+    #eventQueue: EventHandler[];
+    #lock: MutexLock;
+
+    /**
+     * Schedule an event to be processed.
+     * @param {EventHandler} event - The event to be processed.
+     */
+    scheduleEvent(event: EventHandler): Promise<void>;
+    /**
+     * Process all events in the queue.
+     */
+    processEvents(sender: any, e: EventArgs): Promise<void>;
+    /**
+     * Clear all pending events.
+     */
+    clearEvents(): Promise<void>;
+    /**
+     * Get the number of pending events.
+     * @returns {number} The number of pending events.
+     */
+    get pendingEventCount(): number;
+}

package/QueueEventScheduler.js

@@ -0,0 +1,71 @@
+"use strict";
+import { MutexLock } from "./MutexLock.js";
+
+/**
+ * @import { EventArgs, EventHandler } from "./BasicEventModel.js";
+ */
+
+/**
+ * A simple event scheduler that uses a queue and a mutex lock for thread safety.
+ */
+export class QueueEventScheduler {
+    #eventQueue = [];
+    #lock = new MutexLock();
+
+    constructor() {
+    }
+
+    /**
+     * Schedule an event to be processed.
+     * @param {EventHandler} event - The event to be processed.
+     */
+    async scheduleEvent(event) {
+        await this.#lock.acquireLock();
+        try {
+            this.#eventQueue.push(event);
+        } finally {
+            this.#lock.releaseLock();
+        }
+    }
+
+    /**
+     * Process all events in the queue.
+     * @param {*} sender - The sender of the event.
+     * @param {EventArgs} e - The event arguments.
+     */
+    async processEvents(sender, e) {
+        if (this.#eventQueue.length === 0) {
+            return;
+        }
+
+        await this.#lock.acquireLock();
+        try {
+            while (this.#eventQueue.length > 0) {
+                const event = this.#eventQueue.shift();
+                event?.(sender, e);
+            }
+        } finally {
+            this.#lock.releaseLock();
+        }
+    }
+
+    /**
+     * Clear all pending events.
+     */
+    async clearEvents() {
+        await this.#lock.acquireLock();
+        try {
+            this.#eventQueue = [];
+        } finally {
+            this.#lock.releaseLock();
+        }
+    }
+
+    /**
+     * Get the number of pending events.
+     * @returns {number} The number of pending events.
+     */
+    get pendingEventCount() {
+        return this.#eventQueue.length;
+    }
+}

package/README.md

@@ -0,0 +1,124 @@
+# VB.NET-Style Event Models (JavaScript/TypeScript Edition)
+
+A JavaScript/TypeScript library providing event models, message routing, and event scheduling utilities with thread safety, inspired by VB.NET's event model.
+
+NOTE: This library was written in pure TypeScript initially but underwent packaging issues, so it's now rewritten in JavaScript with TypeScript declaration files provided for type support.
+
+Install this package via NPM: `npm install vbstyle-event-models` (no other dependencies required, current version 1.0.5)
+
+## Features
+
+- **BasicEventModel**: A simple event model for registering and invoking event handlers
+- **MessageRouter**: A singleton message router for publish-subscribe pattern
+- **QueueEventScheduler**: A queue-based event scheduler with thread safety
+- **MutexLock**: A simple mutex lock implementation for thread safety
+
+## Usage
+
+### BasicEventModel
+
+```typescript
+import { BasicEventModel, EventHandler, EventArgs } from 'vbstyle-event-models';
+
+// Create an event model
+const eventModel = new BasicEventModel();
+
+// Define an event handler
+const handler: EventHandler = (sender, e) => {
+    console.log('Event triggered:', { sender, args: e });
+};
+
+// Add the handler
+eventModel.addHandler(handler);
+
+// Raise the event
+eventModel.raiseEvent('sender', ['arg1', 'arg2']);
+
+// Remove the handler
+eventModel.removeHandler(handler);
+```
+
+### MessageRouter
+
+```typescript
+import { MessageRouter } from 'vbstyle-event-models';
+
+// Get the singleton instance
+const router = MessageRouter.instance;
+
+// Subscribe to a message type
+await router.subscribe('userCreated', (user) => {
+    console.log('User created:', user);
+});
+
+// Send a message
+await router.send('userCreated', { id: 1, name: 'John' });
+
+// Unsubscribe from a message type
+await router.unsubscribe('userCreated', handler);
+
+// Clear all subscribers for a message type
+await router.clearSubscribers('userCreated');
+
+// Get total subscriber count
+const count = await router.getSubscriberCount();
+console.log('Total subscribers:', count);
+```
+
+### QueueEventScheduler
+
+```typescript
+import { QueueEventScheduler } from 'vbstyle-event-models';
+
+// Create an event scheduler
+const scheduler = new QueueEventScheduler();
+
+// Schedule events
+await scheduler.scheduleEvent(() => {
+    console.log('Event 1 executed');
+});
+
+await scheduler.scheduleEvent(() => {
+    console.log('Event 2 executed');
+});
+
+// Process all events
+await scheduler.processEvents();
+
+// Clear pending events
+await scheduler.clearEvents();
+
+// Get pending event count
+const count = scheduler.pendingEventCount;
+console.log('Pending events:', count);
+```
+
+### MutexLock
+
+```typescript
+import { MutexLock } from 'vbstyle-event-models';
+
+// Create a mutex lock
+const lock = new MutexLock();
+
+// Acquire the lock
+await lock.acquireLock();
+try {
+    // Critical section
+    console.log('Lock acquired');
+} finally {
+    // Release the lock
+    lock.releaseLock();
+    console.log('Lock released');
+}
+
+// Check if locked
+console.log('Is locked:', lock.isLocked);
+
+// Get waiter count
+console.log('Waiters:', lock.waiterCount);
+```
+
+## License
+
+[BSD 3-Clause](LICENSE)

package/index.d.ts

@@ -0,0 +1,4 @@
+export * from './BasicEventModel';
+export * from './MessageRouter';
+export * from './QueueEventScheduler';
+export * from './MutexLock';

package/index.js

@@ -0,0 +1,4 @@
+export * from './BasicEventModel.js';
+export * from './MessageRouter.js';
+export * from './QueueEventScheduler.js';
+export * from './MutexLock.js';

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "vbstyle-event-models",
+  "version": "1.0.5",
+  "description": "A thread-safe JS/TS library, providing event models, message routing, and event scheduling utilities.",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "scripts": {},
+  "keywords": [
+    "events",
+    "event-model",
+    "message-router",
+    "event-scheduler",
+    "mutex",
+    "mutex-lock",
+    "javascript"
+  ],
+  "author": "pac-dessert1436",
+  "license": "BSD-3-Clause",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Pac-Dessert1436/vbstyle-event-models.git"
+  },
+  "homepage": "https://github.com/Pac-Dessert1436/vbstyle-event-models",
+  "dependencies": {}
+}