Wrappers: adapter, decorator, proxy, facade

A phone owner fits a few accessories to her phone; each one sits between her and something else.

With the phone	In code
a USB-C to 3.5 mm dongle lets her old wired headphones work with a phone that has no headphone jack; the headphones never change	an adapter: the client keeps its interface (step 2)
a case keeps every button and port where it was and adds grip; a wallet case over it adds card slots	decorators, stacked in the order she fits them (steps 4–5)
her case leaves her partner's identical phone bare	a decorator object wraps one instance (step 6)
the lock screen looks like the phone and lets her through only after the PIN	a proxy controls access (step 7)
the car dashboard's phone mode shows four big buttons; to change a setting she picks up the phone itself	a facade offers less and seals nothing (steps 9–10)
the maker's engraving on the back of every phone of that model, done at the factory before any is sold	an @ decorator: applied once, to the class (steps 11–12)

In real terms: a wrapper is an object the caller holds in place of another; whose interface it implements, and whether every call passes through, tells you which one it is.

Breaks down when: a case makes the phone too thick for the old car cradle. A decorator in code keeps the interface exactly; any caller of the original takes it.

Contrasting case: a phone used bare, because nothing needs converting, adding or guarding: when an object already has the interface you need, wrap nothing.

4.1 ExamHall EXH-2640: the proctoring vendor's SDK behind VideoSession

ExamHall's ProctorRoom is written against its own VideoSession. The proctoring vendor's SDK speaks another interface:

// video-session.ts (ExamHall's own interface; ProctorRoom calls only this)
export interface VideoSession { start(seat: string, minutes: number): void; isLive(seat: string): boolean }

// proctorcam.ts (the vendor's SDK, as its declarations show it)
export declare class ProctorCam {
  openFeed(opts: { userRef: string; maxSeconds: number }): void;
  feedState(userRef: string): 'LIVE' | 'ENDED';
}

// video-vendor-adapter.ts
import type { VideoSession } from './video-session';
import type { ProctorCam } from './proctorcam';
export class VideoVendorAdapter implements VideoSession {
  constructor(private cam: ProctorCam) {}
  start(seat: string, minutes: number) { this.cam.openFeed({ userRef: seat, maxSeconds: minutes * 60 }); }
  isLive(seat: string) { return this.cam.feedState(seat) === 'LIVE'; }
}

4.1 EXH-2640 new ProctorRoom(cam) with the vendor's ProctorCam as it is: tsc TS2345 main.ts:4
4.1 new ProctorRoom(new VideoVendorAdapter(cam)): tsc no diagnostics · a 90-minute seat opens a feed of 5400 s · isLive true · room.ts unchanged

The SDK object does not fit VideoSession, so tsc refuses it. The adapter implements VideoSession, turns minutes into seconds and the feed state into a yes or no, and ProctorRoom stays as it was (step 2).

4.2 ExamHall EXH-2641 and MR !2940: a caching proxy for the question bank

Every candidate's screen read each question through RemoteBank, one fetch per question:

// question-bank.ts
export interface QuestionBank { question(id: string): string }
export class RemoteBank implements QuestionBank {
  static fetches = 0;
  question(id: string) { RemoteBank.fetches++; return `text of ${id}`; }   // one HTTP fetch each
}

// cached-bank.ts (MR !2940)
import { RemoteBank, type QuestionBank } from './question-bank';
export class CachedBank implements QuestionBank {
  private remote = new RemoteBank();
  private texts = new Map<string, string>();
  question(id: string) {
    if (!this.texts.has(id)) this.texts.set(id, this.remote.question(id));
    return this.texts.get(id)!;
  }
}

4.2 EXH-2641 120 candidates open the same 3-question paper through RemoteBank: fetches 360
4.2 MR !2940 the same through one CachedBank, passed as a QuestionBank: tsc no diagnostics · fetches 3 · each candidate's texts the same

MR !2940 passes one CachedBank wherever a QuestionBank was expected. The screens did not change and read the same questions, but only the first request for each question reaches the remote bank (steps 7–8). How long a cached text may live is cache policy, owned by the cache-* packs.

4.3 When TypeScript runs a decorator

ExamHall's grader tags grade with two decorator factories. The run records each step:

// tags.ts (standard decorators: TypeScript 6.0.3 with experimentalDecorators off)
import type { Grader } from './grader';
export const order: string[] = [];
export function tag(name: string) {
  order.push(`factory ${name}`);
  return (method: (this: Grader) => void, _ctx: ClassMethodDecoratorContext<Grader>) => { order.push(`apply ${name}`); return method; };
}

// grader.ts
import { tag, order } from './tags';
export class Grader {
  @tag('outer') @tag('inner') grade(): void {}
}
order.push('class defined');

// main.ts
import { Grader } from './grader';
import { order } from './tags';
order.push('main starts');
new Grader();
new Grader();
order.push('two graders made');
console.log(order.join(' · '));

4.3 standard decorators: factory outer · factory inner · apply inner · apply outer · class defined · main starts · two graders made
4.3 legacy decorators (experimentalDecorators, (target, key, descriptor) signatures): the same order

Both factories, then both decorators, ran while grader.ts was being loaded, before main.ts made a grader, and making two graders ran none of them again (step 11). The legacy kind, compiled with experimentalDecorators, gives the same order (step 14).