string-input

v1.0.0-alpha.13

Published

2 months ago

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

Downloads

0High
0Medium
0Low

zanerock

string-input

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

This package is currently a prototype.

Install

npm i string-input

Usage

General usage:

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:

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

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 '[email protected]' 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:

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

API generated with dmd-readme-api.

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.

`BooleanString(input, options)` ⇒ `boolean` ↱source code ⇧global function index

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

Returns: boolean - A primitive boolean.

`CardNumber(input, options)` ⇒ `string` ↱source code ⇧global function index

Validates an input string as a syntactically valid card number.

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

`DateTime(input, options)` ⇒ `DateTimeData` ↱source code ⇧global function index

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.

Returns: DateTimeData - The date-time data.

`Day(input, options)` ⇒ `DayData` ↱source code ⇧global function index

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

Returns: DayData - The day/date data.

`EIN(input, options)` ⇒ `string` ↱source code ⇧global function index

Validates the input as a valid EIN.

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

`Email(input, options)` ⇒ `EmailData` ↱source code ⇧global function index

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) [email protected]', 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 allowIPV4andallowIPV6are essentially ignored. | |options.allowIPV4|boolean| | Allows IPV4 domain literal values. Note that any loopback address will still cause a validation error unlessallowLocalHostis also set true. SeeallowAnyDomainLiteral, 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| | Allowslocalhostdomain value or (whenallowIPV6and/orallowIPV4also set true) loopback IP addresses. | |options.allowedTLDs|object.<string, true>| | 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 thegetLatestTLDs, 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 '[email protected]' and '[email protected]'. Initial periods are ignored soexcludeDomains: ['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.

`Integer(input, options)` ⇒ `number` ↱source code ⇧global function index

Parses and validates an input string as an integer.

Returns: number - A primitive integer.

`Numeric(input, options)` ⇒ `number` ↱source code ⇧global function index

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

Returns: number - A primitive number.

`SSN(input, options)` ⇒ `string` ↱source code ⇧global function index

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

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

`TimeOfDay(input, options)` ⇒ `TimeData` ↱source code ⇧global function index

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.

Returns: TimeData - The parsed time data.

`ValidatedString(input, options)` ⇒ `string` ↱source code ⇧global function index

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

Returns: string - Returns the input.

`DateTimeData` : `object` ↱source code ⇧global typedef index

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

`DayData` ↱source code ⇧global typedef index

Represents the components of specific day.

Properties

`EmailData` ↱source code ⇧global typedef index

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

`TimeData` ↱source code ⇧global typedef index

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

`getLatestTLDs()` ⇒ `Promise.<object>` ↱source code ⇧global function index

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.<object> - A Promise resolving to an object whose keys are valid domains; the value of each entry is true. ASCII characters are always lowercased, but the international domains are not transformed after decoding and may contain uppercase non-ASCII unicode characters per [RFC 4343](https://www.rfc-editor.org/rfc/ rfc4343).

Category: Utils

Common description field and `toString()`

All the type functions provide a description field for use in reporting issues or describing the type. E.g., EIN.description = 'EIN'. They also override the toString() function, which will print the description.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

string-input

Install

Usage

Empty string handling

Custom validation functions

Invoking with context

API reference

BooleanString(input, options) ⇒ boolean ↱source code ⇧global function index

CardNumber(input, options) ⇒ string ↱source code ⇧global function index

DateTime(input, options) ⇒ DateTimeData ↱source code ⇧global function index

Day(input, options) ⇒ DayData ↱source code ⇧global function index

EIN(input, options) ⇒ string ↱source code ⇧global function index

Email(input, options) ⇒ EmailData ↱source code ⇧global function index

Integer(input, options) ⇒ number ↱source code ⇧global function index

Numeric(input, options) ⇒ number ↱source code ⇧global function index

SSN(input, options) ⇒ string ↱source code ⇧global function index

TimeOfDay(input, options) ⇒ TimeData ↱source code ⇧global function index

ValidatedString(input, options) ⇒ string ↱source code ⇧global function index

DateTimeData : object ↱source code ⇧global typedef index

DayData ↱source code ⇧global typedef index

EmailData ↱source code ⇧global typedef index

TimeData ↱source code ⇧global typedef index

getLatestTLDs() ⇒ Promise.<object> ↱source code ⇧global function index

Common description field and toString()

`BooleanString(input, options)` ⇒ `boolean` ↱source code ⇧global function index

`CardNumber(input, options)` ⇒ `string` ↱source code ⇧global function index

`DateTime(input, options)` ⇒ `DateTimeData` ↱source code ⇧global function index

`Day(input, options)` ⇒ `DayData` ↱source code ⇧global function index

`EIN(input, options)` ⇒ `string` ↱source code ⇧global function index

`Email(input, options)` ⇒ `EmailData` ↱source code ⇧global function index

`Integer(input, options)` ⇒ `number` ↱source code ⇧global function index

`Numeric(input, options)` ⇒ `number` ↱source code ⇧global function index

`SSN(input, options)` ⇒ `string` ↱source code ⇧global function index

`TimeOfDay(input, options)` ⇒ `TimeData` ↱source code ⇧global function index

`ValidatedString(input, options)` ⇒ `string` ↱source code ⇧global function index

`DateTimeData` : `object` ↱source code ⇧global typedef index

`DayData` ↱source code ⇧global typedef index

`EmailData` ↱source code ⇧global typedef index

`TimeData` ↱source code ⇧global typedef index

`getLatestTLDs()` ⇒ `Promise.<object>` ↱source code ⇧global function index

Common description field and `toString()`