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

changelog.md

@@ -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
 

readme.md

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

test/test.legacy.ts

@@ -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')
+    .property('json')
-    .toEqual('fa4c6baa0812e5b5c80ed8885e55a8a6');
+    .property('text')
+    .toEqual('example_text');
 });
 
 tap.test('should safe get stuff', async () => {

test/test.modern.ts

@@ -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();

ts/00_commitinfo_data.ts

@@ -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.'
 }

ts/modern/features/pagination.ts

@@ -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) 
+  let items: T[] = Array.isArray(response.body)
-    ? 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;
 }

ts/modern/smartrequestclient.ts

@@ -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 { HttpMethod, ResponseType, FormField } from './types/common.js';
-import type {
+import {
-  TPaginationConfig, 
+  type TPaginationConfig,
-  PaginationStrategy, 
+  PaginationStrategy,
-  OffsetPaginationConfig,
+  type OffsetPaginationConfig,
-  CursorPaginationConfig,
+  type CursorPaginationConfig,
-  CustomPaginationConfig,
+  type CustomPaginationConfig,
-  TPaginatedResponse 
+  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, 
+      response,
-      this._paginationConfig, 
+      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;
   }