Abstract Relationships

We've introduced a very, very low-level linking functionality to have
a microstate draw its value from anywhere in the tree. However, what's
lacking is a way to declaratively state from within the microstate
what those links _are_ and where they go.

So, for example in the BigTest network ORM, we want to be able to say:

```js

import { belongsTo } from '@bigtest/network';

class Blog {
  title = String;
  author = belongsTo(Person);
}
```

and for it to link to the correct person.

To accomplish this, we introduce the concept of a relationship which
is just an abstraction over a Type and a path. Every reference from
one microstate to another is now reconceived as a relatioship.

It's not that complicated though. A relationship is really just a
function that takes the holder object, it's type, it's path, and the
name of the relationship and returns a `{ Type, path }` pair that is
used for linking.

For example, the default relationship is `Child` and is defined as:

```js
function Child(spec) {
  return new Relationship(resolve);

  function resolve(origin, originType, path, name) {
    let Type = typeof spec === 'function' ? spec : typeOf(spec);
    return { Type, path: path.concat(name) };
  }
}
```

It's what implements the first line DSL.

`belongsTo`, which resolves to a different place in the store, could
be implemented like so:

```js
function belongsTo(Type) {
  return new Relationship(resolve);

  function resolve(object, objectType, path, name) {
    let tableName = pluralize(Type.name.toLowerCase());
    let id = valueOf(this)[`${name}Id`];
    return { Type, path: path.slice(-3).concat([tableName, "records", id]) };
  }
}
```

this assumes a layout of the DB like:

```json
{
  blogs: {
    nextId: 2,
    records: {
      0: { title: 'How to blog', authorId: 'id1' },
      1: {
        title: 'How to build a fully immutable directed cyclic graph in javascript',
        authorId: '0'
      }
    }
  },
  people: {
    nextId: 1,
    records: {
      0: { firstName: 'Charles', lastName: 'Lowell' }
    }
  }
}
```

So you can see that what we're really doing is using a relative path
within the DB. The expression

```js
path.slice(-3).concat([tableName, "records", id])
```

is really equivalent to `["..", "..", "..", tableName, "records", id]`
if we were writing it out using a more classic method for expressing paths.

** Follow on Work / Questions **

- Need a way to specify what happens when you _set_ a
 relationship. For example, in the case of `belongsTo`, you need to
 update the `authorId` atribute at the appropriate path. We might be
 able to use some sort of lens here.

- This will mess with Identity. Specifically, if a linked object that
  isn't actually contained within this object changes, then the
  identity of the object needs to change (I think). For example, if I
  say:

  ```js
  blog.author.firstName.set('Carlos')
  ```
  even though the `valueOf(blog)` will not have changed (it still has
  `{authorId: 0}`). It should be represented by a new object
  because. This will be possible because of laziness.

Author: cowboyd

src/create.js

@@ -1,6 +1,7 @@
 import { set } from './lens';
-import { link, mount, locationOf, metaOf, atomOf, ownerOf, valueOf } from './meta';
+import { link, locationOf, metaOf, atomOf, ownerOf, typeOf } from './meta';
 import MicrostateType from './microstate-type';
+import Relationship from './relationship';
 
 export default function create(Type, value) {
   let Microstate = MicrostateType(Type, transition, property);
@@ -23,9 +24,18 @@ function transition(object, Type, path, name, method, ...args) {
   return link(create(owner.Type), owner.Type, owner.path, patch());
 }
 
-function property(object, Type, path, name, currentValue) {
-  let value = valueOf(object);
-  let expanded = typeof currentValue === 'function' ? create(currentValue, value) : currentValue;
-  let substate = value != null && value[name] != null ? expanded.set(value[name]) : expanded;
-  return mount(object, substate, name);
+function property(object, Type, path, name, relationship) {
+  let { resolve } = (relationship instanceof Relationship ? relationship : Child(relationship));
+  let target = resolve(object, Type, path, name);
+  let owner = ownerOf(object);
+  return link(create(target.Type), target.Type, target.path, atomOf(object), owner.Type, owner.path);
+}
+
+function Child(spec) {
+  return new Relationship(resolve);
+
+  function resolve(origin, originType, path, name) {
+    let Type = typeof spec === 'function' ? spec : typeOf(spec);
+    return { Type, path: path.concat(name) };
+  }
 }

src/identity.js

@@ -72,8 +72,8 @@ export default function Identity(microstate, fn) {
     return fn(Type, name, path, args);
   }
 
-  function propertyFn(object, Type, path, /* name, currentValue */) {
-    let location = compose(Path(path), Id.ref);
+  function propertyFn(object, Type, path, name /* relationship  */) {
+    let location = compose(Path(path.concat(name)), Id.ref);
     return view(location, paths);
   }
 }

src/meta.js

@@ -1,6 +1,6 @@
 import { type } from 'funcadelic';
 
-import { At, view, set, over, compose, Path } from './lens';
+import { At, view, set, compose, Path } from './lens';
 
 export function root(microstate, Type, value) {
   return set(Meta.data, new Meta(new Location(Type, []), value), microstate);
@@ -10,10 +10,6 @@ export function link(object, Type, path, atom, Owner = Type, ownerPath = path) {
   return set(Meta.data, new Meta(new Location(Type, path), atom, new Location(Owner, ownerPath)), object);
 }
 
-export function mount(microstate, substate, key) {
-  return over(Meta.data, meta => meta.mount(microstate, key), substate);
-}
-
 export function valueOf(object) {
   let { lens } = view(Meta.location, object);
   if (lens != null) {
@@ -57,11 +53,6 @@ export class Meta {
     this.location = location;
     this.owner = owner;
   }
-
-  mount(onto, atKey) {
-    let location = new Location(this.location.Type, pathOf(onto).concat(atKey));
-    return new Meta(location, atomOf(onto), ownerOf(onto));
-  }
 }
 
 class Location {

src/microstate-type.js

@@ -12,7 +12,7 @@ export default function MicrostateType(Type, transitionFn, propertyFn) {
     constructor(value) {
       super(value);
       Object.defineProperties(this, map((slot, key) => {
-        return CachedProperty(key, self => propertyFn(self, Type, pathOf(this).concat(key), key, slot));
+        return CachedProperty(key, self => propertyFn(self, Type, pathOf(self), key, slot));
       }, this));
       return root(this, Type, value);
     }

src/relationship.js

@@ -0,0 +1,7 @@
+export default class Relationship {
+  constructor(resolve) {
+    this.resolve = resolve;
+  }
+
+  resolve(/*origin, Type, path, name */) {}
+}

tests/lab.test.js

@@ -1,6 +1,4 @@
-import { append } from 'funcadelic';
-import { create, valueOf, atomOf } from '../index';
-import { mount, link } from '../src/meta';
+import { create, valueOf } from '../index';
 import expect from 'expect';
 
 describe('Lab', () => {
@@ -118,58 +116,4 @@ describe('Lab', () => {
     });
 
   });
-
-  describe('A globally linked microstate within another microstate', () => {
-    class Person {
-      get left() {
-        return mount(this, append(create(Hand), {
-          get other() {
-            return link(create(Hand), Hand, ['right'], atomOf(this), Hand, ['left']);
-          }
-        }), 'left');
-      }
-      get right() {
-        return mount(this, append(create(Hand), {
-          get other() {
-            return link(create(Hand), Hand, ['left'], atomOf(this), Hand, ['right']);
-          }
-        }), 'right');
-      }
-    }
-
-    class Hand {
-      other = Hand;
-      claps = Num;
-
-      clap() {
-        return this
-          .other.claps.increment()
-          .claps.increment();
-      }
-    }
-
-    let person;
-    beforeEach(function() {
-      person = create(Person, { left: { claps: 1 }, right: { claps: 1 } });
-    });
-
-    it('links the proper states', function() {
-      expect(person.left.claps.state).toEqual(1);
-      expect(person.right.claps.state).toEqual(1);
-    });
-
-    describe('transitioning', function() {
-
-      let clapped;
-      beforeEach(function() {
-        clapped = person.right.clap();
-      });
-      it('claps both hands', function() {
-        expect(clapped.left.claps.state).toEqual(2);
-        expect(clapped.right.claps.state).toEqual(2);
-      });
-    });
-
-  })
-  ;
 });

tests/relationship.test.js

@@ -0,0 +1,49 @@
+import expect from 'expect';
+import Relationship from '../src/relationship';
+import { valueOf } from '../src/meta';
+import create from '../src/create';
+
+describe('abstract relationships', ()=> {
+  class A {
+    b = class B {
+      c = class C {
+        a = root(A);
+      }
+    }
+  }
+
+  function root(Type) {
+    return new Relationship(() => ({ Type, path: []}));
+  }
+
+  let a;
+  let atom;
+
+  beforeEach(()=> {
+    atom = { b: { c: 'Hallo' } };
+    a = create(A, atom);
+  });
+
+
+  it('allows perfectly circular data structures', ()=> {
+    expect(valueOf(a.b.c.a)).toBe(valueOf(a));
+    expect(valueOf(a.b.c.a.b.c.a)).toBe(valueOf(a));
+    expect(valueOf(a.b.c.a.b.c.a.b.c.a)).toBe(valueOf(a));
+    expect(valueOf(a.b.c.a.b.c.a.b.c.a.b.c.a)).toBe(valueOf(a));
+  });
+
+  describe('transitioning from deep within the circular structure', ()=> {
+    let next;
+    beforeEach(()=> {
+      next = a.b.c.a.b.c.a.b.c.a.b.c.a.b.c.set('bye now!');
+    });
+    it('sets the right value', ()=> {
+      expect(valueOf(next)).toEqual({
+        b: {
+          c: 'bye now!'
+        }
+      });
+    });
+  });
+
+});