skills / giuseppe-trisciuoglio / developer-kit / typescript-docs 
typescript-docs 
$ npx skills add https://github.com/giuseppe-trisciuoglio/developer-kit --skill typescript-docs SKILL.md 
TypeScript Documentation Skill 
Overview 
Deliver production-ready TypeScript documentation that serves multiple audiences through layered documentation architecture. Generate API docs with TypeDoc, create architectural decision records, and maintain comprehensive code examples. 
When to Use 
"generate TypeScript API docs" - Create TypeDoc configuration and generate documentation 
"document this TypeScript module" - Add comprehensive JSDoc to a module 
"create ADR for TypeScript decision" - Document architectural decisions 
"setup documentation pipeline" - Configure automated documentation generation 
"document React component" - Create component documentation with examples 
"create API reference" - Generate comprehensive API documentation 
Instructions 
Configure TypeDoc : Set up typedoc.json with entry points and output settings 
Add JSDoc Comments : Document all public APIs with @param, @returns, @example 
Create ADRs : Document architectural decisions with context and consequences 
Set Up Pipeline : Configure CI/CD for automated documentation generation 
Write Examples : Include runnable code examples for complex functions 
Cross-Reference : Use @see and @link to connect related documentation 
Validate Docs : Run ESLint with JSDoc rules to ensure completeness 
Examples 
Documenting a Service Class 

/** * Service for managing user authentication and authorization * * @remarks * This service handles JWT-based authentication, password hashing, * and role-based access control. * * @example * ```typescript * const authService = new AuthService(config); * const token = await authService.login(email, password); * const user = await authService.verifyToken(token); * ``` * * @security * - All passwords hashed with bcrypt (cost factor 12) * - JWT tokens signed with RS256 * - Rate limiting on authentication endpoints */ @ Injectable ( ) export class AuthService { /** * Authenticates a user and returns access tokens * @param credentials - User login credentials * @returns Authentication result with access and refresh tokens * @throws {InvalidCredentialsError} If credentials are invalid */ async login ( credentials : LoginCredentials ) : Promise < AuthResult > { // Implementation } } 
Constraints and Warnings 
Private Members : Use @private or exclude from TypeDoc output 
Complex Types : Document generic constraints and type parameters 
Breaking Changes : Use @deprecated with migration guidance 
Security Info : Never include secrets or credentials in documentation 
Link Validity : Ensure @see references point to valid locations 
Example Code : All examples should be runnable and tested 
Versioning : Keep documentation in sync with code versions 
Quick Start 
Install TypeDoc and related tools: 

npm install --save-dev typedoc typedoc-plugin-markdown npm install --save-dev @compodoc/compodoc # For Angular 
Create basic TypeDoc configuration: 

{ "entryPoints" : [ "src/index.ts" ] , "out" : "docs/api" , "theme" : "markdown" , "excludePrivate" : true , "readme" : "README.md" } 
Generate documentation: 

npx typedoc 
Core Documentation Patterns 
1. JSDoc Best Practices 
Interface Documentation 

/** * Represents a user in the authentication system * @interface User * * @property id - Unique identifier (UUID v4) * @property email - User's email address (validated format) * @property roles - Array of user roles for RBAC * @property metadata - Additional user data (preferences, settings) * * @example * ```typescript * const user: User = { *   id: "550e8400-e29b-41d4-a716-446655440000", *   email: "user@example.com", *   roles: ["user", "admin"], *   metadata: { *     theme: "dark", *     language: "en" *   } * }; * ``` * * @see {@link UserRole} for role definitions * @see {@link UserService} for user operations */ export interface User { id : string ; email : string ; roles : UserRole [ ] ; metadata : Record < string , unknown > ; } 
Function Documentation 

/** * Authenticates a user with email and password * @param email - User's email address * @param password - User's password (min 8 characters) * @param options - Additional authentication options * @returns Promise resolving to authentication result * * @throws {InvalidCredentialsError} If email/password don't match * @throws {AccountLockedError} If account is locked after failed attempts * @throws {RateLimitExceededError} If too many attempts made * * @remarks * Implements secure authentication with: * - Bcrypt password hashing (cost factor 12) * - Rate limiting (5 attempts per 15 minutes) * - Account lockout after 3 consecutive failures * - JWT token generation with 15-minute expiry * * @example * ```typescript * try { *   const result = await authenticateUser("user@example.com", "password123"); *   console.log(`Authenticated: ${result.user.email}`); * } catch (error) { *   if (error instanceof InvalidCredentialsError) { *     // Handle invalid credentials *   } * } * ``` * * @security * - Passwords are never logged or stored in plain text * - Uses timing-attack safe comparison * - Implements CSRF protection for web requests * * @performance * - Average response time: ~200ms * - Uses connection pooling for database queries * - Caches user permissions for 5 minutes */ export async function authenticateUser ( email : string , password : string , options ? : AuthOptions ) : Promise < AuthResult > { // Implementation } 
Class Documentation 

/** * Service for managing user authentication and authorization * * @remarks * This service handles: * - User authentication with JWT tokens * - Password reset flows * - Multi-factor authentication * - Session management * - Role-based access control * * @example * ```typescript * const authService = new AuthService(config); * * // Authenticate user * const token = await authService.login(email, password); * * // Verify token * const user = await authService.verifyToken(token); * ``` * * @security * - All passwords hashed with bcrypt * - JWT tokens signed with RS256 * - Rate limiting on authentication endpoints * - Secure session management * * @performance * - Uses Redis for session storage * - Implements connection pooling * - Caches user permissions */ export class AuthService { /** * Creates an instance of AuthService * @param config - Service configuration * @param config.jwtSecret - Secret key for JWT signing * @param config.tokenExpiry - Token expiry duration * @param config.refreshTokenExpiry - Refresh token expiry */ constructor ( private readonly config : AuthConfig ) { } /** * Authenticates a user and returns access tokens * @param credentials - User credentials * @returns Authentication result with tokens */ async login ( credentials : LoginCredentials ) : Promise < AuthResult > { // Implementation } } 
2. Advanced TypeScript Documentation 
Generic Constraints 

/** * Repository base class for TypeScript entities * @template T - Entity type (must extend BaseEntity) * @template K - Primary key type (string | number) * * @remarks * Provides CRUD operations with type safety. * All methods return Result types for explicit error handling. * * @example * ```typescript * class UserRepository extends BaseRepository<User, string> { *   async findByEmail(email: string): Promise<Result<User, RepositoryError>> { *     // Implementation *   } * } * ``` */ export abstract class BaseRepository < T extends BaseEntity , K extends string | number > { /** * Finds an entity by its primary key * @param id - Primary key value * @returns Result containing entity or error */ abstract findById ( id : K ) : Promise < Result < T , RepositoryError >> ; } 
Union Types and Discriminated Unions 

/** * Represents different types of API responses * @variant success - Successful response with data * @variant error - Error response with error details * @variant pending - Pending response for async operations * * @example * ```typescript * type ApiResponse<T> = SuccessResponse<T> | ErrorResponse | PendingResponse; * * function handleResponse<T>(response: ApiResponse<T>) { *   switch (response.status) { *     case 'success': *       console.log(response.data); *       break; *     case 'error': *       console.error(response.error); *       break; *     case 'pending': *       console.log('Loading...'); *       break; *   } * } * ``` */ export type ApiResponse < T > = | { status : 'success' ; data : T } | { status : 'error' ; error : ApiError } | { status : 'pending' ; progress ? : number } ; 
3. Framework-Specific Documentation 
NestJS Documentation 

/** * Guard for protecting routes with JWT authentication * * @guard * @remarks * Validates JWT tokens from Authorization header. * Attaches user data to request object. * * @usageNotes * Apply to controllers or methods: * ```typescript * @Controller('users') * @UseGuards(JwtAuthGuard) * export class UserController { *   @Get('profile') *   getProfile(@Request() req) { *     return req.user; *   } * } * ``` * * @security * - Validates token signature * - Checks token expiration * - Prevents token replay attacks * * @performance * - Caches validation results for 5 minutes * - Uses Redis for distributed caching */ @ Injectable ( ) export class JwtAuthGuard implements CanActivate { constructor ( private jwtService : JwtService ) { } /** * Validates JWT token and extracts user data * @param context - Execution context * @returns True if authentication successful */ async canActivate ( context : ExecutionContext ) : Promise < boolean > { // Implementation } } 
React Component Documentation 

/** * User profile card component * @component * @param {UserProfileProps} props - Component props * @param {User} props.user - User data to display * @param {boolean} props.editable - Whether profile is editable * @param {function} props.onEdit - Edit button click handler * * @example * ```tsx * export default function Dashboard() { *   const { user } = useAuth(); * *   return ( *     <div> *       <h1>User Profile</h1> *       <UserProfile *         user={user} *         editable={true} *         onEdit={() => console.log('Edit clicked')} *       /> *     </div> *   ); * } * ``` * * @performance * - Memoized with React.memo * - Lazy loads avatar images * - Optimistic UI updates * * @accessibility * - Full keyboard navigation * - ARIA labels for screen readers * - High contrast support */ export const UserProfile = React . memo < UserProfileProps > ( ( { user , editable , onEdit } ) => { // Implementation } ) ; 
Express Middleware Documentation 

/** * Rate limiting middleware with Redis backend * @middleware * @param options - Rate limiting options * @param options.windowMs - Time window in milliseconds * @param options.max - Maximum requests per window * @param options.keyGenerator - Function to generate rate limit key * * @example * ```typescript * app.use('/api', rateLimit({ *   windowMs: 15 * 60 * 1000, // 15 minutes *   max: 100, // limit each IP to 100 requests per windowMs *   keyGenerator: (req) => req.ip * })); * ``` * * @errorResponses * - `429` - Too many requests * - `500` - Redis connection error * * @security * - Prevents DoS attacks * - Implements sliding window algorithm * - Distributed across multiple servers */ export function rateLimit ( options : RateLimitOptions ) : RequestHandler { // Implementation } 
Architectural Decision Records (ADRs) 
ADR Template 

# ADR-001: TypeScript Strict Mode Configuration ## Status Proposed | Accepted | Rejected | Deprecated | Superseded ## Context What is the issue that we're seeing that is motivating this decision? ## Decision What is the change that we're proposing and/or doing? ## Consequences What becomes easier or more difficult to do because of this change? ## Compliance - Links to standards or regulations - Impact on compliance requirements ## References - [ TypeScript Strict Mode Documentation ]( https://www.typescriptlang.org/tsconfig#strict ) - [ Related ADRs ]( # ) 
Sample ADR 

# ADR-003: NestJS Framework Selection for Backend API ## Status Accepted ## Context Our Express.js monolith has grown to 50k+ lines with: - Inconsistent error handling patterns - No standardized validation - Difficult testing due to tight coupling - Poor TypeScript integration We need a framework that provides: - Strong TypeScript support - Opinionated structure - Built-in validation and error handling - Excellent testing support - Microservices readiness ## Decision Adopt NestJS for all new backend services with: - Full TypeScript strict mode - Class-based DI container - Modular architecture - Built-in validation pipes - Exception filters - Swagger/OpenAPI integration ## Consequences ### Positive - 40% reduction in boilerplate code - Consistent patterns across services - Improved testability with dependency injection - Better developer experience with decorators - Built-in support for microservices ### Negative - Learning curve for team (2-3 weeks) - More complex for simple APIs - Requires understanding of decorators - Additional build step needed ## Implementation 1. Create NestJS starter template 2. Migrate new services to NestJS 3. Gradually refactor critical Express services 4. Establish NestJS best practices guide ## Compliance - Aligns with architecture standards v2.1 - Supports SOC2 through better error handling - Enables GDPR compliance with structured logging 
Documentation Generation Pipeline 
TypeDoc Configuration 

{ "entryPoints" : [ "src/index.ts" ] , "out" : "docs/api" , "theme" : "markdown" , "readme" : "README.md" , "excludePrivate" : true , "excludeProtected" : false , "excludeExternals" : true , "includeVersion" : true , "sort" : [ "source-order" ] , "kindSortOrder" : [ "Document" , "Project" , "Module" , "Namespace" , "Enum" , "Class" , "Interface" , "TypeAlias" , "Constructor" , "Property" , "Method" ] , "categorizeByGroup" : true , "categoryOrder" : [ "Authentication" , "Authorization" , "*" , "Other" ] , "navigation" : { "includeCategories" : true , "includeGroups" : true } } 
Documentation Scripts 

{ "scripts" : { "docs:generate" : "typedoc" , "docs:serve" : "cd docs && python -m http.server 8080" , "docs:validate" : "node scripts/validate-docs.js" , "docs:deploy" : "npm run docs:generate && ./scripts/deploy-docs.sh" , "adr:new" : "node scripts/create-adr.js" , "adr:generate-index" : "node scripts/generate-adr-index.js" } } 
GitHub Actions Workflow 

name : Documentation on : push : branches : [ main , develop ] paths : - 'src/**' - 'docs/**' - '.github/workflows/docs.yml' jobs : generate-docs : runs-on : ubuntu - latest steps : - uses : actions/checkout@v3 - name : Setup Node.js uses : actions/setup - node@v3 with : node-version : '18' cache : 'npm' - name : Install dependencies run : npm ci - name : Generate TypeDoc run : npm run docs : generate - name : Validate documentation run : npm run docs : validate - name : Check for documentation changes id : changes run : | if git diff --quiet HEAD~1 docs/; then echo "changed=false" >> $GITHUB_OUTPUT else echo "changed=true" >> $GITHUB_OUTPUT fi - name : Commit documentation if : steps.changes.outputs.changed == 'true' run : | git config --local user.email "action@github.com" git config --local user.name "GitHub Action" git add docs/ git commit -m "docs: update generated documentation [skip ci]" git push - name : Deploy to GitHub Pages uses : peaceiris/actions - gh - pages@v3 with : github_token : $ { { secrets.GITHUB_TOKEN } } publish_dir : ./docs 
Framework-Specific Documentation 
NestJS Documentation Patterns 

/** * Decorator for rate limiting endpoints * @decorator * @param options - Rate limiting options * * @usageNotes * Apply to controller methods: * ```typescript * @Controller('users') * export class UserController { *   @Get() *   @RateLimit({ points: 100, duration: 60 }) *   async findAll() { *     // Implementation *   } * } * ``` * * @see {@link RateLimitInterceptor} * @see {@link RateLimitOptions} */ export const RateLimit = ( options : RateLimitOptions ) => applyDecorators ( UseInterceptors ( RateLimitInterceptor ) , SetMetadata ( 'rateLimit' , options ) ) ; 
React Documentation Patterns 

/** * Custom hook for managing form state with validation * @hook * @param schema - Yup validation schema * @param initialValues - Initial form values * @returns Form state and handlers * * @example * ```tsx * function LoginForm() { *   const { values, errors, handleSubmit, handleChange } = useForm({ *     schema: loginSchema, *     initialValues: { email: '', password: '' } *   }); * *   return ( *     <form onSubmit={handleSubmit}> *       <input *         name="email" *         value={values.email} *         onChange={handleChange} *       /> *       {errors.email && <span>{errors.email}</span>} *     </form> *   ); * } * ``` * * @performance * - Memoized validation to prevent unnecessary re-renders * - Debounced validation for better UX * - Optimistic updates for better perceived performance */ export function useForm < T > ( { schema , initialValues } : UseFormOptions < T > ) : UseFormReturn < T > { // Implementation } 
Angular Documentation Patterns 

/** * Service for managing user sessions * @injectable * @providedIn root * * @remarks * Handles user authentication state across the application. * Automatically refreshes tokens before expiry. * * @example * ```typescript * export class AppComponent { *   constructor(private authService: AuthService) {} * *   async login() { *     await this.authService.login(credentials); *   } * } * ``` * * @security * - Stores tokens in secure storage * - Implements token refresh logic * - Handles logout on all tabs (broadcast channel) */ @ Injectable ( { providedIn : 'root' } ) export class AuthService { // Implementation } 
Documentation Validation 
TypeDoc Plugin for Validation 

// typedoc-plugin-validation.js export function load ( app ) { app . converter . on ( Converter . EVENT_CREATE_SIGNATURE , ( context , reflection , node ? ) => { // Check if method has JSDoc if ( reflection . kind === ReflectionKind . Method ) { const comment = reflection . comment ; if ( ! comment ) { app . logger . warn ( ` Method ${ reflection . name } lacks documentation in ${ reflection . parent . name } ` ) ; } } } ) ; } 
ESLint Rules for Documentation 

{ "rules" : { "jsdoc/require-description" : "error" , "jsdoc/require-param-description" : "error" , "jsdoc/require-returns-description" : "error" , "jsdoc/require-example" : "warn" , "jsdoc/check-alignment" : "error" , "jsdoc/check-indentation" : "error" , "jsdoc/tag-lines" : [ "error" , "any" , { "startLines" : 1 } ] } } 
Best Practices 
Document Public APIs : All public methods, classes, and interfaces 
Use @example : Provide runnable examples for complex functions 
Include @throws : Document all possible errors 
Add @see : Cross-reference related functions/types 
Use @remarks : Add implementation details and notes 
Document Generics : Explain generic constraints and usage 
Include Performance Notes : Document time/space complexity 
Add Security Warnings : Highlight security considerations 
Use Categories : Group related documentation 
Keep Updated : Update docs when code changes 
Common Pitfalls to Avoid 
Don't document obvious code : Focus on why, not what 
Avoid outdated examples : Keep examples current 
Don't skip error cases : Document all @throws scenarios 
Avoid generic descriptions : Be specific to your implementation 
Don't ignore edge cases : Document special conditions 
Avoid broken links : Keep @see references valid 
Don't use unclear language : Write for your audience 
Avoid duplication : Link to related docs instead of repeating Weekly Installs 443 Repository giuseppe-trisciuoglio/developer-kit First Seen Jan 17, 2026 Security Audits Gen Agent Trust Hub Pass Socket Pass Snyk Pass Installed on claude-code 322 opencode 279 gemini-cli 265 cursor 262 antigravity 246 codex 237