Releases · erikjuhani/fp-utils

Full Changelog: 0.7.0...0.8.0

BREAKING CHANGES

The 0.8.0 version contains breaking changes related to functions Option.fromPromise, Option.fromNullable, Result.fromThrowable and Result.fromPromise.

These functions were joined into one function in both modules and now the same functionality can be invoked by calling Option.from or Result.from functions.

The old functions were removed and should be changed to from instead.

Add Result.from function

Result.from function merges the functionality of fromPromise and
fromThrowable to a one function. The function return type is a recursive
type, which means that it can infer from the given value what the actual
return type should be and thus matches with the inner logic of the
function and returns the expected type. The recursive type is called
From. The function itself streamlines the conversion to Result and
allows to use just one function when converting values to results.

The Result.from function accepts an optional second parameter
expected, which if given will replace any errors thrown or rejected
and be returned instead.

// Easily convert async functions to results
result = Result.from(fetch("https://some-address.com/api/get_endpoint"));

// Or promises
result = Result.from(Promise.resolve(42));

// Or primitive values
result = Result.from(42);

Add Option.from function

Option.from function merges the functionality of fromPromise and
fromNullable to a one function. The function return type is a recursive
type, which means that it can infer from the given value what the actual
return type should be and thus matches with the inner logic of the
function and returns the expected type. The recursive type is called
From. The function itself streamlines the conversion to Option and
allows to use just one function when converting values to Options.

// Easily convert optional values into options
opt = Option.from(maybeString);

// Or even functions!
opt = Option.from(() => maybeString);

// Or promises
opt = Option.from(Promise.resolve(42));

Add @module documentation for Result

Simplify the README and module examples and add the example code under
examples/result_readme_example.ts.

Add @module documentation for Option

Simplify the README and module examples and add the example code under
examples/option_readme_example.ts.

Full Changelog: 0.6.0...0.7.0

Update build_npm to work with deno.json files

The deno.json file is packed as the package.json file for npm
publishing. Version is now directly derived from the deno.json file
instead.

Add deno.json file for Result

The deno.json file contains the module definitions like file exports,
name and version. Essentially the deno.json file mimicks
package.json file.

Set Result to version 0.7.0 in deno.json.

Add deno.json file for Option

The deno.json file contains the module definitions like file exports,
name and version. Essentially the deno.json file mimicks
package.json file.

Set Option to version 0.7.0 in deno.json.

Fix "slow types" in Result

This is in preparation to release to jsr.io.

Slow types are essentially return types that are inferred in the type
signature instead of defined explicitly.

For more information: https://jsr.io/docs/about-slow-types

Fix "slow types" in Option

This is in preparation to release to jsr.io.

Slow types are essentially return types that are inferred in the type
signature instead of defined explicitly.

For more information: https://jsr.io/docs/about-slow-types

Update fp-utils logo

Full Changelog: 0.5.0...0.6.0

This release has some type inference fixes and also comment stripping from the output distribution for npm package bundle. The distribution is now around 70% smaller.

Fix type inference for match and flatMap in Option

Previously match was strict of it's return type and forced the caller to return the same return type in both callbacks onSome and onNone. This changes the match function to allow a more loose type to be returned. Both callbacks are now isolated from their return type (U1, U2).

FlatMap type inference could fail to provide a proper type. More explicit overload for the flatMap allows for better type inference.

Fix type inference for match and flatMap in Result

Previously match was strict of it's return type and forced the caller to return the same return type in both callbacks onOk and onErr. This changes the match function to allow a more loose type to be returned. Both callbacks are now isolated from their return type (U1, U2).

FlatMap type inference could fail to provide a proper type. More explicit overload for the flatMap allows for better type inference. This
type inference problem was prominent when one would return Ok | Ok | Err union from a function as the return type, which, previously would just fail to a type inference problem.

Unwrap did not work properly due to Err unwrap returning never type. This was fixed with a type magic by making the unwrap generic, but forcing it to be inhereted from the original T type.

Remove comments from transpiled js files

This makes the runtime file size considerably smaller (around ~70%) and will still work with typescript as expected as the comments are also present in the typings file.

Separate README and LICENSE copy into distinct functions.

Change the order of arguments in Option match function

onSome callback is now the first argument given to match function. This now follows the same pattern as the Result match function.

Add books example for Result type

This is the same example as the one for Option, but using Result type instead.

Full Changelog: 0.4.0...0.5.0

Export Result as a namespace

Result utility type is now exported within a namespace for improved
clarity and convenience. This ensures intuitive usage and better
integration with tools like Deno and TypeScript language servers. For
example, the Result namespace can now be automatically imported with the
language server.

Previous approach:

To achieve the desired code style, a wildcard import was commonly used,
although not mandatory or enforced by the language.

import * as Result from "../result/mod.ts"

The type was explicit and could be verbose and confusing at times.

function returnsResult(): Result.Type<number, string> { ... }

Partial import of the result context was also possible, potentially
leading to confusing scenarios. Once again, importing with a wildcard to
create a namespace was not enforced by the language.

import { unwrap } from "../result/mod.ts"

New solution:

Import is now performed using a named import, and renaming requires
explicit declaration. The complete result context is contained within
and maintains the expected behavior and appearance.

import { Result } from "../result/mod.ts"

The Result type is merged with the namespace for more concise and clear
usage.

function returnsResult(): Result<number, string> { ... }

Importing part of the Result utility type is not allowed, enforcing the
use of the Result namespace.

import { unwrap } from "../result/mod.ts" // Error

import { Result } from "../result/mod.ts"
Result.unwrap // Ok

Export Option as a namespace

Option utility type is now exported within a namespace for improved
clarity and convenience. This ensures intuitive usage and better
integration with tools like Deno and TypeScript language servers. For
example the Option namespace can now be automatically imported with the
language server.

Previous approach:

To get the expected style of the code, wildcard import was expected.
This however is not mandatory or enforced by the language.

import * as Option from "../option/mod.ts"

Type was an explicit type and a bit verbose and confusing at times.

function returnsOption(): Option.Type<number> { ... }

One could just import the option context partly, which in my opinion
could create very confusing and unclear scenarios. Again importing with
wildcard to have a namespace is not enforced by the language.

import { unwrap } from "../option/mod.ts"

New solution:

Import is done by using a named import. Renaming this needs explicit
declaration. The complete option context is contained within and holds
the expected behaviour and look.

import { Option } from "../option/mod.ts"

Option type is merged with the namespace for more concise and clear
usage. No need to use the verbose Option.Type export.

function returnsOption(): Option<number> { ... }

Importing part of the option utility type is not allowed, enforcing the
use of the Option namespace.

import { unwrap } from "../option/mod.ts" // Error

import { Option } from "../option/mod.ts"
Option.unwrap // Ok

Add first benchmarks for Option and Result types

The benchmarks are done against the examples with fetch and json parse.
Keep in mind that this is only preliminary benchmarks to have an idea of
the performance hit or gain when using this library. The option and
result benchmarks are run against the native implementations (without
the library functions).

The historic data can be used to measure if performance has improved or
degraded while making changes to the code.

Improve result parse json example

Now readers can directly compare the native and result examples in the
same file. Also added assertions so this example could be included to
test suites.

Make fetch examples more concise by introducing common module

Common functionality for the option and result fetch examples is now
imported from a common file path called examples/fetch_common.ts. This
makes the example less noisy and more concise.

Fix deprecation warning for actions/checkout action

Node.js 16 actions are deprecated.
This warning also occurs for the denoland action, but it's going to be
fixed in the next version 1.14. so should be fine. More info:
denoland/setup-deno#55

Change the order of arguments in match function

Breaking: onOk callback is now the first argument given to match
function. This change was done since usually we want to check the happy
path first and not the other way around.

Add void type for Result.ok and Result.err

Type void can be in 8000 terpreted to have the same significance as the
unit type. Unit type signifies the absence of a specific value and acts
as a placeholder when no other value exits or is needed.

This satisfies a situation when for example the caller wants to just
determine that the call was succesful without returning any value in the
Result. Result.ok() returns Ok Unit, that can be used with further
processing like the match function.

Make result error type name more verbose

Previously E was used to signify an error type in the generic type
scope. This however wasn't clear enough at times. Changed to TError to
signify the error type.

Also some function signatures were still using Type as the returning
type. This caused undesired effect of getting Result.Type instead of
plain Result in the caller type signatures. Now all exported function
signatures are using the type alias Result to make the type signature
more concise and easier to reason with.

Add result fetch example

Result fetch mimicks the option_fetch example, but using the Result type
instead of Option type for the comparison.

The existing examples were also renamed for consistency and display the
intent of the example better.

Return Err instead of Ok undefined with fromPromise

Previously if a resolved promise would contain nullable value it would
have been set as the contained value for the Ok type, but instead should
have been returned as the Err type.

Adds nullable checks to Result.fromPromise function and now returns Err
if the resolved promise has a nullable value.

Add `fromPromise` function for Option and Result modules

fromPromise function converts a promise or a function that returns an option or a result wrapped inside a Promise. fromPromise handles rejection by return either none for option and onReject for result.

Option.fromPromise(Promise.reject()); // Evaluates to None
Option.fromPromise(Promise.resolve(42)); // Evaluates to Some 42

Result.fromPromise(Promise.reject(), "Rejected"); // Evaluates to Err "Rejected"
Result.fromPromise(Promise.resolve(42), "Rejected"); // Evaluates to Ok 42

Make `unwrapOr` default value use contained type `T`

Previously the unwrapOr would take a generic U as the type for the default value. This was a bit inconsistent since one could return a
different type than what is contained inside Option or Result.

To make this more consistent the unwrapOr now forces the caller to pass a value that is the same type as the contained value T. When the type is known as None or Err the returned defaultValue U type is inferred and returned.

Result encapsulates two possible values: a successful result Ok or an error Err. Result allows to chain together a series of operations that can potentially fail and propagate the error through the computations. This enables to write code that is more focused on the 'happy path' and separate the error handling logic in a clean and concise way.

Result is similar to Option, the main difference is that it holds either a value or an error, and not value or none.

The following functions are provided by the option type:

Result.flatMap - Applies a function fn to the content of a result T and transforms it into a result containing value U.

Result.inspect - Calls the provided function fn with a reference to the contained result value T if the result is ok.

Result.inspectErr - Calls the provided function fn with a reference to the contained result error value E if the result is err.

Result.map - Applies a function fn to result value T and transforms it into value U.

Result.mapErr - Applies a function fn to result error value E and transforms it into value F.

Result.match - Transforms the result value T into U using onOk and then returns U. If the result is Err, the error value E is transformed to U with onErr and then returns U.

Result.unwrap - Returns the value T from the associated result if it is Ok; otherwise it will throw.

Result.unwrapErr - Returns the value E from the associated result if it is Err; otherwise it will throw.

Result.unwrapOr - Returns the value T from the associated result or returns the default value U if the result is Err.

Result.isOk - Returns true if the result is Ok.

Result.isErr - Returns true if the result is Err.

Option.inspect calls the provided function fn with a reference to the contained option value T if the option is some. Inspect is especially useful when there is a a need to print the value and then pass it forward, it essentially removes boilerplate like this:

Option.some(42)
  .map((num) => {
    console.log(num);
    return num;
  });

and instead you can write code like this:

Option.some(42)
  .inspect(console.log);

Add Option utility type

Option represents the presence of a value Some or the absence of a
value None. It's commonly utilized to manage computations that might
or might not yield a result, or those that could potentially fail.

The following functions are provided by the option type:

Option.bind - Applies a function fn to the content of option T and transforms
it into an option U.

Option.map - Applies a function fn to option value T and transforms it into
value U.

Option.match - Transforms the option value T into U using onSome and then
returns U. If the option is None, it uses onNone and returns U.

Option.unwrap - Returns the value T from the associated option if it is Some;
otherwise it will throw.

Option.unwrapOr - Returns the value T from the associated option or returns the
default value U if the option is None.

Option.isSome - Returns true if the option is Some

Option.isNone - Returns true if the option is None

Releases: erikjuhani/fp-utils

0.8.0

BREAKING CHANGES

Uh oh!

0.7.0

Uh oh!

0.6.0

Uh oh!

0.5.0

Uh oh!

v0.4.0

Add fromPromise function for Option and Result modules

Make unwrapOr default value use contained type T

Uh oh!

Add `Result` utility type

Uh oh!

Add `Option.inspect`

Uh oh!

v0.1.0

Uh oh!

Add `fromPromise` function for Option and Result modules

Make `unwrapOr` default value use contained type `T`