ResQ Systems npm Packages
Registry workspace for all ResQ Systems npm packages published under the @resq-systems scope. Provides the shared UI component library, zero-dependency data structures, and standalone server/client utilities for the ResQ Systems autonomous disaster response platform.
Architecture
graph TB
subgraph repo["resq-software/npm"]
direction TB
subgraph foundation["Foundation"]
constants["@resq-systems/constants<br/><small>design tokens · brand · zero deps</small>"]
types["@resq-systems/types<br/><small>nominal/branded types · zero deps</small>"]
end
subgraph frontend["Frontend"]
ui["@resq-systems/ui<br/><small>63 components + flight instruments · Radix + Tailwind v4</small>"]
end
subgraph algorithms["Algorithms"]
dsa["@resq-systems/dsa<br/><small>11 modules · zero deps</small>"]
math["@resq-systems/math<br/><small>expression engine · Pratt parser · zero deps</small>"]
end
subgraph infra["Infrastructure"]
http["@resq-systems/http"]
logger["@resq-systems/logger"]
security["@resq-systems/security"]
ratelimit["@resq-systems/rate-limiting"]
email["@resq-systems/email-templates<br/><small>React Email · Effect contract</small>"]
end
subgraph utilities["Utilities"]
helpers["@resq-systems/helpers"]
decorators["@resq-systems/decorators"]
end
subgraph telemetry["Telemetry"]
analytics["@resq-systems/analytics<br/><small>PostHog + GA4 · cross-subdomain</small>"]
wsclient["@resq-systems/telemetry<br/><small>reconnecting WebSocket · fan-out</small>"]
geomap["@resq-systems/map<br/><small>MapLibre + react-map-gl</small>"]
nav["@resq-systems/nav<br/><small>geometry · CPA/TCPA · derived quantities</small>"]
end
end
constants --> ui
constants --> email
wsclient --> geomap
nav --> geomap
nav --> ui
foundation --> apps["Consumer Apps"]
frontend --> apps
algorithms --> apps
infra --> apps
utilities --> apps
telemetry --> apps
style repo fill:#0d0f14,stroke:#222b42,color:#f5f5f7
style foundation fill:#141722,stroke:#5db8ff,color:#f5f5f7
style frontend fill:#141722,stroke:#388feb,color:#f5f5f7
style algorithms fill:#141722,stroke:#25c68a,color:#f5f5f7
style infra fill:#141722,stroke:#f5a623,color:#f5f5f7
style utilities fill:#141722,stroke:#9ba3b5,color:#f5f5f7
style telemetry fill:#141722,stroke:#b478ff,color:#f5f5f7
style apps fill:#1a1e2e,stroke:#e24b4a,color:#f5f5f7
Packages
| Package | Description | Deps | Docs |
|---|
@resq-systems/constants | Shared design tokens (oklch + email-safe hex), brand identity, and cross-app values — one source of truth | zero deps | README |
@resq-systems/types | Nominal/branded type toolkit — Brand, Opaque, NumberRange, numeric brands, assertNever, and type-level test helpers | zero deps | README |
@resq-systems/ui | React component library — dark-first oklch color system, WCAG AA, subpath exports; 63 components incl. the basic-six flight instruments | radix-ui, tailwindcss | README · Storybook |
@resq-systems/dsa | Data structures & algorithms — graph, heap, trie, bloom filter, distance, LRU cache, queue | zero deps | README |
Examples
Working examples showing the packages in action:
| Example | What it demonstrates | Run |
|---|
react-dashboard | Mission Control UI using all packages — cards, tables, badges, distance calculations, priority queues, throttled actions, sanitized logs | bun --filter example-react-dashboard dev |
node-api | Bun.serve() HTTP server with structured logging, rate limiting, PII sanitization, request tracking | bun --filter example-node-api dev |
dsa-pathfinding | Earthquake drone response — Graph pathfinding, PriorityQueue triage, BloomFilter survey tracking, Trie dispatch lookup | bun --filter example-dsa-pathfinding start |
fleet-telemetry | Socket frames to map-ready geometry — injected transports, reconnect ladder, 50 Hz coalescing, MQTT topic addressing, asset parsing, antimeridian-safe GeoJSON tracks | bun --filter example-fleet-telemetry start |
nav-contacts | Contact assessment for a USV — CPA/TCPA, risk ranking, crab angle, set and drift, staleness, and the four shapes of a refusal | bun --filter example-nav-contacts start |
math-sketch | Branded types and the expression engine — parse, check, compile, evaluate, plus how parse/sort/domain/step-limit failures surface |
Design Assets
design/ holds the engineering style guide and the logo system PDF. The asset files are published in resq-software/docs — SVG masters and PWA PNGs only; the gradient mark and the raster (png, webp) variants are not published.
| Asset | Variants | Formats |
|---|
| Drone coordination mark | resq-mark-color, resq-mark-mono-black, resq-mark-mono-white | svg |
| Logo lockups | horizontal, stacked, tagline, mono (dark + light) | svg |
| Gradient mark | resq-mark-gradient — full-bleed mark on dark | svg, png, webp |
| OG banner | Social sharing card | svg |
| PWA icons | Android, iOS, Windows 11 | png |
| Style guide | oklch color tokens, typography, spacing, component rules | — |
| Logo system | Lockup specs, icon sizing, usage guidelines | pdf |
Development
Prerequisites
- Bun >= 1.x
- Node.js >= 20.19.0
Setup
git clone https://github.com/resq-software/npm.git
cd npm
bun install
Commands
bun install # Install all workspace dependencies
bun test # Run all workspace tests
bun run build # Build all packages
bun --filter @resq-systems/<pkg> test # Test single package
bun --filter @resq-systems/<pkg> build # Build single package
bun --filter @resq-systems/ui storybook # Start Storybook dev server
bun --filter @resq-systems/ui lint # Lint with Biome
bun changeset # Create a changeset for versioning
Stack
| Layer | Tool |
|---|
| Runtime | Bun 1.x |
| Language | TypeScript (strict) |
| Build | tsdown |
| Testing | Vitest |
| Linting | Biome |
| Versioning | Changesets |
| Visual testing | Chromatic (UI) |
Contributing
- Branch from
master and make changes in the relevant packages/ directory.
- Run
bun test to verify nothing breaks.
- Run
bun changeset to describe your changes for the changelog.
- Submit a Pull Request.
Commits follow Conventional Commits (feat:, fix:, chore:, perf:, refactor:). See CONTRIBUTING.md and DEVELOPMENT.md for full details.
License
Apache-2.0 — see LICENSE.
Copyright 2026 ResQ Systems, Inc.
