langsmith 0.10.9 → 0.10.10

package/lib/utils/_uuid.mjs

@@ -0,0 +1,165 @@
+// Relaxed UUID validation regex (allows any valid UUID format including nil UUIDs)
+const UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+import { v7 as uuidv7 } from "./uuid/src/index.mjs";
+import { warnOnce } from "./warn.mjs";
+import { XXH3_128, xxh128ToBytes } from "./xxhash/xxhash.mjs";
+let UUID7_WARNING_EMITTED = false;
+export function assertUuid(str, which) {
+    // Use relaxed regex validation instead of strict uuid.validate()
+    // This allows edge cases like nil UUIDs or test UUIDs that might not pass strict validation
+    if (!UUID_REGEX.test(str)) {
+        const msg = which !== undefined
+            ? `Invalid UUID for ${which}: ${str}`
+            : `Invalid UUID: ${str}`;
+        throw new Error(msg);
+    }
+    return str;
+}
+/**
+ * Generate a UUID v7 from a timestamp.
+ *
+ * @param timestamp - The timestamp in milliseconds
+ * @returns A UUID v7 string
+ */
+export function uuid7FromTime(timestamp) {
+    const msecs = typeof timestamp === "string" ? Date.parse(timestamp) : timestamp;
+    // Work around uuid@10 behavior where providing only { msecs }
+    // may not set the internal timestamp used for stringification.
+    // Providing a seq ensures the implementation updates its internal state
+    // and encodes the provided milliseconds into the UUID bytes.
+    return uuidv7({ msecs, seq: 0 });
+}
+/**
+ * Get the version of a UUID string.
+ * @param uuidStr - The UUID string to check
+ * @returns The version number (1-7) or null if invalid
+ */
+export function getUuidVersion(uuidStr) {
+    if (!UUID_REGEX.test(uuidStr)) {
+        return null;
+    }
+    // Version is in bits 48-51
+    // Format: xxxxxxxx-xxxx-Vxxx-xxxx-xxxxxxxxxxxx
+    const versionChar = uuidStr[14];
+    return parseInt(versionChar, 16);
+}
+/**
+ * Warn if a UUID is not version 7.
+ *
+ * @param uuidStr - The UUID string to check
+ * @param idType - The type of ID (e.g., "run_id", "trace_id") for the warning message
+ */
+export function warnIfNotUuidV7(uuidStr, _idType) {
+    const version = getUuidVersion(uuidStr);
+    if (version !== null && version !== 7 && !UUID7_WARNING_EMITTED) {
+        UUID7_WARNING_EMITTED = true;
+        warnOnce(`LangSmith now uses UUID v7 for run and trace identifiers. ` +
+            `This warning appears when passing custom IDs. ` +
+            `Please use: import { uuidv7 } from 'langsmith'; const id = uuidv7(); ` +
+            `Future versions will require UUID v7.`);
+    }
+}
+/**
+ * Convert a UUID string to its 16-byte representation.
+ * @param uuidStr - The UUID string (with or without dashes)
+ * @returns A Uint8Array containing the 16 bytes of the UUID
+ */
+function uuidToBytes(uuidStr) {
+    const hex = uuidStr.replace(/-/g, "");
+    const bytes = new Uint8Array(16);
+    for (let i = 0; i < 16; i++) {
+        bytes[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+    }
+    return bytes;
+}
+/**
+ * Convert 16 bytes to a UUID string.
+ * @param bytes - A Uint8Array containing 16 bytes
+ * @returns A UUID string in standard format
+ */
+function bytesToUuid(bytes) {
+    const hex = Array.from(bytes)
+        .map((b) => b.toString(16).padStart(2, "0"))
+        .join("");
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+// Reuse TextEncoder instance for performance
+const _textEncoder = new TextEncoder();
+/**
+ * Generates a 16-byte fingerprint for deterministic UUID generation using XXH3-128.
+ *
+ * XXH3 is an extremely fast, non-cryptographic hash function that provides excellent
+ * collision resistance. It's widely used in production systems and compatible with
+ * xxHash implementations in other languages.
+ *
+ * See: https://github.com/Cyan4973/xxHash
+ *
+ * @param str - The input string to hash
+ * @returns A Uint8Array containing 16 bytes of hash output
+ */
+function _fastHash128(str) {
+    const data = _textEncoder.encode(str);
+    // Compute XXH3-128 hash and convert to bytes
+    const hash128 = XXH3_128(data);
+    return xxh128ToBytes(hash128);
+}
+/**
+ * Generate a deterministic UUID v7 derived from an original UUID and a key.
+ *
+ * A pure function of `originalId` and `key`: it reads no ambient state, so the
+ * same pair always yields the same UUID, in any process, at any time. This is
+ * used for creating replica ids that are reproducible across distributed
+ * systems, including across SDK implementations.
+ *
+ * A UUID v7 original keeps its timestamp, so derived ids stay ordered by run
+ * start time. Any other original has none to keep, and the field is
+ * hash-derived: stable, but not chronological.
+ *
+ * @param originalId - The source UUID string (ideally UUID v7 to preserve timestamp)
+ * @param key - A string key used for deterministic derivation (e.g., project name)
+ * @returns A new UUID v7 string with preserved timestamp (if original is v7) and
+ *          deterministic random bits
+ *
+ * @example
+ * ```typescript
+ * const original = uuidv7();
+ * const replicaId = nonCryptographicUuid7Deterministic(original, "replica-project");
+ * // Same inputs always produce same output
+ * assert(nonCryptographicUuid7Deterministic(original, "replica-project") === replicaId);
+ * ```
+ */
+export function nonCryptographicUuid7Deterministic(originalId, key) {
+    // Generate deterministic bytes from hash of original + key
+    const hashInput = `${originalId}:${key}`;
+    const h = _fastHash128(hashInput);
+    // Build new UUID7:
+    // UUID7 structure (RFC 9562):
+    // [0-5]  48 bits: unix_ts_ms (timestamp in milliseconds)
+    // [6]    4 bits: version (0111 = 7) + 4 bits rand_a
+    // [7]    8 bits: rand_a (continued)
+    // [8]    2 bits: variant (10) + 6 bits rand_b
+    // [9-15] 56 bits: rand_b (continued)
+    const b = new Uint8Array(16);
+    const version = getUuidVersion(originalId);
+    if (version === 7) {
+        // Preserve timestamp from original UUID7 (bytes 0-5)
+        const originalBytes = uuidToBytes(originalId);
+        b.set(originalBytes.slice(0, 6), 0);
+    }
+    else {
+        // No timestamp to preserve. Use the six hash bytes left unused below: a
+        // clock read here would make this impure, and the same id is derived
+        // from several runs, all of which must agree.
+        b.set(h.slice(10, 16), 0);
+    }
+    // Set version 7 (0111) in high nibble + 4 bits from hash
+    b[6] = 0x70 | (h[0] & 0x0f);
+    // rand_a continued (8 bits from hash)
+    b[7] = h[1];
+    // Set variant (10) in high 2 bits + 6 bits from hash
+    b[8] = 0x80 | (h[2] & 0x3f);
+    // rand_b (56 bits = 7 bytes from hash)
+    b.set(h.slice(3, 10), 9);
+    return bytesToUuid(b);
+}
+//# sourceMappingURL=_uuid.mjs.map

package/lib/utils/_uuid.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"_uuid.mjs","sourceRoot":"","sources":["../../src/lib/utils/_uuid.ts"],"names":[],"mappings":"AAAA,mFAAmF;AACnF,MAAM,UAAU,GACd,iEAAiE,CAAC;AAEpE,OAAO,EAAE,EAAE,IAAI,MAAM,EAAE,6BAA4B;AACnD,OAAO,EAAE,QAAQ,EAAE,mBAAkB;AACrC,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,4BAA2B;AAE7D,IAAI,qBAAqB,GAAG,KAAK,CAAC;AAElC,MAAM,UAAU,UAAU,CAAC,GAAW,EAAE,KAAc;IACpD,iEAAiE;IACjE,4FAA4F;IAC5F,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QAC1B,MAAM,GAAG,GACP,KAAK,KAAK,SAAS;YACjB,CAAC,CAAC,oBAAoB,KAAK,KAAK,GAAG,EAAE;YACrC,CAAC,CAAC,iBAAiB,GAAG,EAAE,CAAC;QAC7B,MAAM,IAAI,KAAK,CAAC,GAAG,CAAC,CAAC;IACvB,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,SAA0B;IACtD,MAAM,KAAK,GACT,OAAO,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IACpE,8DAA8D;IAC9D,+DAA+D;IAC/D,wEAAwE;IACxE,6DAA6D;IAC7D,OAAO,MAAM,CAAC,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;AACnC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,OAAe;IAC5C,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QAC9B,OAAO,IAAI,CAAC;IACd,CAAC;IAED,2BAA2B;IAC3B,+CAA+C;IAC/C,MAAM,WAAW,GAAG,OAAO,CAAC,EAAE,CAAC,CAAC;IAChC,OAAO,QAAQ,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;AACnC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,OAAe,EAAE,OAAe;IAC9D,MAAM,OAAO,GAAG,cAAc,CAAC,OAAO,CAAC,CAAC;IACxC,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,KAAK,CAAC,IAAI,CAAC,qBAAqB,EAAE,CAAC;QAChE,qBAAqB,GAAG,IAAI,CAAC;QAC7B,QAAQ,CACN,4DAA4D;YAC1D,gDAAgD;YAChD,uEAAuE;YACvE,uCAAuC,CAC1C,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,SAAS,WAAW,CAAC,OAAe;IAClC,MAAM,GAAG,GAAG,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;IACtC,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,EAAE,CAAC,CAAC;IACjC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC;QAC5B,KAAK,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IACvD,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;GAIG;AACH,SAAS,WAAW,CAAC,KAAiB;IACpC,MAAM,GAAG,GAAG,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC;SAC1B,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;SAC3C,IAAI,CAAC,EAAE,CAAC,CAAC;IACZ,OAAO,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,GAAG,CAAC,KAAK,CACxD,EAAE,EACF,EAAE,CACH,IAAI,GAAG,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,CAAC;AAC5C,CAAC;AAED,6CAA6C;AAC7C,MAAM,YAAY,GAAG,IAAI,WAAW,EAAE,CAAC;AAEvC;;;;;;;;;;;GAWG;AACH,SAAS,YAAY,CAAC,GAAW;IAC/B,MAAM,IAAI,GAAG,YAAY,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAEtC,6CAA6C;IAC7C,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;IAC/B,OAAO,aAAa,CAAC,OAAO,CAAC,CAAC;AAChC,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,kCAAkC,CAChD,UAAkB,EAClB,GAAW;IAEX,2DAA2D;IAC3D,MAAM,SAAS,GAAG,GAAG,UAAU,IAAI,GAAG,EAAE,CAAC;IACzC,MAAM,CAAC,GAAG,YAAY,CAAC,SAAS,CAAC,CAAC;IAElC,mBAAmB;IACnB,8BAA8B;IAC9B,yDAAyD;IACzD,oDAAoD;IACpD,oCAAoC;IACpC,8CAA8C;IAC9C,qCAAqC;IAErC,MAAM,CAAC,GAAG,IAAI,UAAU,CAAC,EAAE,CAAC,CAAC;IAE7B,MAAM,OAAO,GAAG,cAAc,CAAC,UAAU,CAAC,CAAC;IAC3C,IAAI,OAAO,KAAK,CAAC,EAAE,CAAC;QAClB,qDAAqD;QACrD,MAAM,aAAa,GAAG,WAAW,CAAC,UAAU,CAAC,CAAC;QAC9C,CAAC,CAAC,GAAG,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACtC,CAAC;SAAM,CAAC;QACN,wEAAwE;QACxE,qEAAqE;QACrE,8CAA8C;QAC9C,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAC5B,CAAC;IAED,yDAAyD;IACzD,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAE5B,sCAAsC;IACtC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IAEZ,qDAAqD;IACrD,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAE5B,uCAAuC;IACvC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAEzB,OAAO,WAAW,CAAC,CAAC,CAAC,CAAC;AACxB,CAAC"}

package/lib/utils/addressing.d.mts

@@ -0,0 +1,28 @@
+import { AgentAddress, EnvAddressError } from "../address.mjs";
+/** One precedence level: the `[project, address]` it names. */
+export type Tier = [string | undefined, AgentAddress | undefined];
+export declare function rejectConflicting(project: unknown, address: unknown): void;
+/** The highest level naming a project or an address, whichever it names. */
+export declare function firstNamed(...tiers: Tier[]): Tier;
+/**
+ * The env's destination: its address, else its project, else "default".
+ * @throws {EnvAddressError} For half an address, or an address and a project.
+ */
+export declare function resolveFromEnv(): Tier;
+export declare function logUntraced(error: EnvAddressError): void;
+/** Warn once, at client construction, if the env can't address runs. */
+export declare function warnOnEnv(): void;
+/**
+ * Put the run's address in its payload field, in its wire form.
+ * Without one, a create naming no project takes the env address.
+ *
+ * @throws {EnvAddressError} If the env names half an address.
+ */
+export declare function applyToPayload(run: {
+    address?: AgentAddress;
+    session_id?: string;
+    session_name?: string;
+}, { update }?: {
+    update?: boolean;
+}): void;
+//# sourceMappingURL=addressing.d.mts.map

package/lib/utils/addressing.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"addressing.d.mts","sourceRoot":"","sources":["../../src/lib/utils/addressing.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,EACZ,eAAe,EAGhB,uBAAsB;AAOvB,+DAA+D;AAC/D,MAAM,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,SAAS,EAAE,YAAY,GAAG,SAAS,CAAC,CAAC;AAElE,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CAO1E;AAED,4EAA4E;AAC5E,wBAAgB,UAAU,CAAC,GAAG,KAAK,EAAE,IAAI,EAAE,GAAG,IAAI,CAQjD;AAUD;;;GAGG;AACH,wBAAgB,cAAc,IAAI,IAAI,CASrC;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI,CAExD;AAED,wEAAwE;AACxE,wBAAgB,SAAS,IAAI,IAAI,CAYhC;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,GAAG,EAAE;IAAE,OAAO,CAAC,EAAE,YAAY,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAAE,EAC3E,EAAE,MAAc,EAAE,GAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAO,GAC5C,IAAI,CAiCN"}

package/lib/utils/addressing.d.ts

@@ -0,0 +1,28 @@
+import { AgentAddress, EnvAddressError } from "../address.js";
+/** One precedence level: the `[project, address]` it names. */
+export type Tier = [string | undefined, AgentAddress | undefined];
+export declare function rejectConflicting(project: unknown, address: unknown): void;
+/** The highest level naming a project or an address, whichever it names. */
+export declare function firstNamed(...tiers: Tier[]): Tier;
+/**
+ * The env's destination: its address, else its project, else "default".
+ * @throws {EnvAddressError} For half an address, or an address and a project.
+ */
+export declare function resolveFromEnv(): Tier;
+export declare function logUntraced(error: EnvAddressError): void;
+/** Warn once, at client construction, if the env can't address runs. */
+export declare function warnOnEnv(): void;
+/**
+ * Put the run's address in its payload field, in its wire form.
+ * Without one, a create naming no project takes the env address.
+ *
+ * @throws {EnvAddressError} If the env names half an address.
+ */
+export declare function applyToPayload(run: {
+    address?: AgentAddress;
+    session_id?: string;
+    session_name?: string;
+}, { update }?: {
+    update?: boolean;
+}): void;
+//# sourceMappingURL=addressing.d.ts.map

package/lib/utils/addressing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"addressing.d.ts","sourceRoot":"","sources":["../../src/lib/utils/addressing.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,EACZ,eAAe,EAGhB,sBAAsB;AAOvB,+DAA+D;AAC/D,MAAM,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,SAAS,EAAE,YAAY,GAAG,SAAS,CAAC,CAAC;AAElE,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CAO1E;AAED,4EAA4E;AAC5E,wBAAgB,UAAU,CAAC,GAAG,KAAK,EAAE,IAAI,EAAE,GAAG,IAAI,CAQjD;AAUD;;;GAGG;AACH,wBAAgB,cAAc,IAAI,IAAI,CASrC;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI,CAExD;AAED,wEAAwE;AACxE,wBAAgB,SAAS,IAAI,IAAI,CAYhC;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,GAAG,EAAE;IAAE,OAAO,CAAC,EAAE,YAAY,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAAE,EAC3E,EAAE,MAAc,EAAE,GAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAO,GAC5C,IAAI,CAiCN"}

package/lib/utils/addressing.js

@@ -0,0 +1,100 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rejectConflicting = rejectConflicting;
+exports.firstNamed = firstNamed;
+exports.resolveFromEnv = resolveFromEnv;
+exports.logUntraced = logUntraced;
+exports.warnOnEnv = warnOnEnv;
+exports.applyToPayload = applyToPayload;
+const address_js_1 = require("../address.js");
+const env_js_1 = require("./env.js");
+const warn_js_1 = require("./warn.js");
+function rejectConflicting(project, address) {
+    if (project && address) {
+        throw new Error(`A run is sent to a project (${JSON.stringify(project)}) or to an ` +
+            "address, not both.");
+    }
+}
+/** The highest level naming a project or an address, whichever it names. */
+function firstNamed(...tiers) {
+    for (const [project, address] of tiers) {
+        rejectConflicting(project, address);
+        if (project || address) {
+            return [project || undefined, address];
+        }
+    }
+    return [undefined, undefined];
+}
+function getEnvProject() {
+    return ((0, env_js_1.getLangSmithEnvironmentVariable)("PROJECT") ||
+        (0, env_js_1.getEnvironmentVariable)("LANGCHAIN_SESSION") ||
+        undefined);
+}
+/**
+ * The env's destination: its address, else its project, else "default".
+ * @throws {EnvAddressError} For half an address, or an address and a project.
+ */
+function resolveFromEnv() {
+    const project = getEnvProject();
+    const address = address_js_1.AgentAddress.fromEnv();
+    if (project && address) {
+        throw new address_js_1.EnvAddressError("LANGSMITH_AGENT_* and a project are both set in the environment.");
+    }
+    return address ? [undefined, address] : [project ?? "default", undefined];
+}
+function logUntraced(error) {
+    (0, warn_js_1.warnOnce)(`LangSmith is not tracing this call: ${error.message}`);
+}
+/** Warn once, at client construction, if the env can't address runs. */
+function warnOnEnv() {
+    if (!(0, address_js_1.envNames)().some((name) => (0, env_js_1.getEnvironmentVariable)(name))) {
+        return;
+    }
+    try {
+        resolveFromEnv();
+    }
+    catch (e) {
+        (0, warn_js_1.warnOnce)(`${e.message} Runs that name no destination in code are ` +
+            "not traced.");
+    }
+}
+/**
+ * Put the run's address in its payload field, in its wire form.
+ * Without one, a create naming no project takes the env address.
+ *
+ * @throws {EnvAddressError} If the env names half an address.
+ */
+function applyToPayload(run, { update = false } = {}) {
+    const payload = run;
+    let address;
+    if (typeof payload.address === "string") {
+        // Wire data already applied: a queued run is applied again when its batch
+        // is sent. It is parsed again, so a malformed one cannot fail the whole
+        // batch in the backend.
+        try {
+            address = address_js_1.AgentAddress._fromLrn(payload.address);
+        }
+        catch {
+            throw new Error("The run's `address` is not a valid agent address.");
+        }
+    }
+    else {
+        address = (0, address_js_1.ensureAgent)(payload.address);
+    }
+    delete payload.address;
+    const namedProject = payload.session_id != null || payload.session_name != null;
+    if (!address && !update && !namedProject) {
+        address = address_js_1.AgentAddress.fromEnv();
+    }
+    if (!address) {
+        return;
+    }
+    (0, warn_js_1.warnOnce)("Sending runs to an `address` is in beta and enabled per workspace; a " +
+        "workspace without it rejects the runs.");
+    payload.address = address._toLrn();
+    if (!namedProject) {
+        delete payload.session_name;
+        delete payload.session_id;
+    }
+}
+//# sourceMappingURL=addressing.js.map

package/lib/utils/addressing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"addressing.js","sourceRoot":"","sources":["../../src/lib/utils/addressing.ts"],"names":[],"mappings":"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"}

package/lib/utils/addressing.mjs

@@ -0,0 +1,92 @@
+import { AgentAddress, EnvAddressError, ensureAgent, envNames, } from "../address.mjs";
+import { getEnvironmentVariable, getLangSmithEnvironmentVariable, } from "./env.mjs";
+import { warnOnce } from "./warn.mjs";
+export function rejectConflicting(project, address) {
+    if (project && address) {
+        throw new Error(`A run is sent to a project (${JSON.stringify(project)}) or to an ` +
+            "address, not both.");
+    }
+}
+/** The highest level naming a project or an address, whichever it names. */
+export function firstNamed(...tiers) {
+    for (const [project, address] of tiers) {
+        rejectConflicting(project, address);
+        if (project || address) {
+            return [project || undefined, address];
+        }
+    }
+    return [undefined, undefined];
+}
+function getEnvProject() {
+    return (getLangSmithEnvironmentVariable("PROJECT") ||
+        getEnvironmentVariable("LANGCHAIN_SESSION") ||
+        undefined);
+}
+/**
+ * The env's destination: its address, else its project, else "default".
+ * @throws {EnvAddressError} For half an address, or an address and a project.
+ */
+export function resolveFromEnv() {
+    const project = getEnvProject();
+    const address = AgentAddress.fromEnv();
+    if (project && address) {
+        throw new EnvAddressError("LANGSMITH_AGENT_* and a project are both set in the environment.");
+    }
+    return address ? [undefined, address] : [project ?? "default", undefined];
+}
+export function logUntraced(error) {
+    warnOnce(`LangSmith is not tracing this call: ${error.message}`);
+}
+/** Warn once, at client construction, if the env can't address runs. */
+export function warnOnEnv() {
+    if (!envNames().some((name) => getEnvironmentVariable(name))) {
+        return;
+    }
+    try {
+        resolveFromEnv();
+    }
+    catch (e) {
+        warnOnce(`${e.message} Runs that name no destination in code are ` +
+            "not traced.");
+    }
+}
+/**
+ * Put the run's address in its payload field, in its wire form.
+ * Without one, a create naming no project takes the env address.
+ *
+ * @throws {EnvAddressError} If the env names half an address.
+ */
+export function applyToPayload(run, { update = false } = {}) {
+    const payload = run;
+    let address;
+    if (typeof payload.address === "string") {
+        // Wire data already applied: a queued run is applied again when its batch
+        // is sent. It is parsed again, so a malformed one cannot fail the whole
+        // batch in the backend.
+        try {
+            address = AgentAddress._fromLrn(payload.address);
+        }
+        catch {
+            throw new Error("The run's `address` is not a valid agent address.");
+        }
+    }
+    else {
+        address = ensureAgent(payload.address);
+    }
+    delete payload.address;
+    const namedProject = payload.session_id != null || payload.session_name != null;
+    if (!address && !update && !namedProject) {
+        address = AgentAddress.fromEnv();
+    }
+    if (!address) {
+        return;
+    }
+    warnOnce("Sending runs to an `address` is in beta and enabled per workspace; a " +
+        "workspace without it rejects the runs.");
+    payload.address = address._toLrn();
+    if (!namedProject) {
+        delete payload.session_name;
+        delete payload.session_id;
+    }
+}
+//# sourceMappingURL=addressing.mjs.map

package/lib/utils/addressing.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"addressing.mjs","sourceRoot":"","sources":["../../src/lib/utils/addressing.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,EACZ,eAAe,EACf,WAAW,EACX,QAAQ,GACT,uBAAsB;AACvB,OAAO,EACL,sBAAsB,EACtB,+BAA+B,GAChC,kBAAiB;AAClB,OAAO,EAAE,QAAQ,EAAE,mBAAkB;AAKrC,MAAM,UAAU,iBAAiB,CAAC,OAAgB,EAAE,OAAgB;IAClE,IAAI,OAAO,IAAI,OAAO,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CACb,+BAA+B,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,aAAa;YACjE,oBAAoB,CACvB,CAAC;IACJ,CAAC;AACH,CAAC;AAED,4EAA4E;AAC5E,MAAM,UAAU,UAAU,CAAC,GAAG,KAAa;IACzC,KAAK,MAAM,CAAC,OAAO,EAAE,OAAO,CAAC,IAAI,KAAK,EAAE,CAAC;QACvC,iBAAiB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACpC,IAAI,OAAO,IAAI,OAAO,EAAE,CAAC;YACvB,OAAO,CAAC,OAAO,IAAI,SAAS,EAAE,OAAO,CAAC,CAAC;QACzC,CAAC;IACH,CAAC;IACD,OAAO,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;AAChC,CAAC;AAED,SAAS,aAAa;IACpB,OAAO,CACL,+BAA+B,CAAC,SAAS,CAAC;QAC1C,sBAAsB,CAAC,mBAAmB,CAAC;QAC3C,SAAS,CACV,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,cAAc;IAC5B,MAAM,OAAO,GAAG,aAAa,EAAE,CAAC;IAChC,MAAM,OAAO,GAAG,YAAY,CAAC,OAAO,EAAE,CAAC;IACvC,IAAI,OAAO,IAAI,OAAO,EAAE,CAAC;QACvB,MAAM,IAAI,eAAe,CACvB,kEAAkE,CACnE,CAAC;IACJ,CAAC;IACD,OAAO,OAAO,CAAC,CAAC,CAAC,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,IAAI,SAAS,EAAE,SAAS,CAAC,CAAC;AAC5E,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,KAAsB;IAChD,QAAQ,CAAC,uCAAuC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;AACnE,CAAC;AAED,wEAAwE;AACxE,MAAM,UAAU,SAAS;IACvB,IAAI,CAAC,QAAQ,EAAE,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,sBAAsB,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC;QAC7D,OAAO;IACT,CAAC;IACD,IAAI,CAAC;QACH,cAAc,EAAE,CAAC;IACnB,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,QAAQ,CACN,GAAI,CAAW,CAAC,OAAO,6CAA6C;YAClE,aAAa,CAChB,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAC5B,GAA2E,EAC3E,EAAE,MAAM,GAAG,KAAK,KAA2B,EAAE;IAE7C,MAAM,OAAO,GAAG,GAA8B,CAAC;IAC/C,IAAI,OAAiC,CAAC;IACtC,IAAI,OAAO,OAAO,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC;QACxC,0EAA0E;QAC1E,wEAAwE;QACxE,wBAAwB;QACxB,IAAI,CAAC;YACH,OAAO,GAAG,YAAY,CAAC,QAAQ,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QACnD,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,IAAI,KAAK,CAAC,mDAAmD,CAAC,CAAC;QACvE,CAAC;IACH,CAAC;SAAM,CAAC;QACN,OAAO,GAAG,WAAW,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IACzC,CAAC;IACD,OAAO,OAAO,CAAC,OAAO,CAAC;IACvB,MAAM,YAAY,GAChB,OAAO,CAAC,UAAU,IAAI,IAAI,IAAI,OAAO,CAAC,YAAY,IAAI,IAAI,CAAC;IAC7D,IAAI,CAAC,OAAO,IAAI,CAAC,MAAM,IAAI,CAAC,YAAY,EAAE,CAAC;QACzC,OAAO,GAAG,YAAY,CAAC,OAAO,EAAE,CAAC;IACnC,CAAC;IACD,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO;IACT,CAAC;IACD,QAAQ,CACN,uEAAuE;QACrE,wCAAwC,CAC3C,CAAC;IACF,OAAO,CAAC,OAAO,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IACnC,IAAI,CAAC,YAAY,EAAE,CAAC;QAClB,OAAO,OAAO,CAAC,YAAY,CAAC;QAC5B,OAAO,OAAO,CAAC,UAAU,CAAC;IAC5B,CAAC;AACH,CAAC"}

package/lib/utils/asserts.d.mts

@@ -0,0 +1,8 @@
+export declare function isPromiseMethod(x: string | symbol): x is "then" | "catch" | "finally";
+export declare function isKVMap(x: unknown): x is Record<string, unknown>;
+export declare const isAsyncIterable: (x: unknown) => x is AsyncIterable<unknown>;
+export declare const isIteratorLike: (x: unknown) => x is Iterator<unknown>;
+export declare const isGenerator: (x: unknown) => x is Generator;
+export declare const isThenable: (x: unknown) => x is Promise<unknown>;
+export declare const isReadableStream: (x: unknown) => x is ReadableStream;
+//# sourceMappingURL=asserts.d.mts.map

package/lib/utils/asserts.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"asserts.d.mts","sourceRoot":"","sources":["../../src/lib/utils/asserts.ts"],"names":[],"mappings":"AAAA,wBAAgB,eAAe,CAC7B,CAAC,EAAE,MAAM,GAAG,MAAM,GACjB,CAAC,IAAI,MAAM,GAAG,OAAO,GAAG,SAAS,CAKnC;AAED,wBAAgB,OAAO,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAahE;AACD,eAAO,MAAM,eAAe,GAAI,GAAG,OAAO,KAAG,CAAC,IAAI,aAAa,CAAC,OAAO,CAIf,CAAC;AAEzD,eAAO,MAAM,cAAc,GAAI,GAAG,OAAO,KAAG,CAAC,IAAI,QAAQ,CAAC,OAAO,CAInC,CAAC;AAG/B,eAAO,MAAM,WAAW,GAAI,GAAG,OAAO,KAAG,CAAC,IAAI,SAC0B,CAAC;AAEzE,eAAO,MAAM,UAAU,GAAI,GAAG,OAAO,KAAG,CAAC,IAAI,OAAO,CAAC,OAAO,CAI9B,CAAC;AAE/B,eAAO,MAAM,gBAAgB,GAAI,GAAG,OAAO,KAAG,CAAC,IAAI,cAIhB,CAAC"}

package/lib/utils/asserts.d.ts

@@ -0,0 +1,8 @@
+export declare function isPromiseMethod(x: string | symbol): x is "then" | "catch" | "finally";
+export declare function isKVMap(x: unknown): x is Record<string, unknown>;
+export declare const isAsyncIterable: (x: unknown) => x is AsyncIterable<unknown>;
+export declare const isIteratorLike: (x: unknown) => x is Iterator<unknown>;
+export declare const isGenerator: (x: unknown) => x is Generator;
+export declare const isThenable: (x: unknown) => x is Promise<unknown>;
+export declare const isReadableStream: (x: unknown) => x is ReadableStream;
+//# sourceMappingURL=asserts.d.ts.map

package/lib/utils/asserts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"asserts.d.ts","sourceRoot":"","sources":["../../src/lib/utils/asserts.ts"],"names":[],"mappings":"AAAA,wBAAgB,eAAe,CAC7B,CAAC,EAAE,MAAM,GAAG,MAAM,GACjB,CAAC,IAAI,MAAM,GAAG,OAAO,GAAG,SAAS,CAKnC;AAED,wBAAgB,OAAO,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAahE;AACD,eAAO,MAAM,eAAe,GAAI,GAAG,OAAO,KAAG,CAAC,IAAI,aAAa,CAAC,OAAO,CAIf,CAAC;AAEzD,eAAO,MAAM,cAAc,GAAI,GAAG,OAAO,KAAG,CAAC,IAAI,QAAQ,CAAC,OAAO,CAInC,CAAC;AAG/B,eAAO,MAAM,WAAW,GAAI,GAAG,OAAO,KAAG,CAAC,IAAI,SAC0B,CAAC;AAEzE,eAAO,MAAM,UAAU,GAAI,GAAG,OAAO,KAAG,CAAC,IAAI,OAAO,CAAC,OAAO,CAI9B,CAAC;AAE/B,eAAO,MAAM,gBAAgB,GAAI,GAAG,OAAO,KAAG,CAAC,IAAI,cAIhB,CAAC"}

package/lib/utils/asserts.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isReadableStream = exports.isThenable = exports.isGenerator = exports.isIteratorLike = exports.isAsyncIterable = void 0;
+exports.isPromiseMethod = isPromiseMethod;
+exports.isKVMap = isKVMap;
+function isPromiseMethod(x) {
+    if (x === "then" || x === "catch" || x === "finally") {
+        return true;
+    }
+    return false;
+}
+function isKVMap(x) {
+    if (typeof x !== "object" || x == null) {
+        return false;
+    }
+    const prototype = Object.getPrototypeOf(x);
+    return ((prototype === null ||
+        prototype === Object.prototype ||
+        Object.getPrototypeOf(prototype) === null) &&
+        !(Symbol.toStringTag in x) &&
+        !(Symbol.iterator in x));
+}
+const isAsyncIterable = (x) => x != null &&
+    typeof x === "object" &&
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    typeof x[Symbol.asyncIterator] === "function";
+exports.isAsyncIterable = isAsyncIterable;
+const isIteratorLike = (x) => x != null &&
+    typeof x === "object" &&
+    "next" in x &&
+    typeof x.next === "function";
+exports.isIteratorLike = isIteratorLike;
+const GeneratorFunction = function* () { }.constructor;
+const isGenerator = (x) => x != null && typeof x === "function" && x instanceof GeneratorFunction;
+exports.isGenerator = isGenerator;
+const isThenable = (x) => x != null &&
+    typeof x === "object" &&
+    "then" in x &&
+    typeof x.then === "function";
+exports.isThenable = isThenable;
+const isReadableStream = (x) => x != null &&
+    typeof x === "object" &&
+    "getReader" in x &&
+    typeof x.getReader === "function";
+exports.isReadableStream = isReadableStream;
+//# sourceMappingURL=asserts.js.map

package/lib/utils/asserts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"asserts.js","sourceRoot":"","sources":["../../src/lib/utils/asserts.ts"],"names":[],"mappings":";;;AAAA,0CAOC;AAED,0BAaC;AAtBD,SAAgB,eAAe,CAC7B,CAAkB;IAElB,IAAI,CAAC,KAAK,MAAM,IAAI,CAAC,KAAK,OAAO,IAAI,CAAC,KAAK,SAAS,EAAE,CAAC;QACrD,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAgB,OAAO,CAAC,CAAU;IAChC,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,IAAI,IAAI,EAAE,CAAC;QACvC,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,SAAS,GAAG,MAAM,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC;IAC3C,OAAO,CACL,CAAC,SAAS,KAAK,IAAI;QACjB,SAAS,KAAK,MAAM,CAAC,SAAS;QAC9B,MAAM,CAAC,cAAc,CAAC,SAAS,CAAC,KAAK,IAAI,CAAC;QAC5C,CAAC,CAAC,MAAM,CAAC,WAAW,IAAI,CAAC,CAAC;QAC1B,CAAC,CAAC,MAAM,CAAC,QAAQ,IAAI,CAAC,CAAC,CACxB,CAAC;AACJ,CAAC;AACM,MAAM,eAAe,GAAG,CAAC,CAAU,EAA+B,EAAE,CACzE,CAAC,IAAI,IAAI;IACT,OAAO,CAAC,KAAK,QAAQ;IACrB,8DAA8D;IAC9D,OAAQ,CAAS,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,UAAU,CAAC;AAJ5C,QAAA,eAAe,mBAI6B;AAElD,MAAM,cAAc,GAAG,CAAC,CAAU,EAA0B,EAAE,CACnE,CAAC,IAAI,IAAI;IACT,OAAO,CAAC,KAAK,QAAQ;IACrB,MAAM,IAAI,CAAC;IACX,OAAO,CAAC,CAAC,IAAI,KAAK,UAAU,CAAC;AAJlB,QAAA,cAAc,kBAII;AAE/B,MAAM,iBAAiB,GAAG,QAAQ,CAAC,MAAK,CAAC,CAAC,WAAW,CAAC;AAC/C,MAAM,WAAW,GAAG,CAAC,CAAU,EAAkB,EAAE,CACxD,CAAC,IAAI,IAAI,IAAI,OAAO,CAAC,KAAK,UAAU,IAAI,CAAC,YAAY,iBAAiB,CAAC;AAD5D,QAAA,WAAW,eACiD;AAElE,MAAM,UAAU,GAAG,CAAC,CAAU,EAAyB,EAAE,CAC9D,CAAC,IAAI,IAAI;IACT,OAAO,CAAC,KAAK,QAAQ;IACrB,MAAM,IAAI,CAAC;IACX,OAAO,CAAC,CAAC,IAAI,KAAK,UAAU,CAAC;AAJlB,QAAA,UAAU,cAIQ;AAExB,MAAM,gBAAgB,GAAG,CAAC,CAAU,EAAuB,EAAE,CAClE,CAAC,IAAI,IAAI;IACT,OAAO,CAAC,KAAK,QAAQ;IACrB,WAAW,IAAI,CAAC;IAChB,OAAO,CAAC,CAAC,SAAS,KAAK,UAAU,CAAC;AAJvB,QAAA,gBAAgB,oBAIO"}

package/lib/utils/asserts.mjs

@@ -0,0 +1,36 @@
+export function isPromiseMethod(x) {
+    if (x === "then" || x === "catch" || x === "finally") {
+        return true;
+    }
+    return false;
+}
+export function isKVMap(x) {
+    if (typeof x !== "object" || x == null) {
+        return false;
+    }
+    const prototype = Object.getPrototypeOf(x);
+    return ((prototype === null ||
+        prototype === Object.prototype ||
+        Object.getPrototypeOf(prototype) === null) &&
+        !(Symbol.toStringTag in x) &&
+        !(Symbol.iterator in x));
+}
+export const isAsyncIterable = (x) => x != null &&
+    typeof x === "object" &&
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    typeof x[Symbol.asyncIterator] === "function";
+export const isIteratorLike = (x) => x != null &&
+    typeof x === "object" &&
+    "next" in x &&
+    typeof x.next === "function";
+const GeneratorFunction = function* () { }.constructor;
+export const isGenerator = (x) => x != null && typeof x === "function" && x instanceof GeneratorFunction;
+export const isThenable = (x) => x != null &&
+    typeof x === "object" &&
+    "then" in x &&
+    typeof x.then === "function";
+export const isReadableStream = (x) => x != null &&
+    typeof x === "object" &&
+    "getReader" in x &&
+    typeof x.getReader === "function";
+//# sourceMappingURL=asserts.mjs.map

package/lib/utils/asserts.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"asserts.mjs","sourceRoot":"","sources":["../../src/lib/utils/asserts.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,eAAe,CAC7B,CAAkB;IAElB,IAAI,CAAC,KAAK,MAAM,IAAI,CAAC,KAAK,OAAO,IAAI,CAAC,KAAK,SAAS,EAAE,CAAC;QACrD,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,UAAU,OAAO,CAAC,CAAU;IAChC,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,IAAI,IAAI,EAAE,CAAC;QACvC,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,SAAS,GAAG,MAAM,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC;IAC3C,OAAO,CACL,CAAC,SAAS,KAAK,IAAI;QACjB,SAAS,KAAK,MAAM,CAAC,SAAS;QAC9B,MAAM,CAAC,cAAc,CAAC,SAAS,CAAC,KAAK,IAAI,CAAC;QAC5C,CAAC,CAAC,MAAM,CAAC,WAAW,IAAI,CAAC,CAAC;QAC1B,CAAC,CAAC,MAAM,CAAC,QAAQ,IAAI,CAAC,CAAC,CACxB,CAAC;AACJ,CAAC;AACD,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAU,EAA+B,EAAE,CACzE,CAAC,IAAI,IAAI;IACT,OAAO,CAAC,KAAK,QAAQ;IACrB,8DAA8D;IAC9D,OAAQ,CAAS,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,UAAU,CAAC;AAEzD,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAU,EAA0B,EAAE,CACnE,CAAC,IAAI,IAAI;IACT,OAAO,CAAC,KAAK,QAAQ;IACrB,MAAM,IAAI,CAAC;IACX,OAAO,CAAC,CAAC,IAAI,KAAK,UAAU,CAAC;AAE/B,MAAM,iBAAiB,GAAG,QAAQ,CAAC,MAAK,CAAC,CAAC,WAAW,CAAC;AACtD,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,CAAU,EAAkB,EAAE,CACxD,CAAC,IAAI,IAAI,IAAI,OAAO,CAAC,KAAK,UAAU,IAAI,CAAC,YAAY,iBAAiB,CAAC;AAEzE,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,CAAU,EAAyB,EAAE,CAC9D,CAAC,IAAI,IAAI;IACT,OAAO,CAAC,KAAK,QAAQ;IACrB,MAAM,IAAI,CAAC;IACX,OAAO,CAAC,CAAC,IAAI,KAAK,UAAU,CAAC;AAE/B,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAU,EAAuB,EAAE,CAClE,CAAC,IAAI,IAAI;IACT,OAAO,CAAC,KAAK,QAAQ;IACrB,WAAW,IAAI,CAAC;IAChB,OAAO,CAAC,CAAC,SAAS,KAAK,UAAU,CAAC"}

package/lib/utils/async_caller.d.mts

@@ -0,0 +1,56 @@
+import { PQueueType } from "./p-queue.mjs";
+type ResponseCallback = (response?: Response) => Promise<boolean>;
+export interface AsyncCallerParams {
+    /**
+     * The maximum number of concurrent calls that can be made.
+     * Defaults to `Infinity`, which means no limit.
+     */
+    maxConcurrency?: number;
+    /**
+     * The maximum number of retries that can be made for a single call,
+     * with an exponential backoff between each attempt. Defaults to 6.
+     */
+    maxRetries?: number;
+    /**
+     * The maximum size of the queue buffer in bytes. When the queue reaches this size,
+     * new calls will be dropped instead of queued.
+     * If not specified, no limit is enforced.
+     */
+    maxQueueSizeBytes?: number;
+    onFailedResponseHook?: ResponseCallback;
+    debug?: boolean;
+}
+export interface AsyncCallerCallOptions {
+    signal?: AbortSignal;
+    /**
+     * The size of this call in bytes, used for queue size tracking.
+     * If not provided, size tracking is skipped for this call.
+     */
+    sizeBytes?: number;
+}
+/**
+ * A class that can be used to make async calls with concurrency and retry logic.
+ *
+ * This is useful for making calls to any kind of "expensive" external resource,
+ * be it because it's rate-limited, subject to network issues, etc.
+ *
+ * Concurrent calls are limited by the `maxConcurrency` parameter, which defaults
+ * to `Infinity`. This means that by default, all calls will be made in parallel.
+ *
+ * Retries are limited by the `maxRetries` parameter, which defaults to 6. This
+ * means that by default, each call will be retried up to 6 times, with an
+ * exponential backoff between each attempt.
+ */
+export declare class AsyncCaller {
+    protected maxConcurrency: AsyncCallerParams["maxConcurrency"];
+    protected maxRetries: AsyncCallerParams["maxRetries"];
+    protected maxQueueSizeBytes: AsyncCallerParams["maxQueueSizeBytes"];
+    queue: PQueueType;
+    private onFailedResponseHook?;
+    private queueSizeBytes;
+    constructor(params: AsyncCallerParams);
+    call<A extends any[], T extends (...args: A) => Promise<any>>(callable: T, ...args: Parameters<T>): Promise<Awaited<ReturnType<T>>>;
+    callWithOptions<A extends any[], T extends (...args: A) => Promise<any>>(options: AsyncCallerCallOptions, callable: T, ...args: Parameters<T>): Promise<Awaited<ReturnType<T>>>;
+}
+export {};
+//# sourceMappingURL=async_caller.d.mts.map

package/lib/utils/async_caller.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"async_caller.d.mts","sourceRoot":"","sources":["../../src/lib/utils/async_caller.ts"],"names":[],"mappings":"AACA,OAAO,EAAU,UAAU,EAAE,sBAAqB;AAYlD,KAAK,gBAAgB,GAAG,CAAC,QAAQ,CAAC,EAAE,QAAQ,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAElE,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAE3B,oBAAoB,CAAC,EAAE,gBAAgB,CAAC;IAExC,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,sBAAsB;IACrC,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,WAAW;IACtB,SAAS,CAAC,cAAc,EAAE,iBAAiB,CAAC,gBAAgB,CAAC,CAAC;IAE9D,SAAS,CAAC,UAAU,EAAE,iBAAiB,CAAC,YAAY,CAAC,CAAC;IAEtD,SAAS,CAAC,iBAAiB,EAAE,iBAAiB,CAAC,mBAAmB,CAAC,CAAC;IAEpE,KAAK,EAAE,UAAU,CAAC;IAElB,OAAO,CAAC,oBAAoB,CAAC,CAAmB;IAEhD,OAAO,CAAC,cAAc,CAAK;gBAEf,MAAM,EAAE,iBAAiB;IAUrC,IAAI,CAAC,CAAC,SAAS,GAAG,EAAE,EAAE,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,GAAG,CAAC,EAC1D,QAAQ,EAAE,CAAC,EACX,GAAG,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,GACrB,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;IAKlC,eAAe,CAAC,CAAC,SAAS,GAAG,EAAE,EAAE,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,GAAG,CAAC,EACrE,OAAO,EAAE,sBAAsB,EAC/B,QAAQ,EAAE,CAAC,EACX,GAAG,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,GACrB,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;CA8GnC"}