├── .gitignore
├── LICENSE
├── Readme.md
├── atom-browser.js
├── atom.js
├── buster.js
├── package.json
└── test
    └── atom-test.js


/.gitignore:
--------------------------------------------------------------------------------
1 | /node_modules/
2 | 


--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
 1 | Copyright (c) 2014
 2 | Christian Johansen
 3 | All rights reserved.
 4 | 
 5 | Redistribution and use in source and binary forms, with or without
 6 | modification, are permitted provided that the following conditions are met:
 7 | 
 8 |     Redistributions of source code must retain the above copyright notice,
 9 |     this list of conditions and the following disclaimer.
10 | 
11 |     Redistributions in binary form must reproduce the above copyright
12 |     notice, this list of conditions and the following disclaimer in the
13 |     documentation and/or other materials provided with the distribution.
14 | 
15 | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
16 | AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
17 | IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
18 | ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
19 | LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
20 | CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
21 | SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
22 | INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
23 | CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
24 | ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
25 | POSSIBILITY OF SUCH DAMAGE.
26 | 


--------------------------------------------------------------------------------
/Readme.md:
--------------------------------------------------------------------------------
  1 | # js-atom
  2 | 
  3 | Clojure(Script) atoms in plain JavaScript.
  4 | 
  5 | ## Why?
  6 | 
  7 | Immutable values require some sort of external state management in order for
  8 | your app to change state. One option is to use variables in scope to hold the
  9 | current state of your app:
 10 | 
 11 | ```js
 12 | function startApp(root) {
 13 |     var data;
 14 | 
 15 |     function render() {
 16 |         React.renderComponent(AppUI(data), root);
 17 |     }
 18 | 
 19 |     pollForData(function (newData) {
 20 |         data = newData;
 21 |         render();
 22 |     });
 23 | 
 24 |     // ...
 25 | }
 26 | ```
 27 | 
 28 | This sort of works, but quickly becomes unwieldy. Atoms offer a formal mechanism
 29 | for maintaining a single mutable reference. An atom is used to hold the current
 30 | state. It offers a small API for changing (or replacing) this state, subscribing
 31 | to changes, and for validating state changes.
 32 | 
 33 | ```js
 34 | function startApp(root) {
 35 |     var state = atom.createAtom({});
 36 | 
 37 |     function render() {
 38 |         React.renderComponent(AppUI(state.deref()), root);
 39 |     }
 40 | 
 41 |     // Render when the state changes
 42 |     state.addWatch("poll-update", render);
 43 | 
 44 |     pollForNewData(function (newData) {
 45 |         state.replace(newData);
 46 |     });
 47 | 
 48 |     // ...
 49 | }
 50 | ```
 51 | 
 52 | ## Immutability
 53 | 
 54 | Atoms are most useful when containing immutable values, but there's nothing
 55 | stopping you from sticking whatever you want in them. If you put a mutable value
 56 | in the atom, you either have to make sure you don't actually mutate it, or lose
 57 | some of the benefits (e.g. being able to trust past versions of the state).
 58 | 
 59 | ## API
 60 | 
 61 | The API is designed to mirror Clojure's atoms as closely as possible. Because
 62 | atoms are references, and not values, I didn't see any problems with defining
 63 | the API as methods on the atom object.
 64 | 
 65 | #### `createAtom(val[, options])`
 66 | 
 67 | Creates a new atom wrapping the provided value. `options` is optional, and
 68 | currently only supports one option: `validator`:
 69 | 
 70 | ```js
 71 | var createAtom = require("js-atom");
 72 | var atom = createAtom([], { validator: Array.isArray });
 73 | 
 74 | atom.replace([1, 2, 3]); // OK
 75 | atom.replace({}); // Throws exception
 76 | ```
 77 | 
 78 | #### `atom.deref()`
 79 | 
 80 | Returns the contained value.
 81 | 
 82 | #### `atom.reset(val)`
 83 | 
 84 | Replace the current state with a new value
 85 | 
 86 | #### `atom.swap(fn[, ...])`
 87 | 
 88 | Update the state by applying the function to the current value, and setting the
 89 | return value as the new value of the atom. Any additional arguments are passed
 90 | to the function as well, after the atom value, e.g.: `atom.swap(fn, 1, 2, 3)`
 91 | will replace the current value with what is returned from
 92 | `fn(atomValue, 1, 2, 3)`.
 93 | 
 94 | #### `atom.addWatch(key, function (key, ref, old, new) {})`
 95 | 
 96 | Add a function that will be called whenever the atom value changes. The key is
 97 | just a string identifying this watcher - it can be used to remove the watcher
 98 | again. The callback is called with four arguments whenever the state changes
 99 | (e.g. with `reset` or `swap`):
100 | 
101 | - `key` - The key used to register the watcher
102 | - `ref` - The atom reference
103 | - `old` - The previous value
104 | - `new` - The new value
105 | 
106 | #### `removeWatch(key)`
107 | 
108 | Removes the previously added watcher.
109 | 
110 | #### `toString`
111 | 
112 | Prints a useful string representation of the contents of the atom.
113 | 
114 | ## License
115 | 
116 | Copyright © 2014, Christian Johansen. js-atom uses semantic versioning. Code
117 | released under the BSD license. Documentation released under CC
118 | Attribution-Share Alike.
119 | 


--------------------------------------------------------------------------------
/atom-browser.js:
--------------------------------------------------------------------------------
 1 | !function(e){if("object"==typeof exports&&"undefined"!=typeof module)module.exports=e();else if("function"==typeof define&&define.amd)define([],e);else{var f;"undefined"!=typeof window?f=window:"undefined"!=typeof global?f=global:"undefined"!=typeof self&&(f=self),f.atom=e()}}(function(){var define,module,exports;return (function e(t,n,r){function s(o,u){if(!n[o]){if(!t[o]){var a=typeof require=="function"&&require;if(!u&&a)return a(o,!0);if(i)return i(o,!0);var f=new Error("Cannot find module '"+o+"'");throw f.code="MODULE_NOT_FOUND",f}var l=n[o]={exports:{}};t[o][0].call(l.exports,function(e){var n=t[o][1][e];return s(n?n:e)},l,l.exports,e,t,n,r)}return n[o].exports}var i=typeof require=="function"&&require;for(var o=0;o<r.length;o++)s(r[o]);return s})({1:[function(require,module,exports){
 2 | /*global exports*/
 3 | 
 4 | exports.createAtom = function createAtom(val, options) {
 5 |     var watchers = {};
 6 |     var validator = options && options.validator || function () { return true; };
 7 | 
 8 |     function transition(next) {
 9 |         if (!validator(next)) {
10 |             var err = new Error(next + " failed validation");
11 |             err.name = "AssertionError";
12 |             throw err;
13 |         }
14 | 
15 |         var prev = val;
16 |         val = next;
17 | 
18 |         Object.keys(watchers).forEach(function (k) {
19 |             watchers[k](k, atom, prev, next);
20 |         });
21 |     }
22 | 
23 |     var atom = {
24 |         addWatch: function (key, fn) {
25 |             watchers[key] = fn;
26 |         },
27 | 
28 |         removeWatch: function (key) {
29 |             delete watchers[key];
30 |         },
31 | 
32 |         swap: function (fn) {
33 |             var args = [val].concat([].slice.call(arguments, 1));
34 |             transition(fn.apply(null, args));
35 |         },
36 | 
37 |         reset: function (v) {
38 |             transition(v);
39 |         },
40 | 
41 |         deref: function () {
42 |             return val;
43 |         },
44 | 
45 |         toString: function () {
46 |             return "Atom(" + JSON.stringify(val) + ")";
47 |         }
48 |     };
49 | 
50 |     return atom;
51 | };
52 | 
53 | },{}]},{},[1])(1)
54 | });


--------------------------------------------------------------------------------
/atom.js:
--------------------------------------------------------------------------------
 1 | /*global exports*/
 2 | 
 3 | exports.createAtom = function createAtom(val, options) {
 4 |     var watchers = {};
 5 |     var validator = options && options.validator || function () { return true; };
 6 | 
 7 |     function transition(next) {
 8 |         if (!validator(next)) {
 9 |             var err = new Error(next + " failed validation");
10 |             err.name = "AssertionError";
11 |             throw err;
12 |         }
13 | 
14 |         var prev = val;
15 |         val = next;
16 | 
17 |         Object.keys(watchers).forEach(function (k) {
18 |             watchers[k](k, atom, prev, next);
19 |         });
20 |     }
21 | 
22 |     var atom = {
23 |         addWatch: function (key, fn) {
24 |             watchers[key] = fn;
25 |         },
26 | 
27 |         removeWatch: function (key) {
28 |             delete watchers[key];
29 |         },
30 | 
31 |         swap: function (fn) {
32 |             var args = [val].concat([].slice.call(arguments, 1));
33 |             transition(fn.apply(null, args));
34 |         },
35 | 
36 |         reset: function (v) {
37 |             transition(v);
38 |         },
39 | 
40 |         deref: function () {
41 |             return val;
42 |         },
43 | 
44 |         toString: function () {
45 |             return "Atom(" + JSON.stringify(val) + ")";
46 |         }
47 |     };
48 | 
49 |     return atom;
50 | };
51 | 


--------------------------------------------------------------------------------
/buster.js:
--------------------------------------------------------------------------------
1 | exports.node = {
2 |     environment: "node",
3 |     tests: ["test/**/*.js"]
4 | };


--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
 1 | {
 2 |   "name": "js-atom",
 3 |   "description": "JavaScript implementation of ClojureScript's atoms",
 4 |   "version": "0.4.0",
 5 |   "main": "atom.js",
 6 |   "devDependencies": {
 7 |     "browserify": "^6.1.0",
 8 |     "buster": "~0.7"
 9 |   },
10 |   "scripts": {
11 |     "bundle": "browserify -s atom -o atom-browser.js atom.js"
12 |   }
13 | }
14 | 


--------------------------------------------------------------------------------
/test/atom-test.js:
--------------------------------------------------------------------------------
 1 | var buster = require("buster");
 2 | var assert = buster.assert;
 3 | var refute = buster.refute;
 4 | var createAtom = require("../atom").createAtom;
 5 | 
 6 | function concat(coll, i) {
 7 |     return coll.concat([i]);
 8 | }
 9 | 
10 | buster.testCase("Atom", {
11 |     "derefs value": function () {
12 |         var val = {};
13 |         var atom = createAtom(val);
14 | 
15 |         assert.same(atom.deref(), val);
16 |     },
17 | 
18 |     "resets value": function () {
19 |         var orig = {};
20 |         var atom = createAtom(orig);
21 |         var val = {};
22 |         atom.reset(val);
23 | 
24 |         refute.same(atom.deref(), orig);
25 |         assert.same(atom.deref(), val);
26 |     },
27 | 
28 |     "swaps value": function () {
29 |         var atom = createAtom([]);
30 |         atom.swap(concat, 2);
31 | 
32 |         assert.equals(atom.deref(), [2]);
33 |     },
34 | 
35 |     "reveals contents when stringified": function () {
36 |         var atom = createAtom([2, 3, 4]);
37 | 
38 |         assert.equals(atom.toString(), "Atom([2,3,4])");
39 |     },
40 | 
41 |     "validates state changes": function () {
42 |         var atom = createAtom([], { validator: Array.isArray });
43 | 
44 |         assert.exception(function () { atom.reset({}); });
45 |         assert.equals(atom.deref(), []);
46 | 
47 |         atom.reset([2]);
48 |         assert.equals(atom.deref(), [2]);
49 |     },
50 | 
51 |     "always passes validation without validator": function () {
52 |         var atom = createAtom([]);
53 | 
54 |         refute.exception(function () { atom.reset(null); });
55 |     },
56 | 
57 |     "notifies watchers": function () {
58 |         var atom = createAtom([]);
59 |         var george = this.spy();
60 |         atom.addWatch("curious george", george);
61 |         var gina = this.spy();
62 |         atom.addWatch("curious gina", gina);
63 | 
64 |         atom.swap(concat, 2);
65 |         atom.reset([1, 3]);
66 | 
67 |         assert.calledTwice(george);
68 |         assert.calledTwice(gina);
69 |         assert.calledWith(gina, "curious gina", atom, [], [2]);
70 |         assert.calledWith(gina, "curious gina", atom, [2], [1, 3]);
71 |     }
72 | });
73 | 


--------------------------------------------------------------------------------