@t4h.framework/cache 0.3.0 → 0.5.0

package/.ai/skills/framework-cache/SKILL.md

@@ -0,0 +1,188 @@
+---
+name: framework-cache
+description: >-
+  Guides correct use of @t4h.framework/cache in T4H Framework workflows:
+  CacheClaim that backs package caching (OAuth2 token caching via
+  @t4h.framework/http), Serializable values, TTL semantics, and runtime Claim
+  providers. Use when a workflow relies on cache-backed package primitives,
+  wiring CacheClaim providers, or testing cache behavior in workflow tests.
+---
+
+# @t4h.framework/cache
+
+Abstract **CacheClaim** for serializable key-value storage used by framework-package primitives (e.g. OAuth2 token caching). The package defines the claim contract only; runtimes supply concrete backends (e.g. Redis).
+
+Package path: `framework/packages/cache`. Peer dependency: `@t4h.framework/core` (`Serializable`, `Claim`, activities).
+
+---
+
+## Import surface
+
+Only symbols exported from `src/cache.ts` exist in the public API:
+
+```typescript
+import { CacheClaim, type CacheClaimSetOptions } from '@t4h.framework/cache'
+```
+
+Do not invent additional exports or helpers not present in this package.
+
+---
+
+## API contract
+
+### `CacheClaimSetOptions`
+
+```typescript
+interface CacheClaimSetOptions {
+  ttl?: number
+}
+```
+
+`ttl` is optional. The README and `OAuth2` pass it in **milliseconds** (see OAuth2 section). Runtime implementations decide how to honor TTL; the abstract type does not document units beyond the optional number.
+
+### `CacheClaim`
+
+```typescript
+abstract class CacheClaim {
+  public abstract get<T extends Serializable>(
+    key: string,
+  ): T | undefined | Promise<T | undefined>
+
+  public abstract set(
+    key: string,
+    value: Serializable,
+    options?: CacheClaimSetOptions,
+  ): Promise<void>
+}
+```
+
+| Method | Behavior |
+|--------|----------|
+| `get` | Returns stored value or `undefined`. May be sync or async — **always `await`** at call sites. |
+| `set` | Stores a `Serializable` value. Always returns `Promise<void>`. Optional `ttl` in `options`. |
+
+Values must satisfy `Serializable` from `@t4h.framework/core`: primitives, `null`, `undefined`, `Binary`, `SerializableClass`, and arrays/objects composed of those.
+
+---
+
+## How workflows use it
+
+Workflows never call `CacheClaim` directly. It backs the caching built into
+framework-package primitives — most notably **OAuth2 token caching** in
+`@t4h.framework/http`. Your only responsibility is that the runtime **registers
+a `CacheClaim` provider** (below) so those primitives work. See **Downstream
+consumer: OAuth2**.
+
+---
+
+## Runtime provider
+
+The runtime (or test harness) must register a concrete implementation:
+
+```typescript
+{ provide: CacheClaim, value: new RedisCacheClaimImpl() }
+```
+
+`RedisCacheClaimImpl` is illustrative — implement `CacheClaim` in the runtime layer; this package does not ship a production backend.
+
+Without a provider, claim resolution fails at runtime (`ClaimProviderNotFoundException` and related errors from core).
+
+---
+
+## Testing cache behavior
+
+Test the **workflow** with `TestWorkflowEnvironment` from
+`@t4h.framework/core/testing`, mocking `CacheClaim` (a workflow that uses OAuth2
+also needs `HttpClientRequestClaim`). An in-memory `Map` makes a good double. See
+the **framework-workflow-testing** skill for the harness API.
+
+```typescript
+import { TestWorkflowEnvironment, mockClaim } from '@t4h.framework/core/testing'
+import { CacheClaim } from '@t4h.framework/cache'
+
+const store = new Map<string, unknown>()
+
+const env = TestWorkflowEnvironment.create({ now: 0 })
+
+await env.execute(workflow, input, {
+  claims: [
+    mockClaim(CacheClaim, {
+      get: key => store.get(key) as any,
+      set: async (key, value) => { store.set(key, value) },
+    }),
+    // ...other claims the workflow's activities need (e.g. HttpClientRequestClaim)
+  ],
+})
+```
+
+When testing TTL-dependent logic, implement `set` with TTL semantics in the test double.
+
+---
+
+## Downstream consumer: OAuth2 (`@t4h.framework/http`)
+
+`@t4h.framework/http` depends on this package for token caching only — the
+`HttpAuth` / `OAuth2` grant classes use `CacheClaim` internally to store tokens:
+
+| Concern | Implementation |
+|---------|----------------|
+| Cache key | `` `oauth2:token:${this.config.clientId}` `` (`tokenCacheKey`) |
+| Stored shape | `OAuth2Token` plus `expiresAt: number` (ms timestamp) |
+| TTL on `set` | `Math.floor(token.expires_in * 1000 * 0.9)` — 90% of `expires_in` in **seconds**, converted to ms |
+| Read path | `get` → if missing, fetch token and `set`; if `expiresAt > Date.now()`, return; else refresh or re-fetch |
+
+Workflows using OAuth2 grant classes must wire **`CacheClaim`** and **`HttpClientRequestClaim`** in the runtime. See `framework-http` skill for HTTP details.
+
+---
+
+## Implementing a custom `CacheClaim`
+
+Subclass `CacheClaim` and implement both methods:
+
+```typescript
+import { CacheClaim, type CacheClaimSetOptions } from '@t4h.framework/cache'
+import type { Serializable } from '@t4h.framework/core'
+
+export class MyCacheClaim extends CacheClaim {
+  public get<T extends Serializable>(
+    key: string,
+  ): T | undefined | Promise<T | undefined> {
+    // ...
+  }
+
+  public set(
+    key: string,
+    value: Serializable,
+    options?: CacheClaimSetOptions,
+  ): Promise<void> {
+    // honor options?.ttl if the backend supports it
+    return Promise.resolve()
+  }
+}
+```
+
+Register: `{ provide: CacheClaim, value: new MyCacheClaim() }`.
+
+---
+
+## Do / Don't
+
+| Do | Don't |
+|----|-------|
+| `await` both `get` and `set` | Assume `get` is always synchronous |
+| Store only `Serializable` values | Cache class instances, functions, or `Buffer` unless wrapped as `Binary` |
+| Namespace keys (`feature:id`) | Use bare global keys like `"token"` |
+| Provide `CacheClaim` in runtime/test `claims` | Use cache outside `Claim` / activity context |
+| Use a test double with explicit TTL when testing expiry | Assume any in-memory mock enforces TTL unless you implement it |
+| Match OAuth2 TTL units (ms) when mirroring that pattern | Mix seconds and milliseconds for `ttl` without checking the caller |
+
+---
+
+## Related packages
+
+| Package | Role |
+|---------|------|
+| `@t4h.framework/core` | `Claim`, `Serializable`, and the `TestWorkflowEnvironment` testing harness |
+| `@t4h.framework/http` | OAuth2 token caching via `CacheClaim` |
+
+For claim wiring use the **framework-core** skill; for the testing harness use **framework-workflow-testing**. For HTTP and OAuth2, use the **framework-http** skill.

package/dist/ActivityCacheClaim.d.ts

@@ -0,0 +1,9 @@
+import type { Serializable } from '@t4h.framework/core';
+export interface ActivityCacheClaimSetOptions {
+    ttl?: number;
+}
+export declare abstract class ActivityCacheClaim {
+    abstract get<T extends Serializable>(key: string): T | undefined | Promise<T | undefined>;
+    abstract set(key: string, value: Serializable, options?: ActivityCacheClaimSetOptions): Promise<void>;
+}
+//# sourceMappingURL=ActivityCacheClaim.d.ts.map

package/dist/ActivityCacheClaim.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ActivityCacheClaim.d.ts","sourceRoot":"","sources":["../src/ActivityCacheClaim.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAEvD,MAAM,WAAW,4BAA4B;IAC3C,GAAG,CAAC,EAAE,MAAM,CAAA;CACb;AAED,8BAAsB,kBAAkB;aACtB,GAAG,CAAC,CAAC,SAAS,YAAY,EACxC,GAAG,EAAE,MAAM,GACV,CAAC,GAAG,SAAS,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;aAEzB,GAAG,CACjB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,YAAY,EACnB,OAAO,CAAC,EAAE,4BAA4B,GACrC,OAAO,CAAC,IAAI,CAAC;CACjB"}

package/dist/ActivityCacheClaim.js

@@ -0,0 +1,3 @@
+export class ActivityCacheClaim {
+}
+//# sourceMappingURL=ActivityCacheClaim.js.map

package/dist/ActivityCacheClaim.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ActivityCacheClaim.js","sourceRoot":"","sources":["../src/ActivityCacheClaim.ts"],"names":[],"mappings":"AAMA,MAAM,OAAgB,kBAAkB;CAUvC"}

package/dist/testing/index.d.ts

@@ -0,0 +1,3 @@
+import { CacheClaim } from '../CacheClaim.js';
+export declare function mockCacheClaim(implementation?: Partial<CacheClaim>): import("@t4h.framework/core").ClaimProvider<CacheClaim>;
+//# sourceMappingURL=index.d.ts.map

package/dist/testing/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAE7C,wBAAgB,cAAc,CAC5B,cAAc,GAAE,OAAO,CAAC,UAAU,CAAM,2DAWzC"}

package/dist/testing/index.js

@@ -0,0 +1,13 @@
+import { mockClaim } from '@t4h.framework/core/testing';
+import { CacheClaim } from '../CacheClaim.js';
+export function mockCacheClaim(implementation = {}) {
+    const store = new Map();
+    return mockClaim(CacheClaim, {
+        get: async (key) => store.get(key),
+        set: async (key, value) => {
+            store.set(key, value);
+        },
+        ...implementation,
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/testing/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,6BAA6B,CAAA;AAEvD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAE7C,MAAM,UAAU,cAAc,CAC5B,iBAAsC,EAAE;IAExC,MAAM,KAAK,GAAG,IAAI,GAAG,EAAmB,CAAA;IAExC,OAAO,SAAS,CAAC,UAAU,EAAE;QAC3B,GAAG,EAAE,KAAK,EAAC,GAAG,EAAC,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAU;QACzC,GAAG,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,EAAE;YACxB,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAA;QACvB,CAAC;QACD,GAAG,cAAc;KAClB,CAAC,CAAA;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@t4h.framework/cache",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Cache module for the T4H Framework",
   "homepage": "https://github.com/tech4humans-brasil/framework/tree/main/packages/cache",
   "bugs": "https://github.com/tech4humans-brasil/framework/issues",
@@ -20,7 +20,8 @@
   "types": "./dist/cache.d.ts",
   "files": [
     "dist",
-    "LICENSE"
+    "LICENSE",
+    ".ai"
   ],
   "scripts": {
     "build": "tsc --project tsconfig.build.json",
@@ -28,14 +29,12 @@
     "lint": "eslint .",
     "prepublishOnly": "yarn build"
   },
-  "dependencies": {
-    "@t4h.framework/core": "^0.3.0"
-  },
   "devDependencies": {
+    "@t4h.framework/core": "^0.8.0",
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "@t4h.framework/core": "^0.3.0"
+    "@t4h.framework/core": "^0.8.0"
   },
   "packageManager": "yarn@4.12.0",
   "engines": {