npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@husky-di/remote

v1.0.3

Published

Readme

@husky-di/remote

Typed, bidirectional unary and RxJS Observable RPC over application-supplied Transport Adapters. A Connector owns one stable Peer; an Acceptor serves multiple Peers. Logical Sessions preserve Peers, exposures, facades, and eligible calls across physical Connection replacement.

Call a remote service

Install @husky-di/remote, @husky-di/core, and rxjs. Supply Adapter instances for your transport, then expose and resolve the same wire contract on both sides. Local service identifiers may differ; wireName and selected member names identify the remote route.

import { createServiceIdentifier } from "@husky-di/core";
import {
  createRemoteServiceDescriptor,
  createRpcAcceptor,
  createRpcConnector,
  type IRpcAcceptorAdapter,
  type IRpcConnectorAdapter,
} from "@husky-di/remote";

type Greeter = { greet(name: string): string };
const IGreeter = createServiceIdentifier<Greeter>("Greeter");
const greeter = createRemoteServiceDescriptor(IGreeter, {
  wireName: "greeter",
  members: { greet: { kind: "function" } },
});

export async function example(
  acceptorAdapter: IRpcAcceptorAdapter,
  connectorAdapter: IRpcConnectorAdapter,
): Promise<void> {
  const server = createRpcAcceptor();
  const client = createRpcConnector();
  server.expose(greeter, { greet: (name) => `Hello, ${name}` });
  const remote = client.peer.resolve(greeter);

  try {
    await server.listen(acceptorAdapter);
    await client.connect({ adapter: connectorAdapter });
    console.log(await remote.greet("Ada"));
  } finally {
    await Promise.all([client.shutdown(), server.shutdown()]);
  }
}

Factories and resolve() are cold. Creating or observing an Owner starts no Transport I/O. Only explicitly allowlisted members are remotely callable. Unary members return Promises; Observable members return cold RxJS Observables, and then is reserved.

Call client.peer.expose() for calls in the opposite direction and resolve from an accepted Peer in server.peers. Acceptor exposures apply atomically to current and future Peers. Peer-local and Acceptor exposures share one effective namespace; exposing the same wire name in both throws TypeError. The idempotent cleanup returned by expose() removes the route for future calls without interrupting an admitted handler. For multiple peers, snapshot server.peers and compose independent calls with Promise.allSettled().

Cancellation and values

A cancelable function member selects { kind: "function", cancelable: true } and has exactly one required trailing AbortSignal in its implementation signature. The facade replaces that slot with a required AbortSignal | undefined; explicitly pass undefined when no cancellation is needed. Aborting rejects with RpcException(canceled) and cooperatively signals an admitted handler. It does not promise rollback.

Arguments and results support detached JSON data: null, booleans, strings, finite numbers other than negative zero, dense arrays, and plain data records. Void results are supported. Unsupported shapes, accessors, cycles, and nested undefined fail validation; serialization hooks never run. Non-enumerable data properties on records are ignored. Messages are limited to 1 MiB, with additional finite value, depth, count, and retained-memory bounds in the specification.

Intercept calls and subscriptions

Pass interceptor to either Owner factory. It receives one context for each outgoing unary call or stream subscription and each incoming execution. Both next() and the interceptor return an RxJS Observable:

import { defer, tap } from "rxjs";
import {
  createRpcConnector,
  RpcCallDirectionEnum,
  type RpcInterceptor,
} from "@husky-di/remote";

const interceptor: RpcInterceptor = (context, next) => defer(() => {
  if (context.direction === RpcCallDirectionEnum.outgoing) {
    context.metadata = { traceId: crypto.randomUUID() };
  }
  return next().pipe(tap({ complete: () => console.log("finished") }));
});
const client = createRpcConnector({ interceptor });

Use RxJS operators for asynchronous preparation, item transformation, and error handling. next() is single-use. Return your own Observable to short-circuit without creating remote work. Interception runs once per opening, never per item or during replay. Unary results adapt zero emissions to undefined, one emission to the result, and a second emission to safe handler-failed.

Outgoing interceptor errors remain local. Incoming interceptor, source, or operator failures become safe handler-failed errors for only that call or stream. Unsubscribing tears down preparation; if continuation has not admitted work, no stream record is sent. An admitted subscription requests remote cancel and ends silently.

Outgoing context.metadata accepts plain Application Value records. The Framework snapshots it when next() runs, charges it against retained-memory limits, and preserves it during replay. Incoming metadata is detached and deeply frozen. Empty metadata adds no wire field. Metadata never enters event$. Older v1 endpoints may ignore it, so successful calls do not prove metadata was processed or authorization was enforced. The Framework creates no trace identifiers or ambient context itself.

Recovery and optional reconnection

The built-in v1/v2 Protocol retains Session state after physical Connection loss. A replacement client.connect({ adapter }) resumes that same Session within its recovery window. Sequence acknowledgments, replay, and the retained call and stream ledgers preserve at-most-once dispatch within that Session. Open sources continue during disconnection within finite retained budgets. Recovery replays queued items in order without another open or source subscription. A new Session never automatically resubscribes an old stream.

For finite automatic replacement attempts, create a Connector with reconnection supervision and a fresh Adapter Factory:

import {
  createRpcReconnectionConnector,
  type RpcConnectorAdapterFactory,
} from "@husky-di/remote";

export function supervise(
  adapterFactory: RpcConnectorAdapterFactory,
) {
  return createRpcReconnectionConnector({
    adapterFactory,
    policy: {
      retryDelaysMs: [1_000, 2_000, 5_000, 10_000],
      attemptTimeoutMs: 30_000,
    },
  });
}

The factory creates a cold Connector, exposed as reconnection.connector for service exposure, resolution, and shutdown. Pass protocolFactory, runtimePolicy, and interceptor directly in the same options object when needed. Call await reconnection.connect() once for the initial attempt. Initial failure is returned without retry. After initial success, each Recovery episode gets one immediate replacement attempt followed by the configured finite delays. Call await reconnection.stop() before manual Connector takeover or Owner shutdown. Stopping supervision does not close the Connector. Recovery has an absolute deadline; retries cannot extend it.

Peer state/state$ remains the authoritative Session state. Reconnection state/state$ describes attempt orchestration; its event$ reports safe background failure stages. Owner and Peer state streams and Acceptor peers$ replay their latest frozen snapshots. Owner event$ is hot and non-replaying, with lifecycle, unary call, and stream opening/terminal observations that exclude application payloads, raw errors, and credentials. There is no per-item stream event.

Limits, errors, and termination

In a source checkout, the built-in Protocol's size, length, count, resource, and policy definitions are collected in src/modules/protocol/constants/rpc-limits.const.ts, with units and derived capacity formulas alongside the constants.

Owner factories accept role-specific runtimePolicy, an optional protocolFactory, and interceptor:

const client = createRpcConnector({
  runtimePolicy: {
    maxPendingInvocationsPerSession: 256,
    maxHandlersPerSession: 16,
    bindingAttemptTimeoutMs: 30_000,
    recoveryGraceMs: 300_000,
    shutdownDeadlineMs: 5_000,
  },
});

These values match the defaults. Policy also bounds retained bytes, handshakes, Sessions, total handlers, acknowledgment delay, activity probes, silence, and send progress. Acceptor handlers are scheduled fairly across Sessions. Healthy handler execution has no framework-imposed timeout; use a cancelable contract for application deadlines. See the specification for every default and the required cross-field constraints.

Framework call failures use RpcException; invalid local inputs use TypeError. Branch on RpcExceptionCodeEnum values:

| Code | Meaning | | --- | --- | | unavailable | Unary/opening admission failed; an active stream can also exhaust its bounded resources. | | outcome-unknown | Admitted work lost authoritative terminal evidence; previous effects or stream items remain. | | canceled | Cancellation won the public result; side effects may remain. | | handler-failed | The handler failed; its message and thrown value remain private. | | unknown-service / unknown-method | The remote route is absent. | | protocol | A Protocol, continuity, or resource invariant failed. |

shutdown() stops new work and drains retained work within one grace interval, then cleans up resources within one further interval. close() forces semantic cutoff immediately and uses only the cleanup interval. Both methods always return the same cached termination Promise. Cleanup failures reject that task; unknown call outcomes remain separate call failures.

Extension points and deployment

| Entry point | Contract | | --- | --- | | @husky-di/remote | Owners, descriptors, reconnection, observations, and caller-required types. | | @husky-di/remote/protocol | Role-specific Protocol factories and semantic implementor SPI. | | @husky-di/remote/transport | Connection and Adapter contracts. | | @husky-di/remote/conformance | Framework-neutral Protocol and Adapter verification runners. |

The default Protocol is selected when protocolFactory is omitted. Custom Protocols use the same application-value and caller contracts. A Transport Adapter supplies the ordered byte channel and framing. This package does not include a WebSocket Adapter, notifications, service discovery, or automatic Container integration.

For browser and Node WebSocket transport, use the separate @husky-di/remote-websocket package. The runnable example demonstrates bidirectional calls and composes its Adapters with the built-in reconnection supervisor.

Recovery uses an independent, stable 256-bit bearer resumeToken. Use a confidential, integrity-protected, anti-replay channel that authenticates the intended endpoint; complete its handshake before RPC handoff and never send bootstrap messages as replayable early data. The built-in Protocol does not authenticate the initiating application. Authenticate and admit inbound initiators before Acceptor handoff, authorize services, and enforce per-principal connection, Session, request-rate, and handler-duration limits at the application or gateway boundary. A resume token grants Session continuity, not user identity. Keep it out of logs and payload traces. Retained-state loss or process restart ends the Session; recovery is in-memory.

ESM, CommonJS, TypeScript NodeNext/Bundler, and browser consumers are supported. Node usage requires Node.js 23.6 or newer.

See the specification, requirement matrix, Protocol guide, and Transport guide.

Observable members

Select an RxJS Observable method or a static Observable property explicitly:

import { createServiceIdentifier } from "@husky-di/core";
import { Observable, of, Subject } from "rxjs";
import { createRemoteServiceDescriptor } from "@husky-di/remote";

type Feed = { watch(topic: string): Observable<number>; updates$: Observable<number> };
const IFeed = createServiceIdentifier<Feed>("Feed");
const feed = createRemoteServiceDescriptor(IFeed, {
  wireName: "feed",
  members: {
    watch: { kind: "observable-function" },
    updates$: { kind: "observable" },
  },
});
const updates = new Subject<number>();
server.expose(feed, { watch: (_topic) => of(1, 2, 3), updates$: updates });
const remote = client.peer.resolve(feed);
const methodSubscription = remote.watch("all").subscribe({
  next: console.log,
  complete: () => console.log("completed"),
  error: (error) => console.error(error.code),
});
const staticSubscription = remote.updates$.subscribe(console.log);
methodSubscription.unsubscribe();
staticSubscription.unsubscribe(); // requests stream-cancel and ends silently

Each method subscription invokes the remote handler independently. Static Observable instances are captured once at exposure and connected lazily. Within one Peer, subscriptions to that same captured instance share one source connection; the last ending subscription tears it down. Different Peers have separate source connections. Static facade properties are readonly and return a stable Observable object. Each subscription still owns its own identity, interception, and terminal.

Only direct RxJS Observables are accepted. AsyncIterable, Promise-wrapped Observables, accessors, and non-Observable results are rejected. Stream methods have no AbortSignal parameter; unsubscribe owns cancellation. Source completion calls complete; source errors become safe RpcException(handler-failed). Recovery expiry or Session termination errors admitted streams with outcome-unknown, without synthesizing completion or resubscription.

Fresh negotiation prefers husky-di-rpc/2, which carries unary and stream records, and offers husky-di-rpc/1 for unary-only peers. Unary calls keep working on v1; a stream subscription errors with unavailable before sending an unknown record. The selected profile is fixed for that Session, including Recovery.

Migrate to specification 2.0.0

Replace methods with members and give every selected member an explicit kind. Replace callInterceptor with interceptor and RpcCallInterceptor with RpcInterceptor; return an Observable and compose next() with RxJS operators. The old keys and type names are rejected, including when combined with new keys. The package remains 0.0.0; the specification version is independent of npm release versioning.