# @probitas/client

> Version: 0.5.0

Core utilities and types for Probitas client libraries.

This package provides shared types, error classes, and utilities used across
all [`@probitas/*`](https://jsr.io/@probitas) client packages.

## Features

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

## Installation

```bash
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.

```ts
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");
  }
}
```

## Related Packages

| Package | Description |
|---------|-------------|
| [`@probitas/client-http`](https://jsr.io/@probitas/client-http) | HTTP client |
| [`@probitas/client-graphql`](https://jsr.io/@probitas/client-graphql) | GraphQL client |
| [`@probitas/client-grpc`](https://jsr.io/@probitas/client-grpc) | gRPC client |
| [`@probitas/client-connectrpc`](https://jsr.io/@probitas/client-connectrpc) | ConnectRPC client |
| [`@probitas/client-sql-postgres`](https://jsr.io/@probitas/client-sql-postgres) | PostgreSQL client |
| [`@probitas/client-sql-mysql`](https://jsr.io/@probitas/client-sql-mysql) | MySQL client |
| [`@probitas/client-sql-sqlite`](https://jsr.io/@probitas/client-sql-sqlite) | SQLite client |
| [`@probitas/client-sql-duckdb`](https://jsr.io/@probitas/client-sql-duckdb) | DuckDB client |
| [`@probitas/client-deno-kv`](https://jsr.io/@probitas/client-deno-kv) | Deno KV client |
| [`@probitas/client-redis`](https://jsr.io/@probitas/client-redis) | Redis client |
| [`@probitas/client-mongodb`](https://jsr.io/@probitas/client-mongodb) | MongoDB client |
| [`@probitas/client-rabbitmq`](https://jsr.io/@probitas/client-rabbitmq) | RabbitMQ client |
| [`@probitas/client-sqs`](https://jsr.io/@probitas/client-sqs) | AWS SQS client |

## Links

- [GitHub Repository](https://github.com/probitas-test/probitas-client)
- [Probitas Framework](https://github.com/probitas-test/probitas)


## Classes

### `ClientError`

```typescript
class ClientError extends Error
```

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

**Constructor:**

```typescript
new ClientError(message: string, _: unknown, options?: ErrorOptions)
```

**Properties:**

- [readonly] `name`: `string`
- [readonly] `kind`: `string`

---

### `ConnectionError`

```typescript
class ConnectionError extends ClientError
```

Error thrown when a connection cannot be established.

**Constructor:**

```typescript
new ConnectionError(message: string, options?: ErrorOptions)
```

**Properties:**

- [readonly] `name`: `string`
- [readonly] `kind`: `"connection"`

---

### `TimeoutError`

```typescript
class TimeoutError extends ClientError
```

Error thrown when an operation times out.

**Constructor:**

```typescript
new TimeoutError(message: string, timeoutMs: number, options?: ErrorOptions)
```

**Properties:**

- [readonly] `name`: `string`
- [readonly] `kind`: `"timeout"`
- [readonly] `timeoutMs`: `number`

---

### `AbortError`

```typescript
class AbortError extends ClientError
```

Error thrown when an operation is aborted via AbortSignal.

**Constructor:**

```typescript
new AbortError(message: string, options?: ErrorOptions)
```

**Properties:**

- [readonly] `name`: `string`
- [readonly] `kind`: `"abort"`

---

## Interfaces

### `CommonConnectionConfig`

```typescript
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.


**Properties:**

- [readonly] `host?`: `string` — Hostname or IP address.
- [readonly] `port?`: `number` — Port number. Each service has its own default.
- [readonly] `username?`: `string` — Username for authentication.
- [readonly] `password?`: `string` — Password for authentication.

**Example:**

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

Use with config object
```ts
import { createHttpClient } from "@probitas/client-http";
const client = createHttpClient({
  url: {
    host: "api.example.com",
    port: 443,
    username: "user",
    password: "secret",
  },
});
await client[Symbol.asyncDispose]();
```

---

### `RetryOptions`

```typescript
interface RetryOptions
```

Retry configuration options.

**Properties:**

- [readonly] `maxAttempts?`: `number` — Maximum number of attempts (1 = no retry).
- [readonly] `backoff?`: `"linear" | "exponential"` — Backoff strategy.
- [readonly] `initialDelay?`: `number` — Initial delay in milliseconds.
- [readonly] `maxDelay?`: `number` — Maximum delay in milliseconds.
- [readonly] `retryOn?`: `(error: Error) => unknown` — Function to determine if the error should trigger a retry.

---

### `CommonOptions`

```typescript
interface CommonOptions
```

Common options shared across all clients.

**Properties:**

- [readonly] `timeout?`: `number` — Timeout in milliseconds.
- [readonly] `signal?`: `AbortSignal` — AbortSignal for cancellation.
- [readonly] `retry?`: `RetryOptions` — Retry configuration.

---

### `ClientResult`

```typescript
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 {@link ClientError} where `kind` is used instead of `type`
for consistency across the framework.


**Properties:**

- [readonly] `kind`: `string` — 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`.
- [readonly] `processed`: `boolean` — 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".
- [readonly] `ok`: `boolean` — 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`.
- [readonly] `error`: `Error | 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).
- [readonly] `duration`: `number` — Operation duration in milliseconds.

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

**Example:**

```ts
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;
  }
}
```

---

## Related Links

### This Package

- [`RetryOptions`](https://probitas-test.github.io/documents/api/client#RetryOptions)

### Built-in Types

- [`Error`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error)

---

*Last updated: 2026-01-12*