joez⬢ne

Just what I need, and nothing more.

Copyright © Joe Honton 2016

License:

Regression tests developed with Bequiesce

Abstract

The joez⬢ne library is a collection of ECMAScript 2015 classes for writing Node.js application software without heavy npm module dependencies.

Motivation

With the new object oriented programming (OOP) syntax introduced in ECMAScript 2015, specifically the keywords class, extends, new, constructor, super, get, set, and static, there is a fresh opportunity to reconsider how to best implement common patterns in JavaScript application development.

The joez⬢ne library builds from the Node.js core, expanding it with capabilities related to the server's file system; control of execution; and contract by design principles.

Contract by Design

JavaScript does not have a type system. This makes for a beautiful environment where everything is polymorphic (if that's what your solution needs); but it makes for a troubling environment when trying to create functions with strict rules of correctness. This is one of the chief stumbling blocks for expert-level programmers getting their first taste of JavaScript; and it's an ongoing source of confusion when libraries are used by third parties who misunderstand functions, their arguments, and their return values.

expect

A function, in the global namespace, for soft assertion of an object's type. Use this for TypeScript-style safety within pure JaveScript modules.

proxyExpect

A surrogate for the real 'expect' function for cases where a class object is serialized for use over a socket or IPC, and the defined type is turned into an anonymous object. In order to use this surrogate fuction, define a class property called 'jsClassName' whose value is set in the constructor to be equal to the real class name.

aver

A function, in the global namespace, for soft assertion of an arbitrary statement.

File system

Almost every Node.js application needs to access the file system: this is what makes it different from browser-based JavaScript code. The classes in this category help with finding, managing, and handling file I/O.

Pfile

A class to assemble and disassemble POSIX file paths, and to access OS file system attributes.

Bunch

A class to search the file system for files matching a regular expression.

TextReader

A class to read line-delimited UTF-8 text files.

TextWriter

A class to write line-delimited UTF-8 text files.

BinaryReader

A class to read binary files.

BinaryWriter

A class to write binary files.

String operations

Character sequences are among the most common data structures in most business applications. There are many common patterns for manipulating strings, but only a few core JavaScript built-ins. There's plenty of room for improvement here, with the idea that dividing the problem-space into many domain-specific classes is the best solution to this opportunity.

Text

A class to provide text concatenation, truncation, alignment, padding, formatting, and ellipsing methods.

Diff

A facility using Neil Fraser's seminal work with "diff-match-patch" to determine the difference between two strings or two files and to colorize the changes.

Logging facility

Every library needs the facilities of a good logging system in order to trace, profile, monitor, and interrupt the execution of code.

Log

This facility dispenses with the classic log-level approach (info, debug, warning, error, fatal) and instead uses filtering categories that reflect the type of operation (todo, trace, normal, abnormal, invalid, logic, security, hopeless) that is the focus of the logging.

terminal

A console logger with methods to colorize the output.

StackTrace

Captures the current stack or the current function for logging purposes.

Cryptography

Security needs to be on everyone's mind when transfering data across the public Internet. The Node.js crypto core functions provide most of the needed functionality; this library adds just enough of a wrapper to make things easier to use.

SHA1

A class to hash a file's contents into an SHA1 checksum.

Archival

CRC32

Computation of a file's CRC32 value using the well-known PKZIP polynomial.

Zip

Create and add files to a ZIP archive.