67 lines
3.0 KiB
Markdown
67 lines
3.0 KiB
Markdown
# `tremolo/schemas`
|
|
|
|
<!-- begin:auto-docs -->
|
|
_(no submodules)_
|
|
<!-- end:auto-docs -->
|
|
|
|
## 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
|
|
|
|
```ts
|
|
import { TremoloPluginOptionsSchema } from "@suaveplan/audio-fx-plugin-tremolo";
|
|
|
|
const parsed = TremoloPluginOptionsSchema.parse({
|
|
initialWaveform: "triangle",
|
|
});
|
|
```
|
|
|
|
## Usage: Advanced Example
|
|
|
|
```ts
|
|
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.
|