`provider/chain-map`

Purpose

ChainMap is the provider-scoped lazy registry of PluginChain instances, keyed by track id. The hook usePluginChain(trackId) calls getOrCreate(trackId) to fetch (or create) the chain associated with that track, so two consumers asking for the same id see the same chain instance. The map's dispose() is wired into the provider's unmount path to dispose every chain it holds.

Features

Lazy creation: chains are constructed on first request, not eagerly at mount.
Identity stable for the same trackId across calls.
Configurable default channels / sampleRate / blockSize at construction; per-call overrides via getOrCreate(id, config).
Inert after dispose() — further calls throw.

Usage: Basic

import { ChainMap, ProviderBusRegistry } from "@suaveplan/react-audio/provider";

const buses = new ProviderBusRegistry();
const chains = new ChainMap(buses);

const chainA = chains.getOrCreate("track-a");
const sameChainA = chains.getOrCreate("track-a"); // === chainA

Usage: Advanced

import { ChainMap, ProviderBusRegistry } from "@suaveplan/react-audio/provider";

const buses = new ProviderBusRegistry();
const chains = new ChainMap(buses, {
    channels: 1,
    sampleRate: 44_100,
    blockSize: 256,
});

// Per-track override:
const monoChain = chains.getOrCreate("voice", { channels: 1 });
const stereoChain = chains.getOrCreate("master", { channels: 2 });

API Reference

new ChainMap(buses, defaultConfig?).
getOrCreate(trackId, config?): PluginChain.
get(trackId): PluginChain | undefined.
list(): ReadonlyArray<string>.
dispose(): void.

Implementation Notes

The map stores fully-constructed PluginChain instances; there is no proxy or wrapping. dispose() is idempotent and iterates the internal map's values(), calling chain.dispose() on each. After dispose the map is cleared so a late get() returns undefined and a late getOrCreate() throws. The Phase-1 default channels / sampleRate / blockSize line up with the typical browser audio context defaults; consumers who need different shapes pass them through getOrCreate(id, config) per chain. The buses argument is held by reference and passed into every chain — keeping a single bus registry for the whole provider subtree means sidechain wiring across tracks remains coherent.

2.3 KiB Raw Permalink Blame History

provider/chain-map