GitHub

@probitas/client

v0.4.2 View on JSR

Core utilities and types for Probitas client libraries.

This package provides shared types, error classes, and utilities used across all `@probitas/*` client packages.

Features

  • Common Options: Shared configuration types like CommonOptions and RetryOptions
  • Error Hierarchy: Base error classes (ClientError, ConnectionError, TimeoutError, AbortError)

Installation

deno add jsr:@probitas/client

Usage

This package is typically used as a dependency by other client packages. End users rarely need to import from it directly.

import type { CommonOptions, RetryOptions } from "@probitas/client";
import { ClientError, ConnectionError, TimeoutError } from "@probitas/client";

// Use CommonOptions for timeout and abort signal support
async function fetchData(options?: CommonOptions) {
  // Implementation with timeout and signal handling
}

// Catch and handle errors
try {
  await fetchData({ timeout: 5000 });
} catch (error) {
  if (error instanceof TimeoutError) {
    console.log(`Timed out after ${error.timeoutMs}ms`);
  } else if (error instanceof ConnectionError) {
    console.log("Failed to connect");
  }
}
PackageDescription
`@probitas/client-http`HTTP client
`@probitas/client-graphql`GraphQL client
`@probitas/client-grpc`gRPC client
`@probitas/client-connectrpc`ConnectRPC client
`@probitas/client-sql-postgres`PostgreSQL client
`@probitas/client-sql-mysql`MySQL client
`@probitas/client-sql-sqlite`SQLite client
`@probitas/client-sql-duckdb`DuckDB client
`@probitas/client-deno-kv`Deno KV client
`@probitas/client-redis`Redis client
`@probitas/client-mongodb`MongoDB client
`@probitas/client-rabbitmq`RabbitMQ client
`@probitas/client-sqs`AWS SQS client

Installation

deno add jsr:@probitas/client

Classes

class

#AbortError

class AbortError extends ClientError
ExtendsClientError

Error thrown when an operation is aborted via AbortSignal.

NameDescription
name—
kind—
Constructor
new AbortError(message: string, options?: ErrorOptions)
Properties
  • readonlynamestring
  • readonlykind"abort"
Links
class

#ClientError

class ClientError extends Error
ExtendsError

Base error class for all client errors.

The kind property is typed as string to allow client-specific packages to define their own error kinds without modifying this core package. Subclasses can narrow the type using literal types with as const.

NameDescription
name—
kind—
Constructor
new ClientError(message: string, _: unknown, options?: ErrorOptions)
Properties
  • readonlynamestring
  • readonlykindstring
class

#ConnectionError

class ConnectionError extends ClientError
ExtendsClientError

Error thrown when a connection cannot be established.

NameDescription
name—
kind—
Constructor
new ConnectionError(message: string, options?: ErrorOptions)
Properties
  • readonlynamestring
  • readonlykind"connection"
Links
class

#TimeoutError

class TimeoutError extends ClientError
ExtendsClientError

Error thrown when an operation times out.

NameDescription
name—
kind—
timeoutMs—
Constructor
new TimeoutError(message: string, timeoutMs: number, options?: ErrorOptions)
Properties
  • readonlynamestring
  • readonlykind"timeout"
  • readonlytimeoutMsnumber
Links

Interfaces

interface

#ClientResult

interface ClientResult

Base interface for all client result types.

All client operation results (responses, query results, etc.) extend this interface, providing a consistent structure across all Probitas clients. The kind property serves as a discriminator for type-safe switch statements.

This mirrors the design of ClientError where kind is used instead of type for consistency across the framework.

Examples
import type { ClientResult } from "@probitas/client";

interface HttpResponse extends ClientResult {
  readonly kind: "http";
  readonly status: number;
}

interface SqlQueryResult extends ClientResult {
  readonly kind: "sql";
  readonly rowCount: number;
}

type MyResult = HttpResponse | SqlQueryResult;

function handleResult(result: MyResult) {
  // Check if request reached the server
  if (!result.processed) {
    console.error("Network failure:", result.error);
    return;
  }

  // Check if operation succeeded
  if (!result.ok) {
    console.error("Operation failed:", result.error);
    return;
  }

  // Type narrowing by kind
  switch (result.kind) {
    case "http":
      console.log(`HTTP ${result.status} in ${result.duration}ms`);
      break;
    case "sql":
      console.log(`${result.rowCount} rows in ${result.duration}ms`);
      break;
  }
}
NameDescription
kindResult kind discriminator.
processedWhether the operation was processed by the server.
okWhether the operation succeeded.
errorError that occurred during the operation (null if successful).
durationOperation duration in milliseconds.
Properties
  • readonlykindstring

    Result kind discriminator.

    The kind property is typed as string to allow client-specific packages to define their own result kinds without modifying this core package. Subinterfaces can narrow the type using literal types with as const.

  • readonlyprocessedboolean

    Whether the operation was processed by the server.

    • true: Server received and processed the request (success or error response)
    • false: Request failed before reaching the server (network error, timeout, etc.)

    Use this to distinguish between "server returned an error" and "couldn't reach server".

  • readonlyokboolean

    Whether the operation succeeded.

    For HTTP responses, this corresponds to status 200-299. For database operations, this indicates successful execution. Always false when processed is false.

  • readonlyerrorError | null

    Error that occurred during the operation (null if successful).

    Contains the error when ok is false. The specific error type depends on the client kind (e.g., HttpError, GraphqlError, SqlError).

  • readonlydurationnumber

    Operation duration in milliseconds.

    Measured from operation start to completion, useful for performance analysis and timeout monitoring.

interface

#CommonConnectionConfig

interface CommonConnectionConfig

Common connection configuration shared across all network clients.

This interface provides a unified way to configure connection parameters for all network-based clients. Each client extends this with service-specific options while maintaining a consistent base.

Examples

Use with string URL

import { createHttpClient } from "@probitas/client-http";
const client = createHttpClient({ url: "http://localhost:3000" });
await client[Symbol.asyncDispose]();

Use with config object

import { createHttpClient } from "@probitas/client-http";
const client = createHttpClient({
  url: {
    host: "api.example.com",
    port: 443,
    username: "user",
    password: "secret",
  },
});
await client[Symbol.asyncDispose]();
NameDescription
hostHostname or IP address.
portPort number.
usernameUsername for authentication.
passwordPassword for authentication.
Properties
  • readonlyhost?string

    Hostname or IP address.

  • readonlyport?number

    Port number. Each service has its own default.

  • readonlyusername?string

    Username for authentication.

  • readonlypassword?string

    Password for authentication.

interface

#CommonOptions

interface CommonOptions

Common options shared across all clients.

NameDescription
timeoutTimeout in milliseconds.
signalAbortSignal for cancellation.
retryRetry configuration.
Properties
  • readonlytimeout?number

    Timeout in milliseconds.

  • readonlysignal?AbortSignal

    AbortSignal for cancellation.

  • readonlyretry?RetryOptions

    Retry configuration.

Links
interface

#RetryOptions

interface RetryOptions

Retry configuration options.

NameDescription
maxAttemptsMaximum number of attempts (1 = no retry).
backoffBackoff strategy.
initialDelayInitial delay in milliseconds.
maxDelayMaximum delay in milliseconds.
retryOnFunction to determine if the error should trigger a retry.
Properties
  • readonlymaxAttempts?number

    Maximum number of attempts (1 = no retry).

  • readonlybackoff?"linear" | "exponential"

    Backoff strategy.

  • readonlyinitialDelay?number

    Initial delay in milliseconds.

  • readonlymaxDelay?number

    Maximum delay in milliseconds.

  • readonlyretryOn?(error: Error) => unknown

    Function to determine if the error should trigger a retry.

Search Documentation