@bloqz/relay 1.0.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 shovelmn12
+
+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.

package/README.md

@@ -0,0 +1,88 @@
+# @bloqz/relay
+
+The `@bloqz/relay` package provides a lightweight, RxJS-powered event bus for enabling communication between different parts of an application. It uses a flexible subscription model that supports both simple string patterns and advanced predicate functions, making it a powerful solution for decoupled architectures.
+
+## Core Concepts
+
+- **Relay**: An event bus that allows for emitting and listening to events.
+- **Topics**: Named channels for events (e.g., 'user', 'cart'), allowing for targeted communication.
+- **Events**: The data payload associated with a topic, which must have a `type` property.
+- **Pattern Matching**: A simple yet powerful syntax for subscribing to events based on their topic and type.
+
+## Installation
+
+This package is part of the Bloqz monorepo. To use it, add it as a dependency in your `package.json`:
+
+```json
+"dependencies": {
+  "@bloqz/relay": "1.0.0"
+}
+```
+
+## Usage
+
+### Creating a Relay
+
+The primary export of this package is the `createRelay` function.
+
+```typescript
+import { createRelay } from '@bloqz/relay';
+
+// Create a new relay instance
+const appRelay = createRelay();
+```
+
+### Emitting Events
+
+You can emit an event to a specific topic using the `emit` method. The event payload must be an object with a `type` property.
+
+```typescript
+appRelay.emit('user', { type: 'login', userId: '123' });
+appRelay.emit('notifications', { type: 'new', message: 'Welcome!' });
+```
+
+### Listening with String Patterns
+
+You can listen for events using a string pattern with the `on` method. This is the most common way to subscribe. The method returns an `unsubscribe` function.
+
+```typescript
+// Listen for login and logout events on the 'user' topic
+const unsubscribe = appRelay.on('user.{login|logout}', (topic, event) => {
+  console.log(`Received event '${event.type}' on topic '${topic}'`);
+});
+
+// To stop listening
+unsubscribe();
+```
+
+### Listening with a Predicate Function
+
+For more complex scenarios, you can use a predicate function to filter events. The predicate receives the topic and event and should return `true` if the handler should be executed.
+
+```typescript
+const unsubscribe = appRelay.on((topic, event) => {
+  return topic === 'user' && event.type === 'login';
+}, (topic, event) => {
+  console.log('User logged in:', event);
+});
+```
+
+### Pattern Matching Syntax
+
+The pattern matching syntax provides a concise way to subscribe to events:
+
+| Pattern                 | Description                                           |
+| ----------------------- | ----------------------------------------------------- |
+| `*`                     | Matches any topic and any event type.                 |
+| `user`                  | Matches any event on the `user` topic.                |
+| `user|cart`             | Matches any event on the `user` or `cart` topics.     |
+| `*.login`               | Matches `login` events on any topic.                  |
+| `user.{login|logout}`   | Matches `login` or `logout` events on the `user` topic. |
+
+### Disposing the Relay
+
+When a relay is no longer needed, you can dispose of it to complete the underlying event stream and unsubscribe all listeners.
+
+```typescript
+appRelay.dispose();
+```

package/dist/create.d.ts

@@ -0,0 +1,6 @@
+import { Relay } from "./index.js";
+/**
+ * Factory function to create a new Relay instance using RxJS.
+ * @returns A new Relay instance.
+ */
+export declare function createRelay(): Relay;

package/dist/create.js

@@ -0,0 +1,83 @@
+import { Subject } from "rxjs";
+import { filter } from "rxjs/operators";
+/**
+ * Factory function to create a new Relay instance using RxJS.
+ * @returns A new Relay instance.
+ */
+export function createRelay() {
+    // The single, central stream for all events.
+    const eventStream$ = new Subject();
+    /**
+     * Parses a pattern and checks if it matches a given topic and event.
+     * (This helper function remains the same)
+     */
+    const matchesPattern = (pattern, topic, event) => {
+        if (pattern === "*")
+            return true;
+        // Helper to split by '|' but ignore it inside '{}'
+        const splitSubPatterns = (p) => {
+            const patterns = [];
+            let lastSplit = 0;
+            let braceDepth = 0;
+            for (let i = 0; i < p.length; i++) {
+                if (p[i] === "{")
+                    braceDepth++;
+                else if (p[i] === "}")
+                    braceDepth--;
+                else if (p[i] === "|" && braceDepth === 0) {
+                    patterns.push(p.substring(lastSplit, i));
+                    lastSplit = i + 1;
+                }
+            }
+            patterns.push(p.substring(lastSplit));
+            return patterns;
+        };
+        const subPatterns = splitSubPatterns(pattern);
+        return subPatterns.some((subPattern) => {
+            const [topicPattern, typePattern] = subPattern.split(".");
+            if (topicPattern !== "*" && topicPattern !== topic)
+                return false;
+            if (!typePattern)
+                return true;
+            if (typePattern === "*")
+                return true;
+            if (typePattern.startsWith("{") && typePattern.endsWith("}")) {
+                const types = typePattern.slice(1, -1).split("|");
+                return types.includes(event.type);
+            }
+            return typePattern === event.type;
+        });
+    };
+    return {
+        emit(topic, event) {
+            // Simply push the new event into the stream.
+            eventStream$.next({ topic, event });
+        },
+        on(patternOrPredicate, callback) {
+            // Create the filter predicate once, before subscribing.
+            const filterFn = ({ topic, event, }) => {
+                if (typeof patternOrPredicate === "string") {
+                    return matchesPattern(patternOrPredicate, topic, event);
+                }
+                // For predicates, just execute them.
+                return patternOrPredicate(topic, event);
+            };
+            // Create a new subscription to the main stream.
+            const subscription = eventStream$
+                .pipe(
+            // Use the pre-built filter function. This is more efficient.
+            filter(filterFn))
+                .subscribe(({ topic, event }) => {
+                // When an event passes the filter, call the user's handler.
+                callback(topic, event);
+            });
+            // Return a function that tears down this specific subscription.
+            return () => subscription.unsubscribe();
+        },
+        dispose() {
+            // Complete the subject, which automatically unsubscribes all listeners.
+            eventStream$.complete();
+        },
+    };
+}
+//# sourceMappingURL=create.js.map

package/dist/create.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create.js","sourceRoot":"","sources":["../src/create.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./models.js";
+export * from "./create.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+export * from "./models.js";
+export * from "./create.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC"}

package/dist/models.d.ts

@@ -0,0 +1,80 @@
+/**
+ * The standard shape for any event payload passed through the relay.
+ * It must include a `type` string to allow for pattern-based filtering.
+ *
+ * @example
+ * const loginEvent: RelayEvent = { type: 'login', userId: '123' };
+ * const logoutEvent: RelayEvent = { type: 'logout' };
+ */
+export type RelayEvent = {
+    readonly type: string;
+};
+/**
+ * A handler function that receives the topic and event for a matched subscription.
+ *
+ * @param topic The topic the event was emitted on (e.g., 'user', 'cart').
+ * @param event The event payload.
+ */
+export type RelayHandler = (topic: string, event: RelayEvent) => void;
+/**
+ * A predicate function used for advanced event filtering. It receives the full
+ * event context and returns `true` if the handler should be called.
+ *
+ * @param topic The topic of the event.
+ * @param event The event payload.
+ * @returns `true` if the subscription handler should be invoked.
+ */
+export type RelayPredicate = (topic: string, event: RelayEvent) => boolean;
+/**
+ * A non-generic, RxJS-powered event bus that supports pattern-based
+ * and predicate-based subscriptions. It serves as a central hub for
+ * cross-cutting communication, such as between Blocs.
+ */
+export interface Relay {
+    /**
+     * Emits an event to a specific topic. All active subscriptions will be
+     * evaluated against the event, and matching handlers will be invoked.
+     *
+     * @param topic The topic to emit to (e.g., 'user', 'cart').
+     * @param event The event payload, which MUST include a `type` property
+     * (e.g., `{ type: 'login', userId: '123' }`).
+     */
+    emit(topic: string, event: RelayEvent): void;
+    /**
+     * Disposes of the relay, completing its internal event stream and
+     * unsubscribing all listeners. After disposal, the relay can no longer
+     * be used.
+     */
+    dispose(): void;
+    /**
+     * Registers a callback for events matching a specific string pattern.
+     * The pattern allows for filtering by topic and event type.
+     *
+     * @param pattern A string pattern to match against topics and event types.
+     *   - `*`: Wildcard, matches any topic and event.
+     *   - `topic.*`: Matches any event on a specific topic.
+     *   - `*.{type1|type2}`: Matches specific event types on any topic.
+     *   - `topic.{type1|type2}`: Matches specific event types on a specific topic.
+     *   - `topic1|topic2`: Matches any event on a list of topics.
+     * @param callback The callback to execute when a matching event is emitted.
+     * @returns A function to unregister the callback and unsubscribe.
+     *
+     * @example
+     * on('user.{login|logout}', (topic, event) => { ... });
+     * on('cart', (topic, event) => { ... }); // same as cart.*
+     * on('*', (topic, event) => { ... });
+     */
+    on(pattern: string, callback: RelayHandler): () => void;
+    /**
+     * Registers a callback for events that pass a custom predicate function.
+     * This allows for more complex filtering logic than string patterns.
+     *
+     * @param predicate A function that returns `true` for events to listen to.
+     * @param callback The callback to execute for events that pass the predicate.
+     * @returns A function to unregister the callback and unsubscribe.
+     *
+     * @example
+     * on((topic, event) => topic === 'user' && event.type === 'login', callback);
+     */
+    on(predicate: RelayPredicate, callback: RelayHandler): () => void;
+}

package/dist/models.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=models.js.map

package/dist/models.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"models.js","sourceRoot":"","sources":["../src/models.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@bloqz/relay",
+  "version": "1.0.3",
+  "description": "A package for enabling inter-bloc communication using an event relay system.",
+  "keywords": [
+    "bloc",
+    "bloqz",
+    "state management",
+    "functional",
+    "rxjs",
+    "typescript",
+    "relay",
+    "event bus",
+    "events"
+  ],
+  "homepage": "https://github.com/shovelmn12/bloqz#readme",
+  "bugs": {
+    "url": "https://github.com/shovelmn12/bloqz/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/shovelmn12/bloqz.git"
+  },
+  "license": "MIT",
+  "author": "Shovel Maman",
+  "type": "module",
+  "exports": {
+    "main": "./dist/index.js",
+    "import": "./dist/index.js",
+    "types": "./dist/index.d.ts"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "rxjs": "^7.8.2"
+  },
+  "peerDependencies": {
+    "@bloqz/core": "1.0.3"
+  },
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "npm run clean && tsc",
+    "test": "vitest --run"
+  }
+}