Options
All
  • Public
  • Public/Protected
  • All
Menu

funfix-core

Sub-project of Funfix, exposing primitive interfaces and data types that need to be universally available, belonging into a standard library.

Contents

Included are data types for expressing disjunctions:

Either data type for expressing results with two possible outcome types (a disjoint union)
Option data type for expressing optional values
Try data type for representing the result of computations that may result in either success or failure

Standard interfaces and tools for dealing with universal equality and hash code generation:

IEquals an interface for defining universal equality and hash code
is and equals for using IEquals in tests, or otherwise falls back to JavaScript's equality (== or valueOf())
hashCode for calculating hash codes (for usage in sets and maps data structures) using IEquals, or otherwise falls back to calculating a hash from .valueOf() or from .toString()
isValueObject for testing if a given object implements IEquals

Also exposes standard, reusable error types, that help with some common scenarios, working with error types being preferable to working with strings:

DummyError for tagging errors used for testing purposes
IllegalArgumentError for signaling that a given argument is violating the contract of the called function or constructor
IllegalInheritanceError for signaling that inheriting from a certain class is illegal
IllegalStateError for signaling that an illegal code branch was executed and thus something is wrong with the code and needs investigation (e.g. a bug)
NoSuchElementError thrown when the user expects an element to be returned from a function call, but no such element exists
NotImplementedError thrown in case an implementation is missing
TimeoutError thrown in case the execution of a procedure takes longer than expected
CompositeError for gathering multiple errors in a single reference that can expose them as a list

Misc utilities:

applyMixins for working with mixins (i.e. classes used as interfaces, with methods that have default implementations), see Mixins for an explanation
id is the "identity" function

Usage

You can depend on the whole funfix library, by adding it to package.json:

npm install --save funfix

In this case imports are like:

import { Option } from "funfix"

Or for finer grained dependency management, the project can depend only on funfix-core:

npm install --save funfix-core

In this case imports are like:

import { Option } from "funfix-core"

Usage sample:

import { Try, Option, Either } from "funfix"

const opt1 = Option.of("hello")
const opt2 = Try.of(() => "world").toOption()

const greeting =
  Option.map2(opt1, opt2, (a, b) => a + " " + b)

console.log(greeting.getOrElse("Ooops!"))

Modules: UMD and ES 2015

The library has been compiled using UMD (Universal Module Definition), so it should work with CommonJS and AMD.

But it also provides a module definition in package.json, thus providing compatibility with ECMAScript 2015 modules, for usage when used with a modern JS engine, or when bundling with a tool chain that understands ES2015 modules, like Rollup or Webpack.

Index

Type aliases

Constructor

Constructor: object | object

Given a type T representing instances of a class C, the type Constructor<T> is the type of the class C.

This type emulates Class from Flow.

Note that in TypeScript constructors can also be protected or private and unfortunately specifying { new(): T } is thus insufficient. Which is why, for classes without a public constructor, we have to specify a _funErasure (static) member as a property, to help the compiler infer type T.

Example:

class NumBox { constructor(public num: number) {} }
class GenBox<A> { constructor(public a: A) {} }

function getDefault<F>(ref: Constructor<F>): Option<F> {
  if ((ref as any)._default) return Some(ref._default)
  return None
}

(NumBox as any)._default = new NumBox(10)
(GenBox as any)._default = new GenBox("value")

const r1: Option<NumBox> = getDefault(NumBox)
const r2: Option<GenBox<any>> = getDefault(GenBox)

And for classes with a private constructor:

class PrivateBox<A> {
  private constructor(public a: A) {}

  static _funErasure: PrivateBox<any> // leaving undefined
}

const F = PrivateBox as any
F._default = new F("hello")

const r: Option<PrivateBox<any>> = getDefault(NumBox)

EitherTypes

EitherTypes: Setoid<Either<any, any>> & Monad<"funfix/either">

Type enumerating the type-classes that Either implements.

OptionTypes

OptionTypes: Setoid<Option<any>> & Monad<"funfix/option">

Type enumerating the type classes implemented by Option.

Throwable

Throwable: Error | Object

Type alias for errors that can be thrown.

Since in JavaScript any object can be thrown, the standard Error class (capital E) is not useful as a type in signatures, the needed type being effectively any, but we still need a type alias for documentation purposes.

And since any represents an untyped object that bypasses the type system, Funfix is using Object for TypeScript and mixed for Flow to represent such throwables.

TryTypes

TryTypes: Setoid<Try<any>> & Monad<"funfix/try">

Type enumerating the type classes implemented by Try.

Variables

Const None

None: TNone = new (TNone as any)()

The None data constructor for Option represents non-existing values for any type.

Using this reference directly is equivalent with Option.none.

Functions

Failure

Left

  • Left<L>(value: L): TLeft<L>
  • The Left data constructor represents the left side of the Either disjoint union, as opposed to the Right side.

    Type parameters

    • L

    Parameters

    • value: L

    Returns TLeft<L>

Right

  • Right<R>(value: R): TRight<R>
  • The Right data constructor represents the right side of the Either disjoint union, as opposed to the Left side.

    Type parameters

    • R

    Parameters

    • value: R

    Returns TRight<R>

Some

  • Some<A>(value: A): TSome<A>
  • The Some<A> data constructor for Option represents existing values of type A.

    Using this function is equivalent with Option.some.

    Type parameters

    • A

    Parameters

    • value: A

    Returns TSome<A>

Success

  • Success<A>(value: A): Try<A>
  • The Success data constructor is for building Try values that are successful results of computations, as opposed to Failure.

    Type parameters

    • A

    Parameters

    • value: A

    Returns Try<A>

applyMixins

  • applyMixins(derivedCtor: object, baseCtors: object[]): void
  • Utility function for implementing mixins, based on the TypeScript Mixins documentation.

    Sample:

    class Disposable { ... }
    class Activatable { ... }
    class SmartObject implements Disposable, Activatable { ... }
    
    applyMixins(SmartObject, [Disposable, Activatable]);
    

    Using implements instead of extends for base classes will make the type system treat them like interfaces instead of classes. And by applyMixins we can also supply global implementations for the non-abstract members.

    Parameters

    • derivedCtor: object
      • prototype: any
    • baseCtors: object[]

    Returns void

convertToMethod

  • convertToMethod(f: Function): Function
  • Given a function, converts it into a method where this gets passed around as the last argument.

    Parameters

    • f: Function

    Returns Function

equals

  • equals<A>(lh: A, rh: A): boolean
  • Alias for is.

    Type parameters

    • A

    Parameters

    • lh: A
    • rh: A

    Returns boolean

hashCode

  • hashCode(ref: any): number
  • Universal hash-code function.

    Depending on the given value, it calculates the hash-code like so:

    1. if it's a number, then it gets truncated to an integer and returned
    2. if it's a "value object" (see isValueObject), then its hashCode is used
    3. if a valueOf() function is provided, then the hashCode gets recursively invoked on its result
    4. if all else fails, the value gets coerced to a String and a hash code is calculated using hashCodeOfString

    Parameters

    • ref: any

      is the value to use for calculating a hash code

    Returns number

    an integer with the aforementioned properties

hashCodeOfString

  • hashCodeOfString(str: string): number
  • Calculates a hash code out of any string.

    Parameters

    • str: string

    Returns number

id

  • id<A>(a: A): A
  • The identity function.

    Type parameters

    • A

    Parameters

    • a: A

    Returns A

is

  • is<A>(lh: A, rh: A): boolean
  • Tests for universal equality.

    First attempting a reference check with ===, after which it tries to fallback on IEquals, if the left-hand side is implementing it.

    equals(10, 10) // true, because 10 === 10
    
    class Box implements IEquals<Box> {
      constructor(value: number) { this.value = value }
    
      equals(other) { return this.value === other.value  }
      hashCode() { return this.value << 2 }
    }
    
    // false, because they are not the same reference
    new Box(10) === new Box(10)
    
    // true, because `Box#equals` gets called
    equals(new Box(10), new Box(10))
    

    Type parameters

    • A

    Parameters

    • lh: A
    • rh: A

    Returns boolean

isValueObject

  • isValueObject(ref: any): boolean
  • Test if the given reference is a value object.

    Value objects are objects that implement the IEquals interface.

    Parameters

    • ref: any

      is the reference to test

    Returns boolean

Object literals

Const EitherModule

EitherModule: object

Type-class implementations, compatible with the static-land and funland specifications.

See funland-js.org.

of

of: pure = Either.pure

ap

chain

  • chain<L, A, B>(f: function, fa: Either<L, A>): Either<L, B>

chainRec

  • chainRec<L, A, B>(f: function, a: A): Either<L, B>
  • Type parameters

    • L

    • A

    • B

    Parameters

    • f: function
        • <C>(next: function, done: function, a: A): Either<L, C>
        • Type parameters

          • C

          Parameters

          • next: function
              • (a: A): C
              • Parameters

                • a: A

                Returns C

          • done: function
              • (b: B): C
              • Parameters

                • b: B

                Returns C

          • a: A

          Returns Either<L, C>

    • a: A

    Returns Either<L, B>

equals

map

Const OptionModule

OptionModule: object

Type-class implementations, compatible with the static-land and funland specification.

See funland-js.org.

of

of: pure = Option.pure

ap

chain

chainRec

  • chainRec<A, B>(f: function, a: A): Option<B>
  • Type parameters

    • A

    • B

    Parameters

    • f: function
        • <C>(next: function, done: function, a: A): Option<C>
        • Type parameters

          • C

          Parameters

          • next: function
              • (a: A): C
              • Parameters

                • a: A

                Returns C

          • done: function
              • (b: B): C
              • Parameters

                • b: B

                Returns C

          • a: A

          Returns Option<C>

    • a: A

    Returns Option<B>

equals

map

Const TryModule

TryModule: object

Type-class implementations, compatible with the static-land and funland specifications.

See funland-js.org.

of

of: pure = Try.pure

ap

  • ap<A, B>(ff: Try<function>, fa: Try<A>): Try<B>

chain

  • chain<A, B>(f: function, fa: Try<A>): Try<B>

chainRec

  • chainRec<A, B>(f: function, a: A): Try<B>
  • Type parameters

    • A

    • B

    Parameters

    • f: function
        • <C>(next: function, done: function, a: A): Try<C>
        • Type parameters

          • C

          Parameters

          • next: function
              • (a: A): C
              • Parameters

                • a: A

                Returns C

          • done: function
              • (b: B): C
              • Parameters

                • b: B

                Returns C

          • a: A

          Returns Try<C>

    • a: A

    Returns Try<B>

equals

  • equals(x: Try<any>, y: Try<any>): boolean

map

  • map<A, B>(f: function, fa: Try<A>): Try<B>
  • Type parameters

    • A

    • B

    Parameters

    • f: function
        • (a: A): B
        • Parameters

          • a: A

          Returns B

    • fa: Try<A>

    Returns Try<B>

Const universalSetoid

universalSetoid: object

Returns a Setoid type-class instance that depends universal equality, as defined by is.

equals

equals: equals

Legend

  • Module
  • Object literal
  • Variable
  • Function
  • Function with type parameter
  • Index signature
  • Type alias
  • Enumeration
  • Enumeration member
  • Property
  • Method
  • Interface
  • Interface with type parameter
  • Constructor
  • Property
  • Method
  • Index signature
  • Class
  • Class with type parameter
  • Constructor
  • Property
  • Method
  • Accessor
  • Index signature
  • Inherited constructor
  • Inherited property
  • Inherited method
  • Inherited accessor
  • Protected property
  • Protected method
  • Protected accessor
  • Private property
  • Private method
  • Private accessor
  • Static property
  • Static method

Generated using TypeDoc