# @tanstack/ai-utils

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

Latest version **1.1.0** (published 2026-11-05) · MIT license · 0 weekly downloads

## Install

```sh
npm install @tanstack/ai-utils
pnpm add @tanstack/ai-utils
yarn add @tanstack/ai-utils
bun add @tanstack/ai-utils
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 1.1.0 |
| Published | 2026-11-05 |
| First published | 2026-05-11 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM |
| Dependencies | 0 |
| Unpacked size | 136.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 3377 |
| Author | Tanner Linsley |
| Maintainers | tannerlinsley, alemtuzlak, kevinvandy |
| Keywords | ai, ai-sdk, typescript, tanstack, utilities, adapter, provider-adapter |

## Links

- npm: https://www.npmjs.com/package/@tanstack/ai-utils
- Repository: https://github.com/TanStack/ai
- Homepage: https://tanstack.com/ai
- Issues: https://github.com/TanStack/ai/issues
- Funding: https://github.com/sponsors/tannerlinsley
- npm.io page: https://npm.io/package/@tanstack/ai-utils

## Alternatives

- [@expo/fingerprint](https://npm.io/package/@expo/fingerprint.md) — 6.2M weekly downloads
- [@azure/monitor-opentelemetry-exporter](https://npm.io/package/@azure/monitor-opentelemetry-exporter.md) — 850.0K weekly downloads
- [@azure/monitor-opentelemetry](https://npm.io/package/@azure/monitor-opentelemetry.md) — 624.0K weekly downloads
- [@posthog/ai](https://npm.io/package/@posthog/ai.md) — 423.3K weekly downloads
- [fakefilter](https://npm.io/package/fakefilter.md) — 63.9K weekly downloads

## Recent versions

- 1.1.0 (latest) — 2026-11-05
- 1.0.1 — 2026-11-04
- 1.0.0 — 2026-10-22
- 0.5.0 — 2026-10-19
- 0.4.2 — 2026-10-13
- 0.4.1 — 2026-09-21
- 0.4.0 — 2026-08-04
- 0.3.1 — 2026-06-25
- 0.3.0 — 2026-06-23
- 0.2.2 — 2026-06-16
- 0.2.1 — 2026-05-22
- 0.2.0 — 2026-05-11
- 0.1.0 — 2026-05-11

## README

<div align="center">
  <picture>
    <source
      media="(prefers-color-scheme: dark)"
      srcset="https://tanstack.com/api/readme/ai.png?theme=dark"
    />
    <source
      media="(prefers-color-scheme: light)"
      srcset="https://tanstack.com/api/readme/ai.png"
    />
    <img
      src="https://tanstack.com/api/readme/ai.png"
      alt="TanStack AI"
      width="900"
    />
  </picture>
</div>

<br />

# @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

```bash
npm install @tanstack/ai-utils
# or
pnpm add @tanstack/ai-utils
# or
yarn add @tanstack/ai-utils
```

## 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 `null`s that strict-mode schema widening synthesized, using the `NullWideningMap` recorded by the widening pass. `.nullable()` fields keep their nulls. |

### Ids and API keys

```typescript
import { generateId, getApiKeyFromEnv } from '@tanstack/ai-utils'

const runId = generateId('run') // run-1758424800000-k3j9x2p1q
const apiKey = getApiKeyFromEnv('OPENAI_API_KEY') // throws if unset
```

### Base64

```typescript
import { arrayBufferToBase64, base64ToUint8Array } from '@tanstack/ai-utils'

declare const file: File

const encoded = arrayBufferToBase64(await file.arrayBuffer())
const bytes = base64ToUint8Array(encoded)
```

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

---
_Source: https://npm.io/package/@tanstack/ai-utils · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
