@dremio/js-sdk 0.40.1 → 0.42.0

package/README.md

@@ -0,0 +1,1043 @@
+# Dremio JavaScript SDK
+
+A JavaScript/TypeScript SDK for interacting with Dremio HTTP APIs.
+
+## Installation
+
+```bash
+npm install @dremio/js-sdk
+```
+
+```bash
+pnpm install @dremio/js-sdk
+```
+
+```bash
+bun install @dremio/js-sdk
+```
+
+### Browser (IIFE)
+
+**jsDelivr:**
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@dremio/js-sdk@latest/dist-iife/cloud.js"></script>
+<script>
+  const { Dremio, fromAccessToken } = window.DremioCloud;
+
+  const dremio = new Dremio({
+    origin: "https://api.dremio.cloud",
+    credentials: fromAccessToken("ACCESS_TOKEN"),
+  });
+</script>
+```
+
+**unpkg:**
+
+```html
+<script src="https://unpkg.com/@dremio/js-sdk@latest/dist-iife/cloud.js"></script>
+<script>
+  const { Dremio, fromAccessToken } = window.DremioCloud;
+  // ... same usage as above
+</script>
+```
+
+### Deno
+
+```typescript
+import { Dremio, fromPat } from "npm:@dremio/js-sdk@latest/cloud";
+
+const dremio = new Dremio({
+  origin: "https://api.dremio.cloud",
+  credentials: fromPat("PERSONAL_ACCESS_TOKEN"),
+});
+```
+
+## Quick Start
+
+```typescript
+import { Dremio, fromAccessToken } from "@dremio/js-sdk/cloud";
+
+const dremio = new Dremio({
+  origin: "https://api.dremio.cloud",
+  credentials: fromAccessToken("ACCESS_TOKEN"),
+});
+
+// Create a `Job` from a SQL query
+const job = await dremio
+  .jobs("PROJECT_ID")
+  .createAndRetrieve({ sql: "SELECT * FROM my_table LIMIT 100" })
+  .then((result) => result.unwrap());
+
+// Retrieve `Job` results as an array
+// Waits for job completion before attempting to fetch results
+const results = await job.results.slice().then((result) => result.unwrap());
+
+// Observe job status in real-time
+const subscription = dremio
+  .jobs("PROJECT_ID")
+  .observe("JOB_ID")
+  .subscribe((result) => {
+    const job = result.unwrap();
+    console.log("Job state:", job.state);
+  });
+```
+
+## Features
+
+### Async Generators
+
+Pagination is handled automatically through the usage of async generators:
+
+```typescript
+// Iterate through pages automatically
+for await (const project of dremio.projects.list().data()) {
+  // Process project
+}
+
+// Or collect all pages at once
+const projects = await Array.fromAsync(dremio.projects.list().data());
+```
+
+### Request Coalescing
+
+When multiple delete or update requests are made synchronously within the same event loop tick, the SDK automatically coalesces them into a single batch API call when available:
+
+```typescript
+// Results in only one bulk HTTP API call
+for (const script of await Array.fromAsync(
+  dremio.scripts("PROJECT_ID").list().data(),
+)) {
+  if (script.owner.id === "USER_ID") {
+    await script.delete();
+  }
+}
+```
+
+### Typed Error Handling
+
+Errors are represented as `Result<T, E>` (see [ts-results-es](https://github.com/vultix/ts-results-es)) to allow type-safe handling of runtime errors. See [Error Handling](#error-handling) for more details.
+
+### Native Data Types
+
+API responses are automatically converted to native JavaScript/TypeScript types:
+
+- ISO 8601 date strings → `Date` objects
+- Timestamps → `Temporal.Instant`
+- Durations → `Temporal.Duration`
+- Large integers → `bigint`
+- Arrays → `Set` or `Map` where appropriate
+
+## Table of Contents
+
+- [Configuration](#configuration)
+- [Authentication](#authentication)
+- [Catalog](#catalog)
+- [Engine Rules](#engine-rules)
+- [Engines](#engines)
+- [Jobs](#jobs)
+- [OAuth Applications](#oauth-applications)
+- [Organizations](#organizations)
+- [Projects](#projects)
+- [Roles](#roles)
+- [Scripts](#scripts)
+- [Users](#users)
+
+## Configuration
+
+The `Dremio` class accepts a configuration object with the following properties:
+
+```typescript
+interface DremioConfig {
+  origin: string;
+  credentials: CredentialProvider;
+  logger?: Logger;
+  fetch?: typeof fetch;
+}
+```
+
+### `origin`
+
+The base API URL of your Dremio instance:
+
+**Dremio Cloud:**
+
+- `"https://api.dremio.cloud"` - US region
+- `"https://api.eu.dremio.cloud"` - EU region
+
+**Dremio Self-Hosted:**
+
+- Your self-hosted Dremio URL (e.g., `"https://dremio.example.com"`)
+
+### `credentials`
+
+A credential provider function that returns authentication headers. See the [Authentication](#authentication) section for available options:
+
+- `fromAccessToken()` - OAuth access token
+- `fromRefreshToken()` - OAuth refresh token (auto-refreshes)
+- `fromPat()` - Personal access token
+
+### `logger` (optional)
+
+A custom logger implementation. Must implement:
+
+```typescript
+interface Logger {
+  debug(message: string, ...args: any[]): void;
+  info(message: string, ...args: any[]): void;
+  warn(message: string, ...args: any[]): void;
+  error(message: string, ...args: any[]): void;
+}
+```
+
+See [Custom Logger](#custom-logger) for examples.
+
+### `fetch` (optional)
+
+A custom fetch implementation. Useful for:
+
+- Adding custom middleware
+- Using a specific fetch polyfill
+- Intercepting requests for testing
+
+Defaults to the global `fetch` function.
+
+## Authentication
+
+### Access Token
+
+```typescript
+import { Dremio, fromAccessToken } from "@dremio/js-sdk/cloud";
+
+const dremio = new Dremio({
+  origin: "https://api.dremio.cloud",
+  credentials: fromAccessToken("your-access-token"),
+});
+```
+
+### Refresh Token
+
+```typescript
+import { Dremio, fromRefreshToken } from "@dremio/js-sdk/cloud";
+
+const credentials = fromRefreshToken({
+  client_id: "your-client-id",
+  redirect_uri: "your-redirect-uri",
+})("your-refresh-token");
+
+const dremio = new Dremio({
+  origin: "https://api.dremio.cloud",
+  credentials,
+});
+```
+
+### Personal Access Token (PAT)
+
+```typescript
+import { Dremio, fromPat } from "@dremio/js-sdk/cloud";
+
+const dremio = new Dremio({
+  origin: "https://api.dremio.cloud",
+  credentials: fromPat("your-personal-access-token"),
+});
+```
+
+## Catalog
+
+### `CatalogReference` Interface
+
+```typescript
+interface CatalogReference {
+  readonly id: string;
+  readonly path: string[];
+  readonly name: string;
+  readonly type:
+    | "DATASET_DIRECT"
+    | "DATASET_PROMOTED"
+    | "DATASET_VIRTUAL"
+    | "FILE"
+    | "FOLDER"
+    | "FUNCTION"
+    | "HOME"
+    | "SOURCE"
+    | "SPACE";
+  pathString(separator?: string): string;
+  catalogObject(): Promise<Result<CatalogObject, unknown>>;
+}
+```
+
+### List Catalog Root
+
+```typescript
+for await (const item of dremio.catalog("PROJECT_ID").list().data()) {
+  console.log(item.path, item.type);
+}
+```
+
+### Retrieve by ID
+
+```typescript
+const catalogObject = await dremio
+  .catalog("PROJECT_ID")
+  .retrieve("CATALOG_ID")
+  .then((result) => result.unwrap());
+```
+
+**Options:**
+
+- `signal`: Optional AbortSignal for request cancellation
+
+### Retrieve by Path
+
+```typescript
+const catalogObject = await dremio
+  .catalog("PROJECT_ID")
+  .retrieveByPath(["SOURCE_NAME", "folder", "table"])
+  .then((result) => result.unwrap());
+```
+
+### Search Catalog
+
+```typescript
+for await (const result of dremio
+  .catalog("PROJECT_ID")
+  .search({
+    query: "sales",
+    filter: 'type=="DATASET"',
+    limit: 50,
+  })
+  .data()) {
+  console.log(result.path, result.type);
+}
+```
+
+**Search Options:**
+
+- `query`: Search query string
+- `filter`: Optional filter expression
+- `limit`: Maximum results per page (default: 25)
+- `signal`: Optional AbortSignal
+
+### Upload Files to Catalog
+
+```typescript
+const uploadLocation = await dremio
+  .catalog("PROJECT_ID")
+  .copyFromObjectStore({
+    sourceName: "SOURCE_NAME",
+    path: ["folder", "dataset.parquet"],
+    extension: "parquet",
+  })
+  .then((result) => result.unwrap());
+```
+
+### Upload and Ingest File (Node.js)
+
+```typescript
+import { Readable } from "node:stream";
+import { createReadStream } from "node:fs";
+
+const job = await dremio
+  .catalog("PROJECT_ID")
+  .upload(Readable.toWeb(createReadStream("./data.csv")), "csv")
+  .andThen((fileUpload) => {
+    const fileFormat = {
+      type: "CSV",
+      comment: "#",
+      escape: '"',
+      extractHeader: true,
+      fieldDelimiter: ",",
+      lineDelimiter: "\r\n",
+      quote: '"',
+      skipLines: 0,
+      emptyAsNull: true,
+      trimSpace: true,
+    } as const;
+    return fileUpload
+      .preview({ fileFormat })
+      .map(({ schema }) => ({ fileFormat, fileUpload, schema }));
+  })
+  .andThen(({ fileFormat, fileUpload, schema }) =>
+    fileUpload.ingest({
+      extension: "csv",
+      fileFormat,
+      schemaFields: schema,
+      namespace: ["@username"],
+      tableName: "my_table",
+    }),
+  )
+  .andThen((jobId) => dremio.jobs("PROJECT_ID").retrieve(jobId))
+  .map((job) => job.retrieveSettled())
+  .then((result) => result.unwrap());
+```
+
+### Upload File with Progress (Browser)
+
+```typescript
+const FILE_FORMAT = {
+  type: "CSV",
+  extractHeader: true,
+  fieldDelimiter: ",",
+  lineDelimiter: "\n",
+  quote: '"',
+  escape: "\\",
+  comment: "#",
+  skipLines: 0,
+  emptyAsNull: true,
+  trimSpace: true,
+} as const;
+
+const fileUpload = await dremio
+  .catalog("PROJECT_ID")
+  .uploadXHR(fileObject, "csv", {
+    onProgress: (e) => {
+      console.log(`Upload progress: ${e.loaded}/${e.total}`);
+    },
+  })
+  .then((result) => result.unwrap());
+
+// Preview and ingest
+const job = await fileUpload
+  .preview({ fileFormat: FILE_FORMAT })
+  .andThen(({ schema }) =>
+    fileUpload.ingest({
+      extension: "csv",
+      fileFormat: FILE_FORMAT,
+      namespace: ["@username"],
+      tableName: "my_table",
+      schemaFields: schema,
+    }),
+  )
+  .andThen((jobId) => dremio.jobs("PROJECT_ID").retrieve(jobId))
+  .map((job) => job.retrieveSettled())
+  .then((result) => result.unwrap());
+```
+
+## Engine Rules
+
+### List Engine Rules
+
+```typescript
+const { rules, defaultRule, tag } = await dremio
+  .engineRules("PROJECT_ID")
+  .list()
+  .then((result) => result.unwrap());
+
+rules.forEach((rule) => {
+  console.log(rule.id, rule.name, rule.engines);
+});
+```
+
+**Options:**
+
+- `signal`: Optional AbortSignal for request cancellation
+
+## Engines
+
+### `Engine` Interface
+
+```typescript
+import { Temporal } from "temporal-polyfill";
+
+type EngineSize =
+  | "XX_SMALL_V1"
+  | "X_SMALL_V1"
+  | "SMALL_V1"
+  | "MEDIUM_V1"
+  | "LARGE_V1"
+  | "X_LARGE_V1"
+  | "XX_LARGE_V1"
+  | "XXX_LARGE_V1";
+
+interface EngineConfiguration {
+  readonly autoStopDelay: Temporal.Duration;
+  readonly cloudTags: Array<{ key: string; value: string }>;
+  readonly description: string | null;
+  readonly drainTimeLimit: Temporal.Duration;
+  readonly maxConcurrency: number;
+  readonly maxReplicas: number;
+  readonly minReplicas: number;
+  readonly queueTimeLimit: Temporal.Duration;
+  readonly runTimeLimit: Temporal.Duration;
+  readonly size: EngineSize;
+}
+
+interface Engine {
+  readonly id: string;
+  readonly name: string;
+  readonly state:
+    | "DELETING"
+    | "DISABLED"
+    | "DISABLING"
+    | "ENABLED"
+    | "ENABLING"
+    | "INVALID";
+  readonly activeReplicas: number;
+  readonly configuration: EngineConfiguration;
+  readonly statusChangedAt: Date;
+  readonly queriedAt: Date | null;
+  update(properties: Partial<EngineConfiguration>): Promise<Engine>;
+}
+```
+
+### List All Engines
+
+```typescript
+for await (const engine of dremio.engines("PROJECT_ID").list().data()) {
+  console.log(engine.id, engine.name, engine.state);
+  console.log("Size:", engine.configuration.size);
+  console.log("Min replicas:", engine.configuration.minReplicas);
+  console.log("Max replicas:", engine.configuration.maxReplicas);
+  console.log("Active replicas:", engine.activeReplicas);
+}
+```
+
+**Options:**
+
+- `signal`: Optional AbortSignal for request cancellation
+
+### Retrieve a Specific Engine
+
+```typescript
+const engine = await dremio
+  .engines("PROJECT_ID")
+  .retrieve("ENGINE_ID")
+  .then((result) => result.unwrap());
+```
+
+### Update Engine Configuration
+
+```typescript
+const engine = await dremio
+  .engines("PROJECT_ID")
+  .retrieve("ENGINE_ID")
+  .then((result) => result.unwrap());
+
+const updatedEngine = await engine.update({
+  size: "LARGE_V1", // Engine size
+  minReplicas: 1,
+  maxReplicas: 5,
+  maxConcurrency: 100,
+  autoStopDelay: Temporal.Duration.from({ minutes: 15 }),
+  description: "Production query engine",
+  cloudTags: [{ key: "environment", value: "production" }],
+});
+```
+
+## Jobs
+
+The `jobs` resource is available for project-level job queries:
+
+```typescript
+// Retrieve job by ID
+const job = await dremio
+  .jobs("PROJECT_ID")
+  .retrieve("JOB_ID")
+  .then((result) => result.unwrap());
+```
+
+### `Job` Interface
+
+```typescript
+interface Job {
+  readonly id: string;
+  readonly state:
+    | "NOT_SUBMITTED"
+    | "STARTING"
+    | "RUNNING"
+    | "COMPLETED"
+    | "CANCELED"
+    | "FAILED"
+    | "CANCELLATION_REQUESTED"
+    | "PLANNING"
+    | "PENDING"
+    | "METADATA_RETRIEVAL"
+    | "QUEUED"
+    | "ENGINE_START"
+    | "EXECUTION_PLANNING"
+    | "INVALID_STATE";
+  readonly queryType:
+    | "UI_RUN"
+    | "UI_PREVIEW"
+    | "ODBC"
+    | "JDBC"
+    | "REST"
+    | "ACCELERATOR_CREATE"
+    | "ACCELERATOR_DROP"
+    | "UNKNOWN";
+  readonly startedAt: Date | null;
+  readonly endedAt: Date | null;
+  readonly rowCount: number | null;
+  readonly errorMessage?: string;
+  readonly settled: boolean;
+  readonly results: {
+    slice: (start?: number, end?: number) => Promise<Result<any[], unknown>>;
+    metadata: () => Promise<
+      Result<{ schema: any; totalRows: number }, unknown>
+    >;
+    jsonBatches: () => AsyncGenerator<any, void, unknown>;
+  };
+  retrieveSettled(): Promise<Job>;
+  cancel(): Promise<Result<void, unknown>>;
+}
+```
+
+For detailed job management methods, refer to the Enterprise/OSS documentation.
+
+## OAuth Applications
+
+### `OAuthApplication` Interface
+
+```typescript
+interface OAuthApplication {
+  readonly id: string;
+  readonly name: string;
+  readonly state: "ENABLED" | "DISABLED";
+  delete(): Promise<Result<void, unknown>>;
+}
+
+interface OAuthApplicationDetails extends OAuthApplication {
+  readonly clientId: string;
+  readonly redirectUris: Set<string>;
+  readonly type: "NATIVE" | "REGULAR_WEB" | "SPA";
+}
+```
+
+### List OAuth Applications
+
+```typescript
+for await (const app of dremio.oauthApplications.list().data()) {
+  // Process app
+}
+```
+
+**Options:**
+
+- `signal`: Optional AbortSignal for request cancellation
+
+### Retrieve an OAuth Application
+
+```typescript
+const app = await dremio.oauthApplications
+  .retrieve("APP_ID")
+  .then((result) => result.unwrap());
+```
+
+**Options:**
+
+- `signal`: Optional AbortSignal for request cancellation
+
+### Create an OAuth Application
+
+```typescript
+const appId = await dremio.oauthApplications
+  .create({
+    name: "My Application",
+    type: "confidential",
+    redirectUris: ["https://myapp.com/callback"],
+  })
+  .then((result) => result.unwrap());
+```
+
+### Delete an OAuth Application
+
+```typescript
+const app = await dremio.oauthApplications
+  .retrieve("APP_ID")
+  .then((result) => result.unwrap());
+
+await app.delete();
+```
+
+## Organizations
+
+### `Organization` Interface
+
+```typescript
+interface Organization {
+  readonly id: string;
+  readonly name: string;
+  readonly state:
+    | "ACTIVE"
+    | "FAILED"
+    | "DELETED"
+    | "INVALID"
+    | "CFT_STARTED"
+    | "CFT_COMPLETE"
+    | "COMMISSIONING";
+  readonly createdAt: Temporal.Instant;
+  readonly createdBy: string;
+  readonly modifiedAt: Temporal.Instant;
+  readonly modifiedBy: string;
+  readonly defaultProjectId: string;
+  readonly cloudTags: Array<{ key: string; value: string }>;
+  readonly settled: boolean;
+  update(fields: {
+    name?: string;
+    defaultProjectId?: string;
+  }): Promise<Result<Organization, unknown>>;
+}
+```
+
+### Retrieve Current Organization
+
+```typescript
+const organization = await dremio.organizations
+  .retrieve()
+  .then((result) => result.unwrap());
+```
+
+**Options:**
+
+- `signal`: Optional AbortSignal for request cancellation
+
+## Projects
+
+### `Project` Interface
+
+```typescript
+interface Project {
+  readonly id: string;
+  readonly name: string;
+  readonly state:
+    | "ACTIVATING"
+    | "ACTIVE"
+    | "ARCHIVED"
+    | "ARCHIVING"
+    | "CREATING"
+    | "DEACTIVATING"
+    | "INACTIVE"
+    | "RESTORING";
+  readonly cloudId: string;
+  readonly cloudType: "AWS" | "AZURE";
+  readonly createdAt: Date;
+  readonly createdBy: string;
+  readonly modifiedAt: Date;
+  readonly modifiedBy: string;
+  readonly numberOfEngines: number;
+  readonly type: "QUERY_ENGINE";
+  readonly settled: boolean;
+  delete(): Promise<Result<undefined, unknown>>;
+  update(properties: { name?: string }): Promise<Result<Project, unknown>>;
+  grants(): Promise<
+    Result<{ grants: Grant[]; availablePrivileges: string[] }, unknown>
+  >;
+}
+```
+
+### List All Projects
+
+```typescript
+for await (const project of dremio.projects.list().data()) {
+  console.log(project.id, project.name, project.state);
+}
+```
+
+**Options:**
+
+- `signal`: Optional AbortSignal for request cancellation
+
+### Retrieve a Specific Project
+
+```typescript
+const project = await dremio.projects
+  .retrieve("PROJECT_ID")
+  .then((result) => result.unwrap());
+```
+
+**Options:**
+
+- `signal`: Optional AbortSignal for request cancellation
+
+### Observe Project Changes
+
+```typescript
+import { Subscription } from "rxjs";
+
+const subscription: Subscription = dremio.projects
+  .observe("PROJECT_ID")
+  .subscribe({
+    next: (project) => {
+      console.log("Project state:", project.state);
+    },
+    error: (error) => {
+      console.error("Error observing project:", error);
+    },
+  });
+
+// Unsubscribe when done
+subscription.unsubscribe();
+```
+
+### Activate a Project
+
+```typescript
+await dremio.projects.activate("PROJECT_ID");
+```
+
+### Delete a Project
+
+```typescript
+await dremio.projects.delete("PROJECT_ID");
+```
+
+### Update a Project
+
+```typescript
+const project = await dremio.projects
+  .retrieve("PROJECT_ID")
+  .then((result) => result.unwrap());
+
+const updatedProject = await project
+  .update({
+    name: "New Project Name",
+  })
+  .then((result) => result.unwrap());
+```
+
+### Project Grants Management
+
+```typescript
+const project = await dremio.projects
+  .retrieve("PROJECT_ID")
+  .then((result) => result.unwrap());
+
+// Retrieve grants
+const { grants, availablePrivileges } = await project
+  .grants()
+  .then((result) => result.unwrap());
+
+grants.forEach((grant) => {
+  console.log(grant.grantee, grant.privileges);
+});
+```
+
+## Roles
+
+### `Role` Interface
+
+```typescript
+interface RoleReference {
+  readonly id: string;
+  readonly name: string;
+  readonly type: "INTERNAL" | "EXTERNAL" | "SYSTEM";
+  delete(): Promise<Result<void, unknown>>;
+}
+
+interface Role {
+  readonly roleReference: RoleReference;
+  readonly description: string | null;
+  readonly memberCount: number;
+  readonly roles: RoleReference[];
+  update(properties: {
+    name?: string;
+    roles?: RoleReference[];
+    description?: string;
+  }): Promise<Result<Role, unknown>>;
+}
+```
+
+### List Roles
+
+```typescript
+// List all roles
+for await (const role of dremio.roles("PROJECT_ID").list().data()) {
+  console.log(role.roleReference.id, role.roleReference.name);
+}
+
+// Retrieve a role
+const role = await dremio
+  .roles("PROJECT_ID")
+  .retrieve("ROLE_ID")
+  .then((result) => result.unwrap());
+```
+
+For detailed role management methods, refer to the Enterprise documentation.
+
+## Scripts
+
+### `Script` Interface
+
+```typescript
+import { Query } from "@dremio/js-sdk/common";
+import { Temporal } from "temporal-polyfill";
+
+interface Script {
+  readonly id: string;
+  readonly name: string;
+  readonly query: Query;
+  readonly createdAt: Temporal.Instant;
+  readonly createdBy: string;
+  readonly modifiedAt: Temporal.Instant;
+  readonly modifiedBy: string;
+  delete(): Promise<Result<void, unknown>>;
+  save(properties: {
+    name?: string;
+    query?: Query;
+  }): Promise<Result<Script, unknown>>;
+}
+```
+
+### List Scripts
+
+```typescript
+for await (const script of dremio.scripts("PROJECT_ID").list().data()) {
+  console.log(script.id, script.name);
+}
+```
+
+**Options:**
+
+- `signal`: Optional AbortSignal for request cancellation
+
+### Retrieve a Script
+
+```typescript
+const script = await dremio
+  .scripts("PROJECT_ID")
+  .retrieve("SCRIPT_ID")
+  .then((result) => result.unwrap());
+```
+
+**Options:**
+
+- `signal`: Optional AbortSignal for request cancellation
+
+### Create a Script
+
+```typescript
+import { Query } from "@dremio/js-sdk/common";
+
+const script = await dremio
+  .scripts("PROJECT_ID")
+  .store({
+    name: "My Query",
+    query: new Query("SELECT * FROM my_table", ["@username"]),
+  })
+  .then((result) => result.unwrap());
+```
+
+### Update a Script
+
+```typescript
+const script = await dremio
+  .scripts("PROJECT_ID")
+  .retrieve("SCRIPT_ID")
+  .then((result) => result.unwrap());
+
+const updatedScript = await script
+  .save({
+    name: "Updated Query Name",
+    query: new Query("SELECT * FROM my_table WHERE id > 100", ["@username"]),
+  })
+  .then((result) => result.unwrap());
+```
+
+### Delete a Script
+
+```typescript
+const script = await dremio
+  .scripts("PROJECT_ID")
+  .retrieve("SCRIPT_ID")
+  .then((result) => result.unwrap());
+
+await script.delete();
+```
+
+## Error Handling
+
+The SDK uses the [`ts-results-es`](https://github.com/lune-climate/ts-results-es) library for error handling. All methods that can fail return a `Result` or `AsyncResult` type:
+
+```typescript
+import { Result } from "ts-results-es";
+
+const result = await dremio.projects.retrieve("PROJECT_ID");
+
+if (result.isOk()) {
+  const project = result.value;
+  console.log(project.name);
+} else {
+  const error = result.error;
+  console.error("Error:", error);
+}
+
+// Or use unwrap() and catch errors
+try {
+  const project = await dremio.projects
+    .retrieve("PROJECT_ID")
+    .then((result) => result.unwrap());
+} catch (error) {
+  console.error("Error:", error);
+}
+```
+
+## Request Cancellation
+
+Methods that do not change state in Dremio support cancellation via AbortSignal:
+
+```typescript
+const abortController = new AbortController();
+
+// Pass the signal to the request
+const project = await dremio.projects
+  .retrieve("PROJECT_ID", {
+    signal: abortController.signal,
+  })
+  .then((result) => result.unwrap());
+
+// Cancel the request if needed
+abortController.abort();
+```
+
+## Observable Pattern
+
+Some methods return RxJS Observables for real-time updates:
+
+```typescript
+import { Subscription } from "rxjs";
+
+const subscription = dremio.projects.observe("PROJECT_ID").subscribe({
+  next: (project) => console.log("Project updated:", project.state),
+  error: (error) => console.error("Error:", error),
+  complete: () => console.log("Observation complete"),
+});
+
+// Unsubscribe when done
+subscription.unsubscribe();
+```
+
+## Advanced Configuration
+
+### Custom Logger
+
+You can provide a custom logger implementation or use a library like [pino](https://getpino.io):
+
+```typescript
+import pino from "pino";
+
+const logger = pino();
+
+const dremio = new Dremio({
+  origin: "https://api.dremio.cloud",
+  credentials: fromAccessToken("your-token"),
+  logger,
+});
+```
+
+### Custom Fetch Implementation
+
+```typescript
+const dremio = new Dremio({
+  origin: "https://api.dremio.cloud",
+  credentials: fromAccessToken("your-token"),
+  fetch: customFetchImplementation,
+});
+```
+
+## API Reference
+
+For complete HTTP API documentation (which this SDK wraps), see the [Dremio Cloud API Reference](https://docs.dremio.com/dremio-cloud/api/).
+
+## License
+
+Apache-2.0

package/dist-iife/cloud.js

@@ -1430,7 +1430,7 @@ var DremioCloud = (() => {
   // dist/cloud/Dremio.js
   var import_moize2 = __toESM(require_moize(), 1);
 
-  // node_modules/.pnpm/ts-results-es@5.0.1/node_modules/ts-results-es/dist/esm/utils.js
+  // node_modules/.pnpm/ts-results-es@6.0.0/node_modules/ts-results-es/dist/esm/utils.js
   function toString(val) {
     var value = String(val);
     if (value === "[object Object]") {
@@ -1442,7 +1442,7 @@ var DremioCloud = (() => {
     return value;
   }
 
-  // node_modules/.pnpm/ts-results-es@5.0.1/node_modules/ts-results-es/dist/esm/option.js
+  // node_modules/.pnpm/ts-results-es@6.0.0/node_modules/ts-results-es/dist/esm/option.js
   var NoneImpl = (
     /** @class */
     (function() {
@@ -1611,7 +1611,7 @@ var DremioCloud = (() => {
     Option2.isOption = isOption;
   })(Option || (Option = {}));
 
-  // node_modules/.pnpm/ts-results-es@5.0.1/node_modules/ts-results-es/dist/esm/result.js
+  // node_modules/.pnpm/ts-results-es@6.0.0/node_modules/ts-results-es/dist/esm/result.js
   var __spreadArray = function(to2, from2, pack) {
     if (pack || arguments.length === 2) for (var i2 = 0, l2 = from2.length, ar2; i2 < l2; i2++) {
       if (ar2 || !(i2 in from2)) {
@@ -1849,7 +1849,7 @@ var DremioCloud = (() => {
     Result2.isResult = isResult;
   })(Result || (Result = {}));
 
-  // node_modules/.pnpm/ts-results-es@5.0.1/node_modules/ts-results-es/dist/esm/asyncresult.js
+  // node_modules/.pnpm/ts-results-es@6.0.0/node_modules/ts-results-es/dist/esm/asyncresult.js
   var __awaiter = function(thisArg, _arguments, P2, generator) {
     function adopt(value) {
       return value instanceof P2 ? value : new P2(function(resolve) {
@@ -2032,6 +2032,9 @@ var DremioCloud = (() => {
           return result.toOption();
         }));
       };
+      AsyncResult2.prototype.then = function(onfulfilled, onrejected) {
+        return this.promise.then(onfulfilled, onrejected);
+      };
       AsyncResult2.prototype.thenInternal = function(mapper) {
         return new AsyncResult2(this.promise.then(mapper));
       };
@@ -2039,7 +2042,7 @@ var DremioCloud = (() => {
     })()
   );
 
-  // node_modules/.pnpm/ts-results-es@5.0.1/node_modules/ts-results-es/dist/esm/asyncoption.js
+  // node_modules/.pnpm/ts-results-es@6.0.0/node_modules/ts-results-es/dist/esm/asyncoption.js
   var __awaiter2 = function(thisArg, _arguments, P2, generator) {
     function adopt(value) {
       return value instanceof P2 ? value : new P2(function(resolve) {
@@ -2202,6 +2205,9 @@ var DremioCloud = (() => {
           return option.toResult(error);
         }));
       };
+      AsyncOption2.prototype.then = function(onfulfilled, onrejected) {
+        return this.promise.then(onfulfilled, onrejected);
+      };
       AsyncOption2.prototype.thenInternal = function(mapper) {
         return new AsyncOption2(this.promise.then(mapper));
       };

package/dist-iife/community.js

@@ -3486,7 +3486,7 @@ var DremioCommunity = (() => {
     }
   };
 
-  // node_modules/.pnpm/ts-results-es@5.0.1/node_modules/ts-results-es/dist/esm/utils.js
+  // node_modules/.pnpm/ts-results-es@6.0.0/node_modules/ts-results-es/dist/esm/utils.js
   function toString(val) {
     var value = String(val);
     if (value === "[object Object]") {
@@ -3498,7 +3498,7 @@ var DremioCommunity = (() => {
     return value;
   }
 
-  // node_modules/.pnpm/ts-results-es@5.0.1/node_modules/ts-results-es/dist/esm/option.js
+  // node_modules/.pnpm/ts-results-es@6.0.0/node_modules/ts-results-es/dist/esm/option.js
   var NoneImpl = (
     /** @class */
     (function() {
@@ -3667,7 +3667,7 @@ var DremioCommunity = (() => {
     Option2.isOption = isOption;
   })(Option || (Option = {}));
 
-  // node_modules/.pnpm/ts-results-es@5.0.1/node_modules/ts-results-es/dist/esm/result.js
+  // node_modules/.pnpm/ts-results-es@6.0.0/node_modules/ts-results-es/dist/esm/result.js
   var __spreadArray = function(to2, from2, pack) {
     if (pack || arguments.length === 2) for (var i2 = 0, l2 = from2.length, ar2; i2 < l2; i2++) {
       if (ar2 || !(i2 in from2)) {
@@ -3905,7 +3905,7 @@ var DremioCommunity = (() => {
     Result2.isResult = isResult;
   })(Result || (Result = {}));
 
-  // node_modules/.pnpm/ts-results-es@5.0.1/node_modules/ts-results-es/dist/esm/asyncresult.js
+  // node_modules/.pnpm/ts-results-es@6.0.0/node_modules/ts-results-es/dist/esm/asyncresult.js
   var __awaiter = function(thisArg, _arguments, P2, generator) {
     function adopt(value) {
       return value instanceof P2 ? value : new P2(function(resolve) {
@@ -4088,6 +4088,9 @@ var DremioCommunity = (() => {
           return result.toOption();
         }));
       };
+      AsyncResult2.prototype.then = function(onfulfilled, onrejected) {
+        return this.promise.then(onfulfilled, onrejected);
+      };
       AsyncResult2.prototype.thenInternal = function(mapper) {
         return new AsyncResult2(this.promise.then(mapper));
       };
@@ -4095,7 +4098,7 @@ var DremioCommunity = (() => {
     })()
   );
 
-  // node_modules/.pnpm/ts-results-es@5.0.1/node_modules/ts-results-es/dist/esm/asyncoption.js
+  // node_modules/.pnpm/ts-results-es@6.0.0/node_modules/ts-results-es/dist/esm/asyncoption.js
   var __awaiter2 = function(thisArg, _arguments, P2, generator) {
     function adopt(value) {
       return value instanceof P2 ? value : new P2(function(resolve) {
@@ -4258,6 +4261,9 @@ var DremioCommunity = (() => {
           return option.toResult(error);
         }));
       };
+      AsyncOption2.prototype.then = function(onfulfilled, onrejected) {
+        return this.promise.then(onfulfilled, onrejected);
+      };
       AsyncOption2.prototype.thenInternal = function(mapper) {
         return new AsyncOption2(this.promise.then(mapper));
       };

package/dist-iife/enterprise.js

@@ -3540,7 +3540,7 @@ var DremioEnterprise = (() => {
   var EnterpriseFileCatalogReference = class extends FileCatalogReference {
   };
 
-  // node_modules/.pnpm/ts-results-es@5.0.1/node_modules/ts-results-es/dist/esm/utils.js
+  // node_modules/.pnpm/ts-results-es@6.0.0/node_modules/ts-results-es/dist/esm/utils.js
   function toString(val) {
     var value = String(val);
     if (value === "[object Object]") {
@@ -3552,7 +3552,7 @@ var DremioEnterprise = (() => {
     return value;
   }
 
-  // node_modules/.pnpm/ts-results-es@5.0.1/node_modules/ts-results-es/dist/esm/option.js
+  // node_modules/.pnpm/ts-results-es@6.0.0/node_modules/ts-results-es/dist/esm/option.js
   var NoneImpl = (
     /** @class */
     (function() {
@@ -3721,7 +3721,7 @@ var DremioEnterprise = (() => {
     Option2.isOption = isOption;
   })(Option || (Option = {}));
 
-  // node_modules/.pnpm/ts-results-es@5.0.1/node_modules/ts-results-es/dist/esm/result.js
+  // node_modules/.pnpm/ts-results-es@6.0.0/node_modules/ts-results-es/dist/esm/result.js
   var __spreadArray = function(to2, from2, pack) {
     if (pack || arguments.length === 2) for (var i2 = 0, l2 = from2.length, ar2; i2 < l2; i2++) {
       if (ar2 || !(i2 in from2)) {
@@ -3959,7 +3959,7 @@ var DremioEnterprise = (() => {
     Result2.isResult = isResult;
   })(Result || (Result = {}));
 
-  // node_modules/.pnpm/ts-results-es@5.0.1/node_modules/ts-results-es/dist/esm/asyncresult.js
+  // node_modules/.pnpm/ts-results-es@6.0.0/node_modules/ts-results-es/dist/esm/asyncresult.js
   var __awaiter = function(thisArg, _arguments, P2, generator) {
     function adopt(value) {
       return value instanceof P2 ? value : new P2(function(resolve) {
@@ -4142,6 +4142,9 @@ var DremioEnterprise = (() => {
           return result.toOption();
         }));
       };
+      AsyncResult2.prototype.then = function(onfulfilled, onrejected) {
+        return this.promise.then(onfulfilled, onrejected);
+      };
       AsyncResult2.prototype.thenInternal = function(mapper) {
         return new AsyncResult2(this.promise.then(mapper));
       };
@@ -4149,7 +4152,7 @@ var DremioEnterprise = (() => {
     })()
   );
 
-  // node_modules/.pnpm/ts-results-es@5.0.1/node_modules/ts-results-es/dist/esm/asyncoption.js
+  // node_modules/.pnpm/ts-results-es@6.0.0/node_modules/ts-results-es/dist/esm/asyncoption.js
   var __awaiter2 = function(thisArg, _arguments, P2, generator) {
     function adopt(value) {
       return value instanceof P2 ? value : new P2(function(resolve) {
@@ -4312,6 +4315,9 @@ var DremioEnterprise = (() => {
           return option.toResult(error);
         }));
       };
+      AsyncOption2.prototype.then = function(onfulfilled, onrejected) {
+        return this.promise.then(onfulfilled, onrejected);
+      };
       AsyncOption2.prototype.thenInternal = function(mapper) {
         return new AsyncOption2(this.promise.then(mapper));
       };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dremio/js-sdk",
-  "version": "0.40.1",
+  "version": "0.42.0",
   "description": "JavaScript library for the Dremio API",
   "keywords": [
     "dremio",
@@ -54,7 +54,7 @@
     "rxjs": "^7",
     "semver": "^7",
     "temporal-polyfill": "^0.3.0",
-    "ts-results-es": "^5.0.1",
+    "ts-results-es": "^6.0.0",
     "zod": "^4.1.0"
   },
   "devDependencies": {