Flyweight Pattern: One Jersey Design, a Whole Team of Players

🏏 One jersey design, eleven players, lakhs of fans

Meet Kiran, who runs a small cricket fan shop in Pune. World Cup season is coming, and his best seller is the Indian team jersey with custom name printing. His younger sister Anjali is a CSE student who helps him with the shop's billing software during holidays — and she is about to find a serious bug in it.

First, think about how the jersey itself comes to exist. The design team works for months on it: the exact shade of blue, the tricolour strokes, the sponsor logos, the fabric pattern. That design is heavy work, and it is done once.

Now the team needs jerseys for Kohli, Bumrah, Gill, and the rest. Does the factory design a brand new jersey from zero for every player? Of course not. Every player's jersey uses the same shared design. Only two small things change per player: the name on the back and the number.

Go one step further, to Kiran's shop. Lakhs of fans buy the same jersey, each printing their own name on the back. One design; lakhs of jerseys. The factory stores one master design file, not lakhs of copies of it.

Split a jersey into its two parts:

• The shared part — colour, pattern, logos, fabric. Same for everyone. Heavy to create. Stored once.
• The unique part — name and number. Different for everyone. Tiny. Stored per person.

Now imagine if the factory was foolish and saved a full copy of the entire multi-GB design file inside every jersey record. Ten lakh jerseys, ten lakh copies of the same design. Storage would explode for no reason at all.

Anjali's discovery: Kiran's billing software was doing exactly this foolish thing with objects in memory — every sold-jersey record carried its own full copy of the design images. The Flyweight pattern is the factory's common sense applied to code: store the heavy shared part once, keep only the tiny unique part per object, and let everyone point to the shared part.

Notice the last section. The record saved per sale is tiny — a name, a number, and a pointer. The heavy design is fetched, never copied. Hold that picture; the whole pattern is in it.

What is the Flyweight pattern?

Flyweight is a structural design pattern that lets you fit far more objects into the same amount of RAM. It works by splitting an object's data into two groups and treating them differently:

• Intrinsic state — the data that is the same across many objects and never changes (the jersey design). This goes inside a shared object called the flyweight, stored exactly once.
• Extrinsic state — the data that is unique to each object (player name, number). This stays outside the flyweight, kept in a small context object or passed into methods as parameters.

A flyweight factory hands out flyweights. When two pieces of code ask for "the India ODI jersey design", the factory gives both of them the same object from its cache. That is why the pattern's other name is Cache.

The two kinds of state, side by side — this table is the entire pattern:

One rule is absolutely non-negotiable: the flyweight must be immutable (read-only after creation). One object is shared by thousands of contexts; if anyone could scribble on it, everyone's data would change at once.

College corner — the formal split: intrinsic state is context-free information: it depends only on what the thing is ("India ODI jersey"), never on where or how it is used. Extrinsic state is context-dependent: it changes per use site (whose back, which number, which shelf). The pattern works because context-free data can be safely aliased — many references to one immutable object are indistinguishable from many copies, except in the memory bill. This is the same insight behind hash consing in compilers and functional languages, where identical immutable subtrees are stored once and compared by pointer. The moment data becomes mutable or context-dependent, aliasing becomes visible (one writer changes everyone's view) and the trick collapses. That is why immutability is not a style preference here — it is the load-bearing wall.

The problem it solves

Here is the shape of the bug Anjali found. The shop's system keeps an object for every jersey ever sold, and the naive class stores everything in every object:

// The naive way: every jersey carries the FULL design
class Jersey {
  constructor(
    public fanName: string,        // unique  — fine
    public num: number,            // unique  — fine
    public teamName: string,       // same for lakhs of jerseys
    public colorScheme: string,    // same for lakhs of jerseys
    public logoImage: Uint8Array,  // ~200 KB — same for lakhs of jerseys!
    public fabricPattern: Uint8Array, // ~300 KB — same again!
  ) {}
}

Sell 10 lakh (1,000,000) jerseys of one design. The name and number are genuinely different in each object — that costs almost nothing. But the half-megabyte of logo and fabric data is identical in every single object. The maths is brutal:

• 1,000,000 jerseys × ~500 KB of duplicated design data ≈ 500 GB of RAM
• Useful unique data: 1,000,000 × a few dozen bytes ≈ a few MB

The program crashes with an out-of-memory error, and 99.99% of what filled the memory was the same bitmap stored a million times. Nothing is wrong with the logic — only with the duplication.

After the fix, memory cost is roughly (10 lakh tiny contexts) + (1 design × 500 KB). From 500 GB down to a few MB. Same forest of objects, a fraction of the RAM.

Watch what the two roads look like as the shop grows. The naive line climbs in a straight, deadly slope; the flyweight line barely moves, because only the tiny per-jersey part grows:

At 100k jerseys the naive approach wants about 50 GB just for duplicated design bytes; the flyweight approach needs single-digit MB — the one design plus 100k tiny records. The gap widens forever as you scale. That widening gap is the whole reason this pattern exists.

College corner — do the memory math before you build: the general formula is simple. Naive cost ≈ N × (unique bytes + shared bytes). Flyweight cost ≈ N × (unique bytes + one pointer) + D × shared bytes, where N is the object count and D is the number of distinct designs. The saving factor is roughly (shared bytes) ÷ (unique bytes + 8) when D is small. For our jerseys: shared ≈ 500,000 bytes, unique ≈ 50 bytes, so the saving is around 10,000×. But flip the numbers — shared 50 bytes, unique 500 KB — and the pattern saves almost nothing while adding a factory, a cache, and indirection on every call. Run this two-line calculation before writing any flyweight code; it tells you honestly whether the pattern will pay.

⚙️ How it works, step by step

1. Sort the fields into two buckets. For each field of the heavy class ask: "Is this identical across many objects, and constant?" If yes → intrinsic. If it differs per object → extrinsic. (Design = intrinsic; name and number = extrinsic.)
2. Build the flyweight class with intrinsic fields only. Set them in the constructor and never expose any setter. The flyweight is immutable.
3. Change methods to accept extrinsic state as parameters. A method that used to read this.fanName now takes fanName as an argument: print(fanName, num).
4. Build a flyweight factory with a cache. It keeps a map keyed by intrinsic state ("india-odi-2026" → flyweight). On request, it returns the cached object if it exists, otherwise creates it once and caches it.
5. Never call the flyweight constructor directly from client code. Only the factory does that — this is what guarantees actual sharing.
6. Make a small context class holding the extrinsic fields plus a reference to the shared flyweight. Many contexts, few flyweights.

Read it as a story: the Shop (client) asks the DesignFactory for a design. The factory returns a shared, immutable JerseyDesign. The shop then creates a tiny Jersey context holding only the fan's name, number, and a pointer to that shared design.

The factory's cache has a tiny life cycle of its own, and it is worth drawing, because every flyweight bug lives somewhere in this diagram:

The expensive Creating state is visited once per distinct design, no matter how many thousand requests arrive. Every later request takes the cheap Cached → Cached loop. If your logs show Creating firing again and again for the same design, someone is bypassing the factory.

Real-life code example

Full jersey shop in TypeScript. Note the counter at the end — it proves the memory saving by printing how many heavy objects actually exist.

// ----- The Flyweight: intrinsic (shared, immutable) state only -----
class JerseyDesign {
  // 'readonly' everywhere — a flyweight must never change.
  constructor(
    public readonly team: string,
    public readonly kit: string,          // "ODI" | "Test" | "T20"
    public readonly colorScheme: string,
    public readonly designData: string,   // imagine ~500 KB of image bytes
  ) {
    JerseyDesign.created++;               // count heavy objects made
    console.log(`  (heavy work) Designing ${team} ${kit} jersey...`);
  }
 
  static created = 0;
 
  // Extrinsic state (fanName, num) is PASSED IN, never stored here.
  print(fanName: string, num: number): void {
    console.log(
      `${this.team} ${this.kit} [${this.colorScheme}] -> ${fanName} #${num}`
    );
  }
}
 
// ----- The Flyweight Factory: one cache for the whole shop -----
class DesignFactory {
  private cache = new Map<string, JerseyDesign>();
 
  getDesign(team: string, kit: string, colors: string): JerseyDesign {
    const key = `${team}-${kit}`;
    if (!this.cache.has(key)) {
      // Heavy creation happens only ONCE per distinct design.
      this.cache.set(
        key,
        new JerseyDesign(team, kit, colors, "<500KB of image data>")
      );
    }
    return this.cache.get(key)!;          // everyone shares THIS object
  }
 
  get designCount(): number {
    return this.cache.size;
  }
}
 
// ----- The Context: tiny, unique, one per sold jersey -----
class Jersey {
  constructor(
    private fanName: string,              // extrinsic
    private num: number,                  // extrinsic
    private design: JerseyDesign,         // reference to SHARED flyweight
  ) {}
 
  print(): void {
    this.design.print(this.fanName, this.num);
  }
}
 
// ----- The client: Kiran's shop sells thousands of jerseys -----
const factory = new DesignFactory();
const sold: Jersey[] = [];
 
const fans = ["Aarav", "Diya", "Kabir", "Meera", "Ishaan", "Anaya"];
 
// Sell 10,000 jerseys across only 3 designs.
for (let i = 0; i < 10_000; i++) {
  const fan = fans[i % fans.length] + "-" + i;
  const kit = ["ODI", "Test", "T20"][i % 3];
  const design = factory.getDesign("India", kit, "Blue/Tricolour");
  sold.push(new Jersey(fan, (i % 99) + 1, design));
}
 
// Print a small sample.
sold[0].print();
sold[1].print();
sold[2].print();
 
// ----- The PROOF: shared objects vs total objects -----
console.log("-".repeat(50));
console.log(`Total jerseys sold (contexts) : ${sold.length}`);
console.log(`Heavy design objects created  : ${JerseyDesign.created}`);
console.log(`Designs in factory cache      : ${factory.designCount}`);
console.log(
  `Memory for designs: ~${JerseyDesign.created * 500} KB instead of ~${
    sold.length * 500
  } KB`
);

Output:

  (heavy work) Designing India ODI jersey...
  (heavy work) Designing India Test jersey...
  (heavy work) Designing India T20 jersey...
India ODI [Blue/Tricolour] -> Aarav-0 #1
India Test [Blue/Tricolour] -> Diya-1 #2
India T20 [Blue/Tricolour] -> Kabir-2 #3
--------------------------------------------------
Total jerseys sold (contexts) : 10000
Heavy design objects created  : 3
Designs in factory cache      : 3
Memory for designs: ~1500 KB instead of ~5000000 KB

Read the proof lines slowly. We created 10,000 jersey objects, but the heavy "designing" message printed only 3 times. Ten thousand contexts share three flyweights. The design memory dropped from about 5 GB to about 1.5 MB — a saving of more than 99.9%. That is the whole pattern in two numbers: many contexts, few flyweights.

Here is the factory conversation behind those numbers — the first request pays, every later request rides free:

And here is where the memory actually sits after the fix. Almost the entire bill is now the tiny per-jersey data — the heavy design has shrunk to a sliver because it exists once:

Compare this pie with the naive world, where the "shared designs" slice would be 99.9% of a chart ten thousand times bigger. A healthy flyweight system always looks like this: the unavoidable unique data dominates, and the shared part is a rounding error.

The same idea in C#

// Flyweight: immutable shared state. A record is perfect — immutable by default.
public record JerseyDesign(string Team, string Kit, string Colors)
{
    public static int Created = 0;
    public void Print(string fanName, int num) =>
        Console.WriteLine($"{Team} {Kit} -> {fanName} #{num}");
}
 
// Factory with a cache
public class DesignFactory
{
    private readonly Dictionary<string, JerseyDesign> _cache = new();
 
    public JerseyDesign Get(string team, string kit, string colors)
    {
        var key = $"{team}-{kit}";
        if (!_cache.TryGetValue(key, out var design))
        {
            design = new JerseyDesign(team, kit, colors);
            JerseyDesign.Created++;
            _cache[key] = design;
        }
        return design;
    }
}
 
// Context: tiny per-jersey data + shared reference
public class Jersey
{
    private readonly string _fan; private readonly int _num;
    private readonly JerseyDesign _design;
    public Jersey(string fan, int num, JerseyDesign design)
        => (_fan, _num, _design) = (fan, num, design);
    public void Print() => _design.Print(_fan, _num);
}
 
// Client
var factory = new DesignFactory();
var sold = new List<Jersey>();
for (int i = 0; i < 10_000; i++)
{
    var kit = new[] { "ODI", "Test", "T20" }[i % 3];
    sold.Add(new Jersey($"Fan-{i}", i % 99 + 1, factory.Get("India", kit, "Blue")));
}
Console.WriteLine($"Jerseys: {sold.Count}, Designs created: {JerseyDesign.Created}");
// Output: Jerseys: 10000, Designs created: 3

Fun fact: C# itself flyweights for you. Identical string literals in your code are interned — stored once and shared — and ReferenceEquals("blue", "blue") returns true.

📚 The textbook printing press, in Python

Anjali's college gave her a perfect second example. A state board prints lakhs of copies of one Class 7 Science textbook. Does the press store the full 300-page layout once per printed copy? Never. One master plate; lakhs of copies; each copy differs only by its serial number and the school it ships to. Same pattern, new clothes:

class BookDesign:
    """Flyweight: the master plate. Intrinsic, immutable, made once."""
    created = 0
 
    def __init__(self, title, subject, page_layout):
        BookDesign.created += 1
        print(f"  (heavy work) Typesetting master plate: {title}")
        self._title = title            # no setters anywhere —
        self._subject = subject        # the plate is frozen
        self._page_layout = page_layout
 
    def print_copy(self, serial, school):
        # Extrinsic state arrives as parameters, never stored here.
        print(f"{self._title} | copy #{serial} -> {school}")
 
class PressFactory:
    """Factory: one cache of master plates for the whole press."""
    def __init__(self):
        self._plates = {}
 
    def get_design(self, title, subject, layout):
        if title not in self._plates:
            self._plates[title] = BookDesign(title, subject, layout)
        return self._plates[title]
 
class PrintedCopy:
    """Context: tiny, unique, one per physical book."""
    def __init__(self, serial, school, design):
        self.serial = serial           # extrinsic
        self.school = school           # extrinsic
        self.design = design           # pointer to the SHARED plate
 
    def print_label(self):
        self.design.print_copy(self.serial, self.school)
 
# The press run: 50,000 copies across 4 textbook designs.
press = PressFactory()
titles = ["Science 7", "Maths 7", "English 7", "History 7"]
copies = [
    PrintedCopy(i, f"School-{i % 900}",
                press.get_design(titles[i % 4], "Class 7", "<300-page layout>"))
    for i in range(50_000)
]
 
copies[0].print_label()
copies[1].print_label()
print("-" * 50)
print(f"Copies printed (contexts) : {len(copies)}")
print(f"Master plates made        : {BookDesign.created}")   # -> 4

Fifty thousand contexts, four flyweights. The proof lines are the same two numbers as the jersey shop — they always are. By the way, Python flyweights small integers for you: every -5 to 256 in your whole program is the same shared object, which you can check with a = 100; b = 100; print(a is b).

Where you see it in real software

Flyweight hides inside languages and engines you already use.

• String interning. Java, C#, and Python keep one shared copy of identical string literals. Write "team india" in a hundred places; the runtime stores it once and every variable points at the same immutable object. Immutability of strings is exactly what makes this safe — the flyweight rule in action.
• Java's Integer cache. Integer.valueOf(n) returns pre-made shared objects for every value from -128 to 127. Boolean.TRUE and Boolean.FALSE are two flyweights for the whole JVM. BigDecimal.ZERO, ONE, and TEN are the same trick.
• Game sprites and meshes. A forest of one million trees in a game keeps just a handful of tree meshes and textures in GPU memory and draws them at a million different positions. The position is extrinsic; the mesh is intrinsic. The same idea powers bullets, particles, and monster types in shooters — the Game Programming Patterns book has a beautiful chapter on this.
• Text editors and browsers. A page holds lakhs of characters, but the glyph shape and font data for the letter "a" exists once; each character on screen stores only its position and a reference to the shared glyph.
• Open-source reference. The java-design-patterns flyweight example models an alchemist shop where potion objects are shared from a cache instead of brewed again.

🧭 When to use it and when not to

Flyweight is a specialised tool. Be honest with this checklist — all the ✅ conditions should hold.

The same checklist as a map. Plot your own case before you write a single class:

Top-right — huge counts, mostly shared data — is flyweight country. Bottom-right is the trap students fall into: lots of objects but nothing meaningfully shared, where the pattern adds machinery and saves nothing.

Common mistakes students make

Compare with cousins

Students mix Flyweight up with Singleton, Prototype, and object pools. The table clears it up:

Other useful relations:

• The flyweight factory is itself often a Singleton — one cache for the whole app.
• Composite trees use flyweights for leaf nodes: a document's thousands of identical characters point at shared glyph objects while the tree keeps the structure.
• Facade is the opposite end of the spectrum: Facade makes one big helpful object in front of a subsystem; Flyweight makes many tiny shared objects behind your data.

Everything on one tree before the revision box:

Quick revision box

+--------------------------------------------------------------+
|                  FLYWEIGHT — QUICK REVISION                   |
+--------------------------------------------------------------+
| Idea      : Share the heavy common data; keep only the tiny  |
|             unique part per object. Saves huge RAM.          |
| Nickname  : Cache                                            |
| Analogy   : One cricket jersey DESIGN shared by all players; |
|             only name + number differ per jersey.            |
| Intrinsic : inside / identical / immutable -> in flyweight   |
| Extrinsic : external / exclusive -> in context or params     |
| Parts     : Flyweight, FlyweightFactory(cache), Context      |
| Iron rule : Flyweight is IMMUTABLE. Factory only creates.    |
| The proof : contexts = 10,000 ... flyweights = 3             |
| Memory    : N x shared  ->  N x pointer + D x shared         |
| Trade-off : Saves RAM, may spend CPU passing extrinsic data  |
| Real life : String interning, Java Integer cache (-128..127),|
|             game sprites/meshes drawn at many positions      |
+--------------------------------------------------------------+

Practice exercise 📝

1. Textbook printing press, extended. Take the Python press above and add a fifth design mid-run. Print the proof lines again and confirm the plate count went from 4 to 5 while the copy count grew freely. Then compute, with the College corner formula, the memory saved if each plate is 40 MB and each copy record is 60 bytes.
2. Chess pieces. A chess server hosts 10,000 games. Each game has up to 32 pieces, but there are only 12 kinds of piece (6 types × 2 colours). Build a PieceType flyweight (type, colour, movementRules) and a Piece context (square, gameId). Show that 10,000 games share just 12 flyweights.
3. Challenge — catch the bug. Take your exercise 1 code and deliberately add a setter set_title() to the flyweight. Change the title through one copy and print two copies from different schools. Watch both change. Write two sentences explaining why immutability is the flyweight's most important rule.
4. College challenge — find the break-even. Using the formula naive = N × (u + s) and flyweight = N × (u + 8) + D × s, derive the value of s (shared bytes) below which the pattern saves less than 10% for your N, u, and D. This one calculation will save you from ever applying Flyweight where it cannot pay.