beardos-toolbox 0.1.0

package/dist/timestamp-gate.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Minimal in-memory singleton for per-ID timestamp gating.
+ * - Stores only last-allowed timestamps (ms since epoch) per id.
+ * - Call check(id) to check & update atomically:
+ *    - If first time or elapsed >= ttlMs -> sets now and returns true
+ *    - Otherwise returns false (unchanged)
+ * - Pass your own `now` when batching or testing.
+ */
+export declare class TimestampGate {
+    private static _instance;
+    private readonly store;
+    private readonly defaultTTL;
+    private constructor();
+    /** Get the single shared instance. */
+    static get instance(): TimestampGate;
+    /**
+     * Check if `id` is allowed based on `ttl`. If allowed, persist `now`.
+     * @param {string} id      Unique key to gate.
+     * @param {number} now     Optional timestamp (ms). Defaults to Date.now() for minimal overhead.
+     * @param {number?} ttl    Time-to-live in milliseconds.
+     * @returns true if allowed (and stored), false otherwise.
+     */
+    check(id: string, now?: number, ttl?: number): boolean;
+    /**
+     * Peek the last-allowed timestamp (ms) for `id`.
+     * @returns number | undefined
+     */
+    get(id: string): number | undefined;
+    /**
+     * Manually set a last-allowed timestamp (ms) for `id`.
+     * Useful for backfilling/imports.
+     */
+    set(id: string, timestampMs: number): void;
+    /** Remove a single id. */
+    delete(id: string): void;
+    /** Drop everything (helps if you shard or rotate caches). */
+    clear(): void;
+    /**
+     * Optional: prune entries whose last timestamp is older than `cutoffMs`.
+     * Keeps memory lean if there is other operations that run on a schedules
+     * or with enough frequency to effectively
+     */
+    pruneFrom(cutoffMs: number): void;
+    /** Current number of tracked ids (for diagnostics). */
+    size(): number;
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "beardos-toolbox",
+  "version": "0.1.0",
+  "description": "Handy scripts and libs that I don't want to write again but don't need their own individual repos",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "node build.mjs",
+    "test": "node --import tsx --test **/*.test.ts",
+    "test:watch": "node --import tsx --test --watch **/*.test.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "@aws-sdk/client-s3": ">=3"
+  },
+  "peerDependenciesMeta": {
+    "@aws-sdk/client-s3": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@aws-sdk/client-s3": "^3.0.0",
+    "@types/node": "^22.0.0",
+    "esbuild": "^0.25.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.0.0"
+  },
+  "keywords": [],
+  "author": "Aaron Toomey <aaron@inkiebeard.codes>",
+  "license": "MIT"
+}