# Kubrickcode Workflow Toolkit Typescript > TypeScript Coding Standards - Skill: `tomevault-io/kubrickcode-workflow-toolkit-typescript` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/kubrickcode-workflow-toolkit-typescript` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/kubrickcode-workflow-toolkit-typescript/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Productivity - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/kubrickcode-workflow-toolkit-typescript --- # TypeScript Coding Standards ## Basic Principles ### One Function, One Responsibility - If function name connects with "and" or "or", it's a signal to split - If test cases are needed for each if branch, it's a signal to split ### Conditional and Loop Depth Limited to 2 Levels - Minimize depth using early return whenever possible - If still heavy, extract into separate functions ### Make Function Side Effects Explicit - Example: If `getUser` also runs `updateLastAccess()`, specify it in the function name ### Convert Magic Numbers/Strings to Constants When Possible - Declare at the top of the file or class where used - Consider separating into a constants file if there are many ### Function Order by Call Order - Follow class access modifier declaration order rules if clear - Otherwise, order top-to-bottom for easy reading by call order ### Review External Libraries for Complex Implementations - When logic is complex and tests become bloated - If industry-standard libraries exist, use them - When security, accuracy, or performance optimization is critical - When browser/platform compatibility or edge cases are numerous ### Modularization (Prevent Code Duplication and Pattern Repetition) - Absolutely forbid code repetition - Modularize similar patterns into reusable forms - Allow pre-modularization if reuse is confirmed - Avoid excessive abstraction - Modularization levels: - Same file: Extract into separate function - Multiple files: Separate into different file - Multiple projects/domains: Separate into package ### Variable and Function Names - Clear purpose while being concise - Forbid abbreviations outside industry standards (id, api, db, err, etc.) - Don't repeat context from the parent scope - Boolean variables use `is`, `has`, `should` prefixes - Function names are verbs or verb+noun forms - Plural rules: - Pure arrays: "s" suffix (`users`) - Wrapped object: "list" suffix (`userList`) - Specific data structure: Explicit (`userSet`, `userMap`) - Already plural words: Use as-is ### Field Order - Alphabetically ascending by default - Maintain consistency in usage - Also alphabetically ordered in destructuring assignment ### Error Handling - Error handling level: Handle where meaningful response is possible - Error messages: Technical details for logs, actionable guidance for users - Error classification: Distinguish between expected and unexpected errors - Error propagation: Add context when propagating up the call stack - Recovery vs. fast fail: Recover from expected errors with fallback - Error types: For domain-specific failures, create custom error classes extending `Error`. Never throw non-Error objects - Async errors: Always handle Promise rejection. Use try-catch for async/await, .catch() for promise chains ## Package Management ### Package Manager - Use pnpm as default package manager - Forbid npm, yarn (prevent lock file conflicts) ## File Structure ### Common for All Files 1. Import statements (grouped) 2. Constant definitions (alphabetically ordered if multiple) 3. Type/Interface definitions (alphabetically ordered if multiple) 4. Main content (see below) ### Inside Classes - Decorators - private readonly members - readonly members - constructor - public methods (alphabetically ordered) - protected methods (alphabetically ordered) - private methods (alphabetically ordered) ### Function Placement in Function-Based Files - Main exported function - Additional exported functions (alphabetically ordered, avoid many) - Helper functions ## Function Writing ### Use Arrow Functions - Always use arrow functions except for class methods - Forbid function keyword entirely (exceptions: generator function\*, function hoisting etc. technically impossible cases only) ### Function Arguments: Flat vs Object - Use flat if single argument or uncertain of future additions - Use object form for 2+ arguments in most cases. Allow flat form when: - All required arguments without boolean arguments - All required arguments with clear order (e.g., (width,height), (start,end), (min,max), (from,to)) ## Type System ### Type Safety - Forbid unsafe type bypasses like any, as, !, @ts-ignore, @ts-expect-error - Exceptions: Missing or incorrect external library types, rapid development needed (clarify reason in comments) - Allow some unknown type when type guard is clear - Allow as assertion when literal type (as const) needed - Allow as assertion when widening literal/HTML types to broader types - Allow "!" assertion when type narrowing impossible after type guard due to TypeScript limitation - Allow @ts-ignore, @ts-expect-error in test code (absolutely forbid in production) ### Interface vs Type - Prioritize Type in all cases by default - Use Interface only for these exceptions: - Public API provided to external users like library public API - Need to extend existing interface like external libraries - Designing OOP-style classes where implementation contract must be clearly defined ### null/undefined Handling - Actively use Optional Chaining (`?.`) - Provide defaults with Nullish Coalescing (`??`) - Distinguish between `null` and `undefined` by semantic meaning: - `undefined`: Uninitialized state, optional parameters, value not assigned yet - `null`: Intentional absence of value (similar to Go's nil) - Examples: - Optional field: `{ name?: string }` → can be `undefined` - Intentionally cleared value: `user.profileImage = null` - External API responses may use either convention ## Code Style ### Maintain Immutability - Use `const` whenever possible, minimize `let` - Create new values instead of directly modifying arrays/objects - Use `spread`, `filter`, `map` instead of `push`, `splice` - Exceptions: Extremely performance-critical cases ## Recommended Libraries - Testing: Jest, Playwright - Utilities: es-toolkit, dayjs - HTTP: ky, @tanstack/query, @apollo/client - Form: React Hook Form - Type validation: zod - UI: Tailwind + shadcn/ui - ORM: Prisma (Drizzle if edge support important) - State management: zustand - Code formatting: prettier, eslint - Build: tsup --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/kubrickcode) — claim your Tome and manage your conversions.