@prompt-template/core

@prompt-template/core contains the core promptTemplate module and types for creating and formatting prompts with input variables. Key features include:

• Type Safety: Ensures promptTemplate input variables are defined and formatted correctly at compile time.
• Modular Design: Supports nested promptTemplates to promote organization and reusability.
• Intuitive Authoring: Simplifies prompt creation by solely defining input variables in promptTemplates.
• Community Prompts: Designed with the vision of creating and sharing promptTemplates with the community (as NPM packages for example).

Installation

npm i @prompt-template/core

Usage

promptTemplate with InputVariableName

import { promptTemplate } from '@prompt-template/core'

const brainstormPromptTemplate = promptTemplate`
  Brainstorm 3 names for a superhero ${'animal'}.
`

const brainstormPrompt = brainstormPromptTemplate.format({
  animal: 'cat',
})
//=> 'Brainstorm 3 names for a superhero cat.'

promptTemplate with InputVariableConfig.onFormat

import { promptTemplate } from '@prompt-template/core'

const brainstormPromptTemplate = promptTemplate`
  Brainstorm 3 names for a superhero ${{
    name: 'animal' as const,
    onFormat: (inputValue) => inputValue.toUpperCase(),
  }}.
`

const brainstormPrompt = brainstormPromptTemplate.format({
  animal: 'cat',
})
//=> 'Brainstorm 3 names for a superhero CAT.'

promptTemplate with InputVariableConfig.schema

import { promptTemplate } from '@prompt-template/core'
import { z } from 'zod'

const brainstormPromptTemplate = promptTemplate`
  Brainstorm 3 names for a superhero ${{
    name: 'animal' as const,
    schema: z.string().nonempty(),
  }}.
`

const brainstormPrompt = brainstormPromptTemplate.format({
  animal: 'cat',
})
//=> 'Brainstorm 3 names for a superhero cat.'

promptTemplate with InputVariableConfig.default

import { promptTemplate } from '@prompt-template/core'

const brainstormPromptTemplate = promptTemplate`
  Brainstorm 3 names for a superhero ${{
    name: 'animal' as const,
    default: 'cat',
  }}.
`

const catBrainstormPrompt = brainstormPromptTemplate.format({})
//=> 'Brainstorm 3 names for a superhero cat.'

const dogBrainstormPrompt = brainstormPromptTemplate.format({
  animal: 'dog',
})
//=> 'Brainstorm 3 names for a superhero dog.'

promptTemplate with nested promptTemplate

import { promptTemplate } from '@prompt-template/core'

const outputFormatPromptTemplate = promptTemplate`
  Format the output as ${{
    name: 'format' as const,
    default: 'bullet points',
  }}.
`

const brainstormPromptTemplate = promptTemplate`
  Brainstorm 3 names for a superhero ${'animal'}.
  ${outputFormatPromptTemplate}
`

const bulletPointsPrompt = brainstormPromptTemplate.format({
  animal: 'cat',
})
//=> 'Brainstorm 3 names for a superhero cat.
//    Format the output as bullet points.'

const numberedListPrompt = brainstormPromptTemplate.format({
  animal: 'cat',
  format: 'a numbered list',
})
//=> 'Brainstorm 3 names for a superhero cat.
//    Format the output as a numbered list.'

promptTemplate with PromptTemplateOptions

import { promptTemplate } from '@prompt-template/core'

const userPromptTemplate = promptTemplate({ prefix: 'user: ' })`
  Brainstorm 3 names for a superhero ${'animal'}.
`

const userPrompt = userPromptTemplate.format({
  animal: 'cat',
})
//=> 'user: Brainstorm 3 names for a superhero cat.'

Note: By default, format will dedent the formatted prompt. You can disable this behavior by setting the dedent option to false.

API

promptTemplate

A tagged template literal function that returns a PromptTemplate instance or a new promptTemplate bound to the provided PromptTemplateOptions overrides.

const myPromptTemplate = promptTemplate`
  My prompt template with ${'inputVariableName'}.
`

const myPrompt = myPromptTemplate.format({
  inputVariableName: 'inputVariableValue' as const,
})
//=> 'My prompt template with inputVariableValue.'

or

const userPromptTemplate = promptTemplate({ prefix: 'user: ' })

const myUserPromptTemplate = userPromptTemplate`
  My prompt template with ${'inputVariableName'}.
`

const myUserPrompt = myUserPromptTemplate.format({
  inputVariableName: 'inputVariableValue' as const,
})
//=> 'user: My prompt template with inputVariableValue.'

Note: The above is conventionally inlined:

const userPromptTemplate = promptTemplate({ prefix: 'user: ' })`
  My prompt template with ${'inputVariableName'}.
`

const userPrompt = userPromptTemplate.format({
  inputVariableName: 'inputVariableValue' as const,
})
//=> 'user: My prompt template with inputVariableValue.'

PromptTemplate Class

A PromptTemplate instance is returned from a promptTemplate call. It contains a format method for creating the final prompt and additional properties/methods for advanced use cases.

const myPromptTemplate = promptTemplate`
  My prompt template with ${'inputVariableName'} and default ${{
    name: 'inputVariableConfigName' as const,
    default: 'inputVariableConfigDefault',
  }}.
`

myPromptTemplate.templateStrings
//=> ['My prompt template with ', ' and default ', '.']

myPromptTemplate.inputVariables
//=> ['inputVariableName', { name: 'inputVariableConfigName' as const, default: 'inputVariableConfigDefault' }]

const myPrompt = myPromptTemplate.format({
  inputVariableName: 'inputVariableValue',
})
//=> 'My prompt template with inputVariableValue and default inputVariableConfigDefault.'

format(inputValues)

A PromptTemplate instance method used to create the final prompt. It accepts an inputValues object where each key corresponds to the InputVariableName, InputVariableConfig.name, and any nested PromptTemplate instance input variable names.

const myNestedPromptTemplate = promptTemplate`
  My nested prompt template with ${'nestedInputVariableName'}.
`

const myPromptTemplate = promptTemplate`
  - My prompt template with ${'inputVariableName'}
  - My prompt template with ${{
    name: 'inputVariableConfigName' as const,
    default: 'inputVariableConfigDefault',
  }}
  - ${myNestedPromptTemplate}
`

const inputValues = {
  inputVariableName: 'inputVariableValue' as const,
  // inputVariableConfigName: 'inputVariableConfigValue' as const, // Optional
  nestedInputVariableName: 'nestedInputVariableValue' as const,
}

const myPrompt = myPromptTemplate.format(inputValues)
//=> '- My prompt template with inputVariableValue
//    - My prompt template with inputVariableConfigDefault
//    - My nested prompt template with nestedInputVariableValue.'

getInputVariableNames()

A PromptTemplate instance method that recursively extracts and deduplicates all input variable names.

const myNestedPromptTemplate = promptTemplate`
  My nested prompt template with ${'nestedInputVariableName'}.
`

const myPromptTemplate = promptTemplate`
  - My prompt template with ${'inputVariableName'}.
  - My prompt template with ${{
    name: 'inputVariableConfigName' as const,
    default: 'inputVariableConfigDefault',
  }}.
  - ${myNestedPromptTemplate}
`

myPromptTemplate.getInputVariableNames()
//=> ['inputVariableName', 'inputVariableConfigName', 'nestedInputVariableName']

getInputVariableNamesRequired()

A PromptTemplate instance method that recursively extracts and deduplicates all required input variable names.

const myNestedPromptTemplate = promptTemplate`
  My nested prompt template with ${'nestedInputVariableName'}.
`

const myPromptTemplate = promptTemplate`
  - My prompt template with ${'inputVariableName'}.
  - My prompt template with ${{
    name: 'inputVariableConfigName' as const,
    default: 'inputVariableConfigDefault',
  }}.
  - ${myNestedPromptTemplate}
`

myPromptTemplate.getInputVariableNamesRequired()
//=> ['inputVariableName', 'nestedInputVariableName']

getInputVariableNamesOptional()

A PromptTemplate instance method that recursively extracts and deduplicates all optional input variable names.

const myNestedPromptTemplate = promptTemplate`
  My nested prompt template with ${'nestedInputVariableName'}.
`

const myPromptTemplate = promptTemplate`
  - My prompt template with ${'inputVariableName'}.
  - My prompt template with ${{
    name: 'inputVariableConfigName' as const,
    default: 'inputVariableConfigDefault',
  }}.
  - ${myNestedPromptTemplate}
`

myPromptTemplate.getInputVariableNamesOptional()
//=> ['inputVariableConfigName']

Important: If input variable names are duplicated and one is required and the other is optional, the input variable name is considered required.

const myPromptTemplate = promptTemplate`
  My duplicate prompt template with ${'duplicateInputVariableName'} and ${{
    name: 'duplicateInputVariableName' as const,
    default: 'duplicateInputVariableNameDefault',
  }}.
`

myPromptTemplate.getInputVariableNamesRequired()
//=> ['duplicateInputVariableName']

myPromptTemplate.getInputVariableNamesOptional()
//=> []

PromptTemplateOptions

A PromptTemplateOptions object is passed to a promptTemplate call to override the default behavior of a PromptTemplate instance.

const promptTemplateOptions = {
  prefix: 'prefix - ',
  suffix: ' - suffix',
  dedent: true, // Default
}

const myPromptTemplate = promptTemplate(promptTemplateOptions)`
  My prompt template with ${'inputVariableName'}
`

const myPrompt = myPromptTemplate.format({
  inputVariableName: 'inputVariableValue' as const,
})
//=> 'prefix - My prompt template with inputVariableValue - suffix'

InputVariableName

An InputVariableName is a string used to identify input variables in a promptTemplate and establish a corresponding property in the format inputValues.

const myPromptTemplate = promptTemplate`
  My prompt template with ${'inputVariableName'}
`

const myPrompt = myPromptTemplate.format({
  inputVariableName: 'inputVariableValue' as const,
})
//=> 'My prompt template with inputVariableValue.'

InputVariableConfig

An InputVariableConfig is an object used to identify input variables in a promptTemplate and establish a corresponding property in the format inputValues. It also allows for additional configuration of the input variable.

const myPromptTemplate = promptTemplate`
  My prompt template with ${{
    name: 'inputVariableConfigName' as const,
    default: 'inputVariableConfigDefault',
    onFormat: (inputValue) => inputValue.toUpperCase(),
    schema: z.string().nonempty(),
  }}
`

const myPrompt = myPromptTemplate.format({
  inputVariableConfigName: 'inputVariableConfigValue' as const,
})
//=> 'My prompt template with INPUTVARIABLECONFIGVALUE.'

InputVariableConfig.name

An InputVariableConfig.name is a string used to identify input variables in a promptTemplate and establish a corresponding property in the format input values.

const myPromptTemplate = promptTemplate`
  My prompt template with ${{ name: 'inputVariableConfigName' as const }}.
`

const myPrompt = myPromptTemplate.format({
  inputVariableConfigName: 'inputVariableConfigValue' as const,
})
//=> 'My prompt template with inputVariableConfigValue.'

InputVariableConfig.default

An InputVariableConfig.default is a default value for an input variable in a promptTemplate and allows the corresponding property in the format inputValues to be omitted.

const myPromptTemplate = promptTemplate`
  My prompt template with ${{
    name: 'inputVariableConfigName' as const,
    default: 'inputVariableConfigDefault',
  }}
`

const myPrompt = myPromptTemplate.format({})
//=> 'My prompt template with inputVariableConfigDefault.'

InputVariableConfig.onFormat

The InputVariableConfig.onFormat function is a callback used to provide custom formatting for inputValues and is called when the format method is called.

const myPromptTemplate = promptTemplate`
  My prompt template with ${{
    name: 'inputVariableConfigName' as const,
    onFormat: (inputValue) => inputValue.toUpperCase(),
  }}
`

const myPrompt = myPromptTemplate.format({
  inputVariableConfigName: 'inputVariableConfigValue' as const,
})
//=> 'My prompt template with INPUTVARIABLECONFIGVALUE.'

InputVariableConfig.schema

The InputVariableConfig.schema property accepts a Zod-like schema and is used to validate format inputValues.

const myPromptTemplate = promptTemplate`
  My prompt template with ${{
    name: 'inputVariableConfigName' as const,
    schema: z.string().nonempty(),
  }}.
`

const myPrompt = myPromptTemplate.format({
  inputVariableConfigName: 'inputVariableConfigValue' as const,
})
//=> 'My prompt template with inputVariableConfigValue.'