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

$3

Install the package using your package manager of choice:

npm:

``bash
npm install @nerdware/ts-string-helpers
`

yarn:

`bash
yarn add @nerdware/ts-string-helpers
`

$3

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:

`typescript
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][unicode-regexp-flag] 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.

$3

| 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][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 |

[rfc-5322]: https://datatracker.ietf.org/doc/html/rfc5322

$3

| 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][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][unicode-regexp-flag] 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.).

[unicode-regexp-flag]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Regular_expressions/Unicode_character_class_escape
[unicode-latin-chars]: https://en.wikipedia.org/w/index.php?title=Latin_script_in_Unicode&oldid=1210023145#Table_of_characters

$3

| Unicode Character Class | Reference of Included Characters |
| :---------------------- | :----------------------------------------------------- |
| \p{Script=Latin}` | [Unicode Latin Script Characters][unicode-latin-chars] |

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