`schemas`

(no submodules)

Purpose

The gate.schemas module owns the Zod boundary guards for GatePlugin — construction options and the plugin-specific preset payload. Every public input runs through these schemas before the plugin touches any state; failures surface as AUDIO_FX.INVALID_OPTIONS / AUDIO_FX.INVALID_PRESET with the Zod issue list in context.issues.

Keeping the schemas in a sibling folder follows the package-wide convention: hosts can import the schemas directly, run their own safeParse against UI input, and surface field-level errors before constructing a GatePlugin.

Features

GatePluginOptionsSchema — every field optional, ranged to match the parameter declarations in gate.ts: threshold ∈ [-80, 0] dB, attack ∈ [0.1, 100] ms, hold ∈ [0, 500] ms, release ∈ [1, 1000] ms.
GatePresetDataSchema — z.object({}).strict(). The gate has no plugin-specific state beyond its automatable parameters; the universal parameters map carries everything that round-trips.

Usage: Basic Example

import { GatePluginOptionsSchema } from "@suaveplan/audio-fx-plugin-gate";

const parsed = GatePluginOptionsSchema.safeParse(formValues);
if (!parsed.success) {
    return showFieldErrors(parsed.error.issues);
}
const gate = new GatePlugin(parsed.data);

Usage: Advanced Example

import {
    GatePluginOptionsSchema,
    GatePresetDataSchema,
} from "@suaveplan/audio-fx-plugin-gate";

// Validate an untrusted preset payload from a shared template
// library before applyPreset. The plugin would catch the same issue,
// but the host wants a friendlier error before a plugin instance is
// constructed.
const result = GatePresetDataSchema.safeParse(payload.data);
if (!result.success) {
    return reject("Gate preset is corrupt.");
}

API Reference

GatePluginOptionsSchema — z.ZodObject matching GatePluginOptions. All fields optional and ranged.
GatePresetDataSchema — strict empty object; rejects any unknown keys.

Implementation Notes

GatePluginOptionsSchema uses .finite() on every numeric field so NaN and ±Infinity are rejected at the boundary; the one-pole envelope follower's exp(-1 / (τ · sr)) calculation would otherwise propagate non-finite coefficients into the smoothing state and contaminate every subsequent block.

attack.min(0.1) and release.min(1) match the parameter declarations; values smaller than this break the one-pole smoothing assumption (the coefficient approaches 1 from below) and produce numerical artefacts in single-precision float. hold.min(0) allows a zero-hold gate (closes immediately when the envelope drops), which is useful for hyper-tight drum gates.

threshold.min(-80) covers the practical noise floor of consumer audio; values below -80 dB are effectively "gate never closes" and don't need their own UI affordance. The upper bound at 0 dB is the maximum useful threshold — at 0 dB the gate is essentially always closed since real-world signals rarely exceed 0 dBFS.

The strict empty GatePresetDataSchema rejects any unknown keys so a stale preset format with phantom fields fails loud rather than silently dropping data.

3.2 KiB Raw Blame History

schemas