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

npm install timelyst

Requires Node.js v14+

⚡ Quick Start

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

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