futilsjs v1.0.0

# futilsjs

A collection of javascript helper functions for fast vector math and more, lots more! This and all my other projects are under heavy development, so please use or try with caution.

This library is created as a personal merge of some usefull javascript functions, modules and classes that I programmed or used over the years. There are also code snippits that I picked up from forums like stackoverflow and the like. Anyway, stuff that I used, or wanted to use, and some refactored from plain C or other languages. For this reason and because I'm in the middle of this process, don't expect to much.

To make my life even more fun, I forked the hyperapp version 1 sourcecode from github, refactored it and added some usefull stuff to it like vnode attribute flattening. I'm not any garanty at the moment that futilsjs works; but it do only check in when it compiles.

Another interesting collection of function and classes is the JSONSchemaObject validator. In this context I added it to futilsjs in order to separate logic from aformjs, which is under heavy development too :).

Keep in mind that for the time being this repo will change a lot, really fast. So if you want to use it, I suggest you copy the dist file to your project and include it that way.

It is recommended to clone this repository first and then npm-link it into your own project. I do this, to fix bugs in futilsjs when they pop-up (immediatly) or add more functionality (when I get to it). There is more coming in the following months, so follow us. You don't have to clone the repo, because there is a npm package available as well. Follow the steps described below, to get futilsjs up and running.

## installation

### npm install futilsjs

Note: this is not recommended! The npm package is out of date untill the project reaches alpha state. I also want to change versioning back to v0.0.1; that would be the more realistic view of the version I am at.

But as the name suggests, it should be not more difficult then this. Go to your favorite local project that your working on and type:

$~/myprojectjs> npm install --save futilsjs

This will do all the magick for you. Now you can use futilsjs by simply refering to it from your sourcecode like so:

import { isObjectType } from 'futilsjs';
const a = isObjectType([]);
console.log('an array is not a pure object ', a !== true);

Tadaaa! Have fun using futilsjs! (BUT AGAIN, DON'T USE IT THIS WAY!)

### git clone and install futilsjs

In order to make futilsjs available to your projects we use npm-link. First clone the repository. You can use any target name as the last parameter of the git clone command. For this demonstration we use the futilsjs/ directory name and we enter it.

$~/> git clone https://github.com/jklarenbeek/futilsjs.git futilsjs
$~/> cd futilsjs
$~/futilsjs>

Then install all the necessary development dependencies. The following command will install all devDependencies from the package.json file for you automatically.

$~/futilsjs> npm install

Now its time to build it. Rollup will do an excellent job, just for that purpose. Let's run rollup by running the build script from the command line like so:

$~/futilsjs> npm run build
created ./dist/index.js in 8.8s

The resulting futilsjs distribution file is generated by rollup and copied into the dist/ directory. Lets go there and make futilsjs available to our other projects.

$~/futilsjs> cd ./dist/
$~/futilsjs/dist> npm link

Thats it! Just wauw :) futilsjs is now available for linking into your own projects.

In order to use it, you need to go to your project and use npm-link again. But this time, call futilsjs by its name.

$~/futilsjs/dist> cd ~/myprojectjs/
$~/myprojectjs> npm link futilsjs

Take note that we use the futilsjs name in the npm link command and not any other name that you cloned it to. From here its the same as using npm install futilsjs.

## documentation

Procastrination

I will look up what that means, later...

### Math and Vector classes

There are 4 extensive math classes defined in futilsjs; int32, float64, vec2i32, vec2f64 and vec3f64. The Matrix class is not yet supported. futilsjs tries to encapsulate and group math functionality as much as possible. This with the idea to help the Javascript Runtime compiler determine what we are looking at. Each class has two types of operator groups; pure and impure. As the name suggests, pure operators are immutable and return a new structure, impure operators operate on the structure itself.

The int32 and float32 classes are mere functions to help speed up your inner loops as some benchmarks suggest. However, these benchmarks are highly speculative and the results differ greatly between browser versions. I still implemented them for two reasons; 1) sometimes I like to be explicit. 2) sometimes it helps me to remember how stuff works. The int32 class also implements some complex operators like sin, cos and others too.

The vector classes vec2i32, vec2f64 and vec3f64 contain enough functionality to quickly do about any operation you want. The primitive pure operators (add, sub, mul, div) and impure operators (iadd, isub, imul, idiv) are supported for the vec2i32, vec2f64 and vec2f64 classes. They also contain product operators (mag2 - magnitude square, mag - magnitude, dot, crossABAB) and other more complex vector operators (unit, iunit).

### Javascript Type Extensions

Eventhough es2017 is becoming pretty cool, futils includes an extensive set of additional extensions to common types. We have added functionality for String and Date classes including a set of test and getters related to the javascript type system.

For object types futils has special functions to manipulate array and objects alike including types like Map.

We also added some additional classes to queue or traverse tree like data structures.

### Browser Type Extensions

Another important part of futilsjs are the browser extensions to manipulate the DOM, load or render images from svg or html, manipulate CSS classes and or use worklets.

### JSONSchemaDocument

The JSONSchemaDocument set of classes can help you build and validate JSON data structures quickly. The JSONSchemaDocument class is capable of compiling most of jsonschema draft-7 keywords and render JSX nodes (VNode) along the openapi 3 spec from swagger. Through a JSONSchemaDocument instance you can use the JSONPointer class to query for any schema or data point within the document.

## frequently asked questions

  So frequently asked
  but never out spoken
  what shadow arrises
  what hath thou awoken

## contact

If you find bugs, or want to know what a function is doing, please don't hesitate to ask me by filing an issue. Off topic questions I'd rather not see, but any futilsjs related question is very welcome.

Please file an issue at the github futilsjs repository.

Be excellent to yourself, and each other!