Composition Behavior around an existing interface

Decorator

Same interface, another layer.

A command-line diagnostic tool renders a few lines. Now you want line numbers and a readable frame around the result. The caller still needs the same operation: render this block.

Put those behaviors around the text block. Then follow exactly what happens when one wrapper calls another.

TypeScriptGoPythonSame output and wrapper order · across the comparison

01 / Add behavior where the operation already meets its caller

The command should not need a new way to render.

A direct render of diagnostic lines is a good start. Formatting beside that call can be enough too. The pressure appears when the terminal, a saved report, and a CI log all repeat the same surrounding behavior, or need different combinations of it.

You could build separate numbered, framed, and numbered-and-framed renderers. Their responsibilities soon overlap. Instead, let a wrapper receive a TextBlock and offer TextBlock itself. The caller can use the result wherever it used the original block.

A Decorator adds behavior around an object while preserving the interface through which its caller uses it. It holds a collaborator and delegates to it. Because the wrapper offers that same interface, another wrapper can surround it in turn.

This is the object-composition pattern, separate from the @decorator syntax in the ECMAScript decorators proposal.

Caller → TextBlock

Ask for the block.

The command handles the returned lines. It does not choose how numbering or framing is implemented.

Wrapper → inner TextBlock

Add one responsibility.

Numbers prefixes each line. Frame adds borders around the returned lines. Each wrapper still offers render.

Source → result

Return the lines.

The plain block owns the source lines and returns them when asked.

The interface remains compatible; observable behavior can change. Numbering changes each line, while framing changes the surrounding structure. The design needs a contract for those additions.

02 / Start with one wrapper, then compose two

Receive a block. Return a block.

The basic view shows the actual numbering wrapper. It delegates once, transforms the returned lines, and offers the same interface. The practical view adds framing. The plain source that both wrappers surround is in the complete form.

The source accepts at most four printable ASCII lines, each no longer than 32 characters. An empty list remains empty. The source snapshots the input so later caller mutations do not change the block.

Frame measures the lines returned by its inner block, then adds matching edges and padding.

Read in

Compare with

The numbering wrapper offers TextBlock, delegates render once, and prefixes each returned line. The complete view supplies the interface and source.

TypeScriptReading

diagnostics.ts

export function withNumbers(inner: TextBlock): TextBlock {
	return {
		render() {
			return inner.render().map((line, i) => `${i + 1}: ${line}`);
		}
	};
}

GoAlongside

diagnostics.go

type numbered struct{ inner TextBlock }

func WithNumbers(inner TextBlock) TextBlock { return numbered{inner} }
func (n numbered) Render() []string {
	lines := n.inner.Render()
	result := make([]string, len(lines))
	for i, line := range lines {
		result[i] = fmt.Sprintf("%d: %s", i+1, line)
	}
	return result
}

Read complete examples without JavaScript

diagnostics.ts

// Authored CLI output. Strings are printable ASCII; there is no terminal I/O here.
export interface TextBlock {
	render(): string[];
}
export const maxLines = 4;
export const maxLineLength = 32;
export class UnsupportedLines extends Error {
	constructor() {
		super(`Use at most ${maxLines} lines of ${maxLineLength} printable ASCII characters`);
		this.name = 'UnsupportedLines';
	}
}
export function plainText(lines: readonly string[]): TextBlock {
	const printable = (line: string) => line.length <= maxLineLength && /^[\x20-\x7e]*$/.test(line);
	if (lines.length > maxLines || !lines.every(printable)) throw new UnsupportedLines();
	const snapshot = [...lines];
	return { render: () => [...snapshot] };
}

export function withNumbers(inner: TextBlock): TextBlock {
	return {
		render() {
			return inner.render().map((line, i) => `${i + 1}: ${line}`);
		}
	};
}

export function withFrame(inner: TextBlock): TextBlock {
	return {
		render() {
			const lines = inner.render();
			if (lines.length === 0) return []; // No output remains no output.
			const width = Math.max(...lines.map((line) => line.length));
			const edge = '+' + '-'.repeat(width + 2) + '+';
			return [edge, ...lines.map((line) => `| ${line.padEnd(width)} |`), edge];
		}
	};
}
export const stackNames = [
	'bare',
	'numbers',
	'frame',
	'frame-numbers',
	'numbers-frame',
	'numbers-numbers'
] as const;
export type Stack = (typeof stackNames)[number];
export function decorate(source: TextBlock, stack: Stack): TextBlock {
	switch (stack) {
		case 'bare':
			return source;
		case 'numbers':
			return withNumbers(source);
		case 'frame':
			return withFrame(source);
		case 'frame-numbers':
			return withFrame(withNumbers(source));
		case 'numbers-frame':
			return withNumbers(withFrame(source));
		case 'numbers-numbers':
			return withNumbers(withNumbers(source));
	}
}

// A consumer knows TextBlock, regardless of the chosen wrappers.
export function display(block: TextBlock): string {
	return block.render().join('\n');
}
export function runExample(): string[] {
	const source = plainText(['check: links', 'broken: 2']);
	const compared: Stack[] = ['frame-numbers', 'numbers-frame'];
	return compared.map((stack) => `${stack}:\n${display(decorate(source, stack))}`);
}

for (const line of runExample()) console.log(line);

diagnostics.go

package main

import (
	"fmt"
	"strings"
)

type TextBlock interface{ Render() []string }
type plain struct{ lines []string }

const maxLines, maxLineLength = 4, 32

// ErrUnsupportedLines carries the shared message, so it starts with a capital letter.
var ErrUnsupportedLines = fmt.Errorf("Use at most %d lines of %d printable ASCII characters", maxLines, maxLineLength)

func PlainText(lines []string) (TextBlock, error) {
	if len(lines) > maxLines {
		return nil, ErrUnsupportedLines
	}
	for _, line := range lines {
		if len(line) > maxLineLength {
			return nil, ErrUnsupportedLines
		}
		for _, char := range line {
			if char < ' ' || char > '~' {
				return nil, ErrUnsupportedLines
			}
		}
	}
	return plain{append([]string{}, lines...)}, nil
}
func (p plain) Render() []string { return append([]string{}, p.lines...) }

type numbered struct{ inner TextBlock }

func WithNumbers(inner TextBlock) TextBlock { return numbered{inner} }
func (n numbered) Render() []string {
	lines := n.inner.Render()
	result := make([]string, len(lines))
	for i, line := range lines {
		result[i] = fmt.Sprintf("%d: %s", i+1, line)
	}
	return result
}


type framed struct{ inner TextBlock }

func WithFrame(inner TextBlock) TextBlock { return framed{inner} }
func (f framed) Render() []string {
	lines := f.inner.Render()
	if len(lines) == 0 {
		return []string{}
	}
	width := 0
	for _, line := range lines {
		if len(line) > width {
			width = len(line)
		}
	}
	edge := "+" + strings.Repeat("-", width+2) + "+"
	result := []string{edge}
	for _, line := range lines {
		result = append(result, "| "+line+strings.Repeat(" ", width-len(line))+" |")
	}
	return append(result, edge)
}
func Decorate(source TextBlock, stack string) TextBlock {
	switch stack {
	case "numbers":
		return WithNumbers(source)
	case "frame":
		return WithFrame(source)
	case "frame-numbers":
		return WithFrame(WithNumbers(source))
	case "numbers-frame":
		return WithNumbers(WithFrame(source))
	case "numbers-numbers":
		return WithNumbers(WithNumbers(source))
	default:
		return source // The call site supplies one of the documented choices.
	}
}


func Display(block TextBlock) string { return strings.Join(block.Render(), "\n") }
func main() {
	source, err := PlainText([]string{"check: links", "broken: 2"})
	if err != nil {
		panic(err)
	}
	for _, stack := range []string{"frame-numbers", "numbers-frame"} {
		fmt.Printf("%s:\n%s\n", stack, Display(Decorate(source, stack)))
	}
}

diagnostics.py

"""Decorate one diagnostic-block contract with numbering and framing."""

from typing import Literal, Protocol


class TextBlock(Protocol):
    def render(self) -> list[str]: ...


max_lines = 4
max_line_length = 32


class UnsupportedLines(ValueError):
    def __init__(self) -> None:
        super().__init__(
            f"Use at most {max_lines} lines of {max_line_length} printable ASCII characters"
        )


class _PlainText:
    def __init__(self, lines: list[str]) -> None:
        self._lines = list(lines)

    def render(self) -> list[str]:
        return list(self._lines)


def plain_text(lines: list[str]) -> TextBlock:
    def printable(line: str) -> bool:
        return len(line) <= max_line_length and all(32 <= ord(char) <= 126 for char in line)

    if len(lines) > max_lines or not all(printable(line) for line in lines):
        raise UnsupportedLines()
    return _PlainText(lines)


class _Numbers:
    def __init__(self, inner: TextBlock) -> None:
        self._inner = inner

    def render(self) -> list[str]:
        return [f"{index}: {line}" for index, line in enumerate(self._inner.render(), 1)]


def with_numbers(inner: TextBlock) -> TextBlock:
    return _Numbers(inner)



class _Frame:
    def __init__(self, inner: TextBlock) -> None:
        self._inner = inner

    def render(self) -> list[str]:
        lines = self._inner.render()
        if not lines:
            return []
        width = max(map(len, lines))
        edge = f"+{'-' * (width + 2)}+"
        return [edge, *[f"| {line.ljust(width)} |" for line in lines], edge]


def with_frame(inner: TextBlock) -> TextBlock:
    return _Frame(inner)


Stack = Literal[
    "bare", "numbers", "frame", "frame-numbers", "numbers-frame", "numbers-numbers"
]
stack_names: tuple[Stack, ...] = (
    "bare",
    "numbers",
    "frame",
    "frame-numbers",
    "numbers-frame",
    "numbers-numbers",
)


def decorate(source: TextBlock, stack: Stack) -> TextBlock:
    if stack == "bare":
        return source
    if stack == "numbers":
        return with_numbers(source)
    if stack == "frame":
        return with_frame(source)
    if stack == "frame-numbers":
        return with_frame(with_numbers(source))
    if stack == "numbers-frame":
        return with_numbers(with_frame(source))
    return with_numbers(with_numbers(source))



def display(block: TextBlock) -> str:
    return "\n".join(block.render())


def run_example() -> list[str]:
    source = plain_text(["check: links", "broken: 2"])
    return [f"{stack}:\n{display(decorate(source, stack))}" for stack in ("frame-numbers", "numbers-frame")]




if __name__ == "__main__":
    for block in run_example():
        print(block)

Diagnostics.java

import java.util.ArrayList;
import java.util.List;

interface TextBlock {
    List<String> render();
}

final class UnsupportedLines extends IllegalArgumentException {
    UnsupportedLines() {
        super("Use at most 4 lines of 32 printable ASCII characters");
    }
}

final class PlainText implements TextBlock {
    private final List<String> lines;

    PlainText(List<String> lines) {
        if (lines.size() > 4 || lines.stream().anyMatch(line -> line.length() > 32 ||
            line.chars().anyMatch(character -> character < 32 || character > 126))) {
            throw new UnsupportedLines();
        }
        this.lines = new ArrayList<>(lines);
    }

    @Override
    public List<String> render() {
        return new ArrayList<>(lines);
    }
}

final class Numbers implements TextBlock {
    private final TextBlock inner;

    Numbers(TextBlock inner) {
        this.inner = inner;
    }

    @Override
    public List<String> render() {
        List<String> lines = inner.render();
        List<String> result = new ArrayList<>(lines.size());
        for (int index = 0; index < lines.size(); index++) {
            result.add((index + 1) + ": " + lines.get(index));
        }
        return result;
    }
}


final class Frame implements TextBlock {
    private final TextBlock inner;

    Frame(TextBlock inner) {
        this.inner = inner;
    }

    @Override
    public List<String> render() {
        List<String> lines = inner.render();
        if (lines.isEmpty()) return List.of();
        int width = lines.stream().mapToInt(String::length).max().orElse(0);
        String edge = "+" + "-".repeat(width + 2) + "+";
        List<String> result = new ArrayList<>();
        result.add(edge);
        for (String line : lines) result.add("| " + line + " ".repeat(width - line.length()) + " |");
        result.add(edge);
        return result;
    }
}

final class DecoratorFactory {
    private DecoratorFactory() {}

    static TextBlock withNumbers(TextBlock inner) {
        return new Numbers(inner);
    }

    static TextBlock withFrame(TextBlock inner) {
        return new Frame(inner);
    }

    static TextBlock decorate(TextBlock source, String stack) {
        return switch (stack) {
            case "bare" -> source;
            case "numbers" -> withNumbers(source);
            case "frame" -> withFrame(source);
            case "frame-numbers" -> withFrame(withNumbers(source));
            case "numbers-frame" -> withNumbers(withFrame(source));
            case "numbers-numbers" -> withNumbers(withNumbers(source));
            default -> throw new IllegalArgumentException("Unknown stack: " + stack);
        };
    }
}

final class Display {
    private Display() {}

    static String render(TextBlock block) {
        return String.join("\n", block.render());
    }
}

public final class Diagnostics {
    private Diagnostics() {}

    static List<String> runExample() {
        TextBlock source = new PlainText(List.of("check: links", "broken: 2"));
        List<String> output = new ArrayList<>();
        for (String stack : List.of("frame-numbers", "numbers-frame")) {
            output.add(stack + ":\n" + Display.render(DecoratorFactory.decorate(source, stack)));
        }
        return output;
    }

    public static void main(String[] args) {
        for (String block : runExample()) System.out.println(block);
    }
}

diagnostics.rs

pub trait TextBlock {
    fn render(&self) -> Vec<String>;
}
struct Plain {
    lines: Vec<String>,
}
pub fn plain_text(lines: &[String]) -> Result<Box<dyn TextBlock>, &'static str> {
    if lines.len() > 4
        || lines
            .iter()
            .any(|line| line.len() > 32 || !line.bytes().all(|b| (32..=126).contains(&b)))
    {
        return Err("Use at most 4 lines of 32 printable ASCII characters");
    }
    Ok(Box::new(Plain {
        lines: lines.to_vec(),
    }))
}
impl TextBlock for Plain {
    fn render(&self) -> Vec<String> {
        self.lines.clone()
    }
}

struct Numbered {
    inner: Box<dyn TextBlock>,
}
pub fn with_numbers(inner: Box<dyn TextBlock>) -> Box<dyn TextBlock> {
    Box::new(Numbered { inner })
}
impl TextBlock for Numbered {
    fn render(&self) -> Vec<String> {
        self.inner
            .render()
            .iter()
            .enumerate()
            .map(|(i, line)| format!("{}: {}", i + 1, line))
            .collect()
    }
}

struct Framed {
    inner: Box<dyn TextBlock>,
}
pub fn with_frame(inner: Box<dyn TextBlock>) -> Box<dyn TextBlock> {
    Box::new(Framed { inner })
}
impl TextBlock for Framed {
    fn render(&self) -> Vec<String> {
        let lines = self.inner.render();
        if lines.is_empty() {
            return vec![];
        }
        let width = lines.iter().map(|line| line.len()).max().unwrap();
        let edge = format!("+{}+", "-".repeat(width + 2));
        let mut result = vec![edge.clone()];
        result.extend(
            lines
                .iter()
                .map(|line| format!("| {}{} |", line, " ".repeat(width - line.len()))),
        );
        result.push(edge);
        result
    }
}
pub fn decorate(source: Box<dyn TextBlock>, stack: &str) -> Box<dyn TextBlock> {
    match stack {
        "numbers" => with_numbers(source),
        "frame" => with_frame(source),
        "frame-numbers" => with_frame(with_numbers(source)),
        "numbers-frame" => with_numbers(with_frame(source)),
        "numbers-numbers" => with_numbers(with_numbers(source)),
        _ => source, // The call site supplies one of the documented choices.
    }
}

pub fn display(block: &dyn TextBlock) -> String {
    block.render().join("\n")
}
fn main() {
    let lines = vec!["check: links".into(), "broken: 2".into()];
    for stack in ["frame-numbers", "numbers-frame"] {
        let block = decorate(plain_text(&lines).unwrap(), stack);
        println!("{}:\n{}", stack, display(block.as_ref()));
    }
}

Reading the TypeScriptStructural interfaces and a captured collaborator

Both wrapper functions return an object with render. That satisfies TextBlock without a base class. The closure retains inner and delegates to it only when the caller renders.

Numbers maps the inner lines without changing the source. Frame returns an empty list for an empty block and otherwise derives its width from the delegated result. Errors from the inner block propagate; wrappers do not silently replace a failed source.

Reading the GoAn interface field supplies the next layer

Numbered and framed values each implement Render and contain a TextBlock. The inner value is retained and called on every render, so a stateful source would remain shared.

PlainText validates before creating the source and returns an error for unsupported input. Render returns a fresh slice of strings. These wrappers do not need mutable counters, locks, or an error protocol for their pure formatting work.

Reading the PythonProtocols and explicit wrapper objects

Python’s Protocol describes the small render contract without requiring a shared base class. Each wrapper retains a TextBlock and calls its render method only when the caller renders, so a stateful source stays observable.

The implementation uses private classes because Python’s function-decorator syntax is a different language feature. The object relationship is the same: a wrapper offers the contract, delegates, and returns a transformed list.

03 / Follow the returned lines

The outer wrapper sees the inner operation.

The source starts with two diagnostic lines. With Frame outside Numbers, the border surrounds already numbered content. Watch the example, step through each composition, then use Try it to edit the lines and wrapper order.

Swap the wrappers. Numbers now sees the frame and prefixes its top and bottom borders. The command still receives a TextBlock, but the returned lines describe a different composition.

Playback controls

Decorator

The order changes the output.

Caller’s render() →Source

Returned diagnostic block

check: links
broken: 2

Source: "check: links" · "broken: 2"

01/ 04

Plain diagnostic

Keep the same operation.

The caller asks render() for two diagnostic lines. No wrapper is present yet.

Reduced motion: choose a scene to see its completed state.

Read this scene

The caller asks render() for two diagnostic lines. No wrapper is present yet.

bare: 2 returned lines.

check: links
broken: 2

Try the example by reading

Numbers adds prefixes to the lines returned by its collaborator. Frame adds border lines. Frame(Numbers(Source)) keeps numbers inside the border; Numbers(Frame(Source)) numbers the border too.

Which lines receive numbers?

Change the text or wrapper order, predict the output, then render. The leftmost wrapper receives the caller’s request first.

Caller’s render() →Choose and render

Returned diagnostic block

No output yet

Source: not rendered

No render yet. Editing inputs clears the previous result.

Order dependence is a normal part of composition: layers need not commute. If two layers depend on each other’s hidden internal state, a combined operation may be easier to reason about.

04 / Choose the boundary before choosing the wrapper

What should the frame contain?

“Add numbering and framing” leaves a decision open. State whether the frame should contain the prefixes. Then choose the stack that expresses it.

Reasoning and a stopping pointAlso available without JavaScript

Frame(Numbers(source)) formats the numbered content as one block. Numbers(Frame(source)) numbers the border as well. Both are useful compositions with different output boundaries.

Adding another formatting wrapper can change the output again. If you only need one fixed presentation, a direct formatter may be clearer than a reusable stack.

Leave yourself a note

What does each layer add? Which one gets called again? Which result, error, and lifetime guarantees still belong to the inner block?

This reflection stays on this page; nothing is saved or graded.

05 / Another object, with a reference to the same collaborator

Wrapping is not copying.

Constructing Frame(source) creates a wrapper; it does not make a fresh source. Two wrappers around the same mutable block can share its state. Here each render returns a fresh array.

Rendering does not consume the plain source, so TypeScript, Go, and Python reuse one source for both comparisons. Every version shows the same independent output values. A stateful or consumable source would need a separate lifetime contract.

The target interface is deliberately small. It exposes render, not every property of the concrete source. Additional methods such as close, flush, subscribe, or seek do not become available just because the wrapper can render.

Who closes a wrapped resource?Decide ownership separately from delegation

A wrapper can own its inner resource, borrow it, or share it under a separate owner. State whether closing the wrapper closes the resource, whether other callers can still use it, and what happens to buffered work. A same-shaped render method answers none of those questions.

Here the source and wrappers hold only memory, so no close protocol is supplied.

06 / Give the assembled stack a visible owner

Setup chooses policy; the command uses the result.

Application setup chooses a text source, adds the required wrappers, and passes the resulting TextBlock to the command. Unit tests can supply the plain block directly. The caller remains unaware of the selected formatting stack.

Suppose the team wants a compact output for terminals and a framed output for reports. Make the order explicit. Silently adding another numbering wrapper can duplicate prefixes; silently moving Frame changes which lines determine its width.

Change	Decision it requires
Support Unicode or terminal escape codes	Measure display columns and preserve control sequences deliberately; this ASCII example counts characters.
Add another formatting layer	State whether it sees source lines or already formatted output. Choose the order at setup.
Use a live source	Decide when rendering reads new state, how errors reach callers, and who owns any resources.
Cache a render	Define freshness and invalidation. Holding an inner block does not cache its output.

Build UIs?Every component that renders lines it was handed trusts a stack it cannot see, and one day you will assemble that stack yourself.

Where it already is in your components

A panel that renders block.render() as a list of lines does not know whether those lines were numbered, framed, or both. It asks the interface and draws what comes back. That is the caller’s side of this lesson: the component depends on the interface, and whoever built the block chose the layers.

When you have to own it

Now the diagnostics appear in a browser panel as well as the terminal. Assemble the stack where the panel is set up, pass the finished block in, and display its returned lines as text in a preformatted element, with whitespace intact and horizontal scrolling for wider output. The component does not reproduce the numbering and framing rules. Text stays text, including angle brackets; it is not interpreted as HTML. The lesson’s lab works this way. A one-off component formatter can be simpler when no other consumer needs the interface.

07 / Find the same relationship in familiar APIs

A text block can add behavior and remain a text block.

Go’s io.TeeReader takes a Reader and returns a Reader that also writes the bytes it reads to a Writer. The write completes as part of the read, and a write failure can become a read error. Adding a side effect changes the operation’s failure contract too.

Go’s bufio.NewReader adds buffering around an io.Reader and returns a *bufio.Reader, itself an io.Reader. Its state matters even when the caller recognizes the interface: discarding a buffer or bypassing it can lose access to unread data.

Both comparisons rest on documented behavior.

What about @decorators?Related wrapping techniques, a different level of description

The ECMAScript decorators proposal, which TypeScript 5.0 implements, customizes classes and members with @name annotations. TypeScript’s older experimentalDecorators flag enables a separate, incompatible form of the idea that frameworks such as NestJS still rely on. A method decorator can install a logging wrapper, but the syntax can also serve other purposes. The object pattern here concerns a runtime object receiving and delegating to another object through a compatible interface.

Recognizing an @ annotation alone does not establish the responsibilities, order, or lifecycle of an object-decorator stack.

08 / Take the idea with you

What does this layer add, and what does it preserve?

Explain the stack without saying “Decorator”: the caller still uses this interface; this layer adds this behavior; it delegates here; this result comes back. Then swap two layers and name what would change.

Use a decorator when surrounding behavior recurs, varies independently, and belongs at a stable interface. Keep a direct call or an explicit before/after statement when there is only one place that needs it. Prefer a named combined operation when the layers cannot explain their rules independently.

Connections to follow nextRelated lessons

Adapter translates an existing interface into the one a caller needs. Decorator starts with a compatible interface and adds behavior around it. Facade presents a convenient entry point to a subsystem. Strategy supplies a chosen policy to a consumer.

Proxy concerns access to a represented object. Proxy and Decorator can have very similar code; intent and contract help explain the distinction. One operational tie-breaker: a decorator always performs the operation it wraps and adds around it, so Numbers never withholds a render. A proxy may refuse, defer, or substitute that operation. A caching wrapper may be discussed in either context. A diagram alone does not settle the name.

Composition over inheritance gives a broader view of supplying collaborators.