@t4h.framework/cache 0.6.9 → 0.6.11

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

@@ -18,14 +18,12 @@ Package path: `framework/packages/cache`. Peer dependency: `@t4h.framework/core`
 
 ## Import surface
 
-Only symbols exported from `src/cache.ts` exist in the public API:
+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'
 ```
 
-Do not invent additional exports or helpers not present in this package.
-
 ---
 
 ## API contract
@@ -58,16 +56,16 @@ abstract class CacheClaim {
 
 | Method | Behavior |
 |--------|----------|
-| `get` | Returns stored value or `undefined`. May be sync or async — **always `await`** at call sites. |
+| `get` | Returns stored value or `undefined`. May be sync or async. |
 | `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.
+`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
 
-Workflows never call `CacheClaim` directly. It backs the caching built into
+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
@@ -85,7 +83,7 @@ The runtime (or test harness) must register a concrete implementation:
 
 `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).
+A missing provider throws `ClaimProviderNotFoundException` (core `exceptions/ClaimException.ts`).
 
 ---
 
@@ -97,18 +95,23 @@ also needs `HttpClientRequestClaim`). An in-memory `Map` makes a good double. Se
 the **framework-workflow-testing** skill for the harness API.
 
 ```typescript
-import { TestWorkflowEnvironment, mockClaim } from '@t4h.framework/core/testing'
 import { CacheClaim } from '@t4h.framework/cache'
+import type { Serializable } from '@t4h.framework/core'
+import { TestWorkflowEnvironment, mockClaim } from '@t4h.framework/core/testing'
 
-const store = new Map<string, unknown>()
+const store = new Map<string, Serializable>()
 
 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) },
+      get: <T extends Serializable>(key: string): T | undefined | Promise<T | undefined> =>
+        store.get(key) as T | undefined,
+      set: (key, value) => {
+        store.set(key, value)
+        return Promise.resolve()
+      },
     }),
     // ...other claims the workflow's activities need (e.g. HttpClientRequestClaim)
   ],
@@ -169,10 +172,7 @@ Register: `{ provide: CacheClaim, value: new MyCacheClaim() }`.
 
 | 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 |
 

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @t4h.framework/cache
 
+## 0.6.11
+
+### Patch Changes
+
+- [#240](https://github.com/tech4humans-brasil/framework/pull/240) [`0606115`](https://github.com/tech4humans-brasil/framework/commit/0606115e2e0baa994e9f0ed3559ee54ecac88e44) Thanks [@gusteycamargo](https://github.com/gusteycamargo)! - The skills do not repeat a rule that a lint rule, `tsc` or a runtime error already enforces. Each such rule is now one line that names the gate. The examples that broke a gate (`process.env`, `as any`, an inline secret, an `EnvDesign` in a workflow file, `ref.output` before `wait()`) are correct now.
+
+## 0.6.10
+
 ## 0.6.9
 
 ## 0.6.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@t4h.framework/cache",
-  "version": "0.6.9",
+  "version": "0.6.11",
   "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",
@@ -26,11 +26,12 @@
   "scripts": {
     "build": "tsc --project tsconfig.build.json",
     "check-types": "tsc --noEmit",
-    "lint": "eslint .",
+    "check-package": "publint --strict && attw --pack . --profile esm-only",
+    "lint": "eslint . --max-warnings 0",
     "prepublishOnly": "yarn build"
   },
   "devDependencies": {
-    "@t4h.framework/core": "^0.18.0",
+    "@t4h.framework/core": "^0.20.0",
     "typescript": "^5.9.3"
   },
   "peerDependencies": {