🔧 TypeScript Starter

TypeScript Starter - A starter template with TypeScript rules, tooling, and configuration for Node.js projects.

---

🎯 Strict Coding Rules (Enforced)

TypeScript Rules

// ✅ ENFORCED: Strict mode with comprehensive type checking// ✅ ENFORCED: No implicit any types// ✅ ENFORCED: No unused variables or parameters// ✅ ENFORCED: All code paths must return// ✅ ENFORCED: Explicit type annotations required// ✅ ENFORCED: No unreachable code// ✅ ENFORCED: Exact optional property types// ✅ ENFORCED: No unchecked indexed access// ❌ This will fail:functionbadFunction(input){// implicit anyif(condition)returnvalue// not all paths returnconstunused="never used"// unused variable}// ✅ This passes:functiongoodFunction: (input: string)=> string =(input: string): string=>{if(condition){returnvalue}returndefaultValue}

Code Style Rules

// ✅ ENFORCED: Single quotes, no semicolons// ✅ ENFORCED: 2-space indentation// ✅ ENFORCED: No trailing commas// ✅ ENFORCED: Required curly braces// ✅ ENFORCED: Spaces inside object braces// ✅ ENFORCED: No spaces inside array brackets// ✅ ENFORCED: Consistent naming conventions// ❌ This will fail:constobj={a: 1,b: 2,};// trailing commaconstarr=[1,2,3];// spaces in arrayif(condition)returnvalue;// no curly braces, semicolon// ✅ This passes:constobj={a: 1,b: 2}constarr=[1,2,3]if(condition){returnvalue}

Best Practices Rules

// ✅ ENFORCED: Prefer const over let/var// ✅ ENFORCED: Arrow functions for callbacks// ✅ ENFORCED: Template literals over concatenation// ✅ ENFORCED: Object destructuring where applicable// ✅ ENFORCED: No inline comments// ✅ ENFORCED: Cognitive complexity ≤ 15// ✅ ENFORCED: No duplicate code// ✅ ENFORCED: Prefer immediate returns// ❌ This will fail:varoldWay="string"+variable;// var, concatenationfunctioncallback(){returnvalue;}// function instead of arrow// inline comment // inline comment// ✅ This passes:constnewWay=`string ${variable}`constcallback=()=>value// Block comment for complex logic

Quality Rules

// ✅ ENFORCED: No duplicate strings// ✅ ENFORCED: No identical functions// ✅ ENFORCED: No redundant boolean expressions// ✅ ENFORCED: Prefer immediate returns// ✅ ENFORCED: No one-iteration loops// ✅ ENFORCED: No unused variables// ✅ ENFORCED: No unreachable code// ❌ This will fail:constmessage="Hello"constgreeting="Hello"// duplicate stringif(condition===true){// redundant booleanreturnvalue}// ✅ This passes:constMESSAGES={GREETING: "Hello"}asconstif(condition){returnvalue}

---

🚀 Quick Start

Installation

# Clone and start coding
git clone https://github.com/NeaByteLab/TypeScript-Starter.git my-project
cd my-project
npm install
npm run dev

Development Commands

# Development
npm run dev # TypeScript watch mode
npm run build # Build for production
npm run clean # Clean build directory# Code Quality
npm run lint # ESLint with strict rules
npm run lint:fix # Auto-fix ESLint violations
npm run format # Prettier formatting
npm run type-check # TypeScript type checking# Testing
npm run test# Run tests with Jest
npm run test:watch # Watch mode for TDD
npm run test:coverage # Run tests with coverage# Documentation
npm run docs # Generate TypeDoc documentation# Quality Assurance
npm run check-all # Run all checks

📁 Project Structure

TypeScript-Starter/
├── src/ # Source code
│ ├── types/ # Type definitions
│ │ └── index.ts # Common types: ConfigOptions, Result<T>, EventHandler, etc.
│ ├── utils/ # Utility functions
│ │ └── index.ts # Helper functions: isNotEmpty, createSuccessResult, etc.
│ └── index.ts # Main entry point - exports all public APIs
├── tests/ # Test files
│ ├── setup.ts # Jest test setup and global configurations
│ └── example.test.ts # Test suite for all functions
├── examples/ # Example usage
│ └── basic-usage.ts # Usage examples with async support
├── dist/ # Build output (ESM + type definitions)
├── docs/ # Auto-generated TypeDoc documentation
├── coverage/ # Test coverage reports (HTML + LCOV)
└── Configuration Files # Strict rules enforced
├── tsconfig.json # TypeScript configuration (all strict options enabled)
├── eslint.config.js # ESLint configuration (200+ rules)
├── jest.config.js # Jest testing configuration with TypeScript
└── package.json # Dependencies and scripts

📦 Core API Reference

Type Definitions

// Configuration options interfaceexportinterfaceConfigOptions{readonlydebug: booleanreadonlytimeout: numberreadonlyretries: number}// Result type for operations (success/error handling)exporttypeResult<T>={readonlysuccess: booleanreadonlydata?: Treadonlyerror?: string}// Event handler typeexporttypeEventHandler<T=unknown>=(event: T)=>void// Async operation typeexporttypeAsyncOperation<T>=()=>Promise<T>// Validation function typeexporttypeValidator<T>=(value: T)=>boolean

Utility Functions

// String validationexportconstisNotEmpty: (value: string)=>boolean// Result constructorsexportconstcreateSuccessResult: <T>(data: T)=>Result<T>exportconstcreateErrorResult: <T>(error: string)=>Result<T>// Async utilitiesexportconstdelay: (ms: number)=>Promise<void>

Main Exports

// Example function (demonstrates strict typing)exportconstexampleFunction: (input: string)=>string// Example class (demonstrates OOP with strict rules)exportclassExampleClass{constructor(value: string)publicgetValue(): stringpublicsetValue(newValue: string): void}

Usage Examples

import{exampleFunction,ExampleClass,isNotEmpty,createSuccessResult,createErrorResult,delay,typeConfigOptions,typeResult}from'typescript-starter'// Function usageconstresult=exampleFunction('hello world')console.log(result)// "HELLO WORLD"// Class usageconstinstance=newExampleClass('test value')console.log(instance.getValue())// "TEST VALUE"// Utility usageconsole.log(isNotEmpty('valid'))// trueconsole.log(isNotEmpty(''))// falseconstsuccess=createSuccessResult({message: 'OK'})consterror=createErrorResult<string>('Failed')// Async usageawaitdelay(1000)console.log('Delayed execution')

📊 Code Quality Metrics

Cognitive Complexity Limit: 15

// ❌ Too complex (will fail)functioncomplexFunction(input: string): string{if(condition1){if(condition2){if(condition3){if(condition4){if(condition5){return"too complex"}}}}}return"default"}// ✅ Simple and clear (passes)functionsimpleFunction(input: string): string{if(!condition1)return"default"if(!condition2)return"default"if(!condition3)return"default"return"result"}

Type Safety

// ❌ These will fail compilationfunctionbadFunction(input){// implicit anyif(condition)returnvalue// not all paths returnconstunused="never used"// unused variable}// ✅ These pass strict checkingfunctiongoodFunction(input: string): string{if(condition){returnvalue}returndefaultValue}

---

🧪 Testing (Required)

Test Structure

// tests/example.test.tsimport{exampleFunction,ExampleClass}from'@/index'describe('exampleFunction',()=>{it('should convert string to uppercase',()=>{constresult=exampleFunction('test')expect(result).toBe('TEST')})})describe('ExampleClass',()=>{letinstance: ExampleClassbeforeEach(()=>{instance=newExampleClass('initial')})it('should set and get values correctly',()=>{instance.setValue('new value')expect(instance.getValue()).toBe('NEW VALUE')})})

Coverage Requirements

• Lines: 80% minimum
• Functions: 100% for public APIs
• Branches: 80% minimum
• Statements: 80% minimum

Running Tests

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

📚 Documentation (Enforced)

JSDoc Required for Public APIs

/** * Example function demonstrating strict rules * @param input - Input string to process * @returns Processed string in uppercase */exportconstexampleFunction: (input: string)=>string=(input: string): string=>{returninput.toUpperCase()}/** * Example class with strict typing */exportclassExampleClass{privatevalue: stringconstructor(initialValue: string){this.value=initialValue.toUpperCase()}/** * Get the current value * @returns The current value in uppercase */publicgetValue(): string{returnthis.value}/** * Set a new value * @param newValue - The new value to set */publicsetValue(newValue: string): void{this.value=newValue.toUpperCase()}}

---

🔍 Path Aliases (Clean Imports)

// ❌ Relative imports (messy)import{utils}from'../../../utils/helper'// ✅ Path aliases (clean)import{utils}from'@/utils/helper'import{types}from'@types/common'import{helpers}from'@utils/helpers'

Available Path Aliases

• @/* → src/* (main source directory)
• @types/* → src/types/* (type definitions)
• @utils/* → src/utils/* (utility functions)

🛠️ Development Workflow

1. Start Coding

npm run dev # Rules are checked

2. Write Tests

npm run test:watch # TDD approach

3. Quality Check

npm run check-all # All rules checked

4. Build & Deploy

npm run build # Production build with minification
npm run docs # Generate TypeDoc documentation
npm run clean # Clean build directory

---

📄 License

MIT License - see LICENSE file for details.