InterType

A JavaScript type checker with helpers to implement own types and do object shape validation.

Table of Contents generated with DocToc

- InterType
- Exported Classes
- Base Types
- create.〈type〉()
- declare()
- evaluate methods
- Sum Types (Variants) and Product Types (Records)
- Declaration Values (Test Method, Type Name, Object)
- Namespaces and Object Fields
- Invariants
- Browserify
- To Do
- Is Done

InterType

Exported Classes

* { Intertype } = require 'intertype': instances of Intertype will contain a catalog of pre-declared
types ('default types')
* { Intertype_minimal } = require 'intertype': instances of Intertype_minimal will not include the
default types
* in both cases, instances will include the basetypes

Base Types

The following basetypes are built-in and treated specially; they are always present and cannot be
overwritten or omitted. The definitions of their test methods reads like pseudo-code:

``coffee
anything: ( x ) -> true
nothing: ( x ) -> not x?
something: ( x ) -> x?
null: ( x ) -> x is null
undefined: ( x ) -> x is undefined
unknown: ( x ) -> ( @type_of x ) is 'unknown'
`

* anything is the set of all JS values;
* nothing is the set containing null and undefined,
* something is anything except nothing (null and undefined).
* type_of x will never test for and return anything, nothing or something.
* null is, unsurprisingly, the name of the value null and
* undefined is the name of the value undefined.
* unknown is the default type name returned by type_of x when no other type test (except for anything,
nothing and something) returns true.

In addition to the above, the 'metatype' or 'quasitype' optional is also reserved. optional is not a
type proper, rather, it is a type modifier to allow for optional nulls and undefineds. It is used in
constructs like isa.optional.integer x and validate.optional.integer x to state succinctly that 'if x is
given (i.e. not null or undefined), it should be an integer'.

$3

Types declarations may include a create and a template entry:

* Types that have neither a create nor a template entry are not 'creatable'; trying to call
types.create.〈type〉() will fail with an error.
* If given, a create entry must be a (synchronous) function that may accept any number of arguments; if it
can make sense out of the values given, if any, it must return a value that passes its own test()
method; otherwise, it should return any non-validating value (maybe null for all types except for
null) to indicate failure. In the latter case, an Intertype_wrong_arguments_for_create will be thrown,
assuming that the input arguments (not the create method) was at fault. Errors other than
Intertype_wrong_arguments_for_create that are raised during calls to the create method should be
considered bugs.
* a type declaration with a template but no create entry will become 'creatable' by being assigned an
auto-generated create method.
* The auto-generated create method will accept no arguments and either
* return the value stored under template, or
* call the template method, if it is a synchronous function; this is not only how one can have a function
being returned by an auto-generated create method, this is also a way to produce new copies instead of
always returning the identical same object, and, furthermore, a way to return random (random_integer)
or time-dependent (date) values.
* anything else but a synchronous function (primitive values, but also asynchronous functions) will just
be returned as-is from the auto-generated create method
* but this behavior may be slightly modified in the future, especially objects as template values
should be copied (shallow or deep, as the case may be)

declare()

* Intertype#declare() accepts any number of objects
* it will iterate over all key, value pairs and interpret
* the key as the type (name), and
* the value as either that type's test method, or, if it's an object, as a type declaration
* the declaration will be rejected if the type name...
* ... is one of the basetypes, or
* ... is already declared
* the declaration will be rejected if the declaration ...
* ... is missing a test method
* ... when the test entry is not a unary function
* ... test method has the wrong arity
* ... when a create entry has been given but has the wrong arity
* ...

* Type declarations are final, meaning that while you can use the types.declare() method after the types
object has been instantiated, you cannot use it to re-declare a known type.
* When instantiating Intertype with a series of declaration objects, any duplicate names on the objects
passed in must be eliminated beforehand.

evaluate methods

* when using isa and validate methods, it can be difficult to see exactly what went wrong when a test
fails
* this is all the more true with nesting types that have complex fields as properties of complex fields;
when isa.employee_record x fails you only know that either x was not an object or that any nested
field such as person.address.city.postcode was not satisfied
* prior versions of this library attempted to solve the problem by tracing the execution of all the test
triggered by calling an isa or a validate method; however, this was cumbersome and wasteful as
collecting the traces needs time and RAM for each single isa and validate method call, whether the
traces are used afterwards or, most of the time, silently discarded
* another problem with tracing is that, in the interest of performance, tests are shortcut, meaning that the
first failed test in a series of tests will cause a negative result, without the subsequent tests being
performed; this means that traces can only ever report the first failure of a complex type check, not
all of the failures
* evaluate methods let users obtain a succinct catalog of all the transitive fields of a given type
declaration and how they fared
* evaluate[type] x will always return a flat object whose keys are fully qualified type names (like
person.address.city); they will appear in order of their declaration with type coming first, so the
object returned by evaluate.person x will always have person as its first key, and the one returned by
evaluate.person.address x will always have person.address as its first key

Sum Types (Variants) and Product Types (Records)

Variants can be defined with or without a qualifier*, a syntactic element that precedes a type name
Variants without* qualifiers ('unqualified variants') can be defined by using a logical disjunction
(or, ||) in the test method. For example, one could declare a type boolordeep like this:

`coffee
declarations:
boolordeep: ( x ) -> ( @isa.boolean x ) or ( x is 'deep' )
`

which will be satisfied by any one of the three values true, false, and (the string) 'deep', to the
exclusion of any other values.
'Qualified* variants' do use an explicit qualifier that is meant to be used in conjunction with other
types, for example:

`coffee
declarations:
nonempty: { role: 'qualifier', }
'nonempty.list': ( x ) -> ( @isa.list x ) and ( x.length isnt 0 )
'nonempty.set': ( x ) -> ( @isa.set x ) and ( x.size isnt 0 )
`

* Having declared the above types—the qualifier nonempty with its two branch types nonempty.list and
nonempty.set—we can now test for any of:
* isa.nonempty.list x: whether x is a list with non-zero x.length
* isa.nonempty.set x: whether x is a set with non-zero x.size
* isa.nonempty x: whether x satisifes either isa.nonempty.list x or isa.nonempty.set x
* In other words, the qualifier is what becomes the variant—isa.nonempty.list and isa.nonempty.set are
ordinary tpes (though conceivably one could declare them as unqualified variants, as shown above)
* 'Product types' or 'records', on the other hand, are types that mandate the presence not of alternatives,
but of named fields each of which must satisfy its own test method for the record to be valid
* Clarification of terminology:
an explicit qualifier is what goes in front of a qualified typename*;
a variant* is a type that has several equivalent alternatives to choose from;
an implicit variant* is a type that has several equivalent alternatives to choose from that are however
not formally declared to the InterType API but inside a test method that contains disjunctions (foo: (
x ) -> ( @isa.a x ) or ( @isa.b x ))
an explicit variant* comes about by using a (chain of) qualifier(s) as a typename; so when we have
declared empty as a qualifier and set up tests for both empty.text and empty.list, then the
explicit variant empty can be tested for with isa.empty x, which will return true for exactly the
values '' and [].

$3

A valid declaration is either

* a test method, or
* the name of an existing type, or
* an object with the following fields:
* test: either a test method or the name of existing type (the latter will be compiled into the
former)
* template
* fields: keys are type names, values are declarations
* create()

Namespaces and Object Fields

* two ways to specify fields on objects
* either in the 'nested style', by using the fields entry of a type declaration; for example:

`
declarations:
quantity:
test: 'object'
fields:
q: 'float'
u: 'text'
`

* or in the 'flat style', by using dot notation in the type name:

`
declarations:
quantity: 'object'
'quantity.q': 'float'
'quantity.u': 'text'
`

* the two styles are identical and have the same result.
* you can now call the following test methods:
* types.isa.quantity x: returns true iff x is an object with (at least) two properties q and u
whose individual test methods both return true as well
* types.isa.quantity.q x: returns true iff x is a float
* types.isa.quantity.u x: returns true iff x is a text
* at least for the time being,
* a type T with field declarations must have its test entry set to object, and,
* when flat style is used, type T must be declared before any field is declared.
* if there is an existing declaration for type T, the only way to add fields to it is by using the flat
declaration style
* field declarations constitute isolated namespaces, meaning that types.isa.text—that is, type text in
the root namespace—is entirely separate from, say, types.isa.product.rating.text, which is type text
in the rating namespace of type product in the root namespace.
* fields can be indefinitely nested, e.g.:

`
types.declare { 'person': 'object', }
types.declare { 'person.name': 'text', }
types.declare { 'person.address': 'object', }
types.declare { 'person.address.city': 'object', }
types.declare { 'person.address.city.name': 'text', }
types.declare { 'person.address.city.postcode': 'text', }
`

Invariants

* a declaration that identifies a known type with a string of characters S as in T: 'some.test.here' is
equivalent to using the same string S to spell out a (possibly dotted, thus compound chain of) property
accessor(s) to @isa inside a test method, as in T: ( x ) -> @isa.some.test.here x
* a constant (literal) property accessor (which may be dotted or not) to isa, isa.optional, validate
and validate.optional is equivalent to the bracket notation with a string literal (or a variable) on the
same base; thus, isa.some.accessor x is equivalent to isa[ 'some.accessor' ] x
* the type_of() method of Intertype_minimal instances can only report the types of null and
undefined (as 'null' and undefined'); all other values are considered 'unknown'. However, it is
possible to test for isa.anything x, isa.nothing x, isa.something x, isa.unknown x (and, of
course, isa.undefined x and isa.null x).

partial / incomplete type system
total type system

(may fail)
`coffee
mulint: ( a, b = 1 ) ->
validate.integer a
validate.integer b
return validate.integer a * b
`

Browserify

`bash
browserify --require intertype --debug -o public/browserified/intertype.js
`

To Do

* [–] in _compile_declaration_object(), add validation for return value
* [–] implement using optional in a declarations, as in { foo: 'optional.text', }
* [–] what should RHS optional.foo.bar mean, is it potentially different from foo.optional.bar (even
if we never want to implement the latter)? Observe that wile optional.foo.bar might mean something
different than foo.optional.bar, when testing for isa.optional.foo.bar x we apparently still
understand foo.bar as a (compound) fully qualified name of a type (bar in namespace foo) that in its
entirety may be present or absent
* [–] consider to disallow optional except in front of a simple type name (without dots)
* [–] test create() method for the recursive case
* [–] acquire deep-freezing method
* [–] use deep-freezing for declaration
* [–] use deep-freezing for generated values when so configured / by default? maybe instantiation
setting?
* [–] what do when, in the declaration, ...
* [–] there's fields but no template
* [–] there's template but no fields
* [–] there's template but no fields, and all fields in template are constants (is it even worth
caring about?)
* [–] there's template but it's a function
* [–] evaluate.cardinal Infinity returns { cardinal: false }; evaluate.posnaught.integer Infinity
returns { 'posnaught.integer': false }; in both cases, more details would be elucidating (Infinity
satisfies posnaught but not integer)
* [–] consider to enrich result of evaluate methods with length-limited rpr() and type of values
encountered
* [–] implement an explain or report method that shows a table with all the tests and what the
actual values were that evaluate enountered
* [–] work out terminology concerning fields, sub-types (as opposed to derived types), and the to-be
implemented 'qualifiers'
* [–] nonempty etc. could be autogenerated: go through each enumerable property T of
isa.nonempty and add a test ( @isa[ T ] x ) and ( @isa.nonempty[ T ] x
* [–] need a term for the 'sub-methods' that get attached as props to the 'target methods'(??), e.g.
after isa.quantity() has been set 'sub-methods' isa.quantity.q(), isa.quantity.u() will be set as
properties of their 'target' isa.quantity; the current terminology is unfortunate and obfuscates more
than it elicits
* [–] clarify difference between basetypes and meta/quasitype optional, provide a type for the union
of both
* [–] Type roles:
* basetype
* optional
* usertype
* qualifier
* negation (?)
* [–] in addition to setting role, allow users to set { test: '@qualifier' } which then can be
shortened to empty: '@qualifier' in dotted field enumerations (maybe really the preferred way to
differentiate qualifier trees from nested records)
* [–] implement method to supply all types that are present in _isa but missing from
default_declarations
* [–] consider to relegate private module exports to sub-key testing or similar
* [–] implement a type forbidden that, in contradistinction to established rules, does throw an error
from its test method when a record with a field thusly marked is encountered; this is to ease transition
when extransous fields are removed from record types

Is Done

* [+] hard-wire basic types anything, nothing, something, null, undefined, unknown
* [+] allow stand-alone methods ({ type_of } = new Intertype())
* [+] ensure all methods have reasonable names
* [+] use proper error types like Validation_error
* [+] make it possible for Intertype methods to use an internal, private instance so type and arity
testing is possible for its own methods
* [+] throw error with instructive message when a type testing or type_of() is called with wrong arity
* [+] throw error with instructive message when an undefined type is being accessed as in isa.quux x
* [+] ensure that optional cannot be used as a type name
* [+] type-check declaration function (a.k.a. isa-test)
* [+] given a declaration like this:

`coffee
declarations =
float:
test: ( x ) -> Number.isFinite x
create: ( p ) -> parseFloat p
`

determine at what point(s) to insert a type validation; presumably, the return value of create() (even
of one generated from a template setting) should be validated

* [+] validate that create entries are sync functions
* [+] validate nullarity of template methods when no create entry is present
* [+] implement a way to keep standard declarations and add own ones on top:
* by implementing a declare() method (which accepts an object with named declarations)
* by exporting (a copy of) default_declarations
* by allowing or requiring a cfg object with an appropriate setting (default_types: true?)
* by implementing Intertype#declarations as a class with an add() method or similar
* [+] allow overrides when so configured but not of built_ins? the 'basetypes'
anything, nothing, something, null, undefined, unknown, or the 'meta type' optional
* [+] what about declarations with missing test? ensure an error is thrown when no test
method is present
* [+] enable setting test to the name of a declared type
* [+] allow name-spacing a la isa.myproject.foobar()? and use it to implement fields
* [+] when fields are implemented, also implement modified rules for test method
* [+] in isa.foo.bar x, foo is implemented as a function with a bar property; what about the
built-in properties of functions like name and length?
* [–] can we use Function::call f, ... instead of f.call ... to avoid possible difficulty if
call should get shadowed?
* [+] allow declaration objects
* [+] remove 'dogfeeding' (class _Intertype), directly use test methods from catalog instead
* [+] fix failure to call sub-tests for dotted type references
* [+] fix failure to validate dotted type
* [+] make get_isa() &c private
* [+] consider to replace override with the (clearer?) replace disallow
overrides
* [+] remove indirection of declare(), _declare() keep indirection of declare() to
avoid 'JavaScript Rip-Off' effect when detaching unbound method
* [+] test whether correct error is thrown throw meaningful error when declare
is called with unsuitable arguments
* [+] unify usage, orthography of 'built ins', 'builtins' (?), 'base type(s)', 'basetype(s)' ->
'basetype(s)'
* [+] currently basetype is declared as ( ( typeof x ) is 'string' ) and ( x is 'optional' or
Reflect.has built_ins, x )
checking for string is redundant checking for ( ( typeof x ) is 'string' ) is not*
redundant as it prevents errors when isa.basetype() is called with a non-object value
* should optional be included?
* [+] fix wrong usage of Reflect.has() in _isa.basetype() (returns true for toString)
* [+] to fix implementation failure connected to RHS optional prefix:
* [+] commit current state, mistakes and all
* [+] identify and rip out all places concerned with is_optional and/or RHS optional prefix
* [+] reduce tests such that valuable tests are preserved but ones using RHS optional prefix are
skipped
* [+] whatever the outcome, update docs
* [+] test whether basic types are immutable with instances of Intertype_minimal
* [+] in _compile_declaration_object(), call recursively for each entry in declaration.fields
* [+] find a way to avoid code duplication in handling of field sub_tests across all four test methods
(isa, isa.optional, validate, validate.optional) ; can we bake those right into
declarations[ type ].test()? But then what when more fields get declared?
* this wouldn't pose a problem if we required that intertype instances be closed for further
declarations before being used first; this could happen implicitly on first use
* if we didn't want that, we'd have to re-formulate the declaration's test method each time a field
is declared for a given type
* [+] implement value creation for all the builtin types
* [+] when fields are declared but no create() method is given, generate a create() method that
accepts any number of objects that, together with the template, will be condensed into one object using
Object.assign()
* [+] test that template functions are called, even when used in template fields
* [+] we should use a recursive merge() method, call it deepmerge(), instead of Object.assign()
when creating values from templates; this method should be exported for the benefit of users who want to
implement their own create() method; conceivably, deepmerge() could / should beimplemented in
webguy.props
* [+] implement method evaluate.[typename] x; like isa and validate methods, however does not
shortcut on failure but runs through all tests, returns object with named results so one can see e.g.
which fields did and which ones didn't conform
* [+] if an evaluated value is null, do we want the full complement of all the type's sub-fields
in the result or is it better to just return { [type]: false, }?
* [+] implement a generated field in declarations that eumerates all fully qualified field names that
belong to the type in question; field generated by module-level method walk_transitive_field_names()
* [+] would it be worth the effort to try and implement a 'permanent debugging' facility, one whose
calls are left in the code (maybe in the form of specially formatted comments) and can be activated when
needed? One could imagine those to produce a complete trace when activated that goes into an SQLite DB and
can then be inspected and filtered as needed. This would obviously be outside the scope of the present
package
* [+] test that a declaration with fields defaults to { test: 'object', }
* [+] implement fields
* [+] test that incorrect templates are rejected
* [+] consider to implement nonempty.text(), nonempty.list(), empty.text(), empty.list(); here,
empty and nonempty are not types names of an object with fields, and the names after the dots are not
field names; also, isa.nonempty x does not necessarily have to make sense so either it shouldn't be a
* [+] implement 'qualifiers' (as in nonempty.text) that look a lot like object fields but have a
different isa method implementation
* [+] qualifiers should be distinguished from optional which is and remains a prefix that can before
any other legal (known, declared) (fully quylified) type name, so isa.optional.nonempty.text x may be
legal but isa.nonempty.optional.text x won't
function or, if it is one, it should throw an error when called, something that has always been ruled out
so far
* [+] use prototypes of test methods throws() &c for new version of guy-test
* [+] use prototype of set equality for equals() implementation in webguy
* [+] allow undefined, null in create` methods that result in record