The `enumerated-literals` package provides a strongly-typed, type-safe and convenient pattern for defining and manage constant strings in an application.
npm install enumerated-literals
The enumerated-literals package is a _zero-dependency_ package that provides a strongly-typed,
type-safe and convenient pattern for defining, organizing and managing constant string values in an
application.
``bash`
$ npm install enumerated-literals
At it's core, the enumerated-literals package provides a method, enumeratedLiterals, that can beenum
used to define a set of constant string literals in an -like fashion:
`ts`
enumeratedLiterals
literals: L,
options: O
): EnumeratedLiterals
The first argument to the enumeratedLiterals method, L (or Literals), should be a conststring
array of values (readonly string[]) or object values (termed [models][model]), each ofvalue
which contains a key ({ value: string }[]).
The second argument provided to the enumeratedLiterals method, O (orEnumeratedLiteralsOptions
[][options]), should be an object type that contains the options for
the instance (see [Configuration Options][options]).
###### Example
`ts
import { enumeratedLiterals, type EnumeratedLiteralMember } from "enumerated-literals";
const Fruits = enumeratedLiterals(["apple", "banana", "blueberry", "orange"] as const, {});
type Fruit = EnumeratedLiteralMember
Fruits.APPLE; // "apple"
Fruits.BANANA; // "banana"
const doSomethingWithFruit = (fruit: Fruit): void;
doSomethingWithFruit("apple");
`
The primary and original motivation for the enumerated-literals package was the fact that constantenum
string literals are not assignable to their equivalent members:
`ts
enum Fruits {
APPLE = "apple",
BANANA = "banana",
BLUEBERRY = "blueberry",
ORANGE = "orange",
}
function getFruitColor(fruit: Fruits): string {
...
}
// InvalidLiteralValueError: Argument of type '"apple"' is not assignable to parameter of type 'Fruits'
const appleColor = getFruitColor("apple");
`
This means that whenever the getFruitColor function is used throughout an application or codebase,Fruits
it requires also importing , and referencing the argument as Fruits.APPLE. While thisenum
might seem like a small inconvenience, its inflexibility can be a pain point in larger applications
with a significant number of constants that benefit from being defined in an -like fashion.
Additionally, the [EnumeratedLiterals][instance] instance offers built-in type-checking methods
and strongly typed properties, which provide a more convenient and organized way of making
assertions and type-checking values related to the constant string literals the instance is
associated with (see Built-In Type Checking).
The following terms will be referenced throughout this documentation:
#### The EnumeratedLiterals Instance
The EnumeratedLiterals object that is created and returned by the enumeratedLiterals methodFruits
(e.g. ):
`ts`
const Fruits = enumeratedLiterals(["apple", "banana", "blueberry", "orange"] as const, {});
#### The EnumeratedLiterals Members
The constant string literal values that the [EnumeratedLiterals][instance] instance contains (e.g."apple", "banana", "blueberry", "orange"), defined as a readonly array of string(s) (i.e.readonly string[]):
`ts`
const Fruits = enumeratedLiterals(["apple", "banana", "blueberry", "orange"] as const, {});
Fruits.members; // readonly ["apple", "banana", "blueberry", "orange"]
The members of the [EnumeratedLiterals][instance] instance will always be a readonly array ofstring(s), even when the [EnumeratedLiterals][instance] instance is created with a series of
[models][model]:
`ts
const Fruits = enumeratedLiterals(
[
{ value: "apple", label: "Apple" },
{ value: "banana", label: "Banana" },
{ value: "blueberry", label: "Blueberry" },
{ value: "orange", label: "Orange" },
] as const,
{},
);
Fruits.members; // readonly ["apple", "banana", "blueberry", "orange"]
`
The type of the [members][member] on an [EnumeratedLiterals][instance] instance can be obtainedEnumeratedLiteralMember
via the generic type:
`ts`
// "apple" | "banana" | "blueberry" | "orange"
type Fruit = EnumeratedLiteralMember
#### The EnumeratedLiterals Models
When there is a need to associate other constant values with the [members][member] on an
[EnumeratedLiterals][instance], the [EnumeratedLiterals][instance] instance can be instantiatedobject
with a readonly array of -type(s), referred to as [models][model], each of which defines itsvalue
associated [member][member] via a attribute:
`ts
const Fruits = enumeratedLiterals(
[
{ value: "apple", label: "Apple" },
{ value: "banana", label: "Banana" },
{ value: "blueberry", label: "Blueberry" },
{ value: "orange", label: "Orange" },
] as const,
{},
);
// readonly ["apple", "banana", "blueberry", "orange"]
Fruits.members;
// [ { value: "apple", label: "Apple" }, { value: "banana", label: "Banana" }, ... ]
Fruits.models;
`
Each [model][model] can contain other constants, functions or definitions that should be strongly
typed and associated with the relevant [member][member] of the [EnumeratedLiterals][instance]
instance.
The type of the [models][model] on an [EnumeratedLiterals][instance] instance can be obtained viaEnumeratedLiteralsModel
the generic type:
`ts`
// { value: "apple", label: "Apple" } | { value: "banana", label: "Banana" } | ...
type FruitModel = EnumeratedLiteralsModel
##### Example
The ability to associate other values with the [members][member] of an
[EnumeratedLiterals][instance] gives rise to common recipes/patterns that can be used to more
conveniently and strongly type the relationships between various constants in an application:
`ts
// "apple" | "banana" | "blueberry" | "orange"
type FruitValue = EnumeratedLiteralsMember
type Fruit = Extract<
EnumeratedLiteralsModel
{ value: I }
>;
/*
| { value: "apple"; description: "A red fruit"; color: "red"; label: "Apple"; }
| { value: "banana"; description: "A yellow fruit"; color: "yellow"; label: "Banana"; }
| { value: "blueberry"; description: "A blue fruit"; color: "blue"; label: "Blueberry"; }
| { value: "orange"; description: "An orange fruit"; color: "orange"; label: "Orange"; }
*/
type AnyFruit = Fruit;
// { value: "apple"; description: "A red fruit"; color: "red"; label: "Apple"; }
type Apple = Fruit<"apple">;
type FruitLabel = Fruit["label"];
// "Apple"
type AppleLabel = FruitLabel<"apple">;
`
#### The EnumeratedLiterals Accessors
The [accessors][accessor] on an [EnumeratedLiterals][instance] instance represent the attributesenum
of the instance that are used to access the [members][member] on the instance in an -like
fashion:
`ts
const Fruits = enumeratedLiterals(["apple", "banana", "blueberry", "orange"] as const, {});
Fruits.APPLE; // "apple"
const b: "banana" = Fruits.BANANA;
`
The [accessors][accessor] on an [EnumeratedLiterals][instance] instance are automatically
generated based on the [members][member] of the instance, but can also be explicitly defined for
each [member][member] on the instance on instantiation:
`ts
const Fruits = enumeratedLiterals(
[
{ value: "apple", accessor: "Apple" },
{ value: "banana", accessor: "Banana" },
{ value: "blueberry", accessor: "Blueberry" },
{ value: "orange", accessor: "Orange" },
] as const,
{},
);
Fruits.Apple; // "apple"
`
Additionally, the manner in which the [accessors][accessor] on an [EnumeratedLiterals][instance]enumeratedLiterals
instance are automatically generated can be customized by providing specific [options][options] to
the method:
`ts
const Fruits = enumeratedLiterals(["Apple", "Banana", "Blueberry", "Orange"] as const, {
accessorCase: "lower",
});
Fruits.apple; // "Apple"
const b: "Banana" = Fruits.banana;
`
For more information on the specific [options][options] available to the enumeratedLiterals
method, see [Configuration Options][options].
The following describes how the enumerated-literals package can be used and the various features
it offers.
In its most basic form, an [EnumeratedLiterals][instance] instance can be created as follows:
`ts`
const Fruits = enumeratedLiterals(["apple", "banana", "blueberry", "orange"] as const, {});
type Fruit = EnumeratedLiteralMember
The constant string literals, "apple", "banana", "blueberry", and "orange" (orEnumeratedLiterals
[members][member] of the [][instance] instance) can be accessed as properties ofFruits
the object via their associated [accessors][accessor]:
`ts`
Fruits.APPLE; // "apple"
The [members][member] of the [EnumeratedLiterals][instance] instance can be accessed as areadonly array as follows:
`ts`
Fruits.members; // readonly ["apple", "banana", "blueberry", "orange"]
#### Built-In Type Checking
The [EnumeratedLiterals][instance] instance is equipped with the following methods that are useful
for type checking:
##### Assertion
The assert method will throw an InvalidLiteralValueError if the value that it is provided is notEnumeratedLiterals
a [member][member] of the [][instance] instance:
`ts`
Fruits.assert("cucumber"); // throws an InvalidLiteralValueError
###### Handling Multiple Values
The [EnumeratedLiterals][instance] instance is also equipped with an assertMultiple method thatInvalidLiteralValueError
will throw an if _any_ of the values in the provided array are notEnumeratedLiterals
[members][member] of the [][instance] instance:
`ts`
Fruits.assertMultiple(["cucumber", "pear"]); // throws an InvalidLiteralValueError
##### Type Guard
The [EnumeratedLiterals][instance] instance is equipped with a typeguard, contains, that returnsEnumeratedLiterals
whether or not the provided value is a member of the [][instance] instance:
`ts
function processFruit(fruit: Fruit) { ... }
function process(value: unknown) {
if (Fruits.contains(value)) {
// 'value' is of type 'Fruit'
processFruit(value);
}
}
`
###### Handling Multiple Values
The [EnumeratedLiterals][instance] instance is also equipped with a typeguard, containsMultiple,EnumeratedLiterals
that can be used to determine whether or not _all_ of the provided values are [members][members] of
the [][instance] instance:
`ts
function processFruits(fruit: Fruit[]) { ... }
function process(values: string[]) {
if (Fruits.containsMultiple(values)) {
// 'value' is of type 'Fruit[]'
processFruits(values);
}
}
`
##### Parser
The parse method will return the provided value, typed as a [member] of theEnumeratedLiterals
[][instance] instance, if the provided value is in fact a [member] of theEnumeratedLiterals
[][instance] instance. Otherwise, it will throw an InvalidLiteralsValueError:
`ts
function processFruit(fruit: Fruit) { ... }
function process(value: unknown) {
// The 'parse' method will throw if the 'value' is not of type 'Fruit'.
const f = Fruits.parse(value, {});
processFruit(f);
}
`
If it is desired that the parse method should not throw an InvalidLiteralsValueError when theEnumeratedLiterals
value is not a [member] of the [][instance] instance, but to instead returnnull, this can be accomplished by providing the strict option to the method:
`ts
function processFruit(fruit: Fruit) { ... }
function process(value: unknown) {
// The 'parse' method will return null if the 'value' is not of type 'Fruit'.`
const f = Fruits.parse(value, { strict: false });
if (f) {
processFruit(f);
}
}
###### Handling Multiple Values
The parse method can also be used to parse multiple values at once by specifying the multiInvalidLiteralsValueError
option. In this case, it will throw an if _any_ of the provided valuesEnumeratedLiterals
are not [members][member] of the [][instance] instance. Otherwise, it willEnumeratedLiterals
return the values typed as [members][member] of the [][instance] instance:
`ts
function processFruits(fruit: Fruit[]) { ... }
function process(values: string[]) {
// The 'parse' method will throw if any of the values in 'value' are not of type 'Fruit'.
const f = Fruits.parse(value, { multi: true });
processFruits(f);
}
`
If it is desired that the parse method should not throw an InvalidLiteralsValueError when anyEnumeratedLiterals
value is not a [member] of the [][instance] instance, but to instead return justEnumeratedLiterals
the values that are [members][member] of the [][instance], this can bestrict
accomplished by providing the option to the method:
`ts
function processFruits(fruit: Fruit[]) { ... }
function process(value: unknown[]) {
// The 'parse' method will return a filtered array of the values that are of type Fruit`
const f = Fruits.parse(value, { strict: false, multi: true });
processFruits(f)
}
#### EnumeratedLiteralsModel
An [EnumeratedLiterals][instance] instance can be created such that its [members][member] are eachEnumeratedLiterals
associated with other values, constants, and/or functions. These other values, constants, and/or
functions will be strongly typed and associated with each [member] of the
[][instance] instance:
`ts
const Fruits = enumeratedLiterals(
[
{ value: "apple", description: "A red fruit", color: "red", label: "Apple" },
{ value: "banana", description: "A yellow fruit", color: "yellow", label: "Banana" },
{ value: "blueberry", description: "A blue fruit", color: "blue", label: "Blueberry" },
{ value: "orange", description: "An orange fruit", color: "orange", label: "Orange" },
] as const,
{},
);
Fruits.members; // readonly ["apple", "banana", "blueberry", "orange"]
/* readonly [
{ value: "apple"; description: "A red fruit"; color: "red"; label: "Apple"; },
{ value: "banana"; description: "A yellow fruit"; color: "yellow"; label: "Banana"; },
{ value: "blueberry"; description: "A blue fruit"; color: "blue"; label: "Blueberry"; },
{ value: "orange"; description: "An orange fruit"; color: "orange"; label: "Orange"; },
] */
Fruits.models;
`
The models attribute will return each [member] of the [EnumeratedLiterals][instance] instance inobject
an that also contains the associated constants, values and/or functions it was instantiatedEnumeratedLiterals
with. The [models][model] that are returned will be ordered in the same manner as the order of the
values that the [][instance] instance was created with.
##### The EnumeratedLiteralsModel Type
The EnumeratedLiteralsModel type can be used to type the [models][model] that are contained on anEnumeratedLiterals
[][instance] instance.
One common use case is to define a type for both the [member] and [model] of an
[EnumeratedLiterals][instance] instance separately, and allow the [model] to be extracted based on
the [member] type:
`ts
// "apple" | "banana" | "blueberry" | "orange"
type FruitValue = EnumeratedLiteralsMember
type Fruit = Extract<
EnumeratedLiteralsModel
{ value: I }
>;
/*
| { value: "apple"; description: "A red fruit"; color: "red"; label: "Apple"; }
| { value: "banana"; description: "A yellow fruit"; color: "yellow"; label: "Banana"; }
| { value: "blueberry"; description: "A blue fruit"; color: "blue"; label: "Blueberry"; }
| { value: "orange"; description: "An orange fruit"; color: "orange"; label: "Orange"; }
*/
type AnyFruit = Fruit;
// { value: "apple"; description: "A red fruit"; color: "red"; label: "Apple"; }
type Apple = Fruit<"apple">;
`
An [EnumeratedLiterals][instance] instance is equipped with the following methods that can be usedEnumeratedLiterals
to interact with the [models][model] on an [][instance] instance:
##### Model Getters
The [EnumeratedLiterals][instance] instance is equipped with a method, getModel, that can beEnumeratedLiterals
used to retrieve the [model] associated with a specific [member] on the
[][instance] instance. The return type will be strongly typed, such that the
properties associated with the provided [member] will be their constant representations:
`ts`
// { value: "apple"; description: "A red fruit"; color: "red"; label: "Apple"; }
Fruits.getModel("apple");
The arguments to the methods are all strongly typed, such that the following code will not compile:
`ts`
Fruits.getModel("cucumber");
Similarly, [EnumeratedLiterals][instance] instance is equipped with a getModelSafe method, thatEnumeratedLiterals
allows the behavior of the method in the case that the provided value is not a [member] of the
[][instance] instance to be controlled.
The getModelSafe method accepts a strict option, that determines whether or not the methodInvalidLiteralValueError
should throw an or simply return null in the case that the providedEnumeratedLiterals
value is not a [member] of the [][instance]
`ts`
Fruits.getModelSafe("cucumber", { strict: true }); // Throws Error, but compiles
`ts`
Fruits.getModelSafe("cucumber", { strict: false }); // Compiles, returns the model or null
##### Attribute Getters
The [EnumeratedLiterals][instance] instance is equipped with methods, getAttribute andgetAttributes, that can be used to access the attributes of a single [model][model] or allEnumeratedLiterals
[models][model] on the [][instance] instance, respectively:
`ts`
Fruits.getAttribute("apple", "description"); // "A red fruit"
The following will not compile:
`ts`
Fruits.getAttribute("cucumber", "description");
The getAttributes method can be used to return the associated attribute of all [models][model] onEnumeratedLiterals
the [][instance] instance, in the same order as the values or object(s) that
were used to instantiate the instance:
`ts`
// readonly ["A red fruit", "A yellow fruit", "A blue fruit", "An orange fruit"]
Fruits.getAttributes("description");
#### Configuration Options
Additional, optional [Configuration Options][options] can be provided to the enumeratedLiteralsEnumeratedLiterals
method in order to control error messages and/or formatting of [accessors][accessor] on the
[][instance] instance.
The [Configuration Options][options] that can be provided to the enumeratedLiterals method are as
follows:
1. invalidValueErrorMessage
A function that can be used to format the error message of the InvalidLiteralValueError that isEnumeratedLiterals
thrown when an invalid value is encountered by the [][instance] instance.
###### Example
`tsThe value '${received[0]}' is not in the set of fruits: ${expected.join(", ")}!
const Fruits = enumeratedLiterals(["apple", "banana", "blueberry", "orange"] as const, {
invalidValueErrorMessage: ({ expected, received }) =>
,`
});
2. accessorSpaceReplacement (AccessorSpaceReplacement or "_" | "-" | "" | null)
The string value that will be used to replace single white-space characters inEnumeratedLiterals
[accessors][accessor] when the [accessors][accessor] are either auto-generated based on the
[members][member] of the [][instance] instance or when white-space charactersaccessor
are encountered in the property of a given [model] on theEnumeratedLiterals
[][instance] instance.
###### Example
`ts
const Fruits = enumeratedLiterals(["red apple", "yellow banana"] as const, {
accessorSpaceReplacement: "-",
});
Fruits["RED-APPLE"]; // "red apple"
Fruits["YELLOW-BANANA"]; // "yellow banana"
`
It is important to note the following:
1. Multiple white-space characters encountered in the middle of a value or [accessor] will be
replaced with single white-space characters:
###### Example
`ts
const Fruits = enumeratedLiterals(["red apple"] as const, {
accessorSpaceReplacement: "_",
});
Fruits.RED_APPLE; // "red apple"
`
2. A null value means that white-space characters will remain and will not be replaced.
However, if multiple consecutive white-space characters are encountered, they will still be
replaced with a single white-space character.
Default: "_"
3. accessorHyphenReplacement (AccessorHyphenReplacement or "_" | "" | null)
The string value that will be used to replace hyphens ("-") when the [accessors][accessor]EnumeratedLiterals
are either auto-generated based on [members][member] [][instance] instance oraccessor
when hyphen characters are encountered in the property of a given [model] on theEnumeratedLiterals
[][instance] instance.
###### Example
`ts
const Fruits = enumeratedLiterals(["red-apple"] as const, {
accessorHyphenReplacement: "_",
});
Fruits.RED_APPLE; // "red-apple"
`
Note that a null value means that the hyphens will not be replaced but will be left in-tact.
Default: Either "_" or null, depending on whether or not the values provided to theenumeratedLiterals
method are provided as an array of object(s) with their own accessorreadonly
properties, or a array of strings.
4. accessorCase ("lower" | "upper" | null)
Whether the [accessors][accessor] should be formatted as lowercase strings, uppercase strings, or
neither (null), when the [accessors][accessor] are either auto-generated based onEnumeratedLiterals
[members][member] [][instance] instance or when the accessor property of aEnumeratedLiterals
given [model] on the [][instance] is explicitly defined.
###### Example
`ts
const Fruits = enumeratedLiterals(["RED-apple"] as const, {
accessorCase: "lower",
});
Fruits.red_apple; // "RED-apple"
`
Default: Either "upper" or null, depending on whether or not the values provided to theenumeratedLiterals
method are provided as an array of [models][model] with their own explicitlyreadonly
defined [accessor][accessors] properties, or a array of [members][member].
The following section describes the methods and properties on an [EnumeratedLiterals][instance]
instance:
#### Instance Properties
##### members (_property_)
The [members][member] of the [EnumeratedLiterals][instance] instance.
`ts`
LiteralsMembers
###### Example
`ts
import { enumeratedLiterals } from "enumerated-literals";
const Fruits = enumeratedLiterals(["apple", "banana", "blueberry", "orange"] as const, {});
Fruits.members; // readonly ["apple", "banana", "blueberry", "orange"]
// or
const Fruits = enumeratedLiterals(
[
{ value: "apple", accessor: "Apple" },
{ value: "banana", accessor: "Banana" },
{ value: "blueberry", accessor: "Blueberry" },
{ value: "orange", accessor: "Orange" },
] as const,
{},
);
Fruits.members; // readonly ["apple", "banana", "blueberry", "orange"]
`
##### models (_property_)
The [models][model] associated with each [member][member] on the [EnumeratedLiterals][instance]
instance instance.
`ts`
LiteralsModels
###### Example
`ts
import { enumeratedLiterals } from "enumerated-literals";
const Fruits = enumeratedLiterals(["apple", "banana", "blueberry", "orange"] as const, {});
// readonly [{ value: "apple" }, { value: "banana" }, { value: "blueberry" }, { value: "orange" }]
Fruits.models;
// or
const Fruits = enumeratedLiterals(
[
{ value: "apple", description: "A red fruit", color: "red", label: "Apple" },
{ value: "banana", description: "A yellow fruit", color: "yellow", label: "Banana" },
{ value: "blueberry", description: "A blue fruit", color: "blue", label: "Blueberry" },
{ value: "orange", description: "An orange fruit", color: "orange", label: "Orange" },
] as const,
{},
);
/* readonly [
{ value: "apple"; description: "A red fruit"; color: "red"; label: "Apple"; },
{ value: "banana"; description: "A yellow fruit"; color: "yellow"; label: "Banana"; },
{ value: "blueberry"; description: "A blue fruit"; color: "blue"; label: "Blueberry"; },
{ value: "orange"; description: "An orange fruit"; color: "orange"; label: "Orange"; },
] */
Fruits.models;
`
#### Instance Methods
##### assert (_method_)
A type assertion that throws an InvalidLiteralValueError if the provided value is not a
[member][member] the [EnumeratedLiterals instance][instance].
`ts`
###### Example
`ts
import { enumeratedLiterals } from "enumerated-literals";
const Fruits = enumeratedLiterals(["apple", "banana", "blueberry", "orange"] as const, {});
type Fruit = EnumeratedLiteralMember
function processFruit(fruit: Fruit) { ... }
function process(value: unknown) {
Fruits.assert(value, "The value is not a fruit!");
processFruit(f);
}
`
##### assertMultiple (_method_)
A type assertion that throws an InvalidLiteralValueError if _any_ of the values in the provided
array are not [members][member] the [EnumeratedLiterals instance][instance].
`ts`
###### Example
`ts
import { enumeratedLiterals } from "enumerated-literals";
const Fruits = enumeratedLiterals(["apple", "banana", "blueberry", "orange"] as const, {});
type Fruit = EnumeratedLiteralMember
function processFruits(fruit: Fruit[]) { ... }
function process(value: unknown[]) {
Fruits.assertMultiple(value, "The value contains invalid fruits!");
processFruits(f);
}
`
##### parse (_method_)
Validates and returns the provided value or values as a [member] or [members][member] of the
[EnumeratedLiterals][instance] instance, respectively. The specific behavior of the method depends
on the options that it accepts:
`ts`
parse
###### Options
1. strict: Whether or not the method should throw an InvalidLiteralValueError if the providedEnumeratedLiterals
value is not a [member] of the [][instance] instance (in the case that themulti
option is not true), or if _any_ of the provided values are not [members][member] ofEnumeratedLiterals
the [][instance] (in the case that the multi option is true).
If false, the method will return null if the provided value is not a [member] of theEnumeratedLiterals
[][instance] instance - when the multi option is not true - or it willEnumeratedLiterals
return the values that are [members][member] of the [][instance] instancemulti
when the option is true.
If true (the default case), the method will throw an InvalidLiteralValueError if the providedEnumeratedLiterals
value is not a [member] of the [][instance] instance - when the multitrue
option is not - or it will throw an InvalidLiteralValueError in the case that _any_ ofEnumeratedLiterals
the provided values are not [members][member] of the [][instance] instancemulti
when the option is true.
Default: true
2. multi: Whether or not the method should parse multiple values at once.
If true, the method will parse each individual value in the provided array separately. Iffalse
(the default case) the method will validate the provided value as a single value.
3. errorMessage: An optional string error message that should be included in the thrownInvalidLiteralValueError
in the case that the strict option is not false and values thatEnumeratedLiterals
are not [members][member] of the [][instance] instance are encountered.
###### Example
`ts
import { enumeratedLiterals } from "enumerated-literals";
const Fruits = enumeratedLiterals(["apple", "banana", "blueberry", "orange"] as const, {});
type Fruit = EnumeratedLiteralMember
function processFruit(fruit: Fruit) { ... }
function process(value: unknown) {
const f = Fruits.parse(value); // 'Fruit'
processFruit(f);
}
`
##### contains (_method_)
A typeguard that returns whether or not the provided value is a [member] of the
[EnumeratedLiterals][instance] instance.
`ts`
(v: unknown): v is LiteralsMember
###### Example
`ts
import { enumeratedLiterals } from "enumerated-literals";
const Fruits = enumeratedLiterals(["apple", "banana", "blueberry", "orange"] as const, {});
type Fruit = EnumeratedLiteralMember
function processFruit(fruit: Fruit) { ... }
function process(value: unknown) {
if (Fruits.contains(value)) {
// 'value' is of type 'Fruit'
processFruit(value);
}
}
`
##### containsMultiple (_method_)
A typeguard that returns whether or not all of the provided values are a [members][member] of the
[EnumeratedLiterals][instance] instance.
`ts`
(v: unknown[]): v is LiteralsMember
###### Example
`ts
import { enumeratedLiterals } from "enumerated-literals";
const Fruits = enumeratedLiterals(["apple", "banana", "blueberry", "orange"] as const, {});
type Fruit = EnumeratedLiteralMember
function processFruits(fruit: Fruit[]) { ... }
function process(value: unknown[]) {
if (Fruits.containsMultiple(value)) {
// 'value' is of type 'Fruit[]'
processFruits(value);
}
}
`
##### getModel (_method_)
Returns the [model] associated with a specific [member] of the [EnumeratedLiterals][instance]
instance.
`ts`
###### Example
`ts
import { enumeratedLiterals } from "enumerated-literals";
const Fruits = enumeratedLiterals(["apple", "banana", "blueberry", "orange"] as const, {});
// { value: "apple"; description: "A red fruit"; color: "red"; label: "Apple"; }
Fruits.getModel("apple");
`
##### getModelSafe (_method_)
Returns the [model] associated with a specific [member] of the [EnumeratedLiterals][instance]EnumeratedLiterals
instance if that provided value is in fact a [member] of the [ instance] instance.InvalidLiteralValueError
If it is not, either an will be thrown or null will be returned, dependingstrict
on the option.
`ts`
In other words, this method does not assume that the provided value has to be a [member] of the
[EnumeratedLiterals][instance] instance, but will rather validate that it is before proceeding.
This means that the compiler will not fail if an invalid value is provided to the method.
###### Options
1. strict: Whether or not the method should throw an InvalidLiteralValueError if the providedEnumeratedLiterals
value is not a [member] of the [][instance] instance or it should insteadnull
simply return .
Default: true
2. errorMessage: An optional string error message that should be included in the thrownInvalidLiteralValueError
in the case that the strict option is not false and the providedEnumeratedLiterals
value is not a [member] of the [][instance] instance.
###### Example
`ts
import { enumeratedLiterals } from "enumerated-literals";
const Fruits = enumeratedLiterals(["apple", "banana", "blueberry", "orange"] as const, {});
const v: unknown = "cucumber";
/*
| { value: "apple"; description: "A red fruit"; color: "red"; label: "Apple"; }
| { value: "banana"; description: "A yellow fruit"; color: "yellow"; label: "Banana"; }
| { value: "blueberry"; description: "A blue fruit"; color: "blue"; label: "Blueberry"; }
| { value: "orange"; description: "An orange fruit"; color: "orange"; label: "Orange"; }
*/
Fruits.getModelSafe(v, { strict: true });
/*
| { value: "apple"; description: "A red fruit"; color: "red"; label: "Apple"; }
| { value: "banana"; description: "A yellow fruit"; color: "yellow"; label: "Banana"; }
| { value: "blueberry"; description: "A blue fruit"; color: "blue"; label: "Blueberry"; }
| { value: "orange"; description: "An orange fruit"; color: "orange"; label: "Orange"; }
| null
*/
Fruits.getModelSafe(v, { strict: false });
// Same as above
Fruits.getModelSafe(v, {});
`
##### getAttribute (_method_)
Returns the value of an attribute, N, on the [model] associated with a specific [member] of theEnumeratedLiterals
[][instance] instance.
`ts`
###### Example
`ts
import { enumeratedLiterals } from "enumerated-literals";
const Fruits = enumeratedLiterals(
[
{ value: "apple", description: "A red fruit", color: "red", label: "Apple" },
{ value: "banana", description: "A yellow fruit", color: "yellow", label: "Banana" },
{ value: "blueberry", description: "A blue fruit", color: "blue", label: "Blueberry" },
{ value: "orange", description: "An orange fruit", color: "orange", label: "Orange" },
] as const,
{},
);
Fruits.getAttribute("apple", "description"); // "A red fruit"
`
##### getAttributes (_method_)
Returns the values for a given attribute, N, on each [model] that is associated with theEnumeratedLiterals
[][instance] instance.
`ts`
###### Example
`ts
import { enumeratedLiterals } from "enumerated-literals";
const Fruits = enumeratedLiterals(
[
{ value: "apple", description: "A red fruit", color: "red", label: "Apple" },
{ value: "banana", description: "A yellow fruit", color: "yellow", label: "Banana" },
{ value: "blueberry", description: "A blue fruit", color: "blue", label: "Blueberry" },
{ value: "orange", description: "An orange fruit", color: "orange", label: "Orange" },
] as const,
{},
);
Fruits.getAttributes("label"); // readonly ["Apple", "Banana", "Blueberry", "Orange"]
`
##### pick (_method_)
Returns a new [EnumeratedLiterals][instance] instance that consists of just the [members][member]
that are provided to the method.
`ts`
ExtractLiterals
OptionsWithNewSet
>
###### Example
`ts
import { enumeratedLiterals } from "enumerated-literals";
const Fruits = enumeratedLiterals(["apple", "banana", "blueberry", "orange"] as const, {});
const RoundFruits = Fruits.pick(["apple", "orange"] as const);
RoundFruits.members; // readonly ["apple", "orange"]
`
##### omit (_method_)
Returns a new [EnumeratedLiterals][instance] instance that consists of just the [members][member]EnumeratedLiterals
on the [][instance] instance that do not belong to those provided to the method.
`ts`
ExcludeLiterals
OptionsWithNewSet
>
###### Example
`ts
import { enumeratedLiterals } from "enumerated-literals";
const Fruits = enumeratedLiterals(["apple", "banana", "blueberry", "orange"] as const, {});
const RoundFruits = Fruits.omit(["banana", "blueberry"] as const);
RoundFruits.members; // readonly ["apple", "orange"]
`
##### humanize (_method_)
Returns a human readable string representing the [members] of the [EnumeratedLiterals][instance]
instance.
`ts`
(options?: HumanizeListOptions
###### Example
`ts
import { enumeratedLiterals } from "enumerated-literals";
const Fruits = enumeratedLiterals(["apple", "banana", "blueberry", "orange"] as const, {});
// "apple, banana, blueberry, or orange"
Fruits.humanize({ conjunction: "or" });
`
##### throwInvalidValue (_method_)
Throws an InvalidLiteralValueError with a message that is generated based on optionally providedEnumeratedLiterals
[Configuration Options][options] to the [][instance] instance on instantiationEnumeratedLiterals
and/or the [members][member] of the [][instance] instance.
`ts`
(v: unknown, errorMessage?: string): never;
###### Example
`ts
import { enumeratedLiterals } from "enumerated-literals";
const Fruits = enumeratedLiterals(["apple", "banana", "blueberry", "orange"] as const, {});
// throws InvalidLiteralValueError
// "The value 'cucumber' is invalid, it must be one of 'apple', 'banana', 'blueberry' or 'orange'."
Fruits.throwInvalidValue("cucumber");
``
[instance]: #the-enumeratedliterals-instance
[member]: #the-enumeratedliterals-members
[accessor]: #the-enumeratedliterals-accessors
[model]: #the-enumeratedliterals-models
[options]: #configuration-options