Creation First demand, remembered result

Lazy initialization

Keep the recipe until it is needed.

Someone opens your help center, reads how to reset a password, and leaves. They never touch search. Yet opening the center built a search index for every article before they read the first one.

The index is useful when someone searches. We can keep the instructions for building it, wait for that first search, and reuse the result afterward.

TypeScriptGoPython One help center · one initialization outcome

01 / Notice the unused work

Opening the page does not always mean using search.

Building the index at startup is a reasonable first choice. Search is ready immediately, initialization errors appear early, and the rest of the program can assume setup has happened. That approach is called eager initialization.

Now imagine a help center whose common path is following article links. Index setup becomes work every visitor pays for, even when their visit never needs it. The useful change is to move that setup behind the operation that requires it.

Lazy initialization delays creating a value until its first demand, then retains the result for later use. Our help center keeps its article records immediately and builds its search index only when a nonblank search needs it.

If you write React, you have already handed it a recipe like this: useState(() => readDraft()) runs readDraft once, for the first render, where useState(readDraft()) runs it on every render.

We use four small articles and a real, deliberately simple term index. The lab counts actual builds rather than timing them; a large index would need measurement before you decide to defer it.

02 / Move the creation boundary

Keep a recipe and a place for its result.

The center keeps a recipe for building its index and a place to remember the outcome. The implementations retain an initialization function and supply the recipe to a retained cell when needed. Creating the wrapper or empty cell does not build the index. First demand runs the recipe. Later calls receive the remembered outcome.

Open → keep recipe

Uninitialized.

The articles and builder exist. The search index does not. Browsing can proceed without it.

First demand → initialize

Run the setup.

A nonblank search calls the retained wrapper. This caller pays the construction cost.

Later demand → reuse

Keep the outcome.

Different queries use one index. A new query does not mean a new initialization.

The phrase “once” needs an owner. Here it means once per help-center instance. Two centers can build two independent indexes. Recreating the wrapper inside every search would give every search its own empty place to cache a result.

Initialization state is also separate from the value. An index with zero terms is a completed, usable index. A stored false, zero, or empty string can be a valid result in other examples. None of those values should accidentally mean “run setup again.”

03 / See the shape

Create the wrapper once. Call it when search needs it.

The basic form retains one initialization outcome. The useful form gives that wrapper a home inside HelpCenter. Browsing copies article records without touching the index; searching asks for it. The separate warm method lets an owner demand setup deliberately before a user searches.

Expected setup failure is part of this example’s result contract. We remember “index unavailable” just as we remember a successful index. That prevents repeated searches from silently repeating a failed build. Recovery needs a deliberate new attempt boundary.

Read in

Compare with

Keep one initialization outcome. TypeScript uses a closure and an undefined sentinel; Go uses sync.OnceValues; Python and Java keep an explicit initialized flag behind a lock; Rust uses OnceLock. Expected failure is a stored outcome too.

TypeScriptReading

search.ts

export function lazyResult<T>(initialize: () => Outcome<T>): () => Outcome<T> {
	let cached: Outcome<T> | undefined;
	return () => (cached ??= initialize());
	// Store the outcome, including an expected error. Undefined alone means "not run".
}

GoAlongside

search.go

func LazyResult[T any](initialize func() (T, error)) func() (T, error) {
	return sync.OnceValues(initialize)
	// The returned function shares one value/error pair, including a non-nil error.
}

Read complete examples without JavaScript

search.ts

export type Outcome<T> = Readonly<{ ok: true; value: T } | { ok: false; error: string }>;
export type Article = Readonly<{ id: number; title: string; text: string }>;
export type IndexState = 'uninitialized' | 'ready' | 'failed';

export function lazyResult<T>(initialize: () => Outcome<T>): () => Outcome<T> {
	let cached: Outcome<T> | undefined;
	return () => (cached ??= initialize());
	// Store the outcome, including an expected error. Undefined alone means "not run".
}

function asciiLower(value: string): string {
	return value.replace(/[A-Z]/g, (letter) => letter.toLowerCase());
}
export function normalizeQuery(query: string): string {
	return asciiLower(query.replace(/^[\t\n\v\f\r ]+|[\t\n\v\f\r ]+$/g, ''));
}
export class SearchIndex {
	#articles: Article[];
	#terms = new Map<string, number[]>();
	constructor(articles: readonly Article[]) {
		this.#articles = articles.map((article) => ({ ...article }));
		this.#articles.forEach((article, position) => {
			const words = new Set(asciiLower(`${article.title} ${article.text}`).match(/[a-z]+/g) ?? []);
			for (const word of words) {
				const positions = this.#terms.get(word) ?? [];
				positions.push(position);
				this.#terms.set(word, positions);
			}
		});
	}
	search(term: string): Article[] {
		return (this.#terms.get(term) ?? []).map((position) => ({ ...this.#articles[position] }));
	}
	get termCount(): number {
		return this.#terms.size;
	}
}
export function buildIndex(articles: readonly Article[], fail = false): Outcome<SearchIndex> {
	return fail
		? { ok: false, error: 'index unavailable' }
		: { ok: true, value: new SearchIndex(articles) };
}

export class HelpCenter {
	#articles: Article[];
	#getIndex: () => Outcome<SearchIndex>;
	#attempts = 0;
	#state: IndexState = 'uninitialized';
	#terms = 0;
	constructor(articles: readonly Article[], fail = false) {
		this.#articles = articles.map((article) => ({ ...article })); // Snapshot this owner's input.
		this.#getIndex = lazyResult(() => {
			this.#attempts++;
			const result = buildIndex(this.#articles, fail);
			this.#state = result.ok ? 'ready' : 'failed';
			this.#terms = result.ok ? result.value.termCount : 0;
			return result;
		}); // Create the wrapper once, outside the search handler.
	}
	browse(): Article[] {
		return this.#articles.map((article) => ({ ...article }));
	}
	search(query: string): Outcome<Article[]> {
		const term = normalizeQuery(query);
		if (!term) return { ok: true, value: [] }; // No index needed for a blank query.
		const result = this.#getIndex();
		return result.ok ? { ok: true, value: result.value.search(term) } : result;
	}
	warm(): Outcome<number> {
		const result = this.#getIndex();
		return result.ok ? { ok: true, value: result.value.termCount } : result;
	}
	stats() {
		return { attempts: this.#attempts, state: this.#state, terms: this.#terms };
	}
}

export const articles: readonly Article[] = [
	{ id: 1, title: 'Reset your password', text: 'Recover your account and login.' },
	{ id: 2, title: 'Request a refund', text: 'Refund a payment from billing.' },
	{ id: 3, title: 'Use the app offline', text: 'Keep downloads ready for travel.' },
	{ id: 4, title: 'Fix a failed payment', text: 'Update your billing card.' }
];
export function runExample(): void {
	const center = new HelpCenter(articles);
	console.log(`opened: ${center.stats().attempts} builds`);
	console.log(`browse: ${center.browse().length} articles, ${center.stats().attempts} builds`);
	for (const query of ['payment', 'offline', 'volcano']) {
		const result = center.search(query);
		console.log(
			`${query}: ${result.ok ? result.value.map((article) => article.id).join(',') || 'no matches' : result.error}; builds=${center.stats().attempts}`
		);
	}
	const unavailable = new HelpCenter(articles, true);
	unavailable.search('payment'); // The first search stores the failure.
	const again = unavailable.search('offline');
	console.log(
		`failed owner: ${again.ok ? 'unexpected success' : again.error}; builds=${unavailable.stats().attempts}`
	);
}

runExample();

search.go

package main

import (
	"errors"
	"fmt"
	"strconv"
	"strings"
	"sync"
	"sync/atomic"
)

type Article struct {
	ID          int
	Title, Text string
}

func LazyResult[T any](initialize func() (T, error)) func() (T, error) {
	return sync.OnceValues(initialize)
	// The returned function shares one value/error pair, including a non-nil error.
}


func asciiLower(value string) string {
	return strings.Map(func(r rune) rune {
		if r >= 'A' && r <= 'Z' {
			return r + ('a' - 'A')
		}
		return r
	}, value)
}
func NormalizeQuery(query string) string { return asciiLower(strings.Trim(query, " \t\n\v\f\r")) }

type SearchIndex struct {
	articles []Article
	terms    map[string][]int
}

var errIndexUnavailable = errors.New("index unavailable")

func BuildIndex(articles []Article, fail bool) (*SearchIndex, error) {
	if fail {
		return nil, errIndexUnavailable
	}
	index := &SearchIndex{articles: append([]Article{}, articles...), terms: map[string][]int{}}
	for position, article := range index.articles {
		seen := map[string]bool{}
		for _, word := range strings.FieldsFunc(asciiLower(article.Title+" "+article.Text), func(r rune) bool { return r < 'a' || r > 'z' }) {
			if !seen[word] {
				index.terms[word] = append(index.terms[word], position)
				seen[word] = true
			}
		}
	}
	return index, nil
}
func (index *SearchIndex) Search(term string) []Article {
	result := []Article{}
	for _, position := range index.terms[term] {
		result = append(result, index.articles[position])
	}
	return result
}

type HelpCenter struct {
	articles []Article
	getIndex func() (*SearchIndex, error)
	attempts atomic.Int32
}

func NewHelpCenter(articles []Article, fail bool) *HelpCenter {
	center := &HelpCenter{articles: append([]Article{}, articles...)}
	center.getIndex = LazyResult(func() (*SearchIndex, error) {
		center.attempts.Add(1)
		return BuildIndex(center.articles, fail)
	}) // One wrapper belongs to this center, not to each search.
	return center
}
func (center *HelpCenter) Browse() []Article { return append([]Article{}, center.articles...) }
func (center *HelpCenter) Search(query string) ([]Article, error) {
	term := NormalizeQuery(query)
	if term == "" {
		return []Article{}, nil
	}
	index, err := center.getIndex()
	if err != nil {
		return nil, err
	}
	return index.Search(term), nil
}
func (center *HelpCenter) Warm() (int, error) {
	index, err := center.getIndex()
	if err != nil {
		return 0, err
	}
	return len(index.terms), nil
}
func (center *HelpCenter) Attempts() int { return int(center.attempts.Load()) }


func Articles() []Article {
	return []Article{
		{ID: 1, Title: "Reset your password", Text: "Recover your account and login."},
		{ID: 2, Title: "Request a refund", Text: "Refund a payment from billing."},
		{ID: 3, Title: "Use the app offline", Text: "Keep downloads ready for travel."},
		{ID: 4, Title: "Fix a failed payment", Text: "Update your billing card."},
	}
}
func main() {
	center := NewHelpCenter(Articles(), false)
	fmt.Printf("opened: %d builds\n", center.Attempts())
	fmt.Printf("browse: %d articles, %d builds\n", len(center.Browse()), center.Attempts())
	for _, query := range []string{"payment", "offline", "volcano"} {
		matches, err := center.Search(query)
		ids := []string{}
		for _, article := range matches {
			ids = append(ids, strconv.Itoa(article.ID))
		}
		message := strings.Join(ids, ",")
		if message == "" {
			message = "no matches"
		}
		if err != nil {
			message = err.Error()
		}
		fmt.Printf("%s: %s; builds=%d\n", query, message, center.Attempts())
	}
	unavailable := NewHelpCenter(Articles(), true)
	unavailable.Search("payment") // The first search stores the failure.
	_, err := unavailable.Search("offline")
	fmt.Printf("failed owner: %s; builds=%d\n", err, unavailable.Attempts())
}

search.py

"""Build a small help-center search index only when a query needs it."""

from __future__ import annotations

import re
from dataclasses import dataclass
from threading import Lock
from typing import Callable, Generic, TypeVar


T = TypeVar("T")


@dataclass(frozen=True)
class Outcome(Generic[T]):
    ok: bool
    value: T | None = None
    error: str | None = None

    @classmethod
    def success(cls, value: T) -> Outcome[T]:
        return cls(True, value=value)

    @classmethod
    def failure(cls, error: str) -> Outcome[T]:
        return cls(False, error=error)


class LazyResult(Generic[T]):
    def __init__(self, initialize: Callable[[], Outcome[T]]) -> None:
        self._initialize = initialize
        self._lock = Lock()
        self._initialized = False
        self._cached: Outcome[T] | None = None

    def get(self) -> Outcome[T]:
        with self._lock:
            if self._initialized:
                assert self._cached is not None
                return self._cached
            result = self._initialize()
            self._cached = result
            self._initialized = True
            return result


def lazy_result(initialize: Callable[[], Outcome[T]]) -> LazyResult[T]:
    return LazyResult(initialize)




@dataclass(frozen=True)
class Article:
    id: int
    title: str
    text: str


def _copy_article(article: Article) -> Article:
    return Article(article.id, article.title, article.text)


def _ascii_lower(value: str) -> str:
    return re.sub(r"[A-Z]", lambda match: match.group(0).lower(), value)


def normalize_query(query: str) -> str:
    return _ascii_lower(query.strip(" \t\n\v\f\r"))


class SearchIndex:
    def __init__(self, articles: list[Article]) -> None:
        self._articles = [_copy_article(article) for article in articles]
        self._terms: dict[str, list[int]] = {}
        for position, article in enumerate(self._articles):
            words = set(re.findall(r"[a-z]+", _ascii_lower(f"{article.title} {article.text}")))
            for word in words:
                self._terms.setdefault(word, []).append(position)

    def search(self, term: str) -> list[Article]:
        return [_copy_article(self._articles[position]) for position in self._terms.get(term, [])]

    @property
    def term_count(self) -> int:
        return len(self._terms)


def build_index(articles: list[Article], fail: bool = False) -> Outcome[SearchIndex]:
    if fail:
        return Outcome.failure("index unavailable")
    return Outcome.success(SearchIndex(articles))


class HelpCenter:
    def __init__(self, articles: list[Article], fail: bool = False) -> None:
        self._articles = [_copy_article(article) for article in articles]
        self._fail = fail
        self._attempts = 0
        self._attempts_lock = Lock()
        self._state = "uninitialized"
        self._terms = 0
        self._stats_lock = Lock()
        self._get_index = lazy_result(self._initialize)  # Create the wrapper once per owner.

    def _initialize(self) -> Outcome[SearchIndex]:
        with self._attempts_lock:
            self._attempts += 1
        result = build_index(self._articles, self._fail)
        with self._stats_lock:
            self._state = "ready" if result.ok else "failed"
            self._terms = result.value.term_count if result.ok and result.value is not None else 0
        return result

    def browse(self) -> list[Article]:
        return [_copy_article(article) for article in self._articles]

    def search(self, query: str) -> Outcome[list[Article]]:
        term = normalize_query(query)
        if not term:
            return Outcome.success([])
        result = self._get_index.get()
        if not result.ok:
            return Outcome.failure(result.error or "index unavailable")
        assert result.value is not None
        return Outcome.success(result.value.search(term))

    def warm(self) -> Outcome[int]:
        result = self._get_index.get()
        if not result.ok:
            return Outcome.failure(result.error or "index unavailable")
        assert result.value is not None
        return Outcome.success(result.value.term_count)

    def stats(self) -> dict[str, int | str]:
        with self._stats_lock, self._attempts_lock:
            return {"attempts": self._attempts, "state": self._state, "terms": self._terms}




articles: tuple[Article, ...] = (
    Article(1, "Reset your password", "Recover your account and login."),
    Article(2, "Request a refund", "Refund a payment from billing."),
    Article(3, "Use the app offline", "Keep downloads ready for travel."),
    Article(4, "Fix a failed payment", "Update your billing card."),
)


def run_example() -> None:
    center = HelpCenter(list(articles))
    print(f"opened: {center.stats()['attempts']} builds")
    print(f"browse: {len(center.browse())} articles, {center.stats()['attempts']} builds")
    for query in ("payment", "offline", "volcano"):
        result = center.search(query)
        if result.ok:
            ids = ",".join(str(article.id) for article in result.value or []) or "no matches"
            message = ids
        else:
            message = result.error or "index unavailable"
        print(f"{query}: {message}; builds={center.stats()['attempts']}")
    unavailable = HelpCenter(list(articles), True)
    unavailable.search("payment")  # The first search stores the failure.
    again = unavailable.search("offline")
    message = again.error if not again.ok else "unexpected success"
    print(f"failed owner: {message}; builds={unavailable.stats()['attempts']}")




if __name__ == "__main__":
    run_example()

Search.java

import java.util.ArrayList;
import java.util.HashMap;
import java.util.HashSet;
import java.util.List;
import java.util.Map;
import java.util.Set;
import java.util.concurrent.atomic.AtomicInteger;
import java.util.function.Supplier;
import java.util.regex.Matcher;
import java.util.regex.Pattern;

record Outcome<T>(boolean ok, T value, String error) {
    static <T> Outcome<T> success(T value) { return new Outcome<>(true, value, null); }
    static <T> Outcome<T> failure(String error) { return new Outcome<>(false, null, error); }
}

final class LazyResult<T> {
    private final Supplier<Outcome<T>> initialize;
    private boolean initialized;
    private Outcome<T> cached;

    LazyResult(Supplier<Outcome<T>> initialize) { this.initialize = initialize; }

    synchronized Outcome<T> get() {
        if (initialized) return cached;
        Outcome<T> result = initialize.get();
        cached = result;
        initialized = true;
        return result;
    }
}

record Article(int id, String title, String text) {}

final class SearchText {
    private static final Pattern WORD = Pattern.compile("[a-z]+");

    private SearchText() {}

    static String asciiLower(String value) {
        StringBuilder result = new StringBuilder(value.length());
        for (char character : value.toCharArray()) {
            result.append(character >= 'A' && character <= 'Z' ? (char) (character + ('a' - 'A')) : character);
        }
        return result.toString();
    }

    static String normalizeQuery(String query) {
        int start = 0;
        int end = query.length();
        while (start < end && isAsciiSpace(query.charAt(start))) start++;
        while (end > start && isAsciiSpace(query.charAt(end - 1))) end--;
        return asciiLower(query.substring(start, end));
    }

    private static boolean isAsciiSpace(char character) {
        return character == ' ' || character == '\t' || character == '\n'
            || character == '\r' || character == '\u000b' || character == '\f';
    }

    static Set<String> words(String value) {
        Set<String> result = new HashSet<>();
        Matcher matcher = WORD.matcher(asciiLower(value));
        while (matcher.find()) result.add(matcher.group());
        return result;
    }
}

final class SearchIndex {
    private final List<Article> articles;
    private final Map<String, List<Integer>> terms = new HashMap<>();

    SearchIndex(List<Article> articles) {
        this.articles = copyArticles(articles);
        for (int position = 0; position < this.articles.size(); position++) {
            Article article = this.articles.get(position);
            for (String word : SearchText.words(article.title() + " " + article.text())) {
                terms.computeIfAbsent(word, ignored -> new ArrayList<>()).add(position);
            }
        }
    }

    List<Article> search(String term) {
        List<Article> result = new ArrayList<>();
        for (int position : terms.getOrDefault(term, List.of())) {
            result.add(copyArticle(articles.get(position)));
        }
        return result;
    }

    int termCount() { return terms.size(); }

    private static List<Article> copyArticles(List<Article> source) {
        List<Article> result = new ArrayList<>();
        for (Article article : source) result.add(copyArticle(article));
        return result;
    }

    private static Article copyArticle(Article article) {
        return new Article(article.id(), article.title(), article.text());
    }
}

final class SearchBuilder {
    private SearchBuilder() {}

    static Outcome<SearchIndex> build(List<Article> articles, boolean fail) {
        return fail ? Outcome.failure("index unavailable") : Outcome.success(new SearchIndex(articles));
    }
}

record Stats(int attempts, String state, int terms) {}

final class HelpCenter {
    private final List<Article> articles;
    private final boolean fail;
    private final AtomicInteger attempts = new AtomicInteger();
    private final LazyResult<SearchIndex> getIndex;
    private volatile String state = "uninitialized";
    private volatile int terms;

    HelpCenter(List<Article> articles, boolean fail) {
        this.articles = copyArticles(articles);
        this.fail = fail;
        this.getIndex = new LazyResult<>(this::initialize);
    }

    private Outcome<SearchIndex> initialize() {
        attempts.incrementAndGet();
        Outcome<SearchIndex> result = SearchBuilder.build(articles, fail);
        state = result.ok() ? "ready" : "failed";
        terms = result.ok() && result.value() != null ? result.value().termCount() : 0;
        return result;
    }

    List<Article> browse() { return copyArticles(articles); }

    Outcome<List<Article>> search(String query) {
        String term = SearchText.normalizeQuery(query);
        if (term.isEmpty()) return Outcome.success(List.of());
        Outcome<SearchIndex> result = getIndex.get();
        return result.ok() ? Outcome.success(result.value().search(term)) : Outcome.failure(result.error());
    }

    Outcome<Integer> warm() {
        Outcome<SearchIndex> result = getIndex.get();
        return result.ok() ? Outcome.success(result.value().termCount()) : Outcome.failure(result.error());
    }

    Stats stats() { return new Stats(attempts.get(), state, terms); }

    private static List<Article> copyArticles(List<Article> source) {
        List<Article> result = new ArrayList<>();
        for (Article article : source) result.add(new Article(article.id(), article.title(), article.text()));
        return result;
    }
}

public final class Search {
    static final List<Article> ARTICLES = List.of(
        new Article(1, "Reset your password", "Recover your account and login."),
        new Article(2, "Request a refund", "Refund a payment from billing."),
        new Article(3, "Use the app offline", "Keep downloads ready for travel."),
        new Article(4, "Fix a failed payment", "Update your billing card.")
    );

    static List<Article> articles() { return new ArrayList<>(ARTICLES); }

    static List<String> runExample() {
        HelpCenter center = new HelpCenter(articles(), false);
        List<String> lines = new ArrayList<>();
        lines.add("opened: " + center.stats().attempts() + " builds");
        lines.add("browse: " + center.browse().size() + " articles, " + center.stats().attempts() + " builds");
        for (String query : List.of("payment", "offline", "volcano")) {
            Outcome<List<Article>> result = center.search(query);
            String message = result.ok()
                ? result.value().stream().map(article -> Integer.toString(article.id())).reduce((a, b) -> a + "," + b).orElse("no matches")
                : result.error();
            lines.add(query + ": " + message + "; builds=" + center.stats().attempts());
        }
        HelpCenter unavailable = new HelpCenter(articles(), true);
        unavailable.search("payment"); // The first search stores the failure.
        Outcome<List<Article>> again = unavailable.search("offline");
        lines.add("failed owner: " + (again.ok() ? "unexpected success" : again.error())
            + "; builds=" + unavailable.stats().attempts());
        return lines;
    }

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

search.rs

use std::collections::{HashMap, HashSet};
use std::sync::{
    atomic::{AtomicUsize, Ordering},
    OnceLock,
};

#[derive(Clone, Debug, PartialEq, Eq)]
pub struct Article {
    pub id: usize,
    pub title: String,
    pub text: String,
}

pub fn lazy_result<T>(
    cell: &OnceLock<Result<T, String>>,
    initialize: impl FnOnce() -> Result<T, String>,
) -> Result<&T, &str> {
    cell.get_or_init(initialize)
        .as_ref()
        .map_err(String::as_str)
    // The cell retains the Result itself, so an expected Err is an initialized value.
}

pub fn normalize_query(query: &str) -> String {
    query
        .trim_matches(|c| matches!(c, ' ' | '\t' | '\n' | '\r' | '\x0b' | '\x0c'))
        .to_ascii_lowercase()
}
pub struct SearchIndex {
    articles: Vec<Article>,
    terms: HashMap<String, Vec<usize>>,
}
pub fn build_index(articles: &[Article], fail: bool) -> Result<SearchIndex, String> {
    if fail {
        return Err("index unavailable".to_owned());
    }
    let mut terms: HashMap<String, Vec<usize>> = HashMap::new();
    for (position, article) in articles.iter().enumerate() {
        let text = format!("{} {}", article.title, article.text).to_ascii_lowercase();
        let words: HashSet<_> = text
            .split(|c: char| !c.is_ascii_alphabetic())
            .filter(|word| !word.is_empty())
            .collect();
        for word in words {
            terms.entry(word.to_owned()).or_default().push(position);
        }
    }
    Ok(SearchIndex {
        articles: articles.to_vec(),
        terms,
    })
}
impl SearchIndex {
    pub fn search(&self, term: &str) -> Vec<Article> {
        self.terms
            .get(term)
            .into_iter()
            .flatten()
            .map(|position| self.articles[*position].clone())
            .collect()
    }
}

pub struct HelpCenter {
    articles: Vec<Article>,
    index: OnceLock<Result<SearchIndex, String>>,
    attempts: AtomicUsize,
    fail: bool,
}
impl HelpCenter {
    pub fn new(articles: Vec<Article>, fail: bool) -> Self {
        Self {
            articles,
            index: OnceLock::new(),
            attempts: AtomicUsize::new(0),
            fail,
        }
    }
    fn get_index(&self) -> Result<&SearchIndex, &str> {
        lazy_result(&self.index, || {
            self.attempts.fetch_add(1, Ordering::Relaxed);
            build_index(&self.articles, self.fail)
        }) // This center retains the cell across calls.
    }
    pub fn browse(&self) -> Vec<Article> {
        self.articles.clone()
    }
    pub fn search(&self, query: &str) -> Result<Vec<Article>, &str> {
        let term = normalize_query(query);
        if term.is_empty() {
            return Ok(Vec::new());
        }
        Ok(self.get_index()?.search(&term))
    }
    pub fn warm(&self) -> Result<usize, &str> {
        Ok(self.get_index()?.terms.len())
    }
    pub fn attempts(&self) -> usize {
        self.attempts.load(Ordering::Relaxed)
    }
}

pub fn articles() -> Vec<Article> {
    [
        (1, "Reset your password", "Recover your account and login."),
        (2, "Request a refund", "Refund a payment from billing."),
        (3, "Use the app offline", "Keep downloads ready for travel."),
        (4, "Fix a failed payment", "Update your billing card."),
    ]
    .into_iter()
    .map(|(id, title, text)| Article {
        id,
        title: title.to_owned(),
        text: text.to_owned(),
    })
    .collect()
}
fn main() {
    let center = HelpCenter::new(articles(), false);
    println!("opened: {} builds", center.attempts());
    println!(
        "browse: {} articles, {} builds",
        center.browse().len(),
        center.attempts()
    );
    for query in ["payment", "offline", "volcano"] {
        let message = match center.search(query) {
            Ok(matches) if matches.is_empty() => "no matches".to_owned(),
            Ok(matches) => matches
                .iter()
                .map(|article| article.id.to_string())
                .collect::<Vec<_>>()
                .join(","),
            Err(error) => error.to_owned(),
        };
        println!("{}: {}; builds={}", query, message, center.attempts());
    }
    let unavailable = HelpCenter::new(articles(), true);
    let _ = unavailable.search("payment");
    let error = unavailable.search("offline").unwrap_err();
    println!("failed owner: {}; builds={}", error, unavailable.attempts());
}

The center snapshots article records when it is created, so later caller mutations cannot change what first initialization sees. Its index maps ASCII words to article positions. Search trims ASCII whitespace, lowercases A–Z, and looks up one exact term. “payment” matches articles 2 and 4; “offline” matches 3. Repeated words in one article do not duplicate that article in the results.

A blank query returns no results without demanding the index. An unmatched word also returns no results, but needs the index to determine that. This is a small exact-word lookup; ranking, stemming, phrase search, and Unicode-aware analysis are separate search requirements.

Reading the TypeScriptA closure, a sentinel, and a tagged outcome

cached lives in the closure returned by lazyResult. The ??= operator calls and assigns the initializer only when cached is nullish; our sentinel is undefined. Once assigned, the wrapper returns the same outcome object.

The ok tag distinguishes a successful value from an expected error. An empty index remains ok: true. This is a synchronous helper.

Reading the GoOnceValues retains the value/error pair

sync.OnceValues returns a function that executes its initializer once and retains both returned values. Here they are *SearchIndex and error. A non-nil error is still a returned value, so it remains part of the cached pair.

The standard wrapper handles concurrent first calls. Our built index has no mutation API, and searches return copied article values. The attempt counter is atomic so the native concurrency check can inspect it safely. Keep a pointer to the center; do not copy a value containing its atomic state after use. Read OnceValues.

Reading the PythonA locked outcome and an explicit state flag

LazyResult keeps an explicit _initialized flag separate from its cached outcome. That matters because a successful value can be false, zero, empty, or otherwise valid. Its lock keeps concurrent first callers inside one initialization boundary.

HelpCenter snapshots its article list before creating the wrapper. A blank search returns immediately, while get stores an expected error as an outcome. Python’s dataclasses and lists make the copied value boundaries visible.

04 / Predict, browse, search

A visitor can leave without ever building the index.

Watch the first-demand story or step through it. In Try it, start with the lazy policy. Predict zero builds, then browse articles. Next predict one and search “payment.” Change the query to “offline” and search again: the result changes while the build count stays at one.

Switch to eager setup and inspect the count before doing anything. Then try the mistaken wrapper lifetime: each search builds again, even though each individual wrapper correctly initializes only once.

Finally, try the empty help center and a setup failure. A successful empty index is ready with zero terms. A failed attempt is a remembered error. These should be different states even when neither shows search results.

Playback controls

Lazy initialization

Build on first demand.

Help center 14 article records

Article snapshot Available to browse

Retained setup slot Recipe only buildIndex(articles) Not called yet

Opened help center

Returned article IDsNot requested

Browse or search to request articles.

Total build attempts 0This owner’s builds 0

01/ 04

Open the help center

Keep the recipe.

Help center 1 owns four articles and an initializer. No index exists yet.

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

Read this scene

Help center 1 owns four articles and an initializer. No index exists yet.

Help center 1: 4 articles. Opened help center. Index uninitialized, 0 terms. 0 total build attempts; 0 in this owner. No result requested.

Try the example by reading

Opening and browsing build nothing. Searching payment builds one index and returns articles 2 and 4. Searching offline returns article 3 using the same index. Recreating the owner loses that reuse.

HELP CENTER / OPTIONAL SEARCH

Read first. Build only if needed.

The index below is built by the lesson’s TypeScript code, and the counters record actual initialization attempts.

Initialization policy

Article snapshot

Fail index setup Browsing still works. Changing this starts a new owner.

After your next action, how many total builds will have been attempted?

Help center 14 article records

Article snapshot Available to browse

Retained setup slot Recipe only buildIndex(articles) Not called yet

Opened help center

Returned article IDsNot requested

Browse or search to request articles.

Total build attempts 0This owner’s builds 0

Opened help center. This center retains one wrapper. Browsing and blank queries leave it untouched; the first nonblank search initializes it.

Search results

Browse the help center, then search for “payment” and “offline.” Watch when the build count changes.

Follow each demand and build

Opened help center: +0 builds → 0 total · uninitialized

Most recent 16 actions. Policy, snapshot, and failure changes open a fresh owner.

Worked trace: open → browse → search payment → search offline
Policy	At opening	After browsing	After first search	After second search
Eager	1 build	1	1	1
Lazy, retained wrapper	0 builds	0	1	1
New wrapper per search	0 builds	0	1	2

The lab uses the same TypeScript center and index as the code views. Eager mode calls warm when opening. The mistaken mode creates a new center inside each search handler. Changing a setting or opening a fresh center resets the owner and its counts.

05 / Review the first demand

What exactly does this owner remember?

Review the wrapper’s lifetime, its failure policy, and the extra state needed when initialization becomes asynchronous.

06 / Give first use a caller

The work moved. Somebody still waits for it.

In an application, a route owner could create one help center when its article snapshot becomes available. Article links call browse; the search form calls search. The route retains that owner across searches and replaces it when switching to another help-center dataset.

That placement decides who pays. Eager setup puts work at opening. Lazy setup puts it at the first search. If setup is expensive and synchronous, it can still block the browser at that moment. Lazy initialization alone neither moves work onto another thread nor makes construction cheaper.

You might prewarm after initial content is usable, or when a visitor signals an intent to search. Our warm method expresses that choice. Prewarming spends work earlier and may spend it unnecessarily; it trades some of lazy initialization’s avoidance for a more predictable first search.

Now articles change. The cached index still describes its owner’s original snapshot. Lazy initialization supplies no automatic invalidation. Creating a new center for the new snapshot keeps that rule explicit. An incrementally updated index is another design with update and synchronization responsibilities.

A shared service also needs the right scope. Two tenants with different articles cannot accidentally use the same cached index. A stable route, dataset version, or service instance can be an owner; a global variable is useful only when global sharing matches the data contract.

When initialization becomes asynchronousRemember the work in progress, too

Suppose the index must be loaded or built in a worker. If you only cache its final value after awaiting it, a second caller can arrive while the cache is still empty and start another initialization. Store the pending promise immediately so both callers share the same attempt.

This TypeScript extension defers the initializer into a promise callback and stores that promise first. It retains a rejection as well as a success.

async-lazy.ts

// TypeScript extension: share pending work and retain success or rejection.
export function lazyAsync<T>(initialize: () => Promise<T>): () => Promise<T> {
	let pending: Promise<T> | undefined;
	return () => (pending ??= Promise.resolve().then(initialize));
	// Store the promise before initialize runs. There is no await-before-store gap.
	// A rejected promise stays cached. Cancellation and retry are separate policies.
}

A retrying wrapper would need an explicit policy for clearing a failed attempt. Cancellation needs an owner too: one departing caller should not blindly abort work that other callers still await.

Failures, recursive demand, and lifetimeChoose the guarantee you actually need

Our expected failure is a returned value. Unexpected exceptions and panics have different native behavior: the TS assignment does not complete after a throw, while Go’s OnceValues replays a panic on later calls. Those mechanisms do not provide one interchangeable retry contract. Go’s panic contract describes the difference.

The initializer must not demand its own unfinished value, directly or through a dependency cycle. A cycle such as search setup → suggestions setup → search setup can recurse or deadlock depending on the mechanism. Keep these initialization dependencies explicit.

Retaining the result also retains its memory for the owner’s lifetime. Lazy creation does not implement eviction or resource disposal. If the value later owns a worker, file, or connection, decide when that owner releases it and what future demand means after disposal.

Build UIs?useState(() => …) is a recipe React keeps for you, and one day a heavy panel will need a load you remember yourself.

Where it already is in your components

React calls your component function on every render, so everything written in it runs again, including the argument you pass to useState. React keeps only the first value. Its docs name the cost: “Although the result of createInitialTodos() is only used for the initial render, you’re still calling this function on every render.” Pass the function itself and “React will only call it during initialization.” That is this lesson’s pattern with a component instance as the owner. A ref filled only while ref.current is null, as the useRef docs show, is the same idea written by hand.

In a React 19.1.0 development mount without StrictMode, the composer below called readDraft six times for its first render and five keystrokes. Given a function instead, React called it once. StrictMode renders twice in development, which made those counts 12 and 2.

A Svelte component’s <script> runs once per instance, not on every update, so let text = $state(readDraft()) already reads storage once: once in a Svelte 5.57 mount across the same five keystrokes. The lazy part of Svelte is $derived. It keeps its expression, and “derived values are not re-evaluated until they are actually read.” The preview’s derived ran zero times while the preview was closed and once when it opened. A derived that nothing reads never ran at all.

When you have to own it

Now the composer gets an emoji picker. Its component and emoji data are a large download, and most messages are sent without opening it. Load it with import() the first time someone opens the panel, and remember the promise, so reopening the panel, a second composer on the page, and a hover that starts the download early all share one load. That is lazyAsync from “When initialization becomes asynchronous” above, with a module as its value.

React’s lazy remembers too. React will not call the loader “until the first time you attempt to render the returned component,” and caches both the promise and its resolved value. It needs a stable owner, which is why the docs say to declare it at the top level of a module. Declared inside a component, every render makes a new wrapper, like the search in section 04 that recreated its center: in React 19.1.0, each re-render of the parent called the loader again and showed the Suspense fallback again. Svelte has no wrapper to misplace, but {#await import(…)} inside {#if open} calls import() again each time the panel opens, so the promise gets its home in <script module>, which runs once for the whole app.

A failure is an outcome too, and here more than one layer remembers it. lazy keeps a rejection: after a failed load, remounting the error boundary showed the same error without calling the loader. The browser can keep it as well. The HTML standard removes a failed fetch from the module map, so by the standard a later import() fetches again. Chromium 153 did not: after a 503, a 404, or a load while offline, importing the same URL again rejected with “Failed to fetch dynamically imported module” and sent no request until the page reloaded. So both samples remember the failure and offer a reload, not a Try again button that cannot succeed there. A new page is a new owner, the same boundary as a new help center.

A composer that restores its saved draft. React computes the useState argument on every render unless you pass a function; Svelte’s script runs once, and its derived preview runs only while the preview is open.

ReactAlready in your code

Composer.tsx

import { useState } from 'react';
import { previewText, readDraft, saveDraft } from './components/draft';

export function Composer() {
	// React calls this function on every render, so the argument below is
	// computed every time: readDraft() reads and parses storage on each
	// keystroke, and React keeps only the result from the first render.
	const [text, setText] = useState(readDraft());
	// Pass the function itself, useState(readDraft), and React calls it once,
	// while initializing. A ref filled only while ref.current is null is the
	// same idea written by hand.
	const [previewing, setPreviewing] = useState(false);

	return (
		<form>
			<textarea
				value={text}
				onChange={(event) => {
					setText(event.target.value);
					saveDraft(event.target.value);
				}}
			/>
			<button type="button" onClick={() => setPreviewing(!previewing)}>
				Preview
			</button>
			{/* Computed inside the branch, so only while the preview is open. */}
			{previewing && <p>{previewText(text)}</p>}
		</form>
	);
}

07 / Recognize the boundary

A useful tool can keep its setup behind first use.

A compiler front end might defer a lookup table until an optional analysis needs it. An application might build a parser, formatter, or search index on first demand. The useful clue is a reusable value with setup that some callers never need.

Go has a wrapper for once-only returned values.

sync.OnceValues is the actual primitive used in our Go program. Its documentation includes reading file contents on first use. The useful connection is that the returned function retains the initialization result for its callers, including concurrent ones.

Read the OnceValues API and example ↗

An initialized value can live in a dedicated cell.

A dedicated cell can separate an empty state from one containing its initialized value. The important policy is the same: store the outcome you want later callers to observe, including expected failure.

08 / Choose when to pay

Delay optional work when first use can carry it.

Lazy setup is a good candidate when a meaningful share of visits never needs the value, initialization has a cost worth avoiding, and callers can handle the first-use delay or failure. Keep the owner visible so you can explain what is shared and how long it remains valid.

Eager initialization may be clearer when the value is always needed, predictable request latency matters more than startup, or setup errors must prevent the service from accepting work. For a cheap value, the branch and lifecycle machinery may not earn their place.

Related questions, different responsibilities
Question	Idea to consider
When should this value be created?	Lazy or eager initialization.
What construction rules belong together?	Factory.
How many instances share one scope?	Singleton or an explicit owner.
Can results be reused for equal arguments?	Memoization, with an argument key.
Who can borrow a reusable resource now?	Object pool, with acquire and return.

Here “payment” and “offline” still perform different lookups. We retain the index, not every query’s answer. That distinction keeps lazy initialization separate from a growing query-result cache.

09 / Take the idea with you

Explain the visit that does zero setup.

Try explaining the help center without the pattern name: opening keeps the articles and a recipe; browsing never calls it; the first search builds one index; later searches use that same index for different questions.

Then change one requirement. The index now loads asynchronously, two searches arrive together, and the first attempt fails. What does the owner remember while loading? What does it remember afterward? Who can start the next attempt? Those answers define the behavior beyond a null check.

Connections to follow nextRelated lessons

Factory can supply the construction recipe. Singleton separates shared scope from creation timing. Object pool adds borrowing and return to reusable resources. Each answers a different question about an object’s life.