@trap_stevo/timelyst/README.md

Forging the next evolution in intelligent data control, this powerhouse solution enables unparalleled management of dynamic lists across any application domain. Blacklist enforcement, whitelist access, behavioral tagging, expiration policies, and real-tim

# Timelyst

Timelyst delivers high-performance, fully extensible dynamic list management for Node.js. Designed for scale and flexibility, it handles advanced access control, behavioral tagging, TTL-driven data expiration, intelligent key indexing, and seamless transitions between in-memory speed and persistent storage durability.

Ideal for blacklist and whitelist enforcement, tagged registries, access flags, content filters, or any scenario requiring intelligent data organization and time-sensitive lifecycle management.

## 🚀 Features

- Dynamic list creation with optional sharding
- In-memory and persistent storage support
- TTL expiration with auto-sweep and background cleanup
- Search indexing and fuzzy key similarity matching
- Tag-based filtering, priority levels, and category grouping
- Batch insertion with optimized shard-aware writes
- Advanced filters, pagination, and sorting
- Auto cleanup with human-readable interval support

## 📦 Installation

```bash
npm install timelyst
```

> Requires Node.js v14+

## ⚡ Quick Start

```js
const Timelyst = require("@trap_stevo/timelyst");

const manager = new Timelyst({
     enableOfflineStorage : true,
     autoCleanupInterval : "10s",
     basePath : "./timelyst_db"
});

(async () => {
     await manager.createList("bannedUsers", { shardCount : 2 });

     await manager.addToList("bannedUsers", "user123", {
          tags      : ["bot", "spam"],
          priority  : 10,
          category  : "abuse",
          expiresIn : "1h"
     });

     const isBanned = await manager.inList("bannedUsers", "user123");
     console.log("Is user123 banned?", isBanned);

     const results = await manager.filterList("bannedUsers", {
          minPriority : 5,
          sortBy      : "priority",
          sortOrder   : "desc"
     });

     console.log("Filtered:", results);
})();
```

## 🔎 Entry Lookup

```js
const entry = await manager.getEntryByKey("user123");
console.log(entry);

const matches = manager.findSimilarKeys("adminUser", {
     threshold: 0.6,
     labels: ["strong", "medium"],
     limit: 10
});

console.log(matches);
```

---

## License

See license in [LICENSE.md](./LICENSE.md)