Vielzeug
sentinel logoSentinelEnvironment
Subscribable browser and DOM snapshots for viewport, network, media query, element size, intersection state, and screen wake lock.
Version
v26.10.5
Size
2.0 KB gzip
Runtime support
Browser
Key exports
createViewportcreateNetworkcreateMediaQuerycreateElementSizecreateIntersection View all 10 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 external-store shape with snapshot reads, subscriptions, and disposal.

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.getSnapshot()?.width);
  });

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

Use Sentinel when browser or DOM observations need consistent snapshot reads, subscriptions, and ownership.

Consider native APIs when one isolated observer is sufficient and a shared lifecycle abstraction adds no value.

Installation ​

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

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.getSnapshot();
    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.
  • createWakeLock(): Prevent the screen from sleeping during active use.
  • createFullscreen(): Track and drive document fullscreen state.
  • dispose(): Release owned browser observers and listeners.
  • SentinelOptions.signal: Abort several Sentinels through one external lifetime.

Documentation ​

See Also ​