# @delight-rpc/protocol

> ```sh npm install --save @delight-rpc/protocol # or yarn add @delight-rpc/protocol ```

Latest version **4.1.1** (published 2023-06-11) · MIT license · 0 weekly downloads

## Install

```sh
npm install @delight-rpc/protocol
pnpm add @delight-rpc/protocol
yarn add @delight-rpc/protocol
bun add @delight-rpc/protocol
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities.

Warnings: low downloads.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 4.1.1 |
| Published | 2023-06-11 |
| First published | 2022-05-07 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=16 |
| Dependencies | 2 |
| Unpacked size | 9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | BlackGlory |
| Maintainers | black_glory |

## Links

- npm: https://www.npmjs.com/package/@delight-rpc/protocol
- Repository: https://github.com/delight-rpc/protocol
- Homepage: https://github.com/delight-rpc/protocol#readme
- Issues: https://github.com/delight-rpc/protocol/issues
- npm.io page: https://npm.io/package/@delight-rpc/protocol

## Dependencies (2)

- [@blackglory/errors](https://npm.io/package/@blackglory/errors.md) ^3.0.0
- [@blackglory/prelude](https://npm.io/package/@blackglory/prelude.md) ^0.3.1

## Recent versions

- 4.1.1 (latest) — 2023-06-11
- 4.1.0 — 2023-04-02
- 4.0.0 — 2023-03-19
- 3.0.1 — 2023-01-21
- 3.0.0 — 2022-12-15
- 2.2.1 — 2022-08-01
- 2.2.0 — 2022-05-07

## README

# @delight-rpc/protocol
## Install
```sh
npm install --save @delight-rpc/protocol
# or
yarn add @delight-rpc/protocol
```

## Protocol
The Delight RPC protocol is an RPC protocol that can be built on any communication protocol and data exchange format.

The communication of the Delight RPC protocol consists of two parties, the client and the server.
The client sends a message to the server and the server returns or does not return a message to the client.

As the implementer of the protocol,
all you need is to make the messages satisfy the following correspondence.

| Client       | Server                |
|--------------|-----------------------|
| Request      | Result / Error        |
| BatchRequest | BatchResponse / Error |
| Abort        | None                  |

## API
```ts
const version = '3.1'

/**
 * The reason why it is divided into two fields
 * is to make it easier to distinguish
 * when sharing channels with other protocols.
 * 
 * Reducing the size of payloads is not the goal of Delight RPC.
 */
interface IDelightRPC {
  protocol: 'delight-rpc'
  version: `3.${number}`

  /**
   * An identifier used to offload multiple different RPC instances
   * over a communication channel.
   */
  channel?: string

  [key: string]: unknown
}

// =================== Client -> Server ===================

interface IRequest<T> extends IDelightRPC {
  id: string

  /**
   * The expected server semver.
   */
  expectedVersion?: Nullable<string>
  
  /**
   * The `method` field can include the namespace it belongs to.
   * For example, `['config','save']` represents the `save` method
   * under the namespace `config`.
   */
  method: string[]
  params: T[]
}

/**
 * The new type of message sent by clients to servers since 3.1.
 * Servers with protocol versions lower than 3.1 will simply ignore these messages.
 */
interface IAbort extends IDelightRPC {
  id: string
  abort: true
}

interface IBatchRequest<T> extends IDelightRPC {
  id: string

  /**
   * The expected server semver.
   */
  expectedVersion?: Nullable<string>

  parallel: boolean

  requests: Array<IRequestForBatchRequest<unknown, T>>
}

interface IRequestForBatchRequest<Result, DataType> {
  method: string[]
  params: DataType[]
}

// =================== Server -> Client ===================

type IResponse<T> = IResult<T> | IError

interface IResult<T> extends IDelightRPC {
  id: string
  result: T
}

interface IError extends IDelightRPC {
  id: string
  error: SerializableError
}

interface IBatchResponse<DataType> extends IDelightRPC {
  id: string
  responses: Array<
  | IResultForBatchResponse<DataType>
  | IErrorForBatchResponse
  >
}

interface IResultForBatchResponse<T> {
  result: T
}

interface IErrorForBatchResponse {
  error: SerializableError
}
```

---
_Source: https://npm.io/package/@delight-rpc/protocol · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._