README.md

hydrate-text

A small, dependency-free and strongly typed template engine.

Features

• Light-weight. Less than 1 KiB (actual size depends on imported functions).
• Dependency-free. Only bundled JavaScript files and TypeScript type declarations are included.
• Tree-shakable. Only imported code comes to your bundle.
• Strongly typed with TypeScript. All types are exported alongside with the core functions.
• Flexible interpolation options change. Change variables' markers in each function or use a special function to configure them once for further usage.

Examples

import { hydrateText } from "hydrate-text";

// "Hello, John!"
console.log(
  hydrateText("Hello, {username}!", {
    username: "John",
  }),
);

// "/users/42"
console.log(
  hydrateText(
    "/users/:id",
    { id: 42 },
    {
      prefix: ":",
      suffix: "",
    },
  ),
);

TypeScript checks that all the variables defined in the given string are provided.

console.log(
  hydrateText(
    "Hello, {username}!",
    // No errors
    {
      username: "John",
    },
  ),
);

console.log(
  hydrateText(
    "Hello, {username}!",
    // Error: `username` is missing
    {},
  ),
);

Interpolation options can be configured via configureHydrateText function, that returns hydrateText function as a result.

import { configureHydrateText } from "hydrate-text";

const hydrateRoute = configureHydrateText({ prefix: ":" });

// "/users/42"
console.log(hydrateRoute("/users/:id", { id: 42 }));

// "/users/42"
console.log(
  hydrateRoute(
    "/users/(id)",
    { id: 42 },
    {
      prefix: "(",
      suffix: ")",
    },
  ),
);

Check out other correct and incorrect usage examples.

Installation

npm

npm install hydrate-text

Yarn

yarn add hydrate-text

API (simplified)

type ValueType = string | boolean | number | bigint;

interface InterpolationOptions {
  prefix: string;
  suffix: string;
}

function hydrateText(
  text: string,
  variables?: Record<string, ValueType>,
  interpolationOptions?: InterpolationOptions,
) {}

function configureHydrateText(
  interpolationOptions: InterpolationOptions,
) => typeof hydrateText;

Check out the "Types" section in the source file for more information.

Known issues

• SyntaxError: Unexpected token 'export'.

  The problem appears when running tests using Jest. That's because of lack of CommonJS support. A solution can be found here. Not supporting CommonJS is intended, since all the industry is moving towards ES modules, and CommonJS will be retired at some point.

Background

Why I wrote "hydrate-text" library

License

MIT