meouzers-playground v2.0.0

Meouzer's Playground

Used to test ReadMe.md files, e.g., for overflow problems.

Now testing ReadMe.md file for type-quickly 3.0.0

type-quickly 3.0.0

NPM's fastest, most comprehensive, and most correct typing package for node and the browser

If you want only the quick rundown, read the Comprehensive/Usage/Properties-of-is sections. If you are coding in a node environment only and just want type checkers for the built-in ES6 classes, use of Node's util.types.isKlass(x) functions is the best option. Our type checkers also work in the browser.

Competitors' typing relies heavily on use of Object.prototype.toString(), constructor names, and possibly instanceof with results that simply do not work unless your world is narrowed down to objects of the form new Klass(...). Anyway, speaking truth to power, the design of Object.prototype.toString() is a complete mess and so should be avoided. A constructor only approach will not work. Untill now, no one has made a constructor/prototype approach work: see apppendix Constructor/Prototype Apporach to Typing. But still, a constructor/prototype approach is slow.

By using prototyping techniques to avoid the previously discussed problematics, the author came up with a type(x) function that correctly types everything. Don't need everything typed? Well, prototyping techniques are still lightning fast, the fastest possible.

This package provides is.Klass(x) type checkers where Klass is a JavaScript class or programmer defined class. This package also provides is.node_path_Klass(x) type checkers where Klass is a Node class whose relative path is path.

Extremely Fast and Correct

The speed of type(x) blows away the competition. Plus it and its compatriots are 100% correct as proven by hundreds of individual tests: see the Tests folders. A number of typing packages are compared against type-quickly in following tables. There are other packages, but the best were chosen.

Delete the tests folder if you wish, which will bring down the total number of files to three: package.json; type-quickly.js; and ReadMe.md.

✅ = yes. ❌ = no. (1) variant error classes incorrectly typed (2) out of date errors (3) example of programmer class instance: const x = new Foo() where Foo is a programmer defined class.

Speed comparisons are based on testing each package's typing function on x = new Boolean(true). Whenever, a competitor slows down on another class due to more complicated logic, type-quickly will be even faster in comparison because type-quickly does not slow down. Secondary objects, which are objects created with Object.create(), are so basic that they should be typed correctly.

Examples of mistakes that all competitors make is to type Boolean.prototype or secondary objects such as Object.create(new Boolean(true)) to "Boolean". If you think that doesn't matter, think again: node's is-type checkers work correctly on the class prototype and all objects deriving from it.

Comprehensive

The type-quickly/type-robustly packages are the most comprehensive typing packages on NPM because they alone type everything in ES6 (and more) correctly, including the following sometimes overlapping categories.

1. All ES6 = ECMA-2015 classes
2. Node-Classes: 100+ classes such as node_buffer_Buffer, node_buffer_Blob, node_stream.Readable, node_http.Server; etc.
3. JavaScript Classes beyond ES6: Blob, Headers, ReadableStream, etc.
4. Secondary-objects, which are objects created with Object.create()
5. Class prototypes
6. Null-objects, which are objects not deriving from Object.prototype
7. Programmer defined classes
8. Edge-cases1 of programmer defined classes
9. Edge-cases of built-in ES6 classes (type-robustly only)
10. Windows and DOM objects

(1) See The Edge Case Appendix.

✅ = yes. ❌ = no. (1) just one mistake (2) sometimes correct, sometimes not (3) programmer classes: class prototype and all objects derived from it must be typed correctly

Usage

Import for Node

const {type, is} = require('type-quickly')
-------------------------------------------------------------------------

Import for Browser

<script src="node_modules/type-quickly/type-quickly.js"  
    type="text/javascript"></script>
    
or copy type-quickly.js anywhere and link to it    
-------------------------------------------------------------------------
ES6 classes:

Boolean; Number; String; Date; RegExp; Array; Int8Array; Uint8Array;
Uint8ClampedArray; Int16Array; Uint16Array; Int32Array; Uint32Array;
Float32Array; Float64Array; BigInt64Array; BigUint64Array; Error;
URIError; EvalError; RangeError; ReferenceError; SyntaxError; TypeError;
WeakSet; Set; WeakMap; Map; ArrayBuffer; DataView; Promise;

// Map objects (Map.prototype or objects deriving from it)

const x = new Map();             
const prototype = Map.prototype;  
const secDegObj = Object.create(x);

// They are correctly typed
type(x)           is  "Map"
type(prototype)   is  "Object"
type(secDegObj)   is  "Object"

is.Map(x)         is  true
is.Map(prototype) is  false
is.Map(secDegObj) is  false

-------------------------------------------------------------------------
JavaScript classes beyond ES6 for node and the browser: some were 
originally defined in node, in which case they are now global in node.  

AggregateError; AbortController; AbortSignal; Blob; 
ByteLengthQueuingStrategy; BroadcastChannel; CompressionStream; 
CountQueuingStrategy; CryptoKey; DecompressionStream; Event; EventTarget; 
FormData; Headers; MessageChannel; MessageEvent; MessagePort; 
PerformanceEntry; PerformanceMeasure; PerformanceObserver; 
PerformanceObserverEntryList; PerformanceResourceTiming; 
ReadableByteStreamController; ReadableStream; ReadableStreamBYOBReader; 
ReadableStreamDefaultController; ReadableStreamDefaultReader; 
SharedArrayBuffer; TextDecoderStream; TextEncoder; TextEncoderStream; 
TransformStream; TransformStreamDefaultController; URL; URLSearchParams; 
WritableStream; WeakRef; WritableStreamDefaultController; 
WritableStreamDefaultWriter;

const x = new Blob();

type(x)                 is "Blob" in node and browser
is.Blob(x)              is true   in node and browser
is.node_buffer_Blob(x)  is true in node environment since
                        Blob is defined at node.buffer.
                        
-------------------------------------------------------------------------

Node Environment only. Node classes that are not JavaScript globals.

const fs = require('fs');
const x = new fs.WriteStream("dummy.txt");

type(x)                     is "node_fs_WriteStream"
is.node_fs_WriteStream(x)   is true

The is.node_fs_WriteStream() function is not available for the browser.

Typing Programmer Defined Classes

Programmer defined classes are correctly typed out of the box, assuming the programmer always insures the constructor is correct, i.e., Klass.prototype.constructor must be Klass.

However, if you want to make such typing lightning fast, then there are two typing protocols. Both work even if the constructor is not properly set.

Protocol-1 is preferable since it at no cost handles edge cases of the class in the type() and dtype() functions.

Protocol-1 for Typing Programmer Defined Classes

For a programmer defined class Klass, simply write (1) type.asInstance(this, "Klass") inside the constructor and (2) type.asClass(Klass) outside the constructor. Edge cases are most excellently handled.

function Klass()
{    
    // (1) Make sure type() works correctly on Klass objects
    type.asInstance(this, "Klass");
}

// If you redefine Klass.prototype, make sure (2)
// succeeds not preceeds it. 

Klass.prototype = ...
    
// (2) Provide an is.Klass() function and make
// sure dtype() handles Klass edge cases. 

type.asClass(Klass)

// Klass objects 
// (Klass.prototpe and objects derived from it)

const x = new Klass()                 
const prototype = Klass.prototype     
const edgeCase = Object.create(Klass.prototype)
const secDegObj = Object.create(x);

// They are typed correctly.
type(x)            is "Klass"
type(prototype)    is "Object"
type(edgeCase)     is "Object"
type(secDegObj)    is "Object"

is.Klass(x)         is  true
is.Klass(prototype) is  false
is.Klass(edgeCase)  is  false
is.Klass(secDegObj) is  false  

Protocol-2 for Typing Programmer Defined Classes

Protocol-2 is deprecated unless protocol-1 is unfeasible for some odd reason, e.g., there is no access to the inside of the constructor.

To type a programmer defined class Klass, write type.thisClass(Klass) outside the constructor. Edge cases will be incorrectly typed to "Klass". Edge cases will also be incorrectly handled dtype().

function Klass()
{    
}

// Make sure Klass objects, except for the edge case 
// are type correctly. Again must be written after
// any redefinition Klass.prototype. 

type.thisClass(Klass)

// Klass objects 
const x = new Klass()                 
const prototype = Klass.prototype     
const edgeCase = Object.create(Klass.prototype)
const secDegObj = Object.create(x);

type(x)             is "Klass"
type(prototype)     is "Object"
type(edgeCase)      is "Klass" (incorrect)
type(secDegObj)     is "Object"

is.Klass(x)           is true
is.Klass(prototype)   is false
is.Klass(edgeCase)    is true (incorrect)
is.Klass(secDegObj)   is false

Exports

Properties of the is Object

Note the difference between is.boolean(x) and is.Boolean(x), which check for the primitive boolean and class instance of Boolean respectively.

Concerning is.ownProperty(x,p), this function works correctly even if x is a null-object. x.hasownProperty(p) fails if x is a null-object because hasOwnProperty is defined on Object.prototype from which x does not inherit.

Appendices

The definitive typing Function dtype(x)

This typing function gives the most detail possible by describing the inheritance chain of x. Again it is the responsibility of the programmer to follow constructor protocol by making sure Klass.prototype.constructor is Klass for each programmer defined class Klass.

Of course, stepping is done in the inheritance chain of x.

Since the inheritance chain of x may contain more than one class prototype, where classes are to include the imaginary Object class and the imaginary Null class, the specificity rule applies: dtype(x) is required to be the most informative choice: the nearest class prototype is used.

If typing protocol-1 is followed, then the edge case is correctly typed to Klass[Object].

const {dtype} = require('type-quickly');

function Klass()
{        
}

// make sure constructor protocol is followed: that
// the following is true.    
Klass.prototype.constructor === Klass

// Klass objects
const instance = new Klass();
const prototype = Klass.prototype;
const edgeCase = Object.create(Klass.prototype);
const deg2Obj = Object.create(Object.create(Klass.prototype);
const deg3Obj = Object.create(Object.create(instance);

dtype(instance)     "Klass"
dtype(prototype)    "Klass[prototype]"
dtype(edgeCase)     "Klass[Object]"     (typing protocol-1 followed)
dtype(edgeCase)     "Klass" (incorrect) (typing protocol-1 not followed)
dtype(deg2Obj)      "Klass[Object(2)]"
dtype(deg3Obj)      "Klass[Object(3)]"        

Constructor/Protoytpe Apporach to Typing

A constructor/protoytpe approach to typing works as long as programmers make sure their class constructors are set correctly: Klass.prototype.constructor should be Klass. A typing function must type class prototypes and all objects deriving from class prototypes correctly.

function typeIt(x)
{
    if (x === null) return "null";
    const tof = typeof(x);
    if(tof === 'function')
    {
        if(x === Function.prototype) return "Object";
        return "Function";
    }
    if (tof !== 'object') return tof;
    const proto = Object.getPrototypeOf(x);
    if(proto === null) return "Object"
    if(proto === BigInt.prototype || proto === Symbol.prototype ) 
        return "Object";
    if(x.constructor !== proto.constructor
        && typeof(x.constructor) === "function"
        && x === x.constructor.prototype) return "Object";
    const Klass = proto.constructor;
    if(Klass === undefined) return "Object";
    if(proto === Klass.prototype) return Klass.name;
    return "Object";
}

The Edge Case

The edge case of a class Klass is edgeCase = Object.create(Klass.prototype) that isn't to be used as a class prototype itself nor to be modified to become a class instance of Klass via a call to Klass.call(x,...) or Klass.apply(x,[...]).

No typing function discussed in this readme file correctly types edge cases of the built-in classes. That's for good reason because edge cases have no reason for existence in JavaScript, and taking edge cases of built-in classes into account would slow down code for no good reason. However, we do take edge cases of programmer defined classes into account because there is no cost to typing them correctly.

The author's type-robustly package does take edge cases of the built-in classes into account. If you think edge cases do matter, then type-robustly is your only possible package. In any case, the dtype() function of type-robustly is great for diagnostics, as it traces out the inheritance chain, and is in fact used by deep-copy-diagnostics. Deep copy packages on NPM will make the mistake of copying a class instance into an edge case and visa-versa. Only use of dtype() of the type-robustly package will uncover these and other deep-copying mistakes.