@adriangalilea/utils 0.2.0 → 0.3.1

package/README.md

@@ -163,6 +163,7 @@ expect(() => assert(false, 'boom')).toThrow(Panic)
 - **Directory Operations**: Create, list, walk directories
 - **KEV**: Redis-style environment variable management with monorepo support
 - **XDG**: XDG Base Directory paths — reads env vars set by [xdg-dirs](https://github.com/adriangalilea/xdg-dirs), falls back to spec defaults
+- **Unseen**: Persistent dedup filter — "what's new since last time?" for cron/monitoring workflows
 - **Project Discovery**: Find project/monorepo roots, detect JS/TS projects
 
 ### XDG Base Directories
@@ -183,6 +184,21 @@ xdg.runtime('myapp')                   // $XDG_RUNTIME_DIR/myapp
 dir.create(xdg.state('notify'))
 ```
 
+### Unseen
+
+Persistent dedup filter — makes any script idempotent. Run it once or a thousand times, you only process each item once. Any scheduling works: manual, cron, a loop, whatever.
+
+```typescript
+import { unseen } from '@adriangalilea/utils'
+
+// only notifies on NEW orders — safe to run on any schedule
+const fresh = await unseen('orders', allOrders, o => o.id)
+for (const o of fresh) await notify(o.summary)
+// 1st run: 5 orders → notifies 5. 2nd run: same 5 → notifies 0. 3rd run: 7 → notifies 2.
+```
+
+State persists at `~/.local/state/unseen/{namespace}.json`.
+
 ## Release
 
 Bump version in `package.json` (and `jsr.json`), push to `main`. CI handles everything:

package/dist/index.d.ts

@@ -14,4 +14,5 @@ export * from './platform/path.js';
 export * from './platform/project.js';
 export * from './platform/kev.js';
 export * from './platform/xdg.js';
+export * from './platform/unseen.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AACtC,YAAY,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAA;AAGvD,cAAc,oBAAoB,CAAA;AAClC,cAAc,uBAAuB,CAAA;AACrC,cAAc,+BAA+B,CAAA;AAG7C,cAAc,gBAAgB,CAAA;AAI9B,cAAc,oBAAoB,CAAA;AAClC,cAAc,mBAAmB,CAAA;AACjC,cAAc,oBAAoB,CAAA;AAClC,cAAc,uBAAuB,CAAA;AACrC,cAAc,mBAAmB,CAAA;AACjC,cAAc,mBAAmB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AACtC,YAAY,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAA;AAGvD,cAAc,oBAAoB,CAAA;AAClC,cAAc,uBAAuB,CAAA;AACrC,cAAc,+BAA+B,CAAA;AAG7C,cAAc,gBAAgB,CAAA;AAI9B,cAAc,oBAAoB,CAAA;AAClC,cAAc,mBAAmB,CAAA;AACjC,cAAc,oBAAoB,CAAA;AAClC,cAAc,uBAAuB,CAAA;AACrC,cAAc,mBAAmB,CAAA;AACjC,cAAc,mBAAmB,CAAA;AACjC,cAAc,sBAAsB,CAAA"}

package/dist/index.js

@@ -18,4 +18,5 @@ export * from './platform/path.js';
 export * from './platform/project.js';
 export * from './platform/kev.js';
 export * from './platform/xdg.js';
+export * from './platform/unseen.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,8CAA8C;AAC9C,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAGtC,wCAAwC;AACxC,cAAc,oBAAoB,CAAA;AAClC,cAAc,uBAAuB,CAAA;AACrC,cAAc,+BAA+B,CAAA;AAE7C,yDAAyD;AACzD,cAAc,gBAAgB,CAAA;AAE9B,8BAA8B;AAC9B,mEAAmE;AACnE,cAAc,oBAAoB,CAAA;AAClC,cAAc,mBAAmB,CAAA;AACjC,cAAc,oBAAoB,CAAA;AAClC,cAAc,uBAAuB,CAAA;AACrC,cAAc,mBAAmB,CAAA;AACjC,cAAc,mBAAmB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,8CAA8C;AAC9C,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAGtC,wCAAwC;AACxC,cAAc,oBAAoB,CAAA;AAClC,cAAc,uBAAuB,CAAA;AACrC,cAAc,+BAA+B,CAAA;AAE7C,yDAAyD;AACzD,cAAc,gBAAgB,CAAA;AAE9B,8BAA8B;AAC9B,mEAAmE;AACnE,cAAc,oBAAoB,CAAA;AAClC,cAAc,mBAAmB,CAAA;AACjC,cAAc,oBAAoB,CAAA;AAClC,cAAc,uBAAuB,CAAA;AACrC,cAAc,mBAAmB,CAAA;AACjC,cAAc,mBAAmB,CAAA;AACjC,cAAc,sBAAsB,CAAA"}

package/dist/platform/unseen.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Persistent dedup filter — "what's new since last time?"
+ *
+ * Makes any script idempotent. Run it once, run it a thousand times —
+ * you only process each item once. This means any scheduling works:
+ * manual `tsx check.ts`, a fish loop, a cron job, whatever.
+ * Can't double-notify, can't miss items, can't corrupt state.
+ *
+ *   1st run: 5 orders exist  → returns 5
+ *   2nd run: same 5 orders   → returns 0
+ *   3rd run: 7 orders exist  → returns 2
+ *
+ * ```ts
+ * const fresh = await unseen('orders', allOrders, o => o.id)
+ * for (const o of fresh) await notify(o.summary)
+ * ```
+ *
+ * State persists at `~/.local/state/unseen/{namespace}.json`
+ *
+ * @param namespace - Seen-set name (e.g. 'messages', 'github-issues', 'orders')
+ * @param items - Items to filter
+ * @param key - Extract a unique string key from each item
+ * @returns Only items whose key hasn't been seen before
+ */
+export declare function unseen<T>(namespace: string, items: T[], key: (item: T) => string): Promise<T[]>;
+//# sourceMappingURL=unseen.d.ts.map

package/dist/platform/unseen.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unseen.d.ts","sourceRoot":"","sources":["../../src/platform/unseen.ts"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,MAAM,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,GAAG,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,MAAM,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC,CAmBrG"}

package/dist/platform/unseen.js

@@ -0,0 +1,45 @@
+import { xdg } from './xdg.js';
+import { dir } from './dir.js';
+import { file } from './file.js';
+import { join, dirname } from 'node:path';
+const STORE_DIR = xdg.state('unseen');
+/**
+ * Persistent dedup filter — "what's new since last time?"
+ *
+ * Makes any script idempotent. Run it once, run it a thousand times —
+ * you only process each item once. This means any scheduling works:
+ * manual `tsx check.ts`, a fish loop, a cron job, whatever.
+ * Can't double-notify, can't miss items, can't corrupt state.
+ *
+ *   1st run: 5 orders exist  → returns 5
+ *   2nd run: same 5 orders   → returns 0
+ *   3rd run: 7 orders exist  → returns 2
+ *
+ * ```ts
+ * const fresh = await unseen('orders', allOrders, o => o.id)
+ * for (const o of fresh) await notify(o.summary)
+ * ```
+ *
+ * State persists at `~/.local/state/unseen/{namespace}.json`
+ *
+ * @param namespace - Seen-set name (e.g. 'messages', 'github-issues', 'orders')
+ * @param items - Items to filter
+ * @param key - Extract a unique string key from each item
+ * @returns Only items whose key hasn't been seen before
+ */
+export async function unseen(namespace, items, key) {
+    const storePath = join(STORE_DIR, `${namespace}.json`);
+    dir.create(dirname(storePath));
+    const seen = new Set(file.exists(storePath) ? JSON.parse(file.readText(storePath)) : []);
+    const result = [];
+    for (const item of items) {
+        const k = key(item);
+        if (!seen.has(k)) {
+            seen.add(k);
+            result.push(item);
+        }
+    }
+    file.write(storePath, JSON.stringify([...seen]));
+    return result;
+}
+//# sourceMappingURL=unseen.js.map

package/dist/platform/unseen.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"unseen.js","sourceRoot":"","sources":["../../src/platform/unseen.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAA;AAC9B,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAA;AAC9B,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAChC,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAEzC,MAAM,SAAS,GAAG,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAA;AAErC;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,CAAC,KAAK,UAAU,MAAM,CAAI,SAAiB,EAAE,KAAU,EAAE,GAAwB;IACrF,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,EAAE,GAAG,SAAS,OAAO,CAAC,CAAA;IACtD,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAA;IAE9B,MAAM,IAAI,GAAgB,IAAI,GAAG,CAC/B,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAa,CAAC,CAAC,CAAC,EAAE,CAC/E,CAAA;IAED,MAAM,MAAM,GAAQ,EAAE,CAAA;IACtB,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,CAAC,GAAG,GAAG,CAAC,IAAI,CAAC,CAAA;QACnB,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;YACjB,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAA;YACX,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QACnB,CAAC;IACH,CAAC;IAED,IAAI,CAAC,KAAK,CAAC,SAAS,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAAA;IAChD,OAAO,MAAM,CAAA;AACf,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adriangalilea/utils",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "TypeScript utilities - logger, currency, formatter, and more",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",