npm package: @neonloom/neonuri
Description: Hyper URI parsing and resolution toolkit for Neon Loom workloads.
Latest version: 0.1.6

# 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

```bash
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](docs/bare-standards.md), 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`](docs/usage.md) for end-to-end resolver wiring and
[`docs/api.md`](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`](https://github.com/mafintosh/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`](docs/integration.md) for migration steps and operational guidance.
- Track upcoming milestones in [`docs/roadmap.md`](docs/roadmap.md).

## Contributing

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

## Security

Please follow the disclosure process outlined in [SECURITY.md](SECURITY.md) for
any vulnerability reports.