@tanstack/ai-utils weekly downloads statistics

@tanstack/ai-utils

Shared TypeScript utilities for TanStack AI provider adapters and runtime packages.

This is an internal dependency of the provider adapters (@tanstack/ai-openai, @tanstack/ai-anthropic, @tanstack/ai-gemini, …) and runtime packages. It has no dependencies of its own and no framework or provider code; you normally get it transitively rather than installing it yourself. It is documented here so adapter authors know what already exists before writing their own.

Installation

What's in it

| Export | Purpose |

| generateId(prefix) | Prefixed unique id: ${prefix}-${timestamp}-${random}, with the full base36 random portion kept for entropy. | | getApiKeyFromEnv(name) | Reads name from window.env (browser) or process.env (Node) and throws a clear error naming the variable when it is missing. | | arrayBufferToBase64, base64ToArrayBuffer, base64ToUint8Array | Cross-runtime base64 helpers. Prefer the native Uint8Array.toBase64() / fromBase64() when available, then Node's Buffer, then atob / btoa. | | transformNullsToUndefined(value) | Recursively strips every null from JSON-shaped structured output so .optional() fields round-trip through Zod. Schema-blind. | | undoNullWidening(value, map?) | Strips only the nulls that strict-mode schema widening synthesized, using the NullWideningMap recorded by the widening pass. .nullable() fields keep their nulls. |

Ids and API keys

Base64

Be cautious with large buffers on serverless and Workers runtimes: base64 multiplies the memory footprint by about 1.33× and can OOM the isolate.

Nulls in structured output

OpenAI-style strict schemas require optional fields to be widened to required + nullable, so the provider returns null for an absent optional. Validating that null against the original schema fails, because .optional() means T | undefined, not T | null.

• undoNullWidening(value, map) is the precise fix: it consults the NullWideningMap built by convertSchemaForStructuredOutput in @tanstack/ai and drops only the nulls the widening pass introduced, so both optional and nullable fields round-trip. With no map, the value is returned untouched. • transformNullsToUndefined(value) is the schema-blind fallback: it strips every null, including ones a .nullable() field legitimately allows, and is meant for JSON.parse output only (class instances, Date, Map, Set are not preserved).

License

MIT

Description from the npm listing.