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

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

📝 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] — @trevor-anderson

     

Dare Mighty Things.