In a few words, ironwingjs is a lightweight, framework-agnostic JavaScript library. ironginwjs is ment to be super easy to use and easy to integrate on any app. Out of the box it offers CRUD manipulation over a REST API interface.
It all started as a simple necessity on a private project. We needed an easy way to asimilate a RESTful API and manage the data on the client. We didn't want to use a framework at the time. We just wanted a simple library without extra dependencies to achieve this. So we started writting a small implementation of our own. It turned out to be exactly what we needed for the task at hand. So... why not open source it?
If you are still reading, this means that you are a tiny bit curious about what can ironwingjs bring to the table. Ironwingjs embraces some well known and used techniques like promises and it also implements some highly extensible concepts: adapters, storage and proxy objects. First of all, ironwingjs is an open-source library, no surprise there. It is fully written in vanilla javascript, which makes it framework agnostic. This means you can use it without any extra dependencies in your own app.
For communicating with the server's REST API, ironwing uses the XMLHttpRequest browser API. This object is used amoung other libraries like jQuery's $.ajax() or Angular's $http service.
$ npm install ironwing
# or
$ bower install ironwingYou can include ironwing directly in your HTML or if you are using browserify you can simply require it.
There are other similar libraries to ironwing like Backbone's Backbone.Model or Angular's has some community provided libraries like Restangular. However, these implementations depend on a dependency to work.
Like it was stated above, the core of ironwing is build around a few concepts:
An adapter is an object which follows a predefined interface so that it can be integrated with ironwing. Out of the box, ironwingjs comes with a XHR JSON adapter which is an intermediate object that communicates with the XMLHttpRequest API. The developer doesn't interact directly with the adapter. The adapter is used "under the hood" by ironwing. The main purpose of adapters is to easily modify how ironwing interacts with the server. Anyone can write their own adapter and use it with ironwingjs. To load an adapter you simply call the useAdapter method first.
import ironwing from 'ironwing';
ironwing.useAdapter('JSON', ['/api']);This tells ironwing to use the JSON adapter to interacte with the server for all future operations. For this example, the adapter needs to know the basepath for the API's endpoints.
By default, ironwing has a local (heap) storage. After ironwing fetches a new model, by default it stores it locally for later use. So for example if we were to fetch data from an endpoint called /users/100:
ironwing('users', 100).then((user) => {
console.log(user.attr.name);
});We can later on retrieve that model from memory without any extra trips to the server, by simply calling
var userModel = ironwing.storage.find('users', 100);Or, if we fetched a collection
ironwing('users',).then((users) => {
console.log(users.length);
});we can later on get one or all users type model
var usersCollection = ironwing.storage.findAll('users');For the moment, only the default storage can be used. In future releases we hope to implement a way to switch between storage implementations like an adapter for local storage so you can save the state of your models after refresh.
The constructor method ironwing() is basically a factory method which returns Model instances. Each model exposes CRUD methods for manipulating your data. However, ironwing never modifies the raw JSON data directly. It exposes a proxy object as an intermediate. Each model object has a .attr object which contains a camel cased transformation of the JSON response. Everything you edit on the attr proxy object, it will be later synced with the original raw response and sent to the back-end. This technique offers control over what gets edited and what doesn't. In future releases, with the help of the proxy object, some cool features can be added like validators on attributes.
A quick create and update example:
import ironwing from 'ironwing';
var userData = {
first_name: 'Jon',
last_name: 'Doe';
};
ironwing.useAdapter('JSON', ['/api']);
ironwing.create('users', userData).then((userModel) => {
/**
* a POST request is sent to the server
* /api/users
*/
userModel.attr.firstName = 'Jon';
userModel.attr.lastName = 'Doe';
userModel.update().then(() => {
/**
* a PUT request is sent to the server
* /api/users/:id
*/
});
});Ironwing is a simple library which you can hook up to an API and start using that data. We decided to share this library to the world in case it comes in handy to anyone. Because it is open source anyone can contribuite with new ideeas and features which they may like. Ironwing is a different way to tackle an everyday problems, it's meant to be easy to use and highly extensible.
Ironwing was originally developed for a product called Trubzi, which was developed by Evozon Systems in Cluj-Napoca. Evozon is a software outsourcing company founded in 2005 by Gabriel Cretu and Robert Masic, with clients on all continents. Evozon develops both on-demand applications, as well as its own products, including Trubzi, Calendis, Hoteliqo and frameworks used by developers worldwide, such as Essence and Crux.