push.rocks/smartrequest
2
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

feat(docs): Enhance documentation and tests with modern API usage examples and migration guide

Browse Source
This commit is contained in:
Philipp Kunz 2025-04-03 06:52:58 +00:00
parent 96820090d4
commit b8f545cdd5
7 changed files with 382 additions and 72 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
changelog.md
View File

@ -1,5 +1,14 @@
# Changelog
## 2025-04-03 - 2.1.0 - feat(docs)
Enhance documentation and tests with modern API usage examples and migration guide
- Updated README to include detailed examples for the modern fluent API, covering GET, POST, headers, query, timeout, retries, and pagination
- Added a migration guide comparing the legacy API and modern API usage
- Improved installation instructions with npm, pnpm, and yarn examples
- Added and updated test files for both legacy and modern API functionalities
- Minor formatting improvements in the code and documentation examples
## 2024-11-06 - 2.0.23 - fix(core)
Enhance type safety for response in binary requests

225
readme.md
View File

@ -1,17 +1,29 @@
# @push.rocks/smartrequest
A module providing a drop-in replacement for the deprecated Request library, focusing on modern HTTP/HTTPS requests with support for form data, file uploads, JSON, binary data, and streams.
A module providing a drop-in replacement for the deprecated Request library, focusing on modern HTTP/HTTPS requests with support for form data, file uploads, JSON, binary data, and streams. The library offers both a legacy API and a modern fluent API for maximum flexibility.
## Install
To install `@push.rocks/smartrequest`, use the following npm command:
To install `@push.rocks/smartrequest`, use one of the following commands:
```bash
# Using npm
npm install @push.rocks/smartrequest --save
# Using pnpm
pnpm add @push.rocks/smartrequest
# Using yarn
yarn add @push.rocks/smartrequest
```
This command will add `@push.rocks/smartrequest` to your project's dependencies.
This will add `@push.rocks/smartrequest` to your project's dependencies.
## Usage
`@push.rocks/smartrequest` is designed as a versatile, modern HTTP client library for making HTTP/HTTPS requests. It supports a range of features, including handling form data, file uploads, JSON requests, binary data, streaming, and much more, all within a modern, promise-based API.
`@push.rocks/smartrequest` is designed as a versatile, modern HTTP client library for making HTTP/HTTPS requests. It supports a range of features, including handling form data, file uploads, JSON requests, binary data, streaming, pagination, and much more, all within a modern, promise-based API.
The library provides two distinct APIs:
1. **Legacy API** - Simple function-based API for quick and straightforward HTTP requests
2. **Modern Fluent API** - A chainable, builder-style API for more complex scenarios and better TypeScript integration
Below we will cover key usage scenarios of `@push.rocks/smartrequest`, showcasing its capabilities and providing you with a solid starting point to integrate it into your projects.
@ -117,11 +129,210 @@ customRequestExample();
`request` is the underlying function that powers the simpler `getJson`, `postJson`, etc., and provides you with full control over the HTTP request.
Through its comprehensive set of features tailored for modern web development, `@push.rocks/smartrequest` aims to provide developers with a powerful tool for handling HTTP/HTTPS requests efficiently. Whether it's a simple API call, handling form data, or processing streams, `@push.rocks/smartrequest` delivers a robust, type-safe solution to fit your project's requirements.
## Modern Fluent API
In addition to the legacy API shown above, `@push.rocks/smartrequest` provides a modern, fluent API that offers a more chainable and TypeScript-friendly approach to making HTTP requests.
### Basic Usage with the Modern API
```typescript
import { SmartRequestClient } from '@push.rocks/smartrequest';
// Simple GET request
async function fetchUserData(userId: number) {
const response = await SmartRequestClient.create()
.url(`https://jsonplaceholder.typicode.com/users/${userId}`)
.get();
console.log(response.body); // The JSON response
}
// POST request with JSON body
async function createPost(title: string, body: string, userId: number) {
const response = await SmartRequestClient.create()
.url('https://jsonplaceholder.typicode.com/posts')
.json({ title, body, userId })
.post();
console.log(response.body); // The created post
}
```
### Setting Headers and Query Parameters
```typescript
import { SmartRequestClient } from '@push.rocks/smartrequest';
async function searchRepositories(query: string, perPage: number = 10) {
const response = await SmartRequestClient.create()
.url('https://api.github.com/search/repositories')
.header('Accept', 'application/vnd.github.v3+json')
.query({
q: query,
per_page: perPage.toString()
})
.get();
return response.body.items;
}
```
### Handling Timeouts and Retries
```typescript
import { SmartRequestClient } from '@push.rocks/smartrequest';
async function fetchWithRetry(url: string) {
const response = await SmartRequestClient.create()
.url(url)
.timeout(5000) // 5 seconds timeout
.retry(3) // Retry up to 3 times on failure
.get();
return response.body;
}
```
### Working with Different Response Types
```typescript
import { SmartRequestClient } from '@push.rocks/smartrequest';
// Binary data
async function downloadImage(url: string) {
const response = await SmartRequestClient.create()
.url(url)
.responseType('binary')
.get();
// response.body is a Buffer
return response.body;
}
// Streaming response
async function streamLargeFile(url: string) {
const response = await SmartRequestClient.create()
.url(url)
.responseType('stream')
.get();
// response is a stream
response.on('data', (chunk) => {
console.log(`Received ${chunk.length} bytes of data`);
});
return new Promise((resolve, reject) => {
response.on('end', resolve);
response.on('error', reject);
});
}
```
### Pagination Support
The modern API includes built-in support for various pagination strategies:
```typescript
import { SmartRequestClient, PaginationStrategy } from '@push.rocks/smartrequest';
// Offset-based pagination (page & limit)
async function fetchAllUsers() {
const client = SmartRequestClient.create()
.url('https://api.example.com/users')
.withOffsetPagination({
pageParam: 'page',
limitParam: 'limit',
startPage: 1,
pageSize: 20,
totalPath: 'meta.total'
});
// Get first page with pagination info
const firstPage = await client.getPaginated();
console.log(`Found ${firstPage.items.length} users on first page`);
console.log(`Has more pages: ${firstPage.hasNextPage}`);
if (firstPage.hasNextPage) {
// Get next page
const secondPage = await firstPage.getNextPage();
console.log(`Found ${secondPage.items.length} more users`);
}
// Or get all pages at once (use with caution for large datasets)
const allUsers = await client.getAllPages();
console.log(`Retrieved ${allUsers.length} users in total`);
}
// Cursor-based pagination
async function fetchAllPosts() {
const allPosts = await SmartRequestClient.create()
.url('https://api.example.com/posts')
.withCursorPagination({
cursorParam: 'cursor',
cursorPath: 'meta.nextCursor',
hasMorePath: 'meta.hasMore'
})
.getAllPages();
console.log(`Retrieved ${allPosts.length} posts in total`);
}
// Link header-based pagination (GitHub API style)
async function fetchAllIssues(repo: string) {
const paginatedResponse = await SmartRequestClient.create()
.url(`https://api.github.com/repos/${repo}/issues`)
.header('Accept', 'application/vnd.github.v3+json')
.withLinkPagination()
.getPaginated();
return paginatedResponse.getAllPages();
}
```
### Convenience Factory Functions
The library provides several factory functions for common use cases:
```typescript
import { createJsonClient, createBinaryClient, createStreamClient } from '@push.rocks/smartrequest';
// Pre-configured for JSON requests
const jsonClient = createJsonClient()
.url('https://api.example.com/data')
.get();
// Pre-configured for binary data
const binaryClient = createBinaryClient()
.url('https://example.com/image.jpg')
.get();
// Pre-configured for streaming
const streamClient = createStreamClient()
.url('https://example.com/large-file')
.get();
```
Through its comprehensive set of features tailored for modern web development, `@push.rocks/smartrequest` aims to provide developers with a powerful tool for handling HTTP/HTTPS requests efficiently. Whether it's a simple API call, handling form data, processing streams, or working with paginated APIs, `@push.rocks/smartrequest` delivers a robust, type-safe solution to fit your project's requirements.
## Migration Guide: Legacy API to Modern API
If you're currently using the legacy API and want to migrate to the modern fluent API, here's a quick reference guide:
| Legacy API | Modern API |
|------------|------------|
| `getJson(url)` | `SmartRequestClient.create().url(url).get()` |
| `postJson(url, { requestBody: data })` | `SmartRequestClient.create().url(url).json(data).post()` |
| `putJson(url, { requestBody: data })` | `SmartRequestClient.create().url(url).json(data).put()` |
| `delJson(url)` | `SmartRequestClient.create().url(url).delete()` |
| `postFormData(url, {}, fields)` | `SmartRequestClient.create().url(url).formData(fields).post()` |
| `getStream(url)` | `SmartRequestClient.create().url(url).responseType('stream').get()` |
| `request(url, options)` | `SmartRequestClient.create().url(url).[...configure options...].get()` |
The modern API provides more flexibility and better TypeScript integration, making it the recommended approach for new projects.
## 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.
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.
@ -131,7 +342,7 @@ This project is owned and maintained by Task Venture Capital GmbH. The names and
### Company Information
Task Venture Capital GmbH
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.

8
test/test.ts → test/test.legacy.ts
View File

@ -14,10 +14,12 @@ tap.test('should request a JSON document over https', async () => {
});
tap.test('should post a JSON document over http', async () => {
await expectAsync(smartrequest.postJson('http://md5.jsontest.com/?text=example_text'))
const testData = { text: 'example_text' };
await expectAsync(smartrequest.postJson('https://httpbin.org/post', { requestBody: testData }))
.property('body')
.property('md5')
.toEqual('fa4c6baa0812e5b5c80ed8885e55a8a6');
.property('json')
.property('text')
.toEqual('example_text');
});
tap.test('should safe get stuff', async () => {

86
test/test.modern.ts Normal file
View File

@ -0,0 +1,86 @@
import { tap, expect } from '@pushrocks/tapbundle';
import { SmartRequestClient } from '../ts/modern/index.js';
tap.test('modern: should request a html document over https', async () => {
const response = await SmartRequestClient.create()
.url('https://encrypted.google.com/')
.get();
expect(response).toHaveProperty('body');
});
tap.test('modern: should request a JSON document over https', async () => {
const response = await SmartRequestClient.create()
.url('https://jsonplaceholder.typicode.com/posts/1')
.get();
expect(response.body).toHaveProperty('id');
expect(response.body.id).toEqual(1);
});
tap.test('modern: should post a JSON document over http', async () => {
const testData = { text: 'example_text' };
const response = await SmartRequestClient.create()
.url('https://httpbin.org/post')
.json(testData)
.post();
expect(response.body).toHaveProperty('json');
expect(response.body.json).toHaveProperty('text');
expect(response.body.json.text).toEqual('example_text');
});
tap.test('modern: should set headers correctly', async () => {
const customHeader = 'X-Custom-Header';
const headerValue = 'test-value';
const response = await SmartRequestClient.create()
.url('https://httpbin.org/headers')
.header(customHeader, headerValue)
.get();
expect(response.body).toHaveProperty('headers');
// Check if the header exists (case-sensitive)
expect(response.body.headers).toHaveProperty(customHeader);
expect(response.body.headers[customHeader]).toEqual(headerValue);
});
tap.test('modern: should handle query parameters', async () => {
const params = { param1: 'value1', param2: 'value2' };
const response = await SmartRequestClient.create()
.url('https://httpbin.org/get')
.query(params)
.get();
expect(response.body).toHaveProperty('args');
expect(response.body.args).toHaveProperty('param1');
expect(response.body.args.param1).toEqual('value1');
expect(response.body.args).toHaveProperty('param2');
expect(response.body.args.param2).toEqual('value2');
});
tap.test('modern: should handle timeout configuration', async () => {
// This test just verifies that the timeout method doesn't throw
const client = SmartRequestClient.create()
.url('https://httpbin.org/get')
.timeout(5000);
const response = await client.get();
expect(response).toHaveProperty('body');
});
tap.test('modern: should handle retry configuration', async () => {
// This test just verifies that the retry method doesn't throw
const client = SmartRequestClient.create()
.url('https://httpbin.org/get')
.retry(1);
const response = await client.get();
expect(response).toHaveProperty('body');
});
tap.start();

2
ts/00_commitinfo_data.ts
View File

@ -3,6 +3,6 @@
*/
export const commitinfo = {
name: '@push.rocks/smartrequest',
version: '2.0.23',
version: '2.1.0',
description: 'A module for modern HTTP/HTTPS requests with support for form data, file uploads, JSON, binary data, streams, and more.'
}

64
ts/modern/features/pagination.ts
View File

@ -11,13 +11,13 @@ export function createPaginatedResponse<T>(
fetchNextPage: (params: Record<string, string>) => Promise<TPaginatedResponse<T>>
): TPaginatedResponse<T> {
// Default to response.body for items if response is JSON
let items: T[] = Array.isArray(response.body)
? response.body
let items: T[] = Array.isArray(response.body)
? response.body
: (response.body?.items || response.body?.data || response.body?.results || []);
let hasNextPage = false;
let nextPageParams: Record<string, string> = {};
// Determine if there's a next page based on pagination strategy
switch (paginationConfig.strategy) {
case PaginationStrategy.OFFSET: {
@ -25,9 +25,9 @@ export function createPaginatedResponse<T>(
const currentPage = parseInt(queryParams[config.pageParam || 'page'] || String(config.startPage || 1));
const limit = parseInt(queryParams[config.limitParam || 'limit'] || String(config.pageSize || 20));
const total = getValueByPath(response.body, config.totalPath || 'total') || 0;
hasNextPage = currentPage * limit < total;
if (hasNextPage) {
nextPageParams = {
...queryParams,
@ -36,14 +36,14 @@ export function createPaginatedResponse<T>(
}
break;
}
case PaginationStrategy.CURSOR: {
const config = paginationConfig;
const nextCursor = getValueByPath(response.body, config.cursorPath || 'nextCursor');
const hasMore = getValueByPath(response.body, config.hasMorePath || 'hasMore');
hasNextPage = !!nextCursor || !!hasMore;
if (hasNextPage && nextCursor) {
nextPageParams = {
...queryParams,
@ -52,50 +52,52 @@ export function createPaginatedResponse<T>(
}
break;
}
case PaginationStrategy.LINK_HEADER: {
const linkHeader = response.headers['link'] || '';
const links = parseLinkHeader(linkHeader);
// Handle both string and string[] types for the link header
const headerValue = Array.isArray(linkHeader) ? linkHeader[0] : linkHeader;
const links = parseLinkHeader(headerValue);
hasNextPage = !!links.next;
if (hasNextPage && links.next) {
// Extract query parameters from next link URL
const url = new URL(links.next);
nextPageParams = {};
url.searchParams.forEach((value, key) => {
nextPageParams[key] = value;
});
}
break;
}
case PaginationStrategy.CUSTOM: {
const config = paginationConfig;
hasNextPage = config.hasNextPage(response);
if (hasNextPage) {
nextPageParams = config.getNextPageParams(response, queryParams);
}
break;
}
}
// Create a function to fetch the next page
const getNextPage = async (): Promise<TPaginatedResponse<T>> => {
if (!hasNextPage) {
throw new Error('No more pages available');
}
return fetchNextPage(nextPageParams);
};
// Create a function to fetch all remaining pages
const getAllPages = async (): Promise<T[]> => {
const allItems = [...items];
let currentPage: TPaginatedResponse<T> = { items, hasNextPage, getNextPage, getAllPages, response };
while (currentPage.hasNextPage) {
try {
currentPage = await currentPage.getNextPage();
@ -104,10 +106,10 @@ export function createPaginatedResponse<T>(
break;
}
}
return allItems;
};
return {
items,
hasNextPage,
@ -123,27 +125,27 @@ export function createPaginatedResponse<T>(
*/
export function parseLinkHeader(header: string): Record<string, string> {
const links: Record<string, string> = {};
if (!header) {
return links;
}
// Split parts by comma
const parts = header.split(',');
// Parse each part into a name:value pair
for (const part of parts) {
const section = part.split(';');
if (section.length < 2) {
continue;
}
const url = section[0].replace(/<(.*)>/, '$1').trim();
const name = section[1].replace(/rel="(.*)"/, '$1').trim();
links[name] = url;
}
return links;
}
@ -155,16 +157,16 @@ export function getValueByPath(obj: any, path?: string): any {
if (!path || !obj) {
return undefined;
}
const keys = path.split('.');
let current = obj;
for (const key of keys) {
if (current === null || current === undefined || typeof current !== 'object') {
return undefined;
}
current = current[key];
}
return current;
}

60
ts/modern/smartrequestclient.ts
View File

@ -2,14 +2,14 @@ import { type ISmartRequestOptions } from '../legacy/smartrequest.interfaces.js'
import { request, type IExtendedIncomingMessage } from '../legacy/smartrequest.request.js';
import * as plugins from '../legacy/smartrequest.plugins.js';
import type { HttpMethod, ResponseType, RetryConfig, TimeoutConfig, FormField } from './types/common.js';
import type {
TPaginationConfig,
PaginationStrategy,
OffsetPaginationConfig,
CursorPaginationConfig,
CustomPaginationConfig,
TPaginatedResponse
import type { HttpMethod, ResponseType, FormField } from './types/common.js';
import {
type TPaginationConfig,
PaginationStrategy,
type OffsetPaginationConfig,
type CursorPaginationConfig,
type CustomPaginationConfig,
type TPaginatedResponse
} from './types/pagination.js';
import { createPaginatedResponse } from './features/pagination.js';
@ -65,7 +65,7 @@ export class SmartRequestClient<T = any> {
*/
formData(data: FormField[]): this {
const form = new plugins.formData();
for (const item of data) {
if (Buffer.isBuffer(item.value)) {
form.append(item.name, item.value, {
@ -76,16 +76,16 @@ export class SmartRequestClient<T = any> {
form.append(item.name, item.value);
}
}
if (!this._options.headers) {
this._options.headers = {};
}
this._options.headers = {
...this._options.headers,
...form.getHeaders()
};
this._options.requestBody = form;
return this;
}
@ -149,11 +149,11 @@ export class SmartRequestClient<T = any> {
*/
responseType(type: ResponseType): this {
this._responseType = type;
if (type === 'binary' || type === 'stream') {
this._options.autoJsonParse = false;
}
return this;
}
@ -177,13 +177,13 @@ export class SmartRequestClient<T = any> {
pageSize: config.pageSize || 20,
totalPath: config.totalPath || 'total'
};
// Add initial pagination parameters
this.query({
[this._paginationConfig.pageParam]: String(this._paginationConfig.startPage),
[this._paginationConfig.limitParam]: String(this._paginationConfig.pageSize)
});
return this;
}
@ -264,24 +264,24 @@ export class SmartRequestClient<T = any> {
if (!this._paginationConfig) {
throw new Error('Pagination not configured. Call one of the pagination methods first.');
}
// Default to GET if no method specified
if (!this._options.method) {
this._options.method = 'GET';
}
const response = await this.execute();
return createPaginatedResponse<ItemType>(
response,
this._paginationConfig,
response,
this._paginationConfig,
this._queryParams,
(nextPageParams) => {
// Create a new client with the same configuration but updated query params
const nextClient = new SmartRequestClient<ItemType>();
Object.assign(nextClient, this);
nextClient._queryParams = nextPageParams;
return nextClient.getPaginated<ItemType>();
}
);
@ -304,28 +304,28 @@ export class SmartRequestClient<T = any> {
}
this._options.queryParams = this._queryParams;
// Handle retry logic
let lastError: Error;
for (let attempt = 0; attempt <= this._retries; attempt++) {
try {
if (this._responseType === 'stream') {
return await request(this._url, this._options, true) as IExtendedIncomingMessage<R>;
} else if (this._responseType === 'binary') {
const response = await request(this._url, this._options, true);
// Handle binary response
const dataPromise = plugins.smartpromise.defer<Buffer>();
const chunks: Buffer[] = [];
response.on('data', (chunk: Buffer) => chunks.push(chunk));
response.on('end', () => {
const buffer = Buffer.concat(chunks);
(response as IExtendedIncomingMessage<R>).body = buffer as any;
dataPromise.resolve();
});
await dataPromise.promise;
return response as IExtendedIncomingMessage<R>;
} else {
@ -334,17 +334,17 @@ export class SmartRequestClient<T = any> {
}
} catch (error) {
lastError = error as Error;
// If this is the last attempt, throw the error
if (attempt === this._retries) {
throw lastError;
}
// Otherwise, wait before retrying
await new Promise(resolve => setTimeout(resolve, 1000));
}
}
// This should never be reached due to the throw in the loop above
throw lastError;
}