# @api.global/typedrequest-interfaces

> Typed request, event, tag, and transport-neutral VirtualStream contracts.

Latest version **7.1.0** (published 2026-08-15) · MIT license · 0 weekly downloads

## Install

```sh
npm install @api.global/typedrequest-interfaces
pnpm add @api.global/typedrequest-interfaces
yarn add @api.global/typedrequest-interfaces
bun add @api.global/typedrequest-interfaces
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 7.1.0 |
| Published | 2026-08-15 |
| First published | 2023-08-03 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 28.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Lossless GmbH |
| Maintainers | lossless |
| Keywords | HTTP, requests, interfaces, TypeScript, streaming, API, virtual streams |

## Links

- npm: https://www.npmjs.com/package/@api.global/typedrequest-interfaces
- npm.io page: https://npm.io/package/@api.global/typedrequest-interfaces

## Alternatives

- [launchdarkly-js-client-sdk](https://npm.io/package/launchdarkly-js-client-sdk.md) — 2.5M weekly downloads
- [@elastic/elasticsearch](https://npm.io/package/@elastic/elasticsearch.md) — 2.1M weekly downloads
- [@c8y/client](https://npm.io/package/@c8y/client.md) — 15.3K weekly downloads
- [@signaldb/maverickjs](https://npm.io/package/@signaldb/maverickjs.md) — 1.7K weekly downloads
- [@bbc/http-transport-cache](https://npm.io/package/@bbc/http-transport-cache.md) — 1.2K weekly downloads

## Recent versions

- 7.1.0 (latest) — 2026-08-15
- 7.0.0 — 2026-08-04
- 6.0.0 — 2026-08-04
- 5.1.1 — 2026-08-01
- 5.1.0 — 2026-08-01
- 5.0.0 — 2026-07-31
- 4.0.0 — 2026-07-29
- 3.0.19 — 2024-05-05
- 3.0.18 — 2024-02-29
- 3.0.17 — 2024-02-24
- 3.0.16 — 2024-02-24
- 3.0.14 — 2024-02-24
- 3.0.13 — 2024-02-23
- 3.0.12 — 2024-02-23
- 3.0.11 — 2024-02-23
- … 12 more at https://npm.io/package/@api.global/typedrequest-interfaces/versions

## README

# @api.global/typedrequest-interfaces

Typed request, event, tag, and transport-neutral VirtualStream contracts.

## Issue Reporting and Security

For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.

## Install

To install `@api.global/typedrequest-interfaces`, you need to have Node.js installed on your system. You can then add this package to your project by running the following command in your terminal:

```bash
pnpm add @api.global/typedrequest-interfaces
```

This will add the package to your project's dependencies. Ensure you are in your project's directory or specify the path where your project is located.

## Usage

This package provides typed request, event, tag, and transport-neutral
VirtualStream contracts for TypeScript applications.

### Setting Up Your Project

First, ensure your project is set up to use TypeScript and ESM (ECMAScript Modules). You will need a `tsconfig.json` file in your project root with at least the following settings:

```json
{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "node",
    "outDir": "./dist",
    "declaration": true,
    "esModuleInterop": true,
    "experimentalDecorators": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src/**/*"]
}
```

Adjust the settings according to your project requirements. This configuration supports modern JavaScript features and TypeScript.

### Basic Implementation

To use the interfaces provided by the package, start by importing them into your TypeScript file. Below is an example demonstrating how to define a typed request using the interfaces:

```typescript
import { ITypedRequest, ITypedEvent, ITag, TVirtualStream } from '@api.global/typedrequest-interfaces';

// Example: Defining a typed request
interface MyCustomRequest extends ITypedRequest {
  method: 'MyCustomMethod';
  authInfo?: {
    jwt: string;
  };
  request: {
    someData: string;
  };
  response: {
    resultData: number;
  };
}
```

This snippet shows how to create a custom interface `MyCustomRequest` that implements the `ITypedRequest` interface from the package. You can specify the types for the request and response data to match your application's needs.

`requestInstanceId` is transport metadata for one exact request attempt. Every
transport response must preserve it. Cancellation and separately routed response
registries use it together with the method and correlation ID so retries cannot
consume stale responses. Application request interfaces do not need to declare
it again.

### Handling Typed Events

You can also define and use typed events similar to the following example:

```typescript
// Example: Defining a typed event
interface MyCustomEvent extends ITypedEvent<{ message: string }> {
  name: 'MyCustomEvent';
  uniqueEventId: 'Event123';
  payload: {
    message: 'Hello World';
  };
}
```

### Utilizing Tags

Tags can be useful for attaching metadata or categorization information to your requests or events. Implementing a tag looks like this:

```typescript
// Example: Defining a tag
interface UserActionTag extends ITag {
  name: 'UserAction';
  payload: {
    userId: number;
    action: string;
  };
}
```

### Virtual Streams

`TVirtualStream` is one transport-neutral abstraction for finite transfers and
open-ended streams such as camera frames. It carries ordered logical
`Uint8Array` chunks in one explicit local direction. One `send()` or
`WritableStream.write()` maps to one `receive()` result or readable enqueue,
even when the transport fragments the chunk internally.

```typescript
import type { ITypedRequest, TVirtualStream } from '@api.global/typedrequest-interfaces';

interface IUploadRequest extends ITypedRequest {
  method: 'upload';
  request: {
    stream: TVirtualStream<'send'>;
  };
  response: {
    stored: boolean;
  };
}

const upload = async (
  stream: TVirtualStream<'send'>,
  chunks: Uint8Array[],
) => {
  for (const chunk of chunks) {
    await stream.send(chunk);
  }
  return await stream.close();
};
```

The direction in a shared TypedRequest DTO is always the requesting peer's
direction. `TypedHandler` reverses it exactly once for the handler's local view.
An upload declared as `TVirtualStream<'send'>` therefore reaches the handler as
`TVirtualStream<'receive'>`.

Receivers consume one complete logical chunk at a time. `undefined` is graceful
EOF. After draining EOF, the receiver explicitly accepts the stream; rejecting
or aborting is peer-visible:

```typescript
const receive = async (stream: TVirtualStream<'receive'>) => {
  while (true) {
    const chunk = await stream.receive();
    if (chunk === undefined) break;
    // Persist or process this complete logical chunk.
  }
  return await stream.accept();
};
```

Open-ended streams omit `integrity` and may continue until either peer ends
them. Finite verified streams declare the exact aggregate byte length and
SHA-256 digest. Chunk boundaries do not affect the aggregate digest:

```typescript
import type {
  IVirtualStreamIntegrity,
} from '@api.global/typedrequest-interfaces';

const integrity: IVirtualStreamIntegrity = {
  algorithm: 'sha256',
  byteLength: 12_345,
  digest: `sha256:${'0'.repeat(64)}`,
};
```

`opened` rejects if establishment fails. `completion` resolves with one shared
accepted receipt and rejects for every abnormal outcome. `closed` always
resolves after bounded transport cleanup. `WritableStream.close()` maps to the
sender's graceful close, `WritableStream.abort()` maps to abort, and
`ReadableStream.cancel()` maps to receiver rejection. Direct `receive()` and
readable consumption are mutually exclusive; sender `send()` and writable
writes share one ordered bounded admission queue.

`IVirtualStreamDescriptor`, `IVirtualStreamTransportRegistration`, and
`IVirtualStreamTransport` define the transport boundary used by TypedRequest and
TypedSocket. Descriptor transport data is JSON-compatible but opaque to
TypedRequest. A registration is synchronous and silent, and its idempotent
disposer performs no transport I/O. Descriptor consumers always receive the
compile-time opposite direction through `TOppositeVirtualStreamDirection`.
Transport staging receives a required `AbortSignal` and remaining timeout; the
transport must stop retained staging work and settle promptly when aborted.

The examples shown demonstrate the versatility of the `@api.global/typedrequest-interfaces` package in structuring your application's request-response mechanisms, event handling, tagging, and stream management. By following TypeScript and ESM conventions, you can leverage these interfaces to architect robust, typed APIs and services.

## License and Legal Information

This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the repository license file.

**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

### Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.

Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.

### Company Information

Task Venture Capital GmbH<br>
Registered at District Court Bremen HRB 35230 HB, Germany

For any legal inquiries or further information, please contact us via email at hello@task.vc.

By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.

---
_Source: https://npm.io/package/@api.global/typedrequest-interfaces · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._