js.stuartsm
challenge

Cross-Runtime Library

Design and ship a small library with a stable public API, conditional exports for browser/Node, a compatibility matrix, benchmarks, a threat model, and a documented release process.

Practices: Modules, packages, and supply-chain design, Engine behavior and performance engineering

Scenario

Design and publish (at minimum, publish-ready — an actual npm publish isn’t required) a small, genuinely useful library — a data-validation utility, a small state-management primitive, a formatting library, or similar — that works correctly in both browsers and Node, with a public API you’d be comfortable committing to for a 1.0 release.

Requirements

Core

  • A clearly scoped, documented public API — what’s exported, what each export does, and explicitly what is not part of the public contract (recall package.json exports).
  • Conditional exports correctly serving both an ESM and a CommonJS build, verified to actually work by consuming the package both ways (import and require) from a small test consumer project.
  • A documented compatibility matrix: which browsers/Node versions are supported, and what happens on an unsupported one (a clear error, or documented silent limitation — not undefined behavior).
  • At least one meaningful benchmark, designed per Benchmark Design (warm-up, multiple iterations, representative input) — comparing your implementation against a naive baseline or an alternative approach, with the results and methodology documented.
  • A short threat model (recall Threat Modeling) for the library itself — what could go wrong if a consumer passes it malicious input, and how the library handles that.

Stretch

  • A dual-package hazard check: if the library has any module-level state, explicitly test and document behavior when both builds are loaded simultaneously.
  • A GitHub Actions (or equivalent) CI configuration running tests against your full compatibility matrix.

Reflect

  • Which parts of your public API design were hardest to commit to as stable? What would you do differently if starting over with what you now know?
  • What did writing the compatibility matrix force you to actually test, that you might otherwise have assumed rather than verified?

Suggested milestones

  1. Implement the core functionality with a single, straightforward build target — no dual-format concerns yet.
  2. Design and document the public API surface explicitly, including what’s deliberately excluded.
  3. Add conditional exports for both ESM and CommonJS; verify both consumption paths actually work.
  4. Write the benchmark and the compatibility matrix.
  5. Write the threat model and a RELEASE.md documenting your versioning/release process (recall Semantic Versioning).

Acceptance checks

  • A small test project can both import and require the library successfully, getting working, correctly-typed results either way.
  • The benchmark, run twice, produces results within a documented reasonable variance of each other (evidence it isn’t dominated by noise).
  • The compatibility matrix’s claims are actually verified, not assumed — at least spot-checked against the oldest supported Node version and one older browser engine if feasible.
  • The public API documentation would let a new consumer use the library correctly without reading its source code.