@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/. 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/ 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:

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:

{
  "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:

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:

// 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:

// 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.

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:

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:

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
Registered at District Court Bremen HRB 35230 HB, Germany

For any legal inquiries or further information, please contact us via email at [email protected].

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.