@lp-labs/ttl-map 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Libin Prasanth
+
+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. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,86 @@
-# Temporary Holding Version
+# @lp-labs/ttl-map
 
-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.
+An entry-bounded expiring Map with an indexed minimum-deadline heap and an injected clock.
+
+## Install
+
+```sh
+npm install @lp-labs/ttl-map
+```
+
+Version 0.1.0. MIT. Zero runtime, peer, or sibling dependencies. Node >=18;
+browser-compatible ES2022 runtime without browser-global reads. ESM and CommonJS
+exports have separate matching declarations.
+
+## Quick start
+
+```js
+import { TtlMap } from '@lp-labs/ttl-map';
+let now = 0;
+const cache = new TtlMap({ maxEntries: 2, clock: () => now, refreshOnGet: true });
+cache.set('job', { ready: true }, 10);
+now = 9;
+if (!cache.get('job')?.ready) throw new Error('missing');
+now = 19; // refresh at 9 extended the deadline to 19
+if (cache.has('job')) throw new Error('expiry');
+console.log(cache.size);
+```
+
+## Contract, customization, errors and ownership
+
+Required `maxEntries` is a positive safe integer; required `clock()` returns a finite number in caller-chosen units. TTLs use those same units. `refreshOnGet` defaults false. No timers or Date/global-clock reads are used. Every public operation, including size/clear, samples the clock once, except set rejects a nonpositive/nonfinite TTL before sampling. Equal timestamps are accepted; a timestamp below the last accepted sample throws RangeError, rather than clamping. A successful sample advances the monotonic watermark even when a later validation/capacity error occurs. A throwing or reentrant clock callback changes no entries. Reentrant clock access throws Error.
+
+`set(key, value, ttl)` requires positive finite TTL and a finite deadline strictly greater than now (including floating-point precision checks). It purges expired entries first and updates an existing key in place. A live-capacity overflow throws RangeError without inserting or evicting live entries; expiry purging may already have committed. Invalid deadlines are rejected before purging. There are no eviction callbacks. Clock adapters must be synchronous; nonfunctions, nonnumeric samples and thenable samples throw TypeError before purging (async rejections are observed). `get` optionally refreshes to now plus that entry's original TTL; overflow throws without changing that entry's deadline, after normal purge. `has`, `entries`, and size do not refresh.
+
+Expiry is inclusive at the deadline: deadline <= now is absent. `purge` returns the number removed by that call. `delete` returns whether a live key was removed. `clear` removes all entries but does not reset the clock watermark. Missing get returns undefined; has distinguishes stored undefined. Entries preserve Map insertion order, with fresh tuples and shared key/value references.
+
+The heap stores exactly one node per live entry, without tombstones: O(log n) insert/update/delete/refresh, expected O(1) non-refresh lookup plus O(k log n) expiration work per operation. Entries O(n + k log n); clear O(n); space O(maxEntries). Synchronous only; not a persistence or distributed-clock cache.
+
+## Complete public declaration contract
+
+Runtime exports and all exported types are listed below. Internal storage members
+are omitted. Optional settings are constructor/function options, not globals.
+
+```ts
+export interface TtlOptions {
+  maxEntries: number;
+  clock: () => number;
+  refreshOnGet?: boolean;
+}
+/** Indexed expiry heap: no stale tombstones or background timers. */
+export declare class TtlMap<K, V> {
+  constructor(options: TtlOptions);
+  get size(): number;
+  purge(): number;
+  set(key: K, value: V, ttl: number): void;
+  get(key: K): V | undefined;
+  has(key: K): boolean;
+  delete(key: K): boolean;
+  clear(): void;
+  entries(): [K, V][];
+}
+```
+
+## Development
+
+```sh
+npm ci --offline
+npm run build
+npm run typecheck
+npm test
+npm run format:check
+```
+
+TypeScript ^5.9.3 and Prettier ^3.6.2 are development-only. Offline installation
+requires their locked packages already in the local npm cache. Build emits
+dist/esm and dist/cjs with separate declarations; tests exercise runtime behavior
+and bare-package ESM/CommonJS type consumers with negative checks. No publish
+step is needed to build or test.
+
+## Support
+
+If this library is useful to you, consider supporting its maintenance with a [donation via PayPal](https://www.paypal.me/LibinPrasanth).
+
+## Author
+
+Created by [Libin Prasanth](https://www.linkedin.com/in/libinprasanth/). Connect on LinkedIn for updates and discussion.

package/dist/cjs/index.d.ts

@@ -0,0 +1,30 @@
+export interface TtlOptions {
+    maxEntries: number;
+    clock: () => number;
+    refreshOnGet?: boolean;
+}
+/** Indexed expiry heap: no stale tombstones or background timers. */
+export declare class TtlMap<K, V> {
+    private readonly data;
+    private readonly heap;
+    private last;
+    private readingClock;
+    private readonly maximum;
+    private readonly clock;
+    private readonly refresh;
+    constructor(options: TtlOptions);
+    private now;
+    private swap;
+    private fix;
+    private remove;
+    private expire;
+    private deadline;
+    get size(): number;
+    purge(): number;
+    set(key: K, value: V, ttl: number): void;
+    get(key: K): V | undefined;
+    has(key: K): boolean;
+    delete(key: K): boolean;
+    clear(): void;
+    entries(): [K, V][];
+}

package/dist/cjs/index.js

@@ -0,0 +1,158 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TtlMap = void 0;
+/** Indexed expiry heap: no stale tombstones or background timers. */
+class TtlMap {
+    data = new Map();
+    heap = [];
+    last = -Infinity;
+    readingClock = false;
+    maximum;
+    clock;
+    refresh;
+    constructor(options) {
+        if (typeof options.clock !== 'function')
+            throw new TypeError('Expected clock callback');
+        if (!Number.isSafeInteger(options.maxEntries) || options.maxEntries < 1)
+            throw new RangeError('maxEntries must be positive');
+        this.maximum = options.maxEntries;
+        this.clock = options.clock;
+        this.refresh = options.refreshOnGet ?? false;
+    }
+    now() {
+        if (this.readingClock)
+            throw new Error('Reentrant clock access');
+        let now;
+        this.readingClock = true;
+        try {
+            const sample = this.clock();
+            if (sample !== null &&
+                (typeof sample === 'object' || typeof sample === 'function') &&
+                typeof sample.then === 'function') {
+                void Promise.resolve(sample).catch(() => { });
+                throw new TypeError('Clock must be synchronous');
+            }
+            if (typeof sample !== 'number')
+                throw new TypeError('Clock must return a number');
+            now = sample;
+        }
+        finally {
+            this.readingClock = false;
+        }
+        if (!Number.isFinite(now) || now < this.last)
+            throw new RangeError('Clock must be finite and monotonic');
+        this.last = now;
+        return now;
+    }
+    swap(a, b) {
+        const x = this.heap[a], y = this.heap[b];
+        this.heap[a] = y;
+        this.heap[b] = x;
+        y.index = a;
+        x.index = b;
+    }
+    fix(index) {
+        while (index > 0) {
+            const parent = Math.floor((index - 1) / 2);
+            if (this.heap[parent].deadline <= this.heap[index].deadline)
+                break;
+            this.swap(parent, index);
+            index = parent;
+        }
+        while (index * 2 + 1 < this.heap.length) {
+            let child = index * 2 + 1;
+            if (child + 1 < this.heap.length &&
+                this.heap[child + 1].deadline < this.heap[child].deadline)
+                child++;
+            if (this.heap[index].deadline <= this.heap[child].deadline)
+                break;
+            this.swap(index, child);
+            index = child;
+        }
+    }
+    remove(entry) {
+        const index = entry.index, tail = this.heap.pop();
+        this.data.delete(entry.key);
+        if (index < this.heap.length) {
+            this.heap[index] = tail;
+            tail.index = index;
+            this.fix(index);
+        }
+    }
+    expire(now) {
+        let removed = 0;
+        while (this.heap.length && this.heap[0].deadline <= now) {
+            this.remove(this.heap[0]);
+            removed++;
+        }
+        return removed;
+    }
+    deadline(now, ttl) {
+        const end = now + ttl;
+        if (!Number.isFinite(ttl) || ttl <= 0 || !Number.isFinite(end) || end <= now)
+            throw new RangeError('TTL must produce a finite future deadline');
+        return end;
+    }
+    get size() {
+        this.expire(this.now());
+        return this.data.size;
+    }
+    purge() {
+        return this.expire(this.now());
+    }
+    set(key, value, ttl) {
+        if (!Number.isFinite(ttl) || ttl <= 0)
+            throw new RangeError('TTL must be positive and finite');
+        const now = this.now(), deadline = this.deadline(now, ttl);
+        this.expire(now);
+        const previous = this.data.get(key);
+        if (previous) {
+            previous.value = value;
+            previous.ttl = ttl;
+            previous.deadline = deadline;
+            this.fix(previous.index);
+            return;
+        }
+        if (this.data.size === this.maximum)
+            throw new RangeError('maxEntries exceeded');
+        const entry = { key, value, ttl, deadline, index: this.heap.length };
+        this.data.set(key, entry);
+        this.heap.push(entry);
+        this.fix(entry.index);
+    }
+    get(key) {
+        const now = this.now();
+        this.expire(now);
+        const entry = this.data.get(key);
+        if (!entry)
+            return undefined;
+        if (this.refresh) {
+            const deadline = this.deadline(now, entry.ttl);
+            entry.deadline = deadline;
+            this.fix(entry.index);
+        }
+        return entry.value;
+    }
+    has(key) {
+        this.expire(this.now());
+        return this.data.has(key);
+    }
+    delete(key) {
+        this.expire(this.now());
+        const entry = this.data.get(key);
+        if (!entry)
+            return false;
+        this.remove(entry);
+        return true;
+    }
+    clear() {
+        this.now();
+        this.data.clear();
+        this.heap.length = 0;
+    }
+    entries() {
+        this.expire(this.now());
+        return [...this.data.values()].map((e) => [e.key, e.value]);
+    }
+}
+exports.TtlMap = TtlMap;

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist/esm/index.d.ts

@@ -0,0 +1,30 @@
+export interface TtlOptions {
+    maxEntries: number;
+    clock: () => number;
+    refreshOnGet?: boolean;
+}
+/** Indexed expiry heap: no stale tombstones or background timers. */
+export declare class TtlMap<K, V> {
+    private readonly data;
+    private readonly heap;
+    private last;
+    private readingClock;
+    private readonly maximum;
+    private readonly clock;
+    private readonly refresh;
+    constructor(options: TtlOptions);
+    private now;
+    private swap;
+    private fix;
+    private remove;
+    private expire;
+    private deadline;
+    get size(): number;
+    purge(): number;
+    set(key: K, value: V, ttl: number): void;
+    get(key: K): V | undefined;
+    has(key: K): boolean;
+    delete(key: K): boolean;
+    clear(): void;
+    entries(): [K, V][];
+}

package/dist/esm/index.js

@@ -0,0 +1,154 @@
+/** Indexed expiry heap: no stale tombstones or background timers. */
+export class TtlMap {
+    data = new Map();
+    heap = [];
+    last = -Infinity;
+    readingClock = false;
+    maximum;
+    clock;
+    refresh;
+    constructor(options) {
+        if (typeof options.clock !== 'function')
+            throw new TypeError('Expected clock callback');
+        if (!Number.isSafeInteger(options.maxEntries) || options.maxEntries < 1)
+            throw new RangeError('maxEntries must be positive');
+        this.maximum = options.maxEntries;
+        this.clock = options.clock;
+        this.refresh = options.refreshOnGet ?? false;
+    }
+    now() {
+        if (this.readingClock)
+            throw new Error('Reentrant clock access');
+        let now;
+        this.readingClock = true;
+        try {
+            const sample = this.clock();
+            if (sample !== null &&
+                (typeof sample === 'object' || typeof sample === 'function') &&
+                typeof sample.then === 'function') {
+                void Promise.resolve(sample).catch(() => { });
+                throw new TypeError('Clock must be synchronous');
+            }
+            if (typeof sample !== 'number')
+                throw new TypeError('Clock must return a number');
+            now = sample;
+        }
+        finally {
+            this.readingClock = false;
+        }
+        if (!Number.isFinite(now) || now < this.last)
+            throw new RangeError('Clock must be finite and monotonic');
+        this.last = now;
+        return now;
+    }
+    swap(a, b) {
+        const x = this.heap[a], y = this.heap[b];
+        this.heap[a] = y;
+        this.heap[b] = x;
+        y.index = a;
+        x.index = b;
+    }
+    fix(index) {
+        while (index > 0) {
+            const parent = Math.floor((index - 1) / 2);
+            if (this.heap[parent].deadline <= this.heap[index].deadline)
+                break;
+            this.swap(parent, index);
+            index = parent;
+        }
+        while (index * 2 + 1 < this.heap.length) {
+            let child = index * 2 + 1;
+            if (child + 1 < this.heap.length &&
+                this.heap[child + 1].deadline < this.heap[child].deadline)
+                child++;
+            if (this.heap[index].deadline <= this.heap[child].deadline)
+                break;
+            this.swap(index, child);
+            index = child;
+        }
+    }
+    remove(entry) {
+        const index = entry.index, tail = this.heap.pop();
+        this.data.delete(entry.key);
+        if (index < this.heap.length) {
+            this.heap[index] = tail;
+            tail.index = index;
+            this.fix(index);
+        }
+    }
+    expire(now) {
+        let removed = 0;
+        while (this.heap.length && this.heap[0].deadline <= now) {
+            this.remove(this.heap[0]);
+            removed++;
+        }
+        return removed;
+    }
+    deadline(now, ttl) {
+        const end = now + ttl;
+        if (!Number.isFinite(ttl) || ttl <= 0 || !Number.isFinite(end) || end <= now)
+            throw new RangeError('TTL must produce a finite future deadline');
+        return end;
+    }
+    get size() {
+        this.expire(this.now());
+        return this.data.size;
+    }
+    purge() {
+        return this.expire(this.now());
+    }
+    set(key, value, ttl) {
+        if (!Number.isFinite(ttl) || ttl <= 0)
+            throw new RangeError('TTL must be positive and finite');
+        const now = this.now(), deadline = this.deadline(now, ttl);
+        this.expire(now);
+        const previous = this.data.get(key);
+        if (previous) {
+            previous.value = value;
+            previous.ttl = ttl;
+            previous.deadline = deadline;
+            this.fix(previous.index);
+            return;
+        }
+        if (this.data.size === this.maximum)
+            throw new RangeError('maxEntries exceeded');
+        const entry = { key, value, ttl, deadline, index: this.heap.length };
+        this.data.set(key, entry);
+        this.heap.push(entry);
+        this.fix(entry.index);
+    }
+    get(key) {
+        const now = this.now();
+        this.expire(now);
+        const entry = this.data.get(key);
+        if (!entry)
+            return undefined;
+        if (this.refresh) {
+            const deadline = this.deadline(now, entry.ttl);
+            entry.deadline = deadline;
+            this.fix(entry.index);
+        }
+        return entry.value;
+    }
+    has(key) {
+        this.expire(this.now());
+        return this.data.has(key);
+    }
+    delete(key) {
+        this.expire(this.now());
+        const entry = this.data.get(key);
+        if (!entry)
+            return false;
+        this.remove(entry);
+        return true;
+    }
+    clear() {
+        this.now();
+        this.data.clear();
+        this.heap.length = 0;
+    }
+    entries() {
+        this.expire(this.now());
+        return [...this.data.values()].map((e) => [e.key, e.value]);
+    }
+}

package/package.json

@@ -1,6 +1,63 @@
 {
   "name": "@lp-labs/ttl-map",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "An entry-bounded expiring Map with an indexed minimum-deadline heap and an injected clock.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "typecheck": "npm run build && node scripts/check-types.mjs",
+    "test": "npm run build && node --test tests/*.test.mjs",
+    "format": "prettier --write src scripts tests *.json README.md",
+    "format:check": "prettier --check src scripts tests *.json README.md",
+    "prepack": "npm run build"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "prettier": "^3.6.2"
+  },
+  "prettier": {
+    "singleQuote": true,
+    "semi": true,
+    "trailingComma": "all",
+    "printWidth": 100,
+    "endOfLine": "lf"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "author": {
+    "name": "Libin Prasanth",
+    "url": "https://www.linkedin.com/in/libinprasanth/"
+  },
+  "funding": {
+    "type": "paypal",
+    "url": "https://www.paypal.me/LibinPrasanth"
+  }
+}