PromptBuilder

Typesafe API for creating prompts

Overview

The Prompt class is a simple class that represents a string template with named placeholders. It provides a toString method that replaces the placeholders with values from an input object, producing a new string.

Basic Usage

To use the Prompt class, you'll need to create an instance of it with a template string that contains named placeholders. Here's an example:

Demo

Code

import { Prompt } from "@/lib/Prompt";

const prompt = new Prompt("Tell {{me}} {{num}} {{jokeType}} joke", {
  //    ^?   Tell Brett 1 funny joke
  me: "Brett",
  num: 1,
  jokeType: "funny",
}).toString();

console.log(prompt);
// Output: Tell Brett 1 funny joke

In this example, we create a new Prompt instance with a template string that contains three named placeholders: {{me}}, {{num}}, and {{jokeType}}. We also provide an input object with values for each of these placeholders.

When we call the toString method on the prompt instance, the placeholders are replaced with the corresponding values from the input object, producing the output string literally typed as "Tell Brett 1 funny joke".

Template Syntax

The template string passed to the Prompt constructor can contain named placeholders enclosed in double curly braces ({{}}). The names inside the placeholders should match the keys of the input object passed to the Prompt instance.

For example, if the input object has a property named firstName, you can use the {{firstName}} placeholder in the template string to include the value of that property in the output string.

Input Validation

If you want to validate the input object against a specific type, you can use the addInputValidation method of the PromptBuilder class to create a new PromptBuilder instance with the validation applied. Here's an example:

const builder = new PromptBuilder("Tell {{me}} {{num}} {{jokeType}} joke");
const validatedBuilder = builder.addInputValidation<{
  jokeType: "funny" | "silly";
  me: "Brett" | "Liana";
  num: number;
}>();

const prompt = validatedBuilder.build({
//     ^?  Tell Brett 1 funny joke
  jokeType: "funny",
  me: "Brett",
  num: 1,
}).toString();

console.log(prompt);
// Output: Tell Brett 1 funny joke

In this example, we create a new PromptBuilder instance with a template string that contains three named placeholders. We then use the addInputValidation method to create a new PromptBuilder instance that validates the input object against a specific type.

The type is defined as an object with properties that correspond to the named placeholders in the template string. The values of these properties are the expected types of the corresponding input values.

When we call the build method on the validatedBuilder instance with an input object that matches the expected type, we get a new Prompt instance with the placeholders replaced by the input values.

If the input object does not match the expected type, a type error will be thrown at compiletime.

addInputValidation only validates at compile time. To check values at runtime use addZodInputValidation

Input Validation with Zod

The PromptBuilder class also provides a method called addZodInputValidation that allows you to use the Zod library for input validation. This method creates a new PromptBuilder instance with the Zod validation schema applied.

Here's an example of how to use the addZodInputValidation method:

import { z } from "zod";

const builder = new PromptBuilder("Tell {{me}} {{num}} {{jokeType}} joke");

const inputSchema = z.object({
  jokeType: z.enum(["funny", "silly"]),
  me: z.enum(["Brett", "Liana"]),
  num: z.number(),
});

const validatedBuilder = builder.addZodInputValidation(inputSchema);

const prompt = validatedBuilder.build({
//     ^?   Tell Brett 1 funny joke
  jokeType: "funny",
  me: "Brett",
  num: 1,
}).toString();

console.log(prompt);
// Output: Tell Brett 1 funny joke

In this example, we create a new PromptBuilder instance with a template string that contains three named placeholders. We then define a Zod schema for the input object, specifying the expected types for each property.

Next, we use the addZodValidation method to create a new PromptBuilder instance that validates the input object against the Zod schema.

When we call the build method on the validatedBuilder instance with an input object that matches the expected schema, we get a new Prompt instance with the placeholders replaced by the input values.

If the input object does not match the expected schema, a typescript error will be thrown at build time and a Zod validation error will be thrown at runtime.