feat(ts): add TypeScript GCache package

[lan17]

Summary

This PR adds a TypeScript sibling package for GCache under packages/gcache-ts, published as @rungalileo/gcache, plus TypeScript CI and Codecov upload. It consolidates the previously stacked milestone PRs into one reviewable PR.

Supersedes: #133, #134, #135, #136.

What changed

Package + CI

• Adds a pnpm workspace and TypeScript package build/test/typecheck scripts.
• Adds ESM/CJS builds, generated type declarations, and package exports.
• Adds .github/workflows/typescript.yaml for install/typecheck/test/build.
• Uploads TypeScript coverage to Codecov from packages/gcache-ts/coverage/lcov.info with the gcache-ts flag.

Local-only GCache MVP

• Adds explicit gcache.enable(fn) / gcache.disable(fn) APIs backed by Node AsyncLocalStorage.
• Keeps caching disabled by default, with nested and parallel async scopes isolated.
• Adds explicit key builders via GCacheKey / GCacheKeyConfig.
• Adds local TTL caching, max-size eviction, delete, flushAll, and fail-open behavior.

Redis TTL layer

• Adds optional Redis-backed distributed TTL caching.
• Implements local → Redis → fallback read-through behavior.
• Supports eager Redis client injection or lazy createClient.
• Adds a versioned timestamped Redis JSON envelope with default/custom serializer support.
• Adds cross-layer delete/flushAll and fail-open Redis read/write/delete/flush behavior.

Runtime config + rollout controls

• Adds runtime cacheConfigProvider support with fallback to per-function defaultConfig.
• Adds per-layer TTL/ramp controls.
• Adds injectable ramp sampling so rollout behavior is deterministic in tests.
• Treats missing/invalid config as layer-disabled and falls through instead of breaking app requests.
• Preserves fail-open behavior for config provider errors.

Observability + operational safety

• Adds metrics hooks for requests, misses, disabled paths, errors, invalidation calls, get/fallback/serialization timers, and serialized value size histograms.
• Adds Prometheus support via prom-client, with custom registry/prefix and duplicate collector reuse.
• Adds custom metrics adapter support for non-Prometheus integrations.
• Separates cache plumbing errors from fallback/business-logic errors in labels.

Targeted invalidation + watermarks

• Adds trackForInvalidation on cached functions.
• Adds gcache.invalidate(keyType, id, { futureBufferMs }).
• Adds Redis Cluster-compatible watermark keys like {urnPrefix:keyType:id}#watermark.
• Adds configurable watermark TTL and documents that it should exceed max cache TTL.
• Suppresses Redis/local writes while an invalidation watermark is active to avoid stale write races.
• Documents local-cache consistency limitations and recommends disabling local cache for strongly invalidated mutable data.
• Fails open with warning/error metrics around watermark read/write failures.

Testing

Tests are written in behavioral Given/When/Then style.

Validation run on the peak branch:

• pnpm install --frozen-lockfile
• pnpm ts:gcache:typecheck
• pnpm ts:gcache:test — 47 tests, coverage: 97.05% statements / 92.62% branches / 98% functions / 97.27% lines
• pnpm ts:gcache:build

Intentionally left for later

• Framework integrations / middleware helpers
• cachedObject convenience API
• Expanded examples
• Release hardening / publishing workflow

[codecov]

Codecov Report

❌ Patch coverage is 91.92399% with 34 lines in your changes missing coverage. Please review.
✅ Project coverage is 95.33%. Comparing base (683034b) to head (9068f07).

Files with missing lines	Patch %	Lines
packages/gcache-ts/src/internal/redis-cache.ts	88.39%	3 Missing and 10 partials ⚠️
packages/gcache-ts/src/gcache.ts	93.67%	5 Missing and 5 partials ⚠️
packages/gcache-ts/src/internal/local-cache.ts	82.60%	2 Missing and 6 partials ⚠️
packages/gcache-ts/src/errors.ts	80.00%	1 Missing ⚠️
packages/gcache-ts/src/internal/runtime-config.ts	96.29%	0 Missing and 1 partial ⚠️
packages/gcache-ts/src/metrics.ts	96.66%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #137      +/-   ##
==========================================
- Coverage   97.47%   95.33%   -2.14%     
==========================================
  Files          13       23      +10     
  Lines         673     1094     +421     
  Branches        0      121     +121     
==========================================
+ Hits          656     1043     +387     
- Misses         17       28      +11     
- Partials        0       23      +23     

Flag	Coverage Δ
gcache-ts	91.92% <91.92%> (?)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.