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
; var address = ;var newAddress = address; addresscity// => Londonaddresscity// => 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.
; var bread = ; var tomorrowsBread = bread; var freshBread = bread; breaddaysFresh// => 1tomorrowsBreaddaysFresh// => 0freshBreaddaysFresh// => 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// => truebread// ! 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// ["name", "daysFresh"] bread instanceof Struct;// => true // Works with or without new Keywordvar ryeBread = name: "ryeBread" daysFresh: 1;
OpenStruct
OpenStruct implements exactly the same behaviour as the Struct except new properties may be added.
; var kermit = Mapname: "Kermit" occupation: "Muppet" age: 15; var kermitFound = kermit; kermitFoundaddress;// => "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; { if !this instanceof Vector return VECTOR_DEFAULTS raw; return Struct;} Vectorprototype = Object;Vectorprototypeconstructor = 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.
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
{ "use strict"; if !this instanceof Struct return defaults source; Object; for var key in source if source if !this throw key; thiskey = sourcekey; Object;}macro struct rule $name ... { if !this instanceof $name return raw; return Struct } $nameprototype = Object; $nameprototypeconstructor = $name; struct Vector x: 0 y: 0v = ;console
[editable version](http://sweetjs.org/browser/editor.html#function%20Struct(defaults,%20source)%7B%0A%20%20%22use%20strict%22;%0A%20%20if%20(%20!(this%20instanceof%20Struct)%20)%20%7B%20return%20new%20Struct(defaults,%20source);%20%7D%0A%0A%20%20Object.assign(this,%20defaults);%0A%20%20for%20(var%20key%20in%20source)%20%7B%0A%20%20%20%20if%20(source.hasOwnProperty(key))%20%7B%0A%20%20%20%20%20%20if%20(!this.hasOwnProperty(key))%20%7B%0A%20%20%20%20%20%20%20%20throw%20new%20KeyError(key);%0A%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20this%5Bkey%5D%20=%20source%5Bkey%5D;%0A%20%20%20%20%7D%0A%20%20%7D%0A%20%20Object.freeze(this);%0A%7D%0Amacro%20struct%20%7B%0A%20%20%20%20rule%20%7B%0A%20%20%20%20%20%20%20%20$name%20%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20$($property%20$%5B:%5D%20$value)%20(,)%20...%0A%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%7D%20=%3E%20%7B%0A%20%20%20%20%20%20%20%20function%20$name(raw)%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20if%20(%20!(this%20instanceof%20$name)%20)%20%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20return%20new%20$name(raw);%0A%20%20%20%20%20%20%20%20%20%20%20%20%7D%0A%0A%20%20%20%20%20%20%20%20%20%20%20%20return%20Struct.call(this,%20%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20$($property%20$%5B:%5D%20$value)%20(,)%20...%0A%20%20%20%20%20%20%20%20%20%20%20%20%7D,%20raw)%0A%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%20%20%0A%20%20%20%20%20%20%20%20$name.prototype%20=%20Object.create(Struct.prototype);%0A%20%20%20%20%20%20%20%20$name.prototype.constructor%20=%20$name;%0A%20%20%20%20%7D%0A%20%20%20%20%0A%7D%0A%0Astruct%20Vector%20%7B%0A%20%20%20%20x:%200,%0A%20%20%20%20y:%200%0A%7D%0Av%20=%20Vector(%7Bt:%205%7D);%0Aconsole.log(v)%0A)