tally-ttl 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 PhoneCloud
+
+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

@@ -0,0 +1 @@
+# tally-ttl

package/dist/cjs/index.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TallyTTL = void 0;
+/**
+ * TallyTTL counts induvidual tallies per given ID with a time-to-live on a per-tally basis.
+ */
+class TallyTTL {
+    constructor(config = {}) {
+        this.store = {};
+        const { defaultTtl = 60, cleanupSeconds = 120000 } = config;
+        if (!Number.isFinite(defaultTtl) || defaultTtl <= 0) {
+            throw new Error("defaultTtlSeconds must be a positive finite number");
+        }
+        this.defaultTtl = defaultTtl;
+        this.cleanupInterval = setInterval(this.cleanup, cleanupSeconds);
+    }
+    /**
+     * Increment the tally for a given id and return the current count.
+     * @param id The identifier to tally.
+     * @param ttlSeconds Optional per-call TTL in seconds. Overrides constructor default when provided.
+     * @returns The count after incrementing.
+     */
+    tally(id, ttlSeconds) {
+        if (typeof id !== "string" || id.length === 0) {
+            throw new Error("id must be a non-empty string");
+        }
+        const ttl = this.resolveTtl(ttlSeconds);
+        const expiresAt = String(Date.now() + ttl * 1000);
+        this.store[id] = this.store[id] || {};
+        this.store[id][expiresAt] = (this.store[id][expiresAt] || 0) + 1;
+    }
+    increment(id) {
+        this.tally(id);
+    }
+    /**
+     * Get the current count without mutating. Returns 0 if missing or expired.
+     */
+    get(id) {
+        const now = Date.now();
+        let count = 0;
+        if (this.store[id]) {
+            for (const t of Object.keys(this.store[id])) {
+                if (Number(t) > now) {
+                    count += this.store[id][t] || 0;
+                }
+            }
+        }
+        return count;
+    }
+    /**
+     * Manually clear an id's tally.
+     */
+    clear(id) {
+        delete this.store[id];
+    }
+    /**
+     * Remove all expired entries. This is optional; entries are lazily reset on access.
+     */
+    cleanup() {
+        const now = Date.now();
+        for (const id of Object.keys(this.store)) {
+            if (this.store[id]) {
+                for (const t of Object.keys(this.store[id])) {
+                    if (Number(t) <= now)
+                        delete this.store[id][t];
+                }
+            }
+        }
+    }
+    resolveTtl(ttlSeconds) {
+        if (ttlSeconds === undefined)
+            return this.defaultTtl;
+        if (!Number.isFinite(ttlSeconds) || ttlSeconds <= 0) {
+            throw new Error("TallyTTL: ttlSeconds must be a positive finite number when provided");
+        }
+        return ttlSeconds;
+    }
+}
+exports.TallyTTL = TallyTTL;
+exports.default = TallyTTL;

package/dist/esm/index.d.ts

@@ -0,0 +1,18 @@
+export type TallyTTLConfig = {
+    defaultTtl?: number;
+    cleanupSeconds?: number;
+};
+export declare class TallyTTL {
+    private readonly defaultTtl;
+    private readonly store;
+    cleanupInterval: number;
+    constructor(config?: TallyTTLConfig);
+    tally(id: string, ttlSeconds?: number): void;
+    increment(id: string): void;
+    get(id: string): number;
+    clear(id: string): void;
+    cleanup(): void;
+    private resolveTtl;
+}
+export default TallyTTL;
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,cAAc,GAAG;IAC5B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAKF,qBAAa,QAAQ;IACpB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAIf;IAEP,eAAe,EAAE,MAAM,CAAC;gBAEZ,MAAM,GAAE,cAAmB;IAgBvC,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM;IAWrC,SAAS,CAAC,EAAE,EAAE,MAAM;IAOpB,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM;IAiBvB,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAOvB,OAAO,IAAI,IAAI;IAWf,OAAO,CAAC,UAAU;CAOlB;AAED,eAAe,QAAQ,CAAC"}

package/dist/esm/index.js

@@ -0,0 +1,58 @@
+export class TallyTTL {
+    constructor(config = {}) {
+        this.store = {};
+        const { defaultTtl = 60, cleanupSeconds = 120000 } = config;
+        if (!Number.isFinite(defaultTtl) || defaultTtl <= 0) {
+            throw new Error("defaultTtlSeconds must be a positive finite number");
+        }
+        this.defaultTtl = defaultTtl;
+        this.cleanupInterval = setInterval(this.cleanup, cleanupSeconds);
+    }
+    tally(id, ttlSeconds) {
+        if (typeof id !== "string" || id.length === 0) {
+            throw new Error("id must be a non-empty string");
+        }
+        const ttl = this.resolveTtl(ttlSeconds);
+        const expiresAt = String(Date.now() + ttl * 1000);
+        this.store[id] = this.store[id] || {};
+        this.store[id][expiresAt] = (this.store[id][expiresAt] || 0) + 1;
+    }
+    increment(id) {
+        this.tally(id);
+    }
+    get(id) {
+        const now = Date.now();
+        let count = 0;
+        if (this.store[id]) {
+            for (const t of Object.keys(this.store[id])) {
+                if (Number(t) > now) {
+                    count += this.store[id][t] || 0;
+                }
+            }
+        }
+        return count;
+    }
+    clear(id) {
+        delete this.store[id];
+    }
+    cleanup() {
+        const now = Date.now();
+        for (const id of Object.keys(this.store)) {
+            if (this.store[id]) {
+                for (const t of Object.keys(this.store[id])) {
+                    if (Number(t) <= now)
+                        delete this.store[id][t];
+                }
+            }
+        }
+    }
+    resolveTtl(ttlSeconds) {
+        if (ttlSeconds === undefined)
+            return this.defaultTtl;
+        if (!Number.isFinite(ttlSeconds) || ttlSeconds <= 0) {
+            throw new Error("TallyTTL: ttlSeconds must be a positive finite number when provided");
+        }
+        return ttlSeconds;
+    }
+}
+export default TallyTTL;

package/package.json

@@ -0,0 +1,48 @@
+{
+	"name": "tally-ttl",
+	"version": "0.5.0",
+	"description": "A simple library to tally items with a configurable per-tally TTL",
+	"keywords": [
+		"tally",
+		"counter",
+		"ttl",
+		"increment",
+		"expiring",
+		"auto-expire"
+	],
+	"homepage": "https://github.com/mattmacadams/tally-ttl#readme",
+	"bugs": {
+		"url": "https://github.com/mattmacadams/tally-ttl/issues"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/mattmacadams/tally-ttl.git"
+	},
+	"license": "CC0-1.0",
+	"author": "Matt MacAdams",
+	"type": "module",
+	"types": "./dist/esm/index.d.ts",
+	"scripts": {
+		"build:esm": "tsc -p tsconfig.esm.json",
+		"build:cjs": "tsc -p tsconfig.cjs.json",
+		"build": "rm -rf dist/* && npm run build:esm && npm run build:cjs",
+		"test": "echo \"Error: no test specified\" && exit 1"
+	},
+	"exports": {
+		".": {
+			"types": "./dist/esm/index.d.ts",
+			"import": "./dist/esm/index.js",
+			"require": "./dist/cjs/index.cjs"
+		}
+	},
+	"files": [
+		"dist",
+		"README.md",
+		"LICENSE"
+	],
+	"sideEffects": false,
+	"devDependencies": {
+		"prettier": "^3.7.4",
+		"typescript": "^5.9.3"
+	}
+}