`provider/provider-options`

Purpose

Defines the AudioProviderOptions shape consumed by <AudioProvider>, the Zod schema that validates it, and the parseAudioProviderOptions helper that converts a Zod failure into a ReactAudioError whose code is REACT_AUDIO.INVALID_OPTIONS. The schema is intentionally permissive about deep adapter/transport internals — those are validated again by their owning packages (@suaveplan/audio-engine-browser revalidates BrowserAdapterOptions, @suaveplan/audio-transport revalidates transport options) — but strict about the provider-level shape so a typo such as adaptor fails at the React boundary instead of mid-way through async init.

Features

AudioProviderOptionsSchema — strict-object Zod schema rejecting unknown top-level keys.
AudioProviderOptions TypeScript interface mirroring the schema.
parseAudioProviderOptions(input) — single-call validator that throws ReactAudioError(REACT_AUDIO.INVALID_OPTIONS) on failure.
PluginFactoryEntry shape for the optional auto-registration list.
PresetStore shape for the pluggable preset persistence layer.

Usage: Basic

import { parseAudioProviderOptions } from "@suaveplan/react-audio/provider";

const options = parseAudioProviderOptions({
    adapter: { sampleRate: 48000 },
    transport: { bpm: 120 },
    sampleRateHz: 60,
});

Usage: Advanced

import {
    parseAudioProviderOptions,
    type AudioProviderOptions,
    type PluginFactoryEntry,
} from "@suaveplan/react-audio/provider";

const factories: ReadonlyArray<PluginFactoryEntry> = [
    { pluginType: "delay", factory: () => makeDelay() },
    { pluginType: "reverb", factory: () => makeReverb() },
];

const opts: AudioProviderOptions = {
    plugins: factories,
    sampleRateHz: 30, // half-rate sampling for low-power devices
};

parseAudioProviderOptions(opts);

API Reference

AudioProviderOptions — { adapter?, transport?, plugins?, presetStore?, sampleRateHz?, slotRenderers? }.
PluginFactoryEntry — { pluginType, factory }.
PresetStore — { save(kind, id, payload), load(kind, id) }.
parseAudioProviderOptions(input) — returns a frozen-shape value on success, throws ReactAudioError otherwise.

Implementation Notes

The schema is .strict() on the top-level object so unknown keys fail validation rather than being silently dropped — this catches shape regressions early. Deeper objects (transport, presetStore) use .passthrough() because their authoritative schemas live in the owning packages; revalidating their full shape here would couple this package to internal layouts that already validate at construction. sampleRateHz is clamped to [1, 240] to keep requestAnimationFrame sampling in a sensible band: below 1 the UI feels frozen, above 240 the work done per frame outpaces typical display refresh.

2.8 KiB Raw Blame History

provider/provider-options