@mantajs/adapter-cache-upstash 0.2.0-beta.0

package/dist/adapter.d.ts

@@ -0,0 +1,16 @@
+import { type ICachePort } from '@mantajs/core';
+export interface UpstashCacheOptions {
+    url?: string;
+    token?: string;
+}
+export declare class UpstashCacheAdapter implements ICachePort {
+    private _redis;
+    constructor(options?: UpstashCacheOptions);
+    get(key: string): Promise<unknown>;
+    set(key: string, data: unknown, ttl?: number): Promise<void>;
+    invalidate(key: string): Promise<void>;
+    clear(): Promise<void>;
+    ping(): Promise<boolean>;
+    _reset(): void;
+}
+//# sourceMappingURL=adapter.d.ts.map

package/dist/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,UAAU,EAAc,MAAM,eAAe,CAAA;AAG3D,MAAM,WAAW,mBAAmB;IAClC,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED,qBAAa,mBAAoB,YAAW,UAAU;IACpD,OAAO,CAAC,MAAM,CAAO;gBAET,OAAO,GAAE,mBAAwB;IAcvC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAKlC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAS5D,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAItC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAItB,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC;IAW9B,MAAM;CAGP"}

package/dist/adapter.js

@@ -0,0 +1,48 @@
+// SPEC-064/077 — UpstashCacheAdapter implements ICachePort
+import { MantaError } from '@mantajs/core';
+import { Redis } from '@upstash/redis';
+export class UpstashCacheAdapter {
+    _redis;
+    constructor(options = {}) {
+        const url = options.url ?? process.env.UPSTASH_REDIS_REST_URL;
+        const token = options.token ?? process.env.UPSTASH_REDIS_REST_TOKEN;
+        if (!url || !token) {
+            throw new MantaError('INVALID_DATA', 'UpstashCacheAdapter requires UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN (env or constructor options)');
+        }
+        this._redis = new Redis({ url, token });
+    }
+    async get(key) {
+        const value = await this._redis.get(key);
+        return value ?? null;
+    }
+    async set(key, data, ttl) {
+        const value = typeof data === 'string' ? data : JSON.stringify(data);
+        if (ttl && ttl > 0) {
+            await this._redis.set(key, value, { ex: ttl });
+        }
+        else {
+            await this._redis.set(key, value);
+        }
+    }
+    async invalidate(key) {
+        await this._redis.del(key);
+    }
+    async clear() {
+        await this._redis.flushdb();
+    }
+    async ping() {
+        // Upstash Redis exposes PING as a REST command. Any successful response
+        // (typically "PONG") means the backend is reachable.
+        try {
+            const result = await this._redis.ping();
+            return result !== null && result !== undefined;
+        }
+        catch {
+            return false;
+        }
+    }
+    _reset() {
+        this._redis.flushdb();
+    }
+}
+//# sourceMappingURL=adapter.js.map

package/dist/adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.js","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAAA,2DAA2D;AAE3D,OAAO,EAAmB,UAAU,EAAE,MAAM,eAAe,CAAA;AAC3D,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAA;AAOtC,MAAM,OAAO,mBAAmB;IACtB,MAAM,CAAO;IAErB,YAAY,UAA+B,EAAE;QAC3C,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC,sBAAsB,CAAA;QAC7D,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,OAAO,CAAC,GAAG,CAAC,wBAAwB,CAAA;QAEnE,IAAI,CAAC,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC;YACnB,MAAM,IAAI,UAAU,CAClB,cAAc,EACd,+GAA+G,CAChH,CAAA;QACH,CAAC;QAED,IAAI,CAAC,MAAM,GAAG,IAAI,KAAK,CAAC,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,CAAA;IACzC,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,GAAW;QACnB,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;QACxC,OAAO,KAAK,IAAI,IAAI,CAAA;IACtB,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,GAAW,EAAE,IAAa,EAAE,GAAY;QAChD,MAAM,KAAK,GAAG,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAA;QACpE,IAAI,GAAG,IAAI,GAAG,GAAG,CAAC,EAAE,CAAC;YACnB,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE,GAAG,EAAE,CAAC,CAAA;QAChD,CAAC;aAAM,CAAC;YACN,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAA;QACnC,CAAC;IACH,CAAC;IAED,KAAK,CAAC,UAAU,CAAC,GAAW;QAC1B,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;IAC5B,CAAC;IAED,KAAK,CAAC,KAAK;QACT,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAA;IAC7B,CAAC;IAED,KAAK,CAAC,IAAI;QACR,wEAAwE;QACxE,qDAAqD;QACrD,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAO,IAAI,CAAC,MAAsD,CAAC,IAAI,EAAE,CAAA;YACxF,OAAO,MAAM,KAAK,IAAI,IAAI,MAAM,KAAK,SAAS,CAAA;QAChD,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAK,CAAA;QACd,CAAC;IACH,CAAC;IAED,MAAM;QACJ,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAA;IACvB,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export type { UpstashCacheOptions } from './adapter';
+export { UpstashCacheAdapter } from './adapter';
+export type { UpstashProgressChannelOptions } from './progress-channel';
+export { UpstashProgressChannel } from './progress-channel';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,YAAY,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAA;AACpD,OAAO,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAA;AAC/C,YAAY,EAAE,6BAA6B,EAAE,MAAM,oBAAoB,CAAA;AACvE,OAAO,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAA"}

package/dist/index.js

@@ -0,0 +1,4 @@
+// SPEC-064/077 — @mantajs/adapter-cache-upstash barrel export
+export { UpstashCacheAdapter } from './adapter';
+export { UpstashProgressChannel } from './progress-channel';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,8DAA8D;AAG9D,OAAO,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAA;AAE/C,OAAO,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAA"}

package/dist/progress-channel.d.ts

@@ -0,0 +1,26 @@
+import type { ILoggerPort, IProgressChannelPort, ProgressSnapshot } from '@mantajs/core';
+import { Redis } from '@upstash/redis';
+export interface UpstashProgressChannelOptions {
+    url?: string;
+    token?: string;
+}
+/**
+ * Progress channel backed by Upstash Redis.
+ *
+ * Accepts either a pre-built `Redis` client (preferred — reuses the cache
+ * adapter's client) or the same credentials the cache adapter uses.
+ *
+ * @example
+ * const channel = new UpstashProgressChannel(redisClient, { logger })
+ */
+export declare class UpstashProgressChannel implements IProgressChannelPort {
+    private _redis;
+    private _logger?;
+    constructor(clientOrOptions?: Redis | UpstashProgressChannelOptions, deps?: {
+        logger?: ILoggerPort;
+    });
+    set(runId: string, snapshot: ProgressSnapshot): Promise<void>;
+    get(runId: string): Promise<ProgressSnapshot | null>;
+    clear(runId: string): Promise<void>;
+}
+//# sourceMappingURL=progress-channel.d.ts.map

package/dist/progress-channel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"progress-channel.d.ts","sourceRoot":"","sources":["../src/progress-channel.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,WAAW,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAA;AAExF,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAA;AAItC,MAAM,WAAW,6BAA6B;IAC5C,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAMD;;;;;;;;GAQG;AACH,qBAAa,sBAAuB,YAAW,oBAAoB;IACjE,OAAO,CAAC,MAAM,CAAO;IACrB,OAAO,CAAC,OAAO,CAAC,CAAa;gBAEjB,eAAe,GAAE,KAAK,GAAG,6BAAkC,EAAE,IAAI,GAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAO;IAsBtG,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAS7D,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC;IAcpD,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAG1C"}

package/dist/progress-channel.js

@@ -0,0 +1,67 @@
+// UpstashProgressChannel — ephemeral workflow progress via Upstash Redis.
+// Implements IProgressChannelPort — see WORKFLOW_PROGRESS.md §5.2 and §9.2.
+//
+// Key format: `workflow:{runId}:progress` (spec §4 architecture diagram).
+// TTL: 3600 seconds (spec §5.2 "TTL 1h").
+// `set()` MUST NOT throw — channel errors are logged, not propagated (§10.2 invariant #2).
+import { MantaError } from '@mantajs/core';
+import { Redis } from '@upstash/redis';
+const TTL_SECONDS = 3600;
+function progressKey(runId) {
+    return `workflow:${runId}:progress`;
+}
+/**
+ * Progress channel backed by Upstash Redis.
+ *
+ * Accepts either a pre-built `Redis` client (preferred — reuses the cache
+ * adapter's client) or the same credentials the cache adapter uses.
+ *
+ * @example
+ * const channel = new UpstashProgressChannel(redisClient, { logger })
+ */
+export class UpstashProgressChannel {
+    _redis;
+    _logger;
+    constructor(clientOrOptions = {}, deps = {}) {
+        this._logger = deps.logger;
+        if (clientOrOptions instanceof Redis) {
+            this._redis = clientOrOptions;
+            return;
+        }
+        const options = clientOrOptions;
+        const url = options.url ?? process.env.UPSTASH_REDIS_REST_URL;
+        const token = options.token ?? process.env.UPSTASH_REDIS_REST_TOKEN;
+        if (!url || !token) {
+            throw new MantaError('INVALID_DATA', 'UpstashProgressChannel requires UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN (env or constructor options)');
+        }
+        this._redis = new Redis({ url, token });
+    }
+    async set(runId, snapshot) {
+        try {
+            await this._redis.set(progressKey(runId), JSON.stringify(snapshot), { ex: TTL_SECONDS });
+        }
+        catch (err) {
+            // Invariant #2: never throw. Log and swallow.
+            this._logger?.warn('progress write failed', { err, runId, stepName: snapshot.stepName });
+        }
+    }
+    async get(runId) {
+        const raw = await this._redis.get(progressKey(runId));
+        if (raw === null || raw === undefined)
+            return null;
+        if (typeof raw === 'string') {
+            try {
+                return JSON.parse(raw);
+            }
+            catch {
+                return null;
+            }
+        }
+        // Upstash auto-parses JSON for some payloads — accept already-parsed objects.
+        return raw;
+    }
+    async clear(runId) {
+        await this._redis.del(progressKey(runId));
+    }
+}
+//# sourceMappingURL=progress-channel.js.map

package/dist/progress-channel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"progress-channel.js","sourceRoot":"","sources":["../src/progress-channel.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,4EAA4E;AAC5E,EAAE;AACF,0EAA0E;AAC1E,0CAA0C;AAC1C,2FAA2F;AAG3F,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAA;AAC1C,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAA;AAEtC,MAAM,WAAW,GAAG,IAAI,CAAA;AAOxB,SAAS,WAAW,CAAC,KAAa;IAChC,OAAO,YAAY,KAAK,WAAW,CAAA;AACrC,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,OAAO,sBAAsB;IACzB,MAAM,CAAO;IACb,OAAO,CAAc;IAE7B,YAAY,kBAAyD,EAAE,EAAE,OAAiC,EAAE;QAC1G,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,MAAM,CAAA;QAE1B,IAAI,eAAe,YAAY,KAAK,EAAE,CAAC;YACrC,IAAI,CAAC,MAAM,GAAG,eAAe,CAAA;YAC7B,OAAM;QACR,CAAC;QAED,MAAM,OAAO,GAAG,eAAe,CAAA;QAC/B,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC,sBAAsB,CAAA;QAC7D,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,OAAO,CAAC,GAAG,CAAC,wBAAwB,CAAA;QAEnE,IAAI,CAAC,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC;YACnB,MAAM,IAAI,UAAU,CAClB,cAAc,EACd,kHAAkH,CACnH,CAAA;QACH,CAAC;QAED,IAAI,CAAC,MAAM,GAAG,IAAI,KAAK,CAAC,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,CAAA;IACzC,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,KAAa,EAAE,QAA0B;QACjD,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,WAAW,CAAC,KAAK,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,EAAE,EAAE,EAAE,EAAE,WAAW,EAAE,CAAC,CAAA;QAC1F,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,8CAA8C;YAC9C,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,uBAAuB,EAAE,EAAE,GAAG,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,CAAC,QAAQ,EAAE,CAAC,CAAA;QAC1F,CAAC;IACH,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,KAAa;QACrB,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,CAAA;QACrD,IAAI,GAAG,KAAK,IAAI,IAAI,GAAG,KAAK,SAAS;YAAE,OAAO,IAAI,CAAA;QAClD,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;YAC5B,IAAI,CAAC;gBACH,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAqB,CAAA;YAC5C,CAAC;YAAC,MAAM,CAAC;gBACP,OAAO,IAAI,CAAA;YACb,CAAC;QACH,CAAC;QACD,8EAA8E;QAC9E,OAAO,GAAuB,CAAA;IAChC,CAAC;IAED,KAAK,CAAC,KAAK,CAAC,KAAa;QACvB,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,CAAA;IAC3C,CAAC;CACF"}

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@mantajs/adapter-cache-upstash",
+  "version": "0.2.0-beta.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@upstash/redis": "^1.34.0"
+  },
+  "peerDependencies": {
+    "@mantajs/core": "0.2.0-beta.0"
+  },
+  "files": [
+    "dist"
+  ]
+}