Skip to content

feat(core): implement resource cache phase 1 - staleTime and deduplicate#119

Merged
mahyarmlk merged 2 commits into
mainfrom
feat/resource-cache-phase-1
Jun 26, 2026
Merged

feat(core): implement resource cache phase 1 - staleTime and deduplicate#119
mahyarmlk merged 2 commits into
mainfrom
feat/resource-cache-phase-1

Conversation

@mahyarmlk

Copy link
Copy Markdown
Collaborator

Summary

Implement resource cache semantics phase 1: cache.staleTime and cache.deduplicate.

API

const team = $.resource("team", {
  cache: {
    staleTime: 5_000,
    deduplicate: true,
  },
  load: async () => loadTeam(),
})

Behavior

cache.staleTime: After a successful load/reload, a timer starts. When it fires, the resource becomes stale — stale condition fires, status stays "ready", value stays available. Resets on every successful load/reload. Failed loads do not start the timer. dispose() clears the timer.

cache.deduplicate: When true (default when cache is set), concurrent load()/reload() calls while a load is pending share a single in-flight promise. Only one loader invocation runs. When false, preserves current independent concurrent behavior. Resources without cache options are unaffected.

Changed files

  • packages/core/src/resource.ts — new ResourceCacheOptions type, cache on ResourceConfig, dispose on ResourceNode, staleTime/deduplicate logic
  • packages/core/src/screen.ts — builder accepts cache option
  • packages/core/src/runtime.ts — passes cache to createResourceNode, calls node.dispose()
  • packages/core/src/index.ts — export ResourceCacheOptions
  • packages/core/src/core.test.ts — 13 new tests covering staleTime, deduplicate, error/dispose edge cases
  • docs/Resources.md — cache options section with phase-1 docs and future-work callout
  • docs/proposals/Resource-Cache-And-Stale-Semantics.md — implementation status notes
  • .changeset/seven-cobras-tan.md — patch changeset for core

Validation

  • pnpm --filter @intent-framework/core test ✅ (174 pass)
  • pnpm test ✅ (384 pass across all packages)
  • pnpm typecheck
  • pnpm build
  • pnpm lint
  • pnpm pack:check
  • pnpm changeset status

Not implemented (still future)

  • cache.key
  • cacheTime
  • swr
  • Cross-navigation cache store
  • Streaming, SSR, optimistic updates

Add ResourceCacheOptions with staleTime (time-based staleness) and
deduplicate (in-flight load deduplication). Resources without cache
options behave exactly as before.

- staleTime: optional ms timer that marks resource stale after
  successful load; resets on reload; cleared on dispose; failed
  loads do not start timer
- deduplicate: optional boolean (default true when cache set);
  concurrent load/reload calls share a single in-flight promise
- dispose(): new ResourceNode method to clean up stale timers
- ScreenRuntime.dispose() now calls node.dispose() on all nodes

Validation: pnpm test (384 all pass), typecheck, build, lint,
pack:check, changeset status
@mahyarmlk mahyarmlk merged commit d403398 into main Jun 26, 2026
1 check passed
@mahyarmlk mahyarmlk deleted the feat/resource-cache-phase-1 branch June 26, 2026 19:49
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant