@trap_stevo/ucr/README.md

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 broa

# 📡 @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

```bash
npm install @trap_stevo/ucr
```

---

```js
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   |

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

---

## 🛠️ Constructor

```js
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

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

### Updating metadata

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

### Broadcasting

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

### Using complex filters

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

---

## 🔌 Custom Operators

```js
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:

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

You can manually disconnect or hook into socket closures:

```js
ucr.disconnectClient("client-x");

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

---

## 📜 License

See [LICENSE.md](./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.