patterns

name	patterns
description	Architectural patterns for code that uses wellcrafted. Covers control flow with trySync/tryAsync, factory function composition, service layers with Result types, error composition across boundaries, and the single-or-array pattern.

Patterns

A style guide for code that uses wellcrafted. Not API reference — architectural taste.

Human-Readable Control Flow

Mirror natural human reasoning: try the thing, check if it failed, continue on the happy path.

Linearizing try-catch into guards

Before — nested, mixed throw/return:

async function handleRequest(userId: string) {
	try {
		const user = await fetchUser(userId);
		const posts = await fetchPosts(user.id);
		return Response.json({ user, posts });
	} catch (error) {
		const message = error instanceof Error ? error.message : 'Unknown error';
		return Response.json({ error: message }, { status: 500 });
	}
}

After — linear guards with tryAsync:

import { tryAsync, Err } from 'wellcrafted/result';

async function handleRequest(userId: string) {
	const { data: user, error: userError } = await tryAsync({
		try: () => fetchUser(userId),
		catch: (cause) => UserError.FetchFailed({ userId, cause })
	});
	if (userError) return Response.json({ error: userError.message }, { status: 502 });

	const { data: posts, error: postsError } = await tryAsync({
		try: () => fetchPosts(user.id),
		catch: (cause) => PostError.FetchFailed({ userId: user.id, cause })
	});
	if (postsError) return Response.json({ error: postsError.message }, { status: 502 });

	return Response.json({ user, posts });
}

Each guard has the same shape: do the thing → check → return early on failure. The happy path accumulates at the bottom.

Natural-language boolean variables

Name booleans so they read like thoughts:

const isAuthenticated = session && !session.expired;
const needsRefresh = token.expiresAt < Date.now() + BUFFER_MS;
const canSkipValidation = input.source === 'trusted' && input.validated;

if (!isAuthenticated) return Response.json({ error: 'Unauthorized' }, { status: 401 });
if (needsRefresh) await refreshToken(token);

Early returns as guard clauses

async function createUser(email: string): Promise<Result<User, UserError>> {
	// Guard: validate input
	if (!email.includes('@')) return UserError.InvalidEmail({ email });

	// Guard: check uniqueness
	const existing = await db.findByEmail(email);
	if (existing) return UserError.AlreadyExists({ email });

	// Happy path
	return tryAsync({
		try: () => db.users.create({ email }),
		catch: (cause) => UserError.CreateFailed({ email, cause })
	});
}

Factory Function Composition

The universal signature

Every factory function follows this shape:

function createSomething(dependencies, options?) {
	return {
		/* methods */
	};
}

Two arguments max. First is resources, second is config. Dependencies come first because they're what makes the factory reusable — the same factory with different deps produces different behavior.

// Single dependency
function createUserService(db: Database) {
	return {
		getById(userId: string) {
			/* uses db */
		},
		create(data: CreateUserInput) {
			/* uses db */
		}
	};
}

// Multiple dependencies
function createNotificationService({ email, sms }: { email: EmailClient; sms: SmsClient }) {
	return {
		notify(userId: string, message: string) {
			/* uses email, sms */
		}
	};
}

Separating option layers

Each layer owns its own configuration. Don't mix them.

// WRONG — mixed options blob
sendEmail({
	timeout: 5000, // client option
	retries: 3, // client option
	to: '[e-mail]', // method option
	subject: 'Hello' // method option
});

// CORRECT — each layer has its own options
const client = createEmailClient({ timeout: 5000, retries: 3 });
const service = createEmailService(client);
service.send({ to: '[e-mail]', subject: 'Hello' });

Anti-patterns

// WRONG — client creation hidden inside
function sendEmail(clientOptions: ClientOpts, emailOptions: EmailOpts) {
	const client = createClient(clientOptions); // Hidden!
	return client.send(emailOptions);
}

// CORRECT — visible dependency chain
const client = createEmailClient(clientOptions);
const service = createEmailService(client);
service.send(emailOptions);

// WRONG — function takes client as first argument everywhere
function getUser(db: Database, userId: string) { ... }
function createUser(db: Database, data: UserInput) { ... }

// CORRECT — factory captures the dependency
const userService = createUserService(db);
userService.getById(userId);
userService.create(data);

Internal zone ordering

Inside a factory, organize code in four zones:

function createUserService(db: Database, options?: { maxRetries?: number }) {
	// Zone 1 — Immutable state (const from deps/options)
	const maxRetries = options?.maxRetries ?? 3;

	// Zone 2 — Mutable state (let declarations)
	let connectionCount = 0;

	// Zone 3 — Private helpers (not exposed)
	function withRetry<T>(fn: () => Promise<T>): Promise<T> {
		/* ... */
	}

	// Zone 4 — Public API (always last)
	return {
		async getById(userId: string): Promise<Result<User, UserError>> {
			/* ... */
		},
		async create(data: CreateUserInput): Promise<Result<User, UserError>> {
			/* ... */
		}
	};
}

The return object is always last — it's the complete public API.

Service Layer Pattern

Services are factory functions that return objects with methods returning Result<T, E>. Each service defines its own error vocabulary with defineErrors.

Complete example

import { defineErrors, extractErrorMessage, type InferErrors } from 'wellcrafted/error';
import { Ok, tryAsync, type Result } from 'wellcrafted/result';

// 1. Define domain errors
const UserError = defineErrors({
	NotFound: ({ userId }: { userId: string }) => ({
		message: `User ${userId} not found`,
		userId
	}),
	CreateFailed: ({ email, cause }: { email: string; cause: unknown }) => ({
		message: `Failed to create user ${email}: ${extractErrorMessage(cause)}`,
		email,
		cause
	}),
	FetchFailed: ({ cause }: { cause: unknown }) => ({
		message: `Failed to fetch users: ${extractErrorMessage(cause)}`,
		cause
	})
});
type UserError = InferErrors<typeof UserError>;

// 2. Factory function returns service object
function createUserService(db: Database) {
	return {
		async getById(userId: string): Promise<Result<User, UserError>> {
			const { data: user, error } = await tryAsync({
				try: () => db.users.findById(userId),
				catch: (cause) => UserError.FetchFailed({ cause })
			});
			if (error) return error;
			if (!user) return UserError.NotFound({ userId });
			return Ok(user);
		},

		async create(email: string): Promise<Result<User, UserError>> {
			return tryAsync({
				try: () => db.users.insert({ email }),
				catch: (cause) => UserError.CreateFailed({ email, cause })
			});
		}
	};
}

// 3. Export factory + Live instance
type UserService = ReturnType<typeof createUserService>;
const UserServiceLive = createUserService(productionDb);

The factory is for testing (inject mocks), the Live instance is for production.

Namespace re-exports

Organize services hierarchically:

// services/index.ts
import { UserServiceLive } from './user';
import { PostServiceLive } from './post';

export const services = {
	users: UserServiceLive,
	posts: PostServiceLive
} as const;

Error Composition Across Layers

Each layer defines its own error vocabulary. Inner errors become cause fields in higher-level errors. extractErrorMessage formats them inside the factory.

// Layer 1: HTTP client errors
const HttpError = defineErrors({
	Connection: ({ url, cause }: { url: string; cause: unknown }) => ({
		message: `Failed to connect to ${url}: ${extractErrorMessage(cause)}`,
		url,
		cause
	}),
	Response: ({ url, status }: { url: string; status: number }) => ({
		message: `${url} returned HTTP ${status}`,
		url,
		status
	})
});

// Layer 2: domain service wraps HTTP errors via cause
const UserError = defineErrors({
	FetchFailed: ({ userId, cause }: { userId: string; cause: unknown }) => ({
		message: `Failed to fetch user ${userId}: ${extractErrorMessage(cause)}`,
		userId,
		cause
	})
});

// The HTTP error becomes cause in the domain error
async function getUser(userId: string): Promise<Result<User, UserError>> {
	const { data: response, error } = await tryAsync({
		try: () => fetch(`/api/users/${userId}`),
		catch: (cause) => UserError.FetchFailed({ userId, cause })
		//                 raw fetch error ^^^^ becomes cause
	});
	if (error) return error;

	if (response.status === 404) return UserError.NotFound({ userId });

	return tryAsync({
		try: () => response.json() as Promise<User>,
		catch: (cause) => UserError.FetchFailed({ userId, cause })
	});
}

The full error chain is JSON-serializable at every level. Log it, send it over the wire, display it in a toast.

See also: define-errors skill for error variant definitions. result-types skill for trySync/tryAsync patterns.

The Single-or-Array Pattern

Accept both single items and arrays, normalize at the top, process uniformly.

function deleteUsers(userOrUsers: User | User[]): Promise<Result<void, DbError>> {
	const users = Array.isArray(userOrUsers) ? userOrUsers : [userOrUsers];

	// One code path for both cases
	const ids = users.map((u) => u.id);
	return tryAsync({
		try: () => db.users.bulkDelete(ids),
		catch: (cause) => DbError.DeleteFailed({ cause })
	});
}

// Works with one
await deleteUsers(user);

// Works with many
await deleteUsers([user1, user2, user3]);

Naming convention

Parameter	Normalized Variable
userOrUsers	users
itemOrItems	items
postOrPosts	posts

Anti-patterns

// WRONG — separate functions for single vs array
function deleteUser(user: User): Promise<...>;
function deleteUsers(users: User[]): Promise<...>;

// WRONG — forcing arrays everywhere
deleteUsers([user]); // awkward for single items

// WRONG — duplicated logic in overloads
function deleteUser(user: User) { return db.delete(user.id); }
function deleteUsers(users: User[]) { return db.bulkDelete(users.map(u => u.id)); }

// CORRECT — single implementation
function deleteUsers(userOrUsers: User | User[]) {
  const users = Array.isArray(userOrUsers) ? userOrUsers : [userOrUsers];
  return db.bulkDelete(users.map((u) => u.id));
}