@adriangalilea/utils 0.1.0 → 0.3.0

package/README.md

@@ -162,8 +162,43 @@ expect(() => assert(false, 'boom')).toThrow(Panic)
 - **File Operations**: Read, write with automatic path resolution
 - **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
+
+XDG paths that respect env vars from [xdg-dirs](https://github.com/adriangalilea/xdg-dirs) with spec-compliant fallbacks:
+
+```typescript
+import { xdg, dir } from '@adriangalilea/utils'
+
+xdg.state('notify')                    // ~/.local/state/notify
+xdg.state('notify', 'watchers.json')   // ~/.local/state/notify/watchers.json
+xdg.config('myapp')                    // ~/.config/myapp
+xdg.data('myapp')                      // ~/.local/share/myapp
+xdg.cache('myapp')                     // ~/.cache/myapp
+xdg.runtime('myapp')                   // $XDG_RUNTIME_DIR/myapp
+
+// Ensure the directory exists before writing
+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

@@ -13,4 +13,6 @@ export * from './platform/dir.js';
 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"}
+{"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

@@ -17,4 +17,6 @@ export * from './platform/dir.js';
 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"}
+{"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 } 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) {
+    dir.create(STORE_DIR);
+    const storePath = join(STORE_DIR, `${namespace}.json`);
+    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,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"}

package/dist/platform/xdg.d.ts

@@ -0,0 +1,8 @@
+export declare const xdg: {
+    config: (...segments: string[]) => string;
+    data: (...segments: string[]) => string;
+    state: (...segments: string[]) => string;
+    cache: (...segments: string[]) => string;
+    runtime: (...segments: string[]) => string;
+};
+//# sourceMappingURL=xdg.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"xdg.d.ts","sourceRoot":"","sources":["../../src/platform/xdg.ts"],"names":[],"mappings":"AAMA,eAAO,MAAM,GAAG;0BACS,MAAM,EAAE;wBACR,MAAM,EAAE;yBACR,MAAM,EAAE;yBACR,MAAM,EAAE;2BACR,MAAM,EAAE;CAChC,CAAA"}

package/dist/platform/xdg.js

@@ -0,0 +1,12 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+const home = homedir();
+const env = (key, fallback) => process.env[key] || fallback;
+export const xdg = {
+    config: (...segments) => join(env('XDG_CONFIG_HOME', join(home, '.config')), ...segments),
+    data: (...segments) => join(env('XDG_DATA_HOME', join(home, '.local', 'share')), ...segments),
+    state: (...segments) => join(env('XDG_STATE_HOME', join(home, '.local', 'state')), ...segments),
+    cache: (...segments) => join(env('XDG_CACHE_HOME', join(home, '.cache')), ...segments),
+    runtime: (...segments) => join(env('XDG_RUNTIME_DIR', join(home, '.local', 'run')), ...segments),
+};
+//# sourceMappingURL=xdg.js.map

package/dist/platform/xdg.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"xdg.js","sourceRoot":"","sources":["../../src/platform/xdg.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAA;AACjC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAEhC,MAAM,IAAI,GAAG,OAAO,EAAE,CAAA;AACtB,MAAM,GAAG,GAAG,CAAC,GAAW,EAAE,QAAgB,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,QAAQ,CAAA;AAE3E,MAAM,CAAC,MAAM,GAAG,GAAG;IACjB,MAAM,EAAG,CAAC,GAAG,QAAkB,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,iBAAiB,EAAE,IAAI,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC,EAAE,GAAG,QAAQ,CAAC;IACpG,IAAI,EAAK,CAAC,GAAG,QAAkB,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,eAAe,EAAE,IAAI,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC,EAAE,GAAG,QAAQ,CAAC;IAC1G,KAAK,EAAI,CAAC,GAAG,QAAkB,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,gBAAgB,EAAE,IAAI,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC,EAAE,GAAG,QAAQ,CAAC;IAC3G,KAAK,EAAI,CAAC,GAAG,QAAkB,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,gBAAgB,EAAE,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,EAAE,GAAG,QAAQ,CAAC;IAClG,OAAO,EAAE,CAAC,GAAG,QAAkB,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,iBAAiB,EAAE,IAAI,CAAC,IAAI,EAAE,QAAQ,EAAE,KAAK,CAAC,CAAC,EAAE,GAAG,QAAQ,CAAC;CAC3G,CAAA"}

package/package.json

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