@t4h.framework/cache 0.4.0 → 0.6.0

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

@@ -2,15 +2,15 @@
 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.
+  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 inside activities. The package defines the claim contract only; runtimes supply concrete backends (e.g. Redis).
+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).
 
@@ -65,53 +65,13 @@ Values must satisfy `Serializable` from `@t4h.framework/core`: primitives, `null
 
 ---
 
-## Declaring CacheClaim in an activity
+## How workflows use it
 
-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.
+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**.
 
 ---
 
@@ -131,46 +91,38 @@ Without a provider, claim resolution fails at runtime (`ClaimProviderNotFoundExc
 
 ## Testing cache behavior
 
-There are no unit tests under `packages/cache/`. Test with an in-memory `CacheClaim` double or `Claim.run`:
+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 { describe, expect, it, vi } from 'vitest'
-import { Claim } from '@t4h.framework/core'
+import { TestWorkflowEnvironment, mockClaim } from '@t4h.framework/core/testing'
 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
+const env = TestWorkflowEnvironment.create({ now: 0 })
 
-await Claim.run(
-  [{ provide: CacheClaim, value: mockCache }],
-  () => myActivity.run(input),
-)
+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)
+  ],
+})
 ```
 
-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.
+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`):
+`@t4h.framework/http` depends on this package for token caching only — the
+`HttpAuth` / `OAuth2` grant classes use `CacheClaim` internally to store tokens:
 
 | Concern | Implementation |
 |---------|----------------|
@@ -230,7 +182,7 @@ Register: `{ provide: CacheClaim, value: new MyCacheClaim() }`.
 
 | Package | Role |
 |---------|------|
-| `@t4h.framework/core` | `Claim`, `Serializable`, activities, `WorkflowTesting`, `Internals` |
+| `@t4h.framework/core` | `Claim`, `Serializable`, and the `TestWorkflowEnvironment` testing harness |
 | `@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.
+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/CHANGELOG.md

@@ -0,0 +1,36 @@
+# @t4h.framework/cache
+
+## 0.6.0
+
+### Minor Changes
+
+- Updated dependencies [[`8098041`](https://github.com/tech4humans-brasil/framework/commit/80980419d59a987378b7c94372ee2f7b7dcc00f5)]:
+  - @t4h.framework/core@0.10.0
+
+## 0.5.0
+
+### Patch Changes
+
+- Update skills ([`6d7e7bc`](https://github.com/tech4humans-brasil/framework/commit/6d7e7bca0c780a9c53a0c9e5aa0a865c5af67959))
+
+## 0.4.0
+
+### Patch Changes
+
+- Internal dependency updates
+
+## 0.3.0
+
+### Minor Changes
+
+- Adds .ai/skills in packages ([#88](https://github.com/tech4humans-brasil/framework/pull/88))
+
+### Patch Changes
+
+- Remove activity prefix from cache claim class name ([`4fa4ec9`](https://github.com/tech4humans-brasil/framework/commit/4fa4ec9e319fffeae0b5c96e0ec0e9cfa4e22c22))
+- Adds github workflow to run, build, tests and lint ([#18](https://github.com/tech4humans-brasil/framework/pull/18))
+- Adds readme ([`d810413`](https://github.com/tech4humans-brasil/framework/commit/d810413e79a04425013c836f76a2dd72ccaf4252))
+- Update package metadata and author information across multiple packages ([`2ca73df`](https://github.com/tech4humans-brasil/framework/commit/2ca73df42dc63c86ed44717b50d5402fca45b4e7))
+- Improve repository info ([`1fad92d`](https://github.com/tech4humans-brasil/framework/commit/1fad92d959b804189fd1486d047115995ac81eb0))
+- Fix resolve module resolution issues in check-types ([`c97a0d2`](https://github.com/tech4humans-brasil/framework/commit/c97a0d2747f38e561cc5c7d592b20de0459bc1ee))
+- Update package dependencies across multiple packages ([`8b4fc1d`](https://github.com/tech4humans-brasil/framework/commit/8b4fc1d0e92d6bd880ddf4c8119fb68c49c53760))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@t4h.framework/cache",
-  "version": "0.4.0",
+  "version": "0.6.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",
@@ -30,11 +30,11 @@
     "prepublishOnly": "yarn build"
   },
   "devDependencies": {
-    "@t4h.framework/core": "^0.6.0",
+    "@t4h.framework/core": "^0.10.0",
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "@t4h.framework/core": "^0.6.0"
+    "@t4h.framework/core": "^0.10.0"
   },
   "packageManager": "yarn@4.12.0",
   "engines": {

package/dist/ActivityCacheClaim.d.ts

@@ -1,9 +0,0 @@
-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

@@ -1 +0,0 @@
-{"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

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

package/dist/ActivityCacheClaim.js.map

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