Develop

[y-aithnini]

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?

[Copilot]

Pull request overview

This PR transitions the repository from the template “ExampleKit” shape into an initial public release of @ciscode/cachekit: a NestJS caching module with pluggable store adapters (memory/Redis), an injectable CacheService, and method decorators for transparent caching/eviction.

Changes:

• Added CacheKit core: CacheModule (dynamic module), CacheService, ports/adapters, and @Cacheable / @CacheEvict decorators.
• Added comprehensive Jest test coverage for the new module/service/adapters/utilities and increased global coverage thresholds.
• Updated packaging, docs, TypeScript/Jest alias configuration, and CI/CD workflows (release checks, publish pipeline, dependabot/codeowners).

Reviewed changes

Copilot reviewed 28 out of 30 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
tsconfig.json	Adds new path aliases for @ports/* and @adapters/* (and updates utils alias).
src/utils/resolve-cache-key.util.ts	Implements {n} placeholder interpolation for cache key templates.
src/utils/resolve-cache-key.util.spec.ts	Unit tests for cache key interpolation behavior and edge cases.
src/utils/cache-service-ref.ts	Adds a module-scoped singleton reference used by decorators to access CacheService.
src/utils/cache-service-ref.spec.ts	Tests singleton behavior and error when accessed before initialization.
src/services/cache.service.ts	Implements primary caching API (get/set/delete/clear/has/wrap) over ICacheStore.
src/services/cache.service.spec.ts	Tests core service behavior including TTL resolution and wrap() semantics.
src/ports/cache-store.port.ts	Defines the ICacheStore abstraction used by adapters and the service.
src/index.ts	Updates public exports to CacheKit module/service/decorators/adapters/tokens/port types.
src/decorators/cacheable.decorator.ts	Adds cache-aside method decorator with key templating and envelope handling.
src/decorators/cacheable.decorator.spec.ts	Tests caching behavior (hit/miss), interpolation, TTL forwarding, and sync/async support.
src/decorators/cache-evict.decorator.ts	Adds eviction decorator that deletes a resolved key after successful execution.
src/decorators/cache-evict.decorator.spec.ts	Tests eviction behavior, error path (no eviction), interpolation, sync/async support.
src/constants.ts	Introduces exported DI tokens (CACHE_STORE, CACHE_MODULE_OPTIONS).
src/cache-kit.module.ts	Implements CacheModule.register() / registerAsync() and adapter wiring logic.
src/cache-kit.module.spec.ts	Tests module wiring, async registration, and CacheServiceRef initialization.
src/adapters/redis-cache-store.adapter.ts	Adds ioredis-backed store adapter with prefix support and SCAN-based clear.
src/adapters/redis-cache-store.adapter.spec.ts	Tests Redis adapter using ioredis-mock (including prefix clear semantics).
src/adapters/in-memory-cache-store.adapter.ts	Adds Map-backed adapter with lazy TTL eviction and JSON serialization.
src/adapters/in-memory-cache-store.adapter.spec.ts	Tests in-memory adapter contract, TTL expiry, and parse-error behavior.
README.md	Rewrites README for CacheKit usage, configuration, and API overview.
package.json	Renames package/versioning intent, adjusts deps/peers, and adds ioredis-mock dev dependency.
package-lock.json	Updates lockfile to reflect dependency/peer changes and added dev deps.
jest.config.ts	Updates coverage thresholds and module mappers; adds forceExit.
.github/workflows/release-check.yml	Restructures CI into quality/test/build/sonar jobs and adds status reporting.
.github/workflows/publish.yml	Switches publish trigger to master push and adds tag/version validation + provenance publish.
.github/workflows/pr-validation.yml	Updates Node version used in PR validation.
.github/dependabot.yml	Adds dependabot configuration for npm dependencies.
.github/CODEOWNERS	Adds repository-wide codeowner rule.
.changeset/compt-59-v0-1-0.md	Adds changeset describing the initial public release contents.

Comments suppressed due to low confidence (2)

README.md:287

• The README still contains the old template sections starting at "### 3. Define DTOs" (ExampleKitModule, class-validator DTOs, etc.). This conflicts with the new CacheKit API and the updated dependencies; remove or replace this leftover template content to avoid misleading consumers.

## 📄 License

MIT © [CisCode](https://github.com/CISCODE-MA)

### 3. Define DTOs

```typescript
// src/dto/create-example.dto.ts
import { IsString, IsNotEmpty } from "class-validator";

export class CreateExampleDto {
  @IsString()
  @IsNotEmpty()
  name: string;
}

**.github/workflows/publish.yml:88**
* The workflow publishes twice (two "Publish to NPM" steps). The second publish will fail with "previously published" (or could race) and makes the job non-idempotent. Keep a single publish step (with provenance if desired).

  - name: Publish to NPM
    run: npm publish --access public --provenance
    env:
      NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

  - name: Publish to NPM
    run: npm publish --access public
    env:
      NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

</details>

[Copilot]

createAsyncProviders()'s useExisting branch registers { provide: factoryClass, useExisting: options.useExisting } where factoryClass is options.useExisting, resulting in a self-referential provider (provide: X, useExisting: X). This will break registerAsync({ useExisting: ... }) at runtime; the factory instance should be injected from the existing token without re-providing it (or the provide token should differ).

Suggested change

	const factoryClass = (options.useClass ?? options.useExisting)!;
	const factoryProvider: Provider = options.useClass
	? // useClass: let NestJS instantiate a new instance of this class
	{ provide: factoryClass, useClass: factoryClass }
	: // useExisting: reuse a token already registered elsewhere in the module tree
	{ provide: factoryClass, useExisting: options.useExisting };
	return [
	factoryProvider,
	{
	// Call createCacheOptions() on the factory instance to get the options
	provide: CACHE_MODULE_OPTIONS,
	useFactory: (factory: {
	createCacheOptions(): Promise<CacheModuleOptions> | CacheModuleOptions;
	}) => factory.createCacheOptions(),
	inject: [factoryClass],
	if (options.useClass) {
	return [
	{
	// useClass: let NestJS instantiate a new instance of this class
	provide: options.useClass,
	useClass: options.useClass,
	},
	{
	// Call createCacheOptions() on the factory instance to get the options
	provide: CACHE_MODULE_OPTIONS,
	useFactory: (factory: {
	createCacheOptions(): Promise<CacheModuleOptions> | CacheModuleOptions;
	}) => factory.createCacheOptions(),
	inject: [options.useClass],
	},
	{
	// Build the store adapter from the resolved options
	provide: CACHE_STORE,
	useFactory: (resolvedOptions: CacheModuleOptions): ICacheStore =>
	createStoreFromOptions(resolvedOptions),
	inject: [CACHE_MODULE_OPTIONS],
	},
	];
	}
	return [
	{
	// useExisting: inject a token already registered elsewhere in the module tree
	provide: CACHE_MODULE_OPTIONS,
	useFactory: (factory: {
	createCacheOptions(): Promise<CacheModuleOptions> | CacheModuleOptions;
	}) => factory.createCacheOptions(),
	inject: [options.useExisting!],

[Copilot]

The CacheModuleOptionsFactory type is defined as a function signature, but useClass/useExisting expect an object with createCacheOptions(). This mismatch is confusing for consumers implementing async config classes; align the type alias and the interface expectations (and update the comments) so the contract is unambiguous.

Suggested change

	* Factory function type used by registerAsync's useFactory.
	* May return the options synchronously or as a Promise.
	*/
	export type CacheModuleOptionsFactory = () => Promise<CacheModuleOptions> | CacheModuleOptions;
	/**
	* Asynchronous configuration options for CacheModule.registerAsync().
	* Supports three patterns:
	* - useFactory — inline factory function (most common)
	* - useClass — instantiate a config class per module
	* - useExisting — reuse an already-provided config class
	*/
	export interface CacheModuleAsyncOptions {
	/** Providers whose tokens are passed as arguments to useFactory. */
	inject?: Array<InjectionToken | OptionalFactoryDependency>;
	/** Inline factory that resolves to CacheModuleOptions. */
	useFactory?: (...args: unknown[]) => Promise<CacheModuleOptions> | CacheModuleOptions;
	/**
	* Class that the module will instantiate to obtain the options.
	* The class must implement CacheModuleOptionsFactory.
	*/
	useClass?: Type<{ createCacheOptions(): Promise<CacheModuleOptions> | CacheModuleOptions }>;
	/**
	* Re-use an already-provided token (class or value) as the options factory.
	* The resolved instance must implement CacheModuleOptionsFactory.
	*/
	useExisting?: Type<{ createCacheOptions(): Promise<CacheModuleOptions> | CacheModuleOptions }>;
	* Contract implemented by async configuration providers used with
	* registerAsync({ useClass }) and registerAsync({ useExisting }).
	* The provider may return the options synchronously or as a Promise.
	*/
	export interface CacheModuleOptionsFactory {
	createCacheOptions(): Promise<CacheModuleOptions> | CacheModuleOptions;
	}
	/**
	* Asynchronous configuration options for CacheModule.registerAsync().
	* Supports three patterns:
	* - useFactory — inline factory function that returns CacheModuleOptions
	* - useClass — instantiate a config class implementing CacheModuleOptionsFactory
	* - useExisting — reuse an already-provided provider implementing CacheModuleOptionsFactory
	*/
	export interface CacheModuleAsyncOptions {
	/** Providers whose tokens are passed as arguments to useFactory. */
	inject?: Array<InjectionToken | OptionalFactoryDependency>;
	/** Inline factory function that resolves to CacheModuleOptions. */
	useFactory?: (...args: unknown[]) => Promise<CacheModuleOptions> | CacheModuleOptions;
	/**
	* Class that the module will instantiate to obtain the options.
	* The instantiated class must implement CacheModuleOptionsFactory.
	*/
	useClass?: Type<CacheModuleOptionsFactory>;
	/**
	* Re-use an already-provided token (class or value) as the options factory.
	* The resolved instance must implement CacheModuleOptionsFactory.
	*/
	useExisting?: Type<CacheModuleOptionsFactory>;

[Copilot]

README examples use keyPrefix: "myapp:" / default "app:", but RedisCacheStore.buildKey() always inserts its own : separator. With a trailing colon this produces double-colons (e.g. myapp::user:1). Update the docs (or normalize in code) to clarify whether keyPrefix should include a trailing :.

Suggested change

	keyPrefix: "myapp:",
	keyPrefix: "myapp",

[Copilot]

npm run lint is effectively ignored (|| true), so the workflow may publish even when lint fails. If lint is intended to be non-blocking, make that explicit; otherwise remove the || true so publishing is gated on lint success.

[Copilot]

forceExit: true makes Jest exit even when there are open handles, which can mask real resource leaks and flaky tests. Prefer cleaning up the ioredis-mock instances (e.g., disconnect/quit in afterEach/afterAll) and keep forceExit off if possible.

Suggested change

	// forceExit closes open ioredis handles left by ioredis-mock after tests finish
	forceExit: true,

[Copilot]

@Cacheable claims it can preserve cached undefined values (see the comments and CacheEnvelope doc), but both adapters serialize via JSON.stringify. JSON.stringify({ __v: undefined }) becomes {}, so the __v property is lost and the next read is treated as a cache miss. Either disallow/normalize undefined return values (e.g., convert to null + sentinel) or change the envelope encoding so undefined can round-trip, and add a test for the undefined case.

[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