Module Bs

module Bs: sig .. end
A stdlib shipped with BuckleScript

This stdlib is still in beta status, but we encourage you to try it out and provide feedback.

Motivation

The motivation of creating such library is to provide BuckleScript users a better end-to-end user experience, since the original OCaml stdlib was not writte with JS platform in mind, below are a list of areas this lib aims to improve:

  1. 1. Consistency in name convention: camlCase, and arguments order
  2. 2. Exception thrown functions are all suffixed with Exn, e.g, getExn
  3. 3. Beter peformance and smaller code size running on JS platform

Name Convention

For higher order functions, it will be suffixed U if it takes uncurried callback.

      val forEach : 'a t -> ('a -> unit) -> unit
      val forEachU : 'a t -> ('a -> unit [@bs]) -> unit
    

In general, uncurried version will be faster, but it is less familiar to people who have a background in functional programming.

A special encoding for collection safety

When we create a collection library for a custom data type, take Set for example, suppose its element type is a pair of ints, it needs a custom compare function. However, the Set could not just be typed as Set.t (int * int) , its customized compare function needs to be manifested in the signature, otherwise, if the user create another customized compare function, and the two collection would mix which would result in runtime error.

The original OCaml stdlib solved the problem using functor which is a big closure in runtime; it makes dead code elimination much harder. We introduced a phantom type to solve the problem

      type t = int * int 
      module I0 =
        (val Bs.Id.comparableU ~cmp:(fun[@bs] ((a0,a1) : t) ((b0,b1) : t) ->
             match compare a0 b0 with
             | 0 -> compare a1 b1
             | c -> c 
           ))
    let s0 = Bs.Set.make ~id:(module I0)
    module I1 =
      (val Bs.Id.comparableU ~cmp:(fun[@bs] ((a0,a1) : t) ((b0,b1) : t) ->
           match compare a1 b1 with
           | 0 -> compare a0 b0
           | c -> c 
         ))
    let s1 = Bs.Set.make ~id:(module I1)
    

Here the compiler would infer s0 and s1 having different type so that it would not mix.

      val s0 : ((int * int), I0.identity) t
      val s1 : ((int * int), I1.identity) t
    

I0.identity and I1.identity are not the same using our encoding scheme.

Collection Hierachy

In general, we provide a generic collection module, but also create specialized modules for commonly used data type, take Bs.Set for example

      Bs.Set
      Bs.Set.Int
      Bs.Set.String
    

The specialized module Bs.Set.Int, Bs.Set.String is in general more efficient.

Currently, both Bs_Set and Bs.Set are accessible to users for some technical rasons, we strongly recommend users stick to qualified import, Bs.Sort, we may hide the internal, i.e, Bs_Set in the future


module Id: Bs_Id
Bs.Id

Provide utiliites to create identified comparators or hashes for data structures used below.

It create a unique identifer per module of functions so that different data structures with slightly different comparison functions won't mix

module Array: Bs_Array
Bs.Array

mutable array: Utililites functions

module SortArray: Bs_SortArray
Bs.SortArray

The toplevel provides some generic sort related utililties.

It also has two specialized inner modules Bs.SortArray.Int and Bs.SortArray.String

module MutableQueue: Bs_MutableQueue
Bs.MutableQueue

An FIFO(first in first out) queue data structure

module MutableStack: Bs_MutableStack
Bs.MutableStack

An FILO(first in last out) stack data structure

module List: Bs_List
Bs.List

Utilities for List data type

module Range: Bs_Range
Bs.Range

Utilities for a closed range (from, start)

module Set: Bs_Set
Bs.Set

The toplevel provides generic immutable set operations.

It also has three specialized inner modules Bs.Set.Int and Bs.Set.String Bs.Set.Dict: This module separate date from function which is more verbbose but slightly more efficient

module Map: Bs_Map
Bs.Map,

The toplevel provides generic immutable map operations.

It also has three specialized inner modules Bs.Map.Int and Bs.Map.String Bs.Map.Dict: This module separate date from function which is more verbbose but slightly more efficient

module MutableSet: Bs_MutableSet
Bs.MutableSet

The toplevel provides generic mutable set operations.

It also has two specialized inner modules Bs.MutableSet.Int and Bs.MutableSet.String

module MutableMap: Bs_MutableMap
Bs.MutableMap

The toplevel provides generic mutable map operations.

It also has two specialized inner modules Bs.MutableMap.Int and Bs.MutableMap.String

module HashSet: Bs_HashSet
Bs.HashSet

The toplevel provides generic mutable hash set operations.

It also has two specialized inner modules Bs.HashSet.Int and Bs.HashSet.String

module HashMap: Bs_HashMap
Bs.HashMap

The toplevel provides generic mutable hash map operations.

It also has two specialized inner modules Bs.HashMap.Int and Bs.HashMap.String