@databricks/sdk-core 0.1.0-dev.4 → 0.1.0-dev.6

package/src/clientinfo/clientinfo.ts

@@ -1,129 +0,0 @@
-/**
- * Collects information about the client and its environment into an
- * immutable {@link ClientInfo} value.
- *
- * {@link ClientInfo.with} derives a new value with additional key/value
- * segments; it never mutates the original.
- *
- * @module
- */
-
-export type ClientInfoErrorCode =
-  | 'INVALID_KEY'
-  | 'INVALID_VALUE'
-  | 'INVALID_VERSION';
-
-export class ClientInfoError extends Error {
-  readonly code: ClientInfoErrorCode;
-
-  constructor(code: ClientInfoErrorCode, message: string) {
-    super(message);
-    this.name = 'ClientInfoError';
-    this.code = code;
-  }
-}
-
-interface Segment {
-  readonly key: string;
-  readonly value: string;
-}
-
-const SEMVER_CORE = String.raw`(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)`;
-
-const SEMVER_PRERELEASE = String.raw`(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?`;
-
-const SEMVER_BUILDMETADATA = String.raw`(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?`;
-
-const REGEXP_SEMVER = new RegExp(
-  '^' + SEMVER_CORE + SEMVER_PRERELEASE + SEMVER_BUILDMETADATA + '$'
-);
-const REGEXP_VALID_SEGMENT = /^[-0-9A-Za-z_.+]+$/;
-const REGEXP_INVALID_SEGMENT_CHAR = /[^-0-9A-Za-z_.+]/g;
-
-export function isSemVer(s: string): boolean {
-  return REGEXP_SEMVER.test(s);
-}
-
-export function isValidSegment(s: string): boolean {
-  return REGEXP_VALID_SEGMENT.test(s);
-}
-
-/**
- * Replaces characters that are not valid in segment values with
- * hyphens. Used for environment-sourced values (runtime version,
- * upstream) that we do not control and cannot reject.
- */
-export function sanitize(s: string): string {
-  return s.replace(REGEXP_INVALID_SEGMENT_CHAR, '-');
-}
-
-/**
- * ClientInfo is an immutable, ordered list of key/value segments. Use
- * {@link ClientInfo.with} to derive new values with additional segments.
- */
-export class ClientInfo {
-  static readonly EMPTY = new ClientInfo();
-
-  readonly segments: readonly Segment[];
-
-  private constructor(
-    segments: readonly {readonly key: string; readonly value: string}[] = []
-  ) {
-    this.segments = [...segments];
-  }
-
-  /**
-   * Returns a new {@link ClientInfo} with the given items appended. Accepts
-   * either individual key/value pairs or another {@link ClientInfo} whose
-   * segments are merged in order. The original is not modified; mixing the
-   * two forms in a single call is supported.
-   *
-   * Keys and values on pair arguments must contain only alphanumeric
-   * characters plus `_`, `.`, `+`, or `-`. Exact key+value duplicates are
-   * silently ignored. On error, an exception is thrown (all-or-nothing).
-   *
-   * @example
-   * ```ts
-   * base.with({key: 'partner', value: 'acme'});
-   * base.with(pkgClientInfo);
-   * base.with(pkgClientInfo, {key: 'sdk-feature', value: 'pagination'});
-   * ```
-   */
-  with(...items: (ClientInfo | Segment)[]): ClientInfo {
-    if (items.length === 0) {
-      return this;
-    }
-
-    const newSegments: Segment[] = [...this.segments];
-
-    for (const item of items) {
-      const pairs = item instanceof ClientInfo ? item.segments : [item];
-      for (const {key, value} of pairs) {
-        if (!isValidSegment(key)) {
-          throw new ClientInfoError('INVALID_KEY', `Invalid key: ${key}.`);
-        }
-        if (!isValidSegment(value)) {
-          throw new ClientInfoError(
-            'INVALID_VALUE',
-            `Invalid value for "${key}": ${value}.`
-          );
-        }
-        if (newSegments.some(s => s.key === key && s.value === value)) {
-          continue;
-        }
-        newSegments.push({key, value});
-      }
-    }
-
-    return new ClientInfo(newSegments);
-  }
-
-  /**
-   * Returns a string representation of the client info suitable for
-   * inclusion in HTTP headers. Key/value pairs are formatted as
-   * "key/value" and joined by spaces in the order they were inserted.
-   */
-  toString(): string {
-    return this.segments.map(s => `${s.key}/${s.value}`).join(' ');
-  }
-}

package/src/clientinfo/default.browser.ts

@@ -1,24 +0,0 @@
-/**
- * Browser-compatible {@link createDefault}. Contains no Node.js-specific
- * APIs (no `process.version`, `process.platform`, or `process.env`); only
- * the segments registered via {@link setProduct}, {@link setPartner}, and
- * {@link addToDefault} are returned, plus the core SDK identity.
- *
- * @module
- */
-
-import {ClientInfo} from './clientinfo';
-import {MODULE_NAME, VERSION, getBase} from './base';
-
-/**
- * Returns a {@link ClientInfo} populated with SDK metadata and segments
- * registered via {@link addToDefault}. Unlike the Node.js variant, this
- * does not auto-detect runtime, OS, CI/CD, or agent because those signals
- * are not available in a browser.
- */
-export function createDefault(): ClientInfo {
-  return ClientInfo.EMPTY.with(
-    {key: MODULE_NAME, value: VERSION},
-    ...getBase().segments
-  );
-}

package/src/clientinfo/default.ts

@@ -1,128 +0,0 @@
-import {ClientInfo, sanitize} from './clientinfo';
-import {MODULE_NAME, VERSION, getBase} from './base';
-import {agentProvider} from './agent';
-
-interface EnvCheck {
-  readonly name: string;
-  readonly expectedValue: string;
-}
-
-interface CicdDef {
-  readonly name: string;
-  readonly envVars: readonly EnvCheck[];
-}
-
-const CICD_PROVIDERS: readonly CicdDef[] = [
-  {
-    name: 'github',
-    envVars: [{name: 'GITHUB_ACTIONS', expectedValue: 'true'}],
-  },
-  {
-    name: 'gitlab',
-    envVars: [{name: 'GITLAB_CI', expectedValue: 'true'}],
-  },
-  {name: 'jenkins', envVars: [{name: 'JENKINS_URL', expectedValue: ''}]},
-  {
-    name: 'azure-devops',
-    envVars: [{name: 'TF_BUILD', expectedValue: 'True'}],
-  },
-  {
-    name: 'circle',
-    envVars: [{name: 'CIRCLECI', expectedValue: 'true'}],
-  },
-  {name: 'travis', envVars: [{name: 'TRAVIS', expectedValue: 'true'}]},
-  {
-    name: 'bitbucket',
-    envVars: [{name: 'BITBUCKET_BUILD_NUMBER', expectedValue: ''}],
-  },
-  {
-    name: 'google-cloud-build',
-    envVars: [
-      {name: 'PROJECT_ID', expectedValue: ''},
-      {name: 'BUILD_ID', expectedValue: ''},
-      {name: 'PROJECT_NUMBER', expectedValue: ''},
-      {name: 'LOCATION', expectedValue: ''},
-    ],
-  },
-  {
-    name: 'aws-code-build',
-    envVars: [{name: 'CODEBUILD_BUILD_ARN', expectedValue: ''}],
-  },
-  {name: 'tf-cloud', envVars: [{name: 'TFC_RUN_ID', expectedValue: ''}]},
-];
-
-function detectCicd(): string {
-  for (const p of CICD_PROVIDERS) {
-    const allMatch = p.envVars.every(ev => {
-      const v = process.env[ev.name];
-      return (
-        v !== undefined && (ev.expectedValue === '' || v === ev.expectedValue)
-      );
-    });
-    if (allMatch) {
-      return p.name;
-    }
-  }
-  return '';
-}
-
-/**
- * Converts a Node.js version string (e.g., "v22.0.0") into a bare
- * semver string (e.g., "22.0.0").
- */
-export function normalizeNodeVersion(raw: string): string {
-  if (!raw.startsWith('v')) {
-    return '0.0.0-dev';
-  }
-  return raw.slice(1);
-}
-
-// Computed once at module load because process.version never changes
-// during a process lifetime.
-export const CACHED_NODE_VERSION = normalizeNodeVersion(process.version);
-
-/**
- * Returns a {@link ClientInfo} populated with SDK metadata, runtime
- * information, segments registered via {@link addToDefault}, and
- * automatically detected environment properties.
- */
-export function createDefault(): ClientInfo {
-  const pairs: {key: string; value: string}[] = [
-    {key: MODULE_NAME, value: VERSION},
-    {key: 'node', value: CACHED_NODE_VERSION},
-    {key: 'os', value: process.platform},
-    ...getBase().segments,
-  ];
-
-  // DATABRICKS_SDK_UPSTREAM and DATABRICKS_SDK_UPSTREAM_VERSION are set
-  // by tools built on top of this SDK (e.g. Terraform provider, Pulumi)
-  // to identify themselves as the upstream product. Both must be present
-  // for the upstream segment to be included.
-  const upstream = process.env.DATABRICKS_SDK_UPSTREAM;
-  if (upstream !== undefined) {
-    const upstreamVersion = process.env.DATABRICKS_SDK_UPSTREAM_VERSION;
-    if (upstreamVersion !== undefined) {
-      pairs.push(
-        {key: 'upstream', value: sanitize(upstream)},
-        {key: 'upstream-version', value: sanitize(upstreamVersion)}
-      );
-    }
-  }
-
-  const cicd = detectCicd();
-  if (cicd !== '') {
-    pairs.push({key: 'cicd', value: cicd});
-  }
-
-  const runtime = process.env.DATABRICKS_RUNTIME_VERSION;
-  if (runtime !== undefined && runtime !== '') {
-    pairs.push({key: 'runtime', value: sanitize(runtime)});
-  }
-
-  const agent = agentProvider();
-  if (agent !== '') {
-    pairs.push({key: 'agent', value: agent});
-  }
-
-  return ClientInfo.EMPTY.with(...pairs);
-}

package/src/clientinfo/index.browser.ts

@@ -1,4 +0,0 @@
-export type {ClientInfoErrorCode} from './clientinfo';
-export {ClientInfo, ClientInfoError} from './clientinfo';
-export {addToDefault, setPartner, setProduct} from './base';
-export {createDefault} from './default.browser';

package/src/clientinfo/index.ts

@@ -1,4 +0,0 @@
-export type {ClientInfoErrorCode} from './clientinfo';
-export {ClientInfo, ClientInfoError} from './clientinfo';
-export {addToDefault, setPartner, setProduct} from './base';
-export {createDefault} from './default';

package/src/http/http.ts

@@ -1,75 +0,0 @@
-/**
- * HTTP transport primitives. Defines the {@link HttpClient} interface and a
- * {@link newFetchHttpClient} implementation backed by the Fetch API.
- *
- * @module
- */
-
-/** HttpRequest represents an outgoing HTTP request. */
-export interface HttpRequest {
-  /** The URL to send the request to. */
-  url: string;
-
-  /** The HTTP method (GET, POST, etc.). */
-  method: string;
-
-  /** The request headers. */
-  headers: Headers;
-
-  /** The request body. */
-  body?: string | ArrayBuffer | Uint8Array | ReadableStream<Uint8Array> | null;
-
-  /** An optional signal to abort the request. */
-  signal?: AbortSignal;
-}
-
-/** HttpResponse represents the response from an HTTP request. */
-export interface HttpResponse {
-  /** The HTTP status code. */
-  statusCode: number;
-
-  /** The response headers. */
-  headers: Headers;
-
-  /** The raw response body stream. */
-  body: ReadableStream<Uint8Array> | null;
-}
-
-/**
- * HttpClient sends HTTP requests and returns responses.
- */
-export interface HttpClient {
-  /** Sends an HTTP request and returns the response. */
-  send(request: HttpRequest): Promise<HttpResponse>;
-}
-
-/**
- * Creates a new HttpClient that uses the Fetch API as its transport.
- */
-export function newFetchHttpClient(): HttpClient {
-  return {
-    async send(request: HttpRequest): Promise<HttpResponse> {
-      const init: RequestInit = {
-        method: request.method,
-        headers: request.headers,
-      };
-      if (request.body !== undefined) {
-        init.body = request.body;
-        // The Fetch spec requires duplex: 'half' for streaming request bodies.
-        // See https://fetch.spec.whatwg.org/#dom-requestinit-duplex.
-        if (request.body instanceof ReadableStream) {
-          init.duplex = 'half';
-        }
-      }
-      if (request.signal !== undefined) {
-        init.signal = request.signal;
-      }
-      const response = await fetch(request.url, init);
-      return {
-        statusCode: response.status,
-        headers: response.headers,
-        body: response.body,
-      };
-    },
-  };
-}

package/src/http/index.ts

@@ -1,8 +0,0 @@
-/**
- * HTTP transport primitives.
- *
- * @packageDocumentation
- */
-
-export {newFetchHttpClient} from './http';
-export type {HttpClient, HttpRequest, HttpResponse} from './http';

package/src/index.ts

@@ -1,5 +0,0 @@
-/**
- * Databricks core library.
- *
- * @packageDocumentation
- */

package/src/logger/index.ts

@@ -1,8 +0,0 @@
-/**
- * Logger interface and built-in implementations.
- *
- * @packageDocumentation
- */
-
-export type {Level, Logger} from './logger';
-export {NoOpLogger, LogLevel} from './logger';

package/src/logger/logger.ts

@@ -1,99 +0,0 @@
-/** Logger interface and built-in implementations. */
-
-/** Supported log levels in order of increasing severity. */
-export type Level = 'debug' | 'info' | 'warn' | 'error' | 'off';
-
-/**
- * A logger that receives messages at different severity levels.
- *
- * The method signatures are intentionally compatible with the global
- * {@link Console} object so that `console` can be used as a Logger when level
- * filtering is not needed.
- */
-export interface Logger {
-  /** Logs a debug-level message. */
-  debug(message: string, ...args: unknown[]): void;
-
-  /** Logs an info-level message. */
-  info(message: string, ...args: unknown[]): void;
-
-  /** Logs a warn-level message. */
-  warn(message: string, ...args: unknown[]): void;
-
-  /** Logs an error-level message. */
-  error(message: string, ...args: unknown[]): void;
-}
-
-/** A logger that silently discards all messages. */
-export class NoOpLogger implements Logger {
-  debug(): void {
-    // Intentionally empty.
-  }
-
-  info(): void {
-    // Intentionally empty.
-  }
-
-  warn(): void {
-    // Intentionally empty.
-  }
-
-  error(): void {
-    // Intentionally empty.
-  }
-}
-
-// Numeric severity used by LogLevel to gate calls.
-const LEVEL_SEVERITY: Record<Level, number> = {
-  debug: 0,
-  info: 1,
-  warn: 2,
-  error: 3,
-  off: 4,
-};
-
-/**
- * A decorator that adds level filtering to any {@link Logger}.
- *
- * Only messages at or above the configured minimum level are forwarded to the
- * underlying logger. The default underlying logger is `console`.
- *
- * @example
- * ```typescript
- * // Only warn and error go to console.
- * const logger = new LogLevel('warn');
- * ```
- */
-export class LogLevel implements Logger {
-  private readonly threshold: number;
-  private readonly logger: Logger;
-
-  constructor(level: Level, logger: Logger = console) {
-    this.threshold = LEVEL_SEVERITY[level];
-    this.logger = logger;
-  }
-
-  debug(message: string, ...args: unknown[]): void {
-    if (this.threshold <= LEVEL_SEVERITY.debug) {
-      this.logger.debug(message, ...args);
-    }
-  }
-
-  info(message: string, ...args: unknown[]): void {
-    if (this.threshold <= LEVEL_SEVERITY.info) {
-      this.logger.info(message, ...args);
-    }
-  }
-
-  warn(message: string, ...args: unknown[]): void {
-    if (this.threshold <= LEVEL_SEVERITY.warn) {
-      this.logger.warn(message, ...args);
-    }
-  }
-
-  error(message: string, ...args: unknown[]): void {
-    if (this.threshold <= LEVEL_SEVERITY.error) {
-      this.logger.error(message, ...args);
-    }
-  }
-}

package/src/ops/execute.ts

@@ -1,99 +0,0 @@
-import type {Options} from './options';
-import type {Retrier} from './retrier';
-
-// Coerces an unknown value to an Error instance.
-function toError(value: unknown): Error {
-  return value instanceof Error ? value : new Error(String(value));
-}
-
-/**
- * Sleeps for the given duration. It is mostly equivalent to setTimeout, but
- * can be interrupted by the AbortSignal if the signal aborts before the
- * duration elapses.
- */
-export function sleep(ms: number, signal?: AbortSignal): Promise<void> {
-  return new Promise<void>((resolve, reject) => {
-    if (signal?.aborted === true) {
-      reject(toError(signal.reason));
-      return;
-    }
-    if (signal === undefined) {
-      setTimeout(resolve, ms);
-      return;
-    }
-    const onAbort = (): void => {
-      clearTimeout(timer);
-      reject(toError(signal.reason));
-    };
-    const timer = setTimeout(() => {
-      signal.removeEventListener('abort', onAbort);
-      resolve();
-    }, ms);
-    signal.addEventListener('abort', onAbort, {once: true});
-  });
-}
-
-// Sleeper is a convenience type for readability.
-type Sleeper = (ms: number, signal?: AbortSignal) => Promise<void>;
-
-/** Executes operation op with the given options. */
-export async function execute(
-  signal: AbortSignal | undefined,
-  op: (signal?: AbortSignal) => Promise<void>,
-  options?: Options
-): Promise<void> {
-  const opts: Options = {...options};
-  return executeImpl(signal, op, opts, sleep);
-}
-
-/**
- * The actual implementation of execute. Its purpose is to ease testing by
- * providing a convenient way to mock the sleeping logic.
- */
-async function executeImpl(
-  signal: AbortSignal | undefined,
-  op: (signal?: AbortSignal) => Promise<void>,
-  opts: Options,
-  sleep: Sleeper
-): Promise<void> {
-  // Optionally combine the signal with a timeout signal. If the signal
-  // already has a deadline, that deadline is updated to the minimum of the
-  // signal's deadline and the timeout.
-  if (opts.timeout !== undefined && opts.timeout > 0) {
-    const timeoutSignal = AbortSignal.timeout(opts.timeout);
-    signal = signal ? AbortSignal.any([signal, timeoutSignal]) : timeoutSignal;
-  }
-
-  // Get a new retrier for this specific execution. This is instantiated
-  // lazily if and when the first operation execution returns an error.
-  let retrier: Retrier | undefined;
-
-  for (;;) {
-    if (opts.rateLimiter) {
-      await opts.rateLimiter.wait(signal);
-    }
-
-    try {
-      await op(signal);
-      return; // Nothing to retry.
-    } catch (err: unknown) {
-      const error = toError(err);
-
-      if (retrier === undefined) {
-        if (opts.retrier) {
-          retrier = opts.retrier(); // Lazily instantiate the retrier.
-        }
-        if (retrier === undefined) {
-          throw error; // No retrier == no retry.
-        }
-      }
-
-      const delay = retrier.isRetriable(error);
-      if (delay === undefined) {
-        throw error; // Not retriable.
-      }
-
-      await sleep(delay, signal);
-    }
-  }
-}

package/src/ops/index.ts

@@ -1,12 +0,0 @@
-/**
- * Utilities to execute Databricks operations with retry, timeout, and rate
- * limiting.
- *
- * @packageDocumentation
- */
-
-export {execute} from './execute';
-export type {Limiter} from './limiter';
-export type {Options} from './options';
-export {BackoffPolicy, retryOn} from './retrier';
-export type {BackoffPolicyOptions, Retrier} from './retrier';

package/src/ops/limiter.ts

@@ -1,8 +0,0 @@
-/**
- * Limiter is anything that can wait. It is typically used to implement
- * client-side rate limiting. Implementations of this interface must be
- * safe to call concurrently.
- */
-export interface Limiter {
-  wait(signal?: AbortSignal): Promise<void>;
-}

package/src/ops/options.ts

@@ -1,22 +0,0 @@
-import type {Limiter} from './limiter';
-import type {Retrier} from './retrier';
-
-/** Options that control the behavior of an operation. */
-export interface Options {
-  /**
-   * Provides a new Retrier to be used to execute an operation. The function
-   * is called for each operation and must be safe to call concurrently. The
-   * retrier must be fresh within the context of an execute call (e.g. no
-   * need to reset a BackoffPolicy).
-   */
-  retrier?: (() => Retrier) | undefined;
-  /** The rate limiter used to potentially rate limit the operation. */
-  rateLimiter?: Limiter | undefined;
-  /**
-   * Timeout duration in milliseconds. If the signal already has a deadline,
-   * that deadline is updated to the minimum of the signal's deadline and the
-   * timeout. The timeout covers the whole operation execution; it is not a
-   * timeout for each intermediary call.
-   */
-  timeout?: number | undefined;
-}