{"id":22560163,"url":"https://github.com/santiagovogit/http-client-for-ts","last_synced_at":"2025-11-03T14:05:13.296Z","repository":{"id":267037952,"uuid":"897555889","full_name":"SantiagoVOGIT/http-client-for-ts","owner":"SantiagoVOGIT","description":"A HTTP client for making requests inspired by the design of the Java HTTP client","archived":false,"fork":false,"pushed_at":"2024-12-30T15:41:57.000Z","size":51,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-24T08:22:38.494Z","etag":null,"topics":["api","fetch","fetch-api","http","http-client","http-requests","java","request","typescript","typescript-library"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SantiagoVOGIT.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-12-02T20:43:55.000Z","updated_at":"2024-12-09T12:18:44.000Z","dependencies_parsed_at":"2024-12-07T21:55:08.544Z","dependency_job_id":"a8c5af80-c6a8-4ddc-8c9f-f5e23c2e3672","html_url":"https://github.com/SantiagoVOGIT/http-client-for-ts","commit_stats":null,"previous_names":["santiagovogit/http-client-for-ts"],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SantiagoVOGIT%2Fhttp-client-for-ts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SantiagoVOGIT%2Fhttp-client-for-ts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SantiagoVOGIT%2Fhttp-client-for-ts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SantiagoVOGIT%2Fhttp-client-for-ts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SantiagoVOGIT","download_url":"https://codeload.github.com/SantiagoVOGIT/http-client-for-ts/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248192648,"owners_count":21062718,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","fetch","fetch-api","http","http-client","http-requests","java","request","typescript","typescript-library"],"created_at":"2024-12-07T21:11:45.783Z","updated_at":"2025-11-03T14:05:13.291Z","avatar_url":"https://github.com/SantiagoVOGIT.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# http-client-for-ts\n\n[![npm version](https://badge.fury.io/js/http-client-for-ts.svg)](https://badge.fury.io/js/http-client-for-ts)[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)  \n[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)\n[![Node.js](https://img.shields.io/badge/Node.js-18%2B-green.svg)](https://nodejs.org/)\n[![ESM](https://img.shields.io/badge/ESM-Native-purple.svg)]()\n\nModern TypeScript HTTP client with a fluent API inspired by Java's HttpClient,\nproviding an elegant abstraction layer over the Fetch API.\n\n## Features\n\n- 📦 **Zero Dependencies**: Lightweight ESM-native with minimal bundle impact\n- 📝 **Type Safety**: Full TypeScript support with generic responses\n- 🏗️ **Builder Pattern**: Fluent API for configuring clients and requests\n- 🔄 **Auto Serialization**: Built-in serialization/deserialization for request and response bodies\n- ⏱️ **Timeout Support**: Built-in request cancellation and timeout handling\n- 🔒 **Immutable Objects**: Thread-safe request/response handling\n- ⚡ **Fetch API Based**: High performance through native browser/Node.js APIs\n- 🔍 **Smart Error Handling**: Dedicated exception types for different scenarios\n\n## Why Choose http-client-for-ts?\n\n### 🎯 **Java-Inspired Design**\n\nFamiliar builder pattern for enterprise developers transitioning from Java ecosystem.\n\n### 🛡️ **Type Safety First**\n\nBuilt from the ground up with TypeScript, not retrofitted onto JavaScript.\n\n### ⚡ **Modern \u0026 Lightweight**\n\n- ESM-only for optimal tree-shaking\n- Promise-based, modern async interface\n- Zero dependencies\n- Native Fetch API performance\n\n### 🔒 **Immutable by Design**\n\nThread-safe objects that prevent accidental mutations and race conditions.\n\n## Table of Contents\n\n- [Installation](#installation)\n- [Quick Start](#quick-start)\n- [Error Handling](#error-handling)\n- [Core API](#core-api)\n- [Migration from CommonJS](#migration-from-commonjs)\n- [Contributing](#contributing)\n\n## Installation\n\n```bash\nnpm install http-client-for-ts\n```\n\n### Requirements\n\n- **Node.js** ≥ 18.0.0\n- **TypeScript** ≥ 5.0.0\n\n\u003e **Note**: This library uses ESM modules and requires Node.js 18+ with native Fetch API support.\n\n## Quick Start\n\n```typescript\nimport { HttpClient, HttpRequest, HttpMethod } from 'http-client-for-ts';\n\n// Define response type\ninterface User {\n    id: number;\n    name: string;\n    email: string;\n}\n\nconst client = HttpClient.newHttpClient();\n\ntry {\n    // Build request\n    const request = HttpRequest.newBuilder()\n        .url(\"https://jsonplaceholder.typicode.com/users\")\n        .method(HttpMethod.GET)\n        .header(\"Accept\", \"application/json\")\n        .build();\n\n    // Send request and get response\n    const response = await client.send\u003cUser[]\u003e(request);\n\n    if (response.ok()) {\n        const users = response.body();\n        console.log('Found users:', users.length);\n    } else {\n        console.error('API Error:', response.statusCode());\n    }\n} catch (error) {\n    console.error('Request failed:', error.message);\n}\n```\n\n### POST Request with JSON Body\n\n```typescript\nimport { MediaType, HttpHeaders } from 'http-client-for-ts';\n\nconst request = HttpRequest.newBuilder()\n    .url('https://api.example.com/users')\n    .method(HttpMethod.POST)\n    .header(HttpHeaders.CONTENT_TYPE, MediaType.APPLICATION_JSON)\n    .body({\n        name: \"John Doe\",\n        email: \"john@example.com\"\n    })\n    .build();\n```\n\n## Error Handling\n\nThe library provides specific exception types for different error scenarios:\n\n### Basic usage:\n\n```typescript\nimport { HttpException } from 'http-client-for-ts';\n\n// Other code\n\ntry {\n    const response = await client.send\u003cUser[]\u003e(request);\n\n    if (response.ok()) {\n        return response.body();\n    } else {\n        console.error('HTTP Error:', response.statusCode());\n    }\n} catch (error) {\n    if (error instanceof HttpException) {\n        console.error('Request error:', error.message);\n    } else {\n        console.error('Unexpected error:', error);\n    }\n}\n```\n\n### Advanced usage:\n\n```typescript\nimport { HttpTimeoutException, HttpConnectException } from 'http-client-for-ts';\n\n// Other code\n\ntry {\n    const response = await client.send\u003cUser[]\u003e(request);\n\n    if (response.httpStatus().is2xxSuccessful()) {\n        // Process successful response\n        return response.body();\n    } else if (response.httpStatus().is4xxClientError()) {\n        // Handle client error (authentication, validation, etc.)\n        throw new Error(`Client error: ${ response.statusCode() }`);\n    } else if (response.httpStatus().is5xxServerError()) {\n        // Handle server error\n        throw new Error(`Server error: ${ response.statusCode() }`);\n    }\n} catch (error) {\n    if (error instanceof HttpTimeoutException) {\n        console.error(\"Request timeout\");\n    } else if (error instanceof HttpConnectException) {\n        console.error(\"Connection failure\");\n    } else {\n        console.error('Other error:', error.message);\n    }\n}\n```\n\n## Core API\n\n| Component      | Description                                                |\n|----------------|------------------------------------------------------------|\n| `HttpClient`   | Main entry point for sending HTTP requests                 |\n| `HttpRequest`  | Immutable request configuration via builder pattern        |\n| `HttpResponse` | Typed response with status, headers, and deserialized body |\n| `HttpStatus`   | HTTP status codes with utility methods                     |\n| `MediaType`    | Constants for common MIME types                            |\n| `HttpHeaders`  | Constants for standard HTTP headers                        |\n\n## Migration from CommonJS\n\nIf you're migrating from a CommonJS project:\n\n```json\n// package.json\n{\n  \"type\": \"module\"\n}\n```\n\nOr use dynamic imports for legacy projects:\n\n```javascript\n// For legacy projects that can't migrate to ESM yet\nconst { HttpClient } = await import('http-client-for-ts');\n```\n\n## Contributing\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## License\n\n[MIT License](LICENSE) © Santiago Valencia Ochoa","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsantiagovogit%2Fhttp-client-for-ts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsantiagovogit%2Fhttp-client-for-ts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsantiagovogit%2Fhttp-client-for-ts/lists"}