@boundaryml/baml-bridge 0.0.0 → 0.13.1-nightly.20260707.e

package/dist/native.d.ts

@@ -0,0 +1,312 @@
+/**
+ * THIS FILE IS AUTO-GENERATED — DO NOT EDIT BY HAND.
+ *
+ * Source: baml_language/crates/bridge_nodejs/typescript_src/
+ * Proto:  baml_language/crates/bridge_ctypes/types/baml_bridge/cffi/v1/*.proto
+ * Build:  cd baml_language/crates/bridge_nodejs && pnpm build:debug
+ */
+/* auto-generated by NAPI-RS */
+/* eslint-disable */
+export declare class BamlAudio {
+  static fromUrl(url: string, mimeType?: string | undefined | null): BamlAudio
+  static fromFile(file: string, mimeType?: string | undefined | null): BamlAudio
+  static fromBase64(base64: string, mimeType?: string | undefined | null): BamlAudio
+  url(): string | null
+  file(): string | null
+  base64(): string
+  mimeType(): string | null
+  /**
+   * Internal: build from an existing `BamlHandle`. Used by proto
+   * decode. Validates the handle's `handle_type` tag matches the
+   * expected media kind, then clones the table row so the input
+   * handle stays usable.
+   */
+  static _fromHandle(handle: BamlHandle): BamlAudio
+  /**
+   * Internal: produce a fresh `BamlHandle` pointing at the same
+   * table row (cloned). Used by inbound encode.
+   */
+  _toHandle(): BamlHandle
+}
+
+/** A call context for cancelling BAML function calls. */
+export declare class BamlCallContext {
+  constructor()
+  abort(): void
+  get aborted(): boolean
+  _attachCallId(callId: string): void
+  _detachCallId(callId: string): void
+}
+
+/**
+ * Base class for all opaque BAML handles.
+ *
+ * When the Node.js garbage collector finalizes an instance, `finalize`
+ * releases the corresponding entry from the global handle table.
+ */
+export declare class BamlHandle {
+  constructor(key: HandleKey, handleType: number)
+  get key(): HandleKey
+  get handleType(): number
+  clone(): BamlHandle
+  _cloneKeyForWire(): HandleKey
+}
+
+export declare class BamlImage {
+  static fromUrl(url: string, mimeType?: string | undefined | null): BamlImage
+  static fromFile(file: string, mimeType?: string | undefined | null): BamlImage
+  static fromBase64(base64: string, mimeType?: string | undefined | null): BamlImage
+  url(): string | null
+  file(): string | null
+  base64(): string
+  mimeType(): string | null
+  /**
+   * Internal: build from an existing `BamlHandle`. Used by proto
+   * decode. Validates the handle's `handle_type` tag matches the
+   * expected media kind, then clones the table row so the input
+   * handle stays usable.
+   */
+  static _fromHandle(handle: BamlHandle): BamlImage
+  /**
+   * Internal: produce a fresh `BamlHandle` pointing at the same
+   * table row (cloned). Used by inbound encode.
+   */
+  _toHandle(): BamlHandle
+}
+
+export declare class BamlPdf {
+  static fromUrl(url: string, mimeType?: string | undefined | null): BamlPdf
+  static fromFile(file: string, mimeType?: string | undefined | null): BamlPdf
+  static fromBase64(base64: string, mimeType?: string | undefined | null): BamlPdf
+  url(): string | null
+  file(): string | null
+  base64(): string
+  mimeType(): string | null
+  /**
+   * Internal: build from an existing `BamlHandle`. Used by proto
+   * decode. Validates the handle's `handle_type` tag matches the
+   * expected media kind, then clones the table row so the input
+   * handle stays usable.
+   */
+  static _fromHandle(handle: BamlHandle): BamlPdf
+  /**
+   * Internal: produce a fresh `BamlHandle` pointing at the same
+   * table row (cloned). Used by inbound encode.
+   */
+  _toHandle(): BamlHandle
+}
+
+/** The main BAML runtime. A zero-sized handle (see module docs). */
+export declare class BamlRuntime {
+  /**
+   * Initialize the process-global runtime from in-memory BAML source
+   * files. `bridge_cffi::initialize_runtime` is a single-slot singleton, so
+   * a second call replaces the prior runtime; the result is also reachable
+   * via the module-level `getRuntime()`. Renamed from `fromFiles` for
+   * parity with `bridge_python`'s sole `initialize_runtime` constructor and
+   * the `initializeRuntime(...)` import the spec docs use.
+   */
+  static initializeRuntime(rootPath: string, files: Record<string, string>): BamlRuntime
+  /** Initialize the process-global runtime from precompiled BAML bytecode. */
+  static initializeRuntimeFromBytecode(bytecode: Buffer): BamlRuntime
+  /** Call a BAML function synchronously (blocking). */
+  callFunctionSync(functionName: string, argsProto: Buffer, ctx?: HostSpanManager | undefined | null, collectors?: Array<Collector> | undefined | null): Buffer
+  /** Call a BAML function asynchronously. */
+  callFunction(functionName: string, argsProto: Buffer, ctx?: HostSpanManager | undefined | null, collectors?: Array<Collector> | undefined | null): Promise<Buffer>
+}
+
+export declare class BamlVideo {
+  static fromUrl(url: string, mimeType?: string | undefined | null): BamlVideo
+  static fromFile(file: string, mimeType?: string | undefined | null): BamlVideo
+  static fromBase64(base64: string, mimeType?: string | undefined | null): BamlVideo
+  url(): string | null
+  file(): string | null
+  base64(): string
+  mimeType(): string | null
+  /**
+   * Internal: build from an existing `BamlHandle`. Used by proto
+   * decode. Validates the handle's `handle_type` tag matches the
+   * expected media kind, then clones the table row so the input
+   * handle stays usable.
+   */
+  static _fromHandle(handle: BamlHandle): BamlVideo
+  /**
+   * Internal: produce a fresh `BamlHandle` pointing at the same
+   * table row (cloned). Used by inbound encode.
+   */
+  _toHandle(): BamlHandle
+}
+
+export declare class Collector {
+  constructor(name?: string | undefined | null)
+  get name(): string
+  get logs(): Array<FunctionLog>
+  get last(): FunctionLog | null
+  get usage(): Usage
+  clear(): number
+  id(functionLogId: string): FunctionLog | null
+}
+
+export declare class FunctionLog {
+  get id(): string
+  get functionName(): string
+  get timing(): Timing
+  get usage(): Usage
+  get calls(): Array<LLMCall>
+  get tags(): Record<string, string>
+  get result(): Buffer | null
+}
+
+export declare class HostSpanManager {
+  constructor()
+  enter(name: string, args: any): void
+  exitOk(): void
+  exitError(errorMessage: string): void
+  upsertTags(tags: Record<string, string>): void
+  deepClone(): HostSpanManager
+  contextDepth(): number
+}
+
+export declare class LlmCall {
+  get functionName(): string
+  get provider(): string | null
+  get timing(): Timing
+  get usage(): Usage
+}
+export type LLMCall = LlmCall
+
+export declare class Timing {
+  get startTimeUtcMs(): number
+  get durationMs(): number | null
+}
+
+export declare class Usage {
+  get inputTokens(): number | null
+  get outputTokens(): number | null
+  get cachedInputTokens(): number | null
+}
+
+/**
+ * Test-only: seed a `FunctionRef` entry into `HANDLE_TABLE`, returning
+ * `[key, handleType]` so test code can construct a `BamlHandle`.
+ */
+export declare function _seedFunctionRefHandle(globalIndex: number): [HandleKey, number]
+
+/** Test-only: seed an `Adt(Media(generic))` entry into `HANDLE_TABLE`. */
+export declare function _seedGenericMediaHandle(): [HandleKey, number]
+
+export declare function cancelFunctionCall(callId: string): boolean
+
+/**
+ * Complete an in-flight host call from the JS dispatch wrapper.
+ *
+ * Exposed to JS as `completeHostCall(callId, isError, content)`. The JS
+ * dispatch wrapper invokes this after it has decoded `argsBytes`, called
+ * the user function, and encoded the result as an `InboundValue` (success
+ * is the value itself; an error is an `Instance` of
+ * `baml.errors.HostCallable` carrying the four metadata fields).
+ *
+ * Forwards directly to the `bridge_cffi::complete_host_call` C entry point
+ * the engine uses for cross-language completion.
+ */
+export declare function completeHostCall(callId: number, isError: number, content: Buffer): void
+
+/** No-op: tracing has been removed. Kept as a live symbol for ABI stability. */
+export declare function flushEvents(): void
+
+/**
+ * Return the process-global `BamlRuntime`, or a `BamlError`-shaped
+ * `napi::Error` if `initializeRuntime` has not run yet. The handle is
+ * zero-sized; the `Arc<dyn Bex>` lives in `bridge_cffi`. Mirrors
+ * `bridge_python`'s module-level `get_runtime()`.
+ */
+export declare function getRuntime(): BamlRuntime
+
+export declare function getVersion(): string
+
+/**
+ * A u64 handle key split into two i32 halves, mirroring the shape of
+ * protobufjs's `Long` type (`{ low: number, high: number }`).
+ *
+ * JavaScript has no convenient native representation for u64 — `number` is
+ * f64 and silently loses precision above 2^53. Rather than forcing BigInt
+ * (which many JS libraries don't handle well), we pass the key as two 32-bit
+ * halves that are layout-compatible with `Long`. This means a protobufjs
+ * `Long` decoded from a uint64 proto field can be handed directly to the
+ * `BamlHandle` constructor, and the `HandleKey` returned by the getter can
+ * be passed straight back into a proto uint64 field — no conversions needed.
+ */
+export interface HandleKey {
+  low: number
+  high: number
+}
+
+/**
+ * Mint a fresh host-value key, drawing from the shared callable+opaque
+ * counter so the engine sees one globally-unique keyspace. Returned to
+ * TS by `registerHostOpaque` (the TS-side function in
+ * `host_value_registry.ts`).
+ *
+ * Exposed to JS as `mintHostValueKey() -> HandleKey`. The TS-side host-value
+ * registry calls this once per `registerHostOpaque(value)` before inserting
+ * the value into its `Map<bigint, unknown>`.
+ */
+export declare function mintHostValueKey(): HandleKey
+
+export declare function newFunctionCall(): string
+
+/**
+ * Register a JS dispatch wrapper in the host-value table and return its key.
+ *
+ * Exposed to JS as `registerHostCallable(fn) -> HandleKey`. Called from
+ * the inbound encoder in `typescript_src/proto.ts` whenever a JS callable
+ * appears as a kwarg — the encoder constructs the dispatch wrapper around
+ * the user's function before calling this.
+ *
+ * The `Function` is converted into a `ThreadsafeFunction` so it can outlive
+ * the napi call scope and be invoked from any thread (the engine's tokio
+ * runtime calls into this entry point from a worker thread).
+ */
+export declare function registerHostCallable(callable: (callId: number, argsBytes: Buffer) => void): HandleKey
+
+/**
+ * Install the TS-side release callback. First-call-wins; subsequent
+ * calls are a no-op (matching the bridge_cffi dispatch-registration
+ * semantics). The callback fires for *every* `HostValueArc` release —
+ * for callable keys it's a TS-side no-op (`Map.delete(key)` on an absent
+ * key), so Rust doesn't need to distinguish kinds here.
+ *
+ * The tsfn is built with `weak::<true>()` (i.e. `napi_unref_threadsafe_
+ * function`). Holding it strong would pin the libuv loop for the
+ * lifetime of the process (the tsfn is parked in a `OnceLock` and never
+ * dropped), preventing the Node process from exiting even after all
+ * host work is done. Weak is correct here: the callback is a *release*
+ * notification — purely informational from the engine's side. Pending
+ * notifications that never deliver because the loop has already exited
+ * are harmless; the engine has already dropped its `Arc<HostValueArc>`,
+ * and the TS-side map entry would be torn down with the process
+ * anyway.
+ *
+ * Note this is the inverse of `register_host_callable`'s dispatch tsfn,
+ * which is `weak::<false>()` — that one pins the loop because a hung
+ * host callback awaiting completion *must* keep the loop alive so the
+ * JS callback can actually run.
+ *
+ * Exposed to JS as `registerHostValueReleaseCallback(cb)`. Must be called
+ * exactly once at SDK module init, before any host call is dispatched.
+ */
+export declare function registerHostValueReleaseCallback(callback: (key: HandleKey) => void): void
+
+/**
+ * Release a host callable the inbound encoder registered but never handed to
+ * the engine — the encode-error rollback path.
+ *
+ * Exposed to JS as `releaseHostCallable(key)`. When `encodeCallArgs`
+ * registers a callable for an early kwarg and then fails to encode a later
+ * kwarg, the `CallFunctionArgs` is never sent, so the engine never decodes
+ * (and so never releases) that key. Without this, the registry entry — and
+ * its strong `weak::<false>` tsfn ref, which keeps the libuv loop alive —
+ * would leak for the life of the process. The encoder calls this for every
+ * key it registered during a failed encode.
+ */
+export declare function releaseHostCallable(key: HandleKey): void