TypeScript Client

Learn how to integrate dot-prompt into your TypeScript/JavaScript application using the @dotprompt/client package.

1. Installation

Install the TypeScript client package from npm:

npm install @dotprompt/client

Requirements

Requires Node.js >=18.0.0 and a running dot-prompt server (Docker container).

2. Quick Start

First, make sure you have the dot-prompt server running. You can use Docker Compose:

docker compose -f docker-compose.headless.yml up -d

This starts the API server at http://localhost:4000.

Basic Usage

Import and initialize the client:

import { DotPromptClient } from '@dotprompt/client';

const client = new DotPromptClient({
  baseUrl: 'http://localhost:4000'
});

const prompts = await client.listPrompts();
console.log(prompts);

Async Client

For better performance with async/await patterns, use the async client:

import { DotPromptAsyncClient } from '@dotprompt/client';

const client = new DotPromptAsyncClient({
  baseUrl: 'http://localhost:4000'
});

// Use with async/await
async function main() {
  const prompts = await client.listPrompts();
  
  // Render a prompt
  const result = await client.render('explain', {
    level: 'expert',
    user_message: 'What is an atom?'
  });
  
  console.log(result.prompt);
}

main();

3. Rendering Prompts

Use the render method to compile a prompt with runtime parameters:

const result = await client.render('explain', {
  level: 'expert',
  user_message: 'What is an atom?'
});

console.log(result.prompt);
// Output: "Explain this with technical detail: What is an atom?"

The result includes the compiled prompt string and any response contract information.

4. Exported Modules

The package exports the following:

export { DotPromptAsyncClient, type DotPromptClientOptions } from "./asyncClient.js";
export { DotPromptClient } from "./client.js";
export { Transport, type RequestOptions } from "./transport.js";
export * from "./models.js";
export * from "./errors.js";
export { validateResponse } from "./utils.js";
export { createEventStream } from "./events.js";

5. Key Classes

DotPromptClient

Synchronous client for Node.js environments. Best for simple use cases.

DotPromptAsyncClient

Async client for use with async/await. Recommended for production use.

Transport

HTTP transport layer for API communication. Can be customized for advanced use cases.

6. Response Validation

Use the validateResponse utility to validate LLM responses against your response contracts:

import { validateResponse } from '@dotprompt/client';

const result = await client.render('prompt-name', params);

// Validate against a response contract
const validation = validateResponse(result);

if (!validation.valid) {
  console.error('Validation errors:', validation.errors);
}

7. Package Scripts

If you're developing the package itself, these scripts are available:

# Build the package
npm run build

# Run tests
npm run test

# Run tests in watch mode
npm run test:watch

# Lint code
npm run lint

# Format code
npm run format

8. Dependencies

Runtime Dependencies

zod (^3.22.4) - TypeScript-first schema validation
eventsource-parser (^1.1.2) - Server-Sent Events parsing

Development Dependencies

@types/node (^18.19.0)
eslint (^8.56.0)
prettier (^3.1.1)
tsup (^8.0.1)
typescript (^5.3.3)
vitest (^1.1.0)