@presenc3/link-helpers

Optional, batteries-included companions for @presenc3/link-core. These used to ship inside link-core under ./helpers; they now live in their own package so the core library stays focused on the protocol, client, and hub, and so the helpers can version independently.

No dependency on link-core

This package has no runtime, peer, or build dependency on @presenc3/link-core. It used to import link-core's primitives and error classes; those couplings have been removed:

• The handful of small primitives it needed (normalizeLogger, nonNegFinite, settleOnEvents) are vendored into src/primitives.js. They are pure, stateless utilities, so a local copy behaves identically.
• Errors are classified structurally, by their stable name (see src/errors.js), instead of via instanceof against link-core's classes. This avoids the dual-package hazard entirely: an error thrown by link.rpc() is an instance of link-core's RpcTimeoutError, and a duplicated class here would be a different identity, so instanceof would silently never match. Keying on name works regardless of which copy of link-core (if any) is installed - the same way Node classifies its own errors via err.code.

In practice you'll still install link-core alongside this package, because the helpers operate on a LinkClient you construct. But that's your dependency, not this package's - these helpers accept any object exposing the small LinkClientLike surface (getPeers/on/off/rpc/publish/…), so wrappers and test doubles work too.

Install

npm install @presenc3/link-helpers
# and, since you'll be passing it a client, link-core too:
npm install @presenc3/link-core

What's inside

| Area | Exports | | ------------- | ------- | | Logging | createLogger, LEVELS | | Env coercion | num, bool, requireEnv, linkClientOptionsFromEnv | | Observability | attachClientObservability, attachHubObservability, DEFAULT_*_CONCERNING_REASONS | | RPC patterns | waitForPeer, rpcWithRetry, createSafeSend, createSafePublisher | | Lifecycle | installProcessHandlers, createGracefulShutdown | | Secrets | loadSecrets, LOADED_SECRETS_UNWATCH | | Recording | createEventRecorder, RECORDED_CLIENT_EVENTS, SNAPSHOT_TRIGGERS |

Usage

const { createLogger, attachClientObservability } = require('@presenc3/link-helpers');
const { LinkClient } = require('@presenc3/link-core');

const log    = createLogger({ minLevel: 'INFO' });
const client = new LinkClient({ url, kind: 'svc', secret, logger: log });
attachClientObservability(client, { logger: log });

The logger returned by createLogger satisfies link-core's { debug, info, warn, error } contract, so the same instance can be passed straight to LinkClient, createHub, and createHubServer.

ESM

The package is dual-published. CommonJS require and ESM import both resolve the same implementation:

import { createLogger, loadSecrets, LOADED_SECRETS_UNWATCH } from '@presenc3/link-helpers';

Tests

npm test                   # full suite; link-core cross-checks run if it's resolvable, else skip
npm run test:unit          # unit suites only (no hub, no link-core required)
npm run test:integration   # hub-backed loadSecrets suite; needs link-core dev-linked
npm run type-check         # tsc --noEmit against the shipped index.d.ts

The integration suite (test/secrets.integration.test.js) and the link-core half of test/errors.test.js need a resolvable @presenc3/link-core (add it as a dev link). Without it, those checks skip and the rest run green.

License

MIT © Presenc3