commflow
  • English

      • commflow Product Guide (Planned APIs)

      Planned APIs: This guide describes the final user-facing commflow contract. request, SSE, RPC, socket, and the VextJS adapter are not published by commflow@0.0.2 and must not be used as current production imports.

      Runnable today: Start with Current Release Quick Start for installation checks and released exports.

      What commflow Helps You Do

      commflow addresses scattered server-side communication behavior. You do not need to rebuild request timeout, RPC call timeout, SSE reconnect, socket heartbeat, trace propagation, context propagation, error normalization, and resource cleanup across frameworks and modules. One communication layer manages those behaviors.

      This page establishes the shared usage model. Detailed operations live in the feature chapters in the left sidebar:

      Feature areaUser task
      requestSend HTTP requests and manage timeout, numeric retry, headers, targets, and context.
      SSESubscribe to server event streams and handle Last-Event-ID, reconnect, messages, errors, and closing.
      RPCCall services by procedure and manage timeout, metadata, errors, and typed contracts.
      socketManage bidirectional long-lived messages, heartbeat, reconnect, send ordering, listener cleanup, and close.
      VextJS adoptionCompare existing app.fetch behavior, plan a compatible migration, and verify context, proxy, and error semantics.
      configurationUnderstand global options, target options, per-call overrides, and adapter options.
      errors and retriesDistinguish HTTP responses, timeout, network, aborted, hook failure, retry, and reconnect policy.

      Feature Overview

      ChapterPurpose
      RequestCreate a request client, call GET/POST, configure targets, context, and hooks.
      SSESubscribe to event streams, handle messages, reconnect, close, and cleanup.
      RPCCall procedures, organize contracts, handle call errors, and use targets.
      SocketConnect, send messages, listen to events, heartbeat, reconnect, and close.
      ConfigurationDistinguish request/RPC timeout and retry from SSE/socket reconnect, headers, targets, metadata, contextProvider, and hooks.
      Errors And RetriesDecide which failures should retry, reconnect, reach business code, or stop immediately.
      VextJS AdoptionCompare current app.fetch behavior and prepare a compatible adoption path.
      TroubleshootingFix current-version, import, Node version, and unreleased API expectation issues.

      Install And Runtime Requirements

      npm install commflow

      Requirements:

      ItemRequirement
      Node.jsPackage runtime requirement is >=20.0.0.
      Module formatESM-first.
      FrameworkThe core package stays framework-agnostic and does not depend on VextJS.
      Current package capability0.0.2 currently only exposes the manifest API.

      Choosing A Feature

      If you need toUse
      Call REST APIs, internal HTTP services, or one-shot requestsrequest
      Receive continuous server-to-client eventsSSE
      Call services by procedure name and share typed contractsRPC
      Use long-lived realtime bidirectional messages, rooms, or channelssocket
      Replace existing VextJS fetch orchestrationVextJS adapter + request core

      Unified Usage Model

      All communication styles share the same context, target, error, and observability model, but they do not force the same option names. request/RPC are calls; SSE/socket are connection lifecycles. SSE/socket recovery is reconnect, not request retry.

      1. Create a client.
      2. Choose a service URL, target, resolver, or socket URL.
      3. Provide context, headers, metadata, or auth.
      4. Dispatch a call or establish a connection.
      5. Handle responses, events, errors, and cleanup.

      The feature chapters below document planned APIs. To run the current package, use the manifest example in Current Release Quick Start; use the client examples only after their runtime APIs are released.

      The configuration guide marks which transports support each capability and why a field is N/A when it does not apply.

      Planned Feature Chapters

      FeatureUsage chapterCore question
      requestRequestHow do I send requests, organize targets, override one call, provide context, and use hooks?
      SSESSEHow do I subscribe, parse events, reconnect, close, and avoid subscription leaks?
      RPCRPCHow do I call procedures, pass arguments, handle return values, and manage errors?
      socketSocketHow do I connect, send messages, listen, heartbeat, reconnect, and close?

      Configuration And Error Handling

      Configuration is a core user feature, not an internal implementation detail. Read:

      • Configuration: option meaning, default layers, target/resolver overrides, hook boundaries, and VextJS adapter boundaries.
      • Errors And Retries: HTTP status, timeout, network, aborted, config, hook failure, and retry/reconnect strategy.

      VextJS Integration

      VextJS is the first target consumer. Adoption focuses on preserving existing app.fetch timeout, retry, proxy, request context, and hook behavior. See VextJS Adoption for prerequisites and the compatibility path.

      Current Release Boundary

      commflow@0.0.2 is still a skeleton package:

      CapabilityCurrent stateRead
      manifestReleasedManifest API
      request runtimeNot releasedRequest
      SSE runtimeNot releasedSSE
      RPC runtimeNot releasedRPC
      socket runtimeNot releasedSocket
      VextJS adapterNot releasedVextJS Adoption

      When you need runnable code now, start with Current Release Quick Start. When you need the complete product model, continue through the feature chapters in this guide.