ig-types 6.20.4 → 6.22.0

package/Date.js

@@ -15,6 +15,15 @@ var object = require('ig-object')
 var DateMixin =
 module.DateMixin =
 object.Mixin('DateMixin', 'soft', {
+	hires: function(){
+		return typeof(process) != 'undefined' ?
+			performance.timeOrigin + performance.now() 
+			: performance.timing.navigationStart + performance.now() },
+	hiresTimeStamp: function(){
+		var t = this.hires()
+		var date = new this(t)
+		return date.getTimeStamp(true) + (''+(t-date.getTime())).slice(1) },
+
 	timeStamp: function(...args){
 		return (new this()).getTimeStamp(...args) },
 	fromTimeStamp: function(ts){

package/Promise.js

@@ -801,6 +801,22 @@ object.Mixin('PromiseMixin', 'soft', {
 	iter: IterablePromise,
 	interactive: InteractivePromise,
 	cooperative: CooperativePromise,
+
+	awaitOrRun: function(data, func){
+		data = [...arguments]
+		func = data.pop()
+		// ceck if we need to await...
+		return data
+				.reduce(function(res, e){
+					return res 
+						|| e instanceof Promise }, false) ?
+			// NOTE: we will not reach this on empty data...
+			(data.length > 1 ?
+				Promise.all(data)
+					.then(function(res){ 
+						return func(...res) })
+				: data[0].then(func))
+			: func(...data) },
 })
 
 PromiseMixin(Promise)

package/README.md

@@ -94,6 +94,8 @@ Library of JavaScript type extensions, types and utilities.
     - [Promise proxies](#promise-proxies)
       - [`<promise>.as(..)`](#promiseas)
       - [`<promise-proxy>.<method>(..)`](#promise-proxymethod)
+    - [Promise utilities](#promise-utilities)
+      - [`Promise.awaitOrRun(..)`](#promiseawaitorrun)
   - [Generator extensions and utilities](#generator-extensions-and-utilities)
     - [The basics](#the-basics)
       - [`generator.Generator`](#generatorgenerator)
@@ -160,6 +162,7 @@ Library of JavaScript type extensions, types and utilities.
   - [Event](#event)
     - [`event.Eventfull(..)`](#eventeventfull)
     - [`event.Event(..)`](#eventevent)
+    - [`event.PureEvent(..)`](#eventpureevent)
     - [`event.TRIGGER`](#eventtrigger)
     - [`event.EventHandlerMixin`](#eventeventhandlermixin)
       - [`<obj>.on(..)`](#objon)
@@ -635,11 +638,17 @@ Compare to arrays ignoring element order and count.
 Sort array as a different array.
 ```bnf
 <array>.sortAs(<other>)
+<array>.sortAs(<other>, 'head')
+    -> <array>
+
+<array>.sortAs(<other>, 'tail')
     -> <array>
 ```
 
 Elements not present in `<other>` retain their relative order and are
-placed after the sorted elements.
+placed after the sorted elements if `'head'` (i.e. _"sorted at head of 
+array"_) is passed as second argument (default) and before them if 
+`'tail'` (_"sorted at tail"_) is passed.
 
 Example:
 ```javascript
@@ -1992,6 +2001,22 @@ the main `<promise>` is resolved.
 
 
 
+### Promise utilities
+
+#### `Promise.awaitOrRun(..)`
+
+Await for inputs if any of them is a promise and then run a function with 
+the results, otherwise run the function in sync.
+
+```dnf
+Promise.awaitOrRun(<value>, <func>)
+Promise.awaitOrRun(<value>, .. , <func>)
+	-> <promise(value)>
+	-> <value>
+```
+
+
+
 ## Generator extensions and utilities
 
 ```javascript
@@ -2829,6 +2854,9 @@ otherwise [`.unorderedRename(..)`](#unique-key-mapunorderedrename) is called.
 
 ## Event
 
+This module defines a set of pure-JavaScript event-like method constructors 
+and utilities.
+
 ```javascript
 var event = require('ig-types/event')
 ```
@@ -2836,60 +2864,199 @@ var event = require('ig-types/event')
 
 ### `event.Eventfull(..)`
 
-<!-- XXX -->
+Create and eventful method.
+```dnf
+event.Eventfull(<name>[, <options>])
+event.Eventfull(<name>, <func>[, <options>])
+	-> <method>
+```
+
+An eventful method is a method that can be called either directly or via
+`.trigger(<method-name>, ..)`.
+
+
+Calling an eventful method will call `<func>(..)` if defined and will 
+trigger the eventful method's handlers trigger, either after `<func>(..)` 
+returns or when `<hander>(..)` is called within `<func>(..)`.
+```dnf
+<method>(..)
+	-> <value>
+```
+
+Note that if `<func>(..)` returns `undefined` then `<method>(..)` will 
+return either `this` or `undefined` depending on `<options>.defaultReturn` 
+being set to `'context'` (default) or `undefined` resp.
+
+
+Handlers can be bound to an eventful method via `.on(<method-name>, ...)`,
+unbound via `.off(<method-name>)`, 
+see: [`event.EventHandlerMixin`](#eventeventhandlermixin) for more info.
+
+```dnf
+<handler>(<event-name>, ...)
+```
+
+
+The event `<func>(..)` gets the `<handle-func>(..)` as first argument 
+followed by the arguments passed to `<method>(..)` when called.
+```dnf
+<func>(<handle-func>, ...)
+	-> <value>
+```
+
+`<handle-func>(..)` controls when the event handlers are called.
+```dnf
+<handle-func>()
+<handle-func>(true)
+	-> true
+	-> false
+
+<handle-func>(true, ...)
+	-> true
+	-> false
+```
+
+Calling `<handle-func>(..)` is optional, if not called the handlers will 
+get triggered after `<func>(..)` returns.
+
+
+Passing `false` to `<handle-func>(..)` will prevent the event handlers 
+from being called.
+```dnf
+<handle-func>(false)
+	-> undefined
+```
+
+Note that for `async` event `<func>(..)` it might be useful to trigger 
+the handlers after the promise resolves, this can be done by first calling
+`<handle-func>(false)` to prevent the handlers from being triggered as soon
+as the promise is returned and after an appropriate `await`ing calling
+`<handle-func>()` to actually trigger the handlers.
+
+Example:
+```javascript
+var evt = event.Event('evt', async function(handler, ...args){
+	handler(false)
+	var value = await something()
+	handler()
+	return value })
+```
+
+
+**Special case: `<event-commands>`**
+
+`<event-command>`s are instances of `EventCommand` that are handled by 
+event methods in a special way.
+
+```dnf
+<method>(<event-command>, ...)
+	-> <value>
+
+<func>(<handle-func>, <event-command>, ...)
+	-> <value>
+```
+
+`EventCommand` instance can be passed as the first argument of `<method>(..)`, 
+in this case the event function will get it but the event handlers 
+will not.
+
+This is done to be able to externally pass commands to event methods
+that get handled in a special way by the function but not passed to 
+the event handlers.
+
+For an example of a built-in `<event-command>` see: [`event.TRIGGER`](#eventtrigger) 
+
 
 
 ### `event.Event(..)`
 
-<!-- XXX -->
+Extends `Eventful(..)` adding ability to bind events via the resulting 
+method directly by passing it a function.
+
+```dnf
+<method>(<handler>)
+	-> <this>
+```
+
+
+### `event.PureEvent(..)`
+
+Like `Event(..)` but produces an event method that can only be triggered 
+via .trigger(name, ...), calling this is a no-op.
+
 
 
 ### `event.TRIGGER`
 
-<!-- XXX -->
+Special value (`<event-command>`) that when passed to an event method as 
+first argument will force it to trigger event if the first argument was 
+a function.
 
 
-Special value when passed to an event method as first argument will force it 
-to trigger event if the first argument was a function.
 
 ### `event.EventHandlerMixin`
 
-<!-- XXX -->
+A _mixin_ defining the basic event API.
+
+For more info on mixins see: 
+https://github.com/flynx/object.js#mixin
 
 
 #### `<obj>.on(..)`
 
-<!-- XXX -->
+Bind a handler to an _event_ or an _eventful_ method.
+```dnf
+<obj>.on(<event-name>, <handler>)
+	-> <obj>
+```
 
 
 #### `<obj>.one(..)`
 
-<!-- XXX -->
+Like `<obj>.on(..)` but the `<handler>` will be called only once.
+```dnf
+<obj>.one(<event-name>, <handler>)
+	-> <obj>
+```
 
 
 #### `<obj>.off(..)`
 
-<!-- XXX -->
+Unbind `<handler>` from _event_.
+```dnf
+<obj>.off(<event-name>, <handler>)
+	-> <obj>
+```
 
 
 #### `<obj>.trigger(..)`
 
-<!-- XXX -->
+Trigger an _event_.
+```dnf
+<obj>.trigger(<event-name>)
+<obj>.trigger(<event-name>, ...)
+	-> <obj>
+```
+
 
 
 ### `event.EventDocMixin`
 
-<!-- XXX -->
+A _mixin_ defining the basic event introspection API.
+
+For more info on mixins see: 
+https://github.com/flynx/object.js#mixin
 
 
 #### `<obj>.eventfull`
 
-<!-- XXX -->
+Property listing the _eventful_ method names in the current context.
 
 
 #### `<obj>.events`
 
-<!-- XXX -->
+Property listing the _event_ method names in the current context, this 
+also will include _eventful_ method names.
 
 
 ### `event.EventMixin`
@@ -2897,6 +3064,10 @@ to trigger event if the first argument was a function.
 Combines [`event.EventHandlerMixin`](#eventeventhandlermixin) and 
 [`event.EventDocMixin`](#eventeventdocmixin).
 
+For more info on mixins see: 
+https://github.com/flynx/object.js#mixin
+
+
 ## Runner
 
 ```javascript

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ig-types",
-  "version": "6.20.4",
+  "version": "6.22.0",
   "description": "Generic JavaScript types and type extensions...",
   "main": "main.js",
   "scripts": {