Creational patterns

Patterns are names for common designs

Programmers solve the same kinds of problems again and again. Over time, the common solutions got names. A design pattern is one of those names. It lets a team say "use a factory here" in three words, instead of explaining the whole design each time. A pattern is a shared word, not a rule you must follow.

The best-known list of patterns comes from a 1994 book by four authors, often called the "Gang of Four" book. It used the languages C++ and Smalltalk. JavaScript has tools those languages lacked, so some of those patterns become very small here:

• A shared object can be one object exported from a module file.
• Private data can live in a closure: variables a function keeps after it returns.
• A long chain of setup steps can often be one object of options with default values.

Some of these ways look alike at first. The table below puts them side by side. Read each row as: "this way makes objects like this, it suits these jobs, and here is what to watch for."

This lesson uses ideas from object basics, constructors and new, class basics, closures, closure patterns, Object.create, private members, why modules exist, import and export, and immutability.

A factory function is a plain function that makes an object and returns it. You call it like any other function, with no new in front. It helps in three ways:

• It can keep private data in a closure, where outside code can't reach it.
• It can return a different kind of object depending on what you pass in.
• It avoids two common class mistakes: forgetting to write new, and losing this, the object a method works on.

function createUser(name) {
  return { name, greet: () => "Hi, " + name };
}
const user = createUser("Asha");
console.log(user.greet());

Line 1 starts the factory, createUser. Line 2 returns a new object. Its greet function remembers name, because a function keeps the variables around it. Line 4 asks for Asha's object, and line 5 prints Hi, Asha.

1function createCounter(label) {2  let count = 0;3  return {4    label,5    next() {6      count += 1;7      return label + ": " + count;8    },9    reset() {10      count = 0;11    },12  };13}14 15const first = createCounter("factory");16const second = createCounter("factory");17console.log(first.next());18console.log(first.next());19console.log(second.next());20console.log(first === second);

Read it line by line:

1. Line 1 starts an ordinary function, createCounter.
2. Line 2 makes a new count variable, just for this one call.
3. Lines 5 to 8 are the next method on the returned object. It can still reach count, but nothing outside can.
4. Lines 15 and 16 call the factory twice. That makes two objects, each with its own count.
5. Lines 17 to 19 print factory: 1, factory: 2, and factory: 1. The second counter starts from zero.
6. Line 20 prints false: the two objects are different, even though both have the same label.

1function createUser(name) {2  return {3    name,4    greet() {5      return "Hello, " + name;6    },7  };8}9 10class ClassUser {11  constructor(name) {12    this.name = name;13  }14  greet() {15    return "Hello, " + this.name;16  }17}18 19function ConstructorUser(name) {20  this.name = name;21}22ConstructorUser.prototype.greet = function () {23  return "Hello, " + this.name;24};25 26console.log(createUser("Ada").greet());27console.log(new ClassUser("Lin").greet());28console.log(new ConstructorUser("Grace").greet());

All three make an object with a greet method. They differ in how:

• The factory (line 1) returns an object, and greet reads name from the closure.
• The class (line 10) is called with new and saves name on this.
• The constructor function (line 19) is the older way to write a class. new ConstructorUser() makes the object, and greet is added to its prototype: a shared object that all its objects look in for methods.

Lines 26 to 28 print Hello, Ada, Hello, Lin, and Hello, Grace.

There is one cost to a factory. Each call makes a new greet function. A class keeps one greet on its prototype, shared by every object. That matters only when you make very many objects.

If you use TypeScript, its types are removed before the code runs. So when a factory gets data from a form or from JSON, check that data in code too.

1function createNotifier(channel) {2  if (channel === "email") {3    return {4      send(message) {5        return "email: " + message;6      },7    };8  }9  if (channel === "sms") {10    return {11      send(message) {12        return "sms: " + message;13      },14    };15  }16  return {17    send(message) {18      return "toast: " + message;19    },20  };21}22 23console.log(createNotifier("email").send("Build passed"));24console.log(createNotifier("sms").send("Deploy now"));

The notifier above is a factory that picks one of three objects: email, SMS, or toast. All three have the same send method, so the code that calls it doesn't change. A bigger version of this idea is called an abstract factory. It makes a whole set of objects that belong together. For example, one UI factory could return a matching createButton and createDialog. Later lessons cover that. For now, remember: one function can hide the choice and return objects with the same methods.

A singleton is an object that exists only once. Every part of the program that asks for it gets that same object.

In JavaScript, a module file is the easiest way to make one. A file with import and export runs only once, even if many files import it. So every importer gets the same exported object. This sharing has limits. Each worker, each browser tab, and each Node process runs its own copy of the module.

globalThis.moduleLoads = (globalThis.moduleLoads ?? 0) + 1;
export const cart = { items: [] };

Line 1 counts how many times this file has run. Line 2 exports one cart object.

import { cart as first } from "./cart.mjs";
import { cart as second } from "./cart.mjs";
first.items.push("tea");
console.log(first === second);
console.log(second.items.join(", "));
console.log(globalThis.moduleLoads);

In consumer.mjs, lines 1 and 2 import the cart from the same file, under two names. Line 3 adds tea through first. Lines 4 to 6 print true, tea, and 1:

• true: both names point at the same object.
• tea: the item added through first shows up through second.
• 1: cart.mjs ran only once.

These are two real module files, so they can't run in the page's editor. They have no Run button.

A singleton can also be lazy: it isn't made until the first time someone asks for it. Step through the example below and watch the second call.

1let configInstance;Run2function getConfig(env) {3  if (!configInstance) {4    configInstance = Object.freeze({5      env,6      apiBase: "https://" + env + ".example.com",7      retries: 2,8    });9  }10  return configInstance;11}12 13const first = getConfig("prod");14const second = getConfig("staging");15console.log(first === second);16console.log(second.env);17console.log(Object.isFrozen(first));

1function createCounter(label) {2  let count = 0;3  return {4    next() {5      count += 1;6      return label + ": " + count;7    },8  };9}10 11let configInstance;12function getConfig(env) {13  if (!configInstance) configInstance = { env };14  return configInstance;15}16 17const firstCounter = createCounter("box");18const secondCounter = createCounter("box");19const firstConfig = getConfig("prod");20const secondConfig = getConfig("staging");21console.log(firstCounter === secondCounter);22console.log(firstCounter.next());23console.log(secondCounter.next());24console.log(firstConfig === secondConfig);25console.log(secondConfig.env);

function welcomeUser(user, send) {
  return send("Welcome, " + user.name);
}
const messages = [];
welcomeUser({ name: "Asha" }, (message) => messages.push(message));
console.log(messages[0]);

Line 1 takes send as an argument. Line 5 passes a small fake send. It saves the message in an array instead of sending an email. Line 6 prints Welcome, Asha. You don't need any library for this. Real code passes a real sender; a test passes a fake.

Object.freeze stops anyone from changing an object's own properties. That suits a settings object. But it doesn't make code easier to test. It is also shallow: objects inside the frozen object can still change, unless you freeze them too. Use a singleton only when sharing one object is the goal.

A builder helps when you make something in several steps. It works like this:

• Each method saves one choice.
• Each method returns the builder (this), so you can call the next method right after it, like .select().where(). This is called chaining.
• A last method, build(), checks the saved choices and returns the finished result.

const request = { method: "GET", path: "/users" };
console.log(request.method + " " + request.path);

Line 1 makes the whole request in one go. Line 2 prints GET /users. When an object is this small, a plain object is easier to read than a chain of builder methods.

1function createQueryBuilder(table) {Run2  const state = {3    table,4    fields: ["*"],5    filters: [],6    limit: null,7  };8  return {9    select(...fields) {10      state.fields = fields;11      return this;12    },13    where(field, value) {14      state.filters.push({ field, value });15      return this;16    },17    limit(count) {18      state.limit = count;19      return this;20    },21    build() {22      if (!state.table) throw new Error("table is required");23      if (state.limit !== null && state.limit <= 0) {24        throw new Error("limit must be positive");25      }26      const fields = state.fields.join(", ");27      const where = state.filters.length28        ? " WHERE " + state.filters.map((filter) =>29            filter.field + " = " + JSON.stringify(filter.value)30          ).join(" AND ")31        : "";32      const limit = state.limit === null ? "" : " LIMIT " + state.limit;33      return "SELECT " + fields + " FROM " + state.table + where + limit;34    },35  };36}37 38const query = createQueryBuilder("users")39  .select("id", "email")40  .where("active", true)41  .limit(2)42  .build();43console.log(query);

This query builder is small, but it has every part of a real one. select, where, and limit save choices. build() throws an error if the table is missing or the limit is zero or less. Otherwise it returns a string. A real query builder would also protect against unsafe input. It would not glue SQL together from strings by hand.

1function createApiClient({2  baseUrl = "/api",3  timeout = 3000,4  headers = {},5} = {}) {6  return { baseUrl, timeout, headers };7}8 9const fastClient = createApiClient({ timeout: 1000 });10console.log(fastClient.baseUrl);11console.log(fastClient.timeout);

Lines 1 to 5 take one options object and give each option a default value. Line 9 passes only timeout. Line 10 prints the default /api, and line 11 prints 1000.

Many JavaScript functions should stop here. An options object is short, and it works well with parameters and destructuring. Use a builder only when there are real steps to check.

A builder also keeps its choices between calls. Start a new builder for each query. If you reuse one, each where() call adds to the filters already saved there.

Before module files with import and export worked everywhere, people used an IIFE to keep data private. IIFE stands for "immediately invoked function expression": a function that runs as soon as it is written. Its variables stay private. It returns an object with only the functions other code may use.

1const cartModule = (() => {2  const items = [];3  function add(name, price) {4    items.push({ name, price });5  }6  function total() {7    return items.reduce((sum, item) => sum + item.price, 0);8  }9  return { add, total };10})();11 12cartModule.add("Book", 12);13cartModule.add("Pen", 3);14console.log(cartModule.total());15console.log(cartModule.items);

Read it line by line:

1. Line 1 starts a function and line 10 runs it straight away, with ().
2. Line 2 makes the items array. It is private, because it is never returned.
3. Lines 3 to 8 write two private functions, add and total.
4. Line 9 returns an object with just those two functions.
5. Lines 12 and 13 add a book and a pen. Line 14 prints 15.
6. Line 15 prints undefined, because items is not on the returned object.

This is called a revealing module: you write private functions first, then return, or "reveal", the ones you choose.

1let currentUser = null;2 3export function setCurrentUser(user) {4  currentUser = user;5}6 7export function getCurrentUser() {8  return currentUser;9}

In a module file, every top-level variable is private unless you export it. Here currentUser (line 1) is private. Only setCurrentUser (line 3) and getCurrentUser (line 7) are exported. And because a module file runs only once, an object made at its top level is JavaScript's usual singleton. Review why modules exist and import and export if this is new to you.

The prototype pattern makes new objects by copying an existing one. Before you copy, ask what the copy should keep:

• the object's own properties,
• objects stored inside it,
• its methods from a class,
• its private fields,
• its prototype, the shared object it looks in for methods.

1const widgetPrototype = {2  describe() {3    return this.kind + ":" + this.theme;4  },5  clone(overrides = {}) {6    return Object.assign(7      Object.create(Object.getPrototypeOf(this)),8      this,9      overrides10    );11  },12};13 14const primary = Object.assign(Object.create(widgetPrototype), {15  kind: "button",16  theme: "primary",17});18const danger = primary.clone({ theme: "danger" });19console.log(primary.describe());20console.log(danger.describe());21console.log(Object.getPrototypeOf(danger) === widgetPrototype);

widgetPrototype holds two shared methods, describe and clone. Inside clone():

• Object.create(Object.getPrototypeOf(this)) (line 7) makes a new empty object with the same prototype as the original.
• Object.assign (line 6) copies the original's own properties onto it, then the changes in overrides.

Line 18 makes danger, a copy of primary with a new theme. Lines 19 to 21 print button:primary, button:danger, and true: the copy kept the same prototype.

1class Point {2  constructor(xOrPoint, y) {3    if (typeof xOrPoint === "object") {4      this.x = xOrPoint.x;5      this.y = xOrPoint.y;6    } else {7      this.x = xOrPoint;8      this.y = y;9    }10  }11  clone() {12    return new Point(this.x, this.y);13  }14  toString() {15    return this.x + "," + this.y;16  }17}18 19const original = new Point(2, 3);20const cloned = original.clone();21const copied = new Point(original);22console.log(cloned.toString());23console.log(copied.toString());24console.log(copied instanceof Point);

There are two ways to copy here:

• Line 20 calls clone() on the old point. The method (line 11) makes the copy.
• Line 21 calls new Point(original). This is a copy constructor: the constructor (line 2) sees an object and copies its x and y.

Both print 2,3, and line 24 prints true: the copy is a real Point. Either way, the class decides how deep the copy goes.

1const original = {2  user: { name: "Ada" },3  tags: ["js"],4};5const spread = { ...original };6spread.user.name = "Lin";7spread.tags = [...spread.tags, "patterns"];8console.log(original.user.name);9console.log(original.tags.join(","));10console.log(spread.tags.join(","));

The spread syntax { ...original } (line 5) makes a shallow copy: a new outer object, but the objects inside it are shared, not copied.

• Line 6 changes spread.user.name. Both objects share one user, so line 8 prints Lin for the original too.
• Line 7 puts a brand new array in spread.tags. The original array doesn't change, so line 9 prints js and line 10 prints js,patterns.

1class Point {2  constructor(x, y) {3    this.x = x;4    this.y = y;5  }6  distance() {7    return Math.hypot(this.x, this.y);8  }9}10 11const point = new Point(3, 4);12const copied = structuredClone(point);13console.log(copied instanceof Point);14console.log(typeof copied.distance);15console.log(JSON.stringify(copied));

structuredClone makes a deep copy: it copies the inner objects too. It works for plain data, like arrays, plain objects, dates, Maps, and Sets. But it doesn't keep a class's prototype. So line 12 copies x and y, but:

• Line 13 prints false: the copy is not a Point.
• Line 14 prints undefined: the distance method is gone.
• Line 15 prints {"x":3,"y":4}: the data is all there.

The table below compares the ways to copy. Read each row as: "this way of copying goes this deep, and it is best for this."

Real code rarely says "this is a pattern". It uses names like createApiClient, logger, queryBuilder, aUser(), or clone(). Knowing the pattern helps you talk about the design and its costs.

The table below shows common jobs. Read each row as: "for this job, people often use this way, for this reason."

When a pattern is too much

Pick the smallest thing that works:

• If one place makes one fixed object, write the object directly, with { }.
• If the object changes a little with each call, use a factory.
• If a module already holds one shared service, export it.

Use a named pattern only when it makes the choices, the saved data, the checks, or the copying easier to see.

Object pools: reuse only when it helps

An object pool keeps used objects and hands them out again, instead of making a new one each time. It can help for things that are slow to make or limited in number, like database connections, when the database library doesn't pool them already. For ordinary JavaScript objects, just make new ones.

function createPool(make, reset) {
  const available = [];
  return {
    acquire() { return available.pop() ?? make(); },
    release(item) { reset(item); available.push(item); },
  };
}
const pool = createPool(() => ({ value: "" }), (item) => { item.value = ""; });
const first = pool.acquire();
first.value = "old";
pool.release(first);
const reused = pool.acquire();
console.log(first === reused);
console.log(reused.value === "" ? "reset" : reused.value);

Read it line by line:

1. Lines 1 to 7 make the pool. It keeps returned objects in the available array.
2. Line 4, acquire(), hands out a kept object, or calls make() if there is none.
3. Line 5, release(), clears the object with reset and keeps it.
4. Lines 9 to 12 take an object, write old into it, give it back, and take one again.
5. Lines 13 and 14 print true and reset: the same object came back, with its old value cleared.

This small pool has gaps. Nothing stops code from giving the same object back twice, and the pool can grow without limit. A real pool needs rules for both. A pool also keeps memory in use, and it can leak old data if the reset misses a property. So measure first, and add a pool only if it clearly helps.

Common misconceptions

• "You must use patterns." Patterns are only names. Use the smallest JavaScript code that solves the problem.
• "A factory is just a class without the word class." A factory can pick which object to return, and it can keep data private in a closure. A class shares its methods through a prototype.
• "A frozen singleton is safe." Freezing stops changes to its top-level properties. But it is still one shared object, and tests still can't swap it out.
• "Every chain of methods is a builder." A builder saves choices and has a build() that checks them. Some chains are just handy helper methods.
• "structuredClone copies everything." It copies plain data deeply, but a class object comes back without its prototype or its methods.

The table below gives a quick check for each mix-up. Read each row as: "if I believe this, I ask this question, and the better way to say it is this."

Key takeaways

• Patterns are names for common designs, not rules you must follow.
• A factory returns a new object each time. It can keep private data in a closure, or pick which object to return.
• A singleton is one shared object. Use it when sharing is the goal, and pass things in as arguments when tests need to swap them.
• A builder makes something in steps and checks it in build(). An options object with defaults is the simpler choice.
• Ways of copying differ in how deep they go and whether they keep the prototype. Check with real === and instanceof tests.

Up next: Observer and pub/sub shows how one part of an app can react when another part changes, without the two knowing about each other. Later lessons cover more patterns, app state, and how to organize a whole app.