A collection of common utilities, classes, and helpers.
createBlueprint<T>(factory: BlueprintFactory<T>): Blueprint<T>
Can be used to generate a blueprint object for use within optimal checks. All supported optimal predicates are passed as an object to the factory.
deepFreeze<T extends object>(obj: T): T
Can be used to recursively freeze plain objects with
deepMerge<T extends object | unknown>(base: T, other?: T): T
Can be used to recursively merge objects and arrays, where values on the right-hand side will overwrite values on the left-hand based on the key or index respectively. Furthermore, if the 2nd argument is not provided, it will simply clone the base value.
formatMs(time: number, options?: Options): string
Can be used to format a UNIX timestamp in milliseconds into a shorthand human readable format. Wraps the pretty-ms package to handle infinite numbers, zeros, and more.
instanceOf(object: unknown, declaration: Constructor, loose?: boolean): boolean
Performs a loose instance check by comparing class names up the prototype chain if
initially fails. To disable this loose check, pass
false as the 3rd argument.
Generics can be used to type the object being checked. This will default to the declaration passed to the 2nd argument.
Loose checks can be useful if multiple copies of the same class declaration exists in the module tree. For example, multiple versions of the same package are imported.
isEmpty(value: unknown): boolean
true if an object has no properties, an array has no items, or the value is falsy,
otherwise, it returns
isFilePath(path: PortablePath): boolean
true if a string or
Path instance looks like a file system path, by checking for
absolute or relative path markers, or the existence of path separating slashes. Will return
for values that are only the file or folder name.
isModuleName(name: ModuleName): boolean
true if a string is a valid Node module package name, according to the rules defined in
for native builtin modules, like
fs, and for the old name format.
isObject<T>(value: unknown): value is T
true if the value is an object.
Generics can be used to type the return value of the object (when necessary).
isPlainObject<T>(value: unknown, loose?: boolean): value is T
isObject but only returns true if the value is a plain object (no class instances, built-ins,
etc). It achieves this by comparing the value's prototype to the built-in
Object types. If you
need to run these checks for cross-realm objects, pass true to the
parseFile<T>(path: string): T
Can be used to synchronously parse and return an object for the following file types & extensions:
yml. The function requires an absolute file path, and
any unsupported file type will throw an error.
TypeScript files require the
typescriptpackage to be installed.
requireModule<T>(path: string): T
Works in a similar fashion to the native NodeJS
require(), but also handles files built with Babel
or TypeScript by properly returning the
default export if an "ES module", and also allowing the
expected type to be defined.
There are some caveats to be aware of in regards to default and named exports in the file being required, they are:
- When only a default export, the exported value is returned directly instead of on an object with a
- When only named exports, the returned value is an object with all the named exports as properties on the object.
- When a default export and named exports together, the returned value is an object with a
defaultproperty, and an additional property for every named export. It's best to stay away from this pattern.
requireTypedModule<T>(path: string): T
requireModule but for importing TypeScript files ending in
tsx. When imported, will
transform the file using the
typescript package (must be installed), evaluate the code in the
current module context, and apply the same process to all child imports.
This helper rarely needs to be used directly as
requireModulewill call it under the hood based on the file extension.
toArray<T>(value?: T | T): T
Converts a non-array to an array. If the provided value is falsy, an empty array is returned. If the provided value is truthy and a non-array, an array of 1 item is returned.
Powered by the JSON5 package, the
json serializer can be
used to parse and stringify JSON data.
Powered by the YAML package, the
yaml serializer can be used
to parse and stringify YAML data.