🏠 Intro

🏠 Introduction to @fizzwiz/vanilla

@fizzwiz/vanilla is a lightweight, dependency-free library that provides semantic helpers for working with plain JSON objects.

A vanilla object is simple, serializable, and flexible. This library lets you manage nested data structures and type-based options safely and consistently, without introducing complex classes or frameworks.

---

Core Concepts

OptionStore

• Store options keyed by classes / types.
• Retrieve options for instances by automatically walking up the prototype chain.
• Ideal for defining default configurations or behavioral policies per type hierarchy.

ObjNavigator

• Navigate, retrieve, and modify nested values using dot-separated paths or arrays of keys.
• Automatically create missing intermediate objects when needed.
• Scoped navigation via within() and returning to parent objects with without().
• Refine or clean up data with delete() and select().
• Safely transform and validate fields using coerce() and validate().
• Errors can be emitted as events, handled via callbacks, or optionally thrown, depending on opts.

Example Usage

import { ObjNavigator } from '@fizzwiz/vanilla';

const opts = { errorEvent: 'inputError' }; // errors will be converted to events and emitted

const nav = new ObjNavigator({ ...req.query })
  .on('inputError', () => res.status(400).send('Malformed query'))
  .coerce('value', v => Number(v), opts)
  .validate('value', v => v >= 0, opts);

if (nav.failed) return;

// ✅ Business logic here — guaranteed safe input

---

Philosophy

• Simplicity: Work directly with plain objects without introducing heavy frameworks.
• Safety: Avoid runtime errors when navigating or manipulating nested data.
• Flexibility: Integrate seamlessly with existing JSON data, API payloads, or derived structures.

By providing OptionStore and ObjNavigator, @fizzwiz/vanilla adds structure and semantic meaning to vanilla objects while keeping your data fully JSON-compatible.