NeonURI

NeonURI is a focused toolkit for parsing, validating, and resolving Hyper* resource identifiers. It ships with production-ready helpers for Hyperdrive, Hyperbee, Hypercore, and Hyperswarm, plus catalog expansion and hash enforcement utilities that play well with existing mesh deployments.

Package Layout

• src/hyperUri.js – canonical parser, validator, and catalog traversal.
• src/hyperResolvers.js – default Hyperdrive/Hyperbee/Hypercore resolvers with Corestore replication.
• src/hyperswarmResolver.js – Hyperswarm dialer with optional Plex autowiring and connection timeouts.
• src/protocols.js – protocol registry used to hydrate transport metadata.
• src/index.js – re-exports the public surface.

Tests under test/ mirror the runtime modules and include smoke paths for resolver networking; benchmark helpers live in tools/benchmarks/.

Installation

npm install @neonloom/neonuri

Scripts

• npm run check:bare – guard against non-portable node:* specifiers for Bare/Pear builds.
• npm run lint – ESLint over src, test, and tools.
• npm run test – Brittle suite via brittle-node, including catalog recursion coverage.
• npm run test:smoke – same Brittle suite with SMOKE_TRACE=1 for resolver logs.
• npm run test:bare – Brittle suite via brittle-bare to ensure parity with Pear/Bare runtimes.
• npm run bench – throughput samples for catalog fallback and direct hits (ITERATIONS env overrides default).
• npm run release – lint + test + smoke for pre-publish validation.
• npm run publish:dry / npm run publish:release – npm publish helpers.

Bare/Pear consumers rely on the guard above along with the repo’s package.json imports map, so npm run test will fail fast if a node:* specifier sneaks back in.

Usage

The primary export is resolveHyperUris(reference, options), which iteratively walks mirrors and catalogs until it returns bytes or a live resource. See docs/usage.md for end-to-end resolver wiring and docs/api.md for detailed signatures. Instrument resolution flows with onAttempt and onResolution callbacks to track duration, fallbacks, and failure rates.

All resolver payloads are Uint8Array instances surfaced via b4a so the same code stays portable across Node, Bare, and Pear runtimes.

Roadmap & Support

• CI (GitHub Actions) runs lint, unit tests, smoke tests, and benchmarks on each PR.
• Benchmarks upload artifacts for trend tracking; inspect the latest workflow run for details.
• Open issues or discussions in the repo to propose new protocol adapters or enhancements.
• Consult docs/integration.md for migration steps and operational guidance.
• Track upcoming milestones in docs/roadmap.md.

Contributing

We welcome issues and pull requests—start with CONTRIBUTING.md and review AGENTS.md for day-to-day engineering guidelines.

Security

Please follow the disclosure process outlined in SECURITY.md for any vulnerability reports.