skandha 0.6.0 → 0.9.1

package/README.md

@@ -2,27 +2,7 @@
 
 ## Rationale
 
-Despite having a lot of good libraries, programmers still find themselves reimplementing
-the same solutions over and over.
-The reason is that not every solution can be captured in a library. When there are cross-cutting concerns (aka
-aspects, as in aspect oriented programming), then out-of-the-box solutions often do not fit well enough. For this
-reason, programmers are often reluctant to store their data in framework-specific data-structures, even though such frameworks could potentially save time.
-
-Skandha proposes an alternative solution (somewhat inspired by Erlang) that aims to let the programmer re-use existing logic,
-while allowing them to use their own data-structures. This is achieved by mapping the user's data-structures onto a set of
-minimal interfaces called facets. These facets perform tasks by interacting via so-called policies. By keeping facets
-minimal, they can be generic, which leads to better code reuse.
-
----
-
-**NOTE**
-
-The binding of facets to containers in Skandha relies on class names. Therefore you
-need to disable the mangling of classnames in your minification tool, or disable minification completely. A future version of Skandha will allow you to declare
-facet names by adding a property in the facet class, or specify the names when calling
-`registerFacets`.
-
----
+The goal of SkandhaJS is to provide data containers that have reusable behaviors, such as selection, highlighting, filtering, drag-and-drop, etc. The only requirement for using these containers is that every item in the container has a unique id. SkandhaJS allows you to combine behaviors and make them interact properly. For example, when selecting an item you may want the item also to be highlighted. As we will see, these interactions are achieved by implementing callback functions.
 
 ## Links
 
@@ -30,322 +10,254 @@ facet names by adding a property in the facet class, or specify the names when c
 - The [skandha-facets](http://github.com/mnieber/skandha-facets) library contains useful facets such as selection, highlight, filtering, addition, etc.
 - The [skandha-mobx](http://github.com/mnieber/skandha-mobx) library contains bindings to MobX
 - The [aspiration](http://github.com/mnieber/aspiration) library handles aspect oriented programming (AOP)
+- The [example code](http://github.com/mnieber/skandha-sample-app) shown in this README.
 
-## Example code
+## Glossary (conceptual)
 
-The full example code for this README can be found [here](http://github.com/mnieber/skandha-sample-app). Note that this repository
-contains two version of the example code. The frst version creates all the behaviours from scratch. Although it gives a good insight into
-the Skandha principles, the code will look bulky. The second version is reflective of a real use-case as it uses the reusable behaviours
-from [skandha-facets](http://github.com/mnieber/skandha-facets).
+- callbacks object: a collection of callback functions that is used by an operation.
+- container: a class that contains multiple facets.
+- facet: a class that implements a reusable behaviour, such as selection.
+- operation: a member function of a facet that changes the data of that facet.
 
-## Explanation
+## Glossary (technical)
 
-The Skandha library will be explained using an example that progressively introduces various concepts
-and functions. The example shows how to add reusable selection, highlight and filtering behaviour to a container
-with Todo items.
+- aspiration: a library that implements a form of Aspect Oriented Programming using callback functions.
+- registerCtr: the function that tells SkandhaJS which containers and facets exist.
+- setCallbacks: the function that installs the callbacks objects that are used by a facet.
 
-### Containers and Facets
+## Example: a simplified Selection facet
 
-A container is a set of related data, e.g. todo items together with data about selection, highlight, etc. A facet is a
-member of a container that represents a single aspect such as `Selection`. In the example below we see a `TodosCtr`
-with five facets: `Selection`, `Highlight`, `Filtering`, `Inputs` and `Outputs`. As we shall see, `Selection`,
-`Highlight` and `Filtering` are generic (not tied to the concept of a Todo) and therefore reusable.
+In Skandha, behaviours (such as selection, or filtering) are implemented in so-called facets that live in containers. For example, a todo container may have facets for selecting, highlighting and filtering todos. Because facets are reusable, they can also be used in other containers. And because facets are abstractions, you can use them to create UI components that handle selection in any container. In this example, we will show a simplified Selection facet class.
 
-The `Inputs` facet contains the data (i.e. the todos) that is selected, highlighted and filtered, whereas the `Outputs` facet
-contains some of the results that are produced by the container (e.g. the filtered list of todos). It's not strictly
-necessary to use `Inputs` and `Outputs` as you could directly connect `Selection`, `Highlight`, and `Filtering` to
-data-sources that are outside of the container, but it's easier to reason about the container if they exist.
+```
+// file: Selection.ts
+import { input, output, operation } from 'skandha';
+
+export type SelectionParamsT = { itemId?: string; isShift?: boolean; isCtrl?: boolean; };
 
-Our initial code is:
+export class Selection<ValueT = any> {
+  static className = () => 'Selection';
 
+  @input selectableIds: Array<string> = [];
+  @output ids: Array<string> = [];
+  @output anchorId?: string;
+  @output items: Array<ValueT> = [];
+
+  @operation selectItem(selectionParams: SelectionParamsT) {
+    // This function calls a callback function to do the actual work.
+    // Details about how this works are omitted for now.
+  }
+}
 ```
-    class Selection<TodoT> {}
 
-    class Highlight<TodoT> {}
+## Fact: facets have @input, @data and @output members
 
-    class Filtering<TodoT> {}
+In `Selection.ts` we see the Selection facet class. It has a `selectableIds` field that stores the list of ids from which we can select. It is marked with the `@input` decorator because this field stores an input. The `ids`, `anchorId` and `items` fields are marked as `@output` fields. They are used to store the result of calling `selectItem()`.
 
-    class Inputs {
-      @data todoById: TodoByIdT = {};
-    }
+## Fact: operations are decorated with `@operation`.
 
-    class Outputs {
-      @data filteredTodoById: TodoByIdT = {};
-    }
+Conceptually, an operation is a member function that is used to manipulate the facet. The `Selection` facet has a `selectItems` operation that allows you to select from the selectable ids. It stores its results in the `ids`, `anchorId` and `items` fields.
+As the comment mentions, `selectItem()` calls a callback function to do the actual work. The reason is that the correct way to make a selection (e.g. what should happen if shift is pressed?) depends on the use-case. Therefore, we want to leave it up to the client to decide this.
 
-    class TodosCtr {
-      @facet inputs: Inputs = new Inputs();
-      @facet outputs: Outputs = new Outputs();
-      @facet selection: Selection<TodoT> = new Selection<TodoT>();
-      @facet highlight: Highlight<TodoT> = new Highlight<TodoT>();
-      @facet filtering: Filtering<TodoT> = new Filtering<TodoT>();
-    }
-```
+## Fact: operations are logged
 
-Notes:
+As a side effect of calling an operation, the entire container is logged to the console; this includes the Selection facet, and any other facets that the container may have. The log message contains all @input, @data and @output fields of all facets in the container.
 
-- The `@data` and `@operation` decorators mark the fields in the facet that make up its abstract interface.
-  Clients should use only these fields.
+## Example: a container with Selection, Highlight and Filtering
 
-### Implementing the Selection facet
+Now that we have some idea of what a facet is, we will discuss containers.
+In this example we will take a look at a todos container. It uses the `Selection` facet that we saw earlier.
 
-We will first implement the Selection facet. The key requirements are that:
+```
+// file: createContainer.ts
+import { Selection_selectItem } from 'SelectionCbs';
+
+const createContainer() {
+  const ctr = {
+    selection: new Selection(),
+    highlight: new Highlight(),
+    filtering: new Filtering()
+  };
+
+  setCallbacks(ctr.selection, {
+    selectItem: {
+      select(this: Selection_selectItem): {
+        handleSelectItem(ctr.selection, this.selectionParams);
+        highlightFollowsSelection(ctr, this.selectionParams);
+      },
+    }
+  });
 
-- this facet is only concerned with ids. To make a selection in any data-structure, it suffices to map this data-structure
-  to a list of ids. And to obtain the list of selected items, it suffices to map in the opposite direction: from ids to items.
-- the facet has to be generic, which means that the client code has control over how selection is actually
-  performed, and over possible side-effects. This means the client can determine
-  the effect of the shift key, or decide that selecting an item should also highlight it.
-- preferably the facet has to perform some useful work, and not just be an empty abstraction.
+  setCallbacks(ctr.filtering, {
+    apply: {
+      exit() {
+        highlightIsCorrectedOnFilterChange(ctr);
+      },
+    },
+  });
 
-This is our proposal for the Selection facet:
+  registerCtr({ ctr: ctr, options: { name: 'Todos'} });
+  return ctr;
+}
+```
 
 ```
-export class Selection_select extends Cbs {
-  selectionParams: SelectionParamsT = stub();
-  selectItem() {}
+// file: highlightFollowsSelection.ts
+const highlightFollowsSelection = (ctr: any, selectionParams: SelectionParamsT) => {
+  if (!selectionParams.isShift && !selectionParams.isCtrl) {
+    ctr.highlight.highlightItem(selectionParams.itemId);
+  }
 }
+```
 
-class Selection<TodoT> {
-  @data selectableIds: Array<string> = stub();
-  @data ids: Array<string> = [];
-  @data anchorId?: string;
-  @data items?: Array<ValueT>;
-
-  @operation @host selectItem(selectionParams: SelectionParamsT) {
-    return (cbs: Selection_select) => {
-      if (!this.selectableIds.includes(selectionParams.itemId)) {
-        throw Error(`Invalid id: ${selectionParams.itemId}`);
-      }
-      cbs.selectItem();
-    }
+```
+// file: handleSelectItem.ts
+export function handleSelectItem(
+  facet: Selection,
+  { itemId, isShift, isCtrl }: SelectionParamsT
+) {
+  if (itemId === undefined) {
+    facet.ids = [];
+    facet.anchorId = undefined;
+    return;
+  }
+
+  if (isShift) {
+    // Omitted for brevity
+  } else if (isCtrl) {
+    facet.ids = facet.ids.includes(itemId)
+      ? facet.ids.filter((x) => x !== itemId)
+      : [...facet.ids, itemId];
+  } else {
+    facet.ids = [itemId];
+  }
+
+  // Move the anchor
+  if (!facet.anchorId || !(isCtrl || isShift)) {
+    facet.anchorId = itemId;
   }
 }
 ```
 
-Notes:
+## Note: the todos container has selection, highlight and filtering
 
-- The `@host` decorator comes from the [Aspiration](http://github.com/mnieber/aspiration) library. It makes
-  the function take a callback object (i.e. a set of callbacks) that is installed by the client. This allows us to
-  write a `Selection` facet that is generic (our 2nd requirement) but also does useful work (3rd requirement).
-  We shall discuss below how the `cbs.selectItem` callback is implemented.
-- The `stub` function is used in callback objects to indicate that although the field is initialized with `undefined`
-  it will receive a value later.
+In `createContainer.ts` we see how `createContainer()` creates a `ctr` object that has three facets: selection, highlight and filtering. After creating the container, the `installCallbacks` function is called to determine how the facet operations are implemented. Finally, `registerCtr()` is called to allow SkandhaJS to introspect the container. This is necessary for two reasons. First, it makes it possible to look up a facet by its name or class, e.g. `getf(ctr, Selection)` returns `ctr.selection`. Second, it informs SkandhaJS how to log all facets of the container
 
-### Implementing the Highlight and Filtering facets
+## Fact: callbacks are installed with `setCallbacks`
 
-Since `Highlight` and `Filtering` follow the same structure as the `Selection` facet, we will only
-show the code. For brevity, we will leave out the code for the callback objects such as
-`Highlight_highlightItem` (they are straightforward and not that interesting):
+We call `setCallbacks` to install a callbacks object for each operation of the `Selection` facet. The callbacks object contains all callbacks for an operation. In our case we only have one operation (`selectItem()`) that has only one callback (`select()`). This callback function calls `handleSelectItem` to take care of doing the selection. This is a typical pattern: you want the call to `setCallbacks` to be as short and readable as possible, so that it's easy to understand what happens in each operation of each facet.
 
-```
-export class Highlight<ValueT = any> {
-  @data id: string | undefined;
-  @data item?: ValueT;
+## Fact: callbacks can take care of side effects
 
-  @operation @host highlightItem(id: string) {
-    return (cbs: Highlight_highlightItem) => {
-      this.id = id;
-    };
-  }
-}
+An important advantage of using callbacks is that they can also take care of side effects. In this case, it calls `highlightFollowsSelection()` to ensure that selected items are also highlighted. Note that the callback function is able to connect selection and highlight because it has access to the entire container.
 
-export class Filtering<ValueT = any> {
-  @data isEnabled: boolean = false;
-  @data filter: FilterT = () => [];
+## Fact: the callback function can access the callbacks object through `this`.
 
-  @data inputItems?: Array<ValueT>;
-  @data get filteredItems() {
-    return this.isEnabled ? this.filter(this.inputItems) : this.inputItems;
-  }
+When the clients calls `ctr.selection.selectItem()` and `select` is called back, then all arguments of the operation are available through `this`. In our case, we see that the `select` callback function is accessing `this.selectionParams`.
 
-  @operation @host apply(filter: FilterT) {
-    return (cbs: Filtering_apply) => {
-      this.filter = filter;
-      this.isEnabled = true;
-    };
-  }
+## Fact: the `exit` callback function is called at the end of an operation
 
-  @operation @host setEnabled(flag: boolean) {
-    return (cbs: Filtering_setEnabled) => {
-      this.isEnabled = flag;
+In `createContainer.ts` we also have a `Filtering` facet that has an `apply(f)` operation (where `f` is the filter function). In this operation, we install the `exit()` callback that corrects the highlight when the filter function changes (because the new filter may hide the highlighted item). The `exit()` callback is called automatically at the end of each operation. Similarly, the `enter()` callback is called at the beginning.
+
+## Example: a complete Selection facet
+
+It's time now to return to the Selection facet and show how callbacks really work.
+
+```
+// file: Selection.ts
+import { input, output, operation } from 'skandha';
+import { host, stub } from 'aspiration';
+import { Selection_selectItem, SelectionParamsT } from 'SelectionCbs';
+
+export class Selection<ValueT = any> {
+  static className = () => 'Selection';
+
+  @input selectableIds: Array<string> = stub();
+  @output ids: Array<string> = [];
+  @output anchorId?: string;
+  @output items: Array<ValueT> = stub();
+
+  @operation @host(['selectionParams']) selectItem(
+    selectionParams: SelectionParamsT
+  ) {
+    return (cbs: Selection_selectItem) => {
+      cbs.select();
     };
   }
 }
 ```
 
-### Implementing the callback objects
-
-We've set up the basic structure of the facets, but the callbacks still have to be implemented.
-This step happens in the container class. We will use the following requirements:
-
-- the `cbs.selectItem` callback should make a selection that takes the shift and control keys into account.
-  We will not show the code (you can see it
-  [here](https://github.com/mnieber/skandha-facets/blob/main/Selection.ts)) but assume we have a library
-  function `handleSelectItem` for this.
-- items that are selected should become highlighted. We will introduce a reusable policy
-  function for this called `highlightFollowsSelection`.
-- if applying the filter hides the highlighted item then we want to correct the highlight.
-  We will use a another reusable policy called `highlightIsCorrectedOnFilterChange` (shown
-  [here](https://github.com/mnieber/skandha-facets/blob/main/policies/highlightIsCorrectedOnFilterChange.ts))
-
 ```
-class TodosCtr {
-  // ...
-
-  constructor() {
-    registerFacets(this);
-    this._setCallbacks();
-  }
+// file: SelectionCbs.ts
+import { stub } from 'aspiration';
 
-  _setCallbacks() {
-    const ctr = this;
-
-    setCallbacks(this.selection, {
-      select: {
-        selectItem(this: Selection_select): {
-          handleSelectItem(ctr.selection, this.selectionParams);
-          highlightFollowsSelection(ctr.selection, this.selectionParams);  // See below
-        },
-      }
-    });
-
-    setCallbacks(this.filtering, {
-      apply: {
-        exit() {
-          FacetPolicies.highlightIsCorrectedOnFilterChange(ctr.filtering);
-        },
-      },
-    });
-  }
-}
+export type SelectionParamsT = { itemId?: string; isShift?: boolean; isCtrl?: boolean; };
 
-export function highlightFollowsSelection(
-  selection: Selection,
-  selectionParams: SelectionParamsT
-) {
-  const {isCtrl, isShift, itemId} = selectionParams;
-  const ctr = getc(selection);
-  if (!isCtrl && !isShift) {
-    getf(Highlight, ctr).highlightItem(itemId);
-  }
+export class Selection_selectItem extends Cbs {
+  selectionParams: SelectionParamsT = stub();
+  select() {}
 }
 ```
 
-Notes:
+## Fact: the `@host` decorator is used to enable callbacks in an operation.
 
-- The call to `registerFacets` is mandatory. It creates a back-reference to the container in each facet
-  instance.
-- The `getc` gets the container for a given facet, whereas `getf` gets a facet for a given container.
+The `@host` decorator comes from the `Aspiration` library. When you call a function `f` that is decorated with `@host` then the following happens:
 
-### Mapping data onto the container, and between facets
+- Aspiration looks up the callbacks object for the operation (that was installed with `setCallbacks`)
+- it copies the operation arguments to the callbacks object (so that callback functions can access these arguments)
+- if calls `f(arguments)(callbacksObject)`.
 
-At this point we have a container with facets that perform useful operations, and that interact
-to achieve interesting behaviours. However, the container will not yet work because `Selection.selectableIds`
-and `Filtering.inputItems` are not connected to any data sources. Note that the client of the container
-is responsible for setting `Inputs.todoById` to the collection of todos (at some time after constructing the
-container).
+Remember that `f` is the original function. We see from the example that `f` returns a closure. This closure receives the callbacks object, but (because it's a closure) it also has access to the arguments of f. This approach allows the client code to call `f` in the usual way; it can be agnostic of the fact that callbacks are used to help implement `f`.
 
-As a first step, we need to connect `Filtering.inputItems` to `Inputs.todoById` and `Outputs.filteredTodoById`.
-We can think of this as setting up a pipeline, where one of more source facet members are mapped onto a destination
-facet member:
+## Fact: callback functions have access to all operation arguments
 
-```
-  _applyPolicies() {
-    mapDataToFacet(
-      [Filtering, 'inputItems'],
-      getm([Inputs, 'todoById']),
-      (x: TodoByIdT) => Object.values(x)
-    )(this);
-
-    const listToItemById = items => items.reduce((acc: any, x: TodoT) => ({ ...acc, [x.id]: x }), {})
-
-    mapDataToFacet(
-      [Outputs, 'filteredTodoById'],
-      getm([Filtering, 'filteredItems']),
-      listToItemById,
-    )(this);
-  }
-```
+As we mentioned earlier, each callback function of the callbacks object has access to all arguments of the operation. For this to work, it's required that you pass the list of argument names to the `@host` decorator (unfortunately, typescript does not have introspection capabilities that allow to automate this). These names need to match the corresponding fields of the callbacks object class (`Selection_selectItem`).
 
-Notes:
+## Fact: facets have a static `className()` function
 
-- the first argument to `mapDataToFacet` is a getter function that takes the container and returns some data.
-  In this case, it uses the `getm` helper function to return the `todoById` member of the `Inputs` facet.
-- the second argument to `mapDataToFacet` is the facet member that receives the data. SkandhaJS will patch the
-  facet, replacing the `inputItems` member with a `get inputItems()` property that runs the
-  getter function.
-- the third argument is a transformation that is applied to the result of the getter function. In this case,
-  it means that `get inputItems()` returns `Object.values(getm(Inputs, 'todoById')(ctr))`,
+To allow SkandhaJS to introspect the container, you need to add the `className()` function to each facet class, so that Skandha knows the name of the facet.
 
-As the next step, we will connect the list of filtered items to `Selection.selectableIds` (so that selection
-happens in the filtered list). In addition, we will add datamappings for `Selection.items`
-and `Selection.item`:
+## Example: a Connector maps data onto each facet
+
+We've seen how facets are implemented, and how they can be added to a container in a way that allows us to create interactions between them. Since our container contains selection and filtering, we should only allow selection of todos that have not been filtered out. In other words, the list of selectable ids should be derived from the list of filtered todos. Moreover, we need to load the todos and set them as the inputs of the filtering facet. In this example, we show two containers (data and todos) and how to map data between them.
 
 ```
-  _applyPolicies() {
-    // ...
-
-    mapDataToFacet(
-      [Selection, 'selectableIds'],
-      getm([Outputs, 'filteredTodoById']),
-      (x: TodoByIdT) => Object.keys(x)
-    )(this);
-
-    mapDatasToFacet(
-      [Selection, 'items'],
-      [
-        getm([Selection, 'ids']),
-        getm([Inputs, 'todoById']),
-      ],
-      (ids: string[], todoById: TodoByIdT) => ids.map((id) => todoById[id])
-    )(this);
-
-    mapDatasToFacet(
-      [Highlight, 'item'],
-      [
-        getm([Highlight, 'id']),
-        getm([Inputs, 'todoById']),
-      ],
-      (id: string, todoById: TodoByIdT) => todoById[id]
-    )(this);
+// file: createContainer.ts
+import * from 'ramda' as R;
+
+const connectContainer(ctr: any) {
+  const data = {
+    inputs: { todos: loadTodos() },
+    outputs: { filteredTodoById: {} },
+  };
+
+  const todos = {
+    selection: new Selection(),
+    highlight: new Highlight(),
+    filtering: new Filtering(),
   }
-```
 
-We are done: the facets in the container are connected. Note that if we put these mapping policies in a reusable
-library then we can shorten `_applyPolicies` to:
+  const con = createConnector({ data: data, todos: todos });
+  const lookUpTodo = (id: string) => outputsCtr.filteredTodoById[id];
 
+  con['todos.filtering'].inputItems = con['inputs'].todos;
+  con['outputs'].filteredTodoById = con['todos.filtering'].filteredItems.tf(R.indexBy('id));
+  con['todos.selection'].selectableIds = con['outputs'].filteredTodoById.tf(R.keys);
+  con['todos.selection'].item = con['todos.selection'].ids.tf(lookUpTodos);
+  con['todos.highlight'].item = con['todos.highlight'].id.tf(lookUpTodo);
+
+  con.connect();
 ```
-  _applyPolicies() {
-    // ...
-
-    const policies = [
-      // selection
-      SelectionUsesSelectableIds([Outputs, 'filteredTodoById'], Object.keys),
-      SelectionUsesItemLookUpTable([Inputs, 'todoById']),
-
-      // highlighting
-      HighlightUsesItemLookUpTable([Inputs, 'todoById']),
-
-      // filtering
-      FilteringUsesInputItems([Inputs, 'todoById'], Object.values),
-      mapDataToFacet(
-        [Outputs, 'filteredTodoById'],
-        getm([Filtering, 'filteredItems']),
-        listToItemById,
-      ),
-    ]
-
-    installPolicies<TodosCtr>(policies, this);
-  }
-```
+
+## Fact: the Connector class maps data between objects
+
+The Connector instance allows you to map data from one object onto another object.
+In our example, the `data.inputs.todos` field is mapped onto the `todos.filtering.inputItems` field. What this means is that `Connector` turns `todos.filtering.inputItems` into a `get` property that returns `data.inputs.todos`.
 
 ### Logging
 
-By calling `setOptions({logging: true})`, the Skandha library allows you to inspect each facet before and
-after calling an operation (remember that an operation is any facet member function decorated with @operation).
-This will log Facet members that are decorated with `@data` in a way that looks similar to what you are
-used to from Redux:
+By calling `setOptions({logging: true})`, the SkandhaJS library allows you to inspect each facet before and after calling an operation.
+All facet members that are decorated with `@data` (or `@input`, or `@output`) are logged in a way that looks similar to what you are used to from Redux:
 
 - before and after each operation, the entire container that holds the facet is logged
 - all data members of each facet in the container are included in the log
@@ -353,25 +265,14 @@ used to from Redux:
 
 ### Making facets observable with Mobx
 
-If you want to render the facets with React then we need to let React know when data changes.
-The [skandha-mobx](http://github.com/mnieber/skandha-mobx) library was created for this purpose.
-It turns each `@data` member into a Mobx property that is either observable or computed. By decorating
-your render function with `observer` you will get a re-render for any changes (in observable facet members)
-in the container:
+If you want to render the facets with React then we need to let React know when data changes. The [skandha-mobx](http://github.com/mnieber/skandha-mobx) library was created for this purpose. It has a `registerCtr` function that turns each `@data` member into a Mobx property that is
+either observable or computed:
 
 ```
-class TodosCtr {
-  // ...
-
-  constructor() {
-    registerFacets(this);
-    this._setCallbacks();
-    this._applyPolicies();
-
-    // Turn all facets in the container into observable objects.
-    // Members annotated with @data will become either @observable or @computed.
-    makeCtrObservable(this);
-  }
+registerCtr({
+  ctr: ctr,
+  options: { name: 'Todos'},
+});
 ```
 
 ## Conclusion
@@ -384,5 +285,4 @@ a policy that says that changing the highlight disables editing. By using facets
 editing-specific code directly in the highlight function (that would obviously be mixing concerns).
 
 In my experience, using SkandhaJS leads to code reuse and improved structure. On top of that, it offers a good
-debugging experience (yes, you will still have to debug) by logging all changes in the container. Finally,
-it works nicely with MobX to render the container contents.
+debugging experience by logging all changes in the container. Finally, it works nicely with MobX to render the container contents.

package/index.d.ts

@@ -1,12 +1,12 @@
-export { ctrState } from "./internal/logging";
-export { getc, getFacetMemberNames } from "./lib/ctr";
-export { input, output, data, log, getLoggedMemberNames, getDataMemberNames, } from "./lib/data";
-export { mapDataToFacet, mapDatasToFacet, patchFacet, mapDataToProp, } from "./lib/patch";
-export { getOptions, setOptions } from "./internal/options";
-export { operation, getOperationMemberNames } from "./lib/operation";
-export { facet, registerFacets, getm, getf } from "./lib/facet";
-export { installPolicies } from "./lib/install";
+export { getCtrState } from './internal/logging';
+export { getOptions, setOptions } from './internal/options';
+export { createConnector } from './lib/Connector';
+export { getc, getFacetMemberNames } from './lib/ctr';
+export { data, getDataMemberNames, getLoggedMemberNames, input, log, output, } from './lib/data';
+export { getf } from './lib/facet';
+export { installPolicies } from './lib/install';
+export { getOperationMemberNames, operation } from './lib/operation';
+export { mapDataToProp } from './lib/patch';
+export { registerCtr } from './lib/registerCtr';
+export type { OptionsT as RegisterCtrOptionsT } from './lib/registerCtr';
 export declare type ClassT = any;
-export declare type MemberNameT = string;
-export declare type ClassMemberT = [ClassT, MemberNameT, any?];
-export declare type GetterT<T = any> = (ctr: any) => T;

package/index.js

@@ -1,8 +1,10 @@
-export { ctrState } from "./internal/logging";
-export { getc, getFacetMemberNames } from "./lib/ctr";
-export { input, output, data, log, getLoggedMemberNames, getDataMemberNames, } from "./lib/data";
-export { mapDataToFacet, mapDatasToFacet, patchFacet, mapDataToProp, } from "./lib/patch";
-export { getOptions, setOptions } from "./internal/options";
-export { operation, getOperationMemberNames } from "./lib/operation";
-export { facet, registerFacets, getm, getf } from "./lib/facet";
-export { installPolicies } from "./lib/install";
+export { getCtrState } from './internal/logging';
+export { getOptions, setOptions } from './internal/options';
+export { createConnector } from './lib/Connector';
+export { getc, getFacetMemberNames } from './lib/ctr';
+export { data, getDataMemberNames, getLoggedMemberNames, input, log, output, } from './lib/data';
+export { getf } from './lib/facet';
+export { installPolicies } from './lib/install';
+export { getOperationMemberNames, operation } from './lib/operation';
+export { mapDataToProp } from './lib/patch';
+export { registerCtr } from './lib/registerCtr';

package/internal/logging.d.ts

@@ -2,4 +2,5 @@ export declare function _defaultFacetLogName(facet: any): string;
 export declare function facetLogName(facet: any): any;
 export declare function log(facet: any, operationMember: any, args: any, start: any): void;
 export declare function facetState(facet: any): {};
-export declare function ctrState(ctr: any): any;
+export declare function defaultGetCtrState(ctr: any): any;
+export declare function getCtrState(ctr: any): any;

package/internal/logging.js

@@ -9,13 +9,13 @@ var __assign = (this && this.__assign) || function () {
     };
     return __assign.apply(this, arguments);
 };
-import { getLoggedMemberNames } from "../lib/data";
-import { getCtrAdmin, getFacetAdmin } from "../internal/utils";
-import { getc, getFacetMemberNames } from "../lib/ctr";
-import { options } from "./options";
+import { getCtrAdmin, getFacetAdmin } from '../internal/utils';
+import { getc, getFacetMemberNames } from '../lib/ctr';
+import { getLoggedMemberNames } from '../lib/data';
+import { options } from './options';
 export function _defaultFacetLogName(facet) {
     var ctr = getc(facet);
-    var prefix = ctr ? ctr.constructor.name + "/" : "";
+    var prefix = ctr ? ctr.constructor.name + '/' : '';
     return prefix + facet.constructor.name;
 }
 export function facetLogName(facet) {
@@ -25,26 +25,23 @@ export function facetLogName(facet) {
 function camelToSnake(string) {
     return string
         .replace(/[\w]([A-Z])/g, function (m) {
-        return m[0] + "_" + m[1];
+        return m[0] + '_' + m[1];
     })
         .toLowerCase();
 }
 var opName = function (operationMember) { return camelToSnake(operationMember).toUpperCase(); };
 export function log(facet, operationMember, args, start) {
-    var _a;
     var ctr = getc(facet);
-    var ctrAdmin = ctr ? getCtrAdmin(ctr) : undefined;
-    var getCtrState = (_a = ctrAdmin === null || ctrAdmin === void 0 ? void 0 : ctrAdmin.ctrStateOverride) !== null && _a !== void 0 ? _a : ctrState;
     var getState = ctr ? function () { return getCtrState(ctr); } : function () { return facetState(facet); };
     var operationName = opName(operationMember);
-    var label = facetLogName(facet) + "." + operationName;
+    var label = facetLogName(facet) + '.' + operationName;
     if (start) {
         console.group(label);
-        console.log("%c           args: ", "color: gray", args);
-        console.log("%c     state", "color: gray", getState());
+        console.log('%c           args: ', 'color: gray', args);
+        console.log('%c     state', 'color: gray', getState());
     }
     else {
-        console.log("%c     next", "color: gray", getState());
+        console.log('%c     next', 'color: gray', getState());
         // @ts-ignore
         console.groupEnd(label);
     }
@@ -61,7 +58,7 @@ export function facetState(facet) {
         }
     }, {});
 }
-export function ctrState(ctr) {
+export function defaultGetCtrState(ctr) {
     if (ctr) {
         return getFacetMemberNames(ctr).reduce(function (acc, facetMemberName) {
             var _a;
@@ -70,3 +67,7 @@ export function ctrState(ctr) {
         }, {});
     }
 }
+export function getCtrState(ctr) {
+    var _a, _b;
+    return ((_b = (_a = getCtrAdmin(ctr)) === null || _a === void 0 ? void 0 : _a.ctrStateOverride) !== null && _b !== void 0 ? _b : defaultGetCtrState)(ctr);
+}

package/internal/symbols.js

@@ -1,3 +1,3 @@
 export var symbols = {
-    admin: Symbol("skandha administration"),
+    admin: Symbol('skandha administration'),
 };

package/internal/utils.d.ts

@@ -1,6 +1,5 @@
 export declare function getOrCreate(obj: any, key: any, fn: any): any;
 export declare const zip: (arr: any, ...arrs: any) => any;
-export declare function getCtrClassAdmin(ctrClass: any): any;
 export declare function getCtrAdmin(ctr: any): any;
 export declare function getFacetClassAdmin(facetClass: any): any;
 export declare function getFacetAdmin(facet: any): any;

package/internal/utils.js

@@ -1,9 +1,13 @@
-var __spreadArray = (this && this.__spreadArray) || function (to, from) {
-    for (var i = 0, il = from.length, j = to.length; i < il; i++, j++)
-        to[j] = from[i];
-    return to;
+var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
+    if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {
+        if (ar || !(i in from)) {
+            if (!ar) ar = Array.prototype.slice.call(from, 0, i);
+            ar[i] = from[i];
+        }
+    }
+    return to.concat(ar || Array.prototype.slice.call(from));
 };
-import { symbols } from "./symbols";
+import { symbols } from './symbols';
 export function getOrCreate(obj, key, fn) {
     if (!obj[key]) {
         obj[key] = fn();
@@ -16,12 +20,9 @@ export var zip = function (arr) {
         arrs[_i - 1] = arguments[_i];
     }
     return arr.map(function (val, i) {
-        return arrs.reduce(function (a, arr) { return __spreadArray(__spreadArray([], a), [arr[i]]); }, [val]);
+        return arrs.reduce(function (a, arr) { return __spreadArray(__spreadArray([], a, true), [arr[i]], false); }, [val]);
     });
 };
-export function getCtrClassAdmin(ctrClass) {
-    return getOrCreate(ctrClass, symbols.admin, function () { return ({}); });
-}
 export function getCtrAdmin(ctr) {
     return getOrCreate(ctr, symbols.admin, function () { return ({}); });
 }

package/lib/Connector.d.ts

@@ -0,0 +1,5 @@
+declare type OptionsT = {
+    strict: boolean;
+};
+export declare const createConnector: (obj: any, options?: OptionsT) => any;
+export {};

package/lib/Connector.js

@@ -0,0 +1,107 @@
+import { mapDataToProp } from './patch';
+function _path(path, obj) {
+    var result = obj;
+    for (var _i = 0, _a = path.split('.'); _i < _a.length; _i++) {
+        var part = _a[_i];
+        result = result === null || result === void 0 ? void 0 : result[part];
+        if (result === undefined)
+            return result;
+    }
+    return result;
+}
+var Connector = /** @class */ (function () {
+    function Connector(obj, options) {
+        var _this = this;
+        var _a;
+        this.entityByKey = {};
+        this.getOrCreateEntity = function (key) {
+            if (_this.entityByKey[key])
+                return _this.entityByKey[key];
+            var obj = _path(key, _this.obj);
+            var entity = new Proxy(new Entity(obj), {
+                get: function (target, key) {
+                    return target[key] || target.getOrCreateField(key);
+                },
+                set: function (target, key, value) {
+                    target.fieldByName[key] = value;
+                    return true;
+                },
+            });
+            _this.entityByKey[key] = entity;
+            return entity;
+        };
+        this.connect = function () {
+            for (var _i = 0, _a = Object.values(_this.entityByKey); _i < _a.length; _i++) {
+                var entity = _a[_i];
+                _this._connectEntity(entity);
+            }
+        };
+        this._connectEntity = function (entity) {
+            var _loop_1 = function (entry) {
+                var name_1 = entry[0], field = entry[1];
+                if (_this.options.strict && !(name_1 in entity.obj)) {
+                    throw new Error("Cannot override the field ".concat(name_1, " in ").concat(entity.obj, ".") +
+                        'Field not found. Disable strict mode to ignore this error.');
+                }
+                mapDataToProp(entity.obj, name_1, function () {
+                    return field.getSource();
+                });
+            };
+            for (var _i = 0, _a = Object.entries(entity.fieldByName); _i < _a.length; _i++) {
+                var entry = _a[_i];
+                _loop_1(entry);
+            }
+        };
+        this.options = {
+            strict: (_a = options === null || options === void 0 ? void 0 : options.strict) !== null && _a !== void 0 ? _a : true,
+        };
+        this.obj = obj;
+    }
+    return Connector;
+}());
+export var createConnector = function (obj, options) {
+    var con = new Connector(obj, options);
+    return new Proxy(con, {
+        get: function (target, key) {
+            var _a;
+            return (_a = target[key]) !== null && _a !== void 0 ? _a : target.getOrCreateEntity(key);
+        },
+    });
+};
+var Entity = /** @class */ (function () {
+    function Entity(obj) {
+        var _this = this;
+        this.fieldByName = {};
+        this.getOrCreateField = function (name) {
+            var _a;
+            // If we create a new field then we should *not* store it in fieldByName.
+            return (_a = _this.fieldByName[name]) !== null && _a !== void 0 ? _a : new Field(_this.obj, name);
+        };
+        this.obj = obj;
+    }
+    return Entity;
+}());
+var Field = /** @class */ (function () {
+    function Field(obj, name) {
+        var _this = this;
+        this.transforms = [];
+        this.getSource = function () {
+            if (!(_this.name in _this.obj)) {
+                throw new Error("Field ".concat(_this.name, " does not exist on object ").concat(_this.obj));
+            }
+            var result = _this.obj[_this.name];
+            for (var _i = 0, _a = _this.transforms; _i < _a.length; _i++) {
+                var tf = _a[_i];
+                result = tf(result);
+            }
+            return result;
+        };
+        this.obj = obj;
+        this.name = name;
+    }
+    Field.prototype.tf = function (transform) {
+        this.transforms.push(transform);
+        return this;
+    };
+    return Field;
+}());

package/lib/ctr.js

@@ -1,4 +1,4 @@
-import { getCtrAdmin, getFacetAdmin } from "../internal/utils";
+import { getCtrAdmin, getFacetAdmin } from '../internal/utils';
 export function getc(facet) {
     return getFacetAdmin(facet).parentContainer;
 }

package/lib/data.js

@@ -1,4 +1,4 @@
-import { getFacetClassAdmin } from "../internal/utils";
+import { getFacetClassAdmin } from '../internal/utils';
 export function log(dataHost, dataMember, descriptor) {
     var _a;
     if (descriptor === void 0) { descriptor = undefined; }

package/lib/facet.d.ts

@@ -1,9 +1,3 @@
-import { ClassT, GetterT, ClassMemberT } from "..";
-export declare function facet(facetHost: any, facetMember: any, descriptor?: undefined): undefined;
-export declare function registerFacets(ctr: any, options: {
-    name?: string;
-    members?: string[];
-    ctrState?: Function;
-}): void;
-export declare function getf(facetClass: ClassT, ctr?: any): any;
-export declare function getm<T = any>(classMember: ClassMemberT): GetterT<T>;
+import { ClassT } from '..';
+export declare function facetClassName(facetClass: ClassT): any;
+export declare function getf(facetClass: ClassT | string, ctr?: any): any;

package/lib/facet.js

@@ -1,52 +1,17 @@
-import { setCtr } from "./ctr";
-import { getCtrClassAdmin, getCtrAdmin, getFacetAdmin, } from "../internal/utils";
-import { options as skandhaOptions } from "../internal/options";
-import { ctrState as getCtrState } from "../internal/logging";
-export function facet(facetHost, facetMember, descriptor) {
-    var _a;
-    if (descriptor === void 0) { descriptor = undefined; }
-    var ctrClassAdmin = getCtrClassAdmin(facetHost.constructor);
-    ctrClassAdmin.facetMembers = (_a = ctrClassAdmin.facetMembers) !== null && _a !== void 0 ? _a : [];
-    ctrClassAdmin.facetMembers.push(facetMember);
-    return descriptor;
-}
-export function registerFacets(ctr, options) {
-    var _a, _b, _c, _d, _e;
-    var ctrName = (_a = options.name) !== null && _a !== void 0 ? _a : ctr.constructor.name;
-    var ctrAdmin = getCtrAdmin(ctr);
-    ctrAdmin.facetMembers = (_b = ctrAdmin.facetMembers) !== null && _b !== void 0 ? _b : [];
-    ctrAdmin.facetByFacetClassName = (_c = ctrAdmin.facetByFacetClassName) !== null && _c !== void 0 ? _c : {};
-    ctrAdmin.ctrStateOverride = options.ctrState;
-    ((_e = (_d = options.members) !== null && _d !== void 0 ? _d : getCtrClassAdmin(ctr.constructor).facetMembers) !== null && _e !== void 0 ? _e : Object.getOwnPropertyNames(ctr)).forEach(function (member) {
-        ctrAdmin.facetMembers.push(member);
-        var facet = ctr[member];
-        setCtr(facet, ctr);
-        var facetAdmin = getFacetAdmin(facet);
-        facetAdmin.logName = ctrName + "/" + facet.constructor.name;
-        var className = facet.constructor.name;
-        if (ctrAdmin.facetByFacetClassName[className] !== undefined) {
-            console.error("Two facets of same type " + className + " in container " + ctrName);
-        }
-        ctrAdmin.facetByFacetClassName[className] = facet;
-        if (skandhaOptions.logging) {
-            console.log("%c     Ctr initialized", "color: gray", getCtrState(ctr));
-        }
-    });
+import { getCtrAdmin } from '../internal/utils';
+export function facetClassName(facetClass) {
+    return facetClass.className ? facetClass.className() : facetClass.name;
 }
 export function getf(facetClass, ctr) {
     var _a;
     if (!ctr)
         return function (ctr) { return getf(facetClass, ctr); };
-    var facet = (_a = getCtrAdmin(ctr).facetByFacetClassName) === null || _a === void 0 ? void 0 : _a[facetClass.name];
+    var facet = typeof facetClass === 'string'
+        ? ctr[facetClass]
+        : (_a = getCtrAdmin(ctr).facetByFacetClassName) === null || _a === void 0 ? void 0 : _a[facetClassName(facetClass)];
     if (!facet) {
-        console.error("No facet " + facetClass.name + " in container " + ctr.constructor.name);
+        var facetName = facetClass === 'string' ? facetClass : facetClassName(facetClass);
+        console.error("No facet ".concat(facetName, " in container ").concat(getCtrAdmin(ctr).logName));
     }
     return facet;
 }
-export function getm(classMember) {
-    var f = function (ctr) { var _a; return getf(classMember[0], (_a = classMember[2]) !== null && _a !== void 0 ? _a : ctr)[classMember[1]]; };
-    // Set some properties on f to easy debugging later
-    f.facetClassName = classMember[0].name;
-    f.facetMemberName = classMember[1];
-    return f;
-}

package/lib/operation.js

@@ -34,9 +34,9 @@ var __generator = (this && this.__generator) || function (thisArg, body) {
         if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
     }
 };
-import { options } from "../internal/options";
-import { log } from "../internal/logging";
-import { getFacetClassAdmin } from "../internal/utils";
+import { log } from '../internal/logging';
+import { options } from '../internal/options';
+import { getFacetClassAdmin } from '../internal/utils';
 function _operation(target, propertyName, descriptor, punctualOptions) {
     var _a;
     var f = descriptor.value;
@@ -44,7 +44,7 @@ function _operation(target, propertyName, descriptor, punctualOptions) {
     facetClassAdmin.operationMemberNames =
         (_a = facetClassAdmin.operationMemberNames) !== null && _a !== void 0 ? _a : [];
     facetClassAdmin.operationMemberNames.push(propertyName);
-    if (typeof descriptor.value === "function") {
+    if (typeof descriptor.value === 'function') {
         descriptor.value = !!punctualOptions.async
             ? function () {
                 var _a;

package/lib/patch.d.ts

@@ -1,5 +1 @@
-import { GetterT, ClassMemberT } from "..";
 export declare function mapDataToProp(facet: any, prop: string, getter: () => any): void;
-export declare function patchFacet(facet: any, members: any, options?: any): void;
-export declare const mapDataToFacet: ([toFacetClass, toMember, toCtr]: ClassMemberT, getter: GetterT, transform?: Function | undefined) => (ctr: any) => void;
-export declare const mapDatasToFacet: ([toFacetClass, toMember, toCtr]: ClassMemberT, getters: Array<GetterT>, transform: Function) => (ctr: any) => void;

package/lib/patch.js

@@ -1,17 +1,3 @@
-var __assign = (this && this.__assign) || function () {
-    __assign = Object.assign || function(t) {
-        for (var s, i = 1, n = arguments.length; i < n; i++) {
-            s = arguments[i];
-            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
-                t[p] = s[p];
-        }
-        return t;
-    };
-    return __assign.apply(this, arguments);
-};
-import { getf } from "./facet";
-import { facetLogName } from "../internal/logging";
-import { getDataMemberNames } from "./data";
 export function mapDataToProp(facet, prop, getter) {
     delete facet[prop];
     Object.defineProperty(facet, prop, {
@@ -20,66 +6,3 @@ export function mapDataToProp(facet, prop, getter) {
         configurable: true,
     });
 }
-export function patchFacet(facet, members, options) {
-    var _a;
-    var dataMemberNames = getDataMemberNames(facet);
-    for (var prop in members) {
-        if ((_a = options === null || options === void 0 ? void 0 : options.warnIfNotADataMember) !== null && _a !== void 0 ? _a : true) {
-            if (!dataMemberNames.includes(prop)) {
-                console.error("Patching a property " + prop + " that wasn't decorated with " +
-                    ("@data, @input or @output in " + facetLogName(facet)));
-            }
-        }
-        try {
-            delete facet[prop];
-        }
-        catch (_b) {
-            console.error("Could not delete property " + prop + " from facet " + facetLogName(facet) +
-                ". In case you are using mobx (or skandha-mobx), this can happen " +
-                "when makeObservable (or makeCtrObservable) is called before " +
-                "patching a property. Try calling these functions as late as " +
-                "possible.");
-        }
-        Object.defineProperty(facet, prop, __assign(__assign({}, members[prop]), { enumerable: true, configurable: true }));
-    }
-}
-export var mapDataToFacet = function (_a, getter, transform) {
-    var toFacetClass = _a[0], toMember = _a[1], toCtr = _a[2];
-    return function (ctr) {
-        var _a;
-        var patch = (_a = {},
-            _a[toMember] = {
-                get: function () {
-                    var context = {
-                        ctr: toCtr !== null && toCtr !== void 0 ? toCtr : ctr,
-                        getter: getter,
-                        toClassMember: [toFacetClass, toMember],
-                        data: getter(ctr),
-                    };
-                    return transform ? transform(context.data) : context.data;
-                },
-            },
-            _a);
-        patchFacet(getf(toFacetClass, toCtr !== null && toCtr !== void 0 ? toCtr : ctr), patch);
-    };
-};
-export var mapDatasToFacet = function (_a, getters, transform) {
-    var toFacetClass = _a[0], toMember = _a[1], toCtr = _a[2];
-    return function (ctr) {
-        var _a;
-        var patch = (_a = {},
-            _a[toMember] = {
-                get: function () {
-                    var context = {
-                        ctr: toCtr !== null && toCtr !== void 0 ? toCtr : ctr,
-                        getters: getters,
-                        toClassMember: [toFacetClass, toMember],
-                        datas: getters.map(function (getter) { return getter(ctr); }),
-                    };
-                    return transform.apply(void 0, context.datas);
-                },
-            },
-            _a);
-        patchFacet(getf(toFacetClass, toCtr !== null && toCtr !== void 0 ? toCtr : ctr), patch);
-    };
-};

package/lib/registerCtr.d.ts

@@ -0,0 +1,6 @@
+export declare type OptionsT = {
+    name: string;
+    facets?: string[];
+    ctrState?: Function;
+};
+export declare function registerCtr(ctr: any, options: OptionsT): void;

package/lib/registerCtr.js

@@ -0,0 +1,31 @@
+import { getCtrState } from '../internal/logging';
+import { options as skandhaOptions } from '../internal/options';
+import { getCtrAdmin, getFacetAdmin } from '../internal/utils';
+import { setCtr } from './ctr';
+import { facetClassName } from './facet';
+export function registerCtr(ctr, options) {
+    var _a, _b, _c;
+    var ctrAdmin = getCtrAdmin(ctr);
+    ctrAdmin.logName = options.name;
+    ctrAdmin.facetMembers = (_a = ctrAdmin.facetMembers) !== null && _a !== void 0 ? _a : [];
+    ctrAdmin.facetByFacetClassName = (_b = ctrAdmin.facetByFacetClassName) !== null && _b !== void 0 ? _b : {};
+    ctrAdmin.ctrStateOverride = options.ctrState;
+    ((_c = options.facets) !== null && _c !== void 0 ? _c : Object.getOwnPropertyNames(ctr)).forEach(function (facetName) {
+        var facet = ctr[facetName];
+        setCtr(facet, ctr);
+        ctrAdmin.facetMembers.push(facetName);
+        if (!facet.constructor.className) {
+            console.error("Facet ".concat(facetName, " of container ").concat(ctrAdmin.logName, " ") +
+                "does not have a static className function");
+        }
+        var className = facetClassName(facet.constructor);
+        getFacetAdmin(facet).logName = "".concat(ctrAdmin.logName, "/").concat(className);
+        if (ctrAdmin.facetByFacetClassName[className] !== undefined) {
+            console.error("Two facets of same type ".concat(className, " in container ").concat(ctrAdmin.logName));
+        }
+        ctrAdmin.facetByFacetClassName[className] = facet;
+    });
+    if (skandhaOptions.logging) {
+        console.log('%c     %s ctr initialized', 'color: gray', ctrAdmin.logName, getCtrState(ctr));
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skandha",
-  "version": "0.6.0",
+  "version": "0.9.1",
   "description": "Create data containers with modular behaviours",
   "main": "index.js",
   "repository": "https://github.com/mnieber/skandha.git",