1300 git pushes and a year later…

… I’ve become fairly proficient at JavaScript and Node.js and just about all the work done in the last year is (a) 100% aligned with this effort (b) MIT-licensed on GitHub.

I came into 2013 with my first published Node.js package, onm. A data modeling tool I wrote for myself in 2012 to help me with a brain-crushing number of dimensions to juggle in the context of trying to build a CAD program inside an HTML 5 SPA.

It’s a case of knowing the use case well, so the tool felt natural. But to those unfamiliar with the use case, the tool is baffling. So lots of work to do yet to make it simple. And, explain more clearly why it’s so damn important.

That said, onm worked well for me and supported lengthy and deep multi-month dives on several important fronts in the war:


The major MV* frameworks just don’t feel right to me. Using onm’s in-memory JSON resource locator and model introspection, I adapted (read ripped the backside off) Facebook’s React framework and bolted their renderer to onm.

The basic idea is to allow the development of re-usable, render functions (data to client browser DOM effectively) that are completely decoupled from one another, but bound loosely via a semantic contract over JSON to some particular input object signature. This worked pretty well.

The client SPA is effectively a generic glue component and a library of render functions. Throw in some JSON, the algorithms sifts through the data, binds the requisite render functions and dispatches them. This solves a lot of problems but isn’t perfect.

The benefit is that a well-written render function can be re-used easily over and over and over in different scenarios, in different apps without having to do any hand-integration whatsoever. This is so because the render functions can be unit tested as can the assembly mechanism so composing them generally just works by superposition.

However, this exercise did expose onm’s weak belly: client data ingress/egress/transformation. I built onm to be a resource locator presuming client code would just reach in and CRUD the raw data. This was a rationalization: I can do that and you can too if you write a lot of tests and are careful. But that’s not how web developers roll generally.


  • resource location by URI everywhere = awesome
  • having to write you own data models all the time = not awesome
  • not supporting arrays in JSON = not awesome (but really a pain in the ass)
  • Everyone wants variants (i.e. addressable, typed, heterogeneous arrays and hash tables) = so noted, but very difficult, and can be safely staged after base features I rationalize.
  • Developers can’t be trusted with raw JSON off the wire. Ever. Not even you. It’s like running as root all the time. No. So there needs to be an API. And it has to be easy to use and understand. Damn. That’s hard. You guys have tried to read the RDF spec right? Yea.


jsgraph implements an in-memory container abstraction for directed mathematical graph data sets. Vertices in the container are represented by user-assigned unique string identifiers. Edges in the container are represented by pairs of vertex identifier strings. The container supports the the attachment of arbitrary application-specific meta-data to vertices and edges.

jsgraph’s bundled breadth-first, and depth-first visitor algorithms leverage the container API and an external state store (color table) to affect the desired traversal firing synchronous callbacks to your code at specific stages of the traversal.

jsgraph is inspired by the design of the Boost C++ Graph Library that leverages C++ templates to affect a complete separation of concerns between (a) data storage and access (read you can adapt your own data source as necessary) (b) data semantics (BYO semantics) (c) re-usable algorithms that rely on generic protocols for (a) and (b) and thus just work by superposition.


onm rewrite

In October 2014 I started back in on onm working on a set of features intended to make it simple to overlay data (i.e. ingress) JSON into onm. As I worked through the details and assessed onm’s deficiencies, a new plan formed.

Some high-level details of this idea are documented here: https://github.com/Encapsule/jbus

It’s not going to be called jbus but rather something else. I’m in a dark period on the code right now: rebase will emerge on GitHub over the next month, perhaps two. We’re talking about 40-50K lines of complex JavaScript.

HUB Bellevue

I’ve moved my office into the new HUB in Bellevue, WA and am heads down until I get this onm re-write released.

Then I’m going to try to teach every Node.js developer on earth how to imbue their JSON with semantics, and leverage this information to write less, more reliable, generally re-usable components that work together by-design (as opposed to by chance or by virtue of the fact that you invested substantial resources writing tests).

Please follow @Encapsule on Twitter and watch for updates over the coming weeks.

Encapsule Project Next Mocha/Chai Test Author(s)

If you look at my GitHub public commit logs you’ll notice that there’s been very little activity here in 2014. This is deceptive; I’ve joined a start-up in Seattle called Azuqua (http://azuqua.com) and am actively working on a major update to the service based, architecturally, on Object Namespace Manager, Software Circuit Description Language (onmd-scdl npm package), and some other for-now secret sauces (hint: graph theory).

onm npm package is stable (both in the browser via browserify) and on Node.js and I’m actively pushing bug fixes and small enhancements as I find/need them for production work. If you’re interested in using this package in your app and want more information drop me an e-mail. I am happy to answer questions and help as I’m able.


I was talking with John-David Dalton (lodash author) after a recent SeattleJS meetup and he advised me to party on Mocha/Chai for my testing needs. So I dove in and think Mocha/Chai is really great. I’ve been writing a ton of tests for new code that derives from onm, but just don’t have the time to circle back and do the same for onm itself.

If you’re interested in learning about the onm lib, I mean really learning it, and are willing to help out writing Mocha/Chai tests please drop me a line.

Normalized ONMjs Node.js + HTML 5 SPA Architecture

I’m working to get ONMjs published as a node.js package and to create a Yeoman generator to automate the creation of a simple generic web application project that can be customized using (a) a shared Data Model Declaration (b) data-model-agnostic re-usable observer plug-ins.

Normalized web app architecture using ONMjs

Normalized web app architecture using ONMjs

ONMjs Sources Committed, Preview Release Plans

Shortly after my last post my progress on ONMjs documentation ground to a halt as I realized that ONMjs addressing was just too complicated for users to deal with. Reluctantly, I went back into the code and did a massive 11th-hour refactoring that completely re-works ONMjs’ public addressing API’s. It was a ton of work but I am pleased with the result; all the implementation details of ONMjs addresses are now hidden. This simplifies everything and importantly ensures that code written against the API is not broken by later extension and optimization of the addressing subsystem.

After completing the refactoring, I separated ONMjs from the Schema SPA and committed the sources to the Encapsule/ONMjs repository on GitHub mid-month (Oct). Since I’ve invested in bug fixes (mostly to the bundled ONMjs observers written originally for Schema but since generalized). Also, I started building an ONMjs-based data editor (inside of Schema) that allows you to edit ONMjs data model declarations. (i.e. I’m using ONMjs to model itself :))

Documentation is dated at this point given all the code work that’s been done this month. Good news is that significant sections of the existing docs can now disappear, and sections that remain reduced and simplified. I’ll be working on this task this week.

Latest ONMjs Links

Source Code (CoffeeScript)


Library Code (Javscript)


Single-files that comprise ONMjs are published here: http://onmjs.encapsule.org/stage/

 jsFiddle Examples

ONMjs Data Model Editor

This is a work in progress but kind of cool…

ONMjs Library Daily Build Goes Live

Howdy, folks.

ONMjs daily build is now live.

ONMjs examples (JSFIDDLE):

ONMjs builds:

ONMjs discussion:

News and updates:
https://twitter.com/Encapsule­ // http://blog.encapsule.org­

Source repo on GitHub should be live very soon:

Simple Address Book w/ONMjs

ONMjs-lib-core-min.js weighs in under 50KB seems to be working well: http://jsfiddle.net/Encapsule/Ar3fB/

This JSFIDDLE project has four external library dependencies:

encapsule-lib-javascript.js is tiny and I’ll likely just fold it into ONMjs-lib-core and be done with it.

uuid.js is a client dependency, not an ONMjs dependency.

Current build of http://schema.encapsule.org is also powered by ONMjs (same ONMjs core library + its optional observer examples).

Tomorrow, I’ll be vetting ONMjs-lib-observe* packages from http://schema.encapsule.org/js/ for dependencies, and then ONMjs will be live.



Presenting ONMjs @ SeaLang on 2013.11.06

I’ll be doing my first public talk on the forthcoming ONMjs library at the Seattle Programming Languages Meetup group on November, 6th 2013 in Redmond, WA. If you’re local, I encourage you to come.

This is a great group and I expect to learn as much as I educate given the caliber of the engineers that turn out monthly for these meetings.

Here’s a link to the event:

[SeaLang] Decoupled Web Apps w/ONMjs

One of our own, Chris Russell, will be presenting the following:

“Join us in November for a talk about architecture, design patterns, and strategies for building decoupled, reactive web applications and components using a new JavaScript library called ONMjs developed by speaker Chris Russell for the open source Encapsule Project.

ONMjs (Object Namespace Manager) is a low-level infrastructure library written in CoffeeScript (compiled to JavaScript) based on a hybrid design pattern called Model Store Observe Feedback Signal (MSOFS) . The library was created to simplify the development of complex client-side HTML 5 data visualization and editing applications but is neither a UI nor strictly client-side library.

Briefly, ONMjs provides you with a way to declare and annotate your application’s data object model (Model concept), an automated way to create and dispose of data objects (Store concept), a set of API’s for writing event handlers (Observer concept), API’s for accessing and mutating data (Feedback concept), and support for communicating data changes among decoupled application subsystems (Signal concept).

The talk will be informal and there will be plenty of time for Q&A and discussion of related topics. You are encouraged to bring your laptop and tip the staff at Canyons Redmond who generously hosts SeaLang’s monthly meetings.”

As always, we’ll have a few OReilly books to bribe away, and as a reminder, your host (Ted Neward) won’t be there. If somebody wants to step up to be the host (meaning, you get there a few minutes early, mention to the staff that we’re taking over the back, remember to bring a VGA cable so Chris can hook his laptop up to the TV, and open the meeting with whatever schtick sounds good to you before introducing Chris), email me and I’ll send you a list of things to do that mirrors exactly that list I just rattled off. ;-)

Thanks to Ted Neward and SeaLang for the opportunity to come speak.

ONMjs Library Docs

I’ve been working on documentation for the ONMjs library for the past 24-hours. It’s good to pop up out of the code and try to explain it before actually releasing a stand-alone preview as it gives me an opportunity to scrub for consistency and audit my scenario coverage.

The more I write about it, the more I like ONMjs. It’s a large amount of work but I’m excited to actually be releasing something that I’m sure a lot of people will find useful.

The Git repository (currently empty) is: Encapsule/ONMjs (GitHub).

ONMjs itself is stable but still in gestation in the Encapsule/schema repository.

You can view the Coffeescript sources here:

… or the compiled Javascript here:

Once I’m satisfied with the docs I plan to learn me some Grunt and automate the generation of debug and minimized versions of ONMjs.

I almost wish I hadn’t already paid for GeekWire Summit tomorrow so I could keep writing. Oh well – it will be fun to get out with the geeks.



September 2013 Project Update

Greetings. It’s been several months since my last post here and there’s a lot of new stuff to talk about.

In May I gave an hour-long demo and Q&A on the Encapsule Project Schema HTML 5 application at the Seattle Graph Database Meetup group. I felt like maybe half of the twenty or so people who came that evening understood the whole point of Soft Circuit Description Language (SCDL). Of that ten, perhaps two people were able to relate the concepts I discussed back to the rather boring Schema HTML 5 app demo I brought along to show.

Not a big win but I did get some good questions. The most interesting was if I was going to enable to programmatic creation of SCDL model and specification data or was simply going to provide the Schema SCDL Editor. I hadn’t previously considered programmatic generation of SCDL to be a high priority and was curious about what people would use such a facility for if it did exist.

Programmatic Generation of SCDL and Program Annotation

Why do we need a programmatic way to generate SCDL in addition to the Schema SCDL editor? The answer is fascinating; providing an API for manipulating SCDL programmatically makes it possible to write programs that write programs (i.e. a program synthesizer). Synthesis as you’ll recall involves the combination of two or more things to make something new. A SCDL program synthesizer specifically leverages SCDL as a domain specific annotation language.

For example a SCDL model set of re-usable data visualization component comprises a kit for building entire class of visualization applications (the class of all possible allowed combinations of the various SCDL models). A SCDL program synthesizer program could be written to glean salient information and features of an input data set(s) (e.g. via parsing), and use this information to generate a SCDL specification to visualize the data in terms of the available SCDL data visualization components.

In this example, what we’re annotating is how we want another program to visualize the input data given its structure, features, content… The resultant “annotation”, a SCDL specification, could then be executed to visualize the data, or serialized and passed along with the data to some other processing entity (e.g. to respond to a request).

To take a far less trivial example, the original question was posed by a gentleman whose job it is to figure out how to programmatically port thousands of legacy enterprise applications to the web. Plausibly I can imagine SCDL providing a framework for building up such transformation systems in a predictable way that scales. The viability of this approach of course depends on much infrastructure that doesn’t yet exist so currently this is theoretical. However, the entire exchange convinced me that I must provide a way to programmatically generate SCDL models and specifications.

In the course of this discussion it was mentioned that I’m rather blithely ignoring the semantic web. I countered that I’ve tried but just don’t get it and that perhaps by working through things my way I’ll understand. Or, be able to demonstrate a simpler way to affect the same ends using data flow graphs.

Schema HTML SCDL Editor and SCDL API

I’ve spent this entire year so far essentially trying to figure out how to write HTML 5 apps like Schema. It’s actually quite a difficult task to build an interactive data editing and visualization application when your data model is complicated. There’s a ton of runtime state and keeping the code clean defect free is extremely hard unless you’ve got some solid low-level infrastructure code.

As of the May demo I was still struggling with fundamental architecture questions about how I was going to structure the application and prevent myself from building something so sprawling that I would not longer be able to comprehend it.

Questions about support for a SCDL API got me thinking that the whatever solution I came up with had to both provide a nice and clean API but additionally support the following core scenarios for building interactive data editing / visualization apps in the browser:

  • The app data model must be declared at design-time and then used at runtime to tailor the specific functionality of generic routines to ensure that changes to the data model do not impose huge refactoring penalties.
  • All application data needs to be addressable in order to ensure a clean decoupling between the many routines that operate on it. Further the addressing schema must accommodate local hash URL routing as well as some future URI-based protocol.
  • It needs to be easy to segregate actual application runtime data from metadata.
  • It needs to be easy to write simple routines that operate on both app data and app metadata stores.
  • It must be trivial to save / restore all runtime app state in JSON format.

My summer has been consumed with designing a solution that meets all the above criteria and the result is a new Javscript library I call ONMjs.


ONM stands for Object Namespace Manager. The ‘js’ is tacked on the end to signify that this is a Javascript implementation of the library (others are certainly possible but for now, just Javascript).

The currently published version of Schema is essentially a complete re-write of the demo I gave in May that leverages the new ONMjs library to manage all of its application state.

What you see in the browser, in the little window panes, are actually little plug-ins that observe and react to changes in runtime application data via a sophisticated implementation of the Observer Pattern. Some even change the data and ONMjs takes care of letting everyone else know.

Over the next week I’ll be forking the ONMjs library into its own repo on GitHub and plan a series of small example apps and blog posts to explain what it is and how to use it in your own applications.

ONMjs is completely generic, is dependency-free Javascript, and is intended to be used in conjunction with libraries such as D3js and Knockoutjs (or with any number of other libraries).

If you’re working on this sort of web app ONMjs wants to be your friend. Stay tuned.

May 30th, 2013 Talk at Seattle Graph Database Meetup

Graph Database Seattle

Graph Database Seattle

I’ll be doing a talk about the Encapsule Project and the Schema HTML 5 application at the Seattle Graph Database Meetup group on Thursday, May 30th, 2013 in Seattle.

Event link: http://seattle.meetup.neo4j.org/events/117587312/

Disney’s 10th Floor World & Land, 925 4th Ave N Seattle,98104, Seattle, WA (map)

Thanks to Saikat Kanjilal and the other organizers of Graph Database Seattle for organizing these meetups and agreeing to let me speak!