📡 @trap_stevo/ucr

The ultimate event routing solution for dynamic, filter-driven, TTL-enforced communication.
Build intelligent, reactive communication layers across clients or processes — with deep filter matching, TTL-based cleanup, customizable operators, and smart broadcast control.

🧾 UCR?

UCR (Universal Communication Router) powers dynamic client coordination with a lightweight, framework-agnostic engine for managing connections and routing events using expressive, JSON-like filters.

Use cases:

• 🧪 Real-time dashboards — deliver updates only to users matching roles or state
• 📟 Multiplayer systems — notify players or devices that meet specific conditions
• 🧠 AI routing layers — direct tasks to models or workers based on context
• 🕹️ IoT/twin networks — route events using location, status, or group metadata

🔌 Networking Perspective

🧠 UCR filters packets at the source — before they leave your system.
Instead of broadcasting to all connected clients, it emits only to those matching dynamic filter rules, avoiding unnecessary traffic by design.

This mirrors techniques like:

• Interest Management in multiplayer games
• Selective Event Routing in real-time systems
• Application-layer Packet Filtering for event-driven architectures

UCR routes who receives what — plug into any transport and drive precise, rule-based event delivery.

🚀 Features

• 🧠 Deep Filter Matching – Match nested fields with advanced logic and operators
• ⌛ TTL Management – Auto-disconnect inactive clients based on time-to-live
• 🧩 Custom Operators – Extend filter logic with your own rule definitions
• 📣 Conditional Broadcasting – Send to clients matching flexible filters or predicates
• 🧭 Filter Description Helper – Generate human-readable summaries of filter objects
• 🧼 Safe Socket Cleanup – Auto-handle socket disconnects to prevent memory leaks
• 🧰 Composable Filters – Use UCR.filter() builder for reusable matching logic

⚙️ Client Management

| Method | Description | |-------------------------------|---------------------------------------------------------------| | registerClient(clientID, ttl, data) | Register or renew a client with optional TTL and metadata | | updateClientData(clientID, updates) | Merge updates into the client's existing metadata | | disconnectClient(clientID) | Manually disconnect and remove a client | | handleSocketDisconnect(clientID) | Alias for safe cleanup when socket closes or crashes |

🔍 Broadcasting & Filtering

| Method | Description | |-------------------------------------|-------------------------------------------------------------------| | broadcastWhere(filter, event, payload) | Emit to all clients matching a filter or predicate function | | matchFilter(filter) | Compile a reusable filter function based on operators | | registerOperator(name, fn) | Define your own comparison operator (e.g., $mod, $startswith) |

🧮 Built-In Operators

| Operator | Description | |------------|----------------------------------------------| | $eq | Equals | | $ne | Not equal | | $gt | Greater than | | $lt | Less than | | $gte | Greater than or equal | | $lte | Less than or equal | | $in | Value is in list | | $nin | Value is NOT in list | | $exists | Key exists (or not) | | $test | Custom function test |

🧠 Filter Description

| Method | Description | |----------------------------|-----------------------------------------------------| | UCR.describeFilter(filter) | Converts a filter into a human-readable sentence |

📦 Installation

npm install @trap_stevo/ucr

const filter = UCR
     .filter("level").greaterThan(50)
     .and("faction").equals("red");

console.log(UCR.describeFilter(filter)); // --> Level greater than 50 and faction equal to "red"

🧰 Filter Builder (Advanced)

| Method | Description | |------------------------|----------------------------------------------| | UCR.filter(field) | Returns a UCRFilterManager for chaining |

const filter = UCR.filter("status").equals("online").and("region").in(["US", "EU"]).build();

🛠️ Constructor

const { UCR } = require("@trap_stevo/ucr");

const ucr = new UCR((clientID, event, payload) =>  {
     // Your send logic here (e.g., WebSocket, socket.io, IoTide, etc.)
});

💡 Example Usage

Registering a client

ucr.registerClient("client-abc", 30000, {
     role : "admin",
     region : "US"
});

Updating metadata

ucr.updateClientData("client-abc", {
     online : true
});

Broadcasting

ucr.broadcastWhere({ role : "admin" }, "admin-alert", { message : "System going down" });

Using complex filters

ucr.broadcastWhere({
     $or : [
          { "region" : { $eq : "US" } },
          { "status" : { $eq : "critical" } }
     ]
}, "alert", { severity : "high" });

🔌 Custom Operators

ucr.registerOperator("$startswith", (a, b) => typeof a === "string" && a.startsWith(b));

ucr.broadcastWhere({
     username : { $startswith : "admin_" }
}, "restricted-notice", {});

♻️ TTL Auto-Disconnect

Clients are auto-disconnected after their TTL (default 30000ms) unless re-registered:

ucr.registerClient("client-x", 10000); // disconnects in 10 seconds

You can manually disconnect or hook into socket closures:

ucr.disconnectClient("client-x");

// or when a socket disconnects
socket.on("close", () => ucr.handleSocketDisconnect("client-x"));

📜 License

See LICENSE.md

🔁 Route Smart. Route Right.

UCR enables event-driven, resilient, and context-aware communication across distributed systems. With rich filter support and deep client control, you gain a powerful foundation for your next-gen messaging or coordination layer.