funkierJS API

Usage: var result = Err(a);

An Err is a type of Result representing a unsuccessful computation. The constructor is new-agnostic. Throws if called without any arguments

var result = funkierJS.Err(new TypeError('boom');

Usage: var result = Just(a);

A Just is a type of Maybe representing a successful computation. The constructor is new-agnostic. Throws when called with no arguments.

var result = funkierJS.Just(42);

Usage: Maybe();

The Maybe type encapsulates the idea of sentinel values returned by functions to represent an error or unusual conditions. Authors can return an instance of the Just constructor when a function executes successfully, and the Nothing object when an error occurs, or the computation is otherwise unsuccessful.

Maybe is the 'base class' of Just and Nothing. It is provided only for the instanceof operator.

It is an error to call Maybe.

A Nothing is a type of Maybe representing an unsuccessful computation.

Usage: var result = Ok(a);

An Ok is a type of Result representing a successful computation. The constructor is new-agnostic. Throws when called with no arguments.

var result = funkierJS.Ok(42);

Usage: var result = Pair(a, b);

A Pair represents an immutable tuple. The constructor function takes two elements, first and second. and returns a new immutable tuple. The contents of the tuple can be accessed with the accessor functions fst and snd respectively. The constructor is new-agnostic.

The constructor is curried: when called with one argument, a function will be returned that expects a second argument; supplying this function with a value will yield a Pair. Note that the constructor is internally curried outside of the usual mechanisms.

Throws a TypeError if called with zero arguments.

var p1 = new funkierJS.Pair(2, 3);
var p2 = funkierJS.Pair(2)(3);
var pairs = funkierJS.map(funkierJS.new Pair(3), [4, 5, 6]);

Usage: Result();

The Result type encapsulates the idea of functions throwing errors. It can be considered equivalent to the Either datatype from Haskell, or the Result type from Rust.

Result is the 'base class' of Ok and Err. It is provided only for the instanceof operator.

It is an error to call Result.

Usage: var result = add(x, y);

A wrapper around the addition operator.

funkierJS.add(1, 1); // => 2

See every

Usage: var result = and(x, y);

A wrapper around the logical and (&&) operator. Returns the logical and of the given arguments

funkierJS.and(true, true); // => true

Usage: var result = andPred(f1, f2);

Takes two unary predicate functions, and returns a new unary function that, when called, will call the original functions with the given argument, and logically and their results, returning that value. Throws if either argument is not a function of arity 1.

Where possible, funkierJS will aim to replicate the currying style of the function. If either function was produced by one of the objectCurry variants, then the resulting function will also be object curried, and supply the correct execution context to the supplied functions. If neither was curried in that manner, but one or more was curried with one of the bind variants, then the resulting function will also be bound to the same context. Otherwise, the function will be curried with curry. (This is only provided in case you need to give the resulting function to one of the withArity functions to change the arity).

var c = funkierJS.constant(true);
var d = funkierJS.constant(false);
var f = funkierJS.andPred(c, d);
f("foo"); // => false

See some

Usage: var result = append(value, arr);

Takes a value, and an array, string or arrayLike, and returns a new array or string with the given value appended.

Throws a TypeError if the second argument is not an arrayLike.

Note: if the second argument is a string and the first is not, the value will be coerced to a string; you may not get the result you expect.

var a = [1, 2, 3];
funkierJS.append(4, a); // => [1, 2, 3, 4]
a; // => [1, 2, 3] (a is not changed)

Usage: var result = apply(args, f);

Applies the given function f with the arguments given in the array args. If the function is not curried, it will be curried (using curry) and partially applied if necessary. If the function is object curried, and has not yet acquired an execution context, then it will be invoked with a null execution context (as apply is itself curried, and so will have no visibility into the execution context it was invoked with). The result of applying the given arguments to the function is returned. Throws a TypeError if args is not an array, or if f is not a function.

funkierJS.apply([1], id); // 1

See arityOf

Usage: var result = arityOf(f);

Reports the real arity of a function. If the function has not been curried by funkier.js, this simply returns the function's length property. For a function that has been curried, the arity of the original function will be reported (the function's length property will always be 0 or 1 in this case). For a partially applied function, the amount of arguments not yet supplied will be returned.

funkierJS.arityOf(function(x) {}); // => 1;

Usage: var result = asArray(p);

Takes a pair, and returns a 2-element array containing the values contained in the given Pair p. Specifically, if the resulting array is named arr, then we have arr[0] === fst(p) and arr[1] === snd(p). Throws a TypeError if p is not a pair.

funkierJS.asArray(funkierJS.Pair(7, 10)); // => [7, 10]',

Usage: var result = bind(ctx, f);

Given an object and function, returns a curried function with the same arity as the original, and whose execution context is permanently bound to the supplied object. The function will be called when sufficient arguments have been supplied. Superfluous arguments are discarded. It is possible to partially apply the resulting function, and indeed the further resulting function(s). The resulting function and its partial applications will throw if they require at least one argument, but are invoked without any. bind throws if the first parameter is not an an acceptable type for an execution context, or if the last parameter is not a function.

The returned function will have a length of 1, unless an arity of 0 was requested, in which case this will be the length. The arityOf function can be used to determine how many arguments are required before the wrapped function will be invoked.

bind will accept functions that have been previously been curried to the same execution context, as that being provided, but will effectively be an identity function in such cases. However, attempting to curry a function known to be bound to a different execution context is an error. In particular, functions curried with curry or curryWithArity cannot be curried with an execution context: they have already been bound with an implicit null execution context. Equally, functions curried with objectCurry and objectCurryWithArity cannot be passed to bind, due to the different way in which they acquire an execution context. bind will throw in such cases.

Note also that many of the function manipulating functions, such as flip, compose etc. will curry the result in the same manner as the supplied functions, or otherwise will curry them using curry. As noted above, functions curried by curry cannot then be recurried by this function. Thus when performing such manipulations, one must curry them in the desired manner first, before manipulating them. This limitation may be removed in future versions of the library.

Unfortunately, funkierJS has no visibility into functions bound with the native bind method; attempting to curry such functions won't throw, but they will not work as expected.

var obj = {foo: 42};

var f = function(x, y) { return this.foo + x; };

var g = funkierJS.bind(obj, f);

g(3)(2); // returns 45

g(5, 2); // returns 47

var obj2 = {foo: 10};
var h = funkierJS.bindWithContextAndArity(3, obj2, f);
var j = funkierJS.bind(obj2, h); // OK, same context object

var err = funkierJS.bind({foo: 1}, g); // throws: execution contexts don't match

See bind

Usage: var result = bindWithContextAndArity(n, ctx, f);

Given an arity, object and function, returns a curried function whose execution context is permanently bound to the supplied object, and whose arity equals the arity given. The supplied arity need not equal the function's length. The function will be only called when the specified number of arguments have been supplied. Superfluous arguments are discarded. It is possible to partially apply the resulting function, and indeed the further resulting function(s). The resulting function and its partial applications will throw if they require at least one argument, but are invoked without any. bindWithContextAndArity throws if the arity is not a natural number, if the second parameter is not an acceptable type for an execution context, or if the last parameter is not a function.

The returned function will have a length of 1, unless an arity of 0 was requested, in which case this will be the length. The arityOf function can be used to determine how many arguments are required before the wrapped function will be invoked.

As noted above, you are permitted to curry a function to a smaller arity than its length. Whether the resulting function behaves in a useful manner will of course depend on the function.

In some limited circumstances, it is possible to recurry previously curried functions, however generally it only makes sense to recurry a function that has not been partially applied: this will be equivalent to currying the original function. To be able to recurry a curried function to a different arity, the execution context given must be the exact object that was previously used to create the function being recurried. It is an error to try and recurry a curried function bound to one execution context to another. In particular, functions curried with curry or curryWithArity cannot be curried with an execution context: they have already been bound with an implicit null execution context. Likewise, functions that have been curried using either objectCurry or objectCurryWithArity cannot be curried using bindWithContextAndArity, due to the different mechanism they use to acquire an execution context. bindWithContextAndArity will throw in that such cases.

Note also that many of the function manipulating functions, such as flip, compose etc. will curry the result in the same manner as the supplied functions, or otherwise will curry them using curry. As noted above, functions curried by curry cannot then be recurried by this function. Thus when performing such manipulations, one must curry them in the desired manner first, before manipulating them. This limitation may be removed in future versions of the library.

Unfortunately, funkierJS has no visibility into functions bound with the native bind method; attempting to curry such functions won't throw, but they will not work as expected.

var obj = {foo: 42};

var f = function(x, y) { return this.foo + x; };

var g = funkierJS.bindWithContextAndArity(1, obj, f);

g(3); // returns 45

var h = funkierJS.bindWithContextAndArity(3, obj, g); // OK, same context object
h(2)(3, 4); // returns 44

var err = funkierJS.bindWithContextAndArity(2, {foo: 1}, g); // throws: execution contexts don't match

var ok = funkierJS.bindWithContextAndArity(2, {foo: 1}, f); // still ok to bind the original function though

Usage: var result = bitwiseAnd(x, y);

A wrapper around the bitwise and (&) operator.

funkierJS.bitwiseAnd(7, 21); // => 5;

Usage: var result = bitwiseNot(x);

A wrapper around the bitwise not (~) operator.

funkierJS.bitwiseNot(5); // => -6;

Usage: var result = bitwiseOr(x, y);

A wrapper around the bitwise or (&) operator.

funkierJS.bitwiseOr(7, 8); // => 15;

Usage: var result = bitwiseXor(x, y);

A wrapper around the bitwise xor (^) operator.

funkierJS.bitwiseAnd(7, 3); // => 4;

Usage: var result = callProp(prop);

A shorthand for callPropWithArity(prop, 0). Returns a new function that takes an object, and calls the specified property on the given object.

var myObj = { return42: function() { return 42; }};
var callReturn42 = funkierJS.callProp('return42');
var callReturn42(myObj); // => 42

Usage: var result = callPropWithArity(prop, arity);

Given a property name and an arity, returns a curried function taking arity + 1 arguments. The new function requires all the original arguments in their original order, and an object as its final parameter. The returned function will then try to call the named property on the given object,

Note that the function is curried in the standard sense. In particular the function is not object curried.

var myMap = funkierJS.callPropWithArity('map', 1);
myMap(f, arr); // => returns arr.map(f);

var myFoldr = funkierJS.callPropWithArity('reduceRight', 2);
myFoldr(f, initialValue, arr); // => arr.reduceRight(f, initialValue);

Usage: var result = chr(n);

Equivalent to String.fromCharCode. Takes a number n, and returns the character whose Unicode value is that number.

funkierJS.chr(69); // => 'E'

Usage: var result = clone(obj);

Returns a shallow clone of the given object. All enumerable and non-enumerable properties from the given object and its prototype chain will be copied, and will be enumerable or non-enumerable as appropriate. Note that values from Object.prototype, Array.prototype, will not be copied, but those prototypes will be in the prototype chain of the clone if they are in the prototype chain of the original object. Functions are returned unchanged. Non-primitive values are copied by reference.

Exercise caution when cloning properties that have get/set functions defined in the descriptor: the cloned object will have these same functions using the same scope. Getting/setting such a property in the clone may affect the corresponding property in the original.

Usage: var result = compose(f, g);

Composes the two functions, returning a new function that consumes one argument, which is passed to g. The result of that call is then passed to f. That result is then returned. Throws if either parameter is not a function, or has arity 0.

The functions will be curried (using the standard curry if required. The resulting function will have real arity of arityOf(f). Note in particular, that if g has arity 1, it will be partially applied with 1 argument: f will recieve a partially applied g, and any remaining arguments.

If g was curried by one of the objectCurry variants, then the returned function will be too, and it will supply g with the context the first time it is invoked. If g was curried by bind, then the returned function will also be considered as having been curried that way, with the correct bound context.

var f1 = function(a) {return a + 1;};
var f2 = function(b) {return b * 2;};
var f = funkierJS.compose(f1, f2); // => f(x) = 2(x + 1)',

Usage: var result = composeMany(fns);

Repeatedly composes the given array of functions, from right to left. All functions are curried where necessary. Functions are curried from right to left. Throws an Error if any array member is not a function, if it has arity zero, or if the value supplied is not an array.

The result of calling composeMany([f1, f2, f3](x) is equal to f1(f2(f3(x))).

var square = function(x) {return x * x;};
var double = function(x) {return 2 * x;};
var plusOne = funkierJS.plus(1);
var f = funkierJS.composeMany([square, double, plusOne]);
f(2); // => 36

Usage: var result = composeOn(argCount, f, g);

Composes the two functions, returning a new function that consumes the specified number of arguments, which are then passed to g. The result of that call is then passed to f. That result is then returned. Throws if the first parameter is not an integer greater than zero, if either parameter is not a function, or if either parameter has arity 0.

The functions will be curried (using the standard curry if required. The resulting function will have real arity of arityOf(f). Note in particular, that if g has arity 1, it will be partially applied with 1 argument: f will recieve a partially applied g, and any remaining arguments.

If g was curried by one of the objectCurry variants, then the returned function will be too, and it will supply g with the context the first time it is invoked. If g was curried by bind, then the returned function will also be considered as having been curried that way, with the correct bound context.

This function is intended to afford an approximation of writing functions in a point-free style.

var f1 = function(a) {return a(2);};
var f2 = function(c, d, e) {return c * d * e;};
var f = funkierJS.composeOn(f1, f2); // => f(x, y) = 2(x * y);

Usage: var result = concat(arr1, arr2);

Takes two arrays, arrayLikes or strings, and returns their concatenation.

Throws a TypeError if either argument is not an arrayLike.

If both arguments are the same type and are either arrays or strings, then the result will be the same type, otherwise it will be an array.

funkierJS.concat([1, 2], [3, 4, 5]); // => [1, 2, 3, 4, 5]
funkierJS.concat('abc', 'def'); // => 'abcdef'
funkierJS.concat('abc', [1, 2, 3]); // => ['a', 'b', 'c', 1, 2, 3]

Usage: var result = constant(a, b);

Intended to be partially applied, first taking a value, returning a function that takes another parameter and which always returns the first value.

var f = funkierJS.constant(42);
f(10); // => 42

Usage: var result = constant0(a);

Returns a function of arity zero that when called always returns the supplied value.

var f = funkierJS.constant0(42);
f(); // => 42

Usage: var result = copy(arr);

Takes an arrayLike, and returns a new array which is a shallow copy.

Throws a TypeError if the given value is not an arrayLike.

var a = [1, 2, 3];]
var b = funkierJS.copy(a); // => [1, 2, 3]
b === a; // => false

Usage: var result = createObject(protoObject);

Returns a new object whose internal prototype property is the given object protoObject.

Note: this is an unary function that discards excess arguments. If you need to simultaneously add new properties to the created object, use createObjectWithProps.

var obj = {};
var newObj = funkierJS.createObject(obj);
funkierJS.isPrototypeOf(obj, newObj); // => true

Usage: var result = createObjectWithProps(protoObject, descriptorsObject);

Creates an object whose internal prototype property is protoObj, and which has the additional properties described in the given property descriptor object descriptorsObject. The property descriptor object is expected to be of the form accepted by Object.create, Object.defineProperties etc.

var obj = {};
var newObj = funkierJS.createObjectWithProps(obj, {prop: {configurable: false, enumerable: false,
                                                          writeable: true, value: 1}});
funkierJS.isPrototypeOf(obj, newObj); // => true
funkierJS.hasOwnProperty('prop', newObj); // => true',

Usage: var result = createProp(prop, val, obj);

Creates the given property to the given value on the given object, returning the object. Equivalent to evaluating o[prop] = value. The property will be not be modified if it already exists; in that case this method will throw. Additionally, it throws when the object is frozen, sealed, or cannot be extended. The property will be successfully created when it already exists, but only in the prototype chain.

Alternatively, one can use safeCreateProp for a version that will not throw in the above circumstances. Similarly, modify and safeModify can be used to modify existing properties without creating them, and set and safeSet can be used to either modify or create the property as required.

var a = {foo: 1};
funkierJS.create('bar', 42, a); // => returns a
a.bar // => 42

Usage: var result = curry(f);

Curries the given function f, returning a function which accepts the same number of arguments as the original function's length property, but which may be partially applied. The function can be partially applied by passing arguments one at a time, or by passing several arguments at once. The function can also be called with more arguments than the given function's length, but the superfluous arguments will be ignored, and will not be passed to the original function. If the curried function or any subsequent partial applications require at least one argument, then calling the function with no arguments will throw. curry throws if its argument is not a function. It will also throw if the function is known to be bound to a specific execution context.

Currying a function that has already been curried will return the exact same function, unless the function was curried with a different mechanism - see below.

The returned function will have a length of 1, unless the original function will have length 0, in which case the result also has length 0. Note that when currying functions of length 0 and 1 that the results will be different functions from those passed in.

If you need a function which accepts an argument count that differs from the function's length property, use curryWithArity.

Note that you cannot pass in functions that have been bound to a specific execution context using bind, or bindWithContextAndArity: allowing those would break the invariant that functions curried with curry are invoked with a null execution context. Similarly, functions curried with objectCurry and objectCurryWithArity cannot be recurried through curryWithArity. Thus an error is thrown in such cases. (However, funkierJS cannot tell if a function has been bound with the native bind method. Currying such functions might lead to unexpected results).

var f = function(x, y, z) { console.log(x, y, z); }

var g = funkierJS.curry(f);

g(4);  // => a function awaiting two arguments

g(4)(2); // => a function awaiting one argument

g(4)(2)('z'); // => 4, 2, 'z' logged

g('a', 'b')('c'); // => 'a', 'b' 'c' logged

g('x')('y', 'z'); // => 'x', 'y' 'z' logged

g('d', 'e', 'f'); // => 'd', 'e' 'f' logged

funkierJS.curry(g) === g;  // => true

Usage: var result = curryOwn(obj);

Takes an object, and providing every enumerable function is writable, (i.e. the function has not been configured as writable: false), then curries the member functions of the object using the objectCurry method. If any member functions are found that do not meet this requirement, then the object is left unchanged. Only the object's own properties are affected; those in the prototype chain are unperturbed. Properties with getter/setters in their descriptor are ignored.

The all-or-nothing approach was taken to avoid the difficulty in reasoning that would ensue on partial success: the client would be left having to manually enumerate the functions to see which ones did get curried. The avoidance of functions returned from properties with getter/setter descriptors is to avoid any lexical scoping ambiguities.

var obj = {foo: function(x, y) { return this.bar + x + y; }, bar: 10};
funkierJS.curryOwn(obj);
obj.foo(2)(3); // => 15

Usage: var result = curryWithArity(n, f);

Curries the given function f to the supplied arity, which need not equal the function's length. The function will be called when that number of arguments have been supplied. Superfluous arguments are discarded. The original function will be called with a null execution context. It is possible to partially apply the resulting function, and indeed the further resulting function(s). The resulting function and its partial applications will throw if they require at least one argument, but are invoked without any. curryWithArity throws if the arity is not a natural number, or if the second parameter is not a function. It will also throw if the given function is known to be bound to a specific execution context.

The returned function will have a length of 1, unless an arity of 0 was requested, in which case this will be the length. The arityOf function can be used to determine how many arguments are required before the wrapped function will be invoked.

As noted above, you are permitted to curry a function to a smaller arity than its length. Whether the resulting function behaves in a useful manner will of course depend on the function. One use case of curryWithArity is to create unique functions from functions that accept optional arguments. For example, one common error involves mapping over an array with parseInt, which has an optional radix parameter. Array.prototype.map invokes the mapping function with additional metadata such as the position of the current element; when these factors collide, one ends up trying to convert to numbers whose radix equals the array index. Instead, one could use curryWithArity with an arity of 1 to create a new function that guarantees parseInt will be called with only one argument. (Note: funkierJS provides a parseInt function for this purpose).

It is possible to recurry functions that have been previously curried with curry or curryWithArity, however generally it only makes sense to recurry a function that has not been partially applied: this will be equivalent to currying the original function. Recurrying a partially applied function will likely not work as you expect: the new function will be one that requires the given number of arguments before calling the original function with the partially applied arguments and some of the ones supplied to the recurried function.

You cannot however pass in functions that have been bound to a specific execution context using bind, or bindWithContextAndArity: curryWithArity promises to invoke functions with a null execution context, but those functions have a fixed execution context that cannot be overridden. For similar reasons, functions curried with objectCurry or objectCurryWithArity cannot be curried. An error is thrown if the function has been bound to an execution context in this way.

Note however that funkierJS has no visibility into the execution contexts of functions bound using the native function bind method. Attempting to curry these might lead to surprising results, and should be avoided.

var f = function(x, y) { console.log(x, y); }

var g = funkierJS.curryWithArity(1, f);

g(7);  // => 1, undefined logged

var h = funkierJS.curryWithArity(3, f);

var j = h(2, 'a');

j(9);  // => 2, 'a' logged

h('fizz')('buzz', 'foo') // => 'fizz', 'buzz' logged

Usage: var result = deepEqual(a, b);

Check two values for deep equality. Deep equality holds if any of the following if the two values are the same object, if both values are objects with the same object, the same prototype, the same enumerable properties and those properties are themselves deeply equal (non-enumerable properties are not checked), or if both values are arrays with the same length, any additional properties installed on the arrays are deeply equal, and the items at each index are themselves deeply equal.

funkierJS.deepEqual({foo: 1, bar: [2, 3]}, {bar: [2, 3], foo: 1}); // => true

See deepEqual

See extractOrDefault

Usage: var result = defineProperties(descriptors, o);

A curried wrapper around Object.defineProperties. Takes an object whose own properties map to property descriptors, and an object o. Returns the object o, after having defined the relevant properties named by the properties of the descriptors parameter, and whose values are dictated by the descriptor parameter.

var a = {};',
funkierJS.hasOwnProperty('foo', a); // => false
funkierJS.defineProperties({foo: {value: 42}}, a);
funkierJS.hasOwnProperty('foo', a); // => true

Usage: var result = defineProperty(prop, descriptor, o);

A curried wrapper around Object.defineProperty. Takes a property name string, a property descriptor object and the object that the property hould be defined on. Returns the object o, after having defined the relevant property per the descriptor. Throws a TypeError if the descriptor is not an object.

var a = {};',
funkierJS.hasOwnProperty('foo', a); // => false
funkierJS.defineProperty('foo', {value: 42}, a);
funkierJS.hasOwnProperty('foo', a); // => true

Usage: var result = deleteProp(prop, obj);

Deletes the given property from the given the given object, returning the object. Equivalent to evaluating delete o[prop]. Throws when the property is not configurable, including when the object is frozen or sealed.

Alternatively, one can use safeDeleteProp that will return the appropriate Maybe value depending on the outcome of the operation.

var a = {foo: 1};
funkierJS.delete('foo',  a); // => returns a
a.foo // => undefined

Usage: var result = descriptors(obj);

Takes an object, and returns an array containing 2-element arrays. The first element of each sub-array is the name of a property from the object, and the second element is its property descriptor. This function only returns key-value pairs for the object's own properties. Returns an empty array for non-objects. The order of the values is not defined.

funkierJS.descriptors({foo: 1}); // => returns [['foo', {configurable: true, writable: true, enumerable: true,
                                                         value: 1}]

Usage: var result = div(x, y);

Returns the quotient on dividing x by y.

funkierJS.div(5, 2); // => 2

Usage: var result = divide(x, y);

A wrapper around the division operator.

funkierJS.divide(4, 2); // => 2;

Usage: var result = drop(count, arr);

Takes a count, and an array, string or arrayLike. Returns an array or string containing the first count elements removed from the given arrayLike.

Throws a TypeError if the count is not integral, or if the last argument is not an array or string.

funkierJS.drop(3, 'banana'); // => 'anana'

Usage: var result = dropWhile(pred, arr);

Takes a predicate function p, and source, an array, string or arrayLike. Returns a new array or string containing the remaining members our source upon removing the initial elements for which the predicate function returned true.

Throws a TypeError if p is not a function of arity 1, or if the given value is not an arrayLike.

Note that, if required, the function must already have its execution context set. Internally, the execution context within dropWhile is null, so it cannot supply a useful execution context to any object-curried functions supplied to this function.

funkierJS.dropWhile(even, [2, 4, 3, 5, 7]; // => [3, 5, 7

Usage: each(f, arr);

Takes a function f, and an array, string or arrayLike arr. Calls f with each member of the array in sequence, and returns undefined.

Throws a TypeError if the first argument is not a function, or if the second is not an arrayLike.

Note that, if required, the function must already have its execution context set. Internally, the execution context within each is null, so it cannot supply a useful execution context to any object-curried functions supplied to this function.

funkierJS.each(function(e) {console.log(e);}, [1, 2]); // => Logs 1 then 2 to the console

Usage: var result = either(f1, f2, r);

Takes two functions of arity 1 or greater, and a Result. If the Result is an Ok value, the first function f1 will be called with the unwrapped value. Otherwise, if the Result is an Err value, the second function is called with the unwrapped value. In either case, the result of of the called function is returned.

Throws a TypeError if either of the first two arguments is not a function of arity 1 or more, or if the given value is not a Result.

Note that, if required, the functions must already have their execution context set. Internally, the execution context within either is null, so it cannot supply a useful execution context to any object-curried functions supplied to this function.

var f = funkierJS.either(function(x) {console.log('Good: ' + x);}, function(x) {console.log('Bad: ' + x);});
f(funkierJS.Ok(2)); // => logs 'Good: 2' to the console
f(funkierJS.Err(':(')); // logs 'Bad: :(' to the console

Usage: var result = element(val, arr);

Takes a value and an array, string or arrayLike. Returns true if the value is in the arrayLike (checked for strict identity) and false otherwise.

Throws a TypeError if the second argument is not an arrayLike.

funkierJS.element('a', 'cable'); // => true

Usage: var result = elementWith(pred, arr);

A generalised version of element. Takes a predicate function p of one argument, and an array, string or arrayLike. Returns true if there is an element in the arrayLike for which p returns true, and returns false otherwise.

Throws a TypeError if the first argument is not a function of arity 1, or the second argument is not an arrayLike.

Note that, if required, the function must already have its execution context set. Internally, the execution context within element is null, so it cannot supply a useful execution context to any object-curried functions supplied to this function.

var p = function(e) {return e.foo = 42;};
funkierJS.elementWith(p, [{foo: 1}, {foo: 42}]); // => true

Usage: var result = equals(a, b);

A wrapper around the non-strict equality (==) operator.

funkierJS.equals(1, '1'); // => true

Usage: var result = even(x);

Given a number, returns true if it is divisible by 2, and false otherwise.

funkierJS.even(2); // => true
funkierJS.even(3); // => false

Usage: var result = every(pred, arr);

Takes two parameters: a predicate function p that takes one argument, and an array, string or arrayLike. Calls the predicate with every element of the array or string, until either the predicate function returns false, or the end of the array or string is reached.

Returns the last value returned by the predicate function.

Throws a TypeError if p is not a function of arity 1, or if the second argument is not an arrayLike.

Note that, if required, the function must already have its execution context set. Internally, the execution context within every is null, so it cannot supply a useful execution context to any object-curried functions supplied to this function.

funkierJS.every(even, [2, 4, 6]); // => true

Usage: var result = exp(x, y);

A curried wrapper around Math.pow.

funkierJS.exp(2, 3); // => 8

Usage: var result = extend(source, dest);

Takes two objects, source and dest, and walks the prototype chain of source, copying all enumerable properties into dest. Any extant properties with the same name are overwritten. Returns the modified dest object. All properties are shallow-copied: in other words, if foo is a property of source whose value is an object, then afterwards source.foo === dest.foo will be true.

var a = {bar: 1};
funkierJS.extend(a, {foo: 42}); // => a === {foo: 42, bar: 1}

Usage: var result = extendOwn(source, dest);

Takes two objects, source and dest, and copies all enumerable properties from source into dest. Properties from source's prototype chain are not copied. Any extant properties with the same name are overwritten. Returns the modified dest object. All properties are shallow-copied: in other words, if foo is a property of source whose value is an object, then afterwards source.foo === dest.foo will be true.

var a = funkierJS.createObject({bar: 1});
a.baz = 2;
var b = {foo: 3};
funkierJS.extendOwn(b, a); // b == {foo: 3, baz: 2}

Usage: var result = extract(prop, obj);

Extracts the given property from the given object. Equivalent to evaluating obj[prop].

funkierJS.extract('foo', {foo: 42}); // => 42

Usage: var result = extractOrDefault(prop, default, obj);

Extracts the given property from the given object, unless the property is not found in the object or its prototype chain, in which case the specified default value is returned.

funkierJS.extractOrDefaultt('foo', 43, {bar: 42}); // => 43

See fmap

Usage: var result = filter(pred, arr);

Takes a predicate function pred, and an array, string or arrayLike arr. Returns an array or string containing those members of arr—in the same order as the original array—for which the predicate function returned true.

Throws a TypeError if pred does not have arity 1, or if arr is not an arrayLike.

Note that, if required, the function must already have its execution context set. Internally, the execution context within filter is null, so it cannot supply a useful execution context to any object-curried functions supplied to this function.

funkierJS.filter(even, [2, 3, 4, 5, 6]); // => [2, 4, 6]

See fst

Usage: var result = firstMatch(r, s);

Finds the first match in a string for a given regular expression. Takes two parameters: a regular expression and a string. Returns a single object or null.

If not null, the object has the following properties:

• index: the index in the original string where the match was found
• matchedText: the substring that matched the pattern
• subexpressions: an array of substrings that matched the parenthesed expressions in the regular expressions. substring matching the first parenthesised expression will be at position 0, the string matching the second at position 1, and so on. If the regular expression did not contain any parenthesised subexpressions, this array will be empty.

This function is not affected by the presence or absence of a global flag in the supplied regular expression. It is not affected by and does not change the lastIndex property of the regular expression if it exists.

Throws a TypeError if the first parameter is not a regular expression.

funkierJS.firstMatch(/a/, 'banana'); // => {index: 3, matchedText: 'a', []}

Usage: var result = firstMatchFrom(r, index, s);

Finds the first match in a string for a given regular expression from a given index. Takes three parameters: a regular expression an index, and a string. Returns a single object or null.

If not null, the object has the following properties:

• index: the index in the original string where the match was found
• matchedText: the substring that matched the pattern
• subexpressions: an array of substrings that matched the parenthesed expressions in the regular expressions. The substring matching the first parenthesised expression will be at position 0, the string the second at position 1, and so on. If the regular expression did not contain any subexpressions, this array will be empty.

This function is not affected by the presence or absence of a global flag in the supplied regular expression. It is not affected by and does not change the lastIndex property of the regular expression if it exists.

Throws a TypeError if the first parameter is not a regular expression.

funkierJS.firstMatchFrom(/a/, 4, 'banana'); // => {index: 5, matchedText: 'a', []}

Usage: var result = flatten(arr);

Takes an array containing arrays or strings. Returns an array containing the concatenation of those arrays/strings. Note that flatten only strips off one layer.

Throws a TypeError if the supplied value is not arrayLike, or if any of the values within it are not arrayLike.

funkierJS.flatten([[1, 2], [3, 4]]); // => [1, 2, 3, 4]

Usage: var result = flattenMap(f, arr);

Takes a function of arity 1, and an array, string or arrayLike. Maps the function over the array/string and flattens the result. The supplied function must be of arity 1, as it is expected to return an array or string; a TypeError is thrown if this is not the case.

A TypeError will also be thrown if the last argument is not arrayLike, or if the first argument is not a function.

Note that, if required, the function must already have its execution context set. Internally, the execution context within flattenWith is null, so it cannot supply a useful execution context to any object-curried functions supplied to this function.

var fn = function(n) {return [n, n * n];};
funkierJS.flattenMap(fn, [1, 2, 3]); // => Returns [1, 1, 2, 4, 3, 9]

Usage: var result = flip(f);

Takes a binary function f, and returns a curried function that takes the arguments in the opposite order.

Note that the returned function will be curried in the extant style, or using curry if the function is not curried. Thus, if you wish to flip a object-curried function on the object prototype, you must object-curry before flipping; in the other order, the function will be curried in the standard manner, preventing later object currying.

var backwards = funkierJS.flip(funkierJS.subtract);
backwards(2, 3); // => 1

Usage: var result = fmap(f, g);

Takes a known Functor, and maps the given function over it. Known functors are currently arrays, strings, Maybes and Results, although this may change in future versions. Throws if the first value is not a function of arity 1, or the second is not a known functor.

The actions taken are as follows:

• arrays/strings: the function is mapped over the array
• Maybe: Just values yield a new Just value containing the result of applying the function to the contents of the Just. Nothing values yield Nothing.
• Result: Ok values yiels a new Ok value containing the result of applying the function to the contents of the Ok. Err values yield the Err value unchanged.

funkierJS.fmap(function(x) { return x + 1; }, Just(10)); => Just 11

Usage: var result = foldl(f, initial, arr);

Takes three parameters: a function f of two arguments, an initial value, and an array, string or arrayLike. Traverses the array or string from left to right, calling the function with two arguments: the current accumulation value, and the current element. The value returned will form the next accumulation value, and foldl returns the value returned by the final call. The first call's accumulation parameter will be the given initial value.

Throws a TypeError if the first parameter is not a function of arity 2, or if the last parameter is not an array or string.

Note that, if required, the function must already have its execution context set. Internally, the execution context within foldl is null, so it cannot supply a useful execution context to any object-curried functions supplied to this function.

funkierJS.foldl(function(soFar, current) {return soFar*10 + (current - 0);}, 0, '123'); // 123

Usage: var result = foldl1(f, arr);

Takes two parameters: a function f of two arguments, and an array, string or arrayLike value. Traverses the array from left to right from the second element, calling the function with two arguments: the current accumulation value, and the current element. The value returned will form the next accumulation value, and foldl1 returns returns the value returned by the final call. The first call's accumulation parameter will be the first element of the array or string.

Throws a TypeError if the first parameter is not a function of arity 2, if the last parameter is not an arrayLike, or if the arrayLike is empty.

Note that, if required, the function must already have its execution context set. Internally, the execution context within foldl1 is null, so it cannot supply a useful execution context to any object-curried functions supplied to this function.

funkierJS.foldl1(multiply, [2, 3, 4]); // => 24

Usage: var result = foldr(f, initial, arr);

Takes three parameters: a function f of two arguments, an initial value, and an array, string or arrayLike value. Traverses the array or string from right to left, calling the function with two arguments: the current accumulation value, and the current element. The value returned will form the next accumulation value, and foldr returns the value returned by the final call. The first call's accumulation parameter willbe the given initial value.

Throws a TypeError if the first parameter is not a function of arity 2, or if the last parameter is not an arrayLike.

Note that, if required, the function must already have its execution context set. Internally, the execution context within foldr is null, so it cannot supply a useful execution context to any object-curried functions supplied to this function.

funkierJS.foldr(subtract, 0, [2, 3, 4]); // => -9

Usage: var result = foldr1(f, arr);

Takes two parameters: a function f of two arguments, and an array, string or arrayLike. Traverses the array from right to left from the penultimate element, calling the function with two arguments: the current accumulation value, and the current element. The value returned will form the next accumulation value, and foldr1 returns returns the value returned by the final call. The first call's accumulation parameter will be the last element of the array or string.

Throws a TypeError if the first parameter is not a function of arity 2, if the last parameter is not an array or string, or if the array or string is empty.

Note that, if required, the function must already have its execution context set. Internally, the execution context within foldr1 is null, so it cannot supply a useful execution context to any object-curried functions supplied to this function.

funkierJS.foldr1(function(soFar, current) {return current + soFar;}, "banana"); // => ananab

Usage: var result = fst(p);

Accessor function for Pair tuples. Returns the first value that was supplied to the Pair constructor. Throws if called with a non-pair value.

var p = new funkierJS.Pair(2, 3);
funkierJS.fst(p); // => 2',

Usage: var result = getCurrentTimeString();

A wrapper around calling the Date constructor without the new operator. Returns a string representing the current date and time.

Usage: var result = getDayOfMonth(d);

A wrapper around Date.prototype.getDate. Takes a Date object, and returns an integer representing the day of the month (1-31) of the given date.

var a = new Date(2000, 1, 15, 10, 11, 12, 13);
funkierJS.getDayOfMonth(a); // => 15

Usage: var result = getDayOfWeek(d);

A wrapper around Date.prototype.getDay. Takes a Date object, and returns an integer representing the day of the month (0-6) of the given date.

var a = new Date(2000, 1, 15, 10, 11, 12, 13);
funkierJS.getDayOfWeek(a); // => 2

Usage: var result = getErrValue(e);

Returns the value wrapped by the given Err instance e. Throws a TypeError if called with anything other than an Err.

funkierJS.getErrValue(funkierJS.Err(4)); // => 4',

Usage: var result = getFullYear(d);

A wrapper around Date.prototype.getFullYear. Takes a Date object, and returns a 4-digit integer representing the year of the given date.

var a = new Date(2000, 1, 15, 10, 11, 12, 13);
funkierJS.getFullYear(a); // => 2000

Usage: var result = getHours(d);

A wrapper around Date.prototype.getHours. Takes a Date object, and returns a integer representing the hour field (0-23) of the given date.

var a = new Date(2000, 1, 15, 10, 11, 12, 13);
funkierJS.getHours(a); // => 10

Usage: var result = getIndex(index, arr);

Takes an index and an array, string or other arrayLike value and returns the element at the given index. Throws a TypeError if the index is outside the range for the given object.

funkierJS.getIndex(1, "abcd"); 1

Usage: var result = getJustValue(j);

Returns the value wrapped by the given Just instance j. Throws a TypeError if called with anything other than a Just.

funkierJS.getJustValue(funkierJS.Just(3)); // => 3',

Usage: var result = getMilliseconds(d);

A wrapper around Date.prototype.getMilliseconds. Takes a Date object, and returns a integer representing the milliseconds field (0-999) of the given date.

var a = new Date(2000, 1, 15, 10, 11, 12, 13);
funkierJS.getMilliseconds(a); // => 13

Usage: var result = getMinutes(d);

A wrapper around Date.prototype.getMinutes. Takes a Date object, and returns a integer representing the minutes field (0-59) of the given date.

var a = new Date(2000, 1, 15, 10, 11, 12, 13);
funkierJS.getMinutes(a); // => 11

Usage: var result = getMonth(d);

A wrapper around Date.prototype.getMonths. Takes a Date object, and returns a integer representing the month field (0-11) of the given date.

var a = new Date(2000, 1, 15, 10, 11, 12, 13);
funkierJS.getMonth(a); // => 1

Usage: var result = getOkValue(o);

Returns the value wrapped by the given Ok instance o. Throws a TypeError if called with anything other than an Ok.

funkierJS.getOkValue(funkierJS.Ok(3)); // => 3',

Usage: var result = getOwnPropertyDescriptor(prop, o);

A curried wrapper around Object.getOwnPropertyDescriptor. Takes a property name and an object. If the object itself has the given property, then the object's property descriptor for the given object is returned, otherwise it returns undefined.

var a = {foo: 42};',
funkierJS.getOwnPropertyDescriptor('foo', a); // => {configurable: true, enumerable: true, writable: true,
                                                     value: 42}
funkierJS.getOwnPropertyDescriptor('toString', a); // => undefined',

Usage: var result = getOwnPropertyNames(obj);

A wrapper around Object.getOwnPropertyNames. Takes an object, and returns an array containing the names of the object's own properties, including non-enumerable properties. Returns an empty array for non-objects. The order of the property names is not defined.

funkierJS.getOwnPropertyNames({foo: 1, bar: 2}); // => returns ['foo', 'bar'] or ['bar', 'foo'] depending on
                                                 // native environment

Usage: var result = getSeconds(d);

A wrapper around Date.prototype.getSeconds. Takes a Date object, and returns a integer representing the seconds field (0-59) of the given date.

var a = new Date(2000, 1, 15, 10, 11, 12, 13);
funkierJS.getSeconds(a); // => 12

Usage: var result = getTimezoneOffset(d);

A wrapper around Date.prototype.getTimezoneOffset. Takes a Date object, and returns the delta in minutes between the Javascript environment and UTC.

Usage: var result = getType(a);

A functional wrapper around the typeof operator. Takes any Javascript value, and returns a string representing the object's type: the result will be one of "number", "string", "boolean", "function", "undefined", or "object".

funkierJS.getType({}); // => "object"

Usage: var result = getUTCDayOfMonth(d);

A wrapper around Date.prototype.getUTCDate. Takes a Date object, and returns an integer representing the day of the month (1-31) of the given date, adjusted for UTC.

Usage: var result = getUTCDayOfWeek(d);

A wrapper around Date.prototype.getUTCDay. Takes a Date object, and returns an integer representing the day of the week (0-6) of the given date, adjusted for UTC.

Usage: var result = getUTCFullYear(d);

A wrapper around Date.prototype.getUTCFullYear. Takes a Date object, and returns a 4-digit integer representing the year of the given date, adjusted for UTC.

Usage: var result = getUTCHours(d);

A wrapper around Date.prototype.getUTCHours. Takes a Date object, and returns an integer representing the hours field of the given date (0-23), adjusted for UTC.

Usage: var result = getUTCMilliseconds(d);

A wrapper around Date.prototype.getUTCMilliseconds. Takes a Date object, and returns an integer representing the milliseconds field of the given date (0-999), adjusted for UTC.

Usage: var result = getUTCMinutes(d);

A wrapper around Date.prototype.getUTCMinutes. Takes a Date object, and returns an integer representing the minutes field of the given date (0-59), adjusted for UTC.

Usage: var result = getUTCMonth(d);

A wrapper around Date.prototype.getUTCMonth. Takes a Date object, and returns an integer representing the month field of the given date (0-11), adjusted for UTC.

Usage: var result = getUTCSeconds(d);

A wrapper around Date.prototype.getUTCSeconds. Takes a Date object, and returns an integer representing the seconds field of the given date (0-59), adjusted for UTC.

Usage: var result = greaterThan(x, y);

A wrapper around the less than or equal (<=) operator.

funkierJS.greaterThan(5, 2); // => true;

Usage: var result = greaterThanEqual(x, y);

A wrapper around the greater than or equal (=>) operator.

funkierJS.greaterThanEqual(2, 2); // => true;

See greaterThan

See greaterThanEqual

Usage: var result = hasOwnProperty(prop, obj);

A curried wrapper around Object.prototype.hasOwnProperty. Takes a string representing a property name and an object, and returns true if the given object itself (i.e. not objects in the prototype chain) has the specified property.

funkierJS.hasOwnProperty('funkier', {funkier: 1}); // => true
funkierJS.hasOwnProperty('toString', {funkier: 1}); // => false

Usage: var result = hasProperty(prop, obj);

A curried wrapper around the in operator. Takes a string representing a property name and an object, and returns true if the given object or some object in the prototype chain has the specified property.

funkierJS.hasProperty('funkier', {funkier: 1}); // => true
funkierJS.hasProperty('toString', {funkier: 1}); // => true

See is

Usage: var result = head(arr);

Takes an array, string or other arrayLike value and returns the first element. Throws a TypeError when given an empty arrayLike.

funkierJS.head([1, 2, 3]); // => 1

Usage: var result = id(a);

Returns the supplied value. Superfluous values are ignored.

funkierJS.id([1, 2]); // => [1, 2]

Usage: var result = init(arr);

Takes an array, string or arrayLike. Returns an array or string containing every element except the last.

Throws a TypeError if the arrayLike is empty, or if the given value is not an arrayLike.

funkierJS.init([2, 3, 4, 5]); // => [2, 3, 4]

Usage: var result = inits(arr);

Takes an array, string or arrayLike. Returns all the prefixes of the given arrayLike.

Throws a TypeError if the given value is not an arrayLike.

funkierJS.inits([2, 3]); // => [[], [2], [2, 3]]

Usage: var result = instanceOf(constructor, obj);

A curried wrapper around the instanceof operator. Takes a constructor function and an object, and returns true if the function's prototype property is in the prototype chain of the given object.

var Constructor = function() {};
funkierJS.instanceOf(Constructor, new Constructor()); // => true
funkierJS.instanceOf(Function, {}); // => false

Usage: var result = intersperse(val, arr);

Takes a value, and an array, string or arrayLike, and returns a new array or string with the value in between each pair of elements of the original.

Note: if the second parameter is a string, the first parameter will be coerced to a string.

Throws a TypeError if the second argument is not arrayLike.

funkierJS.intersperse(1, [2, 3, 4]); // => [2, 1, 3, 1, 4]

Usage: var result = is(type, value);

Given a string that could be returned by the typeof operator, and a value, returns true if typeof the given object equals the given string. Throws if the first argument is not a string.

funkierJS.is('number', 1); // => true

Usage: var result = isArray(a);

Returns true if the given value is an array, false otherwise

funkierJS.isArray([]); // => true

Usage: var result = isBoolean(a);

Returns true if typeof the given value equals "boolean", false otherwise.

funkierJS.isBoolean(false); // => true

Usage: var result = isEmpty(arr);

Returns true if the given array, arrayLike or string is empty, and false if not.

Throws a TypeError if the argument is not arrayLike.

funkierJS.isEmpty([]); // => true

Usage: var result = isErr(a);

Returns true when the given value is a Err object, and false otherwise.

funkierJS.isErr(funkierJS.Err(4)); // => true

Usage: var result = isJust(a);

Returns true if the given value is a Just object, and false otherwise.

funkierJS.isJust(funkierJS.Just(42)); // => true

Usage: var result = isMaybe(a);

Returns true when the given value is a Maybe object, and false otherwise.

funkierJS.isMaybe(funkierJS.Nothing) && funkierJS.isMaybe(funkierJS.Just(42)); // => true

Usage: var result = isNothing(a);

Returns true if the given value is the Nothing object, and false otherwise.

funkierJS.isNothing(funkierJS.Nothing); // => true

Usage: var result = isNull(a);

Returns true if the given object is null, false otherwise

funkierJS.isNull(null); // => true

Usage: var result = isNumber(a);

Returns true if typeof the given value equals "number", false otherwise.

funkierJS.isNumber(1); // => true

Usage: var result = isObject(a);

Returns true if typeof the given value equals "object", false otherwise.

funkierJS.isObject(null); // => true

Usage: var result = isOk(a);

Returns true when the given value is a Ok object, and false otherwise.

funkierJS.isOk(funkierJS.Ok('foo)); // => true

Usage: var result = isPair(a);

Returns true if the given value is a Pair, and false otherwise.

funkierJS.isPair(funkierJS.Pair(2, 3)); // => True

Usage: var result = isPrototypeOf(protoObject, obj);

A curried wrapper around Object.prototype.isPrototypeOf. Takes two objects: the prototype object, and the object whose prototype chain you wish to check. Returns true if protoObj is in the prototype chain of o.

var Constructor = function() {};
funkierJS.isPrototypeOf(Constructor.prototype, new Constructor()); // => true
funkierJS.isPrototypeOf(Function.prototype, {}); // => false

Usage: var result = isRealObject(a);

Returns true if the value is a real Javascript object, i.e. an object for which funkierJS.isObject(a) === true and funkierJS.isNull(a) === false and funkierJS.isArray(a) === false.

funkierJS.isRealObject(null); // => false

Usage: var result = isResult(a);

Returns true when the given value is a Result object, and false otherwise.

funkierJS.isResult(funkierJS.Ok(3)) && funkierJS.isResult(funkierJS.Err(false)); // => true

Usage: var result = isString(a);

Returns true if typeof the given value equals "string", false otherwise.

funkierJS.isString('a'); // => true

Usage: var result = isUndefined(a);

Returns true if typeof the given value equals "undefined", false otherwise.

funkierJS.isUndefined(1); // => false

Usage: var result = join(separator, arr);

Takes a separator value that can be coerced to a string, and an array. Returns a string, containing the toString of each element in the array, separated by the toString of the given separator.

Throws a TypeError if the last element is not an array.

funkierJS.join('-', [1, 2, 3]); // => '1-2-3'

Usage: var result = keyValues(obj);

Takes an object, and returns an array containing 2-element arrays. The first element of each sub-array is the name of a property from the object, and the second element is the value of the property. This function only returns key-value pairs for the object's own properties. Returns an empty array for non-objects. The order of the values is not defined.

funkierJS.keyValues({foo: 1, bar: 2}); // => returns [['foo', 1], ['bar', 2]] or [['bar', 2], ['foo', 1]]
                                       // depending on native environment

Usage: var result = keys(obj);

A wrapper around Object.keys. Takes an object, and returns an array containing the names of the object's own properties. Returns an empty array for non-objects.

funkierJS.keys({foo: 1, bar: 2}); // => returns ['foo', 'bar'] or ['bar', 'foo'] depending on native
                                  //    environment

Usage: var result = last(arr);

Takes an array, string or other arrayLike value, and returns the last element. Throws a TypeError when given an empty arrayLike.

funkierJS.last([1, 2, 3]); // => 3

Usage: var result = leftShift(x, y);

A wrapper around the left shift (<<) operator.

funkierJS.leftShift(1, 2); // => 4;

Usage: var result = length(arr);

Takes an array, string or other arrayLike value, and returns its length. Throws a TypeError if the given value is not an arrayLike.

funkierJS.length([1, 2, 3]); // => 3

Usage: var result = lessThan(x, y);

A wrapper around the less than (<) operator.

funkierJS.lessThan(5, 2); // => false;

Usage: var result = lessThanEqual(x, y);

A wrapper around the less than or equal (<=) operator.

funkierJS.lessThanEqual(2, 2); // => true;

Usage: var result = log(x, y);

Returns the logarithm of y in the given base x. Note that this function uses the change of base formula, so may be subject to rounding errors.

funkierJS.log(2, 8); // => 3;

See lessThan

See lessThanEqual

Usage: var result = makeDateFromMilliseconds(milliseconds);

A wrapper around calling the Date constructor with a single numeric argument. Throws a TypeError when called with a non-numeric argument. Returns a new Date object whose value represents the date which is that many elapsed milliseconds since the epoch.

var d = funkierJS.makeDateFromMilliseconds(1400161244101);

Usage: var result = makeDateFromString(dateString);

A wrapper around calling the Date constructor with a single string argument. Throws a TypeError when called with a non-string argument, or a string that cannot be parsed as a date. Returns a new Date object whose value represents that given in the string.

var d = funkierJS.makeDateFromString('2000-01-01T10:00:01:000Z');

Usage: var result = makeDayDate(year, month, day);

A curried wrapper around calling the Date constructor with three arguments: the year, the month and the day. No validation or type-checking occurs on the parameters. Excess arguments are ignored. All other fields in the Date are initialized to zero. Returns the new Date.

var d = funkierJS.makeDayDate(2000, 0, 2); // => A date representing January 2 2000

Usage: var result = makeHourDate(year, month, day, hour);

A curried wrapper around calling the Date constructor with four arguments: the year, the month, the day and the hour. No validation or type-checking occurs on the parameters. Excess arguments are ignored. All other fields in the Date are initialized to zero. Returns the new Date.

var d = funkierJS.makeHourDate(2000, 0, 2, 10); // => A date representing 10am, January 2 2000

Usage: var result = makeMaybeReturner(f);

Takes a function f. Returns a new function with the same arity as f. When called, the new function calls the original. If the function f throws during execution, then the Nothing object is returned. Otherwise the result of the function is wrapped in a Just and returned.

The function will be curried in the same style as the original, or using curry if the function was not curried.

var g = function(x) {
  if (x < 10)
    throw new Error('Bad value');
  return x;
};

var f = funkierJS.makeMaybeReturner(g);
f(11); // => Just(11)
f(5); // => Nothing

Usage: var result = makeMillisecondDate(year, month, day, hour, minute, second, millisecond);

A curried wrapper around calling the Date constructor with seven arguments: the year, the month, the day, the hour, the minute, the seconds, and the milliseconds. No validation or type-checking occurs on the parameters. Returns the new Date.

var d = funkierJS.makeMillisecondDate(2000, 0, 2, 10, 15, 30, 12); // => A date representing 10:15:30:012,
                                                                   //    January 2 2000

Usage: var result = makeMinuteDate(year, month, day, hour, minute);

A curried wrapper around calling the Date constructor with five arguments: the year, the month, the day, the hour and the minute. No validation or type-checking occurs on the parameters. Excess arguments are ignored. All other fields in the Date are initialized to zero. Returns the new Date.

var d = funkierJS.makeMinuteDate(2000, 0, 2, 10, 15); // => A date representing 10:15:00, January 2 2000

Usage: var result = makeMonthDate(year, month);

A curried wrapper around calling the Date constructor with two arguments: the year and the month. No validation or type-checking occurs on the parameters. Excess arguments are ignored. All other fields in the Date are initialized to zero, with the exception of the day, which is initialized to 1. Returns the new Date.

var d = funkierJS.makeMonthDate(2000, 0); // => A date representing January 1 2000

Usage: var result = makeResultReturner(f);

Takes a function f. Returns a new function with the same arity as f. When called, the new function calls the original. If the function f throws during execution, then the exception will be caught, and an Err object wrapping the exception is returned. Otherwise the result of the function is wrapped in an Ok and returned.

The function will be curried in the same style as the original, or using curry if the function was not curried.

var g = function(x) {
  if (x < 10)
    throw new Error('Bad value');
  return x;
};

var f = funkierJS.makeResultReturner(g);
f(11); // => Ok(11)
f(5); // => Err(Error('Bad value');

Usage: var result = makeSecondDate(year, month, day, hour, minute, second);

A curried wrapper around calling the Date constructor with six arguments: the year, the month, the day, the hour, the minute, and the seconds. No validation or type-checking occurs on the parameters. Excess arguments are ignored. All other fields in the Date are initialized to zero. Returns the new Date.

var d = funkierJS.makeSecondDate(2000, 0, 2, 10, 15, 30); // => A date representing 10:15:30, January 2 2000

Usage: var result = map(f, arr);

Takes a function f, and an array,string or other arrayLike. Returns an array arr2 where, for each element arr2[i], we have arr2[i] === f(arr[i]). Throws a TypeError if the first argument is not a function, if the function does not have an arity of at least 1, or if the last argument is not an arrayLike.

Note that, if required, the function must already have its execution context set. Internally, the execution context within map is null, so it cannot supply a useful execution context to any object-curried functions supplied to this function.

funkierJS.map(plus(1), [2, 3, 4]); // => [3, 4, 5]

Usage: var result = matches(r, s);

Finds all matches within a string for a given regular expression. Takes two parameters: a regular expression and a string. Returns an array of objects, one object per match.

Each object has the following properties:

• index: the index in the original string where the match was found
• matchedText: the substring that matched the pattern
• subexpressions: an array of substrings that matched the parenthesed expressions in the regular expressions. The substring matching the first parenthesised expression will be at position 0, the string matching the second at position 1, and so on. If the regular expression did not contain any parenthesised subexpressions, this array will be empty.

This function is not affected by the presence or absence of a global flag in the supplied regular expression. It is not affected by and does not change the lastIndex property of the regular expression if it exists.

Throws a TypeError if the first parameter is not a regular expression.

funkierJS.matches(/a/, 'banana');
// a => [{index: 1, matchedText: 'a', []}, {index: 3, matchedText: 'a', []},
//       {index: 5, matchedText: 'a', []}]

Usage: var result = matchesFrom(r, index, s);

Finds all matches within a string for a given regular expression from the given index. Takes three parameters: a regular expression, an index and a string. Returns an array of objects, one object per match.

Each object has the following properties:

• index: the index in the original string where the match was found
• matchedText: the substring that matched the pattern
• subexpressions: an array of substrings that matched the parenthesed expressions in the regular expressions. The substring matching the first parenthesised expression will be at position 0, the string matching the second at position 1, and so on. If the regular expression did not contain any parenthesised subexpressions, this array will be empty.

This function is not affected by the presence or absence of a global flag in the supplied regular expression. It is not affected by and does not change the lastIndex property of the regular expression if it exists.

If the index is negative, it is taken as an offset from the end of the string.

Throws a TypeError if the first parameter is not a regular expression.

funkierJS.matchesFrom(/a/, 2, 'banana');
// => [{index: 3, matchedText: 'a', []}, {index: 5, matchedText: 'a', []}]

Usage: var result = max(x, y);

A curried wrapper around Math.max. Takes exactly two arguments.

funkierJS.min(5, 2); // => 5;

Usage: var result = maximum(arr);

Returns the largest element of the given array, string or arrayLike.

Throws a TypeError if the value is not an arrayLike, or it is empty.

Note: this function is intended to be used with arrays containing numeric or character data. You are of course free to abuse it, but it will likely not do what you expect.

funkierJS.maximum([20, 10]); // => 20

See safeCreateProp

See safeDeleteProp

Usage: var result = maybeExtract(prop, obj);

Extracts the given property from the given object, and wraps it in a Just value. When the property is not present, either in the object, or its prototype chain, then Nothing is returned.

funkierJS.maybeExtract('foo', {}); // => Nothing

See safeModify

See safeModify

See safeSet

See safeSet

See maybeExtract

Usage: var result = min(x, y);

A curried wrapper around Math.min. Takes exactly two arguments.

funkierJS.min(5, 2); // => 2;

Usage: var result = minimum(arr);

Returns the smallest element of the given array, string or arrayLike. Throws a TypeError if the value is not an arrayLike, or it is empty.

Note: this function is intended to be used with arrays containing numeric or character data. You are of course free to abuse it, but it will likely not do what you expect.

funkierJS.minimum([20, 10]); // => 10

Usage: var result = modify(prop, val, obj);

Sets the given property to the given value on the given object, providing it exists, and returns the object. Equivalent to evaluating o[prop] = value. The property will not be created when it doesn't exist on the object. Throws when the property is not writable, when it has no setter function, or when the object is frozen.

Alternatively, one can use safeModify for a version that will not throw in the above circumstances. Similarly, set and safeSet can be used to both modify existing properties and create them where required, or create and safeCreateProp can be used when one wants to ensure existing values will not be changed.

var a = {foo: 1};
funkierJS.modify('foo', 42, a); // => returns a
a.foo // => 42

See modify

Usage: var result = multiply(x, y);

A wrapper around the multiplication operator.

funkierJS.multiply(2, 2); // => 4;

Usage: var result = not(b);

A wrapper around the logical not (!) operator. Returns the logical negation of the given argument.

funkierJS.not(true); // => false

Usage: var result = notEqual(a, b);

A wrapper around the inequality (!=) operator.

funkierJS.notEqual({}, {}); // => true

See notEqual

Usage: var result = notPred(f);

Takes a unary predicate function, and returns a new unary function that, when called, will call the original function with the given argument, and return the negated result. Throws if f is not a function, or has an arity other than 1.

If the supplied predicate has been previously curried, then the resulting function will replicate the currying style. In particular, if the original function was curried with one of the objectCurry variants, then the resulting function will be too, and where necessary will supply the execution context to the wrapped function.

var c = funkierJS.constant(true);
var f = funkierJS.notPred(c);
f("foo"); // => false

Usage: var result = nub(arr);

Takes an array, string or arrayLike. Returns a new array/string, with all duplicate elements—tested for strict equality—removed. The order of elements is preserved.

Throws a TypeError if the given argument is not arrayLike.

funkierJS.nub('banana'); // 'ban'

Usage: var result = nubWith(pred, arr);

Takes a predicate function of arity 2, and an array, string or arrayLike. Returns a new array/string, with all duplicate elements removed. A duplicate is defined as a value for which the predicate function returned true when called with a previously encountered element and the element under consideration. The order of elements is preserved.

Throws a TypeError if the first argument is not a function, or has an arity other than 2, or if the last argument is not arrayLike.

Note that, if required, the function must already have its execution context set. Internally, the execution context within nubWith is null, so it cannot supply a useful execution context to any object-curried functions supplied to this function.

var pred = function(x, y) { return x.foo === y.foo; };
funkierJS.nubWith(pred, [{foo: 12}, {foo: 42}, {foo: 42}, {foo: 12}]);
// => [{foo: 12}, {foo: 42}]

Usage: var result = objectCurry(f);

Given a function, returns a curried function which calls the underlying with the execution context active when the first arguments are supplied. This means that when partially applying the function, the resulting functions will have their execution context permanently bound. This method of binding is designed for currying functions that exist on an object's prototype. The function will be only called when sufficient arguments have been supplied. Superfluous arguments are discarded. The resulting function may be called without any arguments even when it has non-zero arity, for the purposes of establishing an execution context (usually when passing the function to some other function-manipulating function); however the partial applications of the result will throw if they require at least one argument, but are invoked without any. objectCurry throws if its parameter is not a function. The resulting function will throw if invoked with an undefined execution context.

The returned function will have a length of 1, unless a function of arity of 0 was supplied, in which case this will be the length. The arityOf function can be used to determine how many arguments are required before the wrapped function will be invoked.

One can pass in a function created by objectCurry or objectCurryWithArity providing it has not been partially applied. This will effectively be an identity operation. However, passing in a partially applied function derived from an earlier currying call is an error, as the execution context has now been bound. Similarly, functions returned from curry, curryWithArity, bind and bindWithContextAndArity cannot be curried with this function, and will throw an error, just as those functions curry functions and their partial applications returned from objectCurry. objectCurry will throw when provided with an invalid function.

Note also that many of the function manipulating functions, such as flip, compose etc. will curry the result in the same manner as the supplied functions, or otherwise will curry them using curry. As noted above, functions curried by curry cannot then be recurried by this function. Thus when performing such manipulations, one must curry them in the desired manner first, before manipulating them. This limitation may be removed in future versions of the library.

In certain cases, objectCurry can be used to curry constructors; the requirement is that the constructor is not new-agnostic. (This may be fixed in future versions). Note that the instanceof relation will not hold for any partially applied functions created along the way.

Unfortunately, funkierJS has no visibility into functions bound with the native bind method; attempting to curry such functions won't throw, but they will not work as expected.

var proto = {foo: function(x, y) { return x + y + this.bar; }};
proto.foo = funkierJS.objectCurry(proto.foo);

var obj1 = Object.create(proto);
obj1.bar = 10;

var g = obj1.foo(10);
g(22); // => 42

var obj2 = Object.create(proto);
obj2.bar = 100;
obj2.foo(10)(10); // => 120
g(1); // => 21, the application using obj2 didn't affect the execution context of g

var err = obj1.foo;
err(1, 2);  // => throws

Usage: var result = objectCurryWithArity(n, f);

Given an arity and function, returns a curried function which calls the underlying with the execution context active when the first arguments are supplied. This means that when partially applying the function, the resulting functions will have their execution context permanently bound. This method of binding is designed for currying functions that exist on an object's prototype. The function will be only called when the specified number of arguments have been supplied. Superfluous arguments are discarded. If the resulting function has non-zero length, it may be called without any arguments for the purpose of establishing an execution context; however its partial applications throw if they require at least one argument, but are invoked without any. objectCurryWithArity throws if the arity is not a natural number or if the second parameter is not a function. The resulting function will throw if invoked with an undefined execution context.

The returned function will have a length of 1, unless an arity of 0 was requested, in which case this will be the length. The arityOf function can be used to determine how many arguments are required before the wrapped function will be invoked.

As noted above, you are permitted to curry a function to a smaller arity than its length. Whether the resulting function behaves in a useful manner will of course depend on the function.

If one has a function that has been returned from objectCurry or objectCurryWithArity, one can recurry it to a different arity if required. However, one cannot recurry any partial applications derived from it, as the execution context has now been bound. objectCurryWithArity also cannot curry functions returned from curry, curryWithArity, bind or bindWithContextAndArity, and nor can those functions curry functions returned from objectCurryWithArity, or their subsequent partial applications. objectCurryWithArity will throw when provided with such a function.

Note also that many of the function manipulating functions, such as flip, compose etc. will curry the result in the same manner as the supplied functions, or otherwise will curry them using curry. As noted above, functions curried by curry cannot then be recurried by this function. Thus when performing such manipulations, one must curry them in the desired manner first, before manipulating them. This limitation may be removed in future versions of the library.

In certain cases, objectCurryWithArity can be used to curry constructors; the requirement is that the constructor is not new-agnostic. (This may be fixed in future versions). Note that the instanceof relation will not hold for any partially applied functions created along the way.

Unfortunately, funkierJS has no visibility into functions bound with the native bind method; attempting to curry such functions won't throw, but they will not work as expected.

var proto = {foo: function(x, y, z) { return x + y + this.bar; }};
proto.foo = funkierJS.objectCurryWithArity(2, proto.foo);

var obj1 = Object.create(proto);
obj1.bar = 10;

var g = obj1.foo(10);
g(22); // => 42

var obj2 = Object.create(proto);
obj2.bar = 100;
obj2.foo(10)(10); // => 120
g(1); // => 21, the application using obj2 didn't affect the execution context of g

var err = obj1.foo;
err(1, 2);  // => throws

Usage: var result = occurrences(needle, haystack);

Takes a value—needle—and haystack, an array, arrayLike or string. Searches for all occurrences of the value—tested for strict equality—and returns an array containing all the indices into haystack where the values may be found.

Throws a TypeError if the haystack parameter is not arrayLike.

funkierJS.occurrences(2, [1, 2, 2, 3, 2, 4]; // => [1, 2, 4]

Usage: var result = occurrencesWith(needle, haystack);

Takes a predicate function pred, and haystack, an array, arrayLike or string. Searches for all occurrences of the value—tested by the given predicate—and returns an array containing all the indices into haystack where the predicate holds.

Throws a TypeError if pred is not a predicate function of arity 1, or if the haystack parameter is not arrayLike.

Note that, if required, the function must already have its execution context set. Internally, the execution context within occurrences is null, so it cannot supply a useful execution context to any object-curried functions supplied to this function.

var pred = function(e) {return e.foo === 42;};
var arr = [{foo: 1}, {foo: 42}, {foo: 42}, {foo: 3}];
funkierJS.occurrencesWith(pred, arr); // => [1, 2]

Usage: var result = odd(x);

Given a number, returns true if it is not divisible by 2, and false otherwise.

funkierJS.odd(2); // => false
funkierJS.odd(3); // => true

Usage: var result = or(x, y);

A wrapper around the logical or (||) operator. Returns the logical or of the given arguments

funkierJS.or(true, false); // => true

Usage: var result = orPred(f1, f2);

Takes two unary predicate functions, and returns a new unary function that, when called, will call the original functions with the given argument, and logically or their results, returning that value. Throws if either argument is not a function of arity 1.

Where possible, funkierJS will aim to replicate the currying style of the function. If either function was produced by one of the `objectCurry' variants, then the resulting function will also be object curried, and supply the correct execution context to the supplied functions. If neither was curried in that manner, but one or more was curried with one of the bind variants, then the resulting function will also be bound to the same context. Otherwise, the function will be curried with curry. (This is only provided in case you need to give the resulting function to one of the withArity functions to change the arity).

var c = funkierJS.constant(true);
var d = funkierJS.constant(false);
var f = funkierJS.orPred(c, d);
f("foo"); // => true

Usage: ord(s);

Takes a string s, and returns the Unicode value of the character at index 0. Equivalent to toCharCode(0, s).

funkierJS.ord('A'); // => 65

Usage: var result = parseInt(s);

A curried wrapper around parseInt when called with one argument. Takes a string and attempts to convert it assuming it represents a number in base 10. Returns NaN if the string does not represent a valid number in base 10.

funkierJS.parseInt(101); // => 101

See stringToInt

Usage: var result = permuteLeft(f);

Takes a function, returns a curried function of the same arity which takes the same parameters, except in a different position. The first parameter of the original function will be the last parameter of the new function, the second parameter of the original will be the first parameter of the new function and so on. This function is essentially a no-op for curried functions of arity 0 and 1, equivalent to curry for uncurried functions of arities 0 and 1, and equivalent to flip for functions of arity 2.

If f is already curried, the currying style of f will be preserved.

Throws a TypeError if f is not a function.

f = function(x, y, z) {return x + y + z;};
g = funkierJS.permuteLeft(f);
g('a', 'b', 'c'); // => 'bca'

Usage: var result = permuteRight(f);

Takes a function, returns a curried function of the same arity which takes the same parameters, except in a different position. The first parameter of the original function will be the second parameter of the new function, the second parameter of the original will be the third parameter of the new function and so on. This function is essentially a no-op for curried functions of arity 0 and 1, equivalent to curry for uncurried functions of arities 0 and 1, and equivalent to flip for functions of arity 2.

If f is already curried, the currying style of f will be preserved.

Throws a TypeError if f is not a function.

f = function(x, y, z) {return x + y + z;};
g = funkierJS.permuteLeft(f);
g('a', 'b', 'c'); // => 'cab'

See add

Usage: var result = post(wrappingFunction, f);

Takes two functions wrappingFunction, and f, and returns a new function with the same arity as the function f, and curried in the same manner (or curried with curry if f was not curried). When this new function is called, it will first call f with the same execution context and arguments that the new function was called with. Its return value will be saved. Next, wrappingFunction will be called, again with the same execution context, and two arguments: an array containing the arguments to f, and f's return value. Anything returned from wrappingFunction will be discarded, and f's return value will be returned.

Throws a TypeError if either of the given values are not functions.

var postLogger = function(args, result) {console.log('plus called with ', args.join(', '), 'returned', result);};
var loggedPlus = funkierJS.post(postLogger, plus);
loggedPlus(2, 2); // => outputs 'plus called with 2, 2 returned 4' to console

See exp

Usage: var result = pre(wrappingFunction, f);

Takes two functions wrappingFunction, and f, and returns a new function with the same arity as the function f, and curried in the same manner (or curried with curry if f was not curried). When this new function is called, it will first call wrappingFunction, with the same execution context, and a single argument: an array containing all the arguments the function was called with. When wrappingFunction returns, its return value will be discarded, and f will be called with the same execution context and invoked with the same arguments as the new function was invoked with. The return value from f will be returned.

Throws a TypeError if neither of the given values are functions.

var logger = function(args) {console.log('plus called with ', args.join(', '));};
var loggedPlus = funkierJS.pre(logger, plus);
loggedPlus(2, 2); // => outputs 'plus called with 2, 2' to console

See inits

Usage: var result = prepend(value, arr);

Takes a value, and an array, string or arrayLike, and returns a new array or string with the given value prepended.

Throws a TypeError if the second argument is not an arrayLike.

Note: if the second argument is a string and the first is not, the value will be coerced to a string; you may not get the result you expect.

var a = [1, 2, 3];
funkierJS.prepend(4, a); // => [4, 1, 2, 3]
a; // => [1, 2, 3] (a is not changed)

Usage: var result = product(arr);

Returns the product of the elements of the given array, or arrayLike. Throws a TypeError if the value is not an arrayLike, or it is empty.

Note: this function is intended to be used with arrays containing numeric data. You are of course free to abuse it, but it will likely not do what you expect.

funkierJS.product([20, 10]); // => 200

Usage: var result = range(a, b);

Takes two numbers, a and b. Returns an array containing the arithmetic sequence of elements from a up to but not including b, each element increasing by 1.

Throws a TypeError if b < a.

funkierJS.range(2, 7); // => [2, 3, 4, 5, 6]

See rangeStride

Usage: var result = rangeStride(a, stride, b);

Takes three numbers, a stride and b. Returns an array containing the arithmetic sequence of elements from a up to but not including b, each element increasing by stride.

Throws a TypeError if the sequence will not terminate.

funkierJS.rangeStep(2, 2, 7); // => [2, 4, 6]

See foldl

See foldl1

See foldr

See foldr1

Usage: var result = regExpSplit(delimiter, s);

A curried wrapper around String.prototype.split. Takes a pattern regexp, and a target string s, and returns an array containing the substrings of s that were separated by substrings matching the given pattern.

Throws a TypeError if the first parameter is not a RegExp or if the second parameter is not a string.

To specify the delimiter as a string, use split. To specify an upper bound, use splitMax/regExpSplitMax.

funkierJS.regExpSplit/a/, 'banana'); // => ['b', 'n', 'n']

See regExpSplitMax

See regExpSplitMax

Usage: var result = regExpSplitMax(delimiter, limit, s);

A curried wrapper around String.prototype.split. Takes a RegExp delimiter, a count, and a target string s, and returns an array containing the substrings of s that were separated by strings matching the given delimiter, the returned array containing at most limit such substrings.

Throws a TypeError if the first parameter is not a RegExp, if the limit count is not integral, or if the last parameter is not a string.

To specify the delimiter as a string, use splitMax. To split without an upper bound, use split/regExpSplit.

funkierJS.regExpSplitMax(/a/, 2, 'banana'); // => ['b', 'n']

Usage: var result = rem(x, y);

A wrapper around the remainder (%) operator.

funkierJS.rem(5, 2); // => 1;

Usage: var result = replicate(length, arr);

Takes a length and a value, and returns an array of the given length, where each element is the given value. Throws a TypeError if the given length is negative.

funkierJS.replicate(5, 42); // => [42, 42, 42, 42, 42]

Usage: var result = reverse(arr);

Takes an array, string or arrayLike, and returns a new array or string that is the reverse of the original.

Throws a TypeError if the argument is not arrayLike.

funkierJS.reverse('banana'); 'ananab'

Usage: var result = rightShift(x, y);

A wrapper around the right shift (>>) operator.

funkierJS.rightShift(-4, 2); // => -1;

Usage: var result = rightShiftZero(x, y);

A wrapper around the left shift (>>>) operator.

funkierJS.rightShiftZero(-4, 2); // => 1073741823;

See permuteLeft

See permuteRight

Usage: var result = safeCreateProp(prop, val, obj);

Creates the given property to the given value on the given object, returning the object wrapped in a Just. Equivalent to evaluating o[prop] = value. The property will be not be modified if it already exists; in that case Nothing will be returned. Additionally, Nothing will be returned when the object is frozen, sealed, or cannot be extended. Note that the property will be successfully created when it already exists, but only in the prototype chain.

Alternatively, one can use create for a version that will throw on failure. Similarly, modify and safeModify can be used to modify existing properties without creating them, and set and safeSet can be used to either modify or create the property as required.

var a = {foo: 1};
Object.freeze(a);
funkierJS.safeCreateProp('bar', 42, a); // => returns Nothing
a.foo // => undefined

Usage: var result = safeDeleteProp(prop, obj);

Deletes the given property from the given the given object, returning the object wrapped as a Just value. Equivalent to evaluating delete o[prop]. When the property is not configurable (either due to the individual descriptor or the object being frozen or sealed) then Nothing will be returned.

Alternatively, one can use delete that will return not wrap the object, and throw on error.

var a = {};
funkierJS.delete('foo',  a); // => returns Nothing

See maybeExtract

Usage: var result = safeModify(prop, val, obj);

Sets the given property to the given value on the given object, providing it exists, and returns the object, wrapped in a Just value when successful. Equivalent to evaluating o[prop] = value. The property will not be created when it doesn't exist on the object; nor will it be amended when the property is not writable, when it has no setter function, or when the object is frozen. In such cases, Nothing will be returned.

Alternatively, one can use modify for a version that will throw in the above circumstances. Similarly, set and safeSet can be used to both modify existing properties and create them where required, or create and safeCreateProp can be used when one wants to ensure existing values will not be changed.

var a = {foo: 1};
Object.freeze(a);
funkierJS.safeModify('foo', 42, a); // => Nothing
a.foo // => 1

See safeModify

Usage: var result = safeSet(prop, val, obj);

Sets the given property to the given value on the given object, returning the object wrapped in a Just value when successful. Equivalent to evaluating o[prop] = value. The property will be created if it doesn't exist on the object. If unable to modify or create the property, then Nothing will be returned.

Alternatively, one can use set for a version that will throw in the above circumstances. Similarly, modify and safeModify can be used to guarantee the property is not created when it does not exist, or create and safeCreateProp can be used when one wants to ensure existing values will not be changed.

var a = {foo: 1};
Object.freeze(a);
funkierJS.safeSet('foo', 42, a); // => returns Nothing
a.foo // => 1

See safeSet

See maybeExtract

See snd

Usage: var result = sectionLeft(f, x);

Partially applies the binary function f with the given argument x, with x being supplied as the first argument to f. The given function f will be curried if necessary. Throws if f is not a binary function.

Note that object-curried functions should first be given a context before passing them into this function: internally this is bound to null within sectionLeft, so it cannot supply a useful execution context to the supplied function.

var f = function(x, y) {return x * y;};',
var g = funkierJS.sectionLeft(f, 2);
g(3); // => 6 (i.e. 2 * 3)',

Usage: var result = sectionRight(f, x);

Partially applies the binary function f with the given argument x, with x being supplied as the second argument to f. The given function f will be curried if necessary. Throws if f is not a binary function.

Note that object-curried functions should first be given a context before passing them into this function: internally this is bound to null within sectionRight, so it cannot supply a useful execution context to the supplied function.

var fn = funkierJS.sectionRight(funkierJS.subtract, 3);
fn(2); // => -1

Usage: var result = set(prop, val, obj);

Sets the given property to the given value on the given object, returning the object. Equivalent to evaluating o[prop] = value. The property will be created if it doesn't exist on the object. Throws when the property is not writable, when it has no setter function, when the object is frozen, or when it is sealed and the property is not already present.

Alternatively, one can use safeSet for a version that will not throw in the above circumstances. Similarly, modify and safeModify can be used to guarantee the property is not created when it does not exist, or create and safeCreateProp can be used when one wants to ensure existing values will not be changed.

var a = {foo: 1};
funkierJS.set('foo', 42, a); // => returns a
a.foo // => 42

Usage: var result = setDayOfMonth(day, d);

A wrapper around Date.prototype.setDate. Takes a value between 1 and 31, and a Date object, and sets the day of the month to the given value. Invalid values will cause a change in other fields: for example, changing the day to 31 in a month with 30 days will increment the month, which may in turn increment the year. Returns the given 'Date` object.

var a = new Date(2000, 1, 15, 10, 11, 12, 13);
funkierJS.setDayOfMonth(1, a); // => a now refers to Feb 1 2000

Usage: var result = setFullYear(year, d);

A wrapper around Date.prototype.setFullYear. Takes a value and a Date object, and sets the year to the given value. This may cause a change in other fields: for example, setting the year when the month and day represent February 29 respectively may cause those values to change to March 1 if the new year is not a leap year. Returns the given Date object.

var a = new Date(2000, 1, 15, 10, 11, 12, 13);
funkierJS.setFullYear(2001, a); // => a now refers to Feb 15 2001

Usage: var result = setHours(hours, d);

A wrapper around Date.prototype.setHours. Takes a value between 0 and 23 representing the hour of the day, and a Date object, and sets the hour to the given value. Invalid values will cause a change in other fields: if the value > 23, then the day will be incremented by hours div 24. This may in turn cause a cascade of increments to other fields. Returns the given Date object.

var a = new Date(2000, 1, 15, 10, 11, 12, 13);
funkierJS.setHours(11, a); // => a now refers to 11:11:12:013

Usage: var result = setMilliseconds(milliseconds, d);

A wrapper around Date.prototype.setMilliseconds. Takes a value between 0 and 999 representing the milliseconds, and a Date object, and sets the milliseconds to the given value. Invalid values will cause a change in other fields: if the value > 999, then the seconds will be incremented by milliseconds div 1000. This may in turn cause a cascade of increments to other fields. Returns the given Date object.

var a = new Date(2000, 1, 15, 10, 11, 12, 13);
funkierJS.setMilliseconds(20, a); // => a now refers to 10:11:12:020

Usage: var result = setMinutes(minutes, d);

A wrapper around Date.prototype.setMinutes. Takes a value between 0 and 59 representing the minutes, and a Date object, and sets the minutes to the given value. Invalid values will cause a change in other fields: if the value > 59, then the hours will be incremented by minutes div 60. This may in turn cause a cascade of increments to other fields. Returns the given Date object.

var a = new Date(2000, 1, 15, 10, 11, 12, 13);
funkierJS.setMinutes(59, a); // => a now refers to 10:59:12:013

Usage: var result = setMonth(month, d);

A wrapper around Date.prototype.setMonth. Takes a value between 0 and 11 representing the month, and a Date object, and sets the month to the given value. Invalid values will cause a change in other fields: if the value > 11, then the year will be incremented by month div 12. Returns the given Date object.

var a = new Date(2000, 1, 15, 10, 11, 12, 13);
funkierJS.setMonth(2, a); // => a now refers to 15 March 2001

See set

Usage: var result = setSeconds(seconds, d);

A wrapper around Date.prototype.setSeconds. Takes a value between 0 and 59 representing the seconds, and a Date object, and sets the seconds to the given value. Invalid values will cause a change in other fields: if the value > 59, then the minutes will be incremented by seconds div 60. This may in turn cause a cascade of increments to other fields. Returns the given Date object.