@t4h.framework/cache 0.6.11 → 0.6.13

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

@@ -1,98 +1,56 @@
 ---
 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.
+  Guides the use of CacheClaim from @t4h.framework/cache in T4H Framework
+  apps: reading and writing Serializable values from an activity, the ttl
+  option of CacheClaimSetOptions, registering a CacheClaim provider in the
+  runtime or in tests (mockClaim, TestWorkflowEnvironment), and the
+  CacheClaim that OAuth2 token caching in @t4h.framework/http needs. Use when
+  code imports CacheClaim, when a workflow that uses OAuth2 fails with
+  ClaimProviderNotFoundException for CacheClaim, or when you write a
+  CacheClaim implementation or test double.
 ---
 
 # @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).
+`CacheClaim` is an abstract claim with `get(key)` and
+`set(key, value, options?)`. The package has no implementation. The runtime or
+the test must give one.
 
-Package path: `framework/packages/cache`. Peer dependency: `@t4h.framework/core` (`Serializable`, `Claim`, activities).
+## Use the cache in an activity
 
----
-
-## Import surface
-
-Import from the package entry. Its `exports` map has only `.`, so `tsc` rejects a deep import:
-
-```typescript
-import { CacheClaim, type CacheClaimSetOptions } from '@t4h.framework/cache'
-```
-
----
-
-## 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`
+1. Declare the claim in the activity with `new Claim({ cache: CacheClaim })`.
+2. Call it only in `run()`. A claim is not available in workflow code.
+3. Give each key a prefix (`feature:id`). All callers share one store.
 
 ```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>
+private readonly claims = new Claim({ cache: CacheClaim })
+
+public async run({ id }: { id: string }) {
+  const key = `config:${id}`
+  const cached = await this.claims.cache.get<Config>(key)
+  if (cached) return cached
+  const value = await loadConfig(id)
+  await this.claims.cache.set(key, value)
+  return value
 }
 ```
 
-| Method | Behavior |
-|--------|----------|
-| `get` | Returns stored value or `undefined`. May be sync or async. |
-| `set` | Stores a `Serializable` value. Always returns `Promise<void>`. Optional `ttl` in `options`. |
-
-`value` is typed `Serializable` from `@t4h.framework/core` (primitives, `null`, `undefined`, `Binary`, `SerializableClass`, and arrays/objects of those), so `tsc` rejects other values.
-
----
-
-## How workflows use it
-
-Workflow code does not call `CacheClaim` directly. The claim 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.
-
-A missing provider throws `ClaimProviderNotFoundException` (core `exceptions/ClaimException.ts`).
+## Traps
 
----
+- `get` can return a value or a `Promise`. Always `await` it.
+- `value` must be `Serializable` from `@t4h.framework/core`. A `Date`, a `Map`
+  or a class instance that is not serializable fails `tsc`.
+- `ttl` has no unit in the type. The implementation decides the unit. Do not
+  guess: read the implementation that your runtime gives. `OAuth2` in
+  `@t4h.framework/http` gives `ttl` in milliseconds.
+- A workflow that uses an `OAuth2` grant from `@t4h.framework/http` needs a
+  `CacheClaim` provider, also if your code never imports `CacheClaim`.
+- Import only from `@t4h.framework/cache`. The package has no deep exports.
 
-## Testing cache behavior
+## Test
 
-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.
+Give a `Map` double with `mockClaim`:
 
 ```typescript
 import { CacheClaim } from '@t4h.framework/cache'
@@ -101,88 +59,23 @@ import { TestWorkflowEnvironment, mockClaim } from '@t4h.framework/core/testing'
 
 const store = new Map<string, Serializable>()
 
-const env = TestWorkflowEnvironment.create({ now: 0 })
-
-await env.execute(workflow, input, {
+await TestWorkflowEnvironment.create().execute(workflow, input, {
   claims: [
     mockClaim(CacheClaim, {
-      get: <T extends Serializable>(key: string): T | undefined | Promise<T | undefined> =>
+      get: <T extends Serializable>(key: string) =>
         store.get(key) as T | undefined,
-      set: (key, value) => {
+      set: async (key, value) => {
         store.set(key, value)
-        return Promise.resolve()
       },
     }),
-    // ...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 |
-|----|-------|
-| Namespace keys (`feature:id`) | Use bare global keys like `"token"` |
-| 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
+The double does not expire entries. If the test depends on `ttl`, write that
+logic in `set` and `get`.
 
-| Package | Role |
-|---------|------|
-| `@t4h.framework/core` | `Claim`, `Serializable`, and the `TestWorkflowEnvironment` testing harness |
-| `@t4h.framework/http` | OAuth2 token caching via `CacheClaim` |
+## Reference
 
-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.
+- README: https://www.npmjs.com/package/@t4h.framework/cache
+- Types: `node_modules/@t4h.framework/cache/dist/CacheClaim.d.ts`

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @t4h.framework/cache
 
+## 0.6.13
+
+## 0.6.12
+
+### Patch Changes
+
+- [#257](https://github.com/tech4humans-brasil/framework/pull/257) [`586bfb4`](https://github.com/tech4humans-brasil/framework/commit/586bfb4663f4a478527ee0c8db360603f034d615) Thanks [@gusteycamargo](https://github.com/gusteycamargo)! - The cache README is the short human doc of `CacheClaim`, and its example now compiles. The README and the skill no longer give a unit for `ttl`, because the type does not fix one.
+
 ## 0.6.11
 
 ### Patch Changes

package/README.md

@@ -1,70 +1,76 @@
 # @t4h.framework/cache
 
-Cache claim for key-value storage within activities.
+`CacheClaim`: a claim for key-value storage of `Serializable` values in
+activities. The package defines only the contract. The runtime gives the
+implementation.
 
-## Claim
+## Installation
 
-### CacheClaim
-
-Abstract dependency for caching serializable values. An activity declares this claim when it needs to cache data (e.g. tokens, computed results). The runtime provides a concrete implementation (e.g. Redis, in-memory).
-
-```typescript
-import { CacheClaim } from '@t4h.framework/cache'
+```bash
+npm install @t4h.framework/cache
 ```
 
-### Interface
+## Contract
 
-```typescript
-interface CacheClaimSetOptions {
-  ttl?: number
-}
+| Method                      | Result                                                     |
+| --------------------------- | ---------------------------------------------------------- |
+| `get<T>(key)`               | The stored value, or `undefined`. It can be sync or async. |
+| `set(key, value, options?)` | `Promise<void>`. `value` must be `Serializable`.           |
+| `CacheClaimSetOptions.ttl`  | Optional number. The type does not fix a unit.             |
 
-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>
-}
-```
+The implementation decides how to apply `ttl`. Before you set `ttl`, make sure
+that you use the unit of the implementation that your runtime gives.
+`OAuth2` in `@t4h.framework/http` uses this claim and gives `ttl` in
+milliseconds.
 
-### Usage inside an activity
+## Usage in an activity
 
 ```typescript
-import { SyncActivity, Claim } from '@t4h.framework/core'
+import { Claim, SyncActivity } from '@t4h.framework/core'
 import { CacheClaim } from '@t4h.framework/cache'
 
-class GetCachedConfigActivity extends SyncActivity<
+type Config = { setting: string }
+
+export class GetConfigActivity extends SyncActivity<
   [key: string],
   { key: string },
-  any
+  Config,
+  Config
 > {
-  private readonly claims = new Claim({
-    cache: CacheClaim,
-  })
+  private readonly claims = new Claim({ cache: CacheClaim })
 
-  public async toInput(key: string) {
+  public toInput(key: string) {
     return { key }
   }
 
-  public async run(input: { key: string }) {
-    const cached = await this.claims.cache.get(input.key)
-
+  public async run({ key }: { key: string }) {
+    const cacheKey = `config:${key}`
+    const cached = await this.claims.cache.get<Config>(cacheKey)
     if (cached) return cached
 
     const value = { setting: 'default' }
-    await this.claims.cache.set(input.key, value, { ttl: 3600 })
-
+    await this.claims.cache.set(cacheKey, value)
     return value
   }
 
-  public toOutput(output: any) {
+  public toOutput(output: Config) {
     return output
   }
 }
 ```
 
-### Runtime provider
+Put a prefix on each key (`feature:id`), because all callers share one store.
+
+## Provider
 
-The runtime must supply a concrete implementation:
+The runtime must give an implementation of `CacheClaim`:
 
 ```typescript
-{ provide: CacheClaim, value: new RedisCacheClaimImpl() }
+{ provide: CacheClaim, value: new MyCacheClaim() }
 ```
+
+If no provider is registered, the activity fails with
+`ClaimProviderNotFoundException` from `@t4h.framework/core`. In tests, use
+`mockClaim(CacheClaim, { get, set })` from `@t4h.framework/core/testing`. A
+`Map` is a good test double. A double applies `ttl` only if you write that
+logic.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@t4h.framework/cache",
-  "version": "0.6.11",
+  "version": "0.6.13",
   "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",
@@ -31,7 +31,7 @@
     "prepublishOnly": "yarn build"
   },
   "devDependencies": {
-    "@t4h.framework/core": "^0.20.0",
+    "@t4h.framework/core": "^0.21.1",
     "typescript": "^5.9.3"
   },
   "peerDependencies": {