<commit_before>FirstContract
=============

A JavaScript contracting library. 

This is very much a work in progress, but it's usable. 

## Why type contracts?
A contract provides a run-time clamp around your code. As JavaScript has no
static typing (and many people, myself included, argue it doesn't necessarily
need one), sometimes it's nice, during development, to have code just die if
types don't match. 

If you declare a function that should take a non-negative, proper number, and
return a non-negative, proper number, and you want code to die then and there
if that isn't the case, then contracts are a tool to do that.

## getting firstcontract

You can install firstcontract through npm, by typing

     npm install firstcontract

or by cloning this repository. The module is written in TypeScript, which I am
learning at the moment. Ideas to improve are welcome.

## how it works

A trivial example: 

    var sum = function (a, b) {
        return a + b;
    }

To be sure that only proper numbers (a number that adheres to this contract
can be neither `NaN` nor `Infinity`) are ever encountered by that function, 
create a contract for it: 

    var contract = c(["R", "R"], "R"),
        sum = contract(function (a, b) {
            return a + b;
        });
        
`"R"` is an alias for the contract "Real numbers".

> Yes I know. IEEE-754 floating point is not "real numbers". But it's close 
> enough. 

As soon as a contract is violated, either by a contract function receiving 
the wrong arguments or returning the wrong values, the contract will make
your program blow up then and there. As such, the code between entry and 
exit of the function is guaranteed to be able to make certain assumptions. 

After development, if all contracts are usually satisfied, you can either
still leave them in, or remove them (but then you need to handle violations
yourself). 

The aliases include (this list is growing, as I added only the most useful 
ones first): 

### Numeric contracts

 - `"Z"` for integers only (Number-type values without fractional parts)
 - `"Z+0"` for non-negative integers including zero
 - `"Z+"` for positive integers 
 - `"Z-"` for negative integers
 - `"R"` for "proper" Number-type values (not `NaN` or `Infinity` values)
 - `"R+0"` for positive floating point Number-type values
 - `"R+"` for positive Number-type values
 - `"R-"`" for negative Number-type values
 
### Types
<commit_msg>Clarified example<commit_after>FirstContract
=============

A JavaScript contracting library. 

This is very much a work in progress, but it's usable. 

## Why type contracts?
A contract provides a run-time clamp around your code. As JavaScript has no
static typing (and many people, myself included, argue it doesn't necessarily
need one), sometimes it's nice, during development, to have code just die if
types don't match. 

If you declare a function that should take a non-negative, proper number, and
return a non-negative, proper number, and you want code to die then and there
if that isn't the case, then contracts are a tool to do that.

Firstcontract will throw Exceptions to have your code die.

## getting firstcontract

You can install firstcontract through npm, by typing

     npm install firstcontract

or by cloning this repository. The module is written in TypeScript, which I am
learning at the moment. Ideas to improve are welcome.

## how it works

A trivial example: 

    var sum = function (a, b) {
        return a + b;
    }

To be sure that only proper numbers (a number that adheres to this contract
can be neither `NaN` nor `Infinity`) are ever encountered by that function, 
create a contract for it: 

    var contract = c(["R", "R"], "R"),
        sum = contract(sum);
        
`"R"` is an alias for the contract "Real numbers".

> Yes I know. IEEE-754 floating point is not "real numbers". But it's close 
> enough. 

As soon as a contract is violated, either by a contract function receiving 
the wrong arguments or returning the wrong values, the contract will make
your program blow up then and there by throwing a "contract violation".
As such, the code between entry and exit of the function is guaranteed to be
able to make certain assumptions. If something unexpected happens, it happened
*in* the function which failed to fulfill its contract.

After development, if all contracts are usually satisfied, you can either
still leave them in, or remove them (but then you need to handle violations
yourself). 

The aliases include (this list is growing, as I added only the most useful 
ones first): 

### Numeric contracts

 - `"Z"` for integers only (Number-type values without fractional parts)
 - `"Z+0"` for non-negative integers including zero
 - `"Z+"` for positive integers 
 - `"Z-"` for negative integers
 - `"R"` for "proper" Number-type values (not `NaN` or `Infinity` values)
 - `"R+0"` for positive floating point Number-type values
 - `"R+"` for positive Number-type values
 - `"R-"`" for negative Number-type values
 
### Types

{'fraction_non_alphanumeric': 0.07814992025518341, 'fraction_numerical': 0.001993620414673046, 'mean_word_length': 3.733018867924528, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 7, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3967706', 'n_tokens_mistral': 1368, 'n_tokens_neox': 1284, 'n_words': 749}