@procedures/client weekly downloads statistics

@procedures/client

Universal protocol-agnostic RPC client/server with middleware composition, type-safe procedures, streaming and procedure-as-data.

The core depends on no other package of the repository. The procedure components are in @procedures/splay, the data structures in @procedures/collections, and the program store with the storage layer in @procedures/store.

Table of Contents

• Overview
• Installation
• Architecture
• Core Concepts
• API Reference
• Examples
• Integration

Overview

@procedures/client is the foundational package of the Mark ecosystem, providing a complete RPC framework with:

• Universal Client/Server: Protocol-agnostic RPC supporting HTTP, WebSocket, gRPC, and local transports
• Type-Safe Procedures: Schema-validated procedures with auto-discovery and registry management
• Middleware System: Composable middleware for retry, cache, timeout, circuit breaker, rate limiting, auth, tracing, and validation
• Procedure-as-Data: JSON programs of calls, references and control flow (PROGRAM-FORMAT.md)
• Event Bus: Pub/sub messaging with async iteration support. A peer subscribes to the bus of another peer over each transport (EVENTS.md)
• Error System: 70+ error codes with rich metadata and recovery suggestions

Installation

npm install @procedures/client

npm installs zod and ws with it. The HTTP server transport needs express 4 or 5 (an optional peer dependency).

import "@procedures/client/register" registers the control flow (client.chain and the others) and procedure.define, get, list and delete in the global registry. createRegistry() adds them to each new registry.

client.trace runs the steps of a client.chain program one at a time, and gives one row for each step with its result. A step that can write does not run, and the procedure asks for a capability without writes. Thus a read-only face can serve it. The procedure reference gives the rows and the input fields upTo and sampleLimit.

Architecture

graph TB
    subgraph "Application Layer"
        Procedures[Procedure System<br/>Type-safe RPC definitions]
        Events[Event Bus<br/>Pub/sub messaging]
    end

    subgraph "Client/Server Core"
        Client[Universal Client&lt;TContext&gt;<br/>Protocol-agnostic RPC]
        Server[Universal Server<br/>Handler registry]
        Middleware[Middleware Chain<br/>Composable behaviors]
    end

    subgraph "Transport Layer"
        HTTP[HTTP Transport<br/>RESTful + POST-only]
        WebSocket[WebSocket Transport<br/>Bidirectional streaming]
        Local[Local Transport<br/>In-process calls]
        Mock[Mock Transport<br/>Testing]
    end

    Procedures --> Client
    Procedures --> Server
    Events -.-> Client

    Client --> Middleware
    Server --> Middleware
    Middleware --> HTTP
    Middleware --> WebSocket
    Middleware --> Local
    Middleware --> Mock

Data Flow

sequenceDiagram
    participant App as Application
    participant Client as Client
    participant MW as Middleware Chain
    participant Transport as Transport
    participant Server as Server
    participant Handler as Procedure Handler

    App->>Client: call(method, payload)
    Client->>MW: compose middleware
    MW->>MW: retry, cache, timeout, auth...
    MW->>Transport: send(message)
    Transport->>Server: HTTP/WS/etc
    Server->>Handler: execute handler
    Handler-->>Server: result
    Server-->>Transport: response
    Transport-->>MW: response stream
    MW-->>Client: unwrap/validate
    Client-->>App: result

Core Concepts

1. Universal Client

The Client class provides protocol-agnostic RPC with type-safe middleware composition:

• Generic over accumulated context type Client<TContext>
• Middleware chain builds type information through .use()
• Context inheritance via .withContext()
• Supports streaming and single request/response

2. Procedure System

Type-safe RPC procedure definitions with:

• Schema validation (Zod)
• Auto-discovery via package.json
• Handler execution (local or remote)
• Procedure-as-data (procedure references)

3. Middleware Composition

Onion-model middleware with:

• Type accumulation (Client<BaseContext & RetryContext & ...>)
• Context propagation (parent → client → per-call)
• Built-in middleware for common patterns

4. Call Policy and Interceptors

A host controls which procedures its callers reach, also through nested calls. See docs/POLICY.md.

• expose: the procedures that the callers of a server can reach.
• A data-driven procedure (client.chain) calls only exposed procedures.
• A procedure of code declares its nested calls in metadata.calls. With strictCalls, a procedure that declares nothing calls only exposed procedures.
• Interceptors run around each invocation and its nested calls: timeoutInterceptor, tracingInterceptor, metricsInterceptor.

5. Related Packages…