carbide v0.3.1
Carbide.js
Immutable Structs for reliable predictable JavaScript
A Struct is a complex data type that defines a group of variables.
Carbide contains two flavors of Struct: Struct
and OpenStruct
.
Example
import Struct from "carbide/struct";
var address = Struct({city: "London", country: "UK"});
var newAddress = address.set({city: "Liverpool"});
address.city
// => London
address.city
// => Liverpool
Carbide structs are designed to have a low overhead and to not fight against the dynamic nature of JavaScript. They do not provide guarantees but are "sufficiently" immutable. Sufficiently immutable objects have an immutable API. They do not prevent the developer from circumventing the API.
Installation
This package is available on npm.
$ npm install carbide
Usage
Carbide is built using ES6 modules. If you use a different setup such as a browser globals see steps below.
Struct
Structs are simple immutable objects. They contain properties which may be of any value. It is up to the developer to only pass immutable values to the constructor if they require an effective deep freeze.
All methods on a struct leave the struct unchanged.
import Struct from "carbide/struct";
var bread = Struct({name: "bread", daysFresh: 1});
var tomorrowsBread = bread.update("daysFresh", function(days){ return days - 1; });
var freshBread = bread.set("daysFresh", 3);
bread.daysFresh
// => 1
tomorrowsBread.daysFresh
// => 0
freshBread.daysFresh
// => 3
Structs can only have the properties that where assigned to them during construction. Attempting to set or fetch a key that does not exist with throw an error
bread.hasKey("name")
// => true
bread.fetch("starRating")
// ! throw KeyError key "starRating" not found
Structs encourage the use of techniques from functional programming, however they are JavaScript objects and can be treated as one
Object.keys(bread)
// ["name", "daysFresh"]
bread instanceof Struct;
// => true
// Works with or without new Keyword
var ryeBread = new Struct({name: "ryeBread", daysFresh: 1});
OpenStruct
OpenStruct implements exactly the same behaviour as the Struct except new properties may be added.
import OpenStruct from "carbide/open-struct";
var kermit = Map({name: "Kermit", occupation: "Muppet", age: 15});
var kermitFound = kermit.set("address", "Brazil");
kermitFound.address;
// => "Brazil"
Struct inheritance
Structs can be inherited from to create immutable custom immutable types.
For example here is a vector object.
var VECTOR_DEFAULTS = {x: 0, y: 0, z: 0};
function Vector(raw){
if ( !(this instanceof Vector) ) { return new Vector(VECTOR_DEFAULTS, raw); }
return Struct.call(this, VECTOR_DEFAULTS, raw);
}
Vector.prototype = Object.create(Struct.prototype);
Vector.prototype.constructor = Vector;
Build non-ES6 distributions
This library uses ES5 JavaScript with ES6 modules. To get started with ES6 modules today you can use Rollup which is an excellent tool. Rollup is a bundler for ES6 modules (Browserify for ES6 modules).
To build the releases change into the carbide directory.
$ cd path/to/carbide
Run the build script.
$ npm run build
There will be a build version that can now be used directly in the browser.
<script type="text/javascript" src="path/to/carbide/dist/carbide.es5.js"></script>
Contributing
- Fork it ( https://github.com/lotus/lotus/fork )
- Create your feature branch (
git checkout -b my-new-feature
) - Commit your changes (
git commit -am 'Add some feature'
) - Push to the branch (
git push origin my-new-feature
) - Run the tests
npm test
- Create a new Pull Request
We will release on using npm distribution tags before main versions. Described here
Macro example
An example to clean up the inheritance procedure. Can create macro with sweet.js
function Struct(defaults, source){
"use strict";
if ( !(this instanceof Struct) ) { return new Struct(defaults, source); }
Object.assign(this, defaults);
for (var key in source) {
if (source.hasOwnProperty(key)) {
if (!this.hasOwnProperty(key)) {
throw new KeyError(key);
}
this[key] = source[key];
}
}
Object.freeze(this);
}
macro struct {
rule {
$name {
$($property $[:] $value) (,) ...
}
} => {
function $name(raw){
if ( !(this instanceof $name) ) {
return new $name(raw);
}
return Struct.call(this, {
$($property $[:] $value) (,) ...
}, raw)
}
$name.prototype = Object.create(Struct.prototype);
$name.prototype.constructor = $name;
}
}
struct Vector {
x: 0,
y: 0
}
v = Vector({t: 5});
console.log(v)