How a function reports failure.

export function byThrow(condition: Condition): Discount {
	const failure = failureFor(condition);
	if (failure) throw new ReportedFailure(failure);
	return discount();
}

export function byNullable(condition: Condition): Discount | undefined {
	return failureFor(condition) ? undefined : discount();
}

func Lookup(condition Condition) (Discount, error) {
	switch condition {
	case Valid:
		return Discount{Code: "SAVE10", Percent: 10}, nil
	case NotFound:
		return Discount{}, Failure{Kind: FailureNotFound, Message: "That code does not exist."}
	case Invalid:
		return Discount{}, Failure{Kind: FailureInvalid, Message: "Enter a valid discount code."}
	case Unavailable:
		return Discount{}, Failure{Kind: FailureUnavailable, RetryAfterSeconds: 5, Message: "Discount service is temporarily unavailable."}
	default:
		return Discount{}, errors.New("unknown lookup condition")
	}
}

export type Condition = 'valid' | 'not-found' | 'invalid' | 'unavailable';
export type Channel = 'throw' | 'nullable' | 'tuple' | 'result';

export type Discount = Readonly<{
	code: string;
	percent: number;
}>;

export type Failure =
	| { kind: 'not-found'; message: string }
	| { kind: 'invalid'; field: 'code'; message: string }
	| { kind: 'unavailable'; retryAfterSeconds: number; message: string };

export type Result<T, E> = { ok: true; value: T } | { ok: false; error: E };
export type Observation = Readonly<{
	channel: Channel;
	condition: Condition;
	path: 'success' | 'failure' | 'ambiguous';
	action:
		'apply discount' | 'show form error' | 'offer retry' | 'show no discount' | 'escalate defect';
	detail: string;
}>;

function discount(): Discount {
	return { code: 'SAVE10', percent: 10 };
}

function failureFor(condition: Condition): Failure | null {
	switch (condition) {
		case 'not-found':
			return { kind: 'not-found', message: 'That code does not exist.' };
		case 'invalid':
			return { kind: 'invalid', field: 'code', message: 'Enter a valid discount code.' };
		case 'unavailable':
			return {
				kind: 'unavailable',
				retryAfterSeconds: 5,
				message: 'Discount service is temporarily unavailable.'
			};
		case 'valid':
			return null;
		default:
			// A condition outside the contract is a defect, not a fourth user outcome.
			throw new Error('unknown lookup condition');
	}
}

export function byThrow(condition: Condition): Discount {
	const failure = failureFor(condition);
	if (failure) throw new ReportedFailure(failure);
	return discount();
}

export function byNullable(condition: Condition): Discount | undefined {
	return failureFor(condition) ? undefined : discount();
}

export class ReportedFailure extends Error {
	readonly failure: Failure;

	constructor(failure: Failure) {
		super(failure.message);
		this.name = 'ReportedFailure';
		this.failure = failure;
	}
}

export function byTuple(condition: Condition): [Discount | null, Failure | null] {
	const failure = failureFor(condition);
	return failure ? [null, failure] : [discount(), null];
}

export function byResult(condition: Condition): Result<Discount, Failure> {
	// failureFor throws for a condition outside the contract: a defect escapes
	// instead of becoming a Failure the caller would treat as a user outcome.
	const failure = failureFor(condition);
	return failure ? { ok: false, error: failure } : { ok: true, value: discount() };
}

function actionFor(failure: Failure): Observation['action'] {
	return failure.kind === 'not-found'
		? 'show no discount'
		: failure.kind === 'invalid'
			? 'show form error'
			: 'offer retry';
}

function failureObservation(channel: Channel, condition: Condition, failure: Failure): Observation {
	return {
		channel,
		condition,
		path: 'failure',
		action: actionFor(failure),
		detail:
			failure.kind === 'unavailable'
				? `${failure.message} Retry after ${failure.retryAfterSeconds}s.`
				: failure.message
	};
}

export function observe(channel: Channel, condition: Condition): Observation {
	if (channel === 'throw') {
		try {
			const value = byThrow(condition);
			return {
				channel,
				condition,
				path: 'success',
				action: 'apply discount',
				detail: `${value.code} applies ${value.percent}% off.`
			};
		} catch (error) {
			if (error instanceof ReportedFailure)
				return failureObservation(channel, condition, error.failure);
			return {
				channel,
				condition,
				path: 'ambiguous',
				action: 'escalate defect',
				detail: 'An unexpected error escaped; the caller must not treat it as a normal outcome.'
			};
		}
	}

	if (channel === 'nullable') {
		const value = byNullable(condition);
		return value
			? {
					channel,
					condition,
					path: 'success',
					action: 'apply discount',
					detail: `${value.code} applies ${value.percent}% off.`
				}
			: {
					channel,
					condition,
					path: 'ambiguous',
					action: 'show no discount',
					detail:
						'undefined says that no discount arrived; it cannot distinguish invalid, missing, and unavailable.'
				};
	}

	if (channel === 'tuple') {
		const [value, failure] = byTuple(condition);
		if (failure) return failureObservation(channel, condition, failure);
		return {
			channel,
			condition,
			path: 'success',
			action: 'apply discount',
			detail: `${value!.code} applies ${value!.percent}% off.`
		};
	}

	const result = byResult(condition);
	return result.ok
		? {
				channel,
				condition,
				path: 'success',
				action: 'apply discount',
				detail: `${result.value.code} applies ${result.value.percent}% off.`
			}
		: failureObservation(channel, condition, result.error);
}

export function runExample() {
	return (['valid', 'invalid', 'unavailable'] as Condition[]).map((condition) => ({
		condition,
		throw: observe('throw', condition),
		nullable: observe('nullable', condition),
		tuple: observe('tuple', condition),
		result: observe('result', condition)
	}));
}

console.log(JSON.stringify(runExample(), null, 2));

package main

import (
	"encoding/json"
	"errors"
	"fmt"
)

type Condition string

const (
	Valid       Condition = "valid"
	NotFound    Condition = "not-found"
	Invalid     Condition = "invalid"
	Unavailable Condition = "unavailable"
)

type Discount struct {
	Code    string `json:"code"`
	Percent int    `json:"percent"`
}

type FailureKind string

const (
	FailureNotFound    FailureKind = "not-found"
	FailureInvalid     FailureKind = "invalid"
	FailureUnavailable FailureKind = "unavailable"
)

type Failure struct {
	Kind              FailureKind `json:"kind"`
	Message           string      `json:"message"`
	RetryAfterSeconds int         `json:"retryAfterSeconds,omitempty"`
}

func (f Failure) Error() string { return f.Message }

func Lookup(condition Condition) (Discount, error) {
	switch condition {
	case Valid:
		return Discount{Code: "SAVE10", Percent: 10}, nil
	case NotFound:
		return Discount{}, Failure{Kind: FailureNotFound, Message: "That code does not exist."}
	case Invalid:
		return Discount{}, Failure{Kind: FailureInvalid, Message: "Enter a valid discount code."}
	case Unavailable:
		return Discount{}, Failure{Kind: FailureUnavailable, RetryAfterSeconds: 5, Message: "Discount service is temporarily unavailable."}
	default:
		return Discount{}, errors.New("unknown lookup condition")
	}
}


type Result[T any] struct {
	Value   T
	Failure *Failure
}

func LookupResult(condition Condition) Result[Discount] {
	value, err := Lookup(condition)
	if err == nil {
		return Result[Discount]{Value: value}
	}
	var failure Failure
	if errors.As(err, &failure) {
		return Result[Discount]{Failure: &failure}
	}
	// Any other error is a defect, not a fourth user outcome: it must not
	// become a form error or "no discount", so it escapes the result.
	panic(fmt.Errorf("lookup defect: %w", err))
}


func Example() map[string]any {
	value, err := Lookup(Unavailable)
	var failure Failure
	_ = errors.As(err, &failure)
	result := LookupResult(Unavailable)
	return map[string]any{
		"lookupError":        failure.Kind,
		"retryAfterSeconds":  failure.RetryAfterSeconds,
		"resultHasValue":     result.Failure == nil,
		"validValue":         mustLookup(Valid),
		"tupleRequiresCheck": value == (Discount{}),
	}
}

func mustLookup(condition Condition) Discount {
	value, err := Lookup(condition)
	if err != nil {
		panic(err)
	}
	return value
}


func main() {
	encoded, err := json.MarshalIndent(Example(), "", "  ")
	if err != nil {
		panic(err)
	}
	fmt.Println(string(encoded))
}