majiayu000/spellbook / skills/typescript-project
typescript-project
FlaggedModern TypeScript project architecture guide for 2025. Use when creating new TS projects, setting up configurations, or designing project structure. Covers tech stack selection, layered architecture, and best practices.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 12.9 KB |
| reference/architecture.md | markdown | 8.4 KB |
| reference/patterns.md | markdown | 12.0 KB |
| reference/tech-stack.md | markdown | 9.4 KB |
| templates/project/biome.json | config | 566 B |
| templates/project/package.json | manifest | 735 B |
| templates/project/src/adapters/in-memory.repository.ts | script | 909 B |
| templates/project/src/adapters/llm.adapter.ts | script | 2.6 KB |
| templates/project/src/index.ts | script | 595 B |
| templates/project/src/lib/config.ts | script | 1.5 KB |
| templates/project/src/lib/errors.ts | script | 1.5 KB |
| templates/project/src/lib/index.ts | script | 148 B |
| templates/project/src/lib/logger.ts | script | 2.2 KB |
| templates/project/src/lib/types.ts | script | 947 B |
| templates/project/src/services/example.service.ts | script | 2.3 KB |
| templates/project/tests/example.service.test.ts | script | 3.5 KB |
| templates/project/tsconfig.json | config | 584 B |
reference/patterns.md
View on GitHub# Design Patterns Reference
## Table of Contents
1. [Result Pattern](#result-pattern)
2. [Repository Pattern](#repository-pattern)
3. [Factory Pattern](#factory-pattern)
4. [Strategy Pattern](#strategy-pattern)
5. [Builder Pattern](#builder-pattern)
6. [Middleware Pattern](#middleware-pattern)
7. [Event-Driven Pattern](#event-driven-pattern)
---
## Result Pattern
Handle success/failure without exceptions:
```typescript
// lib/result.ts
export type Result<T, E = Error> =
| { ok: true; value: T }
| { ok: false; error: E };
export const Result = {
ok: <T>(value: T): Result<T, never> => ({ ok: true, value }),
err: <E>(error: E): Result<never, E> => ({ ok: false, error }),
map: <T, U, E>(result: Result<T, E>, fn: (value: T) => U): Result<U, E> =>
result.ok ? Result.ok(fn(result.value)) : result,
flatMap: <T, U, E>(
result: Result<T, E>,
fn: (value: T) => Result<U, E>
): Result<U, E> => (result.ok ? fn(result.value) : result),
unwrap: <T, E>(result: Result<T, E>): T => {
if (!result.ok) throw result.error;
return result.value;
},
};
// Usage
async function findUser(id: string): Promise<Result<User, AppError>> {
const user = await db.users.findById(id);
if (!user) return Result.err(AppError.notFound('User', id));
return Result.ok(user);
}
const result = await findUser('123');
if (!result.ok) {
return res.status(404).json({ error: result.error.message });
}
const user = result.value;
```
---
## Repository Pattern
Abstract data access behind interfaces:
```typescript
// types/repository.ts
export interface Repository<T, ID = string> {
findById(id: ID): Promise<T | null>;
findAll(): Promise<T[]>;
save(entity: T): Promise<T>;
delete(id: ID): Promise<void>;
}
// services/user.repository.ts
export interface UserRepository extends Repository<User> {
findByEmail(email: string): Promise<User | null>;
findByRole(role: UserRole): Promise<User[]>;
}
// adapters/postgres/user.repository.ts
export class PostgresUserRepository implements UserRepository {
constructor(private readonly db: Database) {}
async findById(id: string): Promise<User | null> {
const row = await this.db.query(
'SELECT * FROM users WHERE id = $1',
[id]
);
return row ? this.toEntity(row) : null;
}
async findByEmail(email: string): Promise<User | null> {
const row = await this.db.query(
'SELECT * FROM users WHERE email = $1',
[email]
);
return row ? this.toEntity(row) : null;
}
async save(user: User): Promise<User> {
const row = await this.db.query(
`INSERT INTO users (id, email, name, created_at)
VALUES ($1, $2, $3, $4)
ON CONFLICT (id) DO UPDATE SET email = $2, name = $3
RETURNING *`,
[user.id, user.email, user.name, user.createdAt]
);
return this.toEntity(row);
}
private toEntity(row: UserRow): User {
return new User(row.id, row.email, row.name, row.created_at);
}
}
// Testing with in-memory implementation
export class InMemoryUserRepository implements UserRepository {
private users = new Map<string, User>();
async findById(id: string): Promise<User | null> {
return this.users.get(id) ?? null;
}
async save(user: User): Promise<User> {
this.users.set(user.id, user);
return user;
}
// ...
}
```
---
## Factory Pattern
Encapsulate complex object creation:
```typescript
// Simple Factory
export function createLogger(config: LogConfig): Logger {
const transports: Transport[] = [];
if (config.console) {
transports.push(new ConsoleTransport(config.level));
}
if (config.file) {
transports.push(new FileTransport(config.file));
}
if (config.remote) {
transports.push(new RemoteTransport(config.remote));
}
return new Logger(transports);
}
// Factory with Registry
class NotificationFactory {
private registry = new Map<string, NotificationBuilder>();
register(type: string, builder: NotificationBuilder) {
this.registry.set(type, builder);
}
create(type: string, data: NotificationData): Notification {
const builder = this.registry.get(type);
if (!builder) throw new Error(`Unknown type: ${type}`);
return builder(data);
}
}
const factory = new NotificationFactory();
factory.register('email', (data) => new EmailNotification(data));
factory.register('sms', (data) => new SmsNotification(data));
factory.register('push', (data) => new PushNotification(data));
const notification = factory.create('email', { to: 'user@example.com' });
// Abstract Factory
interface DatabaseFactory {
createConnection(): Connection;
createQueryBuilder(): QueryBuilder;
createMigrator(): Migrator;
}
class PostgresFactory implements DatabaseFactory {
createConnection() { return new PostgresConnection(); }
createQueryBuilder() { return new PostgresQueryBuilder(); }
createMigrator() { return new PostgresMigrator(); }
}
class SqliteFactory implements DatabaseFactory {
createConnection() { return new SqliteConnection(); }
createQueryBuilder() { return new SqliteQueryBuilder(); }
createMigrator() { return new SqliteMigrator(); }
}
```
---
## Strategy Pattern
Swap algorithms at runtime:
```typescript
// Define strategy interface
interface PricingStrategy {
calculate(order: Order): Money;
}
// Concrete strategies
class StandardPricing implements PricingStrategy {
calculate(order: Order): Money {
return order.items.reduce(
(sum, item) => sum.add(item.price.multiply(item.quantity)),
Money.zero()
);
}
}
class DiscountPricing implements PricingStrategy {
constructor(private readonly discount: Percentage) {}
calculate(order: Order): Money {
const subtotal = new StandardPricing().calculate(order);
return subtotal.subtract(subtotal.multiply(this.discount));
}
}
class TieredPricing implements PricingStrategy {
calculate(order: Order): Money {
const subtotal = new StandardPricing().calculate(order);
const discount = this.getTierDiscount(subtotal);
return subtotal.subtract(subtotal.multiply(discount));
}
private getTierDiscount(amount: Money): Percentage {
if (amount.greaterThan(Money.of(1000))) return Percentage.of(20);
if (amount.greaterThan(Money.of(500))) return Percentage.of(10);
if (amount.greaterThan(Money.of(100))) return Percentage.of(5);
return Percentage.zero();
}
}
// Context
class OrderProcessor {
constructor(private strategy: PricingStrategy) {}
setStrategy(strategy: PricingStrategy) {
this.strategy = strategy;
}
process(order: Order): ProcessedOrder {
const total = this.strategy.calculate(order);
return { ...order, total };
}
}
// Usage
const processor = new OrderProcessor(new StandardPricing());
processor.setStrategy(new DiscountPricing(Percentage.of(15)));
const result = processor.process(order);
```
---
## Builder Pattern
Construct complex objects step by step:
```typescript
// Fluent Builder
class QueryBuilder<T> {
private query: QueryConfig = { table: '', conditions: [], orderBy: [] };
from(table: string): this {
this.query.table = table;
return this;
}
where(field: string, op: Operator, value: unknown): this {
this.query.conditions.push({ field, op, value });
return this;
}
orderBy(field: string, direction: 'asc' | 'desc' = 'asc'): this {
this.query.orderBy.push({ field, direction });
return this;
}
limit(n: number): this {
this.query.limit = n;
return this;
}
build(): Query<T> {
if (!this.query.table) throw new Error('Table required');
return new Query(this.query);
}
}
// Usage
const query = new QueryBuilder<User>()
.from('users')
.where('status', '=', 'active')
.where('age', '>', 18)
.orderBy('createdAt', 'desc')
.limit(10)
.build();
// Builder with Director
class HttpRequestBuilder {
private request: Partial<HttpRequest> = {};
method(m: HttpMethod): this {
this.request.method = m;
return this;
}
url(u: string): this {
this.request.url = u;
return this;
}
header(key: string, value: string): this {
this.request.headers = { ...this.request.headers, [key]: value };
return this;
}
json(data: unknown): this {
this.request.body = JSON.stringify(data);
return this.header('Content-Type', 'application/json');
}
build(): HttpRequest {
if (!this.request.method || !this.request.url) {
throw new Error('Method and URL required');
}
return this.request as HttpRequest;
}
}
// Director for common patterns
const ApiRequest = {
get: (url: string) =>
new HttpRequestBuilder().method('GET').url(url).build(),
postJson: (url: string, data: unknown) =>
new HttpRequestBuilder().method('POST').url(url).json(data).build(),
};
```
---
## Middleware Pattern
Chain processing functions:
```typescript
// Type definitions
type Next = () => Promise<void>;
type Middleware<C> = (ctx: C, next: Next) => Promise<void>;
// Middleware composer
function compose<C>(middlewares: Middleware<C>[]): Middleware<C> {
return async (ctx, next) => {
let index = -1;
async function dispatch(i: number): Promise<void> {
if (i <= index) throw new Error('next() called multiple times');
index = i;
const fn = i < middlewares.length ? middlewares[i] : next;
if (fn) await fn(ctx, () => dispatch(i + 1));
}
await dispatch(0);
};
}
// Example middlewares
const logger: Middleware<Context> = async (ctx, next) => {
const start = Date.now();
await next();
const ms = Date.now() - start;
console.log(`${ctx.method} ${ctx.path} - ${ms}ms`);
};
const errorHandler: Middleware<Context> = async (ctx, next) => {
try {
await next();
} catch (error) {
ctx.status = error.statusCode || 500;
ctx.body = { error: error.message };
}
};
const auth: Middleware<Context> = async (ctx, next) => {
const token = ctx.headers.authorization?.replace('Bearer ', '');
if (!token) throw new UnauthorizedError();
ctx.user = await verifyToken(token);
await next();
};
// Usage
const app = compose([errorHandler, logger, auth, router]);
```
---
## Event-Driven Pattern
Decouple components with events:
```typescript
// Event definitions
interface DomainEvents {
'user.created': { userId: string; email: string };
'user.verified': { userId: string };
'order.placed': { orderId: string; userId: string; total: number };
'order.shipped': { orderId: string; trackingNumber: string };
}
// Type-safe event emitter
class EventBus<Events extends Record<string, unknown>> {
private handlers = new Map<keyof Events, Set<Function>>();
on<K extends keyof Events>(
event: K,
handler: (payload: Events[K]) => void | Promise<void>
): () => void {
if (!this.handlers.has(event)) {
this.handlers.set(event, new Set());
}
this.handlers.get(event)!.add(handler);
return () => this.handlers.get(event)?.delete(handler);
}
async emit<K extends keyof Events>(event: K, payload: Events[K]): Promise<void> {
const handlers = this.handlers.get(event);
if (!handlers) return;
await Promise.all(
Array.from(handlers).map((handler) => handler(payload))
);
}
}
// Usage
const events = new EventBus<DomainEvents>();
// Subscribe
events.on('user.created', async ({ userId, email }) => {
await sendWelcomeEmail(email);
});
events.on('user.created', async ({ userId }) => {
await createDefaultSettings(userId);
});
events.on('order.placed', async ({ orderId, userId }) => {
await notifyUser(userId, `Order ${orderId} confirmed`);
});
// Emit from service
class UserService {
constructor(
private readonly repo: UserRepository,
private readonly events: EventBus<DomainEvents>
) {}
async create(input: CreateUserInput): Promise<User> {
const user = await this.repo.save(User.create(input));
await this.events.emit('user.created', {
userId: user.id,
email: user.email,
});
return user;
}
}
```
---
## Pattern Selection Guide
| Scenario | Pattern |
|----------|---------|
| Handle errors without exceptions | Result |
| Abstract data access | Repository |
| Complex object creation | Factory |
| Swappable algorithms | Strategy |
| Step-by-step construction | Builder |
| Request/response processing | Middleware |
| Decouple components | Event-Driven |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |