2.1.0 • Published 6d ago

@vielzeug/arsenal

Licence

—

Version

2.1.0

Deps

Size

777 kB

Vulns

Weekly

Stars

Summary Dependency Versions

Vielzeug

30 independent, zero-dependency TypeScript packages for modern JavaScript

Documentation • Examples • Contributing

Vielzeug (German for "many tools") is a curated ecosystem of zero-dependency, tree-shakeable TypeScript packages. Each one solves a focused problem and ships as ESM + CJS with full type declarations.

Type-Safe — built with TypeScript from the ground up, strict mode throughout
Zero Dependencies — no external runtime deps; inter-package deps only
Framework Agnostic — works with React, Vue, Svelte, Angular, or vanilla JS
Tree-Shakeable — import only what you need, pay only for what you use
Well-Tested — comprehensive vitest coverage on every package
Production Ready — battle-tested in real-world applications

Packages

@vielzeug/ripple – Reactive Signals

Fine-grained reactive state with signals, computed values, effects, and batch updates.

pnpm add @vielzeug/ripple

Key Features:

Fine-grained signals with computed(), effect(), batch(), watch(), and scope()
store() for reactive objects with deep update tracking
Zero dependencies (7.0 KB min / 2.4 KB gz)

Documentation • Examples

@vielzeug/ore – Web Component Primitives

Lightweight, type-safe web component authoring with reactive state, typed props, and automatic rendering.

pnpm add @vielzeug/ore

Key Features:

Reactive state management with automatic re-rendering
Type-safe component definitions and prop helpers
Shadow DOM with automatic styling and form-associated elements
Event handling, lifecycle hooks, and helpers like live, when, styleMap, until (18 KB min / 5.0 KB gz)

Documentation • Examples

@vielzeug/refine – Accessible Web Components

Accessible, themeable web components built on top of @vielzeug/ore. Works with any framework or vanilla HTML.

pnpm add @vielzeug/refine

Key Features:

Drop-in accessible components — button, input, select, checkbox, accordion, tooltip, and more
Framework-agnostic — plain custom elements, no framework required
Full theming via CSS custom properties
Tree-shakeable per-component imports (@vielzeug/refine/button, @vielzeug/refine/input, …)

Documentation • Examples

@vielzeug/clockwork – Finite State Machines

Framework-neutral typed state machines with pure transitions, immutable snapshots, and owned actors.

pnpm add @vielzeug/clockwork

Key Features:

Fully typed flat states, events, guards, and transitions
Pure context reducers with immutable snapshots
Post-commit effects, async invoke, and delayed transitions
Actor subscriptions, cancellation, and disposal
Framework-neutral runtime with zero dependencies

Documentation • Examples

@vielzeug/flux – Reactive Streams

Minimal push streams with subscription-owned cancellation, explicit buffering, and ecosystem adapters.

pnpm add @vielzeug/flux

Key Features:

stream() factory for cold, reusable, pipeable streams
Subscription owns cancellation; streams have no global lifecycle
createChannel() for bounded-replay hot multicast state
Explicit async-buffer capacity and overflow policy
Ecosystem adapters on dedicated Ripple, Herald, Pulse, and Courier subpaths

Documentation • Examples

@vielzeug/forge – Form State Management

Effortless, type-safe form state and validation for modern web applications.

pnpm add @vielzeug/forge

Key Features:

Type-safe form state with inferred types
Field-level and form-level validation
Reactive subscriptions
Works with @vielzeug/spell, Zod, Valibot, or any Standard Schema library (7.2 KB min / 3.0 KB gz)

Documentation • Examples

@vielzeug/spell – Schema Validation

Lightweight, type-safe schema validation with async support and zero dependencies.

pnpm add @vielzeug/spell

Key Features:

Fluent schema API — s.object(), s.string(), s.number(), s.array(), and more
Precise input/output typing with InferInput<T> and Infer<T>
Async validation, custom refinements, and transforms
Comprehensive error handling with messagesAt() (14 KB min / 2.8 KB gz)

Documentation • Examples

@vielzeug/courier – HTTP Client

Modern, type-safe HTTP client with explicit cache keys, direct mutations, and AsyncIterable streams.

pnpm add @vielzeug/courier

Key Features:

One client for HTTP, queries, mutations, and streams
Keyed cache entries with explicit fetch definitions and in-flight deduplication
Direct mutations with explicit cache updates
Abortable SSE and HTTP streams (10 KB min / 3.4 KB gz)

Documentation • Examples

@vielzeug/pulse – WebSocket Client

Full-featured WebSocket client with typed messaging, channel multiplexing, reactive presence, and auto-reconnect.

pnpm add @vielzeug/pulse @vielzeug/ripple

Key Features:

Typed event maps — payload types inferred from the event key
Channel multiplexing and room management
Reactive status, latency, and presence signals via @vielzeug/ripple
Auto-reconnect with configurable backoff and heartbeat (ping/pong) support
Typed error hierarchy: ConnectionError, TimeoutError, DisposedError, and more

Documentation • Examples

@vielzeug/vault – Browser Storage

Powerful, type-safe browser storage with a unified API for IndexedDB and LocalStorage.

pnpm add @vielzeug/vault

Key Features:

Unified API for IndexedDB, LocalStorage, SessionStorage, and in-memory stores
Advanced querying and filtering with table()
TTL (Time-To-Live) expiration and schema migrations (16 KB min / 4.5 KB gz)

Documentation • Examples

@vielzeug/wayfinder – Client-Side Routing

Lightweight, type-safe client-side router with middleware and guards.

pnpm add @vielzeug/wayfinder

Key Features:

Route parameters and query string parsing
Middleware system for auth, logging, and redirects
Hash and History mode with memory history for testing
Nested routes and layouts (9.0 KB min / 3.1 KB gz)

Documentation • Examples

@vielzeug/ward – RBAC & Permissions

Flexible, type-safe role-based access control with wildcards and predicate rules.

pnpm add @vielzeug/ward

Key Features:

Role-based access control (RBAC) with wildcard support
Dynamic attribute-based rules (ABAC) with owns() helper
Multi-action checks (canAll, canAny) and allowedActions() listing
Explainable deny diagnostics, user-bound permits, and decision caching (5.9 KB min / 2.0 KB gz)

Documentation • Examples

@vielzeug/conduit – Dependency Injection

Compact, type-safe DI container built around typed tokens and explicit scopes.

pnpm add @vielzeug/conduit

Key Features:

Token-based typed dependency registration
Async factory support and child containers
Singleton, transient, and scoped lifetimes
using disposal (8.0 KB min / 2.1 KB gz)

Documentation • Examples

@vielzeug/rune – Structured Logging

Structured, zero-dependency logging with scoped namespaces and non-blocking remote transport.

pnpm add @vielzeug/rune

Key Features:

Log levels (debug → error) with priority-based filtering
scope(name) and child() for isolated namespaced loggers
Browser CSS badge styling — symbol, icon, or text variants
Non-blocking remote handler (Sentry, Datadog, custom endpoint)
time/timeEnd, table, group, assert backed by native console APIs (6.8 KB min / 2.7 KB gz)

Documentation • Examples

@vielzeug/keymap – Keyboard Shortcut Manager

Headless keyboard shortcut manager with chord sequences, context layers, and disposable bindings.

pnpm add @vielzeug/keymap

Key Features:

createKeymap() — bind handlers to shortcuts with chord sequence support (e.g. Ctrl+K Ctrl+S)
createKeymapLayer() for context-scoped bindings that override the base layer
formatShortcut() and parseShortcut() utilities for display and programmatic use
Platform-aware modifier detection (detectModKey) — Meta on macOS, Ctrl elsewhere
Disposable bindings with using cleanup

Documentation • Examples

@vielzeug/lingua – Internationalization

Lightweight, type-safe i18n with pluralization, interpolation, and async loading.

pnpm add @vielzeug/lingua

Key Features:

Type-safe translation keys with autocomplete
Pluralization rules and interpolation
Async translation loading and lazy namespaces
Framework agnostic (7.4 KB min / 1.6 KB gz)

Documentation • Examples

@vielzeug/herald – Typed Event Bus

Lightweight typed event bus with on, once, emit, wait, waitAny, and async streams.

pnpm add @vielzeug/herald

Key Features:

Fully typed event maps — payload types inferred from the event key
once() for single-fire subscriptions
onError and onDispatch hooks for logging and error handling
dispose() for clean teardown; createTestBus() helper for testing
Zero dependencies

Documentation • Examples

@vielzeug/familiar – Web Worker Pool

Run CPU-intensive module-worker tasks off main thread with typed pooling, cancellation, and explicit lifecycle.

pnpm add @vielzeug/familiar

Key Features:

createWorker(url) — typed pool backed by an ES module worker
exposeTask() / exposeStream() — one versioned worker protocol
Timeout and AbortSignal cancellation for waiting, queued, and active work
batch() and createTaskGroup() — task-pool composition helpers
createTestWorker() — faithful in-process task-pool testing
No third-party runtime dependencies

Documentation • Examples

@vielzeug/dnd – Drag and Drop

Framework-agnostic drag-and-drop helpers for file drop zones and sortable lists.

pnpm add @vielzeug/dnd

Key Features:

createDropZone() with MIME type, wildcard, and file extension filtering
onDropRejected callback and counter-based hover state
createSortable() for native sortable lists with data-sort-id
Drag handles, dynamic list refresh, and dispose() / using cleanup
Zero dependencies

Documentation • Examples

@vielzeug/ledger – Undo/Redo History

Async undo/redo command history with reactive canUndo / canRedo signals.

pnpm add @vielzeug/ledger

Key Features:

createLedger() — execute, undo, and redo typed Command objects
compose() to group multiple commands into a single undoable unit
Reactive canUndo and canRedo signals via @vielzeug/ripple
Configurable history limit and async execute/rollback support
Typed error hierarchy: LedgerExecutionError, LedgerRollbackError

Documentation • Examples

@vielzeug/orbit – Floating Positioning

Lightweight floating-element positioning for tooltips, dropdowns, popovers, and menus.

pnpm add @vielzeug/orbit

Key Features:

positionFloat() to compute and apply left / top in one call
computePosition() for low-level { x, y, placement } control
Middleware pipeline: offset, flip, shift, and size
autoUpdate() for scroll, resize, and element-size updates
Zero dependencies

Documentation • Examples

@vielzeug/necromancer – DOM Animations

Lifecycle-owned Web Animations API primitives for element, group, and positional FLIP layout animation.

pnpm add @vielzeug/necromancer

Key Features:

animate() with direct native animation access; animateEach() with group ownership
Self-contained, one-shot positional FLIP transitions
System reduced-motion support with instant keyframes and explicit reduced outcomes
SSR-safe root import with browser-only animation execution
Zero runtime dependencies (3.2 KB min / 1.5 KB gz)

Documentation • Examples

@vielzeug/prism – Reactive SVG Charts

Reactive SVG charting library with signal-driven updates — line, bar, area, pie, and sparkline charts.

pnpm add @vielzeug/prism

Key Features:

createLineChart(), createBarChart(), createAreaChart(), createPieChart(), createSparkline()
Signal-driven reactivity via @vielzeug/ripple — data updates re-render automatically
Built-in scales: linearScale(), bandScale(), timeScale()
Tooltips, crosshairs, legends, and axis configuration
Theming via CSS custom properties and setTheme()
Zero external dependencies (32 KB min / 10.3 KB gz)

Documentation • Examples

@vielzeug/sandbox – Sandboxed iframe Runtime

Safe sandboxed iframe runtime with a typed postMessage bridge for executing untrusted or AI-generated UI code.

pnpm add @vielzeug/sandbox

Key Features:

createSandbox() — mount a sandboxed iframe in any container element
sandbox.render(html) — atomically replace the iframe document; generation-stamped to drop stale messages
Typed onMessage subscription with SandboxMessage discriminated union
buildDocument() and buildCsp() helpers for constructing sandboxed HTML with a strict CSP
createSandboxTestHelpers() for unit-testing consumers without real iframe infrastructure

Documentation • Examples

@vielzeug/scout – Fuzzy Search

Fast fuzzy search with a trigram index, per-field weighting, match highlighting, and an optional reactive layer.

pnpm add @vielzeug/scout

Key Features:

createIndex() — build a trigram-indexed search index from any array of objects
createSearch() for single-shot queries and createReactiveSearch() for signal-driven live filtering
Per-field boost weights and configurable score threshold
highlight() and highlightField() for match range extraction and rendering helpers
toSearchMatcher() and toFilterPredicate() adapters for integration with existing pipelines

Documentation • Examples

@vielzeug/sourcerer – Reactive Data Sources

Reactive local and remote data sources with pagination, filtering, sorting, and search.

pnpm add @vielzeug/sourcerer

Key Features:

createLocalSource() and createPageSource() with atomic source snapshots
Reactive items, total, loading, and error signals
Built-in fuzzy search, multi-field sorting, and pagination
Zero dependencies

Documentation • Examples

@vielzeug/scroll – Virtual Lists

Framework-agnostic virtual list engine that renders only visible rows.

pnpm add @vielzeug/scroll

Key Features:

Virtualized rendering with configurable overscan
Fixed and measured variable-height rows
Programmatic scrolling (scrollToIndex, scrollToOffset)
Framework-agnostic callback API
Zero dependencies

Documentation • Examples

@vielzeug/tempo – Date & Time

Temporal-powered date and time utilities for modern TypeScript apps.

pnpm add @vielzeug/tempo

Key Features:

Built on the TC39 Temporal proposal
Timezone-aware date arithmetic, formatting, and parsing
Calendar system support and duration helpers
Zero dependencies

Documentation • Examples

@vielzeug/coins – Monetary Arithmetic

Bigint-based monetary arithmetic with formatting, exchange, and allocation — no IEEE-754 rounding surprises.

pnpm add @vielzeug/coins

Key Features:

money('19.99', USD) for exact decimal values and explicit { unit: 'minor' } bigint construction
Exact arithmetic, aggregation, and allocation with named rounding options
Deterministic currency definitions; Intl.NumberFormat only controls presentation
exchangeRate() and exchange() for exact currency conversion
Zero dependencies

Documentation • Examples

@vielzeug/arsenal – Utility Library

75+ tree-shakeable helpers for arrays, objects, strings, async, math, and more.

pnpm add @vielzeug/arsenal

Key Features:

75+ utilities fully typed with TypeScript inference
Selector-based and multi-field sorting with sort()
Fuzzy search with search(), deep diff with diff(), deep merge, pruning, and more
Tree-shakeable by design — 0.1–0.5 KB per utility, zero dependencies

Documentation • Examples

@vielzeug/codex – AI / MCP Server

MCP server exposing all Vielzeug documentation, package APIs, and component metadata to AI clients.

# Run without installing:
npx -y @vielzeug/codex

# Or add to your project:
pnpm add @vielzeug/codex

Key Features:

Stdio and HTTP transport modes
Tools: list-packages, search-packages, get-docs, get-package-api, list-components, get-component, and more
Works with Claude Desktop, Copilot Chat, and any MCP-compatible client

Documentation • Examples

@vielzeug/assay – DOM Testing Primitives

Framework-agnostic DOM testing primitives — scoped queries, synchronous event dispatch, and deterministic async waiting.

pnpm add -D @vielzeug/assay

Key Features:

within() — scoped query/queryAll/queryByText/queryByTestId and shadow-DOM-aware queryInShadow/queryPart
Named exact event dispatchers such as fireClick(), fireInput(), and fireKeyDown()
waitUntil()/retry()/waitForEvent() — cancellable async waiting with typed timeout errors
Zero dependencies, no coupling to any UI framework — used by @vielzeug/ore/testing and Refine's internal test suite

Documentation • Examples

Quick Start

Install individual packages as needed:

# Using pnpm (recommended)
pnpm add @vielzeug/forge @vielzeug/courier

# Using npm
npm install @vielzeug/forge @vielzeug/courier

# Using yarn
yarn add @vielzeug/forge @vielzeug/courier

Example: Typed Form with API Integration

import { createForm } from '@vielzeug/forge';
import { customValidator } from '@vielzeug/forge/spell';
import { s, type Infer } from '@vielzeug/spell';
import { createCourier } from '@vielzeug/courier';
import { createLogger } from '@vielzeug/rune';

const log = createLogger('auth');

// Define and validate the shape
const LoginSchema = s.object({
  email: s.string().email(),
  password: s.string().min(8),
});
type LoginInput = Infer<typeof LoginSchema>;

// HTTP client
const courier = createCourier({ baseUrl: 'https://api.example.com' });

// Form wired to the schema
const form = createForm<LoginInput>({
  initialValues: { email: '', password: '' },
  validate: customValidator(LoginSchema),
});

form.submit(async (values) => {
  try {
    const user = await courier.mutate({
      request: ({ signal }) => courier.post('/auth/login', { body: values, signal }),
    });
    log.info('Login successful', { user });
  } catch (error) {
    log.error('Login failed', error);
  }
});

Development

Prerequisites

Node.js >= 22.0.0 (see .nvmrc)
pnpm >= 10.0.0
Rush (npm install -g @microsoft/rush)

Setup

# Clone the repository
git clone https://github.com/helmuthdu/vielzeug.git
cd vielzeug

# Install all dependencies (via Rush)
pnpm setup

# Build all packages
pnpm build

# Run all tests
pnpm test

# Start documentation site
pnpm docs:dev

Project Structure

vielzeug/
├── packages/
│   ├── arsenal/       # 75+ utility functions
│   ├── assay/         # DOM testing primitives
│   ├── clockwork/     # Finite state machines
│   ├── codex/         # AI / MCP server
│   ├── coins/         # Monetary arithmetic & formatting
│   ├── conduit/       # Dependency injection
│   ├── courier/       # HTTP client & query management
│   ├── dnd/           # Drag-and-drop utilities
│   ├── familiar/      # Web Worker pool
│   ├── flux/          # Reactive streams & operators
│   ├── forge/         # Form state management
│   ├── herald/        # Typed event bus
│   ├── keymap/        # Keyboard shortcut manager
│   ├── ledger/        # Undo/redo command history
│   ├── lingua/        # Internationalization
│   ├── orbit/         # Floating element positioning
│   ├── ore/           # Web component primitives
│   ├── prism/         # Reactive SVG charts
│   ├── pulse/         # WebSocket client
│   ├── refine/        # Accessible web components (built on ore)
│   ├── ripple/        # Reactive signals and state
│   ├── rune/          # Structured logging
│   ├── sandbox/       # Sandboxed iframe runtime
│   ├── scout/         # Fuzzy search with trigram index
│   ├── scroll/        # Virtual list engine
│   ├── sourcerer/     # Reactive data sources
│   ├── spell/         # Schema validation
│   ├── tempo/         # Date & time utilities
│   ├── vault/         # Browser storage (IndexedDB + LocalStorage)
│   ├── ward/          # RBAC & permission management
│   ├── wayfinder/     # Client-side routing
├── docs/              # VitePress documentation
└── common/            # Shared Rush configuration

Scripts

pnpm setup          # Rush install — install all dependencies
pnpm build          # Rush build — build all packages
pnpm test           # Run all tests (vitest)
pnpm lint           # Check code with Biome
pnpm fix            # Apply Biome safe fixes
pnpm docs:dev       # Start docs dev server (VitePress)
pnpm docs:build     # Build documentation

Bundle Sizes

All sizes are minified + gzipped production builds:

Package	Minified	Gzipped	Dependencies
`@vielzeug/arsenal`	25.0 KB (full bundle)	9.0 KB	0
`@vielzeug/assay`	4.2 KB	1.5 KB	0
`@vielzeug/clockwork`	8.5 KB	3.1 KB	1*
`@vielzeug/codex`	0.7 KB	0.4 KB	0
`@vielzeug/coins`	9.5 KB	3.5 KB	0
`@vielzeug/conduit`	7.8 KB	2.6 KB	0
`@vielzeug/courier`	21.9 KB	7.4 KB	1*
`@vielzeug/ore`	28.9 KB	10.5 KB	2*
`@vielzeug/dnd`	9.7 KB	3.7 KB	0
`@vielzeug/familiar`	11.3 KB	4.2 KB	0
`@vielzeug/flux`	12.9 KB	3.6 KB	1*
`@vielzeug/forge`	17.9 KB	5.6 KB	0
`@vielzeug/herald`	6.0 KB	2.4 KB	0
`@vielzeug/keymap`	—	—	0
`@vielzeug/ledger`	—	—	1*
`@vielzeug/lingua`	9.1 KB	3.7 KB	0
`@vielzeug/necromancer`	3.2 KB	1.5 KB	0
`@vielzeug/orbit`	12.7 KB	4.8 KB	0
`@vielzeug/prism`	33.7 KB	11.0 KB	2*
`@vielzeug/pulse`	13.4 KB	4.6 KB	1*
`@vielzeug/ripple`	16.3 KB	5.4 KB	0
`@vielzeug/rune`	7.8 KB	3.4 KB	0
`@vielzeug/sandbox`	—	—	0
`@vielzeug/scout`	—	—	1*
`@vielzeug/scroll`	18.3 KB	6.2 KB	0
`@vielzeug/refine`	~3–6 KB per component	~1–2 KB	3*
`@vielzeug/sourcerer`	17.2 KB	5.2 KB	1*
`@vielzeug/spell`	49.1 KB	11.9 KB	0
`@vielzeug/tempo`	12.5 KB	4.0 KB	0
`@vielzeug/vault`	26.9 KB	8.7 KB	0
`@vielzeug/ward`	7.1 KB	2.6 KB	0
`@vielzeug/wayfinder`	16.3 KB	5.9 KB	0

* Only depends on other @vielzeug packages. arsenal is tree-shakeable — individual utilities average 0.1–0.8 KB each. refine is designed for per-component imports; the full bundle is ~453 KB / 95 KB.

Browser & Runtime Support

Browsers: All modern browsers (Chrome, Firefox, Safari, Edge — Baseline 2023+)
Node.js: v22.0.0 or higher
TypeScript: v6.0.0 or higher
Module formats: ESM + CJS, with full .d.ts declarations

Contributing

We welcome contributions! Here's how you can help:

Report Bugs: Open an issue
Suggest Features: Start a discussion
Submit PRs: Fork, create a branch, and submit a pull request

Contribution Guidelines

Fork the repository
Create your feature branch (git checkout -b feat/my-feature)
Commit using conventional commits (git commit -m 'feat(arsenal): add lerp helper')
Push to the branch (git push origin feat/my-feature)
Open a Pull Request

Please ensure:

All tests pass (pnpm test)
Code follows the style guide (pnpm lint)
Documentation is updated if needed

License

MIT Helmuth Saatkamp

Each package is individually licensed under the MIT License. See the LICENSE file in each package directory for details.

FAQ

Why Vielzeug instead of [other library]?

Vielzeug packages are designed to work together as a coherent system while remaining individually useful. The fantasy naming (ripple, forge, spell, herald…) reflects the same philosophy: each package is a distinct spell that, combined, gives you a complete grimoire.