skandha 0.5.0 → 0.9.0

package/README.md

@@ -2,16 +2,10 @@
 
 ## 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.
+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
 
@@ -19,322 +13,265 @@ minimal, they can be generic, which leads to better code reuse.
 - 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
+## Snippet
 
-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).
+```
+// file: Selection.ts
+import { input, output, operation } from 'skandha';
+import { host, stub } from 'aspiration';
 
-## Explanation
+export type SelectionParamsT = { itemId?: string; isShift?: boolean; isCtrl?: boolean; };
 
-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.
+export class Selection<ValueT = any> {
+  static className = () => 'Selection';
 
-### Containers and Facets
+  @input selectableIds: Array<string> = stub();
+  @output ids: Array<string> = [];
+  @output anchorId?: string;
+  @output items: Array<ValueT> = stub();
 
-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.
+  @operation @host(['selectionParams'], selectItemDefaultCbs) selectItem(
+    selectionParams: SelectionParamsT
+  ) {
+    return (cbs: Selection_selectItem) => {
+      cbs.select();
+    };
+  }
+}
+```
 
-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.
+## Fact: the Selection facet has input, data and output members
 
-Our initial code is:
+In the snippet above we see a so-called Facet class. A facet class implements a reusable behaviour. The `Selection` facet stores a list of selectable ids and has a `selectItem` function that allows you to select from those ids. The result of the selection is stored in the `ids`, `anchorId` and `items` fields. Note that `selectItem` is an empty function. The exact method for doing the selection is determined by a callback function, as we shall see later.
 
-```
-    class Selection<TodoT> {}
+## Fact: the Selection facet has a static className function
 
-    class Highlight<TodoT> {}
+Various facets are usually combined in a single container. To allow you to look up a facet by it's name, each facet class implements the static `className` function.
 
-    class Filtering<TodoT> {}
+## Fact: the `selectItem` function uses a callback function
 
-    class Inputs {
-      @data todoById: TodoByIdT = {};
-    }
+We shall see later how callbacks are installed in a facet. For now, it's sufficient to understand that `selectItem` (the host function) executes the `cbs.selectItem()` callback function. This callback function will have access to all parameters of the host function (in this case: `selectionParams`).
 
-    class Outputs {
-      @data filteredTodoById: TodoByIdT = {};
-    }
+## Snippet
 
-    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>();
+```
+// file: Selection.ts
+export class Selection_selectItem extends Cbs {
+  selectionParams: SelectionParamsT = stub();
+  select() {}
+}
+```
+
+```
+// file: createContainer.ts
+import { registerCtr } from 'skandha';
+
+const createContainer() {
+  const ctr = {
+    selection: new Selection()
+  };
+
+  setCallbacks(ctr.selection, {
+    selectItem: {
+      select(this: Selection_selectItem): {
+        handleSelectItem(ctr.selection, this.selectionParams);
+      },
     }
+  });
+
+  // If you omit `members` then all fields of `ctr` are included.
+  registerCtr(ctr, { name: 'TodosCtr', members: ['selection'] });
+  return ctr;
+}
 ```
 
-Notes:
+## Fact: a Cbs class defines a set of callbacks
+
+In the above snippet we see that the `Selection_selectItem` class defines the callbacks that can be installed for the `selectItem` function of the `Selection` facet. This class also defines the parameters that are received by the host function and made available to each callback.
+
+## Fact: the setCallbacks function installs the callbacks for the Selection facet
 
-- The `@data` and `@operation` decorators mark the fields in the facet that make up its abstract interface.
-  Clients should use only these fields.
+In the same snippet we see that `setCallbacks` is called to install the `select` callback function. This callback function forwards to a helper function called `handleSelectItem`. Note that the `Selection_selectItem` instance is available through the `this` constant.
 
-### Implementing the Selection facet
+## Fact: the registerCtr function registers the container with SkandhaJS
 
-We will first implement the Selection facet. The key requirements are that:
+The purpose of calling registerCtr on the container is twofold:
 
-- 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.
+- it makes it possible to look up a facet by its name or class, e.g. `getf(ctr, Selection)` returns `ctr.selection`.
+- it tells SkandhaJS what facets should be included in log reports. When the client calls any facet function that is decorated with @operation then SkandhaJS will log the entire container before and after the operation was executed. Logging can be enabled using the `setOptions` function.
 
-This is our proposal for the Selection facet:
+## Snippet: the handleSelectItem functon
 
 ```
-export class Selection_select extends Cbs {
-  selectionParams: SelectionParamsT = stub();
-  selectItem() {}
-}
+// file: handleSelectItem.ts
+export function handleSelectItem(
+  facet: Selection,
+  { itemId, isShift, isCtrl }: SelectionParamsT
+) {
+  if (itemId === undefined) {
+    facet.ids = [];
+    facet.anchorId = undefined;
+    return;
+  }
 
-class Selection<TodoT> {
-  @data selectableIds: Array<string> = stub();
-  @data ids: Array<string> = [];
-  @data anchorId?: string;
-  @data items?: Array<ValueT>;
+  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];
+  }
 
-  @operation @host selectItem(selectionParams: SelectionParamsT) {
-    return (cbs: Selection_select) => {
-      if (!this.selectableIds.includes(selectionParams.itemId)) {
-        throw Error(`Invalid id: ${selectionParams.itemId}`);
-      }
-      cbs.selectItem();
-    }
+  // Move the anchor
+  if (!facet.anchorId || !(isCtrl || isShift)) {
+    facet.anchorId = itemId;
   }
 }
 ```
 
-Notes:
-
-- 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.
+## Fact: the handleSelectItem does the actual work of selecting items
 
-### Implementing the Highlight and Filtering facets
+For completeness, we show how `handleSelectItem` is implemented. Note that this function stores the results directly in the selection facet instance.
 
-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):
+## Snippet: the Highlight facet
 
 ```
+// file: Highlight.ts
+export class Highlight_highlightItem extends Cbs {
+  id: string = stub();
+  scrollItemIntoView() {}
+}
+
 export class Highlight<ValueT = any> {
-  @data id: string | undefined;
+  @data id?: string;
   @data item?: ValueT;
 
-  @operation @host highlightItem(id: string) {
+  @operation @host(["id"]) highlightItem(id: string) {
     return (cbs: Highlight_highlightItem) => {
       this.id = id;
-    };
-  }
-}
-
-export class Filtering<ValueT = any> {
-  @data isEnabled: boolean = false;
-  @data filter: FilterT = () => [];
-
-  @data inputItems?: Array<ValueT>;
-  @data get filteredItems() {
-    return this.isEnabled ? this.filter(this.inputItems) : this.inputItems;
-  }
-
-  @operation @host apply(filter: FilterT) {
-    return (cbs: Filtering_apply) => {
-      this.filter = filter;
-      this.isEnabled = true;
-    };
-  }
-
-  @operation @host setEnabled(flag: boolean) {
-    return (cbs: Filtering_setEnabled) => {
-      this.isEnabled = flag;
+      if (cbs.scrollItemIntoView) {
+        cbs.scrollItemIntoView();
+      }
     };
   }
 }
 ```
 
-### Implementing the callback objects
+## Fact: the `Highlight` facet implements the highlight behaviour
 
-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 `Highlight` snippet has a similar structure as the `Selection` facet. It has a callback function for scrolling the highlighted item into view. Note that the `highlightItem` function does not set the `item` field, because the facet only deals with ids. We shall later see how the `item` field is set by looking up the item in an external collection.
 
-- 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))
+## Snippet: a container with Selection and Highlight
 
 ```
-class TodosCtr {
-  // ...
-
-  constructor() {
-    registerFacets(this);
-    this._setCallbacks();
-  }
-
-  _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);
-        },
+// file: createContainer.ts
+const createContainer() {
+  const ctr = {
+    selection: new Selection(),
+    highlight: new Highlight()
+  };
+
+  setCallbacks(ctr.selection, {
+    selectItem: {
+      select(this: Selection_selectItem): {
+        handleSelectItem(ctr.selection, this.selectionParams);
+
+        if (!this.selectionParams.isShift && !this.selectionParams.isCtrl) {
+          ctr.highlight.highlightItem(this.selectionParams.itemId);
+        }
+
+        // The above 3 lines could be extracted in a reusable helper function, e.g.
+        // highlightFollowsSelection(ctr, this.selectionParams);
       },
-    });
-  }
-}
+    }
+  });
 
-export function highlightFollowsSelection(
-  selection: Selection,
-  selectionParams: SelectionParamsT
-) {
-  const {isCtrl, isShift, itemId} = selectionParams;
-  const ctr = getc(selection);
-  if (!isCtrl && !isShift) {
-    getf(Highlight, ctr).highlightItem(itemId);
-  }
-}
+  return ctr;
 ```
 
-Notes:
+## Fact: callbacks allow you to create co-ordinated behaviours
 
-- 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.
+Above we see for the first time how SkandhaJS helps you to create co-ordinated behaviours. When the client calls `ctr.selection.selectItem` and the `select` callback is executed, then the callback ensures that the selected item is also highlighted. As the comment in the snippet suggests, we can make the body of the `select` callback more readable by extracting some of the code in a `highlightFollowsSelection` helper function.
 
-### Mapping data onto the container, and between facets
+## Snippet: a container with Selection, Highlight and Filtering
 
-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).
+```
+// file: createContainer.ts
+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);
+      },
+    }
+  });
 
-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:
+  setCallbacks(filtering, {
+    apply: {
+      exit() {
+        highlightIsCorrectedOnFilterChange(ctr);
+      },
+    },
+  });
 
-```
-  _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);
-  }
+  return ctr;
+}
 ```
 
-Notes:
+## Fact: the `exit` callback function is called at the end of the host 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))`,
+In the snippet we add a filtering facet that has an `apply` host function. In this host function, we can install an `exit` callback that corrects the highlight when the filter changes (because the filter may hide the highlighted item). The `exit` callback is called at the end of the host function. Similarly, the `enter` callback is called at the beginning.
 
-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`:
+## Snippet: mapping data onto each facet
 
 ```
-  _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 inputs = { todos: loadTodos() };
+  const outputs = { filteredTodoById: {} };
+
+  const con = createConnector({
+    selection: () => ctr.selection,
+    highlight: () => ctr.highlight,
+    filtering: () => ctr.filtering`,
+    inputs: () => inputs,
+    outputs: () => outputs,
+  });
+
+  const lookUpTodo = (id: string) => outputs.filteredTodoById[id];
+
+  con.filtering.inputItems = con.inputs.todos;
+  con.outputs.filteredTodoById = con.filtering.filteredItems.tf(R.indexBy('id));
+  con.selection.selectableIds = con.outputs.filteredTodoById.tf(R.keys);
+  con.selection.item = con.selection.ids.tf(lookUpTodos);
+  con.highlight.item = con.highlight.id.tf(lookUpTodo);
+
+  con.connect();
 ```
 
-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:
+## Fact: the Connector class maps data between objects
 
-```
-  _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);
-  }
-```
+The Connector instance allows you to map data from one object onto another object. In our example, the `inputs.todos` field is mapped onto the `filtering.inputItems` field. What the `Connector` class does is turn `filtering.inputItems` into a `get` property that returns `filtering.inputItems`.
+The snippet contains three steps. In the first step we declare the objects, such as `selection`, `filtering`, etc. For each object, we specify the getter function that returns the object. In the second step, we declare relations between the different fields of these objects. In this step, we can also declare one or more transformation functions (such as `lookUpTodo`) that should be used in the mapping. In the final step, we call `con.connect` to create the `get` properties that perform the declared mappings.
 
 ### 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. An operation is any facet member function decorated with @operation.
+This will log Facet members that are decorated with `@data` (or `@input`, or `@output`) 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
@@ -344,23 +281,14 @@ used to from Redux:
 
 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:
+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: 'TodosCtr'},
+});
 ```
 
 ## Conclusion
@@ -373,5 +301,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, addCleanUpFunctionToCtr, cleanUpCtr, } 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, addCleanUpFunctionToCtr, cleanUpCtr, } 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 FunctionByNameT = {
+    [name: string]: Function;
+};
+export declare const createConnector: (entities: FunctionByNameT) => any;
+export {};

package/lib/Connector.js

@@ -0,0 +1,98 @@
+import { mapDataToProp } from './patch';
+var Connector = /** @class */ (function () {
+    function Connector(entities, options) {
+        var _this = this;
+        var _a;
+        this.entityByName = {};
+        this.connect = function () {
+            for (var _i = 0, _a = Object.values(_this.entityByName); _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];
+                var obj = entity.getObj();
+                if (_this.options.strict && !(name_1 in obj)) {
+                    throw new Error("Cannot override the field ".concat(name_1, " in ").concat(obj, ".") +
+                        'Field not found. Disable strict mode to ignore this error.');
+                }
+                mapDataToProp(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,
+        };
+        for (var _i = 0, _b = Object.entries(entities); _i < _b.length; _i++) {
+            var entry = _b[_i];
+            var name_2 = entry[0], getObj = entry[1];
+            this.entityByName[name_2] = new Entity(getObj);
+        }
+    }
+    return Connector;
+}());
+export var createConnector = function (entities) {
+    var con = new Connector(entities);
+    return new Proxy(con, {
+        get: function (target, key) {
+            // Code example:
+            //
+            // const con = createConnector({ foo: () => myFoo });
+            //
+            // When you call `con.foo` then you
+            // receive `con.entityByName.foo.fieldByName`.
+            //
+            // con.foo.bar = 5;  // Equivalent to: con.entityByName.foo.fieldByName.bar = 5
+            //
+            // When you call `con.connect` then a normal lookup of the `connect`
+            // member in `con` is performed.
+            var _a, _b;
+            return (_b = (_a = target.entityByName[key]) === null || _a === void 0 ? void 0 : _a.fieldByName) !== null && _b !== void 0 ? _b : target[key];
+        },
+    });
+};
+var Entity = /** @class */ (function () {
+    function Entity(getObj) {
+        var _this = this;
+        this.getObj = getObj;
+        this.fieldByName = new Proxy({}, {
+            get: function (target, key) {
+                var _a;
+                return (_a = target[key]) !== null && _a !== void 0 ? _a : new Field(_this, key);
+            },
+        });
+    }
+    return Entity;
+}());
+var Field = /** @class */ (function () {
+    function Field(entity, name) {
+        var _this = this;
+        this.transforms = [];
+        this.getSource = function () {
+            var obj = _this.entity.getObj();
+            if (!(_this.name in obj)) {
+                throw new Error("Field ".concat(_this.name, " does not exist on object ").concat(obj));
+            }
+            var result = obj[_this.name];
+            for (var _i = 0, _a = _this.transforms; _i < _a.length; _i++) {
+                var tf = _a[_i];
+                result = tf(result);
+            }
+            return result;
+        };
+        this.entity = entity;
+        this.name = name;
+    }
+    Field.prototype.tf = function (transform) {
+        this.transforms.push(transform);
+        return this;
+    };
+    return Field;
+}());

package/lib/ctr.d.ts

@@ -1,5 +1,3 @@
 export declare function getc<CtrT = any>(facet: any): CtrT;
 export declare function setCtr(facet: any, ctr: any): void;
 export declare function getFacetMemberNames(ctr: any): any;
-export declare function addCleanUpFunctionToCtr(ctr: any, f: any): void;
-export declare function cleanUpCtr(ctr: any): void;

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;
 }
@@ -9,15 +9,3 @@ export function getFacetMemberNames(ctr) {
     var _a;
     return (_a = getCtrAdmin(ctr).facetMembers) !== null && _a !== void 0 ? _a : [];
 }
-export function addCleanUpFunctionToCtr(ctr, f) {
-    var _a;
-    var ctrAdmin = getCtrAdmin(ctr);
-    ctrAdmin.cleanUpFunctions = (_a = ctrAdmin.cleanUpFunctions) !== null && _a !== void 0 ? _a : [];
-    ctrAdmin.cleanUpFunctions.push(f);
-}
-export function cleanUpCtr(ctr) {
-    var _a;
-    var ctrAdmin = getCtrAdmin(ctr);
-    ctrAdmin.cleanUpFunctions = (_a = ctrAdmin.cleanUpFunctions) !== null && _a !== void 0 ? _a : [];
-    ctrAdmin.cleanUpFunctions.forEach(function (x) { return x(); });
-}

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,47 +1,17 @@
-import { setCtr } from "./ctr";
-import { getCtrClassAdmin, getCtrAdmin, getFacetAdmin, } from "../internal/utils";
-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 " + options.name);
-        }
-        ctrAdmin.facetByFacetClassName[className] = facet;
-    });
+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,57 +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)));
-            }
-        }
-        delete facet[prop];
-        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;
+    members?: 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.members) !== null && _c !== void 0 ? _c : Object.getOwnPropertyNames(ctr)).forEach(function (member) {
+        var facet = ctr[member];
+        setCtr(facet, ctr);
+        ctrAdmin.facetMembers.push(member);
+        if (!facet.constructor.className) {
+            console.error("Facet ".concat(member, " 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.5.0",
+  "version": "0.9.0",
   "description": "Create data containers with modular behaviours",
   "main": "index.js",
   "repository": "https://github.com/mnieber/skandha.git",