@t4h.framework/cache 0.3.0 → 0.4.0

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

@@ -0,0 +1,236 @@
+---
+name: framework-cache
+description: >-
+  Guides correct use of @t4h.framework/cache in T4H Framework workflows:
+  CacheClaim for key-value storage inside activities, Serializable values, TTL
+  on set, runtime Claim providers, and OAuth2 token caching via @t4h.framework/http.
+  Use when implementing cache-backed activities, wiring CacheClaim providers,
+  testing cache get/set, or working in packages/cache.
+---
+
+# @t4h.framework/cache
+
+Abstract **CacheClaim** for serializable key-value storage inside activities. 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.
+
+---
+
+## Declaring CacheClaim in an activity
+
+Follow the same `Claim` pattern as other framework claims (see `framework-core` skill). Declare the claim on the activity, access it only inside activity methods while the claim context is active (`Claim.run` stack).
+
+```typescript
+import { SyncActivity, Claim } from '@t4h.framework/core'
+import { CacheClaim } from '@t4h.framework/cache'
+
+class GetCachedConfigActivity extends SyncActivity<
+  [key: string],
+  { key: string },
+  any,
+  any
+> {
+  private readonly claims = new Claim({
+    cache: CacheClaim,
+  })
+
+  public async toInput(key: string) {
+    return { key }
+  }
+
+  public async run(input: { key: string }) {
+    const cached = await this.claims.cache.get(input.key)
+
+    if (cached) return cached
+
+    const value = { setting: 'default' }
+    await this.claims.cache.set(input.key, value, { ttl: 3600 })
+
+    return value
+  }
+
+  public toOutput(output: any) {
+    return output
+  }
+}
+```
+
+### Cache-aside pattern
+
+1. `await cache.get(key)` — if hit, return.
+2. Compute or fetch the value.
+3. `await cache.set(key, value, { ttl })` — store for later runs/replays.
+4. Return the value.
+
+Use **stable, namespaced keys** (prefix + id) to avoid collisions across features or tenants.
+
+---
+
+## 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
+
+There are no unit tests under `packages/cache/`. Test with an in-memory `CacheClaim` double or `Claim.run`:
+
+```typescript
+import { describe, expect, it, vi } from 'vitest'
+import { Claim } from '@t4h.framework/core'
+import { CacheClaim } from '@t4h.framework/cache'
+
+const store = new Map<string, unknown>()
+
+const mockCache: CacheClaim = {
+  get: key => store.get(key) as any,
+  set: async (key, value) => { store.set(key, value) },
+} as CacheClaim
+
+await Claim.run(
+  [{ provide: CacheClaim, value: mockCache }],
+  () => myActivity.run(input),
+)
+```
+
+For full workflows, pass the same provider via `WorkflowTesting.run` (see **framework-core** skill). 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. `HttpAuth` and `OAuth2` declare `CacheClaim` via `Claim`:
+
+```typescript
+// HttpAuth — Symbol-keyed claims bag
+public readonly [HTTP_AUTH_CLAIMS_KEY] = new Claim({ cache: CacheClaim })
+
+// OAuth2
+protected readonly claims = new Claim({
+  http: HttpClientRequestClaim,
+  cache: CacheClaim,
+})
+```
+
+OAuth2 cache usage (`packages/http/src/models/OAuth2.ts`):
+
+| 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`, activities, `WorkflowTesting`, `Internals` |
+| `@t4h.framework/http` | OAuth2 token caching via `CacheClaim` |
+
+For claim wiring, activity structure, and testing harnesses, use the **framework-core** skill. 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@t4h.framework/cache",
-  "version": "0.3.0",
+  "version": "0.4.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.6.0",
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "@t4h.framework/core": "^0.3.0"
+    "@t4h.framework/core": "^0.6.0"
   },
   "packageManager": "yarn@4.12.0",
   "engines": {