coolneur 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,17 @@
+MIT License
+
+Copyright (c) 2026 Coolneur contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.

package/README.md

@@ -1,3 +1,231 @@
-# Temporary Holding Version
+# coolneur
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Use this when:** you need an in-memory cooldown manager for a JavaScript or TypeScript game, bot, API, or CLI. Define classic timers or multi-charge abilities, group related cooldowns into named streams, pause and resume state, and save or restore snapshots. `tryUse()` checks and consumes synchronously in one call. Zero runtime dependencies.
+
+**Search terms:** cooldown, cooldown manager, rate limit, throttle, timer, ability cooldown, multi-charge cooldown, charge regeneration, scoped cooldown, user cooldown, guild cooldown, channel cooldown, command cooldown, JavaScript, TypeScript.
+
+## Install
+
+```bash
+npm install coolneur
+```
+
+## Quick start
+
+```js
+import { Coolneur } from 'coolneur';
+
+let now = 0;
+const coolneur = new Coolneur({ clock: () => now });
+const player = coolneur.stream('player:42');
+player.define('dash', { durationMs: 3000 });
+
+const result = player.tryUse('dash');
+if (result.success) console.log('Dash activated');
+else console.log(`Ready in ${result.remainingMs}ms`);
+```
+
+`tryUse(name)` is the synchronous, non-throwing check-and-consume operation. A successful classic result has the shape `{ success: true, remainingMs, mode: 'classic' }`; a blocked result has `{ success: false, remainingMs, mode: 'classic' }`.
+
+## When to use this
+
+Use coolneur when an application needs local cooldown state, such as a game ability, command cooldown, temporary action lockout, or per-entity timer. A stream is a named namespace: create one stream per user, guild, channel, player, game session, or composite key. For example, ``coolneur.stream(`user:${userId}`)`` or ``coolneur.stream(`guild:${guildId}:user:${userId}`)``. Stream names are application-defined; coolneur does not parse Discord or other platform context objects.
+
+Choose **classic mode** for one timer per action. Choose **charges mode** when an ability has multiple uses that regenerate one at a time. Use `sharedGroup` when multiple charge-based definitions inside the same stream should draw from one pool.
+
+## Features
+
+- Classic cooldowns with configurable durations and optional per-use duration overrides.
+- Multi-charge abilities with sequential charge regeneration.
+- Named streams for isolating state by user, guild, channel, player, session, or composite application key.
+- Shared charge pools within one stream through `sharedGroup`.
+- Synchronous `tryUse()` plus throwing `use()` and non-consuming `start()`.
+- Inspect readiness, remaining time, charges, next recharge, and time until full recharge.
+- Pause, resume, reset, and delete cooldown definitions.
+- Lifecycle events with unsubscribe functions.
+- JSON-serializable snapshots and restore with elapsed-time handling.
+- Injected clock for deterministic tests; no background timer handles are created.
+- JavaScript implementation with TypeScript declaration files and no runtime dependencies.
+
+## API at a glance
+
+### Manager
+
+| API | Purpose |
+| --- | --- |
+| `new Coolneur({ clock? })` | Create a manager. `clock` is a `() => number`, defaulting to `Date.now`. |
+| `stream(name)` | Get or create a named `CoolneurStream`. |
+| `on(event, listener)` | Subscribe to an event; returns an unsubscribe function. Use `'*'` to receive all events. |
+| `off(event, listener)` | Remove an event listener. |
+| `snapshot()` | Return a JSON-serializable manager snapshot. |
+| `restore(data, options?)` | Restore streams from a snapshot. |
+| `clear()` | Clear all streams and shared pools. |
+
+### Stream
+
+| API | Purpose |
+| --- | --- |
+| `define(name, config?)` | Define a classic or charge-based cooldown. |
+| `has(name)` / `list()` | Check or list definitions. |
+| `start(name, durationMs?)` | Start/restart a classic timer without consuming it. For a charge definition, this delegates to `use()`. |
+| `tryUse(name)` | Atomically check and consume within this synchronous manager call; returns a result object. |
+| `use(name)` | Consume when ready; throws when unavailable. |
+| `remaining(name)` / `isReady(name)` | Inspect remaining time or readiness. |
+| `charges(name)` | Read available charges for a charge-based definition. |
+| `timeUntilNextCharge(name)` | Milliseconds until the next charge regenerates (0 when no charge is waiting to regenerate). |
+| `timeUntilFull(name)` | Milliseconds until the charge pool is full. |
+| `pause(name)` / `resume(name)` | Pause or resume a timer or charge pool. |
+| `reset(name, options?)` | Reset a classic cooldown or charge count. |
+| `delete(name)` | Delete a definition. |
+| `snapshot()` / `restore(data, options?)` | Save or restore one stream. |
+
+## Classic cooldowns
+
+```js
+const player = coolneur.stream('player:42');
+player.define('dash', { durationMs: 3000 });
+
+const first = player.tryUse('dash');
+// { success: true, remainingMs: 3000, mode: 'classic' }
+
+const second = player.tryUse('dash');
+// { success: false, remainingMs: 3000, mode: 'classic' }
+
+player.start('dash', 1500); // start/restart without consuming
+player.pause('dash');
+player.resume('dash');
+```
+
+Classic configuration accepts `durationMs`, with `cooldownMs` and `cooldown` as aliases. `start(name, durationMs)` can override the configured duration for that start.
+
+## Multi-charge cooldowns
+
+```js
+const player = coolneur.stream('player:42');
+player.define('fireball', {
+  mode: 'charges',
+  maxCharges: 3,
+  initialCharges: 3,
+  rechargeMs: 4000
+});
+
+const result = player.tryUse('fireball');
+// { success: true, charges: 2, remainingMs: 4000, mode: 'charges' }
+
+console.log(player.charges('fireball'));             // 2
+console.log(player.timeUntilNextCharge('fireball')); // milliseconds until the next recharge
+console.log(player.timeUntilFull('fireball'));       // time until all 3 charges are restored
+```
+
+Charges regenerate one at a time. If all three charges are spent at the same moment, the first returns after one `rechargeMs` interval, the second after two intervals, and the third after three. `sharedGroup` makes compatible charge definitions in the same stream use the same pool; the `maxCharges` and `rechargeMs` values must match.
+
+## Scoping examples
+
+Coolneur does not impose a platform-specific context model. Use stable application-defined stream names to isolate state:
+
+```js
+const byUser = coolneur.stream(`user:${userId}`);
+const byGuild = coolneur.stream(`guild:${guildId}`);
+const byChannel = coolneur.stream(`channel:${channelId}`);
+const byGuildAndUser = coolneur.stream(`guild:${guildId}:user:${userId}`);
+
+byUser.define('daily-reward', { durationMs: 24 * 60 * 60 * 1000 });
+```
+
+Choose a stream key that matches the scope your application needs. A stream is in-memory and belongs to one `Coolneur` manager instance.
+
+## Shared charge pools
+
+```js
+const party = coolneur.stream('party:alpha');
+party.define('shield', {
+  mode: 'charges', maxCharges: 2, rechargeMs: 8000, sharedGroup: 'team-energy'
+});
+party.define('heal', {
+  mode: 'charges', maxCharges: 2, rechargeMs: 8000, sharedGroup: 'team-energy'
+});
+
+party.use('shield');
+console.log(party.charges('heal')); // 1: both definitions read the same pool
+```
+
+Shared groups are local to their stream and manager instance. They are not distributed across processes or servers.
+
+## Events
+
+```js
+const unsubscribe = coolneur.on('use', event => {
+  console.log(event.stream, event.cooldown, event.mode);
+});
+
+coolneur.on('*', event => console.log(event.event, event));
+unsubscribe();
+```
+
+Events emitted by the current API: `define`, `start`, `use`, `charge`, `pause`, `resume`, `reset`, and `delete`.
+
+## Save and restore
+
+```js
+const saved = coolneur.snapshot();
+localStorage.setItem('coolneur-state', JSON.stringify(saved));
+
+const restored = new Coolneur();
+restored.restore(JSON.parse(localStorage.getItem('coolneur-state')), {
+  elapsedMs: 2500
+});
+```
+
+`elapsedMs` is the amount of time to account for between saving and restoring. If omitted by `Coolneur.restore()`, elapsed time is derived from `savedAt` and the new manager's clock. Pass `{ applyElapsed: false }` to ignore offline elapsed time when restoring a manager snapshot. Stream-level `restore()` accepts `elapsedMs`.
+
+## Deterministic testing
+
+```js
+let now = 0;
+const testManager = new Coolneur({ clock: () => now });
+const testPlayer = testManager.stream('test-player');
+testPlayer.define('dash', { durationMs: 1000 });
+
+testPlayer.use('dash');
+now += 1000;
+console.log(testPlayer.isReady('dash')); // true
+```
+
+The manager reads the injected clock when methods are called. It does not create native timeout or interval handles.
+
+## Configuration reference
+
+| Option | Applies to | Type | Default / requirement |
+| --- | --- | --- | --- |
+| `clock` | `Coolneur` constructor | `() => number` | `Date.now` |
+| `durationMs` | classic definition | number, milliseconds | `0` |
+| `cooldownMs`, `cooldown` | classic definition | number, milliseconds | Aliases for `durationMs` |
+| `maxCharges` | charge definition | integer | Required; at least `1` |
+| `rechargeMs` | charge definition | number, milliseconds | Required; at least `0` |
+| `initialCharges` | charge definition | integer | Defaults to `maxCharges` |
+| `sharedGroup` | charge definition | string | Optional; shared within the same stream |
+| `metadata` | either definition | any value | Optional user metadata |
+| `elapsedMs` | restore options | number, milliseconds | `0` for stream restore; manager restore derives it from `savedAt` when omitted |
+| `applyElapsed` | manager restore | boolean | `true` |
+
+## Runnable examples
+
+The `examples/` directory contains runnable JavaScript examples:
+
+- `basic.mjs` — define and consume a classic cooldown.
+- `charges.mjs` — use multi-charge abilities and inspect recharge timing.
+- `scopes.mjs` — isolate cooldowns with per-user and composite stream names.
+- `persistence.mjs` — serialize and restore a snapshot.
+
+Run an example from the package root with `node examples/basic.mjs` (replace the filename as needed).
+
+## What coolneur does not do
+
+- It is not a security-grade or distributed rate limiter. For API protection, enforce limits on a trusted server and use shared server-side state where required.
+- It does not provide cross-process locks, a database adapter, or automatic persistence. Applications decide where snapshots are stored and synchronized.
+- It does not parse Discord, guild, channel, or user objects. Those are represented by application-defined stream names.
+- It does not expose `check()`, `peek()`, `consume()`, `scope()`, `addBypass()`, or `checkAsync()` in version 3.0.0. Use the documented API above (`tryUse()`, `remaining()`, `stream()`, and `use()`).
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,161 @@
+const nowDefault = () => Date.now();
+
+function assertName(name, label = 'name') {
+  if (typeof name !== 'string' || !name.trim()) throw new TypeError(`${label} must be a non-empty string`);
+}
+function assertMs(value, label) {
+  if (!Number.isFinite(value) || value < 0) throw new TypeError(`${label} must be a finite number >= 0`);
+}
+
+/** Coolneur: timerless, clock-injectable cooldown and charge manager. */
+class Coolneur {
+  constructor(options = {}) {
+    this.clock = options.clock ?? nowDefault;
+    if (typeof this.clock !== 'function') throw new TypeError('clock must be a function');
+    this.streams = new Map();
+    this.listeners = new Map();
+    this.sharedPools = new Map();
+  }
+  stream(name) {
+    assertName(name, 'stream name');
+    if (!this.streams.has(name)) this.streams.set(name, new CoolneurStream(this, name));
+    return this.streams.get(name);
+  }
+  on(event, listener) {
+    assertName(event, 'event');
+    if (typeof listener !== 'function') throw new TypeError('listener must be a function');
+    if (!this.listeners.has(event)) this.listeners.set(event, new Set());
+    this.listeners.get(event).add(listener);
+    return () => this.off(event, listener);
+  }
+  off(event, listener) { this.listeners.get(event)?.delete(listener); }
+  emit(event, payload) {
+    for (const listener of this.listeners.get(event) ?? []) listener(payload);
+    for (const listener of this.listeners.get('*') ?? []) listener({ event, ...payload });
+  }
+  snapshot() {
+    return { version: 1, savedAt: this.clock(), streams: [...this.streams.values()].map(s => s.snapshot()) };
+  }
+  restore(data, options = {}) {
+    if (!data || data.version !== 1 || !Array.isArray(data.streams)) throw new TypeError('Invalid Coolneur snapshot');
+    const elapsed = options.elapsedMs ?? Math.max(0, this.clock() - (data.savedAt ?? this.clock()));
+    assertMs(elapsed, 'elapsedMs');
+    for (const streamData of data.streams) this.stream(streamData.name).restore(streamData, { elapsedMs: options.applyElapsed === false ? 0 : elapsed });
+    return this;
+  }
+  clear() { this.streams.clear(); this.sharedPools.clear(); }
+}
+
+class CoolneurStream {
+  constructor(manager, name) { this.manager = manager; this.name = name; this.entries = new Map(); }
+  define(name, config = {}) {
+    assertName(name, 'cooldown name');
+    if (this.entries.has(name)) throw new Error(`Cooldown "${name}" is already defined in stream "${this.name}"`);
+    const mode = config.mode ?? (config.maxCharges !== undefined ? 'charges' : 'classic');
+    if (mode !== 'classic' && mode !== 'charges') throw new TypeError('mode must be "classic" or "charges"');
+    const duration = config.durationMs ?? config.cooldownMs ?? config.cooldown ?? 0;
+    assertMs(duration, 'durationMs');
+    let entry;
+    if (mode === 'classic') {
+      entry = { name, mode, durationMs: duration, readyAt: this.manager.clock(), paused: false, pausedRemaining: 0, metadata: config.metadata };
+    } else {
+      const maxCharges = config.maxCharges;
+      const rechargeMs = config.rechargeMs;
+      if (!Number.isInteger(maxCharges) || maxCharges < 1) throw new TypeError('maxCharges must be an integer >= 1');
+      assertMs(rechargeMs, 'rechargeMs');
+      const initialCharges = config.initialCharges ?? maxCharges;
+      if (!Number.isInteger(initialCharges) || initialCharges < 0 || initialCharges > maxCharges) throw new TypeError('initialCharges must be an integer from 0 to maxCharges');
+      const sharedKey = config.sharedGroup;
+      let pool;
+      if (sharedKey != null) {
+        assertName(sharedKey, 'sharedGroup');
+        const poolKey = `${this.name}:${sharedKey}`;
+        pool = this.manager.sharedPools.get(poolKey);
+        if (pool && (pool.maxCharges !== maxCharges || pool.rechargeMs !== rechargeMs)) throw new Error(`Shared group "${sharedKey}" has incompatible charge settings`);
+        if (!pool) { pool = { maxCharges, rechargeMs, charges: initialCharges, queue: [], paused: false, pausedAt: 0, key: poolKey }; this.manager.sharedPools.set(poolKey, pool); }
+      } else pool = { maxCharges, rechargeMs, charges: initialCharges, queue: [], paused: false, pausedAt: 0 };
+      entry = { name, mode, pool, sharedGroup: sharedKey, metadata: config.metadata };
+    }
+    this.entries.set(name, entry);
+    this.manager.emit('define', { stream: this.name, cooldown: name, mode });
+    return this;
+  }
+  has(name) { return this.entries.has(name); }
+  get(name) { const e = this.entries.get(name); if (!e) throw new Error(`Unknown cooldown "${name}" in stream "${this.name}"`); return e; }
+  start(name, durationMs) {
+    const e = this.get(name); if (e.mode !== 'classic') return this.use(name);
+    const duration = durationMs ?? e.durationMs; assertMs(duration, 'durationMs');
+    e.readyAt = this.manager.clock() + duration; e.paused = false;
+    this.manager.emit('start', { stream: this.name, cooldown: name, durationMs: duration, readyAt: e.readyAt });
+    return this;
+  }
+  use(name) { const result = this.tryUse(name); if (!result.success) throw new Error(`Cooldown "${name}" is not ready (${result.remainingMs}ms remaining)`); return this; }
+  tryUse(name) {
+    const e = this.get(name), now = this.manager.clock();
+    if (e.mode === 'classic') {
+      const remainingMs = this.remaining(name);
+      if (remainingMs > 0) return { success: false, remainingMs, mode: 'classic' };
+      e.readyAt = now + e.durationMs;
+      this.manager.emit('use', { stream: this.name, cooldown: name, mode: 'classic', readyAt: e.readyAt });
+      return { success: true, remainingMs: e.durationMs, mode: 'classic' };
+    }
+    const p = e.pool; this._syncPool(p, now);
+    if (p.paused || p.charges <= 0) return { success: false, remainingMs: this.timeUntilNextCharge(name), mode: 'charges', charges: p.charges };
+    p.charges -= 1;
+    if (p.charges < p.maxCharges && p.queue.length === 0) p.queue.push(now + p.rechargeMs);
+    else if (p.charges < p.maxCharges) p.queue.push(p.queue[p.queue.length - 1] + p.rechargeMs);
+    this.manager.emit('use', { stream: this.name, cooldown: name, mode: 'charges', charges: p.charges });
+    this.manager.emit('charge', { stream: this.name, cooldown: name, charges: p.charges, maxCharges: p.maxCharges });
+    return { success: true, charges: p.charges, remainingMs: this.timeUntilNextCharge(name), mode: 'charges' };
+  }
+  remaining(name) { const e = this.get(name); if (e.mode === 'charges') return this.timeUntilNextCharge(name); if (e.paused) return e.pausedRemaining; return Math.max(0, e.readyAt - this.manager.clock()); }
+  isReady(name) { const e = this.get(name); return e.mode === 'charges' ? this.charges(name) > 0 && !e.pool.paused : this.remaining(name) === 0; }
+  charges(name) { const e = this.get(name); if (e.mode !== 'charges') throw new Error(`Cooldown "${name}" is not charge-based`); this._syncPool(e.pool, this.manager.clock()); return e.pool.charges; }
+  timeUntilNextCharge(name) { const e = this.get(name); if (e.mode !== 'charges') throw new Error(`Cooldown "${name}" is not charge-based`); const p = e.pool; this._syncPool(p, this.manager.clock()); return p.paused ? (p.pausedRemaining ?? 0) : Math.max(0, (p.queue[0] ?? this.manager.clock()) - this.manager.clock()); }
+  timeUntilFull(name) { const e = this.get(name); if (e.mode !== 'charges') throw new Error(`Cooldown "${name}" is not charge-based`); const p = e.pool; this._syncPool(p, this.manager.clock()); return p.paused ? (p.pausedRemaining ?? 0) + Math.max(0, p.maxCharges - p.charges - 1) * p.rechargeMs : p.queue.length ? Math.max(0, p.queue[p.queue.length - 1] - this.manager.clock()) : 0; }
+  _syncPool(p, now) {
+    if (p.paused) return;
+    while (p.queue.length && p.queue[0] <= now) { p.queue.shift(); p.charges = Math.min(p.maxCharges, p.charges + 1); }
+    if (p.charges >= p.maxCharges) p.queue.length = 0;
+  }
+  pause(name) {
+    const e = this.get(name), now = this.manager.clock();
+    if (e.mode === 'classic') { if (!e.paused) { e.pausedRemaining = Math.max(0, e.readyAt - now); e.paused = true; } }
+    else { const p = e.pool; this._syncPool(p, now); if (!p.paused) { p.pausedRemaining = p.queue.length ? Math.max(0, p.queue[0] - now) : 0; p.pausedAt = now; p.paused = true; } }
+    this.manager.emit('pause', { stream: this.name, cooldown: name }); return this;
+  }
+  resume(name) {
+    const e = this.get(name), now = this.manager.clock();
+    if (e.mode === 'classic') { if (e.paused) { e.readyAt = now + e.pausedRemaining; e.paused = false; } }
+    else { const p = e.pool; if (p.paused) { p.paused = false; if (p.charges < p.maxCharges) { p.queue = [now + (p.pausedRemaining ?? p.rechargeMs)]; for (let i = 1; i < p.maxCharges - p.charges; i++) p.queue.push(p.queue[i - 1] + p.rechargeMs); } p.pausedRemaining = 0; } }
+    this.manager.emit('resume', { stream: this.name, cooldown: name }); return this;
+  }
+  reset(name, options = {}) {
+    const e = this.get(name);
+    if (e.mode === 'classic') { e.readyAt = this.manager.clock(); e.paused = false; e.pausedRemaining = 0; }
+    else { const p = e.pool; p.charges = options.charges ?? p.maxCharges; if (!Number.isInteger(p.charges) || p.charges < 0 || p.charges > p.maxCharges) throw new TypeError('charges must be from 0 to maxCharges'); p.queue = []; p.paused = false; p.pausedRemaining = 0; }
+    this.manager.emit('reset', { stream: this.name, cooldown: name }); return this;
+  }
+  delete(name) { const deleted = this.entries.delete(name); if (deleted) this.manager.emit('delete', { stream: this.name, cooldown: name }); return deleted; }
+  list() { return [...this.entries.keys()]; }
+  snapshot() {
+    const now = this.manager.clock();
+    return { name: this.name, cooldowns: [...this.entries.values()].map(e => e.mode === 'classic' ? { name: e.name, mode: e.mode, durationMs: e.durationMs, remainingMs: this.remaining(e.name), paused: e.paused, metadata: e.metadata } : (this._syncPool(e.pool, now), { name: e.name, mode: e.mode, maxCharges: e.pool.maxCharges, rechargeMs: e.pool.rechargeMs, charges: e.pool.charges, queueRemainingMs: e.pool.queue.map(t => Math.max(0, t - now)), paused: e.pool.paused, pausedRemaining: e.pool.pausedRemaining, sharedGroup: e.sharedGroup, metadata: e.metadata })) };
+  }
+  restore(data, options = {}) {
+    if (!data || data.name !== this.name || !Array.isArray(data.cooldowns)) throw new TypeError('Invalid stream snapshot');
+    const elapsed = options.elapsedMs ?? 0; assertMs(elapsed, 'elapsedMs');
+    for (const item of data.cooldowns) {
+      if (!this.entries.has(item.name)) {
+        if (item.mode === 'classic') this.define(item.name, { durationMs: item.durationMs, metadata: item.metadata });
+        else this.define(item.name, { mode: 'charges', maxCharges: item.maxCharges, rechargeMs: item.rechargeMs, initialCharges: item.charges, sharedGroup: item.sharedGroup, metadata: item.metadata });
+      }
+      const e = this.get(item.name), now = this.manager.clock();
+      if (e.mode === 'classic' && item.mode === 'classic') { e.paused = !!item.paused; e.pausedRemaining = item.remainingMs; e.readyAt = now + Math.max(0, item.remainingMs - elapsed); if (!e.paused) e.readyAt = now + Math.max(0, item.remainingMs - elapsed); }
+      else if (e.mode === 'charges' && item.mode === 'charges') { const p = e.pool; p.charges = item.charges; p.paused = !!item.paused; p.pausedRemaining = item.pausedRemaining; p.queue = item.queueRemainingMs.map(ms => now + Math.max(0, ms - elapsed)); this._syncPool(p, now); }
+    }
+    return this;
+  }
+}
+
+module.exports = { Coolneur, CoolneurStream, default: Coolneur };

package/dist/index.d.ts

@@ -0,0 +1,37 @@
+export type CooldownMode = 'classic' | 'charges';
+export interface ClassicConfig { mode?: 'classic'; durationMs?: number; cooldownMs?: number; cooldown?: number; metadata?: unknown }
+export interface ChargesConfig { mode?: 'charges'; maxCharges: number; rechargeMs: number; initialCharges?: number; sharedGroup?: string; metadata?: unknown }
+export type CooldownConfig = ClassicConfig | ChargesConfig;
+export interface TryUseResult { success: boolean; remainingMs: number; mode: CooldownMode; charges?: number }
+export interface CoolneurOptions { clock?: () => number }
+export interface RestoreOptions { elapsedMs?: number; applyElapsed?: boolean }
+export declare class Coolneur {
+  constructor(options?: CoolneurOptions);
+  stream(name: string): CoolneurStream;
+  on(event: string, listener: (payload: any) => void): () => void;
+  off(event: string, listener: (payload: any) => void): void;
+  snapshot(): { version: 1; savedAt: number; streams: any[] };
+  restore(data: any, options?: RestoreOptions): this;
+  clear(): void;
+}
+export declare class CoolneurStream {
+  readonly name: string;
+  define(name: string, config?: CooldownConfig): this;
+  has(name: string): boolean;
+  start(name: string, durationMs?: number): this;
+  use(name: string): this;
+  tryUse(name: string): TryUseResult;
+  remaining(name: string): number;
+  isReady(name: string): boolean;
+  charges(name: string): number;
+  timeUntilNextCharge(name: string): number;
+  timeUntilFull(name: string): number;
+  pause(name: string): this;
+  resume(name: string): this;
+  reset(name: string, options?: { charges?: number }): this;
+  delete(name: string): boolean;
+  list(): string[];
+  snapshot(): any;
+  restore(data: any, options?: RestoreOptions): this;
+}
+export default Coolneur;

package/dist/index.js

@@ -0,0 +1,161 @@
+const nowDefault = () => Date.now();
+
+function assertName(name, label = 'name') {
+  if (typeof name !== 'string' || !name.trim()) throw new TypeError(`${label} must be a non-empty string`);
+}
+function assertMs(value, label) {
+  if (!Number.isFinite(value) || value < 0) throw new TypeError(`${label} must be a finite number >= 0`);
+}
+
+/** Coolneur: timerless, clock-injectable cooldown and charge manager. */
+export class Coolneur {
+  constructor(options = {}) {
+    this.clock = options.clock ?? nowDefault;
+    if (typeof this.clock !== 'function') throw new TypeError('clock must be a function');
+    this.streams = new Map();
+    this.listeners = new Map();
+    this.sharedPools = new Map();
+  }
+  stream(name) {
+    assertName(name, 'stream name');
+    if (!this.streams.has(name)) this.streams.set(name, new CoolneurStream(this, name));
+    return this.streams.get(name);
+  }
+  on(event, listener) {
+    assertName(event, 'event');
+    if (typeof listener !== 'function') throw new TypeError('listener must be a function');
+    if (!this.listeners.has(event)) this.listeners.set(event, new Set());
+    this.listeners.get(event).add(listener);
+    return () => this.off(event, listener);
+  }
+  off(event, listener) { this.listeners.get(event)?.delete(listener); }
+  emit(event, payload) {
+    for (const listener of this.listeners.get(event) ?? []) listener(payload);
+    for (const listener of this.listeners.get('*') ?? []) listener({ event, ...payload });
+  }
+  snapshot() {
+    return { version: 1, savedAt: this.clock(), streams: [...this.streams.values()].map(s => s.snapshot()) };
+  }
+  restore(data, options = {}) {
+    if (!data || data.version !== 1 || !Array.isArray(data.streams)) throw new TypeError('Invalid Coolneur snapshot');
+    const elapsed = options.elapsedMs ?? Math.max(0, this.clock() - (data.savedAt ?? this.clock()));
+    assertMs(elapsed, 'elapsedMs');
+    for (const streamData of data.streams) this.stream(streamData.name).restore(streamData, { elapsedMs: options.applyElapsed === false ? 0 : elapsed });
+    return this;
+  }
+  clear() { this.streams.clear(); this.sharedPools.clear(); }
+}
+
+export class CoolneurStream {
+  constructor(manager, name) { this.manager = manager; this.name = name; this.entries = new Map(); }
+  define(name, config = {}) {
+    assertName(name, 'cooldown name');
+    if (this.entries.has(name)) throw new Error(`Cooldown "${name}" is already defined in stream "${this.name}"`);
+    const mode = config.mode ?? (config.maxCharges !== undefined ? 'charges' : 'classic');
+    if (mode !== 'classic' && mode !== 'charges') throw new TypeError('mode must be "classic" or "charges"');
+    const duration = config.durationMs ?? config.cooldownMs ?? config.cooldown ?? 0;
+    assertMs(duration, 'durationMs');
+    let entry;
+    if (mode === 'classic') {
+      entry = { name, mode, durationMs: duration, readyAt: this.manager.clock(), paused: false, pausedRemaining: 0, metadata: config.metadata };
+    } else {
+      const maxCharges = config.maxCharges;
+      const rechargeMs = config.rechargeMs;
+      if (!Number.isInteger(maxCharges) || maxCharges < 1) throw new TypeError('maxCharges must be an integer >= 1');
+      assertMs(rechargeMs, 'rechargeMs');
+      const initialCharges = config.initialCharges ?? maxCharges;
+      if (!Number.isInteger(initialCharges) || initialCharges < 0 || initialCharges > maxCharges) throw new TypeError('initialCharges must be an integer from 0 to maxCharges');
+      const sharedKey = config.sharedGroup;
+      let pool;
+      if (sharedKey != null) {
+        assertName(sharedKey, 'sharedGroup');
+        const poolKey = `${this.name}:${sharedKey}`;
+        pool = this.manager.sharedPools.get(poolKey);
+        if (pool && (pool.maxCharges !== maxCharges || pool.rechargeMs !== rechargeMs)) throw new Error(`Shared group "${sharedKey}" has incompatible charge settings`);
+        if (!pool) { pool = { maxCharges, rechargeMs, charges: initialCharges, queue: [], paused: false, pausedAt: 0, key: poolKey }; this.manager.sharedPools.set(poolKey, pool); }
+      } else pool = { maxCharges, rechargeMs, charges: initialCharges, queue: [], paused: false, pausedAt: 0 };
+      entry = { name, mode, pool, sharedGroup: sharedKey, metadata: config.metadata };
+    }
+    this.entries.set(name, entry);
+    this.manager.emit('define', { stream: this.name, cooldown: name, mode });
+    return this;
+  }
+  has(name) { return this.entries.has(name); }
+  get(name) { const e = this.entries.get(name); if (!e) throw new Error(`Unknown cooldown "${name}" in stream "${this.name}"`); return e; }
+  start(name, durationMs) {
+    const e = this.get(name); if (e.mode !== 'classic') return this.use(name);
+    const duration = durationMs ?? e.durationMs; assertMs(duration, 'durationMs');
+    e.readyAt = this.manager.clock() + duration; e.paused = false;
+    this.manager.emit('start', { stream: this.name, cooldown: name, durationMs: duration, readyAt: e.readyAt });
+    return this;
+  }
+  use(name) { const result = this.tryUse(name); if (!result.success) throw new Error(`Cooldown "${name}" is not ready (${result.remainingMs}ms remaining)`); return this; }
+  tryUse(name) {
+    const e = this.get(name), now = this.manager.clock();
+    if (e.mode === 'classic') {
+      const remainingMs = this.remaining(name);
+      if (remainingMs > 0) return { success: false, remainingMs, mode: 'classic' };
+      e.readyAt = now + e.durationMs;
+      this.manager.emit('use', { stream: this.name, cooldown: name, mode: 'classic', readyAt: e.readyAt });
+      return { success: true, remainingMs: e.durationMs, mode: 'classic' };
+    }
+    const p = e.pool; this._syncPool(p, now);
+    if (p.paused || p.charges <= 0) return { success: false, remainingMs: this.timeUntilNextCharge(name), mode: 'charges', charges: p.charges };
+    p.charges -= 1;
+    if (p.charges < p.maxCharges && p.queue.length === 0) p.queue.push(now + p.rechargeMs);
+    else if (p.charges < p.maxCharges) p.queue.push(p.queue[p.queue.length - 1] + p.rechargeMs);
+    this.manager.emit('use', { stream: this.name, cooldown: name, mode: 'charges', charges: p.charges });
+    this.manager.emit('charge', { stream: this.name, cooldown: name, charges: p.charges, maxCharges: p.maxCharges });
+    return { success: true, charges: p.charges, remainingMs: this.timeUntilNextCharge(name), mode: 'charges' };
+  }
+  remaining(name) { const e = this.get(name); if (e.mode === 'charges') return this.timeUntilNextCharge(name); if (e.paused) return e.pausedRemaining; return Math.max(0, e.readyAt - this.manager.clock()); }
+  isReady(name) { const e = this.get(name); return e.mode === 'charges' ? this.charges(name) > 0 && !e.pool.paused : this.remaining(name) === 0; }
+  charges(name) { const e = this.get(name); if (e.mode !== 'charges') throw new Error(`Cooldown "${name}" is not charge-based`); this._syncPool(e.pool, this.manager.clock()); return e.pool.charges; }
+  timeUntilNextCharge(name) { const e = this.get(name); if (e.mode !== 'charges') throw new Error(`Cooldown "${name}" is not charge-based`); const p = e.pool; this._syncPool(p, this.manager.clock()); return p.paused ? (p.pausedRemaining ?? 0) : Math.max(0, (p.queue[0] ?? this.manager.clock()) - this.manager.clock()); }
+  timeUntilFull(name) { const e = this.get(name); if (e.mode !== 'charges') throw new Error(`Cooldown "${name}" is not charge-based`); const p = e.pool; this._syncPool(p, this.manager.clock()); return p.paused ? (p.pausedRemaining ?? 0) + Math.max(0, p.maxCharges - p.charges - 1) * p.rechargeMs : p.queue.length ? Math.max(0, p.queue[p.queue.length - 1] - this.manager.clock()) : 0; }
+  _syncPool(p, now) {
+    if (p.paused) return;
+    while (p.queue.length && p.queue[0] <= now) { p.queue.shift(); p.charges = Math.min(p.maxCharges, p.charges + 1); }
+    if (p.charges >= p.maxCharges) p.queue.length = 0;
+  }
+  pause(name) {
+    const e = this.get(name), now = this.manager.clock();
+    if (e.mode === 'classic') { if (!e.paused) { e.pausedRemaining = Math.max(0, e.readyAt - now); e.paused = true; } }
+    else { const p = e.pool; this._syncPool(p, now); if (!p.paused) { p.pausedRemaining = p.queue.length ? Math.max(0, p.queue[0] - now) : 0; p.pausedAt = now; p.paused = true; } }
+    this.manager.emit('pause', { stream: this.name, cooldown: name }); return this;
+  }
+  resume(name) {
+    const e = this.get(name), now = this.manager.clock();
+    if (e.mode === 'classic') { if (e.paused) { e.readyAt = now + e.pausedRemaining; e.paused = false; } }
+    else { const p = e.pool; if (p.paused) { p.paused = false; if (p.charges < p.maxCharges) { p.queue = [now + (p.pausedRemaining ?? p.rechargeMs)]; for (let i = 1; i < p.maxCharges - p.charges; i++) p.queue.push(p.queue[i - 1] + p.rechargeMs); } p.pausedRemaining = 0; } }
+    this.manager.emit('resume', { stream: this.name, cooldown: name }); return this;
+  }
+  reset(name, options = {}) {
+    const e = this.get(name);
+    if (e.mode === 'classic') { e.readyAt = this.manager.clock(); e.paused = false; e.pausedRemaining = 0; }
+    else { const p = e.pool; p.charges = options.charges ?? p.maxCharges; if (!Number.isInteger(p.charges) || p.charges < 0 || p.charges > p.maxCharges) throw new TypeError('charges must be from 0 to maxCharges'); p.queue = []; p.paused = false; p.pausedRemaining = 0; }
+    this.manager.emit('reset', { stream: this.name, cooldown: name }); return this;
+  }
+  delete(name) { const deleted = this.entries.delete(name); if (deleted) this.manager.emit('delete', { stream: this.name, cooldown: name }); return deleted; }
+  list() { return [...this.entries.keys()]; }
+  snapshot() {
+    const now = this.manager.clock();
+    return { name: this.name, cooldowns: [...this.entries.values()].map(e => e.mode === 'classic' ? { name: e.name, mode: e.mode, durationMs: e.durationMs, remainingMs: this.remaining(e.name), paused: e.paused, metadata: e.metadata } : (this._syncPool(e.pool, now), { name: e.name, mode: e.mode, maxCharges: e.pool.maxCharges, rechargeMs: e.pool.rechargeMs, charges: e.pool.charges, queueRemainingMs: e.pool.queue.map(t => Math.max(0, t - now)), paused: e.pool.paused, pausedRemaining: e.pool.pausedRemaining, sharedGroup: e.sharedGroup, metadata: e.metadata })) };
+  }
+  restore(data, options = {}) {
+    if (!data || data.name !== this.name || !Array.isArray(data.cooldowns)) throw new TypeError('Invalid stream snapshot');
+    const elapsed = options.elapsedMs ?? 0; assertMs(elapsed, 'elapsedMs');
+    for (const item of data.cooldowns) {
+      if (!this.entries.has(item.name)) {
+        if (item.mode === 'classic') this.define(item.name, { durationMs: item.durationMs, metadata: item.metadata });
+        else this.define(item.name, { mode: 'charges', maxCharges: item.maxCharges, rechargeMs: item.rechargeMs, initialCharges: item.charges, sharedGroup: item.sharedGroup, metadata: item.metadata });
+      }
+      const e = this.get(item.name), now = this.manager.clock();
+      if (e.mode === 'classic' && item.mode === 'classic') { e.paused = !!item.paused; e.pausedRemaining = item.remainingMs; e.readyAt = now + Math.max(0, item.remainingMs - elapsed); if (!e.paused) e.readyAt = now + Math.max(0, item.remainingMs - elapsed); }
+      else if (e.mode === 'charges' && item.mode === 'charges') { const p = e.pool; p.charges = item.charges; p.paused = !!item.paused; p.pausedRemaining = item.pausedRemaining; p.queue = item.queueRemainingMs.map(ms => now + Math.max(0, ms - elapsed)); this._syncPool(p, now); }
+    }
+    return this;
+  }
+}
+
+export default Coolneur;

package/package.json

@@ -1,6 +1,63 @@
 {
   "name": "coolneur",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Cooldown and charge manager for JavaScript and TypeScript: classic timers, multi-charge abilities, scoped streams, pause/resume, snapshots, and deterministic clocks. Zero runtime dependencies.",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "llms.txt",
+    "llms-full.txt",
+    "examples"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "check": "node --check dist/index.js && node --check dist/index.cjs",
+    "prepack": "npm run check && npm test"
+  },
+  "keywords": [
+    "cooldown",
+    "cooldowns",
+    "cooldown-manager",
+    "cooldown-management",
+    "rate-limit",
+    "rate-limiting",
+    "throttle",
+    "timer",
+    "charges",
+    "multi-charge",
+    "charge-system",
+    "game-cooldown",
+    "ability-cooldown",
+    "javascript",
+    "typescript",
+    "zero-dependency",
+    "user-cooldown",
+    "guild-cooldown",
+    "channel-cooldown",
+    "command-cooldown"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jeffrish-benito/coolneur.git"
+  },
+  "homepage": "https://github.com/jeffrish-benito/coolneur#readme",
+  "bugs": {
+    "url": "https://github.com/jeffrish-benito/coolneur/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}