git » hoplite.git » commit 71d57f3

diff --git a/hoplite.org b/hoplite.org
new file mode 100644
index 0000000..b0a95f0
--- /dev/null
+++ b/hoplite.org
@@ -0,0 +1,54 @@
+* hoplite
+
+Hoplite is a JavaScript framework for building single-page web applications in the spirit of [[https://github.com/hoplon/hoplon][Hoplon]], but without the ClojureScript dependency. Hoplite eschews immutable collections and Javelin in favor of a bespoke mutable/relational model. Hoplite fuses the concepts of mutability and "collection" with a bespoke mutable/relational/reactive approach.
+
+** Data Model
+
+The Hoplite data model (data elements that participate in reactivity and are used to encode continuous program behaviors) consists of:
+
+- *atoms*: set of immutable primitive types in JavaScript (and encodable as JSON) that participate in ~===~ such as numbers, booleans, and strings.
+- *databases*: mutable sets of immutable *tuples* each containing one or more *atoms*. Despite their mutability, databases maintain have an identity given by contained tuples.
+
+=datalog.mjs= defines the data model and a Datalog engine for querying it.
+
+** Reactive Reference Types
+
+The following reference types facilitate reactive programming. Together, they transactionally mediate mutation and observation of networks of atoms and databases:
+
+- *Input*: a mutable atom.
+- *Formula*: an immutable atom. The value of the atom is given by a function, and the continuous application of that function to one or more atom (Input or Formula) dependencies.
+- *Database*: a mutable set of tuples. Tuples may be transactionally added and removed in batch. Databases also participate in transactions with other databases, such that all may appear consistent from the perspective of dependencies.
+- *Views*: an immutable set of tuples. The value of the view is given by a Datalog query. The =source= parameters of the query may consist of any other databases or views and the =argument= parameters of the query may consist of any other inputs or formulas.
+
+Relationships between reference types are maintained in =window.depGraph=, a global 2-place relation (bag; =Map= of reference object to =Set= of dependencies) that associates dependencies with dependers. 
+
+Whenever the identity of the set managed by a Database or View changes in the course of a propagation/transaction, the set of tuples that were either added or removed is maintained in the =added= and =removed= properties of the Database or View. Effectively, this gives dependencies an opportunity to respond efficiently to changes in a Database or View on which they depend.
+
+Everything else in Hoplite is designed around supporting this capability. The ability to receive the ways a dependency has changed, instead of just a notification that it *has* changed, makes it possible to manage stateful objects (like DOM nodes) efficiently, in response to data changes. The primary thesis of Hoplite is that the use of managed, mutable sets gets us close to something like the utility of everything-immutable FP, but without a lot of the runtime (or conference talks).
+
+=reactives.mjs= defines the reactive reference types.
+
+** DOM Projection
+
+This part is not yet implemented but its implementation is informed partly by =for-tpl= in Hoplon.
+
+Generally, there are two forms of projecting data to the DOM:
+
+- Projecting atoms to attributes, which can be done without allocating DOM nodes.
+- Projecting databases to sequences of DOM nodes, which necessitates allocating and deallocating DOM nodes in response to changes in tuple composition.
+
+Projecting atoms to attributes is done as easily in Hoplite as it is in Hoplon. Formula functions can modify DOM elements.
+
+Inputs to =for-tpl= in Hoplon are a sequence in a cell and a template function that instantiates an element and any necessary reactives.
+
+- Element order is given by the sequence
+- Elements are never deallocated; they are pooled and added/removed from the DOM on demand.
+
+The use of sets (and the ability to subscribe to changes) in Hoplite suggests a different interface:
+
+- Element order is provided explicity, as sets are not ordered.
+- Element identity is provided explicitly (a la React "key") because there is not generic structural equality.
+- Elements may be removed and their reactives destroyed when the key is removed from the source set.
+
+The set of reactives created through the instantiation of a template function can be done by simulating a dynamic variable. Transactions already implement something similar. The Hoplite =for-tpl= analogue then internally maintains the relationship between instantiated elements and their associated reactives, and surgically disposes of that set of reactives when the element identity disappears and the element is removed from the DOM.
+