@magicapply/retool-typebox-client NPM

`@magicapply/retool-typebox-client`

Typed ✨. Minimal 🪶. Retool-ready 🛠️.
Turn remote TypeMap syntax strings into fully-typed validators inside Retool Workflows & Node.

Why this package?

Retool Workflows runs on Node.js 20 and lets you pipe data between blocks, but lacks built-in helpers for TypeBox schema validation.

This package bridges that gap by providing:

One-liner fetchers – download remote {version, schemas} JSON files containing TypeMap syntax strings, or transform them into [key, JSONSchema][] entries.
Zero-config validator – compile TypeMap syntax strings (like { id: string, tags: string[] }) lazily into TypeBox validators with convenient check | validate | assert helpers.
First-class TypeScript – generics & JSDoc types provide autocompletion without needing .ts files inside Retool.
Retool-specific utilities – strip Retool's _selector metadata keys and infer registry types from tuple entries.

Everything is packaged in ~0.4 MB of bundled CommonJS code optimized for Retool's Node.js 20 runtime.

Installation

npm install @magicapply/retool-typebox-client

This package is CommonJS-only (type: "commonjs") to match Retool's Node.js 20 runtime environment.

Quick start (two-block pipeline)

import { getSchemaEntries } from '@magicapply/retool-typebox-client'

// Fetch and compile TypeMap syntax strings to JSON schemas
return await getSchemaEntries(
  'https://api.example.com/schemas'
)

// @ts-check
import {
  fetchSchemas,
  createValidator,
  RegistryFromEntries
} from '@magicapply/retool-typebox-client'

// Get entries from previous block
const entries = /** @type {const} */ (input.data)

// Fetch raw TypeMap syntax strings for validation
const { schemas } = await fetchSchemas('https://api.example.com/schemas')

// Create validator from syntax strings
const validator = createValidator(schemas)

// Validate with autocompletion ✨
validator.assert('user.profile', { 
  id: '42', 
  name: 'Jane',
  tags: ['admin', 'verified']
})

API Reference

Function / Type	Description
`fetchSchemas(url, fetchFn?)`	Fetch `{ version, schemas }` where `schemas` is a `Record<string, string>` of TypeMap syntax strings.
`getSchemaEntries(url, fetchFn?)`	Fetch and compile syntax strings into `[key, JSONSchema]` pairs.
`createValidator(registry)`	Compile TypeMap syntax strings lazily into validators with:`check` → boolean, `validate` → {value\|issues}, `assert` → throws.Includes `value` re-export from `@sinclair/typebox/value`.
`RegistryFromEntries<Entries>`	Infer a typed registry from `[key, JSONSchema][]` entries.
`SchemaOf<Entries, Key>`	Extract a single schema type from entries.
`ValidatorFromRegistry<Registry>`	Capture the return type of `createValidator`.
`RemoteSchemas<T>`	Strip Retool's `_selector` metadata from fetched schemas.

TypeMap Syntax Examples

The syntax strings use TypeMap's TypeScript-like DSL:

const schemas = {
  'user.profile': '{ id: string, name: string, tags: string[] }',
  'user.settings': '{ theme: "light" | "dark", notifications: boolean }',
  'api.response': '{ data: any, status: number, error?: string }'
}

Advanced usage

1. Custom fetch implementation

Retool Cloud may lack global fetch in some contexts. Pass a compatible implementation:

import { getSchemaEntries } from '@magicapply/retool-typebox-client'
import fetch from 'node-fetch'

const entries = await getSchemaEntries(url, fetch)

2. Skip compilation for performance

If you only need raw TypeMap syntax strings (for createValidator), use fetchSchemas directly:

const { schemas } = await fetchSchemas(url)
const validator = createValidator(schemas) // Pass strings, not compiled schemas

3. Strip Retool metadata

Use RemoteSchemas<T> to remove _selector properties that Retool injects:

const raw = await fetchSchemas(url)
/** @type {RemoteSchemas<typeof raw.schemas>} */
const clean = raw.schemas
const validator = createValidator(clean)