🌊 LogicTide

Channel the tide of logic itself—construct modular intent, replay echoes of logic, and architect environments that remember.

💡 Description

Command the flow of logic with legendary clarity and precision. Trigger, replay, and orchestrate behaviors across infinite namespaces with modular power and graceful structure. Define dynamic behaviors, emit real-time signals, and preserve intent across sessions, devices, and environments.

Switch effortlessly between development, staging, production—or any custom environment—and execute scoped logic tailored to context. Embed TTL-based expiration, snapshot recovery, and namespace isolation to enforce resilience at scale. Streamline adaptive workflows, synchronize distributed systems, and sculpt intelligent decision paths with confidence. Orchestrate logic itself—rewind, adapt, and execute with legendary precision across environments, time, and structure.

🚀 Features

• ⚡ Scoped Logic Execution — Run logic conditionally based on the current environment (development, staging, production, etc).
• 🌐 Namespace Support — Isolate and manage logic across distinct namespaces.
• 🔁 Event Replay — Replay past events programmatically for debugging, analytics, or reactivity.
• 🧠 Snapshot + Restore — Capture and restore in-memory logic history anytime.
• 🗂️ TTL Expiration — Set lifespans for stored events to keep logic lean and relevant.
• 📦 Persistence — Use LevelDB (Node) or IndexedDB (Browser) to store and retrieve logic history.
• 📂 Import / Export — Easily back up and load event history via JSON files or buffers.
• 🧩 Modular API — Override behaviors, plug into different runtimes, and remain fully environment-agnostic.

📐 Specifications

Modes & Environments

| Feature | Description | |---------------------|-----------------------------------------------------------| | setMode(mode) | Define the active logic environment (dev, prod, etc) | | runSync(scope, ...) | Execute logic defined for the current mode (sync) | | run(scope, ...) | Execute logic defined for the current mode (async / sync) | | defineLogic(...) | Attach logic to a specific mode and scope |

Namespaces

| Feature | Description | |---------------------------|-----------------------------------------------------------| | setNamespace(ns) | Switch to a new logical space for isolating events | | getNamespace() | Retrieve the current active namespace | | listNamespaces() | List all known namespaces stored in persistence | | deleteNamespace(ns) | Remove all events under a namespace | | renameNamespace(from, to) | Rename a namespace (preserves events) | | copyNamespace(from, to) | Duplicate a namespace and its events |

Event Management

| Feature | Description | |----------------------------|----------------------------------------------------------| | emit(event, ...args) | Trigger a logic event | | on(event, cb) | Attach listener for a specific or wildcard event | | off(event, cb) | Remove a listener | | replayEvents(...) | Replay historical events with filtering & options | | setHistorySize(n) | Define max number of events kept in memory | | snapshot() | Get a deep copy of current in-memory event state | | restore(snapshot, opts) | Restore events from a snapshot |

Persistence

| Feature | Description | |-----------------------------------|---------------------------------------------------------| | enablePersistence(opts) | Enable LevelDB/IndexedDB-backed persistence | | clearPersistence() | Delete all stored events in the current namespace | | exportEventHistory({ format }) | Export as JSON array or UTF-8 buffer | | exportToFile(path) | Save all logic events to file | | importFromFile(path, opts) | Load event history from file | | purgeExpiredEvents({ namespace }) | Clean TTL-expired events across one or all namespaces |

🧪 Example (NodeJS)

const LogicTide = require("@trap_stevo/logictide");

await LogicTide.enablePersistence({
      path : "./logic-db",
      ttl : 1000 * 60 * 60,
      namespace : "projectX"
});

LogicTide.setMode("staging");

LogicTide.defineLogic("paymentHandler", "production", async (id) => {
      return { token : id, secure : true };
});

LogicTide.defineLogic("paymentHandler", "staging", async () => {
      return { token : "test-token", secure : false };
});

const result = await LogicTide.run("paymentHandler", "tok_abc");
console.log(result); // { token: "test-token", secure: false }

await LogicTide.emit("user.login", { userID : "ABC" });
await LogicTide.replayEvents("user.*");

await LogicTide.exportToFile({ filename : "backup.json" });

🧪 Example (Browser)

import { LogicTide } from "@trap_stevo/logicTide";

await LogicTide.enablePersistence({
      dbName : "LogicTideDB",
      ttl : 1000 * 60 * 60,
      namespace : "ui-events"
});

LogicTide.setMode("staging");

LogicTide.defineLogic("paymentHandler", "production", (id) => {
      return { token : id, secure : true };
});

LogicTide.defineLogic("paymentHandler", "staging", () => {
      return { token : "test-token", secure : false };
});

const result = await LogicTide.run("paymentHandler", "tok_abc");
console.log(result); // { token: "test-token", secure: false }

await LogicTide.emit("user.login", { userID : "ABC" });
await LogicTide.replayEvents("user.*");

// Trigger file export in browser
await LogicTide.exportToFile({ filename : "backup.json" });

// To import from file input element
const input = document.querySelector("#importFile");
input.addEventListener("change", async (e) => {
      const file = e.target.files[0];
      await LogicTide.importFromFile(file, { persist: true });
});

📦 Installation

npm install @trap_stevo/logictide

Supports:

• Node.js
• Plain Javascript

🧭 Roadmap

• [ ] Auto-purge expired events on interval
• [ ] WebSocket broadcast support
• [ ] Logic chaining and reactive transforms
• [ ] Real-time visual debugger

🛡 License

See license in LICENSE.md