@dbx-tools/shared-core 0.1.2

package/.projen/deps.json

@@ -0,0 +1,29 @@
+{
+  "dependencies": [
+    {
+      "name": "@types/node",
+      "version": "^24.6.0",
+      "type": "build"
+    },
+    {
+      "name": "consola",
+      "version": "catalog:",
+      "type": "build"
+    },
+    {
+      "name": "tsx",
+      "version": "^4.23.0",
+      "type": "build"
+    },
+    {
+      "name": "typescript",
+      "type": "build"
+    },
+    {
+      "name": "consola",
+      "version": "catalog:",
+      "type": "peer"
+    }
+  ],
+  "//": "~~ Generated by projen. To modify, edit .projenrc.js and run \"pnpm exec projen\"."
+}

package/.projen/files.json

@@ -0,0 +1,11 @@
+{
+  "files": [
+    ".projen/deps.json",
+    ".projen/files.json",
+    ".projen/tasks.json",
+    "package.json",
+    "test/tsconfig.json",
+    "tsconfig.json"
+  ],
+  "//": "~~ Generated by projen. To modify, edit .projenrc.js and run \"pnpm exec projen\"."
+}

package/.projen/tasks.json

@@ -0,0 +1,121 @@
+{
+  "manifestVersion": 3,
+  "env": {
+    "PATH": "$(pnpm -c exec \"node --print process.env.PATH\")"
+  },
+  "tasks": {
+    "build": {
+      "name": "build",
+      "description": "Full release build",
+      "steps": [
+        {
+          "spawn": "pre-compile"
+        },
+        {
+          "spawn": "compile"
+        },
+        {
+          "spawn": "post-compile"
+        },
+        {
+          "spawn": "test"
+        },
+        {
+          "spawn": "package"
+        }
+      ]
+    },
+    "compile": {
+      "name": "compile",
+      "description": "Only compile",
+      "steps": [
+        {
+          "execArgs": [
+            "tsc",
+            "--build"
+          ]
+        }
+      ]
+    },
+    "default": {
+      "name": "default",
+      "description": "Synthesize project files",
+      "steps": [
+        {
+          "exec": "pnpm exec projen default",
+          "cwd": "../../.."
+        }
+      ]
+    },
+    "install": {
+      "name": "install",
+      "description": "Install project dependencies and update lockfile (non-frozen)",
+      "steps": [
+        {
+          "exec": "pnpm i --no-frozen-lockfile"
+        }
+      ]
+    },
+    "install:ci": {
+      "name": "install:ci",
+      "description": "Install project dependencies using frozen lockfile",
+      "steps": [
+        {
+          "exec": "pnpm i --frozen-lockfile"
+        }
+      ]
+    },
+    "package": {
+      "name": "package",
+      "description": "Creates the distribution package",
+      "steps": [
+        {
+          "execArgs": [
+            "mkdir",
+            "-p",
+            "dist/js"
+          ]
+        },
+        {
+          "execArgs": [
+            "pnpm",
+            "pack",
+            "--pack-destination",
+            "dist/js"
+          ]
+        }
+      ]
+    },
+    "post-compile": {
+      "name": "post-compile",
+      "description": "Runs after successful compilation"
+    },
+    "pre-compile": {
+      "name": "pre-compile",
+      "description": "Prepare the project for compilation"
+    },
+    "test": {
+      "name": "test",
+      "description": "Run tests",
+      "steps": [
+        {
+          "exec": "tsx --test 'test/**/*.test.ts'"
+        }
+      ]
+    },
+    "watch": {
+      "name": "watch",
+      "description": "Watch & compile in the background",
+      "steps": [
+        {
+          "execArgs": [
+            "tsc",
+            "--build",
+            "-w"
+          ]
+        }
+      ]
+    }
+  },
+  "//": "~~ Generated by projen. To modify, edit .projenrc.js and run \"pnpm exec projen\"."
+}

package/README.md

@@ -0,0 +1,220 @@
+# @dbx-tools/shared-core
+
+Browser-safe utility base for `@dbx-tools/*` packages.
+
+Import this package for small, dependency-light helpers that can run in Node,
+browsers, workers, CLIs, and shared schema packages. Modules are exported as
+namespaces so call sites stay explicit:
+
+```ts
+import {
+  async,
+  error,
+  hash,
+  http,
+  iterable,
+  log,
+  net,
+  object,
+  string,
+} from "@dbx-tools/shared-core";
+```
+
+Node-only helpers live in [`@dbx-tools/node-core`](../../node/core). AppKit and
+Databricks SDK helpers live in [`@dbx-tools/node-appkit`](../../node/appkit).
+
+Key features:
+
+- Abort-aware async utilities for polling, sleeping, and connecting cancellation
+  across web and Node runtimes.
+- Error normalization for unknown thrown values, nested causes, and HTTP-ish
+  status/message extraction.
+- Deterministic non-cryptographic hashes and short ids for cache keys, slugs,
+  and generated names.
+- String normalization helpers for slugs, identifiers, unique labels, and prompt
+  descriptions.
+- Object, predicate, iterable, HTTP, cookie, network, token, memoization, and
+  logging helpers that avoid Node-only dependencies.
+- Namespace exports that make utility call sites explicit without creating a
+  grab-bag default import.
+
+## Async Control
+
+```ts
+for await (const status of async.poll(fetchStatus, {
+  intervalMs: 250,
+  timeoutMs: 30_000,
+  predicate: (s) => s !== "READY",
+})) {
+  render(status);
+}
+
+await async.sleep(500, abortSignal);
+```
+
+`async.poll()` is useful for Databricks APIs that expose long-running state.
+`async.tieAbortSignal()` and `async.sleep()` let route handlers connect caller
+cancellation to background work.
+
+## Error Handling
+
+```ts
+try {
+  await run();
+} catch (err) {
+  logger.warn("run failed", { error: error.errorMessage(err) });
+  const ctx = error.errorContext(err);
+  return Response.json({ message: ctx.message }, { status: ctx.status ?? 500 });
+}
+```
+
+`error.toError()`, `error.errorMessage()`, `error.errorMessages()`, and
+`error.errorNodes()` normalize unknown thrown values. `error.errorContext()`
+extracts HTTP-ish status/message detail from nested errors.
+
+## Hashes And Ids
+
+```ts
+const id = hash.id(8);
+const cacheKey = hash.fnvHash("workspace", host, endpointName);
+const suffix = hash.fnvHashWithOptions({ length: 6 }, longName);
+```
+
+These hashes are deterministic and non-cryptographic. Use them for cache keys,
+slug suffixes, and trace-stable identifiers, not secrets or signatures.
+
+## Strings And Descriptions
+
+```ts
+const slug = string.toSlug("My Cool Project!");
+const id = string.toIdentifierWithOptions({ delimiter: "_" }, "Model Name");
+const unique = string.toUniqueSlug("Send Email", { fallbackPrefix: "tool" });
+const description = string.toDescription([
+  "Answer with SQL first.",
+  { "When data is missing": "Say what is missing." },
+]);
+```
+
+`string.tokenize()`, `toSlug()`, and `toIdentifier()` keep package names, tool
+ids, schema ids, and generated labels consistent. `toDescription()` turns nested
+description data into prompt/tool text without hand-concatenating paragraphs.
+
+## Objects And Predicates
+
+```ts
+if (object.isRecord(value)) {
+  const enabled = object.toBoolean(value.enabled);
+}
+
+const same = object.deepEqual(left, right);
+
+const isRunnable = predicate
+  .create((pkg: Package) => pkg.tags.includes("node"))
+  .and((pkg) => pkg.name.includes("appkit"));
+```
+
+`object.deepEqual()` supports an optional comparator for domain-specific
+short-circuits. `predicate.create()` returns composable predicates with `and`,
+`or`, and `negate`, used heavily by the projen engine.
+
+## Iterables
+
+```ts
+const names = iterable
+  .sequence(packages)
+  .map((p) => p.name)
+  .filter(Boolean)
+  .distinct()
+  .toArray();
+
+const grouped = iterable.group(packages, {
+  node: (p) => p.tags.includes("node"),
+  ui: (p) => p.tags.includes("ui"),
+});
+```
+
+The iterable helpers are lazy and work well for filesystem scans, package lists,
+and one-pass generated data. Use `sequence(..., { cache: true })` when a source
+must be re-read.
+
+## HTTP Headers And Cookies
+
+```ts
+const cookies = http.parseCookies(req);
+
+let bearer: string | undefined;
+http.forEachHeaderValue(req, "authorization", (value) => {
+  if (value.startsWith("Bearer ")) bearer = value.slice("Bearer ".length);
+});
+```
+
+`http.HeaderLike` works with Fetch `Request`, Express-ish requests, Node header
+records, and plain `{ headers }` objects. `http.createFetchError()` turns a
+failed `Response` into an error with response text attached.
+
+## Network Strings, Email, And CIDR
+
+```ts
+const url = net.urlBuilder("example.com")?.withPathAppend("api", "2.0");
+const emails = net.parseEmails("alice@example.com; bob@example.com");
+const cidr = net.parseCidr("10.0.0.0/8");
+const internal = cidr ? net.ipInCidr("10.1.2.3", cidr) : false;
+```
+
+`net.urlBuilder()` is a forgiving URL builder for config and REST helpers.
+`net.pathMatch()` compares path prefixes on segment boundaries. IP/CIDR helpers
+parse IPv4 and IPv6 into a shared bigint comparison model.
+
+## Token Claims
+
+```ts
+const scopes = token.getAccessTokenScopes(req, "x-forwarded-access-token");
+const canReadWorkspace = token.includesAccessTokenScope(scopes, ["workspace", "all-apis"]);
+```
+
+Token helpers decode JWT payloads without validating signatures. Use them for
+request-scoped authorization hints after the platform has already authenticated
+the request.
+
+## Memoization
+
+```ts
+const getRanges = functionModule.memoize(fetchRanges, {
+  ttlMs: 24 * 60 * 60 * 1000,
+});
+```
+
+`functionModule.memoize()` caches sync or async factories, evicts rejected
+promises, and supports TTL-based refresh. It is useful for public metadata feeds,
+SDK catalogues, and expensive computed constants.
+
+## Logging
+
+```ts
+const logger = log.logger("mastra/genie");
+logger.info("space:resolved", { spaceId });
+
+if (log.isLevelEnabled("debug")) {
+  logger.debug("large payload", expensivePayload());
+}
+```
+
+`log.logger()` uses `consola` when installed and falls back to `console`. It
+honors `LOG_LEVEL` per call, so debug statements can stay in production code
+without paying formatting cost when disabled.
+
+## Modules
+
+- `async` - polling, sleep, and abort-signal wiring.
+- `error` - unknown-error normalization and HTTP-ish error context.
+- `hash` - ids, FNV hashes, and base32 encoding.
+- `string` - tokenization, slugs, identifiers, descriptions, pluralization, and
+  HTML escaping.
+- `object` - record checks, boolean coercion, deep equality, and shape types.
+- `iterable` - lazy sequence transforms and collection helpers.
+- `predicate` - composable boolean/type predicates.
+- `http` - header iteration, cookie parsing, and fetch error creation.
+- `net` - URL building, email parsing, path matching, IP/CIDR helpers.
+- `token` - JWT payload and scope readers.
+- `functionModule` - memoization.
+- `log` - tagged leveled logging.

package/index.ts

@@ -0,0 +1,26 @@
+// GENERATED by projen watch - DO NOT EDIT.
+// Regenerated from the exporting modules in ./src.
+// Hand edits are overwritten on the next watch; this file is read-only.
+
+export * as async from "./src/async";
+export * as error from "./src/error";
+export * as functionModule from "./src/function";
+export * as hash from "./src/hash";
+export * as http from "./src/http";
+export * as iterable from "./src/iterable";
+export * as log from "./src/log";
+export * as net from "./src/net";
+export * as object from "./src/object";
+export * as predicate from "./src/predicate";
+export * as string from "./src/string";
+export * as token from "./src/token";
+export type { PollContext, PollProducer, PollOptions } from "./src/async";
+export type { ErrorContext } from "./src/error";
+export type { MemoizeOptions } from "./src/function";
+export type { HeaderLike } from "./src/http";
+export type { Sequence, Container, Collection, OneOrMany } from "./src/iterable";
+export type { LogLevel, Logger } from "./src/log";
+export type { UrlLike, IpVersion, ParsedIp, Cidr, UrlBuilder, ParseEmailsOptions } from "./src/net";
+export type { NameLike, NonFunctionKeys, DeepEqualComparator } from "./src/object";
+export type { PredicateFunction, TypePredicateFunction, PredicateInput, Predicate } from "./src/predicate";
+export type { TokenizeOptions, KeyOptions, IdentifierOptions, Description } from "./src/string";

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@dbx-tools/shared-core",
+  "devDependencies": {
+    "@types/node": "^24.6.0",
+    "consola": "^3.4.2",
+    "tsx": "^4.23.0",
+    "typescript": "^5.9.3"
+  },
+  "peerDependencies": {
+    "consola": "^3.4.2"
+  },
+  "main": "index.ts",
+  "license": "UNLICENSED",
+  "version": "0.1.2",
+  "types": "index.ts",
+  "type": "module",
+  "exports": {
+    ".": "./index.ts",
+    "./package.json": "./package.json"
+  },
+  "peerDependenciesMeta": {
+    "consola": {
+      "optional": true
+    }
+  },
+  "dbxToolsConfig": {
+    "tags": [
+      "shared"
+    ]
+  },
+  "//": "~~ Generated by projen. To modify, edit .projenrc.js and run \"pnpm exec projen\".",
+  "scripts": {
+    "build": "projen build",
+    "compile": "projen compile",
+    "default": "projen default",
+    "package": "projen package",
+    "post-compile": "projen post-compile",
+    "pre-compile": "projen pre-compile",
+    "test": "projen test",
+    "watch": "projen watch",
+    "projen": "projen"
+  }
+}

package/src/async.ts

@@ -0,0 +1,209 @@
+/**
+ * Cancellation-aware async primitives: an abortable {@link sleep}, an
+ * {@link AbortController} linker ({@link tieAbortSignal}), and a periodic
+ * {@link poll} generator. Dependency-free; `poll`'s `"distinct"` filter
+ * uses the local {@link deepEqual}.
+ */
+import { deepEqual } from "./object";
+
+/**
+ * Per-iteration context handed to {@link PollProducer} and the
+ * predicate on each step of a {@link poll} loop. Bundles the
+ * iteration metadata so the call signatures stay stable as `poll`
+ * grows additional fields.
+ *
+ * `signal` is owned by `poll`: it tracks the external
+ * `PollOptions.signal` (when supplied) and also fires when the
+ * consumer breaks out of the loop, so producers can forward it to
+ * any in-flight work (`fetch`, SDK calls, etc.) and have a single
+ * cancellation source tear down both the request and the loop.
+ *
+ * `attributes` is a mutable scratchpad shared across every
+ * iteration of a single `poll` run. The same object reference is
+ * passed each call so writes from one iteration are visible to the
+ * next - useful for stashing per-loop state (retry counters, start
+ * timestamps, anything you'd otherwise close over via a let).
+ * Generic `A` lets callers type the bag; defaults to
+ * `Record<string, unknown>`.
+ */
+export interface PollContext<T, A = Record<string, unknown>> {
+  /** Zero-based iteration index (`0` on the first call). */
+  attempt: number;
+  /** Value yielded on the prior iteration; `undefined` on the first. */
+  previous: T | undefined;
+  /** Cancellation handle. Always defined; forward to in-flight work. */
+  signal: AbortSignal;
+  /** Per-run mutable scratchpad shared across iterations. */
+  attributes: A;
+}
+
+/** One step of a {@link poll} loop. See {@link PollContext}. */
+export type PollProducer<T, A = Record<string, unknown>> = (
+  ctx: PollContext<T, A>,
+) => T | PromiseLike<T>;
+
+export interface PollOptions<T, A = Record<string, unknown>> {
+  /** Milliseconds to wait between polls. */
+  intervalMs: number;
+  /**
+   * Predicate evaluated against each yielded value: return `true` to
+   * keep it, `false` to skip it (without stopping the loop). May be
+   * sync or async - a `PromiseLike<boolean>` is awaited before the
+   * decision is made. Receives the same {@link PollContext} as the
+   * producer (same `signal`, same `attributes` bag). The special
+   * value `"distinct"` skips a value that deep-equals the previous
+   * one.
+   */
+  filter?: ((value: T, ctx: PollContext<T, A>) => boolean | PromiseLike<boolean>) | "distinct";
+  /**
+   * Predicate evaluated against each yielded value: return `true` to
+   * keep polling, `false` to stop. May be sync or async. Omit to poll
+   * forever (the consumer stops by breaking out of the loop or by
+   * aborting `signal`).
+   */
+  predicate?: (value: T, ctx: PollContext<T, A>) => boolean | PromiseLike<boolean>;
+  /**
+   * External cancellation handle. Tied into the internal signal that
+   * `poll` hands to `producer`, so aborting it tears down both the
+   * in-flight request and the inter-poll sleep.
+   */
+  signal?: AbortSignal;
+  /**
+   * Hard upper bound on the total lifetime of the poll loop, in
+   * milliseconds. When the budget elapses, `poll` aborts its internal
+   * signal so the in-flight producer and inter-poll sleep both tear
+   * down promptly, and the loop throws the `TimeoutError`
+   * `DOMException` produced by `AbortSignal.timeout(timeoutMs)`. The
+   * budget starts ticking the moment the generator is created.
+   */
+  timeoutMs?: number;
+  /**
+   * Initial value for `ctx.attributes`. Defaults to `{}`. The same
+   * object is reused across iterations, so callers can pre-populate
+   * fields (timers, retry counters, etc.) and the producer /
+   * predicate can mutate them in place.
+   */
+  attributes?: A;
+}
+
+/**
+ * Async iterable that drives a periodic poll. Each iteration:
+ *
+ *   1. Builds a {@link PollContext} (`attempt`, `previous`, `signal`,
+ *      shared `attributes`) and calls `producer(ctx)`; yields the
+ *      resolved value (subject to `filter`).
+ *   2. Evaluates `options.predicate(value, ctx)`; stops when it
+ *      returns (or resolves to) `false`.
+ *   3. Sleeps `options.intervalMs` before the next attempt.
+ *
+ * The first call runs immediately (no leading sleep) so the consumer
+ * sees a value without waiting an interval. Errors thrown by
+ * `producer` propagate through the generator.
+ *
+ * `poll` always creates an internal `AbortController` and exposes
+ * `internal.signal` as `ctx.signal`, so producers can rely on a
+ * defined signal without a nullish check. The external
+ * `options.signal` is tied in, and a `try/finally` aborts the
+ * internal signal when the consumer breaks out of the `for await`
+ * (or the loop throws), so any producer work still holding the
+ * signal sees the cancellation too.
+ *
+ * @example
+ * for await (const msg of poll(
+ *   async ({ signal }) =>
+ *     client.genie.getMessage({ ... }, { abortSignal: signal }),
+ *   {
+ *     intervalMs: 250,
+ *     predicate: (m) => !TERMINAL_STATUSES.has(m.status),
+ *     signal: controller.signal,
+ *   },
+ * )) {
+ *   render(msg);
+ * }
+ */
+export async function* poll<T, A = Record<string, unknown>>(
+  producer: PollProducer<T, A>,
+  options: PollOptions<T, A>,
+): AsyncGenerator<T, void, void> {
+  const { intervalMs, predicate, signal, attributes, timeoutMs } = options;
+  const controller = new AbortController();
+  if (signal) tieAbortSignal(controller, signal);
+  if (timeoutMs !== undefined) {
+    tieAbortSignal(controller, AbortSignal.timeout(timeoutMs));
+  }
+  // Single shared attributes object so writes from one iteration are
+  // visible on the next. `{} as A` is safe because either the caller
+  // supplied `attributes` (typed) or `A` defaulted to the unknown
+  // record shape (in which case `{}` satisfies it).
+  const sharedAttributes = attributes ?? ({} as A);
+  try {
+    let previous: T | undefined;
+    for (let attempt = 0; ; attempt++) {
+      controller.signal.throwIfAborted();
+      const ctx: PollContext<T, A> = {
+        attempt,
+        previous,
+        signal: controller.signal,
+        attributes: sharedAttributes,
+      };
+      const value = await producer(ctx);
+      if (options.filter) {
+        if (options.filter === "distinct") {
+          if (deepEqual(previous, value)) continue;
+        } else if (!(await options.filter(value, ctx))) continue;
+      }
+      yield value;
+      if (predicate && !(await predicate(value, ctx))) return;
+      await sleep(intervalMs, controller.signal);
+      previous = value;
+    }
+  } finally {
+    controller.abort();
+  }
+}
+
+/**
+ * Tie a child `AbortController` to a parent signal. The child aborts
+ * whenever the parent aborts; aborting the child does not affect the
+ * parent (so a fetch-level cancel doesn't tear down the main poll loop).
+ */
+export function tieAbortSignal(child: AbortController, parent?: AbortSignal): void {
+  if (!parent) return;
+  else if (parent.aborted) {
+    child.abort(parent.reason);
+    return;
+  }
+  parent.addEventListener("abort", () => child.abort(parent.reason), {
+    once: true,
+  });
+}
+
+/**
+ * Promisified `setTimeout` that wakes up early (and rejects with
+ * `signal.reason`) when `signal` aborts mid-wait. Short-circuits to a
+ * rejected promise when the signal is already aborted on entry, so the
+ * abort path is consistent regardless of whether the wait actually
+ * started.
+ *
+ * Use as the building block for any "wait, but cancel cleanly" pattern -
+ * inter-poll backoff, pacing loops, retry timers, long-poll budgets - so
+ * cancellation always rejects with the caller's `signal.reason` rather
+ * than silently resolving after the timer expires.
+ *
+ * @example
+ * await sleep(250, req.signal);
+ */
+export function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+  if (signal?.aborted) return Promise.reject(signal.reason);
+  return new Promise((resolve, reject) => {
+    const onAbort = (): void => {
+      clearTimeout(timer);
+      reject(signal!.reason);
+    };
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}