Package Exports

csbridge
csbridge/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (csbridge) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

CSBridge - Client-Server Bridge Utility

Overview

CSBridge is a TypeScript utility library that provides a comprehensive set of tools for handling API requests with robust error handling, retries, and status code management. It's designed to serve as a reliable bridge between client applications and backend services.

Features

Type-Safe API: Fully typed API service with TypeScript interfaces for requests and responses
Comprehensive Status Code Handling: Detailed mapping of HTTP status codes to human-readable messages
Automatic Retry Logic: Configurable exponential backoff retry strategy for transient failures
Error Standardization: Converts various error types to a standardized format using format-the-error
Content Type Detection: Automatically parses responses based on content type (JSON, text, binary)
Upload & Download Support: Specialized methods for file uploads and downloads
Timeout Handling: Built-in request timeout with abort controller
Authentication Support: Easily add authentication tokens to requests
Consistent Error Responses: Utils module provides standardized error responses with success/error patterns

Use Cases

Frontend Applications: Use as the primary HTTP client in React, Vue, Angular, or vanilla TypeScript applications
Backend Services: TypeScript Node.js services can use it for communicating with other microservices
Cross-Platform Apps: Works in any JavaScript environment with fetch support (browsers, Node.js with node-fetch)
API Integrations: Simplify third-party API integrations with standardized error handling

Installation

npm install csbridge

Basic Usage

import apiService from "csbridge";

// GET request
const getUsers = async () => {
  try {
    const response = await apiService.get("/users", {
      params: { limit: 10, offset: 0 },
    });
    return response.data;
  } catch (error) {
    console.error("Failed to fetch users:", error);
    throw error;
  }
};

// POST request with JSON body
const createUser = async (userData) => {
  try {
    const response = await apiService.post("/users", userData);
    return response.data;
  } catch (error) {
    console.error("Failed to create user:", error);
    throw error;
  }
};

// File upload
const uploadUserAvatar = async (userId, file) => {
  try {
    const response = await apiService.upload(`/users/${userId}/avatar`, file, { userId, timestamp: Date.now() });
    return response.data;
  } catch (error) {
    console.error("Failed to upload avatar:", error);
    throw error;
  }
};

Configuration

The library uses a default configuration that can be customized:

import { API_CONFIG } from "csbridge";

// Update configuration
API_CONFIG.baseUrl = "https://api.yourservice.com";
API_CONFIG.timeout = 60000; // 60 seconds
API_CONFIG.retryCount = 3;
API_CONFIG.retryDelay = 500; // 500ms

Advanced Features

Custom Retry Logic

import apiService from "csbridge";

const fetchWithCustomRetry = async () => {
  const response = await apiService.get("/sensitive-data", {
    retry: true,
    retryOptions: {
      retries: 5,
      delay: 1000,
      retriableStatuses: [408, 429, 500, 502, 503, 504],
    },
  });
  return response.data;
};

File Downloads

import apiService from "csbridge";

const downloadReport = async (reportId) => {
  await apiService.download(`/reports/${reportId}/download`, `report-${reportId}.pdf`);
};

Error Handling

The library standardizes errors for consistent handling using the format-the-error library:

import apiService from "csbridge";

const fetchData = async () => {
  try {
    const response = await apiService.get("/data");
    return response.data;
  } catch (error) {
    // Standardized error with: name, message, code, status, data, timestamp
    console.error(`Error ${error.status}: ${error.message}`);

    // Handle specific error codes
    if (error.status === 401) {
      // Handle authentication error
    } else if (error.status === 404) {
      // Handle not found error
    }

    throw error;
  }
};

Enhanced Error Handling with Utils Module

For even more robust error handling, use the utility functions which provide standardized error responses:

import { fetchData } from "csbridge/utils";

const getData = async () => {
  // No try-catch needed - errors are handled and returned in a consistent format
  const response = await fetchData("/data");

  if (response.success) {
    return response.data;
  } else {
    // All errors have the same structure for consistent handling
    console.error(`${response.error?.code}: ${response.error?.message}`);

    // You can check the status code
    if (response.error?.status === 404) {
      console.log("Resource not found");
    }

    // Access additional error details if available
    if (response.error?.details) {
      console.debug("Error details:", response.error.details);
    }

    return null;
  }
};

Utility Functions

The library includes a set of higher-level utility functions in utils.ts that provide standardized responses:

import { fetchData, submitData, updateData, deleteData, createResourceApi } from "csbridge/utils";

// Using generic fetch with standardized response
const getUsersData = async () => {
  const response = await fetchData("/users", { params: { limit: 10 } });

  if (response.success) {
    // Process data
    return response.data;
  } else {
    // Handle error with consistent structure
    console.error(`Error ${response.error?.status}: ${response.error?.message}`);
    return null;
  }
};

// Using the resource API factory for a specific entity
// This creates a complete set of CRUD operations for a resource type
const usersApi = createResourceApi<UserType>("/users");

// Then use these strongly-typed CRUD operations
const createNewUser = async (userData) => {
  const response = await usersApi.create(userData);
  return response.success ? response.data : null;
};

const getUsers = async () => {
  // Get a list of users with pagination
  const response = await usersApi.list({ limit: 20, offset: 0 });
  return response.success ? response.data : [];
};

const getUser = async (userId) => {
  // Get a specific user by ID
  const response = await usersApi.getById(userId);
  return response.success ? response.data : null;
};

const updateUser = async (userId, userData) => {
  // Use update for a full resource replacement
  const response = await usersApi.update(userId, userData);
  return response.success ? response.data : null;
};

const patchUser = async (userId, partialData) => {
  // Use patch for partial updates
  const response = await usersApi.patch(userId, partialData);
  return response.success ? response.data : null;
};

const removeUser = async (userId) => {
  // Delete a resource
  const response = await usersApi.remove(userId);
  return response.success;
};

Resource API Factory

The createResourceApi function creates a complete set of CRUD operations for a specific resource type, making it easy to work with REST APIs in a type-safe way:

// Define your resource type for type safety
interface UserType {
  id: number;
  name: string;
  email: string;
  role: string;
}

// Create a typed API for the users resource
const usersApi = createResourceApi<UserType>("/users");

This factory provides these methods:

Method	Description	Example Usage
`list(params?, options?)`	Get all resources with optional filtering	`usersApi.list({ limit: 20, offset: 0 })`
`getById(id, options?)`	Get a specific resource by ID	`usersApi.getById(123)`
`create(data, options?)`	Create a new resource	`usersApi.create({ name: "John", email: "john@example.com" })`
`update(id, data, options?)`	Replace a resource completely	`usersApi.update(123, userObject)`
`patch(id, data, options?)`	Update a resource partially	`usersApi.patch(123, { name: "Updated Name" })`
`remove(id, options?)`	Delete a resource	`usersApi.remove(123)`

All methods return responses in the standardized format with proper typing.

Standardized Response Format

All utility functions return a consistent response format:

interface StandardResponse<T> {
  success: boolean; // Indicates if the request was successful
  data: T | null; // The response data (when success is true)
  error: {
    // Error details (when success is false)
    message: string; // Human-readable error message
    code?: string; // Error code for programmatic handling
    status?: number; // HTTP status code
    details?: unknown; // Additional error details like stack trace
  } | null;
  meta?: {
    // Optional metadata
    timestamp: string; // Request timestamp
    requestId?: string; // Request ID for tracing
    pagination?: {
      // Pagination details if applicable
      page: number;
      pageSize: number;
      totalItems: number;
      totalPages: number;
    };
  };
}

License

MIT