@dbx-tools/shared 0.1.18 → 0.1.20

package/README.md

@@ -172,7 +172,7 @@ const name = await projectUtils.name();
 projectUtils.parseGitRemote("git@github.com:org/my-repo.git"); // "my-repo"
 ```
 
-## `commonUtils` - memoize + hashing
+## `commonUtils` - memoize, ids, hashing, polling, error messages
 
 ```ts
 import { commonUtils } from "@dbx-tools/shared";
@@ -180,11 +180,24 @@ import { commonUtils } from "@dbx-tools/shared";
 // Memoize by all-args; sync results cache forever, async failures bust.
 const fetchUser = commonUtils.memoize(async (id: string) => loadUser(id));
 
+// Marker-friendly short id (default 8 hex chars from a v4 UUID).
+// Safe within a single conversation / job / batch. Use a full UUID
+// when global uniqueness is needed.
+commonUtils.shortId(); // e.g. "a3f1c92b"
+
 // Short, deterministic hash for cache keys / slug suffixes / etc.
 // Pure-JS FNV-1a in Crockford-style base-32 (digits + lowercase
 // alphabet minus i/l/o/u). Browser-safe.
 commonUtils.fnvHash("databricks-claude-sonnet-4-6"); // e.g. "k3p9q7"
 commonUtils.fnvHashWithOptions({ length: 4 }, "user@example.com");
+
+// Poll an async fn until it returns truthy or the timeout fires.
+await commonUtils.poll(() => isReady(), { intervalMs: 250, timeoutMs: 30_000 });
+
+// Pull a printable message out of any thrown value. Folds the
+// `err instanceof Error ? err.message : String(err)` dance into
+// one helper for log attributes and similar contexts.
+log.warn("write:error", { error: commonUtils.errorMessage(err) });
 ```
 
 `@memoized` is a TC39 stage-1 method decorator built on the same

package/dist/src/api.js

@@ -130,10 +130,6 @@ export function toContext(source, input) {
  * `cancellationToken.onCancellationRequested` to it, so this
  * adapter is the one-line bridge from "platform-standard
  * cancellation" to "the SDK aborts the fetch on your behalf".
- *
- * Kept private for now: the genie package is the only consumer in
- * the workspace. Lift to `@dbx-tools/shared` (`apiUtils`) the
- * moment a second package needs SDK-call cancellation.
  */
 function signalToCancellationToken(signal) {
     return {

package/dist/src/common.d.ts

@@ -175,6 +175,21 @@ export declare function tieAbortSignal(child: AbortController, parent?: AbortSig
  * globally unique, use a full UUID instead.
  */
 export declare function shortId(length?: number): string;
+/**
+ * Extract a human-readable message from any thrown value. Returns
+ * `value.message` when `value` is an `Error`, otherwise coerces
+ * via `String(value)`. Collapses the ubiquitous
+ *
+ * ```ts
+ * err instanceof Error ? err.message : String(err)
+ * ```
+ *
+ * dance into a single helper, useful for log attributes and any
+ * other "give me something printable" context where the caller
+ * doesn't want to re-throw or rely on `console.error`'s default
+ * formatting.
+ */
+export declare function errorMessage(value: unknown): string;
 export declare function fnvHash(...values: string[]): string;
 export declare function fnvHashWithOptions(options?: {
     length?: number;

package/dist/src/common.js

@@ -205,6 +205,23 @@ function sleep(ms, signal) {
 export function shortId(length = 8) {
     return globalThis.crypto.randomUUID().replace(/-/g, "").slice(0, length);
 }
+/**
+ * Extract a human-readable message from any thrown value. Returns
+ * `value.message` when `value` is an `Error`, otherwise coerces
+ * via `String(value)`. Collapses the ubiquitous
+ *
+ * ```ts
+ * err instanceof Error ? err.message : String(err)
+ * ```
+ *
+ * dance into a single helper, useful for log attributes and any
+ * other "give me something printable" context where the caller
+ * doesn't want to re-throw or rely on `console.error`'s default
+ * formatting.
+ */
+export function errorMessage(value) {
+    return value instanceof Error ? value.message : String(value);
+}
 export function fnvHash(...values) {
     return fnvHashWithOptions({}, ...values);
 }