Java Collections For JavaScript

This repository contains implementations of some commonly-used Java collections in JavaScript.

HashMap

Although JavaScript has a native Map object, key equality is determined by the sameValueZero algorithm, so objects with the exact same properties are not considered equal unless they are the same reference ({a: 1, b: 2} !== {a: 1, b: 2}). This cannot be customized. HashMap.js provides fine-grained control over what objects are considered equal, so both primitives and user-defined objects may be used as keys. It implements a Hash Table/Map with similar methods to Java's HashMap. All objects (except primitives) used as keys must implement a hashCode method to return an integer hash code as well as an equals method that accepts another object as a parameter and returns whether or not the value of the current object is equal to parameter. Objects that are considered equal must have the same hash code, but the converse is not true. Note that HashMap instances are iterable, so [...myHashMap] will return an array of arrays, where each inner array consists of the key and value for a mapping (in that order). An example of usage can be found here.

Usage

Include the script before code that uses HashMap. The script can be loaded via CDN or a local downloaded copy.

<script src="https://cdn.jsdelivr.net/npm/[email protected]"></script>
<!-- old version -->
<script src="https://cdn.jsdelivr.net/gh/LieutenantPeacock/[email protected]/src/HashMap.js" integrity="sha384-AD+fe06BloScT8iK5vgKw2FW3imLYjVLP6P9OS+zKpI8vIaNrBTKnQ4TCa4poj2F" crossorigin="anonymous"></script>

Or for Node.js, run npm i java-collections4js to install the package, then use it like so:

const { HashMap, HashSet } = require("java-collections4js");

// or with ECMAScript Module imports
import JavaCollections from "java-collections4js";
import HashMap from "java-collections4js/dist/HashMap.js";

Constructor

The constructor accepts an optional HashMap, which will copy the contents. Alternately, it will create an empty HashMap.

const myMap = new HashMap(); // create empty HashMap
const myMap2 = new HashMap(myMap); // create HashMap from other HashMap

Instance Methods

HashSet

Although JavaScript has a native Set object, elements are considered equal only if they are primitives with the same value or the same reference of an object. Thus, objects with the same properties and values can be duplicated many times. HashSet.js provides fine-grained control over what objects are considered equal, so both primitives and user-defined objects may be inserted with uniqueness guaranteed. It implements an unordered collection with unique elements. Similar to HashMap, each element (except primitives) stored in a HashSet must implement a hashCode and equals method. To use HashSet, HashMap must be included first. Note that HashSet instances are iterable, so [...myHashSet] will return an array containing the elements in the HashSet.

Usage

Include HashMap.js and HashSet.js before code that uses HashSet. The scripts can be loaded via CDN or local downloaded copies.

<script src="https://cdn.jsdelivr.net/gh/LieutenantPeacock/[email protected]/src/HashMap.js" integrity="sha384-AD+fe06BloScT8iK5vgKw2FW3imLYjVLP6P9OS+zKpI8vIaNrBTKnQ4TCa4poj2F" crossorigin="anonymous"></script>
<script src="https://cdn.jsdelivr.net/gh/LieutenantPeacock/[email protected]/src/HashSet.js" integrity="sha384-eEGZyLlAVNsmA+/PWbSLgZR1wO9z2AWkHyVtLzr1vCenlCZ2wb9wLxNKY7Ib5lK5" crossorigin="anonymous"></script>

Constructor

The constructor accepts an optional iterable object, all elements of which will be initially added to the HashSet. If the first parameter is not provided, it constructs an empty HashSet.

const mySet = new HashSet(); // creates empty HashSet
const mySet2 = new HashSet([1, 2, 3]); // creates a HashSet containing the elements of the array

Instance methods

ArrayList

ArrayList.js implements an dynamically-sized list with a hashCode and equals method. Note that ArrayList instances are iterable, so [...myArrayList] will return an array containing the elements in the ArrayList (in order).

Usage

Include the script before code that uses ArrayList. The script can be loaded via CDN or a local downloaded copy.

<script src="https://cdn.jsdelivr.net/gh/LieutenantPeacock/[email protected]/src/ArrayList.js" integrity="sha384-Uz+oGp/Q3Lfeq6ESB4bvbOAHw0hF1RjSBPHQqjpikrVrFjF6SDx6JMV9rI3mBBFr" crossorigin="anonymous"></script>

Constructor

The constructor accepts an optional iterable object to use to fill the list initially. If not specified, an empty ArrayList is constructed.

const myList = new ArrayList(); // creates an empty ArrayList
const myList2 = new ArrayList([1, 2, 3]); // creates an ArrayList containing the numbers 1, 2, 3

Instance Methods

Equals and HashCode for Objects You Cannot Modify

HashedObject.js provides a wrapper for an object that allows specifying an equals and hashCode function. This wrapped object can then be used as a key in a HashMap or stored in a HashSet.

Usage

Include the script before code that uses HashedObject. The script can be loaded via CDN or a local downloaded copy.

<script src="https://cdn.jsdelivr.net/gh/LieutenantPeacock/[email protected]/src/HashedObject.js" integrity="sha384-RBqyEB5bCB2ci4e3ZKiBp4W87K7LYay1qXMFO/9cUq7TndRlQKLSZ4/iFN1bMbRl" crossorigin="anonymous"></script>

Constructor

The constructor takes the object to wrap, the hash function, and the equals function as arguments. The equals function must take two objects as parameters and return a boolean indicating whether they are equal. If not equals function is specified, the default is strict equality comparison. The hashCode function must take one object as input and return its hash code.

let wrapped = new HashedObject(myObj, hashFn, equalsFn);

Instance Methods

Static Methods and Properties

There are some static methods and properties provided for convenience that implement common equals or hash code functions.