Vielzeug

Appearance

sentinel logoSentinelEnvironment
Reactive browser and DOM observations for viewport, network, media query, element size, and intersection state.
Version
v2.0.0
Size
1.4 KB gzip
Dependencies
Zero dependencies
Runtime support
Browser
Key exports
createViewportcreateNetworkcreateMediaQuerycreateElementSizecreateIntersection View all 8 exports
Works well with
ripple ore focus gesture

Why Sentinel? ​

Browser environment APIs use different events, observer callbacks, initial states, and cleanup methods. Sentinel gives them one explicit handle shape and exposes current values as Ripple Readable<T> signals.

ts
// Before
{
  const panel = document.querySelector<HTMLElement>('[data-panel]');
  if (!panel) throw new Error('Panel not found');

  const observer = new ResizeObserver(([entry]) => {
    console.log(entry?.contentRect.width);
  });
  observer.observe(panel);

  // Later
  observer.disconnect();
}

// After
import { createElementSize } from '@vielzeug/sentinel';

{
  const panel = document.querySelector<HTMLElement>('[data-panel]');
  if (!panel) throw new Error('Panel not found');

  const size = createElementSize(panel);
  const unsubscribe = size.subscribe(() => {
    console.log(size.value?.width);
  });

  // Later
  unsubscribe();
  size.dispose();
}
FeatureSentinelNative observer APIsAd hoc event listeners
Bundle size1.4 KBBuilt inApplication-defined
Zero dependencies
Reactive current state
Consistent disposable handle
Shared abort ownership
Ripple composition

Use Sentinel when browser or DOM observations need reactive state, consistent ownership, and composition with Ripple.

Consider native APIs when one isolated observer is sufficient and adding Ripple as a peer dependency is not justified.

Installation ​

sh
pnpm add @vielzeug/sentinel @vielzeug/ripple
sh
npm install @vielzeug/sentinel @vielzeug/ripple
sh
yarn add @vielzeug/sentinel @vielzeug/ripple

Quick Start ​

Create a viewport Sentinel, render its initial state, then react to changes until the page lifetime ends.

ts
import { createViewport } from '@vielzeug/sentinel';

function observeViewport(): () => void {
  const viewport = createViewport();
  const render = () => {
    const { dpr, height, width } = viewport.value;
    console.log(`${width}×${height} at ${dpr}dpr`);
  };

  render();
  const unsubscribe = viewport.subscribe(render);

  return () => {
    unsubscribe();
    viewport.dispose();
  };
}

const stopObserving = observeViewport();
// Call stopObserving() when the owning view unmounts.

Features ​

  • createViewport() — Observe viewport dimensions and device pixel ratio.
  • createNetwork() — Track online status and optional connection details.
  • createMediaQuery() — Observe one media query.
  • createElementSize() — Read content-box dimensions from ResizeObserver.
  • createIntersection() — Track normalized intersection state.
  • dispose() — Release owned browser observers and listeners.
  • SentinelOptions.signal — Abort several Sentinels through one external lifetime.

Documentation ​

See Also ​