
engineering-javascript-typescript
JavaScript, TypeScript, Node.js, Bun and server-side JS frameworks (NestJS, etc.)
- version
- 1.0.0
- GitHub stars
- 5
Install
/plugin install engineering-javascript-typescript@skills-stackRun it inside Claude Code after adding the marketplace with /plugin marketplace add marslanalvi/SkillsStack.
Contents
Discovered from sourceSkills 14
⚡ Bun Development
Fast, modern JavaScript/TypeScript development with the Bun runtime, inspired by oven-sh/bun.
Detailed Guide
Read the detailed guide before executing this skill. It retains the complete procedure and reference material. Treat its safety, prerequisites, and validation requirements as mandatory. For focused work, load the relevant sections; for end-to-end work, read the guide completely.
When to Use This Skill
Use this skill when:
- Starting new JS/TS projects with Bun
- Migrating from Node.js to Bun
- Optimizing development speed
- Using Bun's built-in tools (bundler, test runner)
- Troubleshooting Bun-specific issues
Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.
Bun Runtime
Bun is a fast all-in-one JavaScript runtime and toolkit: runtime, package manager, bundler, and test runner.
When to Use
- Prefer Bun for: new JS/TS projects, scripts where install/run speed matters, Vercel deployments with Bun runtime, and when you want a single toolchain (run + install + test + build).
- Prefer Node for: maximum ecosystem compatibility, legacy tooling that assumes Node, or when a dependency has known Bun issues.
Use when: adopting Bun, migrating from Node, writing or debugging Bun scripts/tests, or configuring Bun on Vercel or other platforms.
How It Works
- Version baseline: guidance below targets Bun 1.4.x. Check the actual version with
bun --versionbefore relying on flag names, since CLI flags can change between releases. - Runtime: Drop-in Node-compatible runtime, built on JavaScriptCore. As of Bun 1.4 the runtime itself is implemented in Rust (migrated from Zig). Not 100% Node-compatible — some native addons, less-common
node:internal APIs, and packages that depend on Node-specific internals can still fail; verify before depending on it in production. - Package manager: Bun includes a package manager; installation performance depends on the project, network conditions, and cache state. Lockfile is
bun.lock(text) by default in current Bun; older versions usedbun.lockb(binary) — Bun still reads that format for migration, but new projects should usebun.lock. - Bundler: Built-in bundler and transpiler for apps and libraries.
- Test runner: Built-in
bun testwith a Jest-like API.
Migration from Node: Replace node script.js with bun run script.js or bun script.js. Run bun install in place of npm install; most packages work. Use bun run for npm scripts; bun x for npx-style one-off runs. Node built-ins are supported; prefer Bun APIs where they exist for better performance.
Package and workspace commands: bun add <pkg> / bun remove <pkg> / bun update [pkg] manage dependencies; bun outdated lists stale deps. bun pm ls lists project dependencies and resolved versions using the lockfile; --all includes transitive dependencies. It is not an integrity check of installed file contents. bun audit queries registry advisories using package names and versions from bun.lock; it does not modify package.json, bun.lock, or node_modules. Review approved destinations before sending private package metadata. Packages whose scoped registry lacks an advisory endpoint are skipped and do not affect the exit code. bun audit fix upgrades and installs dependencies, changing the lockfile and installed packages and sometimes direct version pins; review it as a modifying install operation, including applicable lifecycle scripts. bun dedupe collapses duplicate installs, and bun prune removes packages no longer referenced. Monorepos use a root workspaces array in package.json (same convention as npm/yarn); run a script in one workspace with bun run --filter <pkg-name> <script>.
Built-in APIs: reach for these before adding a dependency — Bun.file / Bun.write for file I/O, bun:sqlite for an embedded SQLite database, Bun.serve for an HTTP/WebSocket server, Bun.sql for SQL databases, Bun.redis for Redis, and Bun.S3Client for S3-compatible object storage. See the 1.4 release notes for the rest of what's new.
Vercel: Set bunVersion: "1.4.x" in vercel.json to use Bun 1.4 (Rust runtime). See Vercel's Bun runtime docs. Build: bun run build or bun build ./src/index.ts --outdir=dist. Install: bun install --frozen-lockfile for reproducible deploys.
Reference: Bun 1.4 release notes.
Examples
Run and install
# Install dependencies (creates/updates bun.lock)
bun install
# Run a script or file
bun run dev
bun run src/index.ts
bun src/index.ts
Scripts and env
bun run --env-file=.env dev
FOO=bar bun run script.ts
Testing
bun test
bun test --watch
For CI on Bun 1.4, available options include bun test --changed[=<ref>] for affected tests, bun test --isolate for per-file globals, bun test --parallel[=<n>] for worker processes, and bun test --shard=<n>/<count> for CI partitioning. --isolate creates a fresh JavaScript global for each file in the same process and cleans up documented per-file resources; it is not a process or security sandbox. --parallel enables it by default. --timings=<file> reads prior durations for scheduling; --update-timings records durations. Example: bun test --parallel --timings=./test-timings.json --update-timings. Check the installed version's help and documentation before choosing timing-file paths for a multi-shard workflow.
// test/example.test.ts
import { expect, test } from "bun:test";
test("add", () => {
expect(1 + 2).toBe(3);
});
Runtime API
const file = Bun.file("package.json");
const json = await file.json();
Bun.serve({
port: 3000,
fetch(req) {
return new Response("Hello");
},
});
Best Practices
- Commit the lockfile (
bun.lock) for reproducible installs. - Prefer
bun runfor scripts. For TypeScript, Bun runs.tsnatively. - Keep dependencies up to date; Bun and the ecosystem evolve quickly.
DBOS TypeScript Best Practices
Guide for building reliable, fault-tolerant TypeScript applications with DBOS durable workflows.
When to Use
Reference these guidelines when:
- Adding DBOS to existing TypeScript code
- Creating workflows and steps
- Using queues for concurrency control
- Implementing workflow communication (events, messages, streams)
- Configuring and launching DBOS applications
- Using DBOSClient from external applications
- Testing DBOS applications
Rule Categories by Priority
| Priority | Category | Impact | Prefix |
|---|---|---|---|
| 1 | Lifecycle | CRITICAL | lifecycle- |
| 2 | Workflow | CRITICAL | workflow- |
| 3 | Step | HIGH | step- |
| 4 | Queue | HIGH | queue- |
| 5 | Communication | MEDIUM | comm- |
| 6 | Pattern | MEDIUM | pattern- |
| 7 | Testing | LOW-MEDIUM | test- |
| 8 | Client | MEDIUM | client- |
| 9 | Advanced | LOW | advanced- |
Critical Rules
Installation
Install a supported SDK version compatible with the existing application and pin it in the lockfile. For a new project, first verify the current official release:
npm install @dbos-inc/dbos-sdk@<verified-version>
DBOS Configuration and Launch
A DBOS application MUST configure and launch DBOS before running any workflows:
import { DBOS } from "@dbos-inc/dbos-sdk";
async function main() {
DBOS.setConfig({
name: "my-app",
systemDatabaseUrl: process.env.DBOS_SYSTEM_DATABASE_URL,
});
await DBOS.launch();
await myWorkflow();
}
main().catch(error => { console.error(error); process.exitCode = 1; });
Workflow and Step Structure
Workflows are comprised of steps. Any function performing complex operations or accessing external services must be run as a step using DBOS.runStep:
import { DBOS } from "@dbos-inc/dbos-sdk";
async function fetchData() {
return await fetch("https://api.example.com").then(r => r.json());
}
async function myWorkflowFn() {
const result = await DBOS.runStep(fetchData, { name: "fetchData" });
return result;
}
const myWorkflow = DBOS.registerWorkflow(myWorkflowFn);
Key Constraints
- Do NOT call, start, or enqueue workflows from within steps
- Do NOT use threads or uncontrolled concurrency to start workflows - use
DBOS.startWorkflowor queues - Workflows MUST be deterministic - non-deterministic operations go in steps
- Do NOT modify global variables from workflows or steps
How to Use
Read individual rule files for detailed explanations and examples:
references/lifecycle-config.md
references/workflow-determinism.md
references/queue-concurrency.md
References
Limitations
- Examples are version-specific sketches; verify signatures and migration guidance against the installed SDK. Register workflows/steps before launch. Keep database credentials private.
- Step replay/retries can repeat external effects. Use stable provider-side idempotency keys and application transactions; a workflow ID alone does not guarantee a card is charged only once.
- Database reset, cancellation, resume and fork examples require an explicit target and authorization; they may destroy data, bypass queue limits or repeat effects.
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.
TaskEither Quick Reference
TaskEither = async operation that can fail. Its shape is () => Promise<Either<E, A>>: construction is lazy.
When to Use
- You need a quick fp-ts reference for async operations that can fail.
- The task involves API calls, Promise wrapping, or composing asynchronous error-handling pipelines.
- You want a concise cheat sheet for
TaskEitheroperators and patterns.
Create
import * as TE from 'fp-ts/TaskEither'
import * as T from 'fp-ts/Task'
TE.right(value) // Async success
TE.left(error) // Async failure
TE.tryCatch(asyncFn, toError) // Promise → TaskEither
TE.fromEither(either) // Either → TaskEither
Transform
TE.map(fn) // Transform success value
TE.mapLeft(fn) // Transform error
TE.flatMap(fn) // Chain (fn returns TaskEither)
TE.orElse(fn) // Recover from error
Execute
// TaskEither is lazy - must call () to run
const result = await myTaskEither() // Either<E, A>
// Or pattern match
await pipe(
myTaskEither,
TE.match(
(err) => console.error(err),
(val) => console.log(val)
)
)()
Common Patterns
import { pipe } from 'fp-ts/function'
import * as TE from 'fp-ts/TaskEither'
import * as T from 'fp-ts/Task'
// Wrap fetch
const fetchUser = (id: string, signal: AbortSignal) => TE.tryCatch(
async () => {
const response = await fetch(`/api/users/${encodeURIComponent(id)}`, { signal })
if (!response.ok) throw new Error(`HTTP ${response.status}`)
const body: unknown = await response.json()
return validateUser(body) // Application schema validator; throws on invalid data
},
(e) => ({ type: 'NETWORK_ERROR', message: String(e) })
)
// Chain async calls
pipe(
fetchUser('123', signal),
TE.flatMap(user => fetchPosts(user.id)),
TE.map(posts => posts.length)
)
// Parallel calls
import { sequenceT } from 'fp-ts/Apply'
sequenceT(TE.ApplyPar)(
fetchUser('1', signal),
fetchPosts('1'),
fetchComments('1')
)
// With recovery
pipe(
fetchUser('123', signal),
TE.orElse(() => TE.right(defaultUser)),
TE.getOrElse(() => T.of(defaultUser))
)
vs async/await
// ❌ async/await - errors hidden
async function getUser(id: string) {
try {
const res = await fetch(`/api/users/${id}`)
return await res.json()
} catch (e) {
return null // Error info lost
}
}
// ✅ TaskEither - errors typed and composable
const getUser = (id: string, signal: AbortSignal) => pipe(
TE.tryCatch(() => fetch(`/api/users/${encodeURIComponent(id)}`, { signal }), toNetworkError),
TE.flatMap(res => TE.tryCatch(async () => {
if (!res.ok) throw new Error(`HTTP ${res.status}`)
return validateUser(await res.json())
}, toParseError))
)
Use TaskEither when you need typed errors for async operations.
Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.
Reference scope
These are fp-ts 2.x fragments. Supply application variables, types, validators and imports, and check the installed version. map does not catch thrown exceptions. Task has no typed error channel; an improperly wrapped promise can still reject. Use tryCatch at fallible boundaries.
Supply a caller-owned timeout/abort signal and validate response schemas. Parallel application calls need bounded concurrency and authorization for their data, costs and effects; ApplyPar does not cancel work automatically on failure. Error callbacks must redact secrets and private payloads.
Official API: fp-ts modules.
JavaScript Testing Patterns
Comprehensive guide for implementing robust testing strategies in JavaScript/TypeScript applications using modern testing frameworks and best practices.
When to Use This Skill
- Setting up test infrastructure for new projects
- Writing unit tests for functions and classes
- Creating integration tests for APIs and services
- Implementing end-to-end tests for user flows
- Mocking external dependencies and APIs
- Testing React, Vue, or other frontend components
- Implementing test-driven development (TDD)
- Setting up continuous testing in CI/CD pipelines
Testing Frameworks
Jest - Full-Featured Testing Framework
Setup:
// jest.config.ts
import type { Config } from "jest";
const config: Config = {
preset: "ts-jest",
testEnvironment: "node",
roots: ["<rootDir>/src"],
testMatch: ["**/__tests__/**/*.ts", "**/?(*.)+(spec|test).ts"],
collectCoverageFrom: [
"src/**/*.ts",
"!src/**/*.d.ts",
"!src/**/*.interface.ts",
],
coverageThreshold: {
global: {
branches: 80,
functions: 80,
lines: 80,
statements: 80,
},
},
setupFilesAfterEnv: ["<rootDir>/src/test/setup.ts"],
};
export default config;
Vitest - Fast, Vite-Native Testing
Setup:
// vitest.config.ts
import { defineConfig } from "vitest/config";
export default defineConfig({
test: {
globals: true,
environment: "node",
coverage: {
provider: "v8",
reporter: ["text", "json", "html"],
exclude: ["**/*.d.ts", "**/*.config.ts", "**/dist/**"],
},
setupFiles: ["./src/test/setup.ts"],
},
});
Unit Testing Patterns
Pattern 1: Testing Pure Functions
// utils/calculator.ts
export function add(a: number, b: number): number {
return a + b;
}
export function divide(a: number, b: number): number {
if (b === 0) {
throw new Error("Division by zero");
}
return a / b;
}
// utils/calculator.test.ts
import { describe, it, expect } from "vitest";
import { add, divide } from "./calculator";
describe("Calculator", () => {
describe("add", () => {
it("should add two positive numbers", () => {
expect(add(2, 3)).toBe(5);
});
it("should add negative numbers", () => {
expect(add(-2, -3)).toBe(-5);
});
it("should handle zero", () => {
expect(add(0, 5)).toBe(5);
expect(add(5, 0)).toBe(5);
});
});
describe("divide", () => {
it("should divide two numbers", () => {
expect(divide(10, 2)).toBe(5);
});
it("should handle decimal results", () => {
expect(divide(5, 2)).toBe(2.5);
});
it("should throw error when dividing by zero", () => {
expect(() => divide(10, 0)).toThrow("Division by zero");
});
});
});
Pattern 2: Testing Classes
// services/user.service.ts
export class UserService {
private users: Map<string, User> = new Map();
create(user: User): User {
if (this.users.has(user.id)) {
throw new Error("User already exists");
}
this.users.set(user.id, user);
return user;
}
findById(id: string): User | undefined {
return this.users.get(id);
}
update(id: string, updates: Partial<User>): User {
const user = this.users.get(id);
if (!user) {
throw new Error("User not found");
}
const updated = { ...user, ...updates };
this.users.set(id, updated);
return updated;
}
delete(id: string): boolean {
return this.users.delete(id);
}
}
// services/user.service.test.ts
import { describe, it, expect, beforeEach } from "vitest";
import { UserService } from "./user.service";
describe("UserService", () => {
let service: UserService;
beforeEach(() => {
service = new UserService();
});
describe("create", () => {
it("should create a new user", () => {
const user = { id: "1", name: "John", email: "john@example.com" };
const created = service.create(user);
expect(created).toEqual(user);
expect(service.findById("1")).toEqual(user);
});
it("should throw error if user already exists", () => {
const user = { id: "1", name: "John", email: "john@example.com" };
service.create(user);
expect(() => service.create(user)).toThrow("User already exists");
});
});
describe("update", () => {
it("should update existing user", () => {
const user = { id: "1", name: "John", email: "john@example.com" };
service.create(user);
const updated = service.update("1", { name: "Jane" });
expect(updated.name).toBe("Jane");
expect(updated.email).toBe("john@example.com");
});
it("should throw error if user not found", () => {
expect(() => service.update("999", { name: "Jane" })).toThrow(
"User not found",
);
});
});
});
Pattern 3: Testing Async Functions
// services/api.service.ts
export class ApiService {
async fetchUser(id: string): Promise<User> {
const response = await fetch(`https://api.example.com/users/${id}`);
if (!response.ok) {
throw new Error("User not found");
}
return response.json();
}
async createUser(user: CreateUserDTO): Promise<User> {
const response = await fetch("https://api.example.com/users", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(user),
});
return response.json();
}
}
// services/api.service.test.ts
import { describe, it, expect, vi, beforeEach } from "vitest";
import { ApiService } from "./api.service";
// Mock fetch globally
global.fetch = vi.fn();
describe("ApiService", () => {
let service: ApiService;
beforeEach(() => {
service = new ApiService();
vi.clearAllMocks();
});
describe("fetchUser", () => {
it("should fetch user successfully", async () => {
const mockUser = { id: "1", name: "John", email: "john@example.com" };
(fetch as any).mockResolvedValueOnce({
ok: true,
json: async () => mockUser,
});
const user = await service.fetchUser("1");
expect(user).toEqual(mockUser);
expect(fetch).toHaveBeenCalledWith("https://api.example.com/users/1");
});
it("should throw error if user not found", async () => {
(fetch as any).mockResolvedValueOnce({
ok: false,
});
await expect(service.fetchUser("999")).rejects.toThrow("User not found");
});
});
describe("createUser", () => {
it("should create user successfully", async () => {
const newUser = { name: "John", email: "john@example.com" };
const createdUser = { id: "1", ...newUser };
(fetch as any).mockResolvedValueOnce({
ok: true,
json: async () => createdUser,
});
const user = await service.createUser(newUser);
expect(user).toEqual(createdUser);
expect(fetch).toHaveBeenCalledWith(
"https://api.example.com/users",
expect.objectContaining({
method: "POST",
body: JSON.stringify(newUser),
}),
);
});
});
});
Mocking Patterns
Pattern 1: Mocking Modules
// services/email.service.ts
import nodemailer from "nodemailer";
export class EmailService {
private transporter = nodemailer.createTransport({
host: process.env.SMTP_HOST,
port: 587,
auth: {
user: process.env.SMTP_USER,
pass: process.env.SMTP_PASS,
},
});
async sendEmail(to: string, subject: string, html: string) {
await this.transporter.sendMail({
from: process.env.EMAIL_FROM,
to,
subject,
html,
});
}
}
// services/email.service.test.ts
import { describe, it, expect, vi, beforeEach } from "vitest";
import { EmailService } from "./email.service";
vi.mock("nodemailer", () => ({
default: {
createTransport: vi.fn(() => ({
sendMail: vi.fn().mockResolvedValue({ messageId: "123" }),
})),
},
}));
describe("EmailService", () => {
let service: EmailService;
beforeEach(() => {
service = new EmailService();
});
it("should send email successfully", async () => {
await service.sendEmail(
"test@example.com",
"Test Subject",
"<p>Test Body</p>",
);
expect(service["transporter"].sendMail).toHaveBeenCalledWith(
expect.objectContaining({
to: "test@example.com",
subject: "Test Subject",
}),
);
});
});
Pattern 2: Dependency Injection for Testing
// services/user.service.ts
export interface IUserRepository {
findById(id: string): Promise<User | null>;
create(user: User): Promise<User>;
}
export class UserService {
constructor(private userRepository: IUserRepository) {}
async getUser(id: string): Promise<User> {
const user = await this.userRepository.findById(id);
if (!user) {
throw new Error("User not found");
}
return user;
}
async createUser(userData: CreateUserDTO): Promise<User> {
// Business logic here
const user = { id: generateId(), ...userData };
return this.userRepository.create(user);
}
}
// services/user.service.test.ts
import { describe, it, expect, vi, beforeEach } from "vitest";
import { UserService, IUserRepository } from "./user.service";
describe("UserService", () => {
let service: UserService;
let mockRepository: IUserRepository;
beforeEach(() => {
mockRepository = {
findById: vi.fn(),
create: vi.fn(),
};
service = new UserService(mockRepository);
});
describe("getUser", () => {
it("should return user if found", async () => {
const mockUser = { id: "1", name: "John", email: "john@example.com" };
vi.mocked(mockRepository.findById).mockResolvedValue(mockUser);
const user = await service.getUser("1");
expect(user).toEqual(mockUser);
expect(mockRepository.findById).toHaveBeenCalledWith("1");
});
it("should throw error if user not found", async () => {
vi.mocked(mockRepository.findById).mockResolvedValue(null);
await expect(service.getUser("999")).rejects.toThrow("User not found");
});
});
describe("createUser", () => {
it("should create user successfully", async () => {
const userData = { name: "John", email: "john@example.com" };
const createdUser = { id: "1", ...userData };
vi.mocked(mockRepository.create).mockResolvedValue(createdUser);
const user = await service.createUser(userData);
expect(user).toEqual(createdUser);
expect(mockRepository.create).toHaveBeenCalled();
});
});
});
Pattern 3: Spying on Functions
// utils/logger.ts
export const logger = {
info: (message: string) => console.log(`INFO: ${message}`),
error: (message: string) => console.error(`ERROR: ${message}`),
};
// services/order.service.ts
import { logger } from "../utils/logger";
export class OrderService {
async processOrder(orderId: string): Promise<void> {
logger.info(`Processing order ${orderId}`);
// Process order logic
logger.info(`Order ${orderId} processed successfully`);
}
}
// services/order.service.test.ts
import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
import { OrderService } from "./order.service";
import { logger } from "../utils/logger";
describe("OrderService", () => {
let service: OrderService;
let loggerSpy: any;
beforeEach(() => {
service = new OrderService();
loggerSpy = vi.spyOn(logger, "info");
});
afterEach(() => {
loggerSpy.mockRestore();
});
it("should log order processing", async () => {
await service.processOrder("123");
expect(loggerSpy).toHaveBeenCalledWith("Processing order 123");
expect(loggerSpy).toHaveBeenCalledWith("Order 123 processed successfully");
expect(loggerSpy).toHaveBeenCalledTimes(2);
});
});
Integration Testing
Integration tests verify real database operations and HTTP endpoints using supertest and a test database instance. Always truncate tables in beforeEach and tear down in afterAll.
For full API integration test examples (supertest + PostgreSQL) and database repository integration tests, see references/advanced-testing-patterns.md.
Frontend Testing with Testing Library
Test React components by rendering them and querying by role, placeholder, or test ID. Test hooks with renderHook + act. Prefer semantic queries (getByRole, getByPlaceholderText) over data-testid.
For complete React component test examples (UserForm, hooks with renderHook/act), see references/advanced-testing-patterns.md.
Test Fixtures and Factories
Use @faker-js/faker to generate realistic test data factories. Factories accept optional overrides so tests can set only the fields they care about:
// tests/fixtures/user.fixture.ts
import { faker } from "@faker-js/faker";
export function createUserFixture(overrides?: Partial<User>): User {
return {
id: faker.string.uuid(),
name: faker.person.fullName(),
email: faker.internet.email(),
createdAt: faker.date.past(),
...overrides,
};
}
For snapshot testing, coverage configuration, test organization patterns, promise testing, and timer mocking, see references/advanced-testing-patterns.md.
Best Practices
- Follow AAA Pattern: Arrange, Act, Assert
- One assertion per test: Or logically related assertions
- Descriptive test names: Should describe what is being tested
- Use beforeEach/afterEach: For setup and teardown
- Mock external dependencies: Keep tests isolated
- Test edge cases: Not just happy paths
- Avoid implementation details: Test behavior, not implementation
- Use test factories: For consistent test data
- Keep tests fast: Mock slow operations
- Write tests first (TDD): When possible
- Maintain test coverage: Aim for 80%+ coverage
- Use TypeScript: For type-safe tests
- Test error handling: Not just success cases
- Use data-testid sparingly: Prefer semantic queries
- Clean up after tests: Prevent test pollution
MCP Server Patterns
The Model Context Protocol (MCP) lets AI assistants call tools, read resources, and use prompts from your server. Use this skill when building or maintaining MCP servers. The SDK API evolves; check Context7 (query-docs for "MCP") or the official MCP documentation for current method names and signatures.
For the broader routing decision of when a capability should be a rule, a skill, MCP, or a plain CLI/API workflow, see docs/capability-surface-selection.md.
When to Use
Use when: implementing a new MCP server, adding tools or resources, choosing stdio vs HTTP, upgrading the SDK, or debugging MCP registration and transport issues.
How It Works
Core concepts
- Tools: Actions the model can invoke (e.g. search, run a command). Register with
registerTool()ortool()depending on SDK version. - Resources: Read-only data the model can fetch (e.g. file contents, API responses). Register with
registerResource()orresource(). Handlers typically receive auriargument. - Prompts: Reusable, parameterised prompt templates the client can surface (e.g. in Claude Desktop). Register with
registerPrompt()or equivalent. - Transport: stdio for local clients (e.g. Claude Desktop); Streamable HTTP is preferred for remote (Cursor, cloud). Legacy HTTP/SSE is for backward compatibility.
The Node/TypeScript SDK may expose tool() / resource() or registerTool() / registerResource(); the official SDK has changed over time. Always verify against the current MCP docs or Context7.
Connecting with stdio
For local clients, create a stdio transport and pass it to your server’s connect method. The exact API varies by SDK version (e.g. constructor vs factory). See the official MCP documentation or query Context7 for "MCP stdio server" for the current pattern.
Keep server logic (tools + resources) independent of transport so you can plug in stdio or HTTP in the entrypoint.
Remote (Streamable HTTP)
For Cursor, cloud, or other remote clients, use Streamable HTTP (single MCP HTTP endpoint per current spec). Support legacy HTTP/SSE only when backward compatibility is required.
Examples
Install and server setup
npm install @modelcontextprotocol/sdk zod
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";
const server = new McpServer({ name: "my-server", version: "1.0.0" });
Register tools and resources using the API your SDK version provides: some versions use server.tool(name, description, schema, handler) (positional args), others use server.tool({ name, description, inputSchema }, handler) or registerTool(). Same for resources — include a uri in the handler when the API provides it. Check the official MCP docs or Context7 for the current @modelcontextprotocol/sdk signatures to avoid copy-paste errors.
Use Zod (or the SDK’s preferred schema format) for input validation.
Best Practices
- Schema first: Define input schemas for every tool; document parameters and return shape.
- Errors: Return structured errors or messages the model can interpret; avoid raw stack traces.
- Idempotency: Prefer idempotent tools where possible so retries are safe.
- Rate and cost: For tools that call external APIs, consider rate limits and cost; document in the tool description.
- Versioning: Pin SDK version in package.json; check release notes when upgrading.
Official SDKs and Docs
- JavaScript/TypeScript:
@modelcontextprotocol/sdk(npm). Use Context7 with library name "MCP" for current registration and transport patterns. - Go: Official Go SDK on GitHub (
modelcontextprotocol/go-sdk). - C#: Official C# SDK for .NET.
Migrate to Shoehorn
Why shoehorn?
shoehorn lets you pass partial data in tests while keeping TypeScript happy. It replaces as assertions with type-safe alternatives.
Test code only. Never use shoehorn in production code.
Problems with as in tests:
- Trained not to use it
- Must manually specify target type
- Double-as (
as unknown as Type) for intentionally wrong data
Install
npm i @total-typescript/shoehorn
Migration patterns
Large objects with few needed properties
Before:
type Request = {
body: { id: string };
headers: Record<string, string>;
cookies: Record<string, string>;
// ...20 more properties
};
it("gets user by id", () => {
// Only care about body.id but must fake entire Request
getUser({
body: { id: "123" },
headers: {},
cookies: {},
// ...fake all 20 properties
});
});
After:
import { fromPartial } from "@total-typescript/shoehorn";
it("gets user by id", () => {
getUser(
fromPartial({
body: { id: "123" },
}),
);
});
as Type → fromPartial()
Before:
getUser({ body: { id: "123" } } as Request);
After:
import { fromPartial } from "@total-typescript/shoehorn";
getUser(fromPartial({ body: { id: "123" } }));
as unknown as Type → fromAny()
Before:
getUser({ body: { id: 123 } } as unknown as Request); // wrong type on purpose
After:
import { fromAny } from "@total-typescript/shoehorn";
getUser(fromAny({ body: { id: 123 } }));
When to use each
| Function | Use case |
|---|---|
fromPartial() | Pass partial data that still type-checks |
fromAny() | Pass intentionally wrong data (keeps autocomplete) |
fromExact() | Force full object (swap with fromPartial later) |
Workflow
-
Gather requirements - ask user:
- What test files have
asassertions causing problems? - Are they dealing with large objects where only some properties matter?
- Do they need to pass intentionally wrong data for error testing?
- What test files have
-
Install and migrate:
- Install:
npm i @total-typescript/shoehorn - Find test files with
asassertions:grep -r " as [A-Z]" --include="*.test.ts" --include="*.spec.ts" - Replace
as TypewithfromPartial() - Replace
as unknown as TypewithfromAny() - Add imports from
@total-typescript/shoehorn - Run type check to verify
- Install:
Modern JavaScript Patterns
Comprehensive guide for mastering modern JavaScript (ES6+) features, functional programming patterns, and best practices for writing clean, maintainable, and performant code.
When to Use This Skill
- Refactoring legacy JavaScript to modern syntax
- Implementing functional programming patterns
- Optimizing JavaScript performance
- Writing maintainable and readable code
- Working with asynchronous operations
- Building modern web applications
- Migrating from callbacks to Promises/async-await
- Implementing data transformation pipelines
Detailed patterns and worked examples
Detailed pattern documentation lives in references/details.md. Read that file when the navigation tier above is insufficient.
Best Practices
- Use const by default: Only use let when reassignment is needed
- Prefer arrow functions: Especially for callbacks
- Use template literals: Instead of string concatenation
- Destructure objects and arrays: For cleaner code
- Use async/await: Instead of Promise chains
- Avoid mutating data: Use spread operator and array methods
- Use optional chaining: Prevent "Cannot read property of undefined"
- Use nullish coalescing: For default values
- Prefer array methods: Over traditional loops
- Use modules: For better code organization
- Write pure functions: Easier to test and reason about
- Use meaningful variable names: Self-documenting code
- Keep functions small: Single responsibility principle
- Handle errors properly: Use try/catch with async/await
- Use strict mode:
'use strict'for better error catching
For common pitfalls (this binding, promise anti-patterns, memory leaks), see references/advanced-patterns.md.
NestJS Development Patterns
Production-grade NestJS patterns for modular TypeScript backends.
When to Activate
- Building NestJS APIs or services
- Structuring modules, controllers, and providers
- Adding DTO validation, guards, interceptors, or exception filters
- Configuring environment-aware settings and database integrations
- Testing NestJS units or HTTP endpoints
Project Structure
src/
├── app.module.ts
├── main.ts
├── common/
│ ├── filters/
│ ├── guards/
│ ├── interceptors/
│ └── pipes/
├── config/
│ ├── configuration.ts
│ └── validation.ts
├── modules/
│ ├── auth/
│ │ ├── auth.controller.ts
│ │ ├── auth.module.ts
│ │ ├── auth.service.ts
│ │ ├── dto/
│ │ ├── guards/
│ │ └── strategies/
│ └── users/
│ ├── dto/
│ ├── entities/
│ ├── users.controller.ts
│ ├── users.module.ts
│ └── users.service.ts
└── prisma/ or database/
- Keep domain code inside feature modules.
- Put cross-cutting filters, decorators, guards, and interceptors in
common/. - Keep DTOs close to the module that owns them.
Bootstrap and Global Validation
async function bootstrap() {
const app = await NestFactory.create(AppModule, { bufferLogs: true });
app.useGlobalPipes(
new ValidationPipe({
whitelist: true,
forbidNonWhitelisted: true,
transform: true,
transformOptions: { enableImplicitConversion: true },
}),
);
app.useGlobalInterceptors(new ClassSerializerInterceptor(app.get(Reflector)));
app.useGlobalFilters(new HttpExceptionFilter());
await app.listen(process.env.PORT ?? 3000);
}
bootstrap();
- Always enable
whitelistandforbidNonWhitelistedon public APIs. - Prefer one global validation pipe instead of repeating validation config per route.
Modules, Controllers, and Providers
@Module({
controllers: [UsersController],
providers: [UsersService],
exports: [UsersService],
})
export class UsersModule {}
@Controller('users')
export class UsersController {
constructor(private readonly usersService: UsersService) {}
@Get(':id')
getById(@Param('id', ParseUUIDPipe) id: string) {
return this.usersService.getById(id);
}
@Post()
create(@Body() dto: CreateUserDto) {
return this.usersService.create(dto);
}
}
@Injectable()
export class UsersService {
constructor(private readonly usersRepo: UsersRepository) {}
async create(dto: CreateUserDto) {
return this.usersRepo.create(dto);
}
}
- Controllers should stay thin: parse HTTP input, call a provider, return response DTOs.
- Put business logic in injectable services, not controllers.
- Export only the providers other modules genuinely need.
DTOs and Validation
export class CreateUserDto {
@IsEmail()
email!: string;
@IsString()
@Length(2, 80)
name!: string;
@IsOptional()
@IsEnum(UserRole)
role?: UserRole;
}
- Validate every request DTO with
class-validator. - Use dedicated response DTOs or serializers instead of returning ORM entities directly.
- Avoid leaking internal fields such as password hashes, tokens, or audit columns.
Auth, Guards, and Request Context
@UseGuards(JwtAuthGuard, RolesGuard)
@Roles('admin')
@Get('admin/report')
getAdminReport(@Req() req: AuthenticatedRequest) {
return this.reportService.getForUser(req.user.id);
}
- Keep auth strategies and guards module-local unless they are truly shared.
- Encode coarse access rules in guards, then do resource-specific authorization in services.
- Prefer explicit request types for authenticated request objects.
Exception Filters and Error Shape
@Catch()
export class HttpExceptionFilter implements ExceptionFilter {
catch(exception: unknown, host: ArgumentsHost) {
const response = host.switchToHttp().getResponse<Response>();
const request = host.switchToHttp().getRequest<Request>();
if (exception instanceof HttpException) {
return response.status(exception.getStatus()).json({
path: request.url,
error: exception.getResponse(),
});
}
return response.status(500).json({
path: request.url,
error: 'Internal server error',
});
}
}
- Keep one consistent error envelope across the API.
- Throw framework exceptions for expected client errors; log and wrap unexpected failures centrally.
Config and Environment Validation
ConfigModule.forRoot({
isGlobal: true,
load: [configuration],
validate: validateEnv,
});
- Validate env at boot, not lazily at first request.
- Keep config access behind typed helpers or config services.
- Split dev/staging/prod concerns in config factories instead of branching throughout feature code.
Persistence and Transactions
- Keep repository / ORM code behind providers that speak domain language.
- For Prisma or TypeORM, isolate transactional workflows in services that own the unit of work.
- Do not let controllers coordinate multi-step writes directly.
Testing
describe('UsersController', () => {
let app: INestApplication;
beforeAll(async () => {
const moduleRef = await Test.createTestingModule({
imports: [UsersModule],
}).compile();
app = moduleRef.createNestApplication();
app.useGlobalPipes(new ValidationPipe({ whitelist: true, transform: true }));
await app.init();
});
});
- Unit test providers in isolation with mocked dependencies.
- Add request-level tests for guards, validation pipes, and exception filters.
- Reuse the same global pipes/filters in tests that you use in production.
Production Defaults
- Enable structured logging and request correlation ids.
- Terminate on invalid env/config instead of booting partially.
- Prefer async provider initialization for DB/cache clients with explicit health checks.
- Keep background jobs and event consumers in their own modules, not inside HTTP controllers.
- Make rate limiting, auth, and audit logging explicit for public endpoints.
Node.js Backend Patterns
Comprehensive guidance for building scalable, maintainable, and production-ready Node.js backend applications with modern frameworks, architectural patterns, and best practices.
When to Use This Skill
- Building REST APIs or GraphQL servers
- Creating microservices with Node.js
- Implementing authentication and authorization
- Designing scalable backend architectures
- Setting up middleware and error handling
- Integrating databases (SQL and NoSQL)
- Building real-time applications with WebSockets
- Implementing background job processing
Detailed patterns and worked examples
Detailed pattern documentation lives in references/details.md. Read that file when the navigation tier above is insufficient.
Best Practices
- Use TypeScript: Type safety prevents runtime errors
- Implement proper error handling: Use custom error classes
- Validate input: Use libraries like Zod or Joi
- Use environment variables: Never hardcode secrets
- Implement logging: Use structured logging (Pino, Winston)
- Add rate limiting: Prevent abuse
- Use HTTPS: Always in production
- Implement CORS properly: Don't use
*in production - Use dependency injection: Easier testing and maintenance
- Write tests: Unit, integration, and E2E tests
- Handle graceful shutdown: Clean up resources
- Use connection pooling: For databases
- Implement health checks: For monitoring
- Use compression: Reduce response size
- Monitor performance: Use APM tools
Testing Patterns
See javascript-testing-patterns skill for comprehensive testing guidance.
Node.js Keccak-256
Ethereum uses Keccak-256, not the NIST-standardized SHA3 variant exposed by Node's crypto.createHash('sha3-256').
When to Use
- Computing Ethereum function selectors or event topics
- Building EIP-712, signature, Merkle, or storage-slot helpers in JS/TS
- Reviewing any code that hashes Ethereum data with Node crypto directly
How It Works
The two algorithms produce different outputs for the same input, and Node will not warn you.
import crypto from 'crypto';
import { keccak256, toUtf8Bytes } from 'ethers';
const data = 'hello';
const nistSha3 = crypto.createHash('sha3-256').update(data).digest('hex');
const keccak = keccak256(toUtf8Bytes(data)).slice(2);
console.log(nistSha3 === keccak); // false
Examples
ethers v6
import { keccak256, toUtf8Bytes, solidityPackedKeccak256, id } from 'ethers';
const hash = keccak256(new Uint8Array([0x01, 0x02]));
const hash2 = keccak256(toUtf8Bytes('hello'));
const topic = id('Transfer(address,address,uint256)');
const packed = solidityPackedKeccak256(
['address', 'uint256'],
['0x742d35Cc6634C0532925a3b8D4C9B569890FaC1c', 100n],
);
viem
import { keccak256, toBytes } from 'viem';
const hash = keccak256(toBytes('hello'));
web3.js
const hash = web3.utils.keccak256('hello');
const packed = web3.utils.soliditySha3(
{ type: 'address', value: '0x742d35Cc6634C0532925a3b8D4C9B569890FaC1c' },
{ type: 'uint256', value: '100' },
);
Common patterns
import { id, keccak256, AbiCoder } from 'ethers';
const selector = id('transfer(address,uint256)').slice(0, 10);
const typeHash = keccak256(toUtf8Bytes('Transfer(address from,address to,uint256 value)'));
function getMappingSlot(key: string, mappingSlot: number): string {
return keccak256(
AbiCoder.defaultAbiCoder().encode(['address', 'uint256'], [key, mappingSlot]),
);
}
Address from public key
import { keccak256 } from 'ethers';
function pubkeyToAddress(pubkeyBytes: Uint8Array): string {
const hash = keccak256(pubkeyBytes.slice(1));
return '0x' + hash.slice(-40);
}
Audit your codebase
grep -rn "createHash.*sha3" --include="*.ts" --include="*.js" --exclude-dir=node_modules .
grep -rn "keccak256" --include="*.ts" --include="*.js" . | grep -v node_modules
Rule
For Ethereum contexts, never use crypto.createHash('sha3-256'). Use Keccak-aware helpers from ethers, viem, web3, or another explicit Keccak implementation.
Setup TS Deep Modules
Make every package in this repo a deep module: a lot of behaviour behind a small interface. A package's public surface is its entry points (the files at the package root), and everything in its subfolders is hidden. This skill installs dependency-cruiser and the rules that make the entry points the only way in, then proves the rules bite.
For the vocabulary (deep module, interface, seam, depth), call the Skill tool with "codebase-design" and use its language throughout.
The shape this enforces
src/packages/
<name>/
index.ts ← an entry point (public). Import this from outside.
client.ts ← another entry point. Packages may expose SEVERAL.
lib/ ← implementation: hidden from outside, free to import each other.
tests/ ← co-located tests + fixtures (a subfolder, so private).
The public surface is the package's root files, not one designated index.ts. By convention implementation lives in lib/ and tests in tests/, giving every package the same two-folder shape. The rule itself is general, though: anything in any subfolder is private, so you never extend the config to add a folder.
Four rules, all error:
- Entry-point boundary: code outside a package (app code or another package) may import only that package's entry points (its root files), never anything in its subfolders.
- Intra-package freedom: a package's own files import each other freely.
- Tests through the entry points: files under
<pkg>/tests/may import any package's entry points and their owntests/fixtures, but never any package's subfolder internals (not even their own). Integration tests across packages are fine; deep imports are not. - No cycles: no dependency cycles.
Entry points, not a barrel. Because the public surface is every root file, a package can expose several small entry points (index.ts, client.ts, server.ts) instead of funnelling everything through one giant index.ts. Barrel files that re-export a whole subtree are discouraged; keep entry points small and hide implementation in subfolders.
Layering (which packages may depend on which) is a different concern and is left as a commented stub in the config for this repo to fill in.
Steps
1. Detect the environment
- Package manager:
pnpm-lock.yaml→ pnpm,yarn.lock→ yarn,bun.lockb→ bun, else npm. Use it for every command below (pnpm/yarn/npm run/bunx). - Packages root: if
src/exists usesrc/packages, elsepackages. Confirm the choice with the user if the repo already has a different obvious convention. - Existing config: check for a
.dependency-cruiser.*file. If one exists, do not overwrite it: merge the four rules and the options in, and tell the user what you added.
Done when: package manager, packages root, and existing-config status are all known.
2. Install dependency-cruiser
Install dependency-cruiser as a devDependency with the detected package manager.
Done when: dependency-cruiser is in devDependencies.
3. Write the config
Copy dependency-cruiser.config.cjs to the repo root as .dependency-cruiser.cjs. Set PACKAGES_ROOT to the root detected in step 1. The rules are path-depth based and extension-agnostic, so nothing else needs adapting.
Done when: .dependency-cruiser.cjs exists with the correct PACKAGES_ROOT, and the four forbidden rules are present.
4. Wire it into the checks
- Add a
lint:boundariesscript:depcruise <packages-root>(ordepcruise src). - Fold it into the repo's umbrella check command, the one that already runs typecheck (e.g. a
check/ci/validatescript). Do not touchtsconfigor add path aliases. - If there is no umbrella script, add
lint:boundariesand tell the user to include it in CI.
Done when: lint:boundaries exists and runs as part of the same command as typecheck.
5. Scaffold the example package
Create a committed <packages-root>/example/ as a copy-me template:
index.tsis an entry point. Export one function that delegates to an internal file (so the package is visibly deep, not a pass-through).lib/impl.ts: an internal file in a subfolder, imported byindex.ts, not reachable from outside.tests/example.test.tsimports only../index(an entry point) and asserts against the public function.
Tell the user this is a starter template to copy or delete.
Done when: the example package exists, exposes its behaviour through a root entry point, and hides impl in a subfolder.
6. Prove the rules bite
This is the completion criterion for the whole skill: a config that doesn't fail on a violation is worthless.
- Run
lint:boundaries. It must pass on the clean example. - Temporarily add a deep import to
tests/example.test.ts(e.g.import { thing } from "../lib/impl"). Runlint:boundariesagain; it must fail withtests-through-entrypoints. - Revert the deep import. Run once more, and it must pass.
Done when: you have observed a pass, then a fail on the deep import, then a pass again. If step 2 does not fail, the rules are not wired correctly, so fix before finishing.
7. Document the convention
Write a README.md in the packages folder (<packages-root>/README.md, next to the packages it governs) covering: the src/packages/<name>/ layout (entry points at the root, lib/ for implementation, tests/ for tests), "import only through a package's entry points (its root files)", and how to run lint:boundaries. Discourage barrel files explicitly: expose several small entry points instead of re-exporting a whole subtree through one index. Keep it to the copy-me snippet plus the four rules in one paragraph each.
Then add a context pointer to it from the repo's agent-instructions file (CLAUDE.md if present, else AGENTS.md, creating AGENTS.md if neither exists). One line is enough, e.g. Packages are deep modules: see [src/packages/README.md](./src/packages/README.md) before adding or importing one. This is what makes an agent discover the boundary rule instead of tripping over it.
Done when: <packages-root>/README.md exists and discourages barrels, and the repo's CLAUDE.md/AGENTS.md links to it.
Notes
- The config's
$1back-references (dependency-cruiser's group matching) are what let a package reach its own internals while outsiders can't. Don't flatten them into separate per-package rules. - Public vs private is decided by depth: a package's root files are entry points; anything in a subfolder is private. The conventional subfolders are
lib/(implementation) andtests/, but the rule doesn't hardcode them: any subfolder is private, so a new folder never needs a config change. Adding an entry point is just adding a root file (no barrel). - Packages are flat: one tier of immediate children under the root. A package's internals may nest as deep as you like; a package may not contain another package.
- Use
.cjs(not.js) so the config'smodule.exportsworks even in"type": "module"repos.
TypeScript Advanced Types
Comprehensive guidance for mastering TypeScript's advanced type system including generics, conditional types, mapped types, template literal types, and utility types for building robust, type-safe applications.
When to Use This Skill
- Building type-safe libraries or frameworks
- Creating reusable generic components
- Implementing complex type inference logic
- Designing type-safe API clients
- Building form validation systems
- Creating strongly-typed configuration objects
- Implementing type-safe state management
- Migrating JavaScript codebases to TypeScript
Core Concepts
1. Generics
Purpose: Create reusable, type-flexible components while maintaining type safety.
Basic Generic Function:
function identity<T>(value: T): T {
return value;
}
const num = identity<number>(42); // Type: number
const str = identity<string>("hello"); // Type: string
const auto = identity(true); // Type inferred: boolean
Generic Constraints:
interface HasLength {
length: number;
}
function logLength<T extends HasLength>(item: T): T {
console.log(item.length);
return item;
}
logLength("hello"); // OK: string has length
logLength([1, 2, 3]); // OK: array has length
logLength({ length: 10 }); // OK: object has length
// logLength(42); // Error: number has no length
Multiple Type Parameters:
function merge<T, U>(obj1: T, obj2: U): T & U {
return { ...obj1, ...obj2 };
}
const merged = merge({ name: "John" }, { age: 30 });
// Type: { name: string } & { age: number }
2. Conditional Types
Purpose: Create types that depend on conditions, enabling sophisticated type logic.
Basic Conditional Type:
type IsString<T> = T extends string ? true : false;
type A = IsString<string>; // true
type B = IsString<number>; // false
Extracting Return Types:
type ReturnType<T> = T extends (...args: any[]) => infer R ? R : never;
function getUser() {
return { id: 1, name: "John" };
}
type User = ReturnType<typeof getUser>;
// Type: { id: number; name: string; }
Distributive Conditional Types:
type ToArray<T> = T extends any ? T[] : never;
type StrOrNumArray = ToArray<string | number>;
// Type: string[] | number[]
Nested Conditions:
type TypeName<T> = T extends string
? "string"
: T extends number
? "number"
: T extends boolean
? "boolean"
: T extends undefined
? "undefined"
: T extends Function
? "function"
: "object";
type T1 = TypeName<string>; // "string"
type T2 = TypeName<() => void>; // "function"
3. Mapped Types
Purpose: Transform existing types by iterating over their properties.
Basic Mapped Type:
type Readonly<T> = {
readonly [P in keyof T]: T[P];
};
interface User {
id: number;
name: string;
}
type ReadonlyUser = Readonly<User>;
// Type: { readonly id: number; readonly name: string; }
Optional Properties:
type Partial<T> = {
[P in keyof T]?: T[P];
};
type PartialUser = Partial<User>;
// Type: { id?: number; name?: string; }
Key Remapping:
type Getters<T> = {
[K in keyof T as `get${Capitalize<string & K>}`]: () => T[K];
};
interface Person {
name: string;
age: number;
}
type PersonGetters = Getters<Person>;
// Type: { getName: () => string; getAge: () => number; }
Filtering Properties:
type PickByType<T, U> = {
[K in keyof T as T[K] extends U ? K : never]: T[K];
};
interface Mixed {
id: number;
name: string;
age: number;
active: boolean;
}
type OnlyNumbers = PickByType<Mixed, number>;
// Type: { id: number; age: number; }
4. Template Literal Types
Purpose: Create string-based types with pattern matching and transformation.
Basic Template Literal:
type EventName = "click" | "focus" | "blur";
type EventHandler = `on${Capitalize<EventName>}`;
// Type: "onClick" | "onFocus" | "onBlur"
String Manipulation:
type UppercaseGreeting = Uppercase<"hello">; // "HELLO"
type LowercaseGreeting = Lowercase<"HELLO">; // "hello"
type CapitalizedName = Capitalize<"john">; // "John"
type UncapitalizedName = Uncapitalize<"John">; // "john"
Path Building:
type Path<T> = T extends object
? {
[K in keyof T]: K extends string ? `${K}` | `${K}.${Path<T[K]>}` : never;
}[keyof T]
: never;
interface Config {
server: {
host: string;
port: number;
};
database: {
url: string;
};
}
type ConfigPath = Path<Config>;
// Type: "server" | "database" | "server.host" | "server.port" | "database.url"
5. Utility Types
Built-in Utility Types:
// Partial<T> - Make all properties optional
type PartialUser = Partial<User>;
// Required<T> - Make all properties required
type RequiredUser = Required<PartialUser>;
// Readonly<T> - Make all properties readonly
type ReadonlyUser = Readonly<User>;
// Pick<T, K> - Select specific properties
type UserName = Pick<User, "name" | "email">;
// Omit<T, K> - Remove specific properties
type UserWithoutPassword = Omit<User, "password">;
// Exclude<T, U> - Exclude types from union
type T1 = Exclude<"a" | "b" | "c", "a">; // "b" | "c"
// Extract<T, U> - Extract types from union
type T2 = Extract<"a" | "b" | "c", "a" | "b">; // "a" | "b"
// NonNullable<T> - Exclude null and undefined
type T3 = NonNullable<string | null | undefined>; // string
// Record<K, T> - Create object type with keys K and values T
type PageInfo = Record<"home" | "about", { title: string }>;
Detailed worked examples and patterns
Detailed sections (starting with ## Advanced Patterns) live in references/details.md. Read that file when the navigation summary above is insufficient.
Best Practices
- Use
unknownoverany: Enforce type checking - Prefer
interfacefor object shapes: Better error messages - Use
typefor unions and complex types: More flexible - Leverage type inference: Let TypeScript infer when possible
- Create helper types: Build reusable type utilities
- Use const assertions: Preserve literal types
- Avoid type assertions: Use type guards instead
- Document complex types: Add JSDoc comments
- Use strict mode: Enable all strict compiler options
- Test your types: Use type tests to verify type behavior
Type Testing
// Type assertion tests
type AssertEqual<T, U> = [T] extends [U]
? [U] extends [T]
? true
: false
: false;
type Test1 = AssertEqual<string, string>; // true
type Test2 = AssertEqual<string, number>; // false
type Test3 = AssertEqual<string | number, string>; // false
// Expect error helper
type ExpectError<T extends never> = T;
// Example usage
type ShouldError = ExpectError<AssertEqual<string, number>>;
Common Pitfalls
- Over-using
any: Defeats the purpose of TypeScript - Ignoring strict null checks: Can lead to runtime errors
- Too complex types: Can slow down compilation
- Not using discriminated unions: Misses type narrowing opportunities
- Forgetting readonly modifiers: Allows unintended mutations
- Circular type references: Can cause compiler errors
- Not handling edge cases: Like empty arrays or null values
Performance Considerations
- Avoid deeply nested conditional types
- Use simple types when possible
- Cache complex type computations
- Limit recursion depth in recursive types
- Use build tools to skip type checking in production
TypeScript Development Patterns
TypeScript patterns and best practices for building robust, type-safe, and maintainable applications. The compiler is most useful when it can prove your program's shape, so the guiding principle here is: push the type system to do real work instead of fighting it. This skill is the "how." For the "what" and "when" (the decisions about which pattern to reach for), see the TypeScript rules — rules/typescript/coding-style.md and rules/typescript/patterns.md in this repository, installed as rules/ecc/typescript/coding-style.md and rules/ecc/typescript/patterns.md.
When to Activate
- Writing new TypeScript or JavaScript code
- Reviewing a PR that touches
.tsor.tsxfiles - Refactoring existing TypeScript to remove
any, tighten types, or add strictness - Designing types, generics, or module boundaries for a new feature
- Setting up a new TypeScript project or upgrading
tsconfig.json - Debugging type errors that cascade through a codebase (usually a design problem, not an annotation problem)
Core Principles
1. Strict Mode Is the Baseline
strict: true (which enables strictNullChecks, noImplicitAny, strictFunctionTypes, and the rest) is not optional in a healthy codebase. If a codebase cannot compile under strict, that is a migration task, not an excuse to leave the flag off.
// tsconfig.json — a strict, discriminating baseline
{
"compilerOptions": {
"strict": true,
"noUncheckedIndexedAccess": true,
"exactOptionalPropertyTypes": true,
"noImplicitOverride": true,
"noFallthroughCasesInSwitch": true,
"noPropertyAccessFromIndexSignature": true,
"noUnusedLocals": true,
"noUnusedParameters": true,
"forceConsistentCasingInFileNames": true,
"verbatimModuleSyntax": true
}
}
noUncheckedIndexedAccess makes array and record access possibly-undefined, which surfaces a whole class of runtime crashes at compile time. If it produces too much noise, this is the pattern to add, not the flag to remove:
// If you have proven the index exists, lift the element into a local first.
const [first] = items
if (first === undefined) {
throw new Error("expected at least one item")
}
2. any Is a Bug, Not a Tool
any disables the type system exactly where a bug is most likely to hide: at the boundary with untrusted or dynamic data. Prefer unknown and narrow it. When you truly need a fallback, prefer an explicit loosening with a comment over a silent any.
// Bad: any disables checking on the public API
export function parseConfig(raw: any): Config {
return raw.config ?? {}
}
interface Config {
timeout: number
retries: number
}
const DEFAULT_CONFIG: Config = { timeout: 30_000, retries: 3 }
function isRecord(value: unknown): value is Record<string, unknown> {
return typeof value === 'object' && value !== null
}
function toPositiveInt(value: unknown, field: string): number {
if (typeof value !== 'number' || !Number.isInteger(value) || value <= 0) {
throw new TypeError(`Expected ${field} to be a positive integer`)
}
return value
}
// Good: unknown forces safe narrowing at the edge. Every consumed field is
// validated with an explicit range, and defaults are declared up front.
export function parseConfig(raw: unknown): Config {
if (!isRecord(raw)) return { ...DEFAULT_CONFIG }
return {
timeout: raw['timeout'] === undefined ? DEFAULT_CONFIG.timeout : toPositiveInt(raw['timeout'], 'timeout'),
retries: raw['retries'] === undefined ? DEFAULT_CONFIG.retries : toPositiveInt(raw['retries'], 'retries'),
}
}
3. Public APIs Get Explicit Types, Locals Get Inference
TypeScript infers local variables well. Exporting functions whose parameter and return types are implicit leaks inference decisions into every consumer and makes intent unreadable.
// Bad: exported API without explicit types
export function formatUser(user) {
return `${user.firstName} ${user.lastName}`
}
// Good: explicit public contract, inferred internals
interface User {
firstName: string
lastName: string
}
export function formatUser(user: User): string {
return `${user.firstName} ${user.lastName}`
}
Type Design
Interfaces vs. Type Aliases
interface for object shapes that may be extended or implemented; type for unions, intersections, tuples, mapped types, and utility types. Prefer string-literal unions over enum unless you need runtime value enumeration or interop with code that requires it.
interface User {
id: string
email: string
}
type UserRole = 'admin' | 'member'
type AdminUser = User & { role: 'admin' }
Discriminated Unions Are the Default State Machine
When a value can be in multiple shapes, model it as a discriminated union with a literal type/kind field. Exhaustive checking then becomes a free compiler feature: never a runtime fallback, always a compile error on a missing branch.
type Transaction =
| { kind: 'draft'; id: string }
| { kind: 'submitted'; id: string; submittedAt: Date }
| { kind: 'paid'; id: string; paidAt: Date; amountCents: number }
function describe(t: Transaction): string {
switch (t.kind) {
case 'draft':
return 'Saved but not sent'
case 'submitted':
return `Submitted on ${t.submittedAt.toISOString()}`
case 'paid':
return `Paid ${t.amountCents} cents on ${t.paidAt.toISOString()}`
default:
// exhaustive: any new member forces this to fail to compile
return assertNever(t)
}
}
function assertNever(value: never): never {
throw new Error(`Unhandled member: ${JSON.stringify(value)}`)
}
Brands and Nominal Safety Where Structure Is Not Enough
Structural typing cannot tell CustomerId from string. When an ID or unit must not be confused with another, add a brand (a phantom field with a unique symbol key).
declare const brand: unique symbol
export type CustomerId = string & { [brand]: 'CustomerId' }
function ensureCustomerId(value: string): CustomerId {
if (!/^cus_[a-z0-9]+$/.test(value)) {
throw new TypeError(`Invalid customer id: ${value}`)
}
return value as CustomerId
}
Keep brands internal to a boundary module; never expose the cast helper far from the validation that justifies it.
Generics Model Caller-Dependent Types
If a value's type depends on what the caller supplies, make it generic rather than flattening to any or unknown and hand-casting at call sites.
// Bad: caller must cast the result
export function getCached(key: string): unknown {
return cache.get(key)
}
// Good: the caller's type flows through
export function getCached<T>(key: string, parse: (raw: string) => T): T | undefined {
const raw = cache.get(key)
if (raw === undefined) return undefined
return parse(raw)
}
Constrain generics so the contract is discoverable: prefer T extends SomeShape over free-floating T when a shape assumption exists.
Options Objects over Positional Parameters
Functions with more than a couple of knobs should take a single options object. It makes call sites self-documenting and lets new knobs be added without positional churn.
interface FetchOptions {
timeoutMs?: number
retries?: number
signal?: AbortSignal
}
export async function fetchWithRetry(url: string, options: FetchOptions = {}): Promise<Response> {
// ...
}
Narrowing and Runtime Safety
Validate at the Boundary, Trust Inside
Untrusted data enters at I/O boundaries: API handlers, message consumers, file loaders. Parse and validate once with a schema, then carry the refined type through the domain. This is where a validation library (for example, Zod) earns its keep — the schema is both the runtime check and the compile-time type.
import { z } from 'zod'
const userInputSchema = z.object({
email: z.string().email(),
age: z.number().int().min(0).max(150)
})
export type UserInput = z.infer<typeof userInputSchema>
// validate once at the edge
const input: UserInput = userInputSchema.parse(rawBody)
Type Predicates and Assertion Functions
Prefer type predicates and assertion functions over unchecked casts when guarding shapes. The guard documents the invariant and the compiler checks its usage.
function isConfig(value: unknown): value is Config {
if (typeof value !== 'object' || value === null) return false
if (!('timeout' in value) || !('retries' in value)) return false
const { timeout, retries } = value
return (
typeof timeout === 'number' && Number.isInteger(timeout) && timeout > 0 &&
typeof retries === 'number' && Number.isInteger(retries) && retries > 0
)
}
To fail loudly on a malformed value instead of returning a boolean, use an assertion signature:
function assertIsStringArray(value: unknown): asserts value is string[] {
if (!Array.isArray(value)) {
throw new TypeError('Expected an array of strings')
}
// Iteration visits sparse positions as undefined instead of skipping them.
for (const item of value) {
if (typeof item !== 'string') throw new TypeError('Expected an array of strings')
}
}
Readonly by Default
Mark array and object parameters readonly/ReadonlyArray when the function does not mutate them. It prevents accidental mutation and signals intent at the signature. (Per the coding-style rules, prefer the spread operator for immutable updates.)
export function totalAmount(items: readonly LineItem[]): number {
return items.reduce((sum, item) => sum + item.amountCents, 0)
}
Runtime immutability (for example, Object.freeze) is for hot application boundaries; readonly in type positions is the everyday guard.
Error Handling
Fail at the Boundary, Handle at the Edge
The try/catch belongs where the caller can act on failure — not wrapped around every internal call in a stack of swallowed errors. Use async/await with try/catch and narrow unknown errors safely (per the coding-style rules).
This endpoint example accepts non-empty IDs made of ASCII letters, digits, underscores, and hyphens, such as u_1. Validate that contract before constructing the path or making a request. Adapt the identifier grammar to the real API.
type User = { id: string; email: string }
function isUser(value: unknown): value is User {
if (typeof value !== 'object' || value === null) return false
if (!('id' in value) || !('email' in value)) return false
const { id, email } = value
return (
typeof id === 'string' && id.length > 0 &&
typeof email === 'string' && email.includes('@')
)
}
function assertUserId(userId: string): void {
if (typeof userId !== 'string' || userId.length === 0 || /[^A-Za-z0-9_-]/.test(userId)) {
throw new TypeError('Expected a user ID using letters, digits, "_" or "-"')
}
}
async function loadUser(userId: string): Promise<User> {
assertUserId(userId)
const response = await fetch(`/users/${userId}`)
if (!response.ok) {
throw new Error(`Failed to load user ${userId}: ${response.status}`)
}
const data: unknown = await response.json()
if (!isUser(data)) {
throw new TypeError(`Invalid user payload for ${userId}`)
}
return data
}
export async function getUser(userId: string): Promise<User> {
try {
return await loadUser(userId)
} catch (error: unknown) {
if (error instanceof Error) {
// known failure mode: retry or surface a friendly message
throw new Error(`user lookup failed: ${error.message}`, { cause: error })
}
throw new TypeError('unknown error shape')
}
}
Result Types for Expected Failures
For expected business failures (validation, not-found, conflict), a discriminated Result union makes failure explicit in the type instead of hiding it in the exception flow.
type Result<T, E> = { ok: true; value: T } | { ok: false; error: E }
function createUser(input: UserInput): Result<User, ValidationIssue[]> {
const issues = validate(input)
if (issues.length > 0) {
return { ok: false, error: issues }
}
return { ok: true, value: { id: generateId(), ...input } }
}
Reserve exceptions for the unexpected. Expected outcomes belong in the return type.
Preserve Error Context
Use new Error(message, { cause }) (available since ES2022) so the original failure chain survives rewrapping. Never stringify errors into a message and lose the cause.
Async Patterns
Prefer Promise.allSettled for Independent Fan-Out
When results are independent and one failure must not drop the others, use Promise.allSettled and handle the per-promise outcomes.
const results: PromiseSettledResult<number>[] = await Promise.allSettled(
sourceIds.map((id) => fetchCount(id))
)
const total = results.reduce((sum, result) => {
if (result.status === 'fulfilled') {
return sum + result.value
}
log.warn('count fetch failed', result.reason)
return sum
}, 0)
Use Promise.all when you want fail-fast semantics — genuinely all-or-nothing work.
Avoid Unbounded Concurrency
Fanning out hundreds of promises at once overwhelms connections and event loop. Bound the concurrency with a small pool.
async function mapWithConcurrency<T, R>(
items: readonly T[],
limit: number,
mapper: (item: T) => Promise<R>
): Promise<R[]> {
if (!Number.isInteger(limit) || limit < 1) {
throw new RangeError(`Expected concurrency limit to be a positive integer, got: ${limit}`)
}
const results: R[] = new Array(items.length)
let nextIndex = 0
const workers = Array.from({ length: Math.min(limit, items.length) }, async () => {
while (true) {
const index = nextIndex++
if (index >= items.length) return
// Required under noUncheckedIndexedAccess: the index is proven
// in-bounds above, but the compiler still types this T | undefined.
// Skip only genuine sparse-array holes, mirroring Array.prototype.map:
// a present `undefined` element is a legitimate value and must still
// reach the mapper.
if (!Object.hasOwn(items, index)) continue
// Presence is proven above, so the indexed access is in-bounds and
// filled — never a hole and never the compiler's speculative undefined.
results[index] = await mapper(items[index]!)
}
})
// One worker rejecting rejects the whole pool: Promise.all propagates the
// first rejection to the caller (fail-fast). That is rejection, not
// cancellation — the other workers keep running and may settle more of
// their remaining items after the pool has already rejected. Use
// Promise.all only when leaving that in-flight work running is acceptable;
// otherwise use allSettled or thread an AbortSignal through the mapper.
await Promise.all(workers)
return results
}
Timeouts and Cancellation
Always thread AbortSignal through long-running or outbound work so callers can cancel; pair it with Promise.race for hard timeouts where the underlying operation cannot be aborted.
function withTimeout<T>(promise: Promise<T>, ms: number): Promise<T> {
return new Promise((resolve, reject) => {
const timer = setTimeout(() => reject(new Error(`Timed out after ${ms}ms`)), ms)
promise.then(
(value) => {
clearTimeout(timer)
resolve(value)
},
(reason) => {
clearTimeout(timer)
reject(reason)
}
)
})
}
Null and Undefined Discipline
Prefer a discriminated approach over mixing sentinel values. Where "not found" or "absent" is a legitimate state, use T | undefined and check explicitly; avoid deeply nesting ?. chains followed by silent fallbacks that hide bugs.
function findUser(id: string): User | undefined {
return users.get(id)
}
const user = findUser('u_1')
if (user === undefined) {
return notFound()
}
// from here on, `user` is narrowed to User
Avoid truthiness checks that silently accept wrong types (if (result) when result may be 0 or ''). Compare against undefined/null explicitly.
Module Boundaries and Exports
Small, Named Modules
Expose a deliberate surface at each module's boundary. Prefer explicit named exports over default exports, and re-export at the public edge so consumers import from the module that owns the type — not from deep internals that can be refactored.
// user/model.ts — internal types
export interface UserAccount {
id: string
email: string
role: UserRole
}
// user/index.ts — public surface
export { type UserAccount, type UserRole } from './model'
export { createUser, findUser, updateUser } from './service'
Avoid Barrel Bloat and Circular Imports
Do not create barrels that import everything at module load (they defeat tree-shaking and grow cold-start). Import concrete paths. Circular imports signal a submission boundary that should fold upward; the type that both sides need belongs in a shared module neither imports.
Split by Dependency Direction
Let the type graph point the way: types that cross boundaries go in a contract module; implementations import the contract; nothing imports implementations from contracts. In a node/backend codebase that means roughly: domain (pure types and rules) → application (use cases) → infrastructure (adapters), with dependencies pointing only inward.
Dependencies and Build
Diagnose, Then Add Dependencies
Prefer built-in Array, Map, Promise, and Intl over pulling in utilities for every small operation. A tiny inline function beats a dependency that must be upgraded, audited, and kept compatible. (The Go idiom "a little copying is better than a little dependency" applies to TypeScript too.)
Runtime Validation, Not Type-of-Trust
Schemas that validate at runtime (Zod, validators, or hand-written guards) are the bridge between untrusted data and compile-time types. Library approaches differ (Zod and other schema-first libraries derive the type from the schema; validators in some ecosystem patterns are type-first with the runtime check derived). Pick one model and be consistent across the codebase.
Keep the Compiler Incremental and Fast
Large codebases benefit from composite: true with project references, an incremental build cache, and moduleResolution: bundler where the bundler supports it. Slow type-checking is a workflow problem that pushes developers off the type system — invest in narrowing the checked surface over relaxing it.
Performance
Types Are Free, Structures Are Not
Type-level gymnastics (mapped types, conditional types, template literal types) cost nothing at runtime but can cost a lot of developer clarity. Keep complex type machinery inside boundary modules; do not export type circus acts as the public API.
Avoid Unnecessary Object Renaming
Copying and spreading large nested objects repeatedly has real cost in hot paths. Prefer immutable updates with spread at the point of change, but avoid defensive re-copying of unchanged structures (for example, in render paths or per-message handlers).
Memoize Idempotent Computation
Pure, expensive derivations belong behind a cache if they repeat with the same inputs. Use Map-based caches with explicit lifetime instead of ad-hoc global caches that never clear.
Type-Level Testing
Assert the Types, Not Just the Runtime
Behavior tests prove runtime behavior; dedicated type tests lock in the public API contract. A type that silently loosens is a regression.
import { expectTypeOf } from 'vitest'
expectTypeOf<Result<User, ValidationIssue[]>>().toEqualTypeOf<
| { ok: true; value: User }
| { ok: false; error: ValidationIssue[] }
>()
Use satisfies to Preserve Intent
satisfies checks a value against a shape without widening it to that shape — the ideal way to keep literal types while still validating structure.
const statusByAction = {
new: 'open',
reopen: 'open',
close: 'closed'
} as const satisfies Record<Action, Status>
TypeScript Tooling Integration
Essential Commands
# Type-check the whole project
npx tsc --noEmit
# Watch mode for fast feedback
npx tsc --noEmit --watch
# Run tests (Vitest)
npx vitest run
# Lint with types-aware rules (typescript-eslint)
npx eslint .
# Formatting
npx prettier --write .
Recommended Linter Baseline
The typescript-eslint recommended-type-checked ruleset is the practical default: it promotes no-unsafe-assignment, no-unsafe-member-access, no-unsafe-argument, and no-unsafe-call from style noise to compiler-like guarantees. Keep the type-aware config; if it is slow, that is a project-structure signal, not a reason to disable it.
Anti-Patterns to Avoid
anyas a speed hack — it converts the compiler's proof into a runtime guess. Reach forunknown+ narrowing instead.ascasts that lie — a cast that bypasses a check you did not actually perform is where null-pointer and shape bugs are born. Validate, then cast, and keep the cast inside the module that validates.- Deeply nested callbacks / promise chains — prefer async/await; flat code is narrowable code.
enumcoercion bugs — string-literal unions give you the same safety without runtime artifacts or reverse-mapping footguns.- Giant god types — a single interface that models several unrelated shapes should be a discriminated union or several interfaces.
- Optional-only option objects —
allOptionalconfig types silently swallow typos at the call site; prefer required fields for the ones the function genuinely depends on. - Silent catch —
catch {}orcatch (e) { /* nothing */ }hides failures the caller assumed were handled. - Mixing sync and async error paths — an
asyncfunction always surfaces throws as rejections, even before the firstawait. Only a non-asyncfunction returning a promise can throw synchronously (before returning it), forcing callers to handle two error shapes. Preferasyncthroughout so every failure is a rejection:
async function asyncFails(): Promise<never> {
throw new Error('becomes a rejection, never a sync throw')
}
function lazyFails(): Promise<never> {
throw new Error('throws synchronously — needs try/catch AND .catch')
}
Remember: the type system is a proof tool, not a paperwork burden. When a type error resists a reasonable annotation, the design — not the compiler — is usually the thing to change. Prefer boring, explicit, well-scoped TypeScript over clever type engines.
Related Skills
nestjs-patterns— NestJS architecture patterns for TypeScript backends (modules, controllers, providers, DTO validation)frontend-patterns— React and Next.js component and state patterns- TypeScript rules (
rules/typescript/, installed asrules/ecc/typescript/) — the "what" and "when" this skill implements as the "how" prisma-patterns— database access patterns used in TypeScript applications
Sponsors
Details
- Marketplace
- marslanalvi/SkillsStack
- Source
- plugins/engineering/javascript-typescript
- Category
- Engineering
- Keywords
- engineering, javascript-typescript
More from marslanalvi/SkillsStack
All 45- engineering-jvmv1.0.0
- engineering-mobilev1.0.0
- engineering-other-languagesv1.0.0
- engineering-pythonv1.0.0
- engineering-systems-languagesv1.0.0
- engineering-testingv1.0.0
- marketing-content-socialv1.0.0
- marketing-growth-adsv1.0.0
- marketing-seov1.0.0
- productivity-automation-personalv1.0.0
- productivity-documents-officev1.0.0
- productivity-thinking-planningv1.0.0
- productivity-writing-communicationv1.0.0
- security-appsec-reviewv1.0.0
- security-blockchain-web3v1.0.0
- security-compliance-privacyv1.0.0
- security-fuzzingv1.0.0
- security-offensive-securityv1.0.0
- ai-agent-engineeringv1.0.0
- ai-coding-assistant-workflowv1.0.0
- ai-llm-applicationsv1.0.0
- ai-machine-learningv1.0.0
- ai-skill-authoringv1.0.0
- business-legal-industryv1.0.0