Skip to main content Link Search Menu Expand Document (external link)
ping-cli

helpers overview

HTTP Client Helper Utilities

Provides reusable utilities for making HTTP requests with standard error handling and schema validation.

Architecture Note:

  • Retry logic is added via HttpClientWithRetry wrapper layer at app entry point
  • Caching uses CacheService directly (cannot be done at HttpClient layer due to schema requirement)
  • All helpers only require HttpClient.HttpClient (+ CacheService for cached requests)

Added in v0.0.2

Table of contents

HTTP Helpers

executeCachedRequest

Executes a cached HTTP request with standard error handling and schema validation.

Caching Strategy:

  • Wraps the HTTP request execution with CacheService
  • GET requests are cached with 5-minute TTL
  • Mutations (POST/PUT/PATCH/DELETE) bypass cache and trigger invalidation
  • Cached values are validated with the provided schema

Signature

export declare const executeCachedRequest: <A, I, R>(
  request: HttpClientRequest.HttpClientRequest,
  responseSchema: Schema.Schema<A, I, R>
) => Effect.Effect<
  A,
  PingOneApiError | HttpClientError.HttpClientError | ParseResult.ParseError,
  HttpClient.HttpClient | CacheService | R
>

Added in v0.0.2

executeRequest

Executes an HTTP request with standard error handling and schema validation.

This helper encapsulates the common pattern of:

  1. Executing an HTTP request via HttpClient
  2. Checking response status (2xx = success)
  3. Parsing response body with a schema

Cross-Cutting Concerns: Retry logic and caching are handled by wrapper layers, not in this helper.

Signature

export declare const executeRequest: <A, I, R>(
  request: HttpClientRequest.HttpClientRequest,
  responseSchema: Schema.Schema<A, I, R>
) => Effect.Effect<
  A,
  PingOneApiError | HttpClientError.HttpClientError | ParseResult.ParseError,
  HttpClient.HttpClient | R
>

Added in v0.0.2

executeVoidRequest

Executes an HTTP request without response body parsing.

Useful for DELETE operations or endpoints that return no content (204). Only checks status code and returns the raw response.

Signature

export declare const executeVoidRequest: (
  request: HttpClientRequest.HttpClientRequest
) => Effect.Effect<
  HttpClientResponseType.HttpClientResponse,
  PingOneApiError | HttpClientError.HttpClientError,
  HttpClient.HttpClient
>

Added in v0.0.2