tiny-server-state 0.1.2

package/README.md

@@ -0,0 +1,269 @@
+# 🧠 tiny-server-state
+
+A **lightweight, reactive in-memory state engine** for Node.js servers. It offers simple key-value storage with optional TTL (Time-To-Live), real-time subscriptions, and a React-like API for easier state management.
+
+> Ideal for handling temporary, shared, or cacheable state without a database.
+
+---
+
+## 🚀 Features
+
+- ✅ **Simple and minimal** state engine
+- 🕓 **TTL-based expiration** (auto-deletes expired keys)
+- 🧠 **React-style `useState`** for intuitive state access
+- 📡 **Subscriptions** for real-time updates
+- 🔁 **Automatic Garbage Collection (GC)**
+- 🛠️ **No external dependencies**
+- 🔒 **TypeScript support** out of the box
+
+---
+
+## 📦 Installation
+
+```bash
+npm install tiny-server-state
+```
+
+## 🚀 Quick Start
+
+```typescript
+import { createServerState } from "tiny-server-state";
+
+// Create a new state store instance
+const store = createServerState();
+
+// Use React-like state management
+const [count, setCount] = store.useState("count", 0);
+console.log(count); // 0
+
+// Update state with a new value
+setCount(5);
+
+// Or use a function to update based on previous value
+setCount(prev => prev + 1);
+```
+
+## 📚 API Reference
+
+### Creating a Store
+
+```typescript
+const store = createServerState(sweepInterval?: number);
+```
+
+- `sweepInterval`: Optional interval (in ms) for garbage collection (default: 60000)
+
+### Core Methods
+
+#### `get<T>(key: string): T | undefined`
+Retrieve a value from the store.
+
+```typescript
+const value = store.get("myKey");
+```
+
+#### `set<T>(key: string, value: T, options?: StateOptions): void`
+Set a value in the store.
+
+```typescript
+// Simple set
+store.set("myKey", "myValue");
+
+// Set with TTL (expires after 5 seconds)
+store.set("temporaryKey", "value", { ttl: 5000 });
+```
+
+#### `useState<T>(key: string, initial: T | (() => T), options?: StateOptions)`
+React-style state management.
+
+```typescript
+// Basic usage
+const [value, setValue] = store.useState("key", "initial");
+
+// With initializer function
+const [user, setUser] = store.useState("user", () => ({ name: "John" }));
+
+// With TTL
+const [token, setToken] = store.useState("token", "abc123", { ttl: 3600000 }); // 1 hour
+
+// Update examples
+setValue("new value");              // Direct update
+setValue(prev => prev + " updated"); // Function update
+```
+
+#### `subscribe<T>(key: string, callback: (value: T) => void)`
+Subscribe to state changes.
+
+```typescript
+// Subscribe to changes
+const unsubscribe = store.subscribe("user", (newValue) => {
+  console.log("User updated:", newValue);
+});
+
+// Later: cleanup subscription
+unsubscribe();
+```
+
+#### `useEffect(effect: () => void | (() => void), deps?: string[], effectId?: string)`
+React-style effect management for side effects when state changes.
+
+```typescript
+// Run effect when dependencies change
+const cleanup = store.useEffect(
+  () => {
+    console.log("User or settings changed");
+    
+    // Optional cleanup function
+    return () => {
+      console.log("Effect cleanup");
+    };
+  },
+  ["user", "settings"] // Dependencies
+);
+
+// Run effect only once (no dependencies)
+const onceCleanup = store.useEffect(() => {
+  console.log("This runs once");
+});
+
+// Later: cleanup effect
+cleanup();
+```
+
+#### `cleanupAllEffects(): void`
+Cleanup all active effects (useful for testing or shutdown).
+
+```typescript
+// Cleanup all effects at once
+store.cleanupAllEffects();
+```
+
+## 🎯 Use Cases
+
+### 1. Session Management
+```typescript
+// Store session data with automatic expiration
+const [session, setSession] = store.useState("session", null, {
+  ttl: 30 * 60 * 1000 // 30 minutes
+});
+
+// Update session
+setSession({ userId: "123", lastActive: Date.now() });
+```
+
+### 2. Caching
+```typescript
+// Cache expensive operation results
+async function getCachedData(id: string) {
+  const [data, setData] = store.useState(`cache:${id}`, null, {
+    ttl: 5 * 60 * 1000 // 5 minutes
+  });
+  
+  if (!data) {
+    const newData = await fetchExpensiveData(id);
+    setData(newData);
+    return newData;
+  }
+  
+  return data;
+}
+```
+
+### 3. Real-time Updates and Side Effects
+```typescript
+// Broadcast changes to all subscribers
+const [status, setStatus] = store.useState("systemStatus", "operational");
+const [metrics, setMetrics] = store.useState("metrics", { cpu: 0, memory: 0 });
+
+// React to status and metrics changes
+store.useEffect(() => {
+  const currentMetrics = store.get("metrics");
+  const currentStatus = store.get("systemStatus");
+  
+  // Notify admins when system is stressed
+  if (currentMetrics.cpu > 90 || currentMetrics.memory > 90) {
+    notifyAdmins(`High resource usage detected! CPU: ${currentMetrics.cpu}%, Memory: ${currentMetrics.memory}%`);
+    setStatus("stressed");
+  }
+  
+  // Log all status changes
+  console.log(`System status: ${currentStatus}`);
+  
+  // Cleanup function (runs before next effect or on cleanup)
+  return () => {
+    console.log(`Previous status: ${currentStatus}`);
+  };
+}, ["systemStatus", "metrics"]);
+
+// Update status
+setStatus("maintenance");
+
+// Update metrics
+setMetrics({ cpu: 95, memory: 85 }); // This will trigger the effect and change status to "stressed"
+```
+
+## 🔧 Configuration
+
+### StateOptions Interface
+
+```typescript
+interface StateOptions {
+  ttl?: number; // Time-to-live in milliseconds
+}
+```
+
+### Garbage Collection
+
+The store automatically removes expired entries at regular intervals. You can configure the sweep interval when creating the store:
+
+```typescript
+// Custom sweep interval (e.g., every 5 minutes)
+const store = createServerState(5 * 60 * 1000);
+```
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## 📄 License
+
+MIT License - feel free to use this in your own projects.
+
+---
+
+## 🔍 TypeScript Support
+
+This package includes TypeScript definitions out of the box. You'll get full type safety and autocompletion in your TypeScript projects.
+
+```typescript
+// Type-safe state management
+const [user, setUser] = store.useState<{
+  id: string;
+  name: string;
+  age: number;
+}>("user", {
+  id: "1",
+  name: "John",
+  age: 30
+});
+
+// TypeScript will ensure type safety
+setUser(prev => ({
+  ...prev,
+  age: prev.age + 1
+}));
+```
+
+## ⚡ Performance Considerations
+
+- The store uses an in-memory Map, so be mindful of memory usage when storing large objects
+- TTL and garbage collection help manage memory automatically
+- Consider using shorter TTLs for frequently changing data
+- For large-scale applications, consider using a proper database instead
+
+## 🔐 Security Notes
+
+- Data is stored in memory and will be lost when the server restarts
+- Don't store sensitive information without proper encryption
+- Be cautious with TTL values to prevent memory leaks
+- Consider implementing rate limiting for state updates if exposed to client requests

package/dist/Store.d.ts

@@ -0,0 +1,46 @@
+import { EventEmitter } from "node:events";
+export interface StateOptions {
+    ttl?: number;
+}
+export declare class ServerState {
+    private sweepEvery;
+    private cache;
+    private events;
+    private effects;
+    constructor(sweepEvery?: number);
+    /** Internal GC */
+    private sweep;
+    /** Get value (or undefined if missing / expired) */
+    get<T>(key: string): T | undefined;
+    /** Set value + optional TTL */
+    set<T>(key: string, value: T, opts?: StateOptions): void;
+    /**
+     * React-like helper.
+     * ```ts
+     * const [count, setCount] = store.useState("count", 0, { ttl: 30_000 });
+     * ```
+     */
+    useState<T>(key: string, initial: T | (() => T), opts?: StateOptions): [T, (v: T | ((prev: T) => T), o?: StateOptions) => void];
+    /** Subscribe; returns an unsubscribe fn */
+    subscribe<T>(key: string, cb: (v: T) => void): () => EventEmitter<[never]>;
+    /**
+     * React-like useEffect helper.
+     * Runs effect when dependencies change, supports cleanup.
+     * ```ts
+     * // Run effect when 'user' or 'settings' change
+     * const cleanup = store.useEffect(
+     *   () => {
+     *     console.log('User or settings changed');
+     *     return () => console.log('Cleanup');
+     *   },
+     *   ['user', 'settings']
+     * );
+     * ```
+     */
+    useEffect(effect: () => void | (() => void), deps?: string[], effectId?: string): () => void;
+    /**
+     * Cleanup all effects (useful for testing or shutdown)
+     */
+    cleanupAllEffects(): void;
+}
+export declare const createServerState: (sweep?: number) => ServerState;

package/dist/index.cjs

@@ -0,0 +1,145 @@
+'use strict';
+
+var node_events = require('node:events');
+
+// [tiny-server-state] in-memory state engine
+class ServerState {
+    constructor(sweepEvery = 60000 /* 1 min */) {
+        this.sweepEvery = sweepEvery;
+        this.cache = new Map();
+        this.events = new node_events.EventEmitter();
+        this.effects = new Map(); // Track effect cleanup functions
+        setInterval(() => this.sweep(), sweepEvery).unref();
+    }
+    // ───────────────────────── core helpers ─────────────────────────
+    /** Internal GC */
+    sweep() {
+        const now = Date.now();
+        for (const [k, v] of this.cache)
+            if (v.expiresAt && v.expiresAt <= now)
+                this.cache.delete(k);
+    }
+    /** Get value (or undefined if missing / expired) */
+    get(key) {
+        const hit = this.cache.get(key);
+        if (!hit)
+            return undefined;
+        if (hit.expiresAt && hit.expiresAt <= Date.now()) {
+            this.cache.delete(key);
+            return undefined;
+        }
+        return hit.value;
+    }
+    /** Set value + optional TTL */
+    set(key, value, opts = {}) {
+        const expiresAt = opts.ttl ? Date.now() + opts.ttl : undefined;
+        this.cache.set(key, { value, expiresAt });
+        this.events.emit(key, value); // notify subscribers
+    }
+    // ───────────────────── React-flavoured sugar ─────────────────────
+    /**
+     * React-like helper.
+     * ```ts
+     * const [count, setCount] = store.useState("count", 0, { ttl: 30_000 });
+     * ```
+     */
+    useState(key, initial, opts = {}) {
+        let current = this.get(key);
+        if (current === undefined) {
+            current = typeof initial === "function" ? initial() : initial;
+            this.set(key, current, opts);
+        }
+        const setter = (v, override = {}) => {
+            const prev = this.get(key);
+            const next = typeof v === "function" ? v(prev) : v;
+            this.set(key, next, { ...opts, ...override });
+        };
+        return [current, setter];
+    }
+    /** Subscribe; returns an unsubscribe fn */
+    subscribe(key, cb) {
+        this.events.on(key, cb);
+        return () => this.events.off(key, cb);
+    }
+    /**
+     * React-like useEffect helper.
+     * Runs effect when dependencies change, supports cleanup.
+     * ```ts
+     * // Run effect when 'user' or 'settings' change
+     * const cleanup = store.useEffect(
+     *   () => {
+     *     console.log('User or settings changed');
+     *     return () => console.log('Cleanup');
+     *   },
+     *   ['user', 'settings']
+     * );
+     * ```
+     */
+    useEffect(effect, deps = [], effectId) {
+        const id = effectId || `effect_${Date.now()}_${Math.random()}`;
+        // Cleanup previous effect if it exists
+        const existingCleanup = this.effects.get(id);
+        if (existingCleanup) {
+            existingCleanup();
+            this.effects.delete(id);
+        }
+        let cleanup;
+        const unsubscribers = [];
+        // Run effect initially
+        const runEffect = () => {
+            // Cleanup previous run
+            if (cleanup)
+                cleanup();
+            // Run the effect
+            const result = effect();
+            cleanup = typeof result === 'function' ? result : undefined;
+        };
+        // If no dependencies, run once and return cleanup
+        if (deps.length === 0) {
+            runEffect();
+            const effectCleanup = () => {
+                if (cleanup)
+                    cleanup();
+                this.effects.delete(id);
+            };
+            this.effects.set(id, effectCleanup);
+            return effectCleanup;
+        }
+        // Subscribe to all dependencies
+        deps.forEach(dep => {
+            const unsub = this.subscribe(dep, () => {
+                runEffect();
+            });
+            unsubscribers.push(unsub);
+        });
+        // Run effect initially
+        runEffect();
+        // Return cleanup function
+        const effectCleanup = () => {
+            // Cleanup effect
+            if (cleanup)
+                cleanup();
+            // Unsubscribe from all dependencies
+            unsubscribers.forEach(unsub => unsub());
+            // Remove from effects map
+            this.effects.delete(id);
+        };
+        this.effects.set(id, effectCleanup);
+        return effectCleanup;
+    }
+    /**
+     * Cleanup all effects (useful for testing or shutdown)
+     */
+    cleanupAllEffects() {
+        for (const cleanup of this.effects.values()) {
+            cleanup();
+        }
+        this.effects.clear();
+    }
+}
+// factory (so callers don’t import the class directly)
+const createServerState = (sweep) => new ServerState(sweep);
+
+exports.ServerState = ServerState;
+exports.createServerState = createServerState;
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","sources":["../src/Store.ts"],"sourcesContent":["// [tiny-server-state] in-memory state engine\nimport { EventEmitter } from \"node:events\";\n\nexport interface StateOptions { ttl?: number /* ms */; }\n\ninterface Entry<T = unknown> {\n  value: T;\n  /** epoch in ms when the value dies */\n  expiresAt?: number;\n}\n\nexport class ServerState {\n  private cache = new Map<string, Entry>();\n  private events = new EventEmitter();\n  private effects = new Map<string, () => void>(); // Track effect cleanup functions\n\n  constructor(private sweepEvery = 60_000 /* 1 min */) {\n    setInterval(() => this.sweep(), sweepEvery).unref();\n  }\n\n  // ───────────────────────── core helpers ─────────────────────────\n\n  /** Internal GC */\n  private sweep() {\n    const now = Date.now();\n    for (const [k, v] of this.cache) if (v.expiresAt && v.expiresAt <= now) this.cache.delete(k);\n  }\n\n  /** Get value (or undefined if missing / expired) */\n  get<T>(key: string): T | undefined {\n    const hit = this.cache.get(key);\n    if (!hit) return undefined;\n    if (hit.expiresAt && hit.expiresAt <= Date.now()) {\n      this.cache.delete(key);\n      return undefined;\n    }\n    return hit.value as T;\n  }\n\n  /** Set value + optional TTL */\n  set<T>(key: string, value: T, opts: StateOptions = {}): void {\n    const expiresAt = opts.ttl ? Date.now() + opts.ttl : undefined;\n    this.cache.set(key, { value, expiresAt });\n    this.events.emit(key, value);             // notify subscribers\n  }\n\n  // ───────────────────── React-flavoured sugar ─────────────────────\n\n  /**\n   * React-like helper.\n   * ```ts\n   * const [count, setCount] = store.useState(\"count\", 0, { ttl: 30_000 });\n   * ```\n   */\n  useState<T>(\n    key: string,\n    initial: T | (() => T),\n    opts: StateOptions = {}\n  ): [T, (v: T | ((prev: T) => T), o?: StateOptions) => void] {\n    let current = this.get<T>(key);\n    if (current === undefined) {\n      current = typeof initial === \"function\" ? (initial as () => T)() : initial;\n      this.set(key, current, opts);\n    }\n    const setter = (v: T | ((prev: T) => T), override: StateOptions = {}) => {\n      const prev = this.get<T>(key) as T;\n      const next = typeof v === \"function\" ? (v as (p: T) => T)(prev) : v;\n      this.set(key, next, { ...opts, ...override });\n    };\n    return [current, setter];\n  }\n\n  /** Subscribe; returns an unsubscribe fn */\n  subscribe<T>(key: string, cb: (v: T) => void) {\n    this.events.on(key, cb);\n    return () => this.events.off(key, cb);\n  }\n\n  /**\n   * React-like useEffect helper.\n   * Runs effect when dependencies change, supports cleanup.\n   * ```ts\n   * // Run effect when 'user' or 'settings' change\n   * const cleanup = store.useEffect(\n   *   () => {\n   *     console.log('User or settings changed');\n   *     return () => console.log('Cleanup');\n   *   },\n   *   ['user', 'settings']\n   * );\n   * ```\n   */\n  useEffect(\n    effect: () => void | (() => void),\n    deps: string[] = [],\n    effectId?: string\n  ): () => void {\n    const id = effectId || `effect_${Date.now()}_${Math.random()}`;\n    \n    // Cleanup previous effect if it exists\n    const existingCleanup = this.effects.get(id);\n    if (existingCleanup) {\n      existingCleanup();\n      this.effects.delete(id);\n    }\n\n    let cleanup: (() => void) | undefined;\n    const unsubscribers: (() => void)[] = [];\n\n    // Run effect initially\n    const runEffect = () => {\n      // Cleanup previous run\n      if (cleanup) cleanup();\n      \n      // Run the effect\n      const result = effect();\n      cleanup = typeof result === 'function' ? result : undefined;\n    };\n\n    // If no dependencies, run once and return cleanup\n    if (deps.length === 0) {\n      runEffect();\n      const effectCleanup = () => {\n        if (cleanup) cleanup();\n        this.effects.delete(id);\n      };\n      this.effects.set(id, effectCleanup);\n      return effectCleanup;\n    }\n\n    // Subscribe to all dependencies\n    deps.forEach(dep => {\n      const unsub = this.subscribe(dep, () => {\n        runEffect();\n      });\n      unsubscribers.push(unsub);\n    });\n\n    // Run effect initially\n    runEffect();\n\n    // Return cleanup function\n    const effectCleanup = () => {\n      // Cleanup effect\n      if (cleanup) cleanup();\n      \n      // Unsubscribe from all dependencies\n      unsubscribers.forEach(unsub => unsub());\n      \n      // Remove from effects map\n      this.effects.delete(id);\n    };\n\n    this.effects.set(id, effectCleanup);\n    return effectCleanup;\n  }\n\n  /**\n   * Cleanup all effects (useful for testing or shutdown)\n   */\n  cleanupAllEffects(): void {\n    for (const cleanup of this.effects.values()) {\n      cleanup();\n    }\n    this.effects.clear();\n  }\n}\n\n// factory (so callers don’t import the class directly)\nexport const createServerState = (sweep?: number) => new ServerState(sweep);\n"],"names":["EventEmitter"],"mappings":";;;;AAAA;MAWa,WAAW,CAAA;IAKtB,WAAoB,CAAA,UAAA,GAAa,KAAM,cAAY;QAA/B,IAAU,CAAA,UAAA,GAAV,UAAU;AAJtB,QAAA,IAAA,CAAA,KAAK,GAAG,IAAI,GAAG,EAAiB;AAChC,QAAA,IAAA,CAAA,MAAM,GAAG,IAAIA,wBAAY,EAAE;AAC3B,QAAA,IAAA,CAAA,OAAO,GAAG,IAAI,GAAG,EAAsB,CAAC;AAG9C,QAAA,WAAW,CAAC,MAAM,IAAI,CAAC,KAAK,EAAE,EAAE,UAAU,CAAC,CAAC,KAAK,EAAE;;;;IAM7C,KAAK,GAAA;AACX,QAAA,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE;QACtB,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,IAAI,CAAC,KAAK;YAAE,IAAI,CAAC,CAAC,SAAS,IAAI,CAAC,CAAC,SAAS,IAAI,GAAG;AAAE,gBAAA,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC;;;AAI9F,IAAA,GAAG,CAAI,GAAW,EAAA;QAChB,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC;AAC/B,QAAA,IAAI,CAAC,GAAG;AAAE,YAAA,OAAO,SAAS;AAC1B,QAAA,IAAI,GAAG,CAAC,SAAS,IAAI,GAAG,CAAC,SAAS,IAAI,IAAI,CAAC,GAAG,EAAE,EAAE;AAChD,YAAA,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC;AACtB,YAAA,OAAO,SAAS;;QAElB,OAAO,GAAG,CAAC,KAAU;;;AAIvB,IAAA,GAAG,CAAI,GAAW,EAAE,KAAQ,EAAE,OAAqB,EAAE,EAAA;QACnD,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,GAAG,GAAG,SAAS;AAC9D,QAAA,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC;QACzC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;;;AAK/B;;;;;AAKG;AACH,IAAA,QAAQ,CACN,GAAW,EACX,OAAsB,EACtB,OAAqB,EAAE,EAAA;QAEvB,IAAI,OAAO,GAAG,IAAI,CAAC,GAAG,CAAI,GAAG,CAAC;AAC9B,QAAA,IAAI,OAAO,KAAK,SAAS,EAAE;AACzB,YAAA,OAAO,GAAG,OAAO,OAAO,KAAK,UAAU,GAAI,OAAmB,EAAE,GAAG,OAAO;YAC1E,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,CAAC;;QAE9B,MAAM,MAAM,GAAG,CAAC,CAAuB,EAAE,QAAyB,GAAA,EAAE,KAAI;YACtE,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAI,GAAG,CAAM;AAClC,YAAA,MAAM,IAAI,GAAG,OAAO,CAAC,KAAK,UAAU,GAAI,CAAiB,CAAC,IAAI,CAAC,GAAG,CAAC;AACnE,YAAA,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,GAAG,IAAI,EAAE,GAAG,QAAQ,EAAE,CAAC;AAC/C,SAAC;AACD,QAAA,OAAO,CAAC,OAAO,EAAE,MAAM,CAAC;;;IAI1B,SAAS,CAAI,GAAW,EAAE,EAAkB,EAAA;QAC1C,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC;AACvB,QAAA,OAAO,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,CAAC;;AAGvC;;;;;;;;;;;;;AAaG;AACH,IAAA,SAAS,CACP,MAAiC,EACjC,IAAiB,GAAA,EAAE,EACnB,QAAiB,EAAA;AAEjB,QAAA,MAAM,EAAE,GAAG,QAAQ,IAAI,UAAU,IAAI,CAAC,GAAG,EAAE,IAAI,IAAI,CAAC,MAAM,EAAE,EAAE;;QAG9D,MAAM,eAAe,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QAC5C,IAAI,eAAe,EAAE;AACnB,YAAA,eAAe,EAAE;AACjB,YAAA,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;;AAGzB,QAAA,IAAI,OAAiC;QACrC,MAAM,aAAa,GAAmB,EAAE;;QAGxC,MAAM,SAAS,GAAG,MAAK;;AAErB,YAAA,IAAI,OAAO;AAAE,gBAAA,OAAO,EAAE;;AAGtB,YAAA,MAAM,MAAM,GAAG,MAAM,EAAE;AACvB,YAAA,OAAO,GAAG,OAAO,MAAM,KAAK,UAAU,GAAG,MAAM,GAAG,SAAS;AAC7D,SAAC;;AAGD,QAAA,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE;AACrB,YAAA,SAAS,EAAE;YACX,MAAM,aAAa,GAAG,MAAK;AACzB,gBAAA,IAAI,OAAO;AAAE,oBAAA,OAAO,EAAE;AACtB,gBAAA,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;AACzB,aAAC;YACD,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,EAAE,aAAa,CAAC;AACnC,YAAA,OAAO,aAAa;;;AAItB,QAAA,IAAI,CAAC,OAAO,CAAC,GAAG,IAAG;YACjB,MAAM,KAAK,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE,MAAK;AACrC,gBAAA,SAAS,EAAE;AACb,aAAC,CAAC;AACF,YAAA,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC;AAC3B,SAAC,CAAC;;AAGF,QAAA,SAAS,EAAE;;QAGX,MAAM,aAAa,GAAG,MAAK;;AAEzB,YAAA,IAAI,OAAO;AAAE,gBAAA,OAAO,EAAE;;YAGtB,aAAa,CAAC,OAAO,CAAC,KAAK,IAAI,KAAK,EAAE,CAAC;;AAGvC,YAAA,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;AACzB,SAAC;QAED,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,EAAE,aAAa,CAAC;AACnC,QAAA,OAAO,aAAa;;AAGtB;;AAEG;IACH,iBAAiB,GAAA;QACf,KAAK,MAAM,OAAO,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE;AAC3C,YAAA,OAAO,EAAE;;AAEX,QAAA,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE;;AAEvB;AAED;AACO,MAAM,iBAAiB,GAAG,CAAC,KAAc,KAAK,IAAI,WAAW,CAAC,KAAK;;;;;"}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from "./Store";

package/dist/index.js

@@ -0,0 +1,142 @@
+import { EventEmitter } from 'node:events';
+
+// [tiny-server-state] in-memory state engine
+class ServerState {
+    constructor(sweepEvery = 60000 /* 1 min */) {
+        this.sweepEvery = sweepEvery;
+        this.cache = new Map();
+        this.events = new EventEmitter();
+        this.effects = new Map(); // Track effect cleanup functions
+        setInterval(() => this.sweep(), sweepEvery).unref();
+    }
+    // ───────────────────────── core helpers ─────────────────────────
+    /** Internal GC */
+    sweep() {
+        const now = Date.now();
+        for (const [k, v] of this.cache)
+            if (v.expiresAt && v.expiresAt <= now)
+                this.cache.delete(k);
+    }
+    /** Get value (or undefined if missing / expired) */
+    get(key) {
+        const hit = this.cache.get(key);
+        if (!hit)
+            return undefined;
+        if (hit.expiresAt && hit.expiresAt <= Date.now()) {
+            this.cache.delete(key);
+            return undefined;
+        }
+        return hit.value;
+    }
+    /** Set value + optional TTL */
+    set(key, value, opts = {}) {
+        const expiresAt = opts.ttl ? Date.now() + opts.ttl : undefined;
+        this.cache.set(key, { value, expiresAt });
+        this.events.emit(key, value); // notify subscribers
+    }
+    // ───────────────────── React-flavoured sugar ─────────────────────
+    /**
+     * React-like helper.
+     * ```ts
+     * const [count, setCount] = store.useState("count", 0, { ttl: 30_000 });
+     * ```
+     */
+    useState(key, initial, opts = {}) {
+        let current = this.get(key);
+        if (current === undefined) {
+            current = typeof initial === "function" ? initial() : initial;
+            this.set(key, current, opts);
+        }
+        const setter = (v, override = {}) => {
+            const prev = this.get(key);
+            const next = typeof v === "function" ? v(prev) : v;
+            this.set(key, next, { ...opts, ...override });
+        };
+        return [current, setter];
+    }
+    /** Subscribe; returns an unsubscribe fn */
+    subscribe(key, cb) {
+        this.events.on(key, cb);
+        return () => this.events.off(key, cb);
+    }
+    /**
+     * React-like useEffect helper.
+     * Runs effect when dependencies change, supports cleanup.
+     * ```ts
+     * // Run effect when 'user' or 'settings' change
+     * const cleanup = store.useEffect(
+     *   () => {
+     *     console.log('User or settings changed');
+     *     return () => console.log('Cleanup');
+     *   },
+     *   ['user', 'settings']
+     * );
+     * ```
+     */
+    useEffect(effect, deps = [], effectId) {
+        const id = effectId || `effect_${Date.now()}_${Math.random()}`;
+        // Cleanup previous effect if it exists
+        const existingCleanup = this.effects.get(id);
+        if (existingCleanup) {
+            existingCleanup();
+            this.effects.delete(id);
+        }
+        let cleanup;
+        const unsubscribers = [];
+        // Run effect initially
+        const runEffect = () => {
+            // Cleanup previous run
+            if (cleanup)
+                cleanup();
+            // Run the effect
+            const result = effect();
+            cleanup = typeof result === 'function' ? result : undefined;
+        };
+        // If no dependencies, run once and return cleanup
+        if (deps.length === 0) {
+            runEffect();
+            const effectCleanup = () => {
+                if (cleanup)
+                    cleanup();
+                this.effects.delete(id);
+            };
+            this.effects.set(id, effectCleanup);
+            return effectCleanup;
+        }
+        // Subscribe to all dependencies
+        deps.forEach(dep => {
+            const unsub = this.subscribe(dep, () => {
+                runEffect();
+            });
+            unsubscribers.push(unsub);
+        });
+        // Run effect initially
+        runEffect();
+        // Return cleanup function
+        const effectCleanup = () => {
+            // Cleanup effect
+            if (cleanup)
+                cleanup();
+            // Unsubscribe from all dependencies
+            unsubscribers.forEach(unsub => unsub());
+            // Remove from effects map
+            this.effects.delete(id);
+        };
+        this.effects.set(id, effectCleanup);
+        return effectCleanup;
+    }
+    /**
+     * Cleanup all effects (useful for testing or shutdown)
+     */
+    cleanupAllEffects() {
+        for (const cleanup of this.effects.values()) {
+            cleanup();
+        }
+        this.effects.clear();
+    }
+}
+// factory (so callers don’t import the class directly)
+const createServerState = (sweep) => new ServerState(sweep);
+
+export { ServerState, createServerState };
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../src/Store.ts"],"sourcesContent":["// [tiny-server-state] in-memory state engine\nimport { EventEmitter } from \"node:events\";\n\nexport interface StateOptions { ttl?: number /* ms */; }\n\ninterface Entry<T = unknown> {\n  value: T;\n  /** epoch in ms when the value dies */\n  expiresAt?: number;\n}\n\nexport class ServerState {\n  private cache = new Map<string, Entry>();\n  private events = new EventEmitter();\n  private effects = new Map<string, () => void>(); // Track effect cleanup functions\n\n  constructor(private sweepEvery = 60_000 /* 1 min */) {\n    setInterval(() => this.sweep(), sweepEvery).unref();\n  }\n\n  // ───────────────────────── core helpers ─────────────────────────\n\n  /** Internal GC */\n  private sweep() {\n    const now = Date.now();\n    for (const [k, v] of this.cache) if (v.expiresAt && v.expiresAt <= now) this.cache.delete(k);\n  }\n\n  /** Get value (or undefined if missing / expired) */\n  get<T>(key: string): T | undefined {\n    const hit = this.cache.get(key);\n    if (!hit) return undefined;\n    if (hit.expiresAt && hit.expiresAt <= Date.now()) {\n      this.cache.delete(key);\n      return undefined;\n    }\n    return hit.value as T;\n  }\n\n  /** Set value + optional TTL */\n  set<T>(key: string, value: T, opts: StateOptions = {}): void {\n    const expiresAt = opts.ttl ? Date.now() + opts.ttl : undefined;\n    this.cache.set(key, { value, expiresAt });\n    this.events.emit(key, value);             // notify subscribers\n  }\n\n  // ───────────────────── React-flavoured sugar ─────────────────────\n\n  /**\n   * React-like helper.\n   * ```ts\n   * const [count, setCount] = store.useState(\"count\", 0, { ttl: 30_000 });\n   * ```\n   */\n  useState<T>(\n    key: string,\n    initial: T | (() => T),\n    opts: StateOptions = {}\n  ): [T, (v: T | ((prev: T) => T), o?: StateOptions) => void] {\n    let current = this.get<T>(key);\n    if (current === undefined) {\n      current = typeof initial === \"function\" ? (initial as () => T)() : initial;\n      this.set(key, current, opts);\n    }\n    const setter = (v: T | ((prev: T) => T), override: StateOptions = {}) => {\n      const prev = this.get<T>(key) as T;\n      const next = typeof v === \"function\" ? (v as (p: T) => T)(prev) : v;\n      this.set(key, next, { ...opts, ...override });\n    };\n    return [current, setter];\n  }\n\n  /** Subscribe; returns an unsubscribe fn */\n  subscribe<T>(key: string, cb: (v: T) => void) {\n    this.events.on(key, cb);\n    return () => this.events.off(key, cb);\n  }\n\n  /**\n   * React-like useEffect helper.\n   * Runs effect when dependencies change, supports cleanup.\n   * ```ts\n   * // Run effect when 'user' or 'settings' change\n   * const cleanup = store.useEffect(\n   *   () => {\n   *     console.log('User or settings changed');\n   *     return () => console.log('Cleanup');\n   *   },\n   *   ['user', 'settings']\n   * );\n   * ```\n   */\n  useEffect(\n    effect: () => void | (() => void),\n    deps: string[] = [],\n    effectId?: string\n  ): () => void {\n    const id = effectId || `effect_${Date.now()}_${Math.random()}`;\n    \n    // Cleanup previous effect if it exists\n    const existingCleanup = this.effects.get(id);\n    if (existingCleanup) {\n      existingCleanup();\n      this.effects.delete(id);\n    }\n\n    let cleanup: (() => void) | undefined;\n    const unsubscribers: (() => void)[] = [];\n\n    // Run effect initially\n    const runEffect = () => {\n      // Cleanup previous run\n      if (cleanup) cleanup();\n      \n      // Run the effect\n      const result = effect();\n      cleanup = typeof result === 'function' ? result : undefined;\n    };\n\n    // If no dependencies, run once and return cleanup\n    if (deps.length === 0) {\n      runEffect();\n      const effectCleanup = () => {\n        if (cleanup) cleanup();\n        this.effects.delete(id);\n      };\n      this.effects.set(id, effectCleanup);\n      return effectCleanup;\n    }\n\n    // Subscribe to all dependencies\n    deps.forEach(dep => {\n      const unsub = this.subscribe(dep, () => {\n        runEffect();\n      });\n      unsubscribers.push(unsub);\n    });\n\n    // Run effect initially\n    runEffect();\n\n    // Return cleanup function\n    const effectCleanup = () => {\n      // Cleanup effect\n      if (cleanup) cleanup();\n      \n      // Unsubscribe from all dependencies\n      unsubscribers.forEach(unsub => unsub());\n      \n      // Remove from effects map\n      this.effects.delete(id);\n    };\n\n    this.effects.set(id, effectCleanup);\n    return effectCleanup;\n  }\n\n  /**\n   * Cleanup all effects (useful for testing or shutdown)\n   */\n  cleanupAllEffects(): void {\n    for (const cleanup of this.effects.values()) {\n      cleanup();\n    }\n    this.effects.clear();\n  }\n}\n\n// factory (so callers don’t import the class directly)\nexport const createServerState = (sweep?: number) => new ServerState(sweep);\n"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "tiny-server-state",
+  "version": "0.1.2",
+  "description": "Lightweight TTL-enabled in-memory state for Node servers",
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    "import": "./dist/index.js",
+    "require": "./dist/index.cjs"
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "state",
+    "cache",
+    "ttl",
+    "node",
+    "server"
+  ],
+  "license": "MIT",
+  "scripts": {
+    "build": "rollup -c",
+    "clean": "rimraf dist",
+    "prepublishOnly": "npm run clean && npm run build",
+    "test": "node test/basic.test.js"
+  },
+  "devDependencies": {
+    "@rollup/plugin-typescript": "^11.1.3",
+    "@types/node": "^22.15.21",
+    "rimraf": "^5.0.5",
+    "rollup": "^4.41.0",
+    "typescript": "^5.4.5"
+  },
+  "dependencies": {
+    "tslib": "^2.8.1"
+  }
+}