space-lift - npm Package Compare versions

Comparing version 0.1.1 to 0.2.0

array/find.d.ts

@@ -1,2 +0,2 @@
-import { Option } from 'option.ts';
+import { Option } from '../option';
 import { ArrayOps } from '../';
@@ -3,0 +3,0 @@ declare module '../' {

array/find.js

 "use strict";
 exports.__esModule = true;
-var option_ts_1 = require("option.ts");
+var option_1 = require("../option");
 var _1 = require("../");
@@ -13,7 +13,7 @@ /**
         if (predicate(item, i))
-            return option_ts_1.Option(item);
+            return option_1.Option(item);
     }
-    return option_ts_1.None;
+    return option_1.None;
 }
 exports.find = find;
 _1.ArrayOps.prototype.find = find;

array/findIndex.d.ts

@@ -1,2 +0,2 @@
-import { Option } from 'option.ts';
+import { Option } from '../option';
 import { ArrayOps } from '../';
@@ -3,0 +3,0 @@ declare module '../' {

array/findIndex.js

 "use strict";
 exports.__esModule = true;
-var option_ts_1 = require("option.ts");
+var option_1 = require("../option");
 var _1 = require("../");
@@ -12,7 +12,7 @@ /**
         if (predicate(arr[i], i))
-            return option_ts_1.Option(i);
+            return option_1.Option(i);
     }
-    return option_ts_1.None;
+    return option_1.None;
 }
 exports.findIndex = findIndex;
 _1.ArrayOps.prototype.findIndex = findIndex;

array/first.d.ts

@@ -1,2 +0,2 @@
-import { Option } from 'option.ts';
+import { Option } from '../option';
 import { ArrayOps } from '../';
@@ -3,0 +3,0 @@ declare module '../' {

array/first.js

 "use strict";
 exports.__esModule = true;
-var option_ts_1 = require("option.ts");
+var option_1 = require("../option");
 var _1 = require("../");
@@ -9,5 +9,5 @@ /**
 function first() {
-    return option_ts_1.Option(this.value()[0]);
+    return option_1.Option(this.value()[0]);
 }
 exports.first = first;
 _1.ArrayOps.prototype.first = first;

array/flatMap.d.ts

@@ -1,2 +0,2 @@
-import { Option } from 'option.ts';
+import { Option } from '../option';
 import { ArrayOps, Wrapper } from '../';
@@ -3,0 +3,0 @@ declare module '../' {

array/flatMap.js

 "use strict";
 exports.__esModule = true;
-var option_ts_1 = require("option.ts");
+var option_1 = require("../option");
 var _1 = require("../");
@@ -12,3 +12,3 @@ /**
         var item = fun(arr[i], i);
-        if (option_ts_1.Option.isOption(item))
+        if (option_1.Option.isOption(item))
             item.isDefined() && result.push(item.get());
@@ -15,0 +15,0 @@ else

array/flatten.d.ts

@@ -1,2 +0,2 @@
-import { Option } from 'option.ts';
+import { Option } from '../option';
 import { ArrayOps } from '../';
@@ -3,0 +3,0 @@ declare module '../' {

array/flatten.js

 "use strict";
 exports.__esModule = true;
-var option_ts_1 = require("option.ts");
+var option_1 = require("../option");
 var _1 = require("../");
@@ -12,3 +12,3 @@ /**
         var item = arr[i];
-        if (option_ts_1.Option.isOption(item))
+        if (option_1.Option.isOption(item))
             item.isDefined() && result.push(item.get());
@@ -15,0 +15,0 @@ else

array/get.d.ts

@@ -1,2 +0,2 @@
-import { Option } from 'option.ts';
+import { Option } from '../option';
 import { ArrayOps } from '../';
@@ -3,0 +3,0 @@ declare module '../' {

array/get.js

 "use strict";
 exports.__esModule = true;
-var option_ts_1 = require("option.ts");
+var option_1 = require("../option");
 var _1 = require("../");
@@ -9,5 +9,5 @@ /**
 function get(index) {
-    return option_ts_1.Option(this.value()[index]);
+    return option_1.Option(this.value()[index]);
 }
 exports.get = get;
 _1.ArrayOps.prototype.get = get;

array/last.d.ts

@@ -1,2 +0,2 @@
-import { Option } from 'option.ts';
+import { Option } from '../option';
 import { ArrayOps } from '../';
@@ -3,0 +3,0 @@ declare module '../' {

array/last.js

 "use strict";
 exports.__esModule = true;
-var option_ts_1 = require("option.ts");
+var option_1 = require("../option");
 var _1 = require("../");
@@ -10,5 +10,5 @@ /**
     var arr = this.value();
-    return option_ts_1.Option(arr[arr.length - 1]);
+    return option_1.Option(arr[arr.length - 1]);
 }
 exports.last = last;
 _1.ArrayOps.prototype.last = last;

index.d.ts

@@ -15,29 +15,29 @@ export interface Lift {
 export default lift;
-export declare class ArrayOps<A> {
+export declare class ArrayOps<A> implements Wrapper<A[]> {
     constructor(array: A[]);
-    private _isLiftWrapper;
+    _isLiftWrapper: boolean;
     private _value;
     value(): A[];
 }
-export declare class ObjectOps<A> {
+export declare class ObjectOps<A> implements Wrapper<A> {
     constructor(object: A);
-    private _isLiftWrapper;
+    _isLiftWrapper: boolean;
     private _value;
     value(): A;
 }
-export declare class NumberOps {
+export declare class NumberOps implements Wrapper<number> {
     constructor(num: number);
-    private _isLiftWrapper;
+    _isLiftWrapper: boolean;
     private _value;
     value(): number;
 }
-export declare class StringOps {
+export declare class StringOps implements Wrapper<string> {
     constructor(str: string);
-    private _isLiftWrapper;
+    _isLiftWrapper: boolean;
     private _value;
     value(): string;
 }
-export declare class BoolOps {
+export declare class BoolOps implements Wrapper<boolean> {
     constructor(value: boolean);
-    private _isLiftWrapper;
+    _isLiftWrapper: boolean;
     private _value;
@@ -47,2 +47,3 @@ value(): boolean;
 export interface Wrapper<A> {
+    _isLiftWrapper: {};
     value(): A;
@@ -52,2 +53,3 @@ }
 export { update, DELETE } from 'immupdate';
-export { Option, None, Some } from 'option.ts';
+export { Option, None, Some } from './option';
+export { Result, Ok, Err } from './result';

index.js

@@ -77,3 +77,3 @@ "use strict";
 function getValue(input) {
-    return input['_isLiftWrapper']
+    return input && input['_isLiftWrapper']
         ? input.value()
@@ -89,5 +89,9 @@ : input;
 exports.DELETE = immupdate_1.DELETE;
-var option_ts_1 = require("option.ts");
-exports.Option = option_ts_1.Option;
-exports.None = option_ts_1.None;
-exports.Some = option_ts_1.Some;
+var option_1 = require("./option");
+exports.Option = option_1.Option;
+exports.None = option_1.None;
+exports.Some = option_1.Some;
+var result_1 = require("./result");
+exports.Result = result_1.Result;
+exports.Ok = result_1.Ok;
+exports.Err = result_1.Err;

object/get.d.ts

@@ -1,3 +0,3 @@
-import { Option } from 'option.ts';
-import { ObjectOps } from '../';
+import { Option } from '../option';
+import { ObjectOps } from '..';
 declare module '../' {
@@ -4,0 +4,0 @@ interface ObjectOps<A> {

object/get.js

 "use strict";
 exports.__esModule = true;
-var option_ts_1 = require("option.ts");
-var _1 = require("../");
+var option_1 = require("../option");
+var __1 = require("..");
 /**
@@ -11,5 +11,5 @@ * Returns the value found at the provided key, as an Option.
 function get(key) {
-    return option_ts_1.Option(this.value()[key]);
+    return option_1.Option(this.value()[key]);
 }
 exports.get = get;
-_1.ObjectOps.prototype.get = get;
+__1.ObjectOps.prototype.get = get;

package.json

 {
   "name": "space-lift",
-  "version": "0.1.1",
-  "description": "JS/TS array, object utils",
+  "version": "0.2.0",
+  "description": "Idiomatic TS array, object utils, Option, Result monads",
   "main": "index.js",
@@ -17,3 +17,5 @@ "typings": "index.d.ts",
     "object",
-    "function"
+    "function",
+    "option",
+    "result"
   ],
@@ -23,4 +25,4 @@
     "build": "tsc src/**/*.ts src/*.ts --lib 'es5,es2015.core' --outDir ./ --declaration --noImplicitAny --strictNullChecks --suppressImplicitAnyIndexErrors",
-    "pretest": "npm run build && tsc --lib 'es5,es2015.core' test/mocha.d.ts test/global.d.ts test/test.ts --outDir ./test --noImplicitAny --strictNullChecks",
-    "test": "mocha test/test.js",
+    "pretest": "npm run build && tsc --lib 'es5,es2015.core' test/expect.d.ts test/mocha.d.ts test/global.d.ts test/test.ts test/option.ts test/result.ts --outDir ./test --noImplicitAny --strictNullChecks",
+    "test": "mocha test/test.js && mocha --ui tdd test/option.js && mocha --ui tdd test/result.js",
     "prepublish": "npm run build"
@@ -30,8 +32,7 @@ },
   "dependencies": {
-    "immupdate": "1.0.2",
-    "option.ts": "0.3.0"
+    "immupdate": "1.0.2"
   },
 
   "devDependencies": {
-    "typescript": "next",
+    "typescript": "2.3.2",
     "mocha": "3.0.2",
@@ -50,3 +51,3 @@ "expect": "1.8.0"
   "homepage": "https://github.com/AlexGalays/spacelift",
-  "keywords": ["typescript", "ts", "TS", "std lib", "collection", "underscore"]
+  "keywords": ["typescript", "ts", "TS", "std lib", "collection", "underscore", "monad", "option", "maybe", "result"]
 }

README.md

@@ -7,3 +7,3 @@ **space-lift**
 
-# Utils for Arrays, Objects  
+# Rich Array/Object wrapper, Option, Result monads
 
@@ -15,19 +15,54 @@ Design goals
 - Tiny and performant
-- Small set of functions, configurable with lambdas rather than a kitchen sink trying to cater for every single little variation
+- Small set of functions, configurable with lambdas
+- Cover 95% of frontend data transformation needs without becoming a bloated lib just to cover the remaining 5%
+- The Array/Object wrappers use an OO style as it's the most convenient without an `|>` operator directly in the language
 
 
-# Importing
+* [How to use](#howtouse)
+* [Examples](#examples)
+* [Installing](#installing)
+* [Auto unwrap](#autounwrap)
+* [API](#api)
+  * [Array](#api.array)
+  * [Object](#api.object)
+  * [Function](#api.function)
+  * [Option](#api.option)
+  * [Result](#api.result)
 
-For convenience, `space-lift` uses and re-export [immupdate](https://github.com/AlexGalays/immupdate) and [option.ts](https://github.com/AlexGalays/option.ts) for seamless chaining and type-safety.
 
+<a name="howtouse"></a>
+# How to use
+
 Here's everything that can be imported from `space-lift`:  
 
 ```ts
-import lift, { Option, Some, None, update, DELETE } from 'space-lift'
+import lift, { Option, Some, None, Result, Ok, Err, update, DELETE } from 'space-lift'
 ```
 
-`Option`, `Some`, `None` come from [option.ts](https://github.com/AlexGalays/option.ts)  
-`update`, `DELETE` come from [immupdate](https://github.com/AlexGalays/immupdate)
+`lift` is a generic function that can wrap an Array or Object and give it extra functionalities  
+`update`, `DELETE` come from [immupdate](https://github.com/AlexGalays/immupdate)  
+`Option`, `Some`, `None` are used to work with optional values  
+`Result`, `Ok`, `Err` are used to work with computation that may fail  
 
 
+By default, the library provides no operators to the Wrapped Arrays/Objects at all. You get to choose what to import.
+
+The fastest way is to install everything in a single import (probably in your main file):  
+
+```ts
+import 'space-lift/all'
+```
+
+But you can also choose exactly what to import:  
+
+```ts
+import 'space-lift/array/map'
+import 'space-lift/object/mapValues'
+```
+
+Note: When using typescript, don't forget to enable (at least) these two flags for better type-safety: `noImplicitAny`, `strictNullChecks`
+
+
+
+<a name="examples"></a>
 # Examples  
@@ -49,3 +84,3 @@
   .findIndex(p => p.id === 2)
-  .map(index => lift(people).updateAt(index, p => update(p, { name: 'Nick' })))
+  .map(index => lift(people).updateAt(index, person => update(person, { name: 'Nick' })))
   .getOrElse(people)
@@ -60,5 +95,5 @@ ```
 const people = [
-  { first: 'jon', last: 'haggis' },
+  { first: 'jon',   last: 'haggis' },
   { first: 'sarah', last: 'john' },
-  { first: 'nina', last: 'pedro' }
+  { first: 'nina',  last: 'pedro' }
 ]
@@ -73,32 +108,424 @@
 
+<a name="autounwrap"></a>
+# Auto unwrap
 
-# Install
+Most of the time, you will have to call `.value()` to read your value back (or `.get()` for options, although it is recommended to use `map`/`getOrElse`/etc instead)  
+Because it's distracting to write `.value()` more than once per chain, some operators will automatically unwrap values returned from their iterators.  
+These operators are:  
 
-By default, the library provides no operators at all. You get to choose what to import.
+- `Option.map`
+- `Array.map`
+- `Array.flatMap`
+- `Array.updateAt`
 
-The fastest way is to install everything in a single import (probably in your main file):  
 
+<a name="api"></a>
+# API
+
+
+
+<a name="api.array"></a>
+## Array
+
+* [lift(array)](#lift.array)
+* [append](#array.append)
+* [appendAll](#array.appendAll)
+* [compact](#array.compact)
+* [count](#array.count)
+* [distinct](#array.distinct)
+* [drop](#array.drop)
+* [dropRight](#array.dropRight)
+* [every](#array.every)
+* [filter](#array.filter)
+* [find](#array.find)
+* [findIndex](#array.findIndex)
+* [first](#array.first)
+* [flatMap](#array.flatMap)
+* [flatten](#array.flatten)
+* [fold](#array.fold)
+* [foldRight](#array.foldRight)
+* [fromArrayLike](#array.fromArrayLike)
+* [get](#array.get)
+* [groupBy](#array.groupBy)
+* [insert](#array.insert)
+* [insertAll](#array.insertAll)
+* [join](#array.join)
+* [last](#array.last)
+* [map](#array.map)
+* [range](#array.range)
+* [removeAt](#array.removeAt)
+* [reverse](#array.reverse)
+* [some](#array.some)
+* [sort](#array.sort)
+* [take](#array.take)
+* [takeRight](#array.takeRight)
+* [toSet](#array.toSet)
+* [updateAt](#array.updateAt)
+
+TODO: Detail and examples
+
+
+<a name="api.object"></a>
+## Object
+
+* [lift(object)](#lift.object)
+* [add](#object.add)
+* [filter](#object.filter)
+* [get](#object.get)
+* [is](#object.is)
+* [keys](#object.keys)
+* [mapValues](#object.mapValues)
+* [remove](#object.remove)
+* [set](#object.set)
+* [toArray](#object.toArray)
+* [update](#object.update)
+* [values](#object.values)
+
+TODO: Detail and examples
+
+
+
+<a name="api.function"></a>
+## Function
+
+### memoize
+
 ```ts
-import 'space-lift/all'
+import memoize from 'space-lift/function/memoize'
+
+function multiply(a: number, b: number) {
+  return a * b
+}
+
+// Using reference equality on every arg
+const memoizedMultiply = memoize(multiply)
+
+
+const myObj = { id: 10 }
+
+// Using memo keys
+const memoized = memoize(
+  (a: number, b: typeof myObj): {} => ({ x: a, y: b }),
+  { key: (a, b) => `${a}_${b.id}` }
+)
+
 ```
 
-But you can also choose exactly what to import:  
 
+<a name="api.option"></a>
+## Option 
+
+* [Option()](#Option())
+* [Option.all()](#Option.all)
+* [Option.isOption](#Option.isOption)
+* [None](#option.None)
+* [map](#option.map)
+* [flatMap](#option.flatMap)
+* [filter](#option.filter)
+* [fold](#option.fold)
+* [orElse](#option.orElse)
+* [isDefined](#option.isDefined)
+* [get](#option.get)
+* [getOrElse](#option.getOrElse)
+* [forEach](#option.forEach)
+* [toArray](#option.toArray)
+
+
+### Creating an Option
+
+<a name="Option()"></a>
+#### Option(x)
+
+Creates an Option from a value.
+If the value is null or undefined, it will create a None, else a Some.
+
 ```ts
-import 'space-lift/array/map'
-import 'space-lift/object/mapValues'
+const some = Option(33) // some === Some(33)
+const none = Option(null) // none === None
 ```
 
-Note: When using typescript, don't forget to enable (at least) these two flags for better type-safety: `noImplicitAny`, `strictNullChecks`
+If you already know the value is defined for sure (not nullable) or not, you can create a `Some` or `None` directly:  
 
+```ts
+const some = Some(33) // Some(null | undefined) wouldn't compile.
+const none = None
+```
 
-# Auto unwrap
 
-Most of the time, you will have to call `.value()` to read your value back (or `.get()` for options, although it is recommended to use `map`/`getOrElse`/etc instead)  
-Because it's distracting to write `.value()` more than once per chain, some operators will automatically unwrap values returned from their iterators.  
-These operators are:  
+<a name="Option.all"></a>
+#### Option.all(...optionsOrValues)
 
-- `Option.map`
-- `Array.map`
-- `Array.flatMap`
-- `Array.updateAt`
+Creates a new Option holding the tuple of all the passed values if they were all Some or non null/undefined values,  
+else returns None
+
+```ts
+const some = Option.all(
+  Option(10),
+  20,
+  Option(5)
+)
+// some === Some([10, 20, 5])
+
+const none = Option.all(
+  Option(10),
+  None,
+  Option(5),
+  null
+)
+// none === None
+```
+
+<a name="Option.isOption"></a>
+#### Option.isOption
+
+Returns whether the passed instance in an Option, and refines its type
+
+```ts
+import { Option, Some } from 'space-lift'
+Option.isOption(Some(33)) // true
+```
+
+
+<a name="option.None"></a>
+#### None
+
+The Option constant representing no value.
+
+```ts
+import { None } from 'space-lift'
+```
+
+
+### Transforming an Option
+
+<a name="option.map"></a>
+#### map
+
+Maps the value contained in this Some, else returns None.
+Depending on the map function return value, a Some could be tranformed into a None, as a Some is guaranteed to never contain a null or undefined value.
+
+```ts
+const some = Option(33).map(x => x * 2)
+// some === Some(66)
+```
+
+<a name="option.flatMap"></a>
+#### flatMap
+
+Maps the value contained in this Some to a new Option, else returns None.
+
+```ts
+const some = Option(33).flatMap(_ => Option(44))
+// some === Some(44)
+```
+
+<a name="option.filter"></a>
+#### filter
+
+If this Option is a Some and the predicate returns true, keep that Some.
+In all other cases, return None.
+
+```ts
+const some = Option(33).filter(x => x > 32)
+// some === Some(33)
+```
+
+<a name="option.fold"></a>
+#### fold
+
+Applies the first function if this is a None, else applies the second function.  
+Note: Since this method creates 2 functions everytime it runs, don't use in tight loops; use isDefined() instead.
+
+```ts
+const count = Option(10).fold(
+  () => 100, // None
+  count => count * 10 // Some
+)
+```
+
+<a name="option.toArray"></a>
+#### toArray
+
+Transforms this option into an Array or either 1 or 0 element.
+
+
+<a name="option.orElse"></a>
+#### orElse
+
+Returns this Option unless it's a None, in which case the provided alternative is returned.
+
+```ts
+const some = Option(null).orElse(() => Option(33))
+// some === Some(33)
+```
+
+### Misc
+
+<a name="option.get"></a>
+#### get
+
+`Some` instances return their value, whereas `None` always return `undefined`.  
+This method never throws.
+
+```ts
+const value = Some(33).get()
+// value === 33
+```
+
+<a name="option.isDefined"></a>
+#### isDefined
+
+Returns whether this Option has a defined value (i.e, it's a Some(value))  
+Note: this refines the type of the Option to be a Some so it's guaranteed its value is not null/undefined.
+
+
+<a name="option.getOrElse"></a>
+#### getOrElse
+
+Returns this Option's value if it's a Some, else return the provided alternative
+
+```ts
+const value = Option(undefined).getOrElse(33)
+
+// value === 33
+```
+
+
+<a name="option.forEach"></a>
+#### forEach
+
+Applies the given procedure to the option's value, if it is non empty.
+
+```ts
+Option(33).forEach(x => console.log(x))
+```
+
+
+
+
+
+<a name="api.result"></a>
+## Result
+
+* [Result, Ok, Err](#Result)
+* [Result.isResult](#Result.isResult)
+* [Result.all](#Result.all)
+* [isOk](#result.isOk)
+* [map](#result.map)
+* [mapError](#result.mapError)
+* [flatMap](#result.flatMap)
+* [fold](#result.fold)
+
+
+A `Result` is the result of a computation that may fail. An `Ok` represents a successful computation, while an `Err` represent the error case.  
+
+
+<a name="Result"></a>
+### Importing Result
+
+Here's everything that can be imported to use Results:  
+
+```ts
+import { Result, Ok, Err } from 'space-lift'
+
+const ok = Ok(10)
+const err = Err('oops')
+```
+
+<a name="Result.isResult"></a>
+### Result.isResult
+
+Returns whether this instance is a Result (either an Ok or a Err) and refines its type
+
+```ts
+import { Result, Ok } from 'space-lift'
+
+Result.isResult(Ok(10)) // true
+```
+
+<a name="Result.all"></a>
+### Result.all
+
+Creates a new Ok Result holding the tuple of all the passed values if they were all Ok,
+else returns the first encountered Err.
+
+```ts
+import { Result, Ok, Err } from 'space-lift'
+
+const result = Result.all(
+  Ok(20),
+  Err('nooo'),
+  Ok(200),
+  Err('oops')
+) // Err('nooo')
+```
+
+
+<a name="result.isOk"></a>
+### isOk
+
+Returns whether this is an instance of Ok
+
+```ts
+import { Result, Ok, Err } from 'space-lift'
+
+Ok(10).isOk() // true
+```
+
+
+<a name="result.map"></a>
+### map
+
+Maps the value contained in this Result if it's an Ok, else propagates the Error.
+
+```ts
+import { Result, Ok, Err } from 'space-lift'
+
+Ok(10).map(x => x * 2) // Ok(20)
+Err(10).map(x => x * 2) // Err(10)
+```
+
+
+<a name="result.mapError"></a>
+### mapError
+
+Maps the Error contained in this Result if it's an Err, else propagates the Ok.
+
+```ts
+import { Result, Ok, Err } from 'space-lift'
+
+Ok(10).mapError(x => x * 2) // Ok(10)
+Err(10).mapError(x => x * 2) // Err(20)
+```
+
+
+<a name="result.flatMap"></a>
+### flatMap
+
+Maps the value contained in this Result with another Result if it's an Ok, else propagates the Error.
+Note: It is allowed to return a Result with a different Error type.
+
+```ts
+import { Result, Ok, Err } from 'space-lift'
+
+Ok(10).flatMap(x => Ok(x * 2)) // Ok(20)
+Ok(10).flatMap(x => Err(x * 2)) // Err(20)
+```
+
+
+<a name="result.fold"></a>
+### fold
+
+Applies the first function if this is an Err, else applies the second function.
+Note: Don't use in tight loops; use isOk() instead.
+
+
+```ts
+import { Result, Ok, Err } from 'space-lift'
+
+Ok(10).fold(
+  err => console.error(err),
+  num => num * 2
+) // 20
+```
+

No alert changes

Improved metrics

Total package byte prevSize

71100

increased by37.24%

Dependency count

1

decreased by-50%

Number of package files

102

increased by4.08%

Lines of code

1900

increased by20.71%

Number of lines in readme file

527

increased by432.32%

Dependency changes

• - Removedoption.ts@0.3.0

• - Removedoption.ts@0.3.0(transitive)