Skip to content

README.md

Latest commit

 

History

History
324 lines (245 loc) · 7.49 KB

README.md

File metadata and controls

324 lines (245 loc) · 7.49 KB

CacheKit

CacheKit provides reusable caching utilities and integrations for NestJS services.

🎯 What You Get

  • ✅ CSR Architecture - Controller-Service-Repository pattern
  • ✅ TypeScript - Strict mode with path aliases
  • ✅ Testing - Jest with 80% coverage threshold
  • ✅ Code Quality - ESLint + Prettier + Husky
  • ✅ Versioning - Changesets for semantic versioning
  • ✅ CI/CD - GitHub Actions workflows
  • ✅ Documentation - Complete Copilot instructions
  • ✅ Examples - Full working examples for all layers

📦 Installation

# Clone CacheKit
git clone https://github.com/CISCODE-MA/CacheKit.git cachekit
cd cachekit

# Install dependencies
npm install

# Start developing
npm run build
npm test

🏗️ Architecture

src/
  ├── index.ts                    # PUBLIC API exports
  ├── {module-name}.module.ts     # NestJS module definition
  │
  ├── controllers/                # HTTP Layer
  │   └── example.controller.ts
  │
  ├── services/                   # Business Logic
  │   └── example.service.ts
  │
  ├── entities/                   # Domain Models
  │   └── example.entity.ts
  │
  ├── repositories/               # Data Access
  │   └── example.repository.ts
  │
  ├── guards/                     # Auth Guards
  │   └── example.guard.ts
  │
  ├── decorators/                 # Custom Decorators
  │   └── example.decorator.ts
  │
  ├── dto/                        # Data Transfer Objects
  │   ├── create-example.dto.ts
  │   └── update-example.dto.ts
  │
  ├── filters/                    # Exception Filters
  ├── middleware/                 # Middleware
  ├── config/                     # Configuration
  └── utils/                      # Utilities

🚀 Usage

1. Customize Your Module

// src/example-kit.module.ts
import { Module, DynamicModule } from "@nestjs/common";
import { ExampleService } from "@services/example.service";

@Module({})
export class ExampleKitModule {
  static forRoot(options: ExampleKitOptions): DynamicModule {
    return {
      module: ExampleKitModule,
      providers: [ExampleService],
      exports: [ExampleService],
    };
  }
}

2. Create Services

// src/services/example.service.ts
import { Injectable } from "@nestjs/common";

@Injectable()
export class ExampleService {
  async doSomething(data: string): Promise<string> {
    return `Processed: ${data}`;
  }
}

3. Define DTOs

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

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

4. Export Public API

// src/index.ts
export { ExampleKitModule } from "./example-kit.module";
export { ExampleService } from "./services/example.service";
export { CreateExampleDto } from "./dto/create-example.dto";

📝 Scripts

# Development
npm run build          # Build the package
npm run build:watch    # Build in watch mode
npm run typecheck      # TypeScript type checking

# Testing
npm test               # Run tests
npm run test:watch     # Run tests in watch mode
npm run test:cov       # Run tests with coverage

# Code Quality
npm run lint           # Run ESLint
npm run format         # Check formatting
npm run format:write   # Fix formatting

# Release
npx changeset          # Create a changeset
npm run release        # Publish to npm (CI does this)

🔄 Release Workflow

This template uses Changesets for version management.

1. Create a Feature

git checkout develop
git checkout -b feature/my-feature
# Make your changes

2. Create a Changeset

npx changeset

Select the change type:

  • patch - Bug fixes
  • minor - New features (backwards compatible)
  • major - Breaking changes

3. Commit and PR

git add .
git commit -m "feat: add new feature"
git push origin feature/my-feature
# Create PR → develop

4. Release

  • Automation opens "Version Packages" PR
  • Merge to master to publish

🧪 Testing

Tests are MANDATORY for all public APIs.

// src/services/example.service.spec.ts
describe("ExampleService", () => {
  let service: ExampleService;

  beforeEach(async () => {
    const module = await Test.createTestingModule({
      providers: [ExampleService],
    }).compile();

    service = module.get(ExampleService);
  });

  it("should be defined", () => {
    expect(service).toBeDefined();
  });

  it("should process data correctly", async () => {
    const result = await service.doSomething("test");
    expect(result).toBe("Processed: test");
  });
});

Coverage threshold: 80%

📚 Path Aliases

Configured in tsconfig.json:

import { ExampleService } from "@services/example.service";
import { CreateExampleDto } from "@dtos/create-example.dto";
import { Example } from "@entities/example.entity";
import { ExampleRepository } from "@repos/example.repository";

Available aliases:

  • @/* → src/*
  • @controllers/* → src/controllers/*
  • @services/* → src/services/*
  • @entities/* → src/entities/*
  • @repos/* → src/repositories/*
  • @dtos/* → src/dto/*
  • @guards/* → src/guards/*
  • @decorators/* → src/decorators/*
  • @config/* → src/config/*
  • @utils/* → src/utils/*

🔒 Security Best Practices

  • ✅ Input validation on all DTOs (class-validator)
  • ✅ Environment variables for secrets
  • ✅ No hardcoded credentials
  • ✅ Proper error handling
  • ✅ Rate limiting on public endpoints

🤖 AI-Friendly Development

This template includes comprehensive Copilot instructions in .github/copilot-instructions.md:

  • Module architecture guidelines
  • Naming conventions
  • Testing requirements
  • Documentation standards
  • Export patterns
  • Security best practices

📖 Documentation

🛠️ Customization

  1. Rename the module: Update package.json name
  2. Update description: Modify package.json description
  3. Configure exports: Edit src/index.ts
  4. Add dependencies: Update peerDependencies and dependencies
  5. Customize structure: Add/remove directories as needed

⚠️ Important Notes

What to Export

✅ DO export:

  • Module
  • Services
  • DTOs
  • Guards
  • Decorators
  • Types/Interfaces

❌ DON'T export:

  • Entities
  • Repositories

Entities and repositories are internal implementation details.

Versioning

  • MAJOR (x.0.0) - Breaking changes
  • MINOR (0.x.0) - New features (backwards compatible)
  • PATCH (0.0.x) - Bug fixes

📋 Checklist Before Publishing

  • All tests passing (80%+ coverage)
  • No ESLint warnings
  • TypeScript strict mode passing
  • All public APIs documented (JSDoc)
  • README updated
  • Changeset created
  • Breaking changes documented
  • .env.example updated (if needed)

📄 License

MIT

🤝 Contributing

See CONTRIBUTING.md

🆘 Support

Made with ❤️ by CisCode