string-input

 

A library to validate user input strings; compatible with command-line-args.

This package is currently a prototype.

- Install
- Usage
- Empty string handling
- Custom validation functions
- Invoking with context
- API reference
- Common description field and toString()

Install

``bash
npm i string-input
`

Usage

General usage:

`javascript
import { readFileSync } from 'node:fs'
import { Day, Email } from 'string-input'

const csv = readFileSync(process.env.FILE_PATH, { encoding: 'utf8' })
const lines = csv.split('\n') // of course in reality we'd use a library here

for (const line of lines) {
const [name, email, birthday] = line.split(/\s,\s/)
// validate contents
Email(email)
const bdayBoundary = new Date()
bdayBoundary = bdayBoundary.setYear(bdayBoundary.getFullYear() - 125)
Day(birthday, { after: bdayBoundary }) // no one's older than 125
}
`

With command-line-args (or similar), you can make set the type options directly on the option specification:

`javascript
import commandLineArgs from 'command-line-args'
import { Day, Email, ValidatedString }

const bdayBoundary = new Date()
bdayBoundary = bdayBoundary.setYear(bdayBoundary.getFullYear() - 125)

const optionSpec = [
{ name: 'name', defaultOption: true, type: ValidatedString, maxLength: 40 },
{ name: 'birthday', type: Date, after: bdayBoundary },
{ name: 'email', type: Email }
]

const options = commandLineArgs(optionSpec)
`

See notes on invoking with context

Empty string handling

By default, all type functions accept the empty string ('') as input, which results in a return value of undefined. In that case, no other validation checks are performed except for the required validation, which, if true, will cause the type function to reject the empty string and throw ArgumentMissingError.

Custom validation functions

Both validateInput and validateValue can be used for custom validation. validateInput looks at the original input and is called after all other input validations but before input is converted to value. validateValue is then called after any native value validations.

These functions each take two arguments: either the original input or the processed value, respectively, and an options object containing all the original options passed into the type function or set on the context plus input (which is useful for validateValue which otherwise wouldn't see the original input), if any. E.g.:

`javascript
const options = {
name: 'email',
noPlusEmails: true,
propertyForValidationFunction: 'BAIL OUT!',
validateInput: (input, { propertyForValidationFunction }) => {
if (propertyForValidationFunction === 'BAIL OUT!') {
// on error, we return the 'issue description', which will be used to construct an error message that
// incorporates the argument name and value
return is bailing out
}
},
}
`

The validate functions _must_ return true if validated. Any non-true result is treated as indicative of failure. If the validation function returns a string, than that is treated as an explanation of the issue and it is embedded in a string like: ${type} ${name} input '${input} ${result}. E.g., if our validation function returns 'contains offensive words', then the error message raised would be something like, "Email personalEmail input 'asshat@foo.com' contains offensive words."

Invoking with context

All the functions will take their options either 1) passed in as the second argument or 2) from the this context (passed in options override this options). This allows you do something like:

`javascript
const context = { allowQuotedLocalPart: true, type: Email }
context.type('"quoted local part"@foo.com') // is valid because context is treated as this
`

This is how this library integrates with command-line-args. You can specify the options right in the option spec and internally, the type function is invoked like in our example above.


API reference


- Functions:
- BooleanString(): Parses and validates an input string as a boolean.
- CardNumber(): Validates an input string as a syntactically valid card number.
- DateTime(): Parses and validates a wide range of date-time formats.
- Day(): Parses and validates input string as a specific day (date).
- EIN(): Validates the input as a valid EIN.
- Email(): Parses and validates an input string as a valid email address according to RFC 5322 (email messaging), RFC 6531/6532 (internationalized email), and RFC 5890 (internationalized domain names).
- Integer(): Parses and validates an input string as an integer.
- Numeric(): Parses and validates an input string as a valid number (float).
- SSN(): Parses and validates a string as a valid Social Security Number, with our without dashes.
- TimeOfDay(): Parses and validates the input as a time-of-day.
- ValidatedString(): Validates a string according to the provided options.
- _Utils_
- getLatestTLDs(): Dynamically retrieves the latest list of valid TLDs from the Internet Assigned Numbers Authority (IANA).

- Typedefs:
- DateTimeData: Date-time components.
- DayData: Represents the components of specific day.
- EmailData: Email address and components.
- TimeData: Represents the time components.

$3

Parses and validates an input string as a boolean. By default recognizes true/t/yes/y/any positive number as true
and false/f/no/n/0 as false (case insensitive).


| Param | Type | Default | Description |
| --- | --- | --- | --- |
| input | string | | The input string. |
| options | object | | The validation options. |
| options.name | string | | The 'name' by which to refer to the input when generating error messages for the user. |
| [options.status] | number | 400 | The HTTP status to use when throwing ArgumentInvalidError errors. This can be used to mark arguments specified by in code or configurations without user input. |
| [options.required] | boolean | false | If true, then the empty string is rejected and ArgumentMissingError is thrown. |
| [options.noAbbreviations] | boolean | false | Disallow t/f/y/n responses. |
| [options.noNumeric] | boolean | false | Disallow numeric answers. |
| [options.noYesNo] | boolean | false | Disallow yes/no/y/n responses. |
| [options.treatNegativeValuesAsFalse] | boolean | false | When true, inputs that parse as a negative numeric value will be treated as false instead of raising an exception. |
| [options.validateInput] | function | | A custom validation function which looks at the original input string. See the custom validation functions section for details on input and return values. |
| [options.validateValue] | function | | A custom validation function which looks at the transformed value. See the custom validation functions section for details on input and return values. |

Returns: boolean - A primitive boolean.

$3

Validates an input string as a syntactically valid card number.


| Param | Type | Default | Description |
| --- | --- | --- | --- |
| input | string | | The input string. |
| options | object | | The validation options. |
| options.name | string | | The 'name' by which to refer to the input when generating error messages for the user. |
| [options.status] | number | 400 | The HTTP status to use when throwing ArgumentInvalidError errors. This can be used to mark arguments specified by in code or configurations without user input. |
| [options.required] | boolean | false | If true, then the empty string is rejected and ArgumentMissingError is thrown. |
| [options.iins] | Array. | | A list of acceptable Industry Identifier Numbers, or initial card numbers. E.g., iins : ['123'] would only accept cards with an account number starting with '123'. If left undefined, then all otherwise valid card numbers are treated as valid. |
| [options.lengths] | Array. | [12, 13, 14, 15, 16, 17, 18, 19] | An array of integers defining acceptable card lengths. The default value is any length between 12 and 19, inclusive. |
| [options.validateInput] | function | | A custom validation function which looks at the original input string. See the custom validation functions section for details on input and return values. |
| [options.validateValue] | function | | A custom validation function which looks at the transformed value. See the custom validation functions section for details on input and return values. |

Returns: string - A number-string with no delimiters. Note, there are valid card numbers beginning with 0.

$3

Parses and validates a wide range of date-time formats. Accepts RFC 8601 style date times (e.g.:
2024-01-01T12:30:00Z) as well RFC-2822 style dates (e.g., '1 Jan 2024'), year-first, and US style dates combined
with standard (AP/PM), twenty-four hour, and military time designations in either '[date] [time]' or '[time] [date]'
order.


| Param | Type | Default | Description |
| --- | --- | --- | --- |
| input | string | | The input string. |
| options | object | | The validation options. |
| options.name | string | | The 'name' by which to refer to the input when generating error messages for the user. |
| [options.status] | number | 400 | The HTTP status to use when throwing ArgumentInvalidError errors. This can be used to mark arguments specified by in code or configurations without user input. |
| [options.required] | boolean | false | If true, then the empty string is rejected and ArgumentMissingError is thrown. |
| [options.localTimezone] | string | | For otherwise valid date time input with no time zone component, then the localTimezone must be specified as an option. This value is only used if the timezone is not specified in the input string and any timezone specified in the input string will override this value. |
| [options.min] | string \| number \| Date | | The earliest valid time, inclusive. This may be specified as any string parseable by this function, milliseconds since the epoch (UTC), or a Date object. |
| [options.max] | string \| number \| Date | | The latest valid time, inclusive. This may be specified as any string parseable by this function, milliseconds since the epoch (UTC), or a Date object. |
| [options.noEod] | boolean | false | Disallows the special times '24:00:00', which represents the last moment of the day. |
| [options.validateInput] | function | | A custom validation function which looks at the original input string. See the custom validation functions section for details on input and return values. |
| [options.validateValue] | function | | A custom validation function which looks at the transformed value. See the custom validation functions section for details on input and return values. |

Returns: DateTimeData - The date-time data.

$3

Parses and validates input string as a specific day (date). Can handle year first and US format, with or without
delimiters, along with RFC 2822 style dates like '1 Jan 2024'.


| Param | Type | Default | Description |
| --- | --- | --- | --- |
| input | string | | The input string. |
| options | object | | The validation options. |
| options.name | string | | The 'name' by which to refer to the input when generating error messages for the user. |
| [options.status] | number | 400 | The HTTP status to use when throwing ArgumentInvalidError errors. This can be used to mark arguments specified by in code or configurations without user input. |
| [options.required] | boolean | false | If true, then the empty string is rejected and ArgumentMissingError is thrown. |
| [options.max] | string \| number \| Date | | The latest day to be considered valid. |
| [options.min] | string \| number \| Date | | The earliest day to be considered valid. |
| [options.validateInput] | function | | A custom validation function which looks at the original input string. See the custom validation functions section for details on input and return values. |
| [options.validateValue] | function | | A custom validation function which looks at the transformed value. See the custom validation functions section for details on input and return values. |

Returns: DayData - The day/date data.

$3

Validates the input as a valid EIN.


| Param | Type | Default | Description |
| --- | --- | --- | --- |
| input | string | | The input string. |
| options | object | | The validation options. |
| options.name | string | | The 'name' by which to refer to the input when generating error messages for the user. |
| [options.status] | number | 400 | The HTTP status to use when throwing ArgumentInvalidError errors. This can be used to mark arguments specified by in code or configurations without user input. |
| [options.required] | boolean | false | If true, then the empty string is rejected and ArgumentMissingError is thrown. |
| [options.validateInput] | function | | A custom validation function which looks at the original input string. See the custom validation functions section for details on input and return values. |
| [options.validateValue] | function | | A custom validation function which looks at the transformed value. See the custom validation functions section for details on input and return values. |

Returns: string - A canonically formatted EIN 'XX-XXXXXXX'.

$3

Parses and validates an input string as a valid email address according to RFC 5322 (email messaging), RFC 6531/6532
(internationalized email), and RFC 5890 (internationalized domain names). Validation happens in two general steps.
First, the input is parsed according to the relevant RFC specifications. If this is successful, then the result will
always contain a username,address, and either domain or domainLiteral fields. If these are present, you know
that the email was successfully parsed. The second stage validates the parsed email components against the provided
options or option defaults. Therefore, you can have a situation where an email address is valid according to the
specs and can be parsed without an issue, but is still _invalid_ according to the effective options (or defaults).

By default, the validation restricts possible features in the email address—such as comments and domain
literals—which are not normally wanted in basic email address. In particular, the default options:
- disallow embedded comments,
- disallow domain literal (IP addressing),
- disallow the 'localhost' domain,
- restricts possible TLDs to known good TLDs,
- restricts domain names to valid subdomain and TLDs based on DNS and ICANN rules beyond the email address
specification, and
- performs extra validation for known provider domains google.com and hotmail.com.

Options can be explicitly defined to allow for a more liberal or restrictive validation.

These options are largely determined by the the
true-email-validator
validateEmail() function,
which is used internally to validate the email. All options are passed directly to the validateEmail() function.


| Param | Type | Default | Description |
| --- | --- | --- | --- |
| input | string | | The input string. |
| options | object | | The validation options. |
| options.name | string | | The 'name' by which to refer to the input when generating error messages for the user. |
| [options.status] | number | 400 | The HTTP status to use when throwing ArgumentInvalidError errors. This can be used to mark arguments specified by in code or configurations without user input. |
| options.allowComments | boolean | | If true, allows embedded comments in the address like '(comment) john@foo.com', which are disallowed by default. Note, the comments, if present, will be extracted regardless of this setting, the result valid field will just be set false and an issue will be reported. |
| options.allowAnyDomain | boolean | | If true, then overrides all default restrictions and format checks of the domain value and allows any syntactically valid domain value except a localhost name or address (unless allowLocalHost is also set true). Note that impossible sub-domain labels (e.g., a label more than 63 characters long or a single digit) or TLDs (e.g. '123') will still trigger an invalid result. Otherwise, the domain value is verified as recognizable as a domain name (as opposed to an IP address, for instance). |
| options.allowAnyDomainLiteral | boolean | | If true, then overrides default restrictions and format checks of domain literal values and allows any syntactically valid domain literal value that is not a localhost address ( unless allowLocalhost is also true). In general, domain literal values point to IPV4/6 addresses and the validation will (when allowIP4 and/orallowIPV6 are true), allow valid IP address values but would reject other domain literal values, unless this value is set true. Note, if this value is true then allowIPV4 and allowIPV6 are essentially ignored. |
| options.allowIPV4 | boolean | | Allows IPV4 domain literal values. Note that any loopback address will still cause a validation error unless allowLocalHost is also set true. See allowAnyDomainLiteral, allowIPV6, and allowLocahost. |
| options.allowIPV6 | boolean | | Allows IPV6 domain literal values. Note that the localhost address will still cause a validation error unless allowLocaHost is also set true. See allowAnyDomainLiteral, allowIPV4, and allowLocahost. |
| options.allowLocalhost | boolean | | Allows localhost domain value or (when allowIPV6 and/or allowIPV4 also set true) loopback IP addresses. |
| options.allowedTLDs | object. | | By default, the TLD portion of a domain name will be validated against known good TLDs. To limit this list or use an updated list, set this value to an array of acceptable TLDs or a map with valid TLD keys (the value is not used). You can use the getLatestTLDs, also exported by this package, to get an object defining the most current TLDs as registered with ICANN. See arbitraryTLDs. |
| options.allowQuotedLocalPart | boolean | | Overrides default restriction and allows quoted username/local parts. |
| options.arbitraryTLDs | boolean | | Skips the 'known TLD' check and allows any validly formatted TLD name. This is still restricted by the TLD name restrictions which are tighter than standard domain labels. |
| options.excludeChars | boolean | | Either a string or array of excluded characters. In the array form, it will match the whole string, so you can also use this to exclude specific character sequences. |
| options.excludeDomains | boolean | | An array of domains to exclude. Excluding a domain also excludes all subdomains so eclxuding 'foo.com' would exclude 'john@foo.com' and 'john@bar.foo.com'. Initial periods are ignored so excludeDomains: ['com']', and excludeDomains: ['.com'] are equivalent. |
| options.noDomainSpecificValidation | boolean | | Setting this to true will skip domain specific validations. By default, the validation includes domain specific checks for 'google.com' and 'hotmail.com' domains. These domains are known to have more restrictive policies regarding what is and is not a valid email address. |
| options.noLengthCheck | boolean | | If true, then skips username (local part) and total email address length restrictions. Note that domain name label lengths are still enforced. |
| options.noPlusEmails | boolean | | If true, then '+' is not allowed in the username/local part. This is equivalent to setting excludeChars = '+'. |
| options.noTLDOnly | boolean | | If true, then disallows TLD only domains in an address like 'john@com'. |
| options.noNonASCIILocalPart | boolean | | If true, then disallows non-ASCII/international characters in the username/local part of the address. |
| [options.validateInput] | function | | A custom validation function which looks at the original input string. See the custom validation functions section for details on input and return values. |
| [options.validateValue] | function | | A custom validation function which looks at the transformed value. See the custom validation functions section for details on input and return values. |

Returns: EmailData - Email data object.

$3

Parses and validates an input string as an integer.


| Param | Type | Default | Description |
| --- | --- | --- | --- |
| input | string | | The input string. |
| options | object | | The validation options. |
| options.name | string | | The 'name' by which to refer to the input when generating error messages for the user. |
| [options.status] | number | 400 | The HTTP status to use when throwing ArgumentInvalidError errors. This can be used to mark arguments specified by in code or configurations without user input. |
| [options.allowLeadingZeros] | boolean | false | Overrides default behavior which rejects strings with leading zeros. |
| options.divisibleBy | number | | Requires the resulting integer value be divisible by the indicated number ( which need not itself be an integer). |
| options.max | number | | The largest value considered valid. |
| options.min | number | | The smallest value considered valid. |
| [options.validateInput] | function | | A custom validation function which looks at the original input string. See the custom validation functions section for details on input and return values. |
| [options.validateValue] | function | | A custom validation function which looks at the transformed value. See the custom validation functions section for details on input and return values. |

Returns: number - A primitive integer.

$3

Parses and validates an input string as a valid number (float).


| Param | Type | Default | Description |
| --- | --- | --- | --- |
| input | string | | The input string. |
| options | object | | The validation options. |
| options.name | string | | The 'name' by which to refer to the input when generating error messages for the user. |
| [options.status] | number | 400 | The HTTP status to use when throwing ArgumentInvalidError errors. This can be used to mark arguments specified by in code or configurations without user input. |
| options.allowLeadingZeros | boolean | | Overrides default behavior which rejects strings with leading zeros. |
| options.divisibleBy | number | | Requires the resulting integer value be divisible by the indicated number ( which need not be an integer). |
| options.max | number | | The largest value considered valid. |
| options.min | number | | The smallest value considered valid. |
| [options.validateInput] | function | | A custom validation function which looks at the original input string. See the custom validation functions section for details on input and return values. |
| [options.validateValue] | function | | A custom validation function which looks at the transformed value. See the custom validation functions section for details on input and return values. |

Returns: number - A primitive number.

$3

Parses and validates a string as a valid Social Security Number, with our without dashes.


| Param | Type | Default | Description |
| --- | --- | --- | --- |
| input | string | | The input string. |
| options | object | | The validation options. |
| options.name | string | | The 'name' by which to refer to the input when generating error messages for the user. |
| [options.status] | number | 400 | The HTTP status to use when throwing ArgumentInvalidError errors. This can be used to mark arguments specified by in code or configurations without user input. |
| [options.validateInput] | function | | A custom validation function which looks at the original input string. See the custom validation functions section for details on input and return values. |
| [options.validateValue] | function | | A custom validation function which looks at the transformed value. See the custom validation functions section for details on input and return values. |

Returns: string - A canonically formatted SSN like 'XX-XXX-XXXX'.

$3

Parses and validates the input as a time-of-day. Because there is no date component and some timezones would be
ambiguous, this type does not recognize nor accepts timezone specification.


| Param | Type | Default | Description |
| --- | --- | --- | --- |
| input | string | | The input string. |
| options | object | | The validation options. |
| options.name | string | | The 'name' by which to refer to the input when generating error messages for the user. |
| [options.status] | number | 400 | The HTTP status to use when throwing ArgumentInvalidError errors. This can be used to mark arguments specified by in code or configurations without user input. |
| options.max | string | | A string, parseable by this function, representing the latest valid time. |
| options.min | string | | A string, parseable by this function, representing the earliest valid time. |
| options.noEod | boolean | | Disallows the special times '24:00:00', which represents the last moment of the day. |
| [options.validateInput] | function | | A custom validation function which looks at the original input string. See the custom validation functions section for details on input and return values. |
| [options.validateValue] | function | | A custom validation function which looks at the transformed value. See the custom validation functions section for details on input and return values. |

Returns: TimeData - The parsed time data.

$3

Validates a string according to the provided options. This is useful when there's not a pre-built type like Email.


| Param | Type | Default | Description |
| --- | --- | --- | --- |
| input | string | | The input string. |
| options | object | | The validation options. |
| options.name | string | | The 'name' by which to refer to the input when generating error messages for the user. |
| [options.status] | number | 400 | The HTTP status to use when throwing ArgumentInvalidError errors. This can be used to mark arguments specified by in code or configurations without user input. |
| [options.required] | boolean | false | If true, then the empty string is rejected and ArgumentMissingError is thrown. |
| [options.after] | string | | The input must be or lexicographically sort after this string. |
| [options.before] | string | | The input must be or lexicographically sort before this string. |
| [options.endsWith] | string | | The input string must end with the indicated string. |
| [options.maxLength] | number | | The longest valid input string in terms of characters. |
| [options.matchRe] | string \| RegExp | | The input string must match the provided regular expression. Specifying a string which is an invalid regular expression will cause an exception to be thrown. |
| [options.minLength] | number | | The shortest valid input string in terms of characters. |
| [options.oneOf] | Array. | | The input string must be exactly one of the members of this array. |
| [options.startsWith] | string | | The input string must start with the indicated string. |
| [options.validateInput] | function | | A custom validation function which looks at the original input string. See the custom validation functions section for details on input and return values. |
| [options.validateValue] | function | | A custom validation function which looks at the transformed value. See the custom validation functions section for details on input and return values. |

Returns: string - Returns the input.

$3

Date-time components.

Properties

| Name | Type | Description |
| --- | --- | --- |
| isDateTimeObject() | function | Used for duck-typing. Always returns true. |
| getYear() | function | The year component of the date-time (integer). |
| getMonth() | function | The month of the year (1-indexed; integer). |
| getDayOfMonth() | function | The numerical day of the month (integer). |
| isEod() | function | Whether or not the time is the special 'end of day' time. |
| getHours() | function | The hours component of the date-time (integer). |
| getMinutes() | function | The minutes component of the date-time (integer). |
| getSeconds() | function | The seconds component of the date-time (integer). |
| getFractionalSeconds() | function | The fractional seconds component of the date-time. |
| getMilliseconds() | function | The fractional seconds component of the date-time expressed as milliseconds (integer). |
| getTimezoneOffset() | function | The timezone offset of the original input string in minutes. May be positive, or negative (integer). |
| getDate() | function | A Date object corresponding to the original input string. |
| valueOf() | function | The milliseconds since the epoch (UTC) represented by the original input string (integer). |

$3

Represents the components of specific day.

Properties

| Name | Type | Description |
| --- | --- | --- |
| isDateTimeObject() | function | Used for duck-typing. Always returns true. |
| getYear() | function | The year component of the date-time (integer). |
| getMonth() | function | The month of the year (1-indexed) (integer). |
| getDayOfMonth() | function | The numerical day of the month (integer). |
| getDate() | function | A Date object corresponding to the original input string. The time components of the Date will all be set to 0 and the timezone is always UTC. |
| valueOf() | function | The seconds since the epoch (UTC) represented by the original input string (at the start of the UTC day). |

$3

Email address and components.

Properties

| Name | Type | Description |
| --- | --- | --- |
| address | string | The normalized email address. The domain portion, if any, will always be in lowercase ( the domain property will preserve the original case). |
| username | string | The username or local part of the email address. |
| domain | string \| undefined | The domain value, if present. Exactly one of domain and domainLiteral will always be defined for a syntactically valid email address. The original case of the domain is preserved. |
| domainLiteral | string \| undefined | The domain literal value, if present. Exactly one of domain and domainLiteral will always be defined for a syntactically valid email address. |
| commentLocalPartPrefix | string \| undefined | The embedded comment, if any, immediately before the address username (local part). |
| commentLocalPartSuffix | string \| undefined | The embedded comment, if any, immediately following the address username (local part). |
| commentDomainPrefix | string \| undefined | The embedded comment, if any, immediately before the domain or domain literal. |
| commentDomainSuffix | string \| undefined | The embedded comment, if any, immediately after the domain or domain literal. |

$3

Represents the time components.

Properties

| Name | Type | Description |
| --- | --- | --- |
| isEod() | function | Whether or not the time is the special 'end of day' time. |
| getHours() | function | The hours component of the date-time (integer). |
| getMinutes() | function | The minutes component of the date-time (integer). |
| getSeconds() | function | The seconds component of the date-time (integer). |
| getFractionalSeconds() | function | The fractional seconds component of the date-time; this will always be a float less than 1. |
| getMilliseconds() | function | The fractional seconds component of the date-time expressed as milliseconds (integer). |
| valueOf() | function | Seconds (including fractional seconds) since 00:00:00. |

$3

Dynamically retrieves the latest list of valid TLDs from the Internet Assigned Numbers Authority (IANA). The
resolved result can be passed to the Email type function allowedTLDs option.

Note, international domains are decoded and both the decoded (international domain) and encoded ('xn--) domain
will be present in the results object as both represent valid domains from a user's point of view.

This function is re-exported from the true-email-validator
module.

Returns: Promise.