typed-string-interpolation

String interpolation for TypeScript with correct return types based on passed in variables.

Library used within a React app. Note that the library itself is framework agnostic and could be used in any TypeScript/JavaScript app.

Main features

• Replaces variables within a string with passed in variables
• Dead simple syntax for working with translators
• Sanity checks that correct variables were passed in
• Returns the correct type based on passed in variable substitutions
• Options to customize return, pattern matching and sanity checking
• Both ES Module and CommonJS distributions available. Use anywhere!
• Tiny footprint:
  • ES Module: 383B Gzipped (553B unpacked)
  • CommonJS: 623B Gzipped (1.02kB unpacked)

Motivation

String interpolation/variable substitution (i.e. injecting variables within text) is a really common operation when building single and multilingual applications alike. Existing string interpolation utilities within the most used i18n / l10n packages like i18next and formatjs come with massive overhead while lacking proper TypeScript infer support for the interpolation operation. The string syntax for many common libraries and approaches also seem overly complex and hard to understand.

This utility aims to provide a high quality string interpolation "primitive" to use as is or within other localization frameworks and tooling that is as easy as possible to understand for both developers and translators.

Getting started

Easiest way to get started is to play around with a React example sandbox.

Install

npm i typed-string-interpolation

typed-string-interpolation package @ NPM

Usage

// ES module
import { stringInterpolation } from "typed-string-interpolation"
// CommonJS
const { stringInterpolation } = require("typed-string-interpolation")

Returns a string when the result can be joined into a string.

stringInterpolation("You have {{n}} messages", {
  n: 3,
}) // "You have 3 messages"

Returns an array when the result can't be joined into a string. This makes it really easy to use the utility with libraries like react or anything else.

stringInterpolation("You have {{n}} messages", {
  n: <strong>3</strong>,
}) // ["You have ", <strong>3</strong>, " messages"]

For more example use cases, see the unit test files in the repository:

• Unit tests for library logic
• Unit tests for inferred Typescript types

TypeScript support

If the string can be joined you'll get back a string type. Otherwise a union type within an array is returned based on the passed in variables.

stringInterpolation("You have {{n}} messages from {{person}}", {
  n: 3,
  person: "John",
}) // : string

stringInterpolation("You have {{n}} messages from {{person}}", {
  n: <strong>3</strong>,
  person: "John",
}) // : (JSX.Element | string)[]

Options

Takes in an optional third parameter for options:

stringInterpolation(str, variables, options)

type Options = {
  raw?: boolean // default: false
  pattern?: RegExp // default: /\{{([^{]+)}}/g
  sanity?: boolean // default: true
}

raw

Return the raw interpolation results without joining to string when you want full control for some reason.

stringInterpolation(
  "You have {{n}} messages from {{person}}",
  {
    n: 3,
    person: "John",
  },
  { raw: true },
) // : (number | string)[]

pattern

Provide your own RegExp pattern for variable matching. Must be defined as:

pattern: /\{{([^{]+)}}/g // Default

Example alternative pattern:

stringInterpolation(
  "Hi %{name}",
  { name: "John" },
  {
    pattern: /%\{([^}]+)\}/g,
  },
),

sanity

If you want to live dangerously, sanity checking can be turned off.

{
  sanity: false
}

Turning of sanity checking removes throw from:

• empty string
• string variables and passed in variables count mismatch
• missing variables

Contributing

Easiest way to contribute is to open new issues for API suggestions and bugs.

Contributing for a release

Steps for contributing through a pull request:

• Fork main on Github and clone fork locally
• Install dependencies
  • npm ci
• Make changes while running tests in watch mode
  • npm run test:unit:all:watch
  • This project has a .vscode/launch.json file containing configuration for running Jest tests with the VSCode debugger which makes it simple to step through logic excecution. Steps to use VSCode debugger:
    • Add a breakpoint to the source code
    • Open a Jest unit test file (*.test.ts)
    • Go to the VSCode debugger Tab (shift + command + D on MacOS) and select "Jest Current File" or optionally start the debug session from the command line (shift + command + P on MacOS) and type "Debug: Start debugging"
    • VSCode should open a new terminal window and attach the Jest instance to the debugger
    • Debugger should stop on the defined breakpoint in the source code
• Once all changes are complete, create a new release with changesets. (Note that this command also formats the code with the style rules of the repository).
  • npm run create-release
• Commit and push changes to fork
• Open a pull request against the fork
• If the PR needs changes before a merge to main can be made, push more changes to the fork until the PR is approved