What is factory-function-composition?

This Claude skill provides a structured approach to implementing factory function patterns in TypeScript, facilitating clean dependency injection and a clear separation of concerns. By standardizing how clients and services are composed, it eliminates common anti-patterns like hidden dependencies and mixed configuration blobs, resulting in a more maintainable, scalable, and testable codebase.

When should I use factory-function-composition?

factory-function-composition is useful in the following scenarios: • 1. Refactoring Legacy Code: Decoupling hardcoded client initializations from business logic to improve modularity and code reuse. • 2. Enhancing Testability: Implementing dependency injection via factory functions to easily swap real clients with mocks or stubs during unit testing. • 3. API Client Wrapper Development: Creating domain-specific service layers that wrap low-level SDKs while keeping client, service, and method configurations strictly separated. • 4. Standardizing Team Codebases: Establishing a universal function signature for service creation to ensure architectural consistency across large-scale TypeScript projects.

name	factory-function-composition
description	Apply factory function patterns to compose clients and services with proper separation of concerns. Use when creating functions that depend on external clients, wrapping resources with domain-specific methods, or refactoring code that mixes client/service/method options together.
author	epicenter
version	'1.0'

Factory Function Composition

This skill helps you apply factory function patterns for clean dependency injection and function composition in TypeScript.

When to Apply This Skill

Use this pattern when you see:

A function that takes a client/resource as its first argument
Options from different layers (client, service, method) mixed together
Client creation happening inside functions that shouldn't own it
Functions that are hard to test because they create their own dependencies

The Universal Signature

Every factory function follows this signature:

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

First argument: Always the resource(s). Either a single client or a destructured object of multiple dependencies.
Second argument: Optional configuration specific to this factory. Never client config—that belongs at client creation.

Two arguments max. First is resources, second is config. No exceptions.

The Core Pattern

// Single dependency
function createService(client, options = {}) {
	return {
		method(methodOptions) {
			// Uses client, options, and methodOptions
		},
	};
}

// Multiple dependencies
function createService({ db, cache }, options = {}) {
	return {
		method(methodOptions) {
			// Uses db, cache, options, and methodOptions
		},
	};
}

// Usage
const client = createClient(clientOptions);
const service = createService(client, serviceOptions);
service.method(methodOptions);

Key Principles

Client configuration belongs at client creation time — don't pipe clientOptions through your factory
Each layer has its own options — client, service, and method options stay separate
Dependencies come first — factory functions take dependencies as the first argument
Return objects with methods — not standalone functions that need the resource passed in

Recognizing the Anti-Patterns

Anti-Pattern 1: Function takes client as first argument

// Bad
function doSomething(client, options) { ... }
doSomething(client, options);

// Good
const service = createService(client);
service.doSomething(options);

Anti-Pattern 2: Client creation hidden inside

// Bad
function doSomething(clientOptions, methodOptions) {
	const client = createClient(clientOptions); // Hidden!
	// ...
}

// Good
const client = createClient(clientOptions);
const service = createService(client);
service.doSomething(methodOptions);

Anti-Pattern 3: Mixed options blob

// Bad
doSomething({
	timeout: 5000, // Client option
	retries: 3, // Client option
	endpoint: '/users', // Method option
	payload: data, // Method option
});

// Good
const client = createClient({ timeout: 5000, retries: 3 });
const service = createService(client);
service.doSomething({ endpoint: '/users', payload: data });

Anti-Pattern 4: Multiple layers hidden

// Bad
function doSomething(clientOptions, serviceOptions, methodOptions) {
	const client = createClient(clientOptions);
	const service = createService(client, serviceOptions);
	return service.method(methodOptions);
}

// Good — each layer visible and configurable
const client = createClient(clientOptions);
const service = createService(client, serviceOptions);
service.method(methodOptions);

Multiple Dependencies

When your service needs multiple clients:

function createService(
	{ db, cache, http }, // Dependencies as destructured object
	options = {}, // Service options
) {
	return {
		method(methodOptions) {
			// Uses db, cache, http
		},
	};
}

// Usage
const db = createDbConnection(dbOptions);
const cache = createCacheClient(cacheOptions);
const http = createHttpClient(httpOptions);

const service = createService({ db, cache, http }, serviceOptions);
service.method(methodOptions);

The Mental Model

Think of it as a chain where each link:

Receives a resource from the previous link
Adds its own configuration
Produces something for the next link

createClient(...)  →  createService(client, ...)  →  service.method(...)
     ↑                       ↑                            ↑
 clientOptions          serviceOptions              methodOptions

Benefits

Testability: Inject mock clients easily
Reusability: Share clients across multiple services
Flexibility: Configure each layer independently
Clarity: Clear ownership of configuration at each level

References

See the full articles for more details:

The Universal Factory Function Signature — signature explained in depth
Stop Passing Clients as Arguments — practical guide
The Factory Function Pattern — detailed explanation
Factory Method Patterns — separating options and method patterns

factory-function-composition

When & Why to Use This Skill

Use Cases