api.global/typedrequest-interfaces
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

update documentation

Browse Source
This commit is contained in:
Philipp Kunz 2024-04-14 18:59:49 +02:00
parent fba724741b
commit 53aece818a
4 changed files with 165 additions and 31 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
npmextra.json
View File

@ -2,17 +2,29 @@
"gitzone": {
"projectType": "npm",
"module": {
"githost": "gitlab.com",
"githost": "code.foss.global",
"gitscope": "api.global",
"gitrepo": "typedrequest-interfaces",
"description": "interfaces for making typed requests",
"description": "A library providing interfaces for making typed HTTP requests.",
"npmPackagename": "@api.global/typedrequest-interfaces",
"license": "MIT",
"projectDomain": "api.global"
"projectDomain": "api.global",
"keywords": [
"HTTP",
"requests",
"interfaces",
"TypeScript",
"streaming",
"API",
"virtual streams"
]
}
},
"npmci": {
"npmGlobalTools": [],
"npmAccessLevel": "public"
},
"tsdoc": {
"legal": "\n## License and Legal Information\n\nThis repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository. \n\n**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.\n\n### Trademarks\n\nThis 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 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, and any usage must be approved in writing by Task Venture Capital GmbH.\n\n### Company Information\n\nTask Venture Capital GmbH \nRegistered at District court Bremen HRB 35230 HB, Germany\n\nFor any legal inquiries or if you require further information, please contact us via email at hello@task.vc.\n\nBy 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.\n"
}
}

13
package.json
View File

@ -2,7 +2,7 @@
"name": "@api.global/typedrequest-interfaces",
"version": "3.0.18",
"private": false,
"description": "interfaces for making typed requests",
"description": "A library providing interfaces for making typed HTTP requests.",
"main": "dist_ts/index.js",
"typings": "dist_ts/index.d.ts",
"author": "Lossless GmbH",
@ -35,5 +35,14 @@
"type": "module",
"browserslist": [
"last 1 chrome versions"
],
"keywords": [
"HTTP",
"requests",
"interfaces",
"TypeScript",
"streaming",
"API",
"virtual streams"
]
}
}

1
readme.hints.md Normal file
View File

@ -0,0 +1 @@

164
readme.md
View File

@ -1,39 +1,151 @@
# @api.global/typedrequest-interfaces
interfaces for making typed requests
## Availabililty and Links
* [npmjs.org (npm package)](https://www.npmjs.com/package/@api.global/typedrequest-interfaces)
* [gitlab.com (source)](https://gitlab.com/api.global/typedrequest-interfaces)
* [github.com (source mirror)](https://github.com/api.global/typedrequest-interfaces)
* [docs (typedoc)](https://api.global.gitlab.io/typedrequest-interfaces/)
## Install
## Status for master
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:
Status Category | Status Badge
-- | --
GitLab Pipelines | [![pipeline status](https://gitlab.com/api.global/typedrequest-interfaces/badges/master/pipeline.svg)](https://lossless.cloud)
GitLab Pipline Test Coverage | [![coverage report](https://gitlab.com/api.global/typedrequest-interfaces/badges/master/coverage.svg)](https://lossless.cloud)
npm | [![npm downloads per month](https://badgen.net/npm/dy/@api.global/typedrequest-interfaces)](https://lossless.cloud)
Snyk | [![Known Vulnerabilities](https://badgen.net/snyk/api.global/typedrequest-interfaces)](https://lossless.cloud)
TypeScript Support | [![TypeScript](https://badgen.net/badge/TypeScript/>=%203.x/blue?icon=typescript)](https://lossless.cloud)
node Support | [![node](https://img.shields.io/badge/node->=%2010.x.x-blue.svg)](https://nodejs.org/dist/latest-v10.x/docs/api/)
Code Style | [![Code Style](https://badgen.net/badge/style/prettier/purple)](https://lossless.cloud)
PackagePhobia (total standalone install weight) | [![PackagePhobia](https://badgen.net/packagephobia/install/@api.global/typedrequest-interfaces)](https://lossless.cloud)
PackagePhobia (package size on registry) | [![PackagePhobia](https://badgen.net/packagephobia/publish/@api.global/typedrequest-interfaces)](https://lossless.cloud)
BundlePhobia (total size when bundled) | [![BundlePhobia](https://badgen.net/bundlephobia/minzip/@api.global/typedrequest-interfaces)](https://lossless.cloud)
```bash
npm install @api.global/typedrequest-interfaces --save
```
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
## Contribution
To use the `@api.global/typedrequest-interfaces` package in your TypeScript project, follow the steps below. This package provides interfaces for making typed requests, which can help enforce a structured request and response pattern in your applications.
We are always happy for code contributions. If you are not the code contributing type that is ok. Still, maintaining Open Source repositories takes considerable time and thought. If you like the quality of what we do and our modules are useful to you we would appreciate a little monthly contribution: You can [contribute one time](https://lossless.link/contribute-onetime) or [contribute monthly](https://lossless.link/contribute). :)
### Setting Up Your Project
## Contribution
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:
We are always happy for code contributions. If you are not the code contributing type that is ok. Still, maintaining Open Source repositories takes considerable time and thought. If you like the quality of what we do and our modules are useful to you we would appreciate a little monthly contribution: You can [contribute one time](https://lossless.link/contribute-onetime) or [contribute monthly](https://lossless.link/contribute). :)
```json
{
"compilerOptions": {
"target": "ESNext",
"module": "ESNext",
"moduleResolution": "node",
"outDir": "./dist",
"declaration": true,
"esModuleInterop": true,
"experimentalDecorators": true,
"forceConsistentCasingInFileNames": true
},
"include": ["src/**/*"]
}
```
For further information read the linked docs at the top of this readme.
Adjust the settings according to your project requirements. This configuration supports modern JavaScript features and TypeScript.
## Legal
> MIT licensed | **©** [Task Venture Capital GmbH](https://task.vc)
| By using this npm module you agree to our [privacy policy](https://lossless.gmbH/privacy)
### 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, IVirtualStream, IStreamRequest } 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.
### 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
For more advanced use cases, like handling data streams, the `IVirtualStream` interface can be implemented as follows:
```typescript
// Example: Implementing a virtual stream
class MyStream implements IVirtualStream<Uint8Array> {
side = 'requesting';
streamId = 'myStream123';
sendMethod = async (data: Uint8Array) => { /* Implementation here */ };
// Implement other required methods...
}
```
### Working with Stream Requests
Stream requests allow for handling requests that involve streaming data. Here is how you can use the `IStreamRequest` interface:
```typescript
// Example: Using an IStreamRequest
const myStreamRequest: IStreamRequest = {
method: '##VirtualStream##',
request: {
streamId: 'myStream123',
cycleId: 'cycle456',
cycle: 'request',
mainPurpose: 'start'
// More properties here...
},
response: {
// Response structure here...
}
};
```
This setup demonstrates creating a request for initializing a virtual stream. Other `mainPurpose` values like 'chunk', 'read', 'end', and 'feedback' can also be used depending on the interaction with the stream.
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 that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository.
**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 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, and any usage must be approved in writing by Task Venture Capital GmbH.
### Company Information
Task Venture Capital GmbH
Registered at District court Bremen HRB 35230 HB, Germany
For any legal inquiries or if you require 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.