effect-context-witness

Context Witness Pattern

Choose between witness (existence) and capability (behavior) patterns for Context.Service definitions.

Coupling: Hard vs Soft

Some coupling is necessary and good - but move it from hard to soft coupling.

Hard Coupling (Schema)

Field exists in the schema - tightly coupled to domain model:

import { Schema } from 'effect';

// ❌ HARD COUPLING - Serial is part of the schema
export const PaymentIntent = Schema.Struct({
	id: Schema.String,
	serial: Schema.String, // In schema = hard coupled
	amount: Schema.BigInt
});

// Every PaymentIntent MUST have a serial
// Serialization/validation requires serial
// Cannot create without providing serial
// Schema change needed to remove/change serial

Soft Coupling (Witness)

Field removed from schema, only injected in code:

import { Schema, Context, Effect, Logger } from 'effect';

declare const generateId: () => string;

// ✅ SOFT COUPLING - Serial not in schema
export const PaymentIntent = Schema.Struct({
	id: Schema.String,
	amount: Schema.BigInt
	// No serial field!
});

// Serial is a witness - required but injected via Context
class Serial extends Context.Service<Serial, string>()('Serial') {}

const createPaymentIntent = (amount: bigint) =>
	Effect.gen(function* () {
		const serial = yield* Serial; // Injected from context

		// Use serial in business logic, logging, etc.
		// but it's not part of the persisted data
		yield* Logger.info(`Creating payment intent ${serial}`);

		return PaymentIntent.make({ id: generateId(), amount });
	});

// Type: Effect<PaymentIntent, never, Serial>

Key insight: schema (hard coupling) => witness (soft coupling)

By removing the field from the schema and injecting it only where needed, you:

• Keep domain models minimal
• Avoid unnecessary persistence
• Easy to test (provide test serial)
• Easy to remove/change (just change injection)
• Explicit dependencies in type signature

When to use witnesses: