@bun-and-butter/factory

A small helper for lazily building and caching values behind a consistent async API.

@bun-and-butter/factory is useful when you want to create something exactly once per key and then reuse it afterwards. The builder can be synchronous or asynchronous, but the public API always returns a promise so consumers can use one consistent access pattern.

Typical examples are database connections, clients, prepared resources, configuration objects, adapters, or other application services that should be constructed on demand and then reused.

The package supports three styles:

• factory A shared default instance for simple, module-level usage.
• createFactory() Creates isolated factory instances with their own cache.
• AbstractFactory A base class for class-based APIs that still want the same caching behavior.

Quick Start

import { factory } from "@bun-and-butter/factory";

let buildCount = 0;

const getConfig = () =>
	factory.get("app-config", async () => {
		buildCount += 1;

		return {
			environment: "development",
			featureFlags: ["onboarding-v2"],
		};
	});

const first = await getConfig();
const second = await getConfig();

console.log(first);
console.log(second);
console.log("build count:", buildCount); // 1

Quick Start With AbstractFactory

import { AbstractFactory } from "@bun-and-butter/factory";

class DatabaseFactory extends AbstractFactory {
	public getDatabase(name: string) {
		return this.get(`sqlite:${name}`, async () => {
			return connectToDatabase(name);
		});
	}
}

const databases = new DatabaseFactory();

const first = await databases.getDatabase("main");
const second = await databases.getDatabase("main");

console.log(first === second); // true

Why Use It

In many codebases, lazy initialization starts out as a small closure or a module variable:

• a database connection should only be opened once
• a client should only be configured once
• a resource is expensive enough that it should be reused
• the same setup logic appears in multiple places

That works for a while, but it often becomes inconsistent once synchronous and asynchronous initialization mix together or once multiple parts of the application need their own isolated caches.

This package keeps that flow explicit:

• values are cached by key
• sync and async builders use the same API
• concurrent requests for the same key share the same in-flight build
• failed builds are removed from the cache so later calls can retry

Core API

There are three main entry points:

• factory A shared default instance that is convenient when one cache should be reused throughout the application.
• createFactory() Returns a new isolated Factory instance with its own cache.
• AbstractFactory Lets you expose domain-specific methods like getDatabase() or getClient() while delegating the caching behavior to the shared base implementation.

The central method is always get(key, build).

• key Identifies the cached value.
• build Creates the value when it is not cached yet.
• return value Always a Promise<T>, regardless of whether build is sync or async.

Cache Behavior

The cache stores the in-flight promise for each key.

That has a few useful consequences:

• the first call starts the build and stores the promise
• later calls with the same key reuse that promise
• concurrent callers do not trigger duplicate work
• once the promise resolves, future calls still reuse the same resolved promise
• if the build rejects, the failed promise is removed so the next call can try again

This is especially helpful for resources like SQL connections, API clients, or configuration loading where duplicate initialization is undesirable.

Usage Patterns

Shared Factory

Use the shared factory export when one cache should be reused by default:

import { factory } from "@bun-and-butter/factory";

export const getDatabase = () =>
	factory.get("sqlite:main", async () => {
		return connectToDatabase();
	});

This is the smallest and most convenient option, but it also means the cache is shared across every module that imports that same factory instance.

Isolated Factories

Use createFactory() when different parts of the application need separate caches:

import { createFactory } from "@bun-and-butter/factory";

const europeFactory = createFactory();
const usFactory = createFactory();

const europeDb = await europeFactory.get("sqlite:tenant", () => connect("eu"));
const usDb = await usFactory.get("sqlite:tenant", () => connect("us"));

Both factories may use the same key while still building different values, because each factory instance owns its own cache.

Class-Based API

Use AbstractFactory when you want a domain-specific class interface:

import { AbstractFactory } from "@bun-and-butter/factory";

class DatabaseFactory extends AbstractFactory {
	public getDatabase(name: string) {
		return this.get(`sqlite:${name}`, () => connect(name));
	}
}

This is useful when you want factory behavior plus a clear object-oriented API for your application domain.

Error Handling

If build() throws or returns a rejected promise, that failed entry is removed from the cache before the error is rethrown.

That means this works as expected:

1. the first call fails
2. the cache entry is cleared
3. the second call retries the build instead of reusing a rejected result

This makes the helper safe for transient initialization failures.

When To Use Which API

• use factory when one shared cache is the simplest and correct choice
• use createFactory() when isolation matters
• use AbstractFactory when you want domain-specific methods instead of exposing raw keys directly

If you are unsure, start with createFactory() or AbstractFactory() and only move to the shared factory export when shared process-wide state is actually desirable.

Examples

The repository currently includes four examples:

• examples/demo.ts shows the three main usage styles in one file with Bun SQL and SQLite :memory: connections
• examples/shared.ts shows the shared factory export with one cached SQLite connection
• examples/createFactory.ts shows isolated caches created via createFactory()
• examples/abstractFactory.ts shows a class-based wrapper built on AbstractFactory

Design Notes

• the package is intentionally small and focused on one job
• caching happens by explicit string key
• the public API stays consistent for sync and async builders
• concurrency is handled by reusing the same in-flight promise
• isolated and shared usage are both first-class parts of the API

Recommended Pattern

For most applications:

1. choose clear, stable keys that describe the resource being cached
2. keep builder functions small and focused on initialization
3. use createFactory() or AbstractFactory when isolation matters
4. use the shared factory export only when one shared cache is genuinely the intended behavior
5. close or dispose cached resources explicitly when your application shuts down, if those resources require cleanup