@adriangalilea/utils 0.3.0 → 0.4.0

package/README.md

@@ -186,17 +186,22 @@ 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.
+Persistent dedup filter for arrays of objects. Remembers which IDs it has seen across runs, returns only the new ones.
 
 ```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.
+type Message = { id: string, text: string }
+
+const messages: Message[] = await fetchMessages()
+const newMessages = await unseen('messages', messages, 'id')
+// 1st run: 3 messages → returns 3. 2nd run: same 3 → returns []. 3rd run: 5 → returns 2 new.
+
+for (const m of newMessages) console.log(m.text)
 ```
 
+The third argument is the field name that uniquely identifies each item (e.g. `'id'`, `'messageId'`, `'bdnsCode'`). Type-safe — autocompletes valid fields, catches typos at compile time.
+
 State persists at `~/.local/state/unseen/{namespace}.json`.
 
 ## Release

package/dist/platform/unseen.d.ts

@@ -1,26 +1,29 @@
 /**
- * Persistent dedup filter — "what's new since last time?"
+ * Persistent dedup filter for arrays of objects.
  *
- * 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
+ * You have objects with IDs. `unseen` remembers which IDs it has
+ * seen across runs and returns only the new ones.
  *
  * ```ts
- * const fresh = await unseen('orders', allOrders, o => o.id)
- * for (const o of fresh) await notify(o.summary)
+ * type Message = { id: string, text: string }
+ *
+ * const messages: Message[] = await fetchMessages()
+ * const newMessages = await unseen('messages', messages, 'id')
+ *
+ * // 1st run: 3 messages exist  → returns all 3
+ * // 2nd run: same 3 messages   → returns []
+ * // 3rd run: 5 messages exist  → returns the 2 new ones
  * ```
  *
+ * Makes any script idempotent — run it once or a thousand times,
+ * you only process each item once. Any scheduling works.
+ *
  * 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
+ * @param namespace - Name for this seen-set (e.g. 'messages', 'orders')
+ * @param items - Array of objects to filter
+ * @param key - Which field is the unique ID (e.g. 'id', 'messageId', 'bdnsCode')
+ * @returns Only items not seen in previous runs
  */
-export declare function unseen<T>(namespace: string, items: T[], key: (item: T) => string): Promise<T[]>;
+export declare function unseen<T>(namespace: string, items: T[], key: keyof T & string): Promise<T[]>;
 //# sourceMappingURL=unseen.d.ts.map

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

@@ -1 +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"}
+{"version":3,"file":"unseen.d.ts","sourceRoot":"","sources":["../../src/platform/unseen.ts"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAsB,MAAM,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC,CAmBlG"}

package/dist/platform/unseen.js

@@ -1,41 +1,44 @@
 import { xdg } from './xdg.js';
 import { dir } from './dir.js';
 import { file } from './file.js';
-import { join } from 'node:path';
+import { join, dirname } from 'node:path';
 const STORE_DIR = xdg.state('unseen');
 /**
- * Persistent dedup filter — "what's new since last time?"
+ * Persistent dedup filter for arrays of objects.
  *
- * 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
+ * You have objects with IDs. `unseen` remembers which IDs it has
+ * seen across runs and returns only the new ones.
  *
  * ```ts
- * const fresh = await unseen('orders', allOrders, o => o.id)
- * for (const o of fresh) await notify(o.summary)
+ * type Message = { id: string, text: string }
+ *
+ * const messages: Message[] = await fetchMessages()
+ * const newMessages = await unseen('messages', messages, 'id')
+ *
+ * // 1st run: 3 messages exist  → returns all 3
+ * // 2nd run: same 3 messages   → returns []
+ * // 3rd run: 5 messages exist  → returns the 2 new ones
  * ```
  *
+ * Makes any script idempotent — run it once or a thousand times,
+ * you only process each item once. Any scheduling works.
+ *
  * 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
+ * @param namespace - Name for this seen-set (e.g. 'messages', 'orders')
+ * @param items - Array of objects to filter
+ * @param key - Which field is the unique ID (e.g. 'id', 'messageId', 'bdnsCode')
+ * @returns Only items not seen in previous runs
  */
 export async function unseen(namespace, items, key) {
-    dir.create(STORE_DIR);
     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);
+        const id = String(item[key]);
+        if (!seen.has(id)) {
+            seen.add(id);
             result.push(item);
         }
     }

package/dist/platform/unseen.js.map

@@ -1 +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,MAAM,WAAW,CAAA;AAEhC,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,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAA;IACrB,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,EAAE,GAAG,SAAS,OAAO,CAAC,CAAA;IAEtD,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"}
+{"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;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,CAAC,KAAK,UAAU,MAAM,CAAI,SAAiB,EAAE,KAAU,EAAE,GAAqB;IAClF,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,EAAE,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAA;QAC5B,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC;YAClB,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAA;YACZ,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.3.0",
+  "version": "0.4.0",
   "description": "TypeScript utilities - logger, currency, formatter, and more",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",