@antcolag/tools - npm Package Compare versions

Comparing version 2.0.1 to 2.0.2

.gitlab-ci.yml

docs/debug.md

		@@ -1,10 +0,12 @@
		Debug
		===
		# Debug

		Debugging utilities wrapped in hendlers.
		Most of the debugging functionality are skipped
		when the ```DEBUGGING``` member of the module is falsy
		The module contains collection of functions for type checking and to handle
		statements like throw and debug, as functions.

		ASSERT
		---
		It also exposes a ```DEBUGGING``` that can be used to controll some behaviour
		of your functions. Can be changed using the DEBUG function exposesd in the
		module.

		## ASSERT

		compare two values vith strict equal operator, if they are not equal, will [croak](debug.md#croak) an exception
		@@ -22,6 +24,6 @@ ```javascript
		```
		---

		ASSERT_T
		---

		## ASSERT_T

		Assert true but not strictly, if you pass a falsy value will throw that value
		@@ -40,6 +42,5 @@ ```javascript
		```
		---

		ASSERT_F
		---
		## ASSERT_F

		Assert false but not strictly, if you pass a truthy value will throw that value
		@@ -58,20 +59,6 @@ ```javascript
		```
		---

		DEBUGGING
		---
		Userfull to check the debugging status
		```javascript
		import { DEBUGGING } from './debug.js'
		if(DEBUGGING){
		console.warn('debugging mode')
		}
		else {
		console.log('normal mode')
		}
		```
		---

		croak
		---
		## croak

		Functional wrapper for ```throw```
		@@ -83,6 +70,6 @@ ```javascript
		```
		---

		pause
		---

		## pause

		Functional wrapper for ```debugger``` directive
		@@ -94,6 +81,5 @@ ```javascript
		```
		---

		DEBUG
		---
		## DEBUG

		Sets the debugging status
		@@ -103,6 +89,36 @@ ```javascript
		DEBUG(false)
		console.log('debugging?', debug.DEBUGGING)
		console.log('are in debugging mode?', debug.DEBUGGING)
		DEBUG(true)
		console.log('debugging?', debug.DEBUGGING)
		console.log('are in debugging mode?', debug.DEBUGGING)
		```
		---

		## DEBUGGING

		Check the debugging status
		```javascript
		import { DEBUGGING } from './debug.js'
		if(DEBUGGING){
		console.warn('debugging mode')
		}
		else {
		console.log('normal mode')
		}
		```

		## Good and crap

		Functions for type checking

		```javascript
		const num = 1

		// throw if type of num is not Number
		good(num, Number)

		// throw if type of num is object
		crap(num, Object)

		// more than one type can be checked
		good(1, Boolean, Number)

		crap(1, Boolean, Object)

docs/dom.md

		@@ -1,9 +0,16 @@
		Dom
		Dom printer
		===

		It provides a couple of userfull tools:
		It provides a class that exports functions to build HTML fragments.


		- emmet: will build a dom from an emmet like string
		- html: will print a dom from an html like string

		The functions are to be used as template string tag.

		The module exports the above functions exposed from a shared instance but you
		can create an instance of the DomPrinter class and use it with custom
		settings

		Example
		@@ -18,15 +25,21 @@ ---
		)
		// in the console you can see the builded DocumentFragment instancies
		// in the console you can see the built DocumentFragment instancies
		```

		DomPrinter
		DomPrinter class
		---
		This is the class that exposes the `html` and `emmet` methods.

		You can use an instance of this class if you have to handle the concrete building of the dom, the default builder is a wrapper for
		The constructor accepts a builder function to transform the resulting
		html string, and a filter function to parse the argumets passed to the
		template string tag

		`document.createRange().createContextualWrapper( /* your string */ )`
		You can use an instance of this class if you have to handle the building of the
		dom, the default builder is a wrapper for `Range.createContextualFragment`

		so it will render a DocumentFragment instance in the browser.
		so it will render a DocumentFragment in the browser.

		If you have to build different objects you can set a different builder in the class. The result must anyway implement some basic Element's methods ie querySelectorAll, setAttributeNode and append.
		If you have to build different objects you can set a different builder in the
		class. The result must anyway implement some basic Element's methods ie
		querySelectorAll, setAttributeNode and append.

		@@ -33,0 +46,0 @@ Example

docs/observe.md

		@@ -5,3 +5,3 @@ Observe

		It exploit the [injectProperties](utils.md#The-injectProperties-function) and add the
		Adds the
		- on: run the handler every time of the event occurs
		@@ -8,0 +8,0 @@ - once: run the handler once

docs/reactive.md

		Reactive
		===
		This extension provide a way to build a bind betwin the properies of two or more objcets.
		Binds properies between objects.

		Description
		---
		Is userfull when you need to mantain aligned the properties of a set of objects. But is perfect for build graphic interfaces because it semplify the binding between a model object and the UI for visualize data.

		Initialization
		---
		```javascript
		@@ -26,26 +21,24 @@ // you can initialize an existing object

		Provides
		bindable
		---
		> bindable
		> ---
		> declare a bindable property
		> ```javascript
		> var instance = reactive.call({})
		> instance.bindable("property")
		> ```
		> ---
		> bind
		> ---
		> binds an object to a reactive instance
		> ```javascript
		> var other = {}
		> instance.bind("property", other)
		> ```
		> ---
		> unbind
		> ---
		> unbinds a property from the reactive instance
		>```javascript
		> instance.unbind("property", other)
		> ```
		declare a bindable property
		```javascript
		var instance = reactive.call({})
		instance.bindable("property")
		```
		---
		bind
		---
		binds an object to a reactive instance
		```javascript
		var other = {}
		instance.bind("property", other)
		```
		---
		unbind
		---
		unbinds a property from the reactive instance
		```javascript
		instance.unbind("property", other)
		```

		@@ -55,3 +48,4 @@
		---
		You only need to inject his instance in the object you want to enhance, declare the bindable properties and then bind the object you want to mantain aligned
		Declare the bindable properties and then bind the object you want keep
		syncronized

		@@ -82,3 +76,3 @@ ```javascript
		---
		It explots getters and setters for properties you want to share, so it cannot export property that already use getters or setters like the magic properties of the built in object of the browsers (ie you cannot make innerHTML on an HTMLElement bindable, but you can bind the innerHTML property of an HTMLElement to an object you build)
		It cannot export property that use getters or setters already

		@@ -89,4 +83,3 @@ ```javascript

		// this will auto update the innerHTML of the first
		// HTMLAnchorElement in the document when o.innerHTML
		// this will auto update the innerHTML when o.innerHTML
		// changes
		@@ -93,0 +86,0 @@ var o = new reactive()

docs/test.md

		Test
		===
		Mini test suite
		Test suite

		Test
		---
		test suite
		test class

		@@ -9,0 +9,0 @@ ---

docs/tools.md

		Tools
		===

		This module provides a set of functionalities userfull for build interface generators.
		This module provides a set of functions to build the interface generators used
		for reactive, readable and observable.

		@@ -9,5 +10,2 @@ The injectProperties function

		Is userfull for add methods and properties.
		The injectProperties is the foundation of reactive, observable and readable interfaces.

		### Example
		@@ -25,18 +23,1 @@
		```

		Despite the apparence it can be very userfull for inject interfaces directly in a class prototype, like they where defined inside the class

		```javascript
		const myInterface = {
		foo() { /* ... */ },
		bar() { /* ... */ }
		}

		class First { /* ... */ }
		class Second { /* ... */ }

		injectProperties.call(First.prototype, myInterface)
		injectProperties.call(Second.prototype, myInterface)
		```

		Now all the instances of First as well as all the instances of Second will have a non iterable reference to foo and bar method in their class prototype hierarchy. Prety cool, isn't?

docs/utils.md

		Utils
		===

		Is a collection of some userfull functions, like comparer, and operation generators.

		These function are maded mostly as support functionalities, like default parameter, for handlers and function reference in general, so you don't have to redefine those functions everytime, saving up time and memory.

		See api documentation for an exaustive list of the exposed functions
		Collection of functions and operation like a noop, a pipe, true/false ecc

package.json

		{
		"name": "@antcolag/tools",
		"version": "2.0.1",
		"version": "2.0.2",
		"description": "npm wrapper for tools",
		@@ -20,3 +20,3 @@ "scripts": {
		"type": "git",
		"url": "git+https://github.com/antcolag/npm-tools.git"
		"url": "git+https://gitlab.com/antcolag/npm-tools.git"
		},
		@@ -23,0 +23,0 @@ "keywords": [

238

README.md

		@@ -1,40 +0,37 @@
		Tools
		===
		userfull es6 mini library
		# Tools A Functional E6 Library

		## What it does provide
		The library is a collection of JavaScript functions that I found useful, grouped in ES6
		modules.

		In this library you can find utilities for
		* generic purpuse -> [utils.mjs](docs/utils.md)
		* generator for object conposition -> [tools.mjs](docs/tools.md)
		* observer pattern interface -> [observe.mjs](docs/observe.md)
		* reactive pattern interface -> [reactive.mjs](docs/reactive.md)
		* a mini test suite -> [test.mjs](docs/test.md)
		* debuging handlers -> [debug.mjs](docs/debug.md)
		* dom printing -> [dom.mjs](docs/dom.md)
		## In this library you can find utilities for

		# Examples
		* [HTML printing](docs/dom.md)
		* [test suite](docs/test.md)
		* [debugging library](docs/debug.md)
		* [observer pattern interface](docs/observe.md)
		* [reactive pattern interface](docs/reactive.md)
		* [base utils](docs/utils.md)
		* [base tools](docs/tools.md)

		I think that the test suite, the dom utilities, and the ```observable``` and ```reactive``` interfaces deserve quick but in depth view
		# Some examples

		Test suite
		---
		The following examples assume that the repository is cloned in the current
		direcotry.

		This mini test class is super easy to use but work super well!
		## Test suite

		you can define your test scenario and if something goes wrong (ie if something is thrown, like an unhandled runtime error), then the test will *fail* and a fail message will be printed the console. Otherwise it will *pass* and a passed message in console will be printed.
		A class for test handling is provided in the test.mjs module

		```javascript
		import Test from "./test.mjs";
		// ASSERT will throw an error if strict equal comparison fails
		import { ASSERT } from "./debug.mjs";
		import Test from "./tools/test.mjs";

		// the function to be tested
		// The ASSERT function throws an error if strict equal comparison fails
		import { ASSERT } from "./tools/debug.mjs";

		// The function to be tested, it simply sums the arguments if there are any,
		// otherwise it will throw an error
		const sum = (...arg) => {
		// ...
		// if something goes wrong
		// throw it with no mercy!!
		if(!arg.length){
		throw new Error("no arguments!");
		}
		// simply sum the arguments
		return arg.reduce((prev, curr) => {
		@@ -45,31 +42,43 @@ return curr + prev

		// define your test
		const test = new Test("2 + 2 should return 4", (N) => {
		ASSERT(sum(2, 2), 4)
		// Define your test case
		const test = new Test(
		// Add a description
		"2 + 2 should return 4",

		// define the test case
		(N) => {
		ASSERT(sum(2, 2), 4)

		// test the 1 + 2 + 3 + ... + N serie
		var args = []
		for(var i = 1; i <= N; i++) {
		args.push(i)
		// You can run the test using different arguments
		// ie test the 1 + 2 + 3 + ... + N series
		var args = []
		for(var i = 1; i <= N; i++) {
		args.push(i)
		}

		ASSERT(sum.apply(this, args), N * (N + 1) / 2 )
		}
		ASSERT(sum.apply(this, args), N * (N + 1) / 2 )
		})
		)

		// run it!
		// Run with 100 as argument
		test.run(100)

		// Verify that your test case throws an error if called with no arguments
		test.die()
		```

		Dom utilities
		---
		## Dom utilities

		A set of a fiew userfull utilities for building user interfaces
		A set of functions to build HTML fragments

		```javascript
		// import the library
		import * from dom from "./dom.mjs";
		// Import the library
		import * from dom from "./tools/dom.mjs";

		// you can use your own elements
		document.body.appendChild(dom.html `<span>ipsum</span>`)

		// You can use your own elements
		const myTitle = document.createElement('h2')

		// print a dom fragment in the body
		// The following statement prints a DocumentFagment in the body
		document.body.appendChild(dom.html `
		@@ -81,6 +90,6 @@ <article>

		// of course you can handle your element after it has been printed
		// You can handle myTitle element after it has been printed too
		myTitle.innerHTML = 'hello world'
		```
		And it work with an *emmet-like* sintax too!
		And it also works with an *emmet-like* sintax too!

		@@ -90,3 +99,3 @@ ```javascript

		// print a dom fragment in the body... in emmet dialect!
		// The following statement prints a dom fragment in the body... in emmet dialect
		document.body.appendChild(
		@@ -96,25 +105,28 @@ dom.emmet `article>${myTitle2}.title>span{hello }`

		// of course you can still handle your element after
		// You can still handle your element after
		myTitle2.innerHTML += 'emmet!'
		```

		Observer
		---
		## Observer

		It implements the observer pattern in the objects where is injected.
		It is an observer pattern interface injectable in objects.
		The following functions are injected to myObj when `observable.call(myObj)`
		is called
		- `on` to append a handler to a event
		- `off` to remove a handler
		- `once` to append a handler to an event and call it once
		- `fire` to call all the handlers associated to an event

		For example:

		```javascript
		import observable from "./observe.mjs"
		import observable from "./tools/observe.mjs"

		// take your class
		class FireworkClass {
		now(...args){
		// do some magic stuff
		// then...
		this.fire('fireworks!', ...args)
		// the following class will trigger the event "firework" repeatedly
		class Firework {
		#counter = 0
		// triggers the event using "fire" and then reschedule it
		now(){
		this.fire('fireworks', ++this.#counter)
		this.schedule()
		}
		// never stop the fireworks <3

		schedule() {
		@@ -127,87 +139,65 @@ setTimeout(
		}
		// and inject the interface
		observable.call(FireworkClass.prototype)
		```
		The `observable.call(FireworkClass.prototype)` will add the function for handle events
		- on
		- off
		- once
		- fire

		*fire* will dispatch the event
		```javascript
		// you can inject the interface to the prototype
		observable.call(Firework.prototype)

		// ...
		// create instance of Firework
		let firework = new Firework()

		// create instance
		let firework = new FireworkClass()

		// add an event handler for both the events
		firework.on('fireworks!', (...args) => {
		console.log('this fireworks are beautiful', ...args)
		firework.on('fireworks', (counter) => {
		console.log('firework event triggered!', counter)
		})

		// ...

		// let's do the fireworks now!
		firework.now( /* [...args] */ )
		firework.now()
		```

		Reactive
		---
		Sincronize variation between different objects
		## Reactive

		This interface can be used to keep the state of different objects synchronized

		```javascript
		import reactive from "./reactive.mjs"
		import reactive from "./tools/reactive.mjs"

		// define MyReactiveClass
		class MyReactiveClass {
		// The instances from the following class expose a property named "foo"
		// that can be used to update a property of other objects
		class MyReactive {
		constructor() {
		// make magicProperty bindable
		this.bindable("magicProperty")
		// Exposes foo as bindable. Assumes that the interface is injected
		this.bindable("foo")
		}
		}
		// add reactive inteface to MyReactiveClass's prototype
		reactive.call(MyReactiveClass.prototype)
		```
		After you have injected the interface, the instances can have some *bindable* properties
		```javascript
		// create instance
		let myReactiveInstance = new MyReactiveClass()
		let myObj = {} // given an object
		// you can bind the
		// magicProperty of myReactiveInstance
		// to myObj's magicProperty
		myReactiveInstance.bind('magicProperty', myObj)
		// Adds reactive interface to MyReactive's prototype
		reactive.call(MyReactive.prototype)

		myReactiveInstance.magicProperty = 'hello reactive!'
		// will print 'hello reactive!'
		console.log(myObj.magicProperty)
		```
		This can be userfull when building user interfaces because...
		```javascript
		// you can of course bind a reactive object
		// with different properties another object
		// Creates an instance and a target object
		let myReactive = new MyReactive(), myTarget = {}

		// You can bind the "foo" of myReactive to myTarget's "foo" property
		myReactive.bind('foo', myTarget)

		// Changes on myReactive.foo will be reflected to myTarget.foo
		myReactive.foo = 'hello reactive!'

		// The following statement will print 'hello reactive!'
		console.log(myTarget.foo)

		// You can use reactive to update the text inside HTML elements
		let element = document.querySelector('#my-element')
		if(element) {
		myReactiveInstance.bind(
		'magicProperty',
		myReactive.bind(
		'foo',
		element,
		'innerHTML'
		)
		// the html content of #my-element
		// will be updated when the magicProperty change
		}
		myReactiveInstance.magicProperty = 'hello again!'
		```
		sometimes can be userfull also to bind a method of an object to a bindable reactive's property
		```javascript
		// and you can surely use it with functions
		myReactiveInstance.bind(
		'magicProperty',
		myReactive.foo = 'hello again!'

		// You can also bind the property changes to a function
		myReactive.bind(
		'foo',
		console.log.bind(console)
		)

		// now we will also print the magicProperty value
		// in console when the magicProperty change
		myReactiveInstance.magicProperty = 'woooow!!'
		```
		// The following assignment will call console.log
		myReactive.foo = 'woooow!!'
		```

debug.mjs