Sentence

Description

Sentence is a fluent TypeScript sentence builder for constructing grammatically correct error and validation messages. It provides a chainable builder API with built-in support for singular and plural nouns, a rich library of pre-defined nouns and superlatives, and automatic formatting — making it easy to produce consistent, human-readable messages across the @nuov.io ecosystem.

Installation

npm install @nuov.io/sentence

Usage

Basic singular sentence

import { Sentence, Nouns, Superlatives } from '@nuov.io/sentence';

Sentence.the(Nouns.ARGUMENT).is(Superlatives.BLANK).period();
// => "The argument is blank."

Sentence.the(Nouns.PROPERTY, 'email').is(Superlatives.UNDEFINED).period();
// => "The property 'email' is undefined."

Sentence.the(Nouns.ARGUMENT, 'age', 42)
  .is(Superlatives.LESS_THAN)
  .the(Nouns.MINIMUM, undefined, 50)
  .period();
// => "The argument 'age' (42) is less than the minimum (50)."

Sentence.the(Nouns.CLASS, undefined, 'Request')
  .doesNot(Superlatives.EXIST)
  .period();
// => "The class (Request) does not exist."

Basic plural sentence

import { Sentence, Nouns, Superlatives } from '@nuov.io/sentence';

Sentence.allThe(Nouns.ELEMENTS, 'a', 'b', 'c').are(Superlatives.EMPTY).period();
// => "All the elements 'a', 'b' & 'c' are empty."

Sentence.the(Nouns.ARGUMENTS, 'foo', 'bar').are(Superlatives.BLANK).period();
// => "The arguments 'foo', 'bar' are blank."

Sentence.the(Nouns.ARGUMENTS, 'alpha', 'bravo', 'charlie')
  .are(Superlatives.UNDEFINED)
  .period();
// => "The arguments 'alpha', 'bravo' & 'charlie' are undefined."

Sentence.the(Nouns.ARGUMENTS, 'dog', 'cat', 'mouse', 'bee')
  .are(Superlatives.LOCKED)
  .period();
// => "The arguments 'dog', 'cat', 'mouse' & 'bee' are locked."

Chaining with and

import { Sentence, Nouns, Superlatives } from '@nuov.io/sentence';

Sentence.the(Nouns.ARGUMENT, 'json')
  .is(Superlatives.UNDEFINED)
  .and()
  .the(Nouns.OBJECT, 'searchParams')
  .is(Superlatives.EMPTY)
  .period();
// => "The argument 'json' is undefined and the object 'searchParams' is empty."

Current tense

import { Sentence, Nouns, Superlatives } from '@nuov.io/sentence';

Sentence.the(Nouns.ARGUMENTS, 'alpha', 'bravo', 'charlie')
  .are(Superlatives.NULL)
  .period();
// => "The arguments 'alpha', 'bravo' & 'charlie' are null."

Sentence.the(Nouns.ARGUMENTS, 'x-ray', 'yankee', 'zulu')
  .areNot(Superlatives.VALID)
  .period();
// => "The arguments 'x-ray', 'yankee' & 'zulu' are not valid."

Sentence.the(Nouns.ARGUMENT, 'enabled').does(Superlatives.EXIST).period();
// => "The argument 'enabled' does exist."

Sentence.the(Nouns.ARGUMENT, 'disabled').doesNot(Superlatives.EXIST).period();
// => "The argument 'disabled' does not exist."

Sentence.the(Nouns.ARGUMENT, 'size').is(Superlatives.UNDEFINED).period();
// => "The argument 'size' is undefined."

Sentence.the(Nouns.ARGUMENT, 'yourClass').isAnInstanceOf('MyClass').period();
// => "The argument 'yourClass' is an instance of 'MyClass'."

Sentence.the(Nouns.ARGUMENT, 'offset').isNot(Superlatives.DEFINED).period();
// => "The argument 'offset' is not defined."

Sentence.the(Nouns.ARGUMENT, 'yourClass').isNotAnInstanceOf('MyClass').period();
// => "The argument 'yourClass' is not an instance of 'MyClass'."

Past tense

import { Sentence, Nouns, Superlatives } from '@nuov.io/sentence';

Sentence.the(Nouns.ARGUMENT).was(Superlatives.BLANK).period();
// => "The argument was blank."

Sentence.the(Nouns.ARGUMENT).wasNot(Superlatives.BLANK).period();
// => "The argument was not blank."

Sentence.the(Nouns.ARGUMENTS, 'foo', 'bar').were(Superlatives.BLANK).period();
// => "The arguments 'foo', 'bar' were blank."

Sentence.the(Nouns.ARGUMENTS, 'romeo', 'sierra', 'tango')
  .wereNot(Superlatives.VALID)
  .period();
// => "The arguments 'romeo', 'sierra' & 'tango' were not valid."

Conflicts With

import { Sentence, Nouns } from '@nuov.io/sentence';

Sentence.the(Nouns.ARGUMENT, 'cat')
  .conflictsWith()
  .the(Nouns.ARGUMENT, 'dog')
  .period();
// => "The argument 'cat' conflicts with the argument 'dog'."

Contains

import { Sentence, Nouns, Superlatives } from '@nuov.io/sentence';

Sentence.the(Nouns.OBJECT, 'parameters')
  .contains(Superlatives.AN_UNDEFINED_KEY)
  .period();
// => "The object 'parameters' contains an undefined key."

Custom nouns and superlatives

You can create your own nouns and superlatives:

import {
  SingularNoun,
  PluralNoun,
  Superlative,
  Sentence,
} from '@nuov.io/sentence';

const widget = new SingularNoun('widget');
const widgets = new PluralNoun('widgets');
const malformed = new Superlative('malformed');

Sentence.the(widget).is(malformed).period();
// => "The widget is malformed."

Sentence.the(widgets, 'a', 'b').are(malformed).period();
// => "The widgets 'a', 'b' are malformed."

API Reference

Sentence (class)

The main entry point. Provides static factory methods that return the appropriate sentence builder.

Static Methods

| Method | Returns | Description | | ------------------------------------------ | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | Sentence.allThe(pluralNoun, ...names) | PluralSentenceBuilder | Starts a sentence with "all the" + plural noun + comma-separated names (with an ampersand between the last pair of names when names.length > 2). | | Sentence.the(singularNoun) | SingularSentenceBuilder | Starts a sentence with "the" + singular noun. | | Sentence.the(singularNoun, named) | SingularSentenceBuilder | Starts a sentence with "the" + singular noun + name in single quotes. | | Sentence.the(singularNoun, named, value) | SingularSentenceBuilder | Starts a sentence with "the" + singular noun + name in single quotes + value in parentheses. | | Sentence.the(pluralNoun, ...names) | PluralSentenceBuilder | Starts a sentence with "the" + plural noun + comma-separated names (with an ampersand between the last pair of names when names.length > 2). |

SingularSentenceBuilder (class)

A chainable builder for sentences with singular subjects. All builder methods return the SingularSentenceBuilder instance.

Static Methods

| Method | Returns | Description | | --------------------------------------------------------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | SingularSentenceBuilder.the(singularNoun) | SingularSentenceBuilder | Creates a new SingularSentenceBuilder instance starting with "the" + singular noun. | | SingularSentenceBuilder.the(singularNoun, named) | SingularSentenceBuilder | Creates a new SingularSentenceBuilder instance starting with "the" + singular noun + name in single quotes. | | SingularSentenceBuilder.the(singularNoun, named, value) | SingularSentenceBuilder | Creates a new SingularSentenceBuilder instance starting with "the" + singular noun + name in single quotes + value in parentheses. |

Instance Methods

| Method | Returns | Description | | --------------------------------- | ---------- | -------------------------------------------------------------------------------------------------------- | | and() | instance | Appends "and". | | conflictsWith() | instance | Appends "conflicts with". | | contains(superlative) | instance | Appends "contains" + superlative. | | does(superlative) | instance | Appends "does" + superlative. | | doesNot(superlative) | instance | Appends "does not" + superlative. | | is(superlative) | instance | Appends "is" + superlative. | | isAnInstanceOf(className) | instance | Appends "is an instance of" + single quoted class name. | | isNot(superlative) | instance | Appends "is not" + superlative. | | isNotAnInstanceOf(className) | instance | Appends "is not an instance of" + single quoted class name. | | period() | string | Terminates the sentence with a period, capitalizes the first letter, and returns the formatted sentence. | | the(singularNoun) | instance | Appends "the" + singular noun. | | the(singularNoun, named) | instance | Appends "the" + singular noun + name in single quotes. | | the(singularNoun, named, value) | instance | Appends "the" + singular noun + name in single quotes + value in parentheses. | | was(superlative) | instance | Appends "was" + superlative. | | wasNot(superlative) | instance | Appends "was not" + superlative. |

PluralSentenceBuilder (class)

A chainable builder for sentences with plural subjects. All builder methods return the PluralSentenceBuilder instance.

Static Methods

| Method | Returns | Description | | ---------------------------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | PluralSentenceBuilder.allThe(pluralNoun, ...names) | PluralSentenceBuilder | Creates a new PluralSentenceBuilder instance starting with "all the" + plural noun + comma-separated names (with an ampersand between the last pair of names when names.length > 2). | | PluralSentenceBuilder.the(pluralNoun, ...names) | PluralSentenceBuilder | Creates a new PluralSentenceBuilder instance starting with "the" + plural noun + comma-separated names (with an ampersand between the last pair of names when names.length > 2). |

Instance Methods

| Method | Returns | Description | | ------------------------------ | ---------- | ----------------------------------------------------------------------------------------------------------------------------- | | allThe(pluralNoun, ...names) | instance | Appends "all the" + plural noun. | | are(superlative) | instance | Appends "are" + superlative. | | areNot(superlative) | instance | Appends "are not" + superlative. | | period() | string | Terminates the sentence with a period, capitalizes the first letter, and returns the formatted sentence. | | the(pluralNoun, ...names) | instance | Appends "the" + plural noun + comma-separated names (with an ampersand between the last pair of names when names.length > 2). | | were(superlative) | instance | Appends "were" + superlative. | | wereNot(superlative) | instance | Appends "were not" + superlative. |

Nouns (class)

A collection of commonly used singular and plural noun constants.

| Singular | Plural | | ---------------------------- | ----------------------------- | | Nouns.ARGUMENT | Nouns.ARGUMENTS | | Nouns.ARRAY | Nouns.ARRAYS | | Nouns.CLASS | Nouns.CLASSES | | Nouns.COLLECTION | Nouns.COLLECTIONS | | Nouns.ELEMENT | Nouns.ELEMENTS | | Nouns.ENUM | Nouns.ENUMS | | Nouns.ENVIRONMENT_VARIABLE | Nouns.ENVIRONMENT_VARIABLES | | Nouns.ERROR | Nouns.ERRORS | | Nouns.EXAMPLE | Nouns.EXAMPLES | | Nouns.FILE | Nouns.FILES | | Nouns.KEY | Nouns.KEYS | | Nouns.METHOD | Nouns.METHODS | | Nouns.OBJECT | Nouns.OBJECTS | | Nouns.PARAMETER | Nouns.PARAMETERS | | Nouns.PROPERTY | Nouns.PROPERTIES | | Nouns.RESOURCE | Nouns.RESOURCES | | Nouns.RESPONSE | Nouns.RESPONSES | | Nouns.SERVICE | Nouns.SERVICES | | Nouns.TEST | Nouns.TESTS | | Nouns.VALUE | Nouns.VALUES | | Nouns.VARIABLE | Nouns.VARIABLES |

Also includes standalone singular nouns: Nouns.MAXIMUM, Nouns.MAXIMUM_NUMBER_OF_CHARACTERS, Nouns.MAXIMUM_NUMBER_OF_ELEMENTS, Nouns.MINIMUM, Nouns.MINIMUM_NUMBER_OF_CHARACTERS, Nouns.MINIMUM_NUMBER_OF_ELEMENTS.

Superlatives (class)

A collection of commonly used superlative constants. Some examples:

| Category | Constants | | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Types | A_BIGINT, A_BOOLEAN, A_BYTE, A_CHAR, A_CHARACTER, A_DATE, A_DOUBLE, A_FLOAT, A_JWT, A_LONG, A_NUMBER, A_SHORT, A_STRING, A_URL, A_UUID, AN_ARRAY, AN_EMAIL_ADDRESS, AN_ENUM, AN_INTEGER, AN_OBJECT | | States | ACTIVE, ASSIGNED, BLANK, CLOSED, COMPLETE, COMPLETED, DEFINED, DRAFT, EMPTY, ENABLED, EXIST, EXISTS, FOUND LOCKED, MODIFIED, NULL, PENDING, UNDEFINED, UPDATED, VALID | | Comparisons | GREATER_THAN, LESS_THAN, MORE_THAN, TOO_FEW_ELEMENTS , TOO_LONG, TOO_MANY_ELEMENTS, TOO_SHORT | | Cases | LOWER_CASE, UPPER_CASE | | Issues | A_BLANK_ELEMENT, A_DUPLICATE, A_NULL_ELEMENT, A_NULL_KEY, A_NULL_VALUE, A_PADDED_ELEMENT, AN_UNDEFINED_ELEMENT, AN_UNDEFINED_KEY,AN_UNDEFINED_VALUE, ILLEGAL_CHARACTERS, NULL_ELEMENTS, NULL_KEYS, NULL_VALUES, WARNINGS, WHITE_SPACE | | Other | ACKNOWLEDGED, ALREADY_ASSIGNED, COMPARABLE, CURRENT, EXECUTED, EXPIRED, IGNORED, IN_MAINTENANCE_MODE, IN_PROGRESS, ORPHANED, OVERRIDDEN, PADDED, READ_ONLY, STALLED, STARTED, STOPPED, SUPPORTED, TEMPORARILY_UNAVAILABLE, TRANSACTIONAL, TRUSTED, VERIFIED |

SingularNoun (class)

Represents a singular noun (e.g., "argument", "property").

new SingularNoun('widget');

PluralNoun (class)

Represents a plural noun (e.g., "arguments", "properties").

new PluralNoun('widgets');

Superlative (class)

Represents a superlative — a word or phrase used to describe a quantity or state.

new Superlative('malformed');

Noun (interface)

The contract that both SingularNoun and PluralNoun satisfy.

| Property | Type | Description | | ------------ | --------- | ----------------------------------------------- | | isNoun | true | Brand flag to overcome duck-typing limitations. | | isPlural | boolean | Whether the noun is plural. | | isSingular | boolean | Whether the noun is singular. | | text | string | The noun text. |

Section (interface)

The base contract for all sentence sections.

| Property | Type | Description | | -------- | --------------------- | ------------------------------------------------------------------- | | text | string \| undefined | The section text, or undefined if the section produces no output. |

Features

• Fluent builder API — chain methods to construct grammatically correct sentences
• Singular and plural support — correct verb forms for singular (is, was, does) and plural (are, were) subjects
• Pre-defined nouns — Nouns class with common singular/plural noun pairs
• Pre-defined superlatives — Superlatives class with commonly used descriptors
• Named values — automatic formatting of names in quotes and values in parentheses
• Extensible — create custom SingularNoun, PluralNoun, and Superlative instances
• TypeScript-first — full type definitions included
• ESM-only — distributed as an ES module

License

MIT License