@nerdware/ts-string-helpers NPM

TypeScript utils to sanitize and validate strings in any environment 🎉ESM ✅ CommonJS ✅ NodeJS ✅ browsers ✅

🚀 Getting Started

This package provides a lightweight set of TypeScript utils to sanitize and validate strings in any environment.

The sanitize functions use reverse-regex patterns to strip unwanted characters from strings — even pesky zero-width control characters — leaving only the characters you want. This is useful for sanitizing user input and other untrusted data.

📦 Installation

Install the package using your package manager of choice:

npm:

npm install @nerdware/ts-string-helpers

yarn:

yarn add @nerdware/ts-string-helpers

🛠️ Usage

Here's a simple example of how to use the sanitizeEmail and isValidEmail functions to sanitize and validate an email address before using it in a NodeJS Express route:

import { sanitizeEmail, isValidEmail } from "@nerdware/ts-string-helpers";
import express from "express";
import { UserModel } from "./models/my-user-model";

// or const { sanitizeEmail } = require("@nerdware/ts-string-helpers");

const app = express();

app.use(express.json());

app.post("/register", (req, res, next) => {
  // Sanitize the unknown `email` input before using it!
  const userEmail = sanitizeEmail(req.body.email);

  // Validate the sanitized email
  if (!isValidEmail(userEmail)) {
    return res.status(400).send("Invalid email address");
  }

  // Now you can safely use the sanitized value throughout the rest of your stack!🎉
  const newUser = UserModel.create({ email: userEmail });

  res.status(201).json(newUser);
});

⚙️ API

!TIP
In the tables below, click on a function to view the exact regex pattern it uses.
Additional information is also available in each function's JSDoc comments.
Functions with the 🌎 globe emoji in their description use limited Unicode character classes rather than ASCII-character ranges for greater i18n support (for more info, see Unicode Support).
All functions with the Alpha infix (e.g., sanitizeAlphabetic) only permit ASCII characters and are case-insensitive.

Sanitizers

Function	Description
`sanitizeAlphabetic`	Removes non-alphabetic characters
`sanitizeAlphanumeric`	Removes non-alphanumeric characters
`sanitizeBase64`	Removes invalid base64 characters
`sanitizeBase64URL`	Removes invalid base64URL characters
`sanitizeEmail`	Removes invalid email characters (see RFC 5322)
`sanitizeHandle`	Removes invalid social-handle characters
`sanitizeHex`	Removes non-hexadecimal characters
`sanitizeID`	Removes non-alphanumeric characters which are not `_`, `-`, or `#`
`sanitizeJsonString`	Removes characters which are not valid in stringified JSON
`sanitizeJWT`	Removes characters which are not valid in a JSON Web Token
`sanitizeName`	Removes characters which are generally not valid in a name (🌎i18n-friendly)
`sanitizeNumeric`	Removes non-numeric characters
`sanitizePassword`	Removes non-alphanumeric characters which are not `!`, `@`, `#`, `$`, `%`, `^`, `&`, or `*`
`sanitizePhone`	Removes characters which are not valid in a phone number
`sanitizeText`	Removes characters which are generally not used in text/comments (🌎i18n-friendly)
`sanitizeURL`	Removes invalid URL characters

Validators

Function	Description
`isValidAlphabetic`	Returns `true` if `value` only contains alphabetic characters
`isValidAlphanumeric`	Returns `true` if `value` only contains alphanumeric characters
`isValidBase64`	Returns `true` if `value` is a valid base64 string
`isValidBase64URL`	Returns `true` if `value` is a valid base64URL string
`isValidCurrency`	Returns `true` if `value` is a valid USD currency-formatted string
`isValidEmail`	Returns `true` if `value` is a valid email address (see RFC 5322)
`isValidHandle`	Returns `true` if `value` is a valid social account handle (e.g., `@foo_user`)
`isValidHex`	Returns `true` if `value` only contains hexadecimal characters
`isValidID`	Returns `true` if `value` only contains alphanumeric characters, `_`, `-`, or `#`
`isValidISO8601Timestamp`	Returns `true` if `value` is a valid ISO-8601 timestamp
`isValidJsonString`	Returns `true` is `value` only contains valid JSON characters
`isValidJWT`	Returns `true` if `value` only contains valid JSON Web Token characters
`isValidName`	Returns `true` if `value` only contains name-related characters (🌎i18n-friendly)
`isValidNumeric`	Returns `true` if `value` only contains numeric characters
`isValidPassword`	Returns `true` if `value` is a valid password (see jsdoc for details)
`isValidPhone`	Returns `true` if `value` is a valid US phone number
`isValidStreetAddress`	Returns `true` if `value` is a valid street address (line 1 or line 2) (🌎i18n-friendly)
`isValidText`	Returns `true` if `value` does not contain potentially harmful characters (🌎i18n-friendly)
`isValidURL`	Returns `true` if `value` is a valid absolute or relative URL (protocol agnostic)
`isValidHttpURL`	Returns `true` if `value` is a valid absolute HTTP/S URL
`isValidUUID`	Returns `true` if `value` is a valid UUID of any version

🌎 Unicode Support

To offer greater i18n support, functions denoted with a 🌎 globe emoji implement limited Unicode character classes to provide greater flexibility than ASCII alternatives (e.g., \p{Script=Latin} instead of [a-zA-Z]). Over time, efforts will be made to expand this library's i18n support wherever it's possible to do so without compromising security.

!IMPORTANT Broadly permissive Unicode character classes like \p{Letter} will never be used by any utilities in this library due to their potential security implications (right-to-left override attacks, homoglyph attacks, etc.).

Supported Unicode Character Classes

Unicode Character Class	Reference of Included Characters
`\p{Script=Latin}`	Unicode Latin Script Characters

🤝 Contributing

Pull requests are welcome! Before you begin, please check existing GitHub Issues and Pull Requests to see if your idea is already in the pipeline. If not, here's a guide on how to contribute to this project. Thank you!