usertools

Assorted methods for working with user metadata

A username is a unique, human-readable identifier for a user. They are used in a wide variety of contexts, such as a URL to link to a specific person's profile page on a social media site, or as the name of a home directory to hold a user's data.

This module makes it easier to support friendly usernames by providing common methods for processing and validating them.

Usernames are categorized into two groups, "normalized" and "canonical". A normalized username is one that has been prepared for comparison with other usernames, such that two visually similar usernames (i.e. those different only in case or punctuation) will be considered identical after normalization. A canonical username is simply one that has not been normalized. With these semantics, we can make a system that respects vanity names with punctuation in them, while actively preventing the creation of new usernames that are confusingly similar to existing ones.

Contents

• Why?
• Install
• Usage
• API
• Contributing
• License

Why?

• Consistent validation of usernames.
• Easier database queries.

Install

npm install @noirdoor/usertools --save

Usage

Get it into your program.

const usertools = require('@noirdoor/usertools');

API

punctuationRegex

Type: RegExp

Pattern for matching non-alphanumeric characters.

usernameRegex

Type: RegExp

Pattern for matching all valid usernames (regardless of normalization).

validateUsername(username, option)

Returns the username as-is if it is valid (regardless of normalization), otherwise throws an error whose message describes a constraint that has been violated.

Note that the validate option is implicitly always true for this method.

validateUsername('Jazz-Master');   // => 'Jazz-Master'
validateUsername('Jazz-Master-');  // Error: Username must end with an alphanumeric character

validateUsername.silent(username, option)

Returns an object of username validation problems. If username is valid (regardless of normalization), the object will be empty, otherwise it will contain messages describing each constraint that was violated.

validateUsername.silent('I-Am-Okay');      // {}
validateUsername.silent('IEndWithABang!')  // { invalidEnd : 'Username must end with an alphanumeric character' }

Problem	Description
tooShort	The username is falsey. If the allowEmpty option is set to true, this will never be returned.
tooLong	The username is more than thirty characters.
doubleHyphen	The username has at least two consecutive hyphens (--).
invalidStart	The username has a non-alphanumeric first character.
invalidEnd	The username has a non-alphanumeric last character.
invalidChars	The username has a character that is neither alphanumeric, nor a hyphen.

isValidUsername(username, option)

Returns true if the username is valid, as determined by usernameRegex, otherwise returns false.

Note that the validate option is implicitly always true for this method, but validation errors will be represented via the returned boolean instead of being thrown. If the allowEmpty option is set to true, a falsey username is treated as valid.

isValidUsername('Jazz-Master-1');   // => true
isValidUsername('-Jazz-Master-1');  // => false

normalizeUsername(username, option)

Returns the username in lowercase, with all non-alphanumeric characters removed.

Note that validation happens before normalization. Set the validate option to false if you want to force normalization of invalid usernames, but note that the return value is then not guaranteed to be a valid username, since it could exceed the maximum length limit for valid usernames.

normalizeUsername('Jazz-Master-1');  // => 'jazzmaster1'

isNormalizedUsername(username, option)

Returns true if the username is all lowercase and only contains alphanumeric characters, otherwise returns false.

isNormalizedUsername('Jazz-Master-1');  // => false
isNormalizedUsername('jazzmaster1');    // => true

username

Type: string
Example: Jazz-Master

option

Type: object

validate

Type: boolean
Default: true

Throw when username is invalid, as determined by validateUsername().

allowEmpty

Type: boolean
Default: false

Allow username to be falsey, causing it to be treated as valid and normalized. This is useful to avoid errors being thrown when a form field has not been filled out yet, for example.

Note that this option only has an effect when validation is enabled. If you set validate to false, empty usernames will always be allowed and this option will be ignored. File an issue if you want to prevent empty usernames while still disabling other validation constraints.

Contributing

See our contributing guidelines for more details.

1. Fork it.
2. Make a feature branch: git checkout -b my-new-feature
3. Commit your changes: git commit -am 'Add some feature'
4. Push to the branch: git push origin my-new-feature
5. Submit a pull request.

License

Copyright © Noirdoor. All rights reserved.