Skip to main content
Home
Browse packagesDocsSign in

@marianmeres/interpolate@1.2.1

latest
marianmeres/interpolate

Interpolates string variable name placeholders, so that "Hello, ${NAME:-World}!" works as expected.

This package works with Node.js, Deno, BrowsersIt is unknown whether this package works with Cloudflare Workers, Bun
It is unknown whether this package works with Cloudflare Workers
This package works with Node.js
This package works with Deno
It is unknown whether this package works with Bun
This package works with Browsers
JSR Score
100%
Published
5 days ago (1.2.1)

@marianmeres/interpolate

NPM version JSR version

Simple helper function which interpolates string variable name placeholders, so that "Hello, ${NAME:-World}!" works as expected.

Inspired by docker compose interpolation syntax, with minor extension (read NOTE below). The nested notation is not supported.

The context (source data to interpolate from) is provided as a parameter.

Supported syntax

The unset below means undefined and empty means empty string.

IMPORTANT NOTES:

  • The unbraced syntax $VAR only matches uppercase variable names (pattern: /[A-Z_][A-Z0-9_]*/). This follows Docker Compose conventions. Use braced syntax ${var} for lowercase or mixed-case names.
  • Context values must be strings. The function signature is Record<string, string>.
  • Best Practice: For consistency and clarity, it's recommended to use UPPERCASE names for all variables, even in braced syntax.
Syntax Description
$VAR Basic unbracketed direct substitution (uppercase only)
${VAR} Basic bracketed direct substitution (any case)
${VAR:-default} Use "default" if VAR is unset or empty
${VAR-default} Use "default" only if VAR is unset
${VAR:?error message} Throws "error message" if VAR is unset or empty (read NOTE)
${VAR?error message} Throws "error message" only if VAR is unset (read NOTE)
${VAR:?} Throws error if VAR is unset or empty (read NOTE)
${VAR?} Throws error only if VAR is unset (read NOTE)
${VAR:+replacement} Use "replacement" if VAR is set and non-empty, otherwise empty
${VAR+replacement} Use "replacement" if VAR is set, otherwise empty

NOTE: for the assertion syntax both "?" and "!" are supported

Install

deno add jsr:@marianmeres/interpolate

npm install @marianmeres/interpolate

Example usage

import { interpolate } from '@marianmeres/interpolate';

// signature:
function interpolate(str: string, context: Record<string, string>): string

// Hello, World!
interpolate("Hello, ${NAME:-World}", {}); 

// Hello, Foo!
interpolate("Hello, ${NAME:-World}", { NAME: "Foo" }); 
interpolate("Hello, $NAME", { NAME: "Foo" }); 

// throws generic error
interpolate("Hello, ${NAME:!}", {}); 
interpolate("Hello, ${NAME:?}", {}); // same as above, both "!" and "?" are supported
interpolate("Hello, ${NAME:!}", { NAME: "" }); 

// throws "custom error message"
interpolate("Hello, ${NAME:?custom error message}", {});

Package Identity

New Ticket: Report package

Please provide a reason for reporting this package. We will review your report and take appropriate action.

Please review the JSR usage policy before submitting a report.

Add Package

deno add jsr:@marianmeres/interpolate

Import symbol

import * as interpolate from "@marianmeres/interpolate";
or

Import directly with a jsr specifier

import * as interpolate from "jsr:@marianmeres/interpolate";

Add Package

pnpm i jsr:@marianmeres/interpolate
or (using pnpm 10.8 or older)
pnpm dlx jsr add @marianmeres/interpolate

Import symbol

import * as interpolate from "@marianmeres/interpolate";

Add Package

yarn add jsr:@marianmeres/interpolate
or (using Yarn 4.8 or older)
yarn dlx jsr add @marianmeres/interpolate

Import symbol

import * as interpolate from "@marianmeres/interpolate";

Add Package

vlt install jsr:@marianmeres/interpolate

Import symbol

import * as interpolate from "@marianmeres/interpolate";

Add Package

npx jsr add @marianmeres/interpolate

Import symbol

import * as interpolate from "@marianmeres/interpolate";

Add Package

bunx jsr add @marianmeres/interpolate

Import symbol

import * as interpolate from "@marianmeres/interpolate";