improvement: replace KEYS with SCAN, fix @Cacheable null-return bug, …

[y-aithnini]

…clean up index exports

Summary

• What does this PR change?

Why

• Why is this change needed?

Checklist

• Added/updated tests (if behavior changed)
• npm run lint passes
• npm run typecheck passes
• npm test passes
• npm run build passes
• Added a changeset (npx changeset) if this affects consumers

Notes

• Anything reviewers should pay attention to?

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[Copilot]

Pull request overview

This PR updates CacheKit’s caching behavior and Redis adapter clearing strategy, while cleaning up the package’s public exports.

Changes:

• Updated @Cacheable to wrap cached values in an envelope so null return values can be cached.
• Replaced Redis KEYS usage with cursor-based SCAN in RedisCacheStore.clear() (prefix mode).
• Removed “Example*” exports from the library entrypoint (src/index.ts) to reduce/clean the public API surface.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
src/index.ts	Removes previously exported example DTO/guard/decorator symbols from the public entrypoint.
src/decorators/cacheable.decorator.ts	Implements envelope-wrapping for @Cacheable reads/writes to distinguish cached null vs cache miss.
src/decorators/cacheable.decorator.spec.ts	Updates TTL assertion for envelope-wrapped values and adds a test for caching null return values.
src/adapters/redis-cache-store.adapter.ts	Replaces KEYS + DEL with cursor-based SCAN + batched DEL when clearing prefixed keys.
src/adapters/redis-cache-store.adapter.spec.ts	Updates test expectations for scan+del and adds a test ensuring SCAN is used.

Comments suppressed due to low confidence (1)

src/index.ts:40

• This PR removes previously-exported symbols from the package entrypoint (src/index.ts). Since index.ts defines the public API surface, removing exports is a breaking change for any consumer that imported them. Please add an appropriate changeset (and ensure the version bump matches semver for removed exports), or keep the exports until a major release deprecation/removal cycle.

// ============================================================================
// SERVICES (Main API)
// ============================================================================
// CacheService is the primary interface consumers interact with.
// Inject it anywhere via constructor injection.
export { CacheService } from "./services/cache.service";

// ============================================================================
// DECORATORS
// ============================================================================
// Method decorators for automatic caching and cache invalidation.
// Apply these to service methods — no manual CacheService injection needed.

// Cache-aside decorator: returns cached value or calls the method and stores the result
export { Cacheable } from "./decorators/cacheable.decorator";
// Cache eviction decorator: deletes the cache entry after the method executes

[Copilot]

The envelope detection is too permissive: isEnvelope() treats any cached object with a __v property as an envelope. This can break existing caches (and manual cache.set usage) where the cached value is an object containing __v (e.g., Mongoose documents), causing the decorator to return the inner __v field instead of the full object. Consider using an unambiguous marker (e.g., __cachekit: 1 + value) and/or a stricter guard (e.g., require a marker and hasOwnProperty) so non-envelope objects are never misclassified.

[Copilot]

CacheEnvelope claims it can preserve undefined, but JSON serialization drops undefined object properties (e.g., { __v: undefined } becomes {}), so methods returning undefined will never actually be cached and will re-execute on every call. Either remove the undefined claim from docs/types, or change the envelope format to include a dedicated marker field so an "envelope with undefined" can round-trip reliably.

[Copilot]

Storing { __v: result } changes the on-disk/on-Redis value shape for keys written by @Cacheable, and the new JSDoc explicitly warns that CacheService.get() will now return the raw envelope object for those keys. That’s a breaking change in how @Cacheable interoperates with the library’s primary public API (CacheService). Consider keeping the external value shape stable (e.g., by namespacing decorator keys, or by unwrapping the envelope transparently in CacheService.get()/wrap() when a Cacheable-envelope marker is detected), and document the migration/compatibility story for existing cached entries.