# 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)