update

Author: parthban-db

package-lock.json

@@ -0,0 +1,50 @@
+{
+  "name": "@databricks/sdk-databricks",
+  "version": "0.1.0",
+  "description": "Databricks SDK core infrastructure for JavaScript/TypeScript",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "lint": "eslint src tests --ext .ts",
+    "lint:fix": "eslint src tests --ext .ts --fix",
+    "format": "prettier --write \"src/**/*.ts\" \"tests/**/*.ts\"",
+    "format:check": "prettier --check \"src/**/*.ts\" \"tests/**/*.ts\"",
+    "test": "vitest run",
+    "test:node": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "@databricks/sdk-auth": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "@typescript-eslint/eslint-plugin": "^7.0.0",
+    "@typescript-eslint/parser": "^7.0.0",
+    "@vitest/coverage-v8": "^2.1.0",
+    "eslint": "^8.57.0",
+    "eslint-config-prettier": "^9.1.0",
+    "prettier": "^3.2.0",
+    "typescript": "^5.3.0",
+    "vitest": "^2.1.0"
+  },
+  "author": "Databricks",
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

packages/databricks/package.json

@@ -0,0 +1,113 @@
+/**
+ * Utilities to make API calls against the Databricks API with retry, timeout,
+ * and rate limiting support.
+ */
+
+import type {Option, Options} from './options';
+import type {Retrier} from './retrier';
+
+/**
+ * A function representing a single API call attempt. Throw an error to
+ * indicate failure; return normally to indicate success.
+ */
+export type Call = (signal: AbortSignal) => Promise<void>;
+
+/**
+ * Makes an API call using the given options for retry, timeout, and rate
+ * limiting behavior.
+ */
+export async function execute(call: Call, ...opts: Option[]): Promise<void> {
+  const options: Options = {};
+  for (const opt of opts) {
+    opt.apply(options);
+  }
+
+  await executeImpl(call, options, sleepMs);
+}
+
+/**
+ * Sleeps for the given duration in milliseconds. Rejects with an
+ * AbortError if the signal is aborted before the sleep completes.
+ */
+function sleepMs(ms: number, signal: AbortSignal): Promise<void> {
+  return new Promise<void>((resolve, reject) => {
+    if (signal.aborted) {
+      reject(signal.reason as Error);
+      return;
+    }
+
+    const timer = setTimeout(() => {
+      signal.removeEventListener('abort', onAbort);
+      resolve();
+    }, ms);
+
+    function onAbort(): void {
+      clearTimeout(timer);
+      reject(signal.reason as Error);
+    }
+
+    signal.addEventListener('abort', onAbort, {once: true});
+  });
+}
+
+// Convenience type for readability and testability.
+type Sleeper = (ms: number, signal: AbortSignal) => Promise<void>;
+
+/**
+ * The actual implementation of execute, separated for testability.
+ */
+async function executeImpl(
+  apiCall: Call,
+  opts: Options,
+  sleep: Sleeper
+): Promise<void> {
+  // Set up abort controller with optional timeout.
+  const controller = new AbortController();
+  const {signal} = controller;
+
+  let timeoutId: ReturnType<typeof setTimeout> | undefined;
+  if (opts.timeoutMs !== undefined && opts.timeoutMs > 0) {
+    timeoutId = setTimeout(() => {
+      controller.abort(
+        new DOMException('The operation timed out.', 'TimeoutError')
+      );
+    }, opts.timeoutMs);
+  }
+
+  try {
+    // Lazily instantiated retrier.
+    let retrier: Retrier | undefined;
+
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition, no-constant-condition
+    while (true) {
+      if (opts.rateLimiter !== undefined) {
+        await opts.rateLimiter.wait(signal);
+      }
+
+      try {
+        await apiCall(signal);
+        return; // Success — nothing to retry.
+      } catch (err: unknown) {
+        if (retrier === undefined) {
+          if (opts.retrier !== undefined) {
+            retrier = opts.retrier();
+          }
+          if (retrier === undefined) {
+            throw err; // No retrier — no retry.
+          }
+        }
+
+        const decision = retrier.isRetriable(err);
+        if (!decision.retriable) {
+          throw err; // Not retriable.
+        }
+
+        await sleep(decision.delayMs, signal);
+      }
+    }
+  } finally {
+    if (timeoutId !== undefined) {
+      clearTimeout(timeoutId);
+    }
+  }
+}

packages/databricks/src/api/api.ts

@@ -0,0 +1,19 @@
+// API call execution.
+export type {Call} from './api';
+export {execute} from './api';
+
+// Options for API calls.
+export type {Option, Options} from './options';
+export {
+  withRetrier,
+  withDisableRetry,
+  withTimeout,
+  withLimiter,
+} from './options';
+
+// Rate limiting.
+export type {Limiter} from './limiter';
+
+// Retry logic.
+export type {RetryDecision, Retrier, BackoffPolicyOptions} from './retrier';
+export {retryOnCodes, retryOn, BackoffPolicy} from './retrier';

packages/databricks/src/api/index.ts

@@ -0,0 +1,15 @@
+/**
+ * Rate limiting interface for API calls.
+ */
+
+/**
+ * A limiter controls the rate of API calls. Implementations must be safe
+ * to call concurrently from multiple async contexts.
+ */
+export interface Limiter {
+  /**
+   * Waits until the call is allowed to proceed. Rejects if the signal is
+   * aborted before the wait completes.
+   */
+  wait(signal?: AbortSignal): Promise<void>;
+}

packages/databricks/src/api/limiter.ts

@@ -0,0 +1,86 @@
+/**
+ * Options to control the behavior of an API call.
+ */
+
+import type {Limiter} from './limiter';
+import type {Retrier} from './retrier';
+
+/**
+ * An option that configures the behavior of an API call via Execute.
+ */
+export interface Option {
+  /**
+   * Applies this option to the given options object.
+   * Throws if the option is invalid.
+   */
+  apply(opts: Options): void;
+}
+
+/**
+ * Collected options that control the behavior of an API call.
+ */
+export interface Options {
+  /**
+   * Provides a new Retrier for each Execute call. The function must be safe
+   * to call from multiple async contexts. The retrier must be fresh within
+   * the context of an Execute call.
+   */
+  retrier?: () => Retrier;
+
+  /** Rate limiter applied before each API call attempt. */
+  rateLimiter?: Limiter;
+
+  /** Timeout in milliseconds for the entire Execute invocation. */
+  timeoutMs?: number;
+}
+
+/**
+ * Configures a retrier provider for the API call. If no retrier is provided,
+ * the call is not retried on failure.
+ *
+ * The provider function must be safe to call from multiple async contexts.
+ */
+export function withRetrier(provider: () => Retrier): Option {
+  return {
+    apply(opts: Options): void {
+      opts.retrier = provider;
+    },
+  };
+}
+
+/**
+ * Convenience option to disable retries.
+ */
+export function withDisableRetry(): Option {
+  return {
+    apply(opts: Options): void {
+      opts.retrier = undefined;
+    },
+  };
+}
+
+/**
+ * Sets the timeout duration for the entire Execute invocation.
+ *
+ * If the underlying signal already has a deadline, the effective timeout is
+ * the minimum of both.
+ */
+export function withTimeout(ms: number): Option {
+  return {
+    apply(opts: Options): void {
+      opts.timeoutMs = ms;
+    },
+  };
+}
+
+/**
+ * Configures a rate limiter for the API call. The limiter is invoked before
+ * each call attempt. If no limiter is provided, the call is not rate limited.
+ */
+export function withLimiter(limiter: Limiter): Option {
+  return {
+    apply(opts: Options): void {
+      opts.rateLimiter = limiter;
+    },
+  };
+}