@nerdware/ts-string-helpers

Nerdware TypeScript String Helpers

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

• 🚀 Getting Started
  • 📦 Installation
  • 🛠️ Usage
• ⚙️ API
  • Sanitizers
  • Validators
• 🌎 Unicode Support
  • Supported Unicode Character Classes
• 🤝 Contributing
• 📝 License
• 💬 Contact

🚀 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.

For each sanitize function, there's a corresponding validate function to ensure strings match a specific format.

📦 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
sanitizeAlphabeticWithSpaces	Removes non-alphabetic/space characters
sanitizeAlphanumeric	Removes non-alphanumeric characters
sanitizeAlphanumericWithSpaces	Removes non-alphanumeric/space 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	Alias of sanitizeNumeric
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
isValidAlphabeticWithSpaces	Returns true if value only contains alphabetic characters and/or spaces
isValidAlphanumeric	Returns true if value only contains alphanumeric characters
isValidAlphanumericWithSpaces	Returns true if value only contains alphanumeric characters and/or spaces
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 #
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 string of US phone number DIGITS
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

🌎 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!

📝 License

All files, scripts, and source code contained herein are open-source software licensed under an MIT License.

See LICENSE for more information.

💬 Contact

Trevor Anderson — [e-mail] — @TeeRevTweets

     

Dare Mighty Things.