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.

Status note

TypeScript support is experimental for now. The package is intended for early validation and feedback before treating the API and operational behavior as stable.

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 93.98664% with 27 lines in your changes missing coverage. Please review.
✅ Project coverage is 96.07%. Comparing base (cd63783) to head (887e69e).

Files with missing lines	Patch %	Lines
packages/gcache-ts/src/internal/local-cache.ts	76.08%	6 Missing and 5 partials ⚠️
packages/gcache-ts/src/internal/redis-cache.ts	92.06%	2 Missing and 8 partials ⚠️
packages/gcache-ts/src/gcache.ts	98.13%	1 Missing and 2 partials ⚠️
packages/gcache-ts/src/errors.ts	80.00%	1 Missing ⚠️
packages/gcache-ts/src/internal/runtime-config.ts	96.55%	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%   96.07%   -1.40%     
==========================================
  Files          13       23      +10     
  Lines         673     1122     +449     
  Branches        0      129     +129     
==========================================
+ Hits          656     1078     +422     
- Misses         17       27      +10     
- Partials        0       17      +17     

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

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.