Flyweight

Two kinds of state: intrinsic vs extrinsic

The whole pattern is one act of sorting. Take everything an object stores and split it into two piles:

• Intrinsic state — the part that is the same across many objects and doesn't change: the sprite, the color, the texture, the name Oak. This lives inside the flyweight (TreeType) and is shared by everyone. Intrinsic = belongs to the type.
• Extrinsic state — the part that is unique to each object: this tree's x and y. This is kept outside the flyweight — stored in the small per-tree object, or passed in as method arguments (type.draw(x, y)). Extrinsic = belongs to the instance.

A quick self-test for any field: if I made 10,000 of these, how many distinct values would this field have? Three values (species sprite) → intrinsic, share it. Ten thousand values (position) → extrinsic, keep it per object. Get this split right and the rest of the pattern writes itself.

The factory cache: build each flyweight once

Nobody creates a TreeType directly. Everyone asks a `TreeFactory`, which keeps a cache (a map from a key like "Oak" to the flyweight). The first request for Oak builds the heavy TreeType and stores it; every later request returns the already-built, shared one. Plant 10,000 trees across 3 species and the factory constructs exactly 3 heavy objects — the other 9,997 requests are cache hits. It's the same 'check the cache, build once, reuse forever' move a Singleton's getInstance() makes, except the factory manages a family of instances, one per key.

class TreeFactory {
  private static cache = new Map<string, TreeType>();

  static get(name: string, color: string, sprite: string): TreeType {
    let type = TreeFactory.cache.get(name);
    if (!type) {                                  // first time this species?
      type = new TreeType(name, color, sprite);   // build the heavy 2 KB once
      TreeFactory.cache.set(name, type);
    }
    return type;                                  // everyone shares this one
  }
}

Why flyweights MUST be immutable

One TreeType is referenced by thousands of trees at once. If any code could write oakType.color = "purple", every oak in the forest would silently turn purple — a change made 'to one tree' would hit thousands of unrelated ones. That's why flyweights are immutable: all fields set in the constructor, no setters, read-only forever. Immutability is what makes sharing safe — this is the same reasoning behind value objects in [[immutability-and-value-objects]]. If a value needs to differ per tree or change over time, it isn't intrinsic — move it out to extrinsic state.

The memory math

• Without Flyweight: 10,000 trees × 2 KB each ≈ 20 MB, and it grows linearly — every new tree costs another full 2 KB.
• With Flyweight: 3 shared TreeTypes × 2 KB + 10,000 trees × ~40 B (an x, a y, a reference) ≈ 6 KB + 400 KB ≈ 0.4 MB — roughly 50× less.
• The win scales with count × duplication: the heavy cost is paid per species (3, fixed), while the per-tree cost is tiny. Doubling the forest adds ~0.4 MB, not ~20 MB.

Where you meet this in the real world

• Text editors — one shared glyph object per distinct character; each character position in the document stores only which glyph plus where it sits. A million-character file needs ~100 glyph objects, not a million.
• String interning — "hello" written in two places points at one shared string object; the runtime keeps an intern table (a flyweight factory for strings).
• `Integer.valueOf()` in Java — values from −128 to 127 come from a shared cache, so boxing small numbers doesn't allocate.
• Browsers — thousands of DOM nodes with identical styling share one computed-style object instead of each storing its own copy.
• Games — particles, bullets, tiles and props: thousands of instances, a handful of shared sprite/mesh 'types'. Flyweight is the standard trick.

Reach for Flyweight when all three line up

• Huge object counts — thousands to millions of instances alive at the same time: game entities, characters in a document, map markers, table cells.
• Heavy, repeated state — a big chunk of each object (sprite, glyph, style, config blob) is duplicated across many of them, with far fewer distinct values than instances.
• The shared part can be immutable — you can freeze the repeated chunk and pass the changing bits (position, selection, velocity) in from outside.
• Memory is actually the constraint — profiling (or arithmetic like 10,000 × 2 KB) shows the duplication is what's hurting you.

Skip it when

• Object counts are modest — a few hundred objects duplicating 2 KB is ~half a megabyte; the pattern's complexity isn't buying anything.
• State is mostly unique — if almost every field differs per instance, there's nothing worth sharing; a flyweight of one field saves nothing.
• The 'shared' part must mutate — if per-object changes to that data are needed, sharing it is a bug factory, not an optimization.
• You haven't measured — Flyweight splits one simple class into three parts (flyweight, factory, context). Don't pay that readability cost before a profile or back-of-envelope math shows a real memory problem.