@databricks/sdk-core 0.0.0-dev → 0.1.0-dev.2

package/dist/wkt/fieldmask.js

@@ -0,0 +1,68 @@
+// Remove duplicates and paths subsumed by a parent (e.g. "config" subsumes "config.numWorkers").
+function normalize(paths) {
+    const unique = [...new Set(paths)].sort();
+    const result = [];
+    for (const path of unique) {
+        const isSubsumed = result.some(existing => path.startsWith(existing + '.'));
+        if (!isSubsumed) {
+            result.push(path);
+        }
+    }
+    return result;
+}
+// Walk a dot-separated typescript field name path against a schema, returning the equivalent wire-format path. Returns `undefined` when any segment fails: a name that isn't a field of the current message, or a non-terminal segment that doesn't reference another message.
+function walkFieldMaskPath(schema, path) {
+    const segments = path.split('.');
+    const wireSegments = [];
+    let current = schema;
+    for (let i = 0; i < segments.length; i++) {
+        const seg = segments[i];
+        // Existence check before lookup: `current[seg]` is typed as FieldMaskSchemaField without noUncheckedIndexedAccess, so an undefined check downstream would be flagged "unnecessary".
+        if (!(seg in current))
+            return undefined;
+        const field = current[seg];
+        wireSegments.push(field.wire);
+        if (i < segments.length - 1) {
+            if (field.children === undefined)
+                return undefined;
+            current = field.children();
+        }
+    }
+    return wireSegments.join('.');
+}
+/**
+ * A field mask implementing google.protobuf.FieldMask semantics.
+ */
+export class FieldMask {
+    // Stored post-translation, normalized wire-format paths.
+    paths;
+    constructor(paths) {
+        this.paths = paths;
+    }
+    /**
+     * Build a FieldMask from typescript field name paths against the target message's schema. Validates every path by walking each segment through the schema and throws Error when any segment fails.
+     *
+     * Reserved for generated per-message factories; user code should call the factory (e.g. `alertFieldMask(...)`), which supplies the schema before delegating here.
+     *
+     * @internal
+     */
+    static build(paths, schema) {
+        const normalized = normalize(paths);
+        const wire = [];
+        for (const p of normalized) {
+            const w = walkFieldMaskPath(schema, p);
+            if (w === undefined) {
+                throw new Error(`Unknown field path "${p}"`);
+            }
+            wire.push(w);
+        }
+        return new FieldMask(wire);
+    }
+    /**
+     * Serialize the mask to the wire-format string.
+     */
+    toString() {
+        return this.paths.join(',');
+    }
+}
+//# sourceMappingURL=fieldmask.js.map

package/dist/wkt/fieldmask.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fieldmask.js","sourceRoot":"","sources":["../../src/wkt/fieldmask.ts"],"names":[],"mappings":"AAAA,iGAAiG;AACjG,SAAS,SAAS,CAAC,KAAe;IAChC,MAAM,MAAM,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAC1C,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,KAAK,MAAM,IAAI,IAAI,MAAM,EAAE,CAAC;QAC1B,MAAM,UAAU,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,QAAQ,GAAG,GAAG,CAAC,CAAC,CAAC;QAC5E,IAAI,CAAC,UAAU,EAAE,CAAC;YAChB,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACpB,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAeD,+QAA+Q;AAC/Q,SAAS,iBAAiB,CACxB,MAAuB,EACvB,IAAY;IAEZ,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACjC,MAAM,YAAY,GAAa,EAAE,CAAC;IAClC,IAAI,OAAO,GAAoB,MAAM,CAAC;IACtC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,QAAQ,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACzC,MAAM,GAAG,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;QACxB,oLAAoL;QACpL,IAAI,CAAC,CAAC,GAAG,IAAI,OAAO,CAAC;YAAE,OAAO,SAAS,CAAC;QACxC,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;QAC3B,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC9B,IAAI,CAAC,GAAG,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC5B,IAAI,KAAK,CAAC,QAAQ,KAAK,SAAS;gBAAE,OAAO,SAAS,CAAC;YACnD,OAAO,GAAG,KAAK,CAAC,QAAQ,EAAE,CAAC;QAC7B,CAAC;IACH,CAAC;IACD,OAAO,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAChC,CAAC;AAED;;GAEG;AACH,MAAM,OAAO,SAAS;IAIpB,yDAAyD;IACxC,KAAK,CAAW;IAEjC,YAAoB,KAAe;QACjC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,CAAC;IAED;;;;;;OAMG;IACH,MAAM,CAAC,KAAK,CAAI,KAAe,EAAE,MAAuB;QACtD,MAAM,UAAU,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC;QACpC,MAAM,IAAI,GAAa,EAAE,CAAC;QAC1B,KAAK,MAAM,CAAC,IAAI,UAAU,EAAE,CAAC;YAC3B,MAAM,CAAC,GAAG,iBAAiB,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;YACvC,IAAI,CAAC,KAAK,SAAS,EAAE,CAAC;gBACpB,MAAM,IAAI,KAAK,CAAC,uBAAuB,CAAC,GAAG,CAAC,CAAC;YAC/C,CAAC;YACD,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACf,CAAC;QACD,OAAO,IAAI,SAAS,CAAI,IAAI,CAAC,CAAC;IAChC,CAAC;IAED;;OAEG;IACH,QAAQ;QACN,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC9B,CAAC;CACF"}

package/dist/wkt/index.d.ts

@@ -0,0 +1,4 @@
+export { FieldMask } from './fieldmask';
+export type { FieldMaskSchema, FieldMaskSchemaField } from './fieldmask';
+export type { JsonValue, JsonObject } from './value';
+//# sourceMappingURL=index.d.ts.map

package/dist/wkt/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/wkt/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,SAAS,EAAC,MAAM,aAAa,CAAC;AACtC,YAAY,EAAC,eAAe,EAAE,oBAAoB,EAAC,MAAM,aAAa,CAAC;AACvE,YAAY,EAAC,SAAS,EAAE,UAAU,EAAC,MAAM,SAAS,CAAC"}

package/dist/wkt/index.js

@@ -0,0 +1,2 @@
+export { FieldMask } from './fieldmask';
+//# sourceMappingURL=index.js.map

package/dist/wkt/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/wkt/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,SAAS,EAAC,MAAM,aAAa,CAAC"}

package/dist/wkt/value.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Represents any valid JSON value. Matches the JSON value space used by
+ * google.protobuf.Value.
+ */
+export type JsonValue = null | number | string | boolean | JsonObject | JsonValue[];
+/**
+ * Represents a JSON object with string keys and JSON values. Matches the
+ * structure used by google.protobuf.Struct.
+ */
+export interface JsonObject {
+    [key: string]: JsonValue;
+}
+//# sourceMappingURL=value.d.ts.map

package/dist/wkt/value.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"value.d.ts","sourceRoot":"","sources":["../../src/wkt/value.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,MAAM,SAAS,GACjB,IAAI,GACJ,MAAM,GACN,MAAM,GACN,OAAO,GACP,UAAU,GACV,SAAS,EAAE,CAAC;AAEhB;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;CAC1B"}

package/dist/wkt/value.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=value.js.map

package/dist/wkt/value.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"value.js","sourceRoot":"","sources":["../../src/wkt/value.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,7 +1,85 @@
 {
   "name": "@databricks/sdk-core",
-  "version": "0.0.0-dev",
-  "description": "Bootstrap placeholder; real contents in a later release.",
-  "main": "index.js",
-  "license": "Apache-2.0"
+  "version": "0.1.0-dev.2",
+  "description": "Databricks core library for JavaScript/TypeScript",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./profiles": {
+      "types": "./dist/profiles/index.d.ts",
+      "import": "./dist/profiles/index.js"
+    },
+    "./profiles/browser": {
+      "types": "./dist/profiles/index.browser.d.ts",
+      "import": "./dist/profiles/index.browser.js"
+    },
+    "./wkt": {
+      "types": "./dist/wkt/index.d.ts",
+      "import": "./dist/wkt/index.js"
+    },
+    "./clientinfo": {
+      "browser": {
+        "types": "./dist/clientinfo/index.browser.d.ts",
+        "import": "./dist/clientinfo/index.browser.js"
+      },
+      "default": {
+        "types": "./dist/clientinfo/index.d.ts",
+        "import": "./dist/clientinfo/index.js"
+      }
+    },
+    "./clientinfo/browser": {
+      "types": "./dist/clientinfo/index.browser.d.ts",
+      "import": "./dist/clientinfo/index.browser.js"
+    },
+    "./http": {
+      "types": "./dist/http/index.d.ts",
+      "import": "./dist/http/index.js"
+    },
+    "./logger": {
+      "types": "./dist/logger/index.d.ts",
+      "import": "./dist/logger/index.js"
+    },
+    "./api": {
+      "types": "./dist/api/index.d.ts",
+      "import": "./dist/api/index.js"
+    },
+    "./apierror": {
+      "types": "./dist/apierror/index.d.ts",
+      "import": "./dist/apierror/index.js"
+    },
+    "./apierror/codes": {
+      "types": "./dist/apierror/codes/index.d.ts",
+      "import": "./dist/apierror/codes/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "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:browser": "vitest run --config vitest.config.browser.ts",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist tsconfig.tsbuildinfo"
+  },
+  "author": "Databricks",
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "dependencies": {
+    "json-bigint": "^1.0.0",
+    "zod": "^4.3.6"
+  }
 }

package/src/api/execute.ts

@@ -0,0 +1,102 @@
+import type {Options} from './options';
+import type {Retrier} from './retrier';
+
+/** Call represents a call to a Databricks API. */
+export type Call = (signal?: AbortSignal) => Promise<void>;
+
+// 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>;
+
+/** Makes a call to a Databricks API using the given options. */
+export async function execute(
+  signal: AbortSignal | undefined,
+  call: Call,
+  options?: Options
+): Promise<void> {
+  const opts: Options = {...options};
+  return executeImpl(signal, call, 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,
+  apiCall: Call,
+  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 call execution returns an error.
+  let retrier: Retrier | undefined;
+
+  for (;;) {
+    if (opts.rateLimiter) {
+      await opts.rateLimiter.wait(signal);
+    }
+
+    try {
+      await apiCall(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/api/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Databricks API client utilities.
+ *
+ * @packageDocumentation
+ */
+
+export {execute} from './execute';
+export type {Call} 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/api/limiter.ts

@@ -0,0 +1,8 @@
+/**
+ * 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/api/options.ts

@@ -0,0 +1,22 @@
+import type {Limiter} from './limiter';
+import type {Retrier} from './retrier';
+
+/** Options to control the behavior of an API call. */
+export interface Options {
+  /**
+   * Provides a new Retrier to be used to execute a Call. The function is
+   * called for each Call 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 API call. */
+  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 Call execution; it is not a timeout
+   * for each intermediary API call.
+   */
+  timeout?: number | undefined;
+}

package/src/api/retrier.ts

@@ -0,0 +1,108 @@
+/** Options for configuring a {@link BackoffPolicy}. */
+export interface BackoffPolicyOptions {
+  /** Initial delay in milliseconds; defaults to 1000. */
+  initial?: number;
+
+  /** Maximum delay in milliseconds; defaults to 60000. */
+  maximum?: number;
+
+  /**
+   * Factor by which the delay is multiplied after each retry. The value must
+   * be greater or equal to 1. If not, it defaults to 2.
+   */
+  factor?: number;
+}
+
+// Random number generation, wrapped in an object for testability.
+export const rand = {
+  // Returns a random integer in [0, n).
+  int(n: number): number {
+    return Math.floor(Math.random() * n);
+  },
+};
+
+/**
+ * BackoffPolicy implements an exponential backoff policy. The delay between
+ * retries is randomly computed between 0 and the "exponential delay" as
+ * recommended in [Exponential Backoff And Jitter]. The retry delay starts from
+ * initial and grows exponentially by factor at every retry. The maximum retry
+ * delay is capped by maximum.
+ *
+ * There is no parameter to limit the number of retries. This is intended as
+ * such logic should be implemented upstream (e.g. in a Retrier).
+ *
+ * [Exponential Backoff And Jitter]: https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/
+ */
+export class BackoffPolicy {
+  /** Initial delay in milliseconds. */
+  readonly initial: number;
+
+  /** Maximum delay in milliseconds. */
+  readonly maximum: number;
+
+  /** Factor by which the delay is multiplied after each retry. */
+  readonly factor: number;
+
+  // Current delay before the next retry.
+  private current: number;
+
+  constructor(options?: BackoffPolicyOptions) {
+    let initial = options?.initial ?? 1000; // Default initial delay of 1 second.
+    const maximum = options?.maximum ?? 60000; // Default maximum delay of 60 seconds.
+
+    if (initial > maximum) {
+      // Initial cannot be greater than maximum.
+      initial = maximum;
+    }
+
+    this.initial = initial;
+    this.maximum = maximum;
+    this.factor =
+      options?.factor !== undefined && options.factor >= 1 ? options.factor : 2;
+    this.current = this.initial;
+  }
+
+  /** Returns a random delay in [0, current] and grows the current delay. */
+  delay(): number {
+    // Random duration in the range [0, this.current].
+    const d = rand.int(this.current + 1);
+
+    // Grow delay for the next call.
+    this.current = Math.min(this.current * this.factor, this.maximum);
+
+    return d;
+  }
+}
+
+/** Retrier defines a retry behavior. */
+export interface Retrier {
+  /**
+   * Returns the delay in milliseconds before the next retry, or undefined if
+   * the error is not retriable. Implementations should assume that the given
+   * error is never undefined.
+   */
+  isRetriable(err: Error): number | undefined;
+}
+
+/**
+ * Returns a Retrier that retries based on the isRetriable predicate and relies
+ * on an internal backoff policy to decide how long to wait between retries.
+ *
+ * Important: the retrier has its own backoff policy which cannot be trivially
+ * reset by design. Users who need to reset the backoff policy should rather
+ * create a new retrier.
+ */
+export function retryOn(
+  options: BackoffPolicyOptions,
+  isRetriable: (err: Error) => boolean
+): Retrier {
+  const bp = new BackoffPolicy(options);
+  return {
+    isRetriable(err: Error): number | undefined {
+      if (!isRetriable(err)) {
+        return undefined;
+      }
+      return bp.delay();
+    },
+  };
+}