🍦 @fizzwiz/vanilla

Lightweight semantics for working with plain JavaScript objects

@fizzwiz/vanilla is a small, dependency‑free library that adds semantic structure to everyday JavaScript objects. It focuses on clarity, safety, and intent, providing higher‑level abstractions for configuration storage, deep object navigation, coercion, and validation — while staying very close to plain JSON data and native objects.

Rather than introducing new data models or DSLs, Vanilla works with what you already have, making object traversal and input handling more expressive and predictable.

The library is designed to be useful both in:

• Application code (configuration, request handling, domain logic)
• Low‑level tooling where introducing heavy frameworks would be undesirable

✨ Features

OptionStore

• Store options keyed by types / classes rather than strings
• Automatically resolve options by walking up the prototype chain
• Ideal for defaults, policies, and behavioral configuration in class hierarchies

ObjNavigator

A semantic cursor over an object tree with a unified failure model.

• get(expr) — retrieve a value or compute one from the current scope
• set(path, value) — assign a value (optionally creating missing nodes)
• delete(path) — remove a property
• select(predicate) — filter object entries in place
• coerce(path, fn, opts) — coerce a value safely
• validate(expr, predicate, opts) — validate values with configurable failure behavior
• within(expr) / without() — scoped navigation across derived objects

All operations share a unified failure model. Each step may specify how failures are handled using the opts argument:

• onError — run a callback
• errorEvent — emit an event
• bubbles — bubble the error to parent navigators
• throws — throw immediately
• payload — control the emitted / thrown value

Once a navigator enters a failed state, subsequent operations become no‑ops unless explicitly handled.

📦 Installation

NPM

npm install @fizzwiz/vanilla

Browser (UMD bundle via jsDelivr)

<script src="https://cdn.jsdelivr.net/npm/@fizzwiz/vanilla/dist/vanilla.bundle.js"></script>
<script>
  const { OptionStore, ObjNavigator } = window.vanilla;

  const nav = ObjNavigator.from({})
    .set('user.profile.name', 'Alice'); 
</script>

🚀 Quick Start

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

// OptionStore example
class Base {}
class Derived extends Base {}

const options = OptionStore.as({});
options.set(Base, 'color', 'blue');
options.get(Derived, 'color'); // 'blue'

// ObjNavigator example
const nav = ObjNavigator.from({})
  .set('user.profile', {})  
  .with('user.profile')    
    .set('name', 'Alice')
    .set('age', 30)
  .without() 

🧭 DOM Navigation Example

ObjNavigator is not limited to JSON data. Because navigation steps can be functions, it can traverse derived or computed structures such as the DOM.

Navigating the DOM with querySelector

<div id="app">
  <section class="profile">
    <span class="name">Alice</span>
    <span class="age">30</span>
  </section>
</div>

const { ObjNavigator } = window.vanilla;

const name = ObjNavigator.from(document)
  .with(doc => doc.querySelector('#app .profile .name'))
  .get('textContent');

console.log(name); // 'Alice'

🛂 Request / Handler Example (Coerce + Validate)

A common use case is handling untrusted input (e.g. HTTP query parameters), where errors should be reported, not thrown. In such cases, it is useful to emit an error event or handle the failure immediately through a dedicated callback.

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

function handleRequest(req, res) {

  const nav = ObjNavigator.from({ ...req.query })
    .on('inputError', () => res.status(400).send('Malformed query'))
    .coerce('limit', Number, { errorEvent: 'inputError' })
    .validate('limit', v => Number.isInteger(v) && v > 0, { errorEvent: 'inputError' });

  if (nav.failed) return; // response already sent

  // ✅ Safe, validated input
  // Business logic here
}

In this model:

• coerce() converts input without throwing
• validate() enforces invariants
• Errors are emitted as events, not thrown
• Business logic only runs if input is known to be valid

🧠 Mental Model

• An ObjNavigator is a cursor over a value

• Each step either:

  • Produces a new value, or
  • Transitions into a failed state

• Failure handling is explicit and composable (callbacks, events, bubbling, throws)

This makes navigation, validation, and transformation linear, readable, and intention‑revealing.

🌐 Documentation & Resources

• Blog: https://vanilla.blog.fizzwiz.cloud
• GitHub Pages: https://fizzwiz.github.io/vanilla

📄 License

MIT