`tremolo/schemas`

(no submodules)

Purpose

Zod schemas validating the construction-time options and preset payload of TremoloPlugin. These run at the public boundary so any malformed object — wrong waveform name, out-of-range rate, NaN depth — is rejected with AUDIO_FX.INVALID_OPTIONS or AUDIO_FX.INVALID_PRESET before it can corrupt runtime state.

Separating schemas from the plugin module lets index.ts re-export them so callers can introspect the option surface (for forms, RPC validation, or storybook controls) without importing the audio implementation.

Features

TremoloWaveformSchema — z.enum(["sine", "triangle", "square"]) — used in both options and preset payloads.
TremoloPluginOptionsSchema — validates the three optional construction fields with their documented ranges (rate 0.05..20 Hz, depth 0..1, waveform enum).
TremoloPresetDataSchema — .strict() object carrying only waveform; extra fields are rejected.
All numeric fields are z.number().finite() so NaN and Infinity cannot sneak through.

Usage: Basic Example

import { TremoloPluginOptionsSchema } from "@suaveplan/audio-fx-plugin-tremolo";

const parsed = TremoloPluginOptionsSchema.parse({
    initialWaveform: "triangle",
});

Usage: Advanced Example

import {
    TremoloPresetDataSchema,
    TremoloWaveformSchema,
} from "@suaveplan/audio-fx-plugin-tremolo";

// Validate a preset blob coming off the wire before applying it.
function safeApplyPreset(plugin: TremoloPlugin, payload: unknown) {
    const parsed = TremoloPresetDataSchema.safeParse(payload);
    if (!parsed.success) {
        log.warn("dropped bad tremolo preset", parsed.error.issues);
        return;
    }
    plugin.applyPreset({
        version: 1,
        parameters: {},
        presetData: parsed.data,
    });
}

const waveforms = TremoloWaveformSchema.options;
console.log(waveforms); // ["sine", "triangle", "square"]

API Reference

TremoloWaveformSchema: z.ZodEnum<["sine", "triangle", "square"]>
TremoloPluginOptionsSchema: z.ZodObject<{ initialRateHz?, initialDepth?, initialWaveform? }>
TremoloPresetDataSchema: z.ZodObject<{ waveform: TremoloWaveform }, "strict">

Implementation Notes

TremoloWaveformSchema is exported as a named schema (not inlined) so the same value is reused by TremoloPluginOptionsSchema.initialWaveform and TremoloPresetDataSchema.waveform. That guarantees both validation paths agree byte-for-byte on the legal waveform set — adding a fourth waveform in a future revision is a one-line change in schemas.ts.

TremoloPresetDataSchema uses .strict() for the same reason as the other plugins: unknown fields almost always indicate a payload from a sibling plugin or a forwards-incompatible schema. Silent rejection at the boundary is much less harmful than partial application, which can leave the plugin in a half-restored state. The combined "waveform-must-be-known, payload-must-be-exact" stance keeps the preset surface stable across plugin versions.

3.0 KiB Raw Blame History

tremolo/schemas