hoard.js

A JavaScript client for Team4159's shop inventory management project.

Installation

In a browser:

<script src="hoard.js"></script>

Using npm:

npm i @team4159/hoard.js --save

Usage

const myHoard = new Hoard("My Hoard Name");

const pencil = { 
    name: 'Pencil', 
    category: 'Writing', 
    amount: 1
}

// Adds a 'Pencil' to the hoard named 'My Hoard Name', then logs it
myHoard.addItem(pencil)
    .then(console.log);

// Logs all Items in the hoard name 'My Hoard Name'
myHoard.getAllItems()
    .then(console.log);

API

Item

Hoard is centered around Item objects with the following schema:

{
    // Name of the item (i.e. Hacksaw)
    name: string,
    // Category the item belongs to (i.e. Saws)
    category: string,
    // Amount of the item in inventory
    amount: number,
    
    // Optional image url
    imageUrl?: string,
    // Optional description
    description?: string,
    
    // Name of the hoard the item belongs to, assigned by the client
    hoardName?: string,
    // Unique MongoDB ObjectID assigned by the server, can be used for calculating the timestamp of the creation of the item
    _id?: string
}

Methods

Synchronous

You should avoid using synchronous methods. They can cause your apps to freeze and your browser to crash. However, on smaller scales, it should be fine to use synchronous methods. Synchronous methods avoid using Promises by instead blocking until the server responds.

The synchronous API is the same as the asynchronous API (see below). Simply append 'Sync' to any asynchronous method to use the equivalent synchronous method. For example:

const data = item.getItemsByCategorySync('Measurement');

// Logs all items in category 'Measurement'
console.log(data);

Asynchronous

The hoard.js client returns asynchronous Promises that are resolved to Items or arrays of Items.

// Adds an Item, resolves to the added Item
hoard.addItem(item);

// Gets all Items, resolves to an array of Items 
hoard.getAllItems();

// Gets a specific item by name, resolves to the specified Item
hoard.getItemByName(item_name);

// Gets a specific item by its MongoDB ObjectID, resolves to the specified Item
hoard.getItemByID(item_id);

// Gets all Items in a certain category, resolves to an array of Items in the category
hoard.getItemsByCategory(category);

// Find an Item by its name and update it, resolves to the updated Item.
hoard.updateItemByName(item_name, updated_item);

// The updated item can be a partial Item object. For example, if you wanted to change the amount of an Item, you would call:
hoard.updateItemByName('Pencil', { amount: 7 });

// Find an Item by its MongoDB ObjectID and update it, resolves to the updated Item.
hoard.updateItemByID(item_id, updated_item);

// Delete an Item by its name, resolves to the deleted Item
hoard.deleteItemByName(item_name);

// Delete an Item by its MongoDB ObjectID, resolves to the deleted Item
hoard.deleteItemByID(item_id);

To use asynchronous methods, employ the .then method. For example, if one wanted to log all 'Power Tools' that were in inventory:

hoard.getItemsByCategory('Power Tools')
    .then(function(data) {
        console.log(data);
    });

The above is equivalent to this:

hoard.getItemsByCategory('Power Tools')
    .then(console.log)