npm package: @imolko/ultra-result
Description: Librería para el manejo de resultados. Esta librería busca hacer más expresivo el manejo de los resultados de llamadas a distintas funciones.
Author: Roberto Matute
Latest version: 2.0.11

Ultra-Result
========

Librería para el manejo de resultados.

Esta librería busca hacer más expresivo el manejo de los resultados de llamadas a distintas funciones.

Problema que resuelve
========

El objetivo es hacer más expresivo el código que generamos.  La idea es que se evite romper el flujo de control con IFs, Loops y switch.  

Inspiración
======

Se toman un montón de ideas de la programación funcional. 

Se toman bastante ideas de la librería [fp-ts](https://github.com/gcanti/fp-ts) que maneja un montón de conceptos funcionales en typescript.


Conceptos principales
=======

Execution
------

Clase para representar un cambio síncrono en el estado de la aplicación. 

Se entiende por ejecución cualquier función que hace un cambio en la aplicación. Esto incluye creación de objetos, transformación de objetos, etc.

Para ejecuciones asíncronas ver TaskExecution.

Validation
-----

Clase para representar una validación síncrona a realizar sobre un dato. Una validación no realiza transformación en ninguna variable o estado de la aplicación.

Se utiliza normalmente para garantizar que un dato cumple con unas reglas. Por ejemplo, IsEmail, MaxLength, HasAccess, etc.

Para validaciones asíncronas ver TaskValidation.

Task
----

Define una interface básica para una tarea asíncrona. En la mayoría de los casos, vas a usar TaskValidation o TaskExecution, pero se incluye el Task porque es el tipo base para ambos.

Cuándo utilices cualquier tipo de tarea, se va a devolver una función que crea la promesa. Por esta razón para obtener el resultado final, debes usar:

```javascript
const process = task(...);
const result = await process();
```

TaskExecution
-------

Clase para representar una Ejecución que se realiza asíncronamente. 

Para ejecuciones síncronas ver Execution.

TaskValidation
-----

Clase para representar una Validación que se realiza asíncronamente.

Para validaciones asíncronas ver Validation.


Seed - Encadenamiento de funciones
======

Se provee la clase "seed" como mecanismo para encadenar operaciones.  

La idea es utilizar la misma idea de los observables, dónde se aplican distintas funciones sin tener que trabajar directamente con los valores.

La clase seed es muy sencilla y sólo provee el método "pipe". Este métod simplemente se encarga de llamar consecutivamente las funciones suministradas, pasando la salida de la anterior como entrada de la próxima.

Cada función en el pipe debe ser una función con un sólo parámetro.

```javascript
const process = seed(1)
    .pipe(
        (value) => value+1
        (value) => value*10
    );
expect(process).toBe(20);
```


Operadores comunes
======

Cada tipo de datos ofrece operadores comunes. Estos operadores manejan el mismo concepto aplicado a cada tipo de datos.

chain
------

Aplica una función para crear un nuevo objeto. La función recibe el valor almacenado en el objeto actual y devuelve un nuevo objeto.

fold
------

Permite aplicar una función al valor exitoso o una función al error. El operador ejecuta la función de acuerdo al status del objeto.

fromError
------

Crea un nuevo objeto a partir de una lista de errores.  El objeto creado es del tipo Invalid o Fail.

fromValue
-------

Crea un nuevo objeto a partir de un valor.  El objeto creado es del tipo Ok o Valid.

map
-----

Aplica una función para transformar el valor de un objeto. La función recibe el valor almacenado en el objeto actual y devuelve un nuevo valor.

tapValue
------

Aplica un efecto colateral en el valor del objeto. La función sólo se ejecuta si el objeto está en Ok o Valid.

tap
------

Aplica un efecto colateral en el objeto. La función recibe el objeto completo.

Tests
=====

La librería tiene tests para todas las clases principales y cada operador implementado.

Cada test está pegado al archivo correspondiente con la extensión "spec".

Te recomiendo que revises los tests que sirven como documentación de cómo funciona cada clase y operador.