skandha 0.4.0 → 0.7.0

package/README.md

@@ -2,16 +2,19 @@
 
 ## 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.
+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. When combining behaviors in a container, you need to
+make sure that they 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.
 
-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**
+
+In a Skandha container, behaviors are implemented using classes that are called facets, and they are found by their class name. The recommendation is to add a `static className` function to each facet class. If you omit this function, then Skandha will use the automatically generated class name, which can cause problems with the mangling of classnames in your minification tool.
+
+---
 
 ## Links
 
@@ -22,128 +25,167 @@ minimal, they can be generic, which leads to better code reuse.
 
 ## Example code
 
-The full example code for this README can be found [here](http://github.com/mnieber/skandha-sample). 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 more reflective of a real use-case as it uses the reusable behaviours
+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 first 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).
 
 ## Explanation
 
-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.
-
-### Containers and Facets
-
-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.
+### The Selection facet
 
-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.
-
-Our initial code is:
+As mentioned above, behaviors in Skandha are implemented as classes that are called facets. Let's start by looking at a reusable
+Selection facet. Before we show how it's implemented, here is an example of using it to select a range of
+items from id `2` to id `5`:
 
 ```
-    class Selection<TodoT> {}
-
-    class Highlight<TodoT> {}
-
-    class Filtering<TodoT> {}
-
-    class Inputs {
-      @data todoById: TodoByIdT = {};
-    }
+const ctr = createContainer();
+ctr.selection.selectableIds = ["1", "2", "3", "4", "5", "6", "7", "8", "9"];
 
-    class Outputs {
-      @data filteredTodoById: TodoByIdT = {};
-    }
-
-    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>();
-    }
+ctr.selection.selectItem({itemId: "2"});
+ctr.selection.selectItem({itemId: "5", isShift: true});
+console.log(ctr.selection.ids);
 ```
 
-Notes:
-
-- The `@data` and `@operation` decorators mark the fields in the facet that make up its abstract interface.
-  Clients should use only these fields.
+Note that the key function call here is `selection.selectItem`. Let's look at how it's implemented. First of all, we need a type that holds the selection parameters:
 
-### Implementing the Selection facet
-
-We will first implement the Selection facet. The key requirements are that:
-
-- 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.
+```
+export type SelectionParamsT = {
+  itemId: string | undefined;
+  isShift?: boolean;
+  isCtrl?: boolean;
+};
+```
 
-This is our proposal for the Selection facet:
+The next step is less obvious: we define a helper class that declares the arguments and callbacks of
+`selection.selectItem`. Why is this needed? The reason for using a callback function is that we
+don't want to hard code how selection is performed (e.g. what the effect of the shift and ctrl key is),
+because this would limit the reusability. The reason for storing the arguments of `selection.selectItem`
+is that this makes it easier to pass these arguments to other functions that want to use
+them. For example, if a side-effect of selection is to highlight the item, then we
+would like to pass the `SelectionParamsT` instance also to a `highlightSelectedItem` policy function
+(this will be explained in detail later). The helper class looks like this:
 
 ```
-export class Selection_select extends Cbs {
+export class Selection_selectItem extends Cbs {
   selectionParams: SelectionParamsT = stub();
-  selectItem() {}
+  select() {}
 }
+```
 
-class Selection<TodoT> {
+Next, we add the `Selection` class itself that has a `selectItem` function that checks the selection
+parameters and then calls the `select` callback function.
+
+```
+class Selection<ValueT> {
   @data selectableIds: Array<string> = stub();
   @data ids: Array<string> = [];
   @data anchorId?: string;
-  @data items?: Array<ValueT>;
+  @data items?: Array<ValueT>;  // ignore this field for now...
 
   @operation @host selectItem(selectionParams: SelectionParamsT) {
-    return (cbs: Selection_select) => {
+    return (cbs: Selection_selectItem) => {
       if (!this.selectableIds.includes(selectionParams.itemId)) {
         throw Error(`Invalid id: ${selectionParams.itemId}`);
       }
-      cbs.selectItem();
+      cbs.select();
     }
   }
 }
 ```
 
+And finally, we add the `createContainer` function that creates a `Selection` instance and implements
+the `select` callback. We don't show the code of `handleSelectItem`, but you can see it
+[here](https://github.com/mnieber/skandha-facets/blob/main/Selection.ts).
+
+```
+const createContainer() {
+  const ctr = {
+    selection: new Selection()
+  };
+
+  setCallbacks(ctr.selection, {
+    selectItem: {
+      select(this: Selection_selectItem): {
+        handleSelectItem(ctr.selection, this.selectionParams);
+      },
+    }
+  });
+
+  return ctr;
+}
+```
+
 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.
+- The `@host` decorator comes from the [Aspiration](http://github.com/mnieber/aspiration) library.
+- The `stub` function is used in callback objects to indicate that although the field is initialized with `undefined` it will receive a value later.
 
-### Implementing the Highlight and Filtering facets
+## Combining Selection with Highlight
 
-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):
+So far, we have shown a rather indirect implementation of selection. This indirect approach becomes useful
+when we add a second facet: Highlight. We will extend the example such that when the user selects an item,
+it will also be highlighted. The same approach can be used to make sure that the Filtering and Highlight
+facets work well together: if the filter is enabled, the highlight moves to an item that is not hidden by the
+filter. In general, there are many possibilities to create complex behaviors this way.
+
+Let's start by looking at the code of the `Highlight` facet:
 
 ```
+export class Highlight_highlightItem extends Cbs {
+  id: string = stub();
+  scrollItemIntoView() {}
+}
+
 export class Highlight<ValueT = any> {
   @data id: string | undefined;
-  @data item?: ValueT;
+  @data item?: ValueT;  // ignore this field for now...
 
   @operation @host highlightItem(id: string) {
     return (cbs: Highlight_highlightItem) => {
       this.id = id;
+      maybe(cbs.scrollItemIntoView).bind(cbs)();
     };
   }
 }
+```
+
+We can now update `createContainer` with the `Highlight` facet:
+
+```
+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);
+        }
+      },
+    }
+  });
 
+  return ctr;
+```
+
+### Adding the Filtering facet
+
+Now, let's add filtering. For brevity, the definition of `Filtering_apply` and `Filtering_enable`
+is skipped. Also, we assume that the logic for highlighting the select item is captured in a policy
+function called `highlightFollowsSelection`, and that `highlightIsCorrectedOnFilterChange` ensures
+that there is still a highlighted item when the filter changes.
+
+```
 export class Filtering<ValueT = any> {
   @data isEnabled: boolean = false;
-  @data filter: FilterT = () => [];
-
+  @data filter: FilterT = (ValueT[]) => [];
   @data inputItems?: Array<ValueT>;
+
   @data get filteredItems() {
     return this.isEnabled ? this.filter(this.inputItems) : this.inputItems;
   }
@@ -161,172 +203,150 @@ export class Filtering<ValueT = any> {
     };
   }
 }
-```
-
-### 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();
-  }
-
-  _setCallbacks() {
-    const ctr = this;
-
-    setCallbacks(this.selection, {
-      select: {
-        selectItem(this: Selection_select): {
-          handleSelectItem(ctr.selection, this.selectionParams);
-          highlightFollowsSelection(ctr.selection, this.selectionParams);  // See below
-        },
-      }
-    });
+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);
+      },
+    }
+  });
 
-    setCallbacks(this.filtering, {
-      apply: {
-        exit() {
-          FacetPolicies.highlightIsCorrectedOnFilterChange(ctr.filtering);
-        },
+  setCallbacks(filtering, {
+    apply: {
+      exit() {
+        highlightIsCorrectedOnFilterChange(ctr);
       },
-    });
-  }
-}
+    },
+  });
 
-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:
 
-- 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.
+- There are special callback functions called `enter` and `exit` that are called at the
+  beginning and end of the operation function. An example of using the `exit` callback is shown
+  above.
 
 ### Mapping data onto the container, and between facets
 
 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).
+to achieve interesting behaviours. However, we took a shortcut by hard coding the value of
+`Selection.selectableIds`, and also we forgot to set the value of `Filtering.inputItems`. Skandha
+comes with data mapping functions for this purpose. Let's extend the container with input
+and output data structures:
+
+```
+const createContainer() {
+  // we keep all the existing code that was added above
+
+  ctr['inputs'] = {
+    todoById: {[id: string]: TodoT} = loadTodos();
+  };
 
+  ctr['outputs'] = {
+    filteredTodoById: {[id: string]: TodoT} = {};
+  };
+
+  registerFacets(ctr, { name: 'TodosCtr' });
+  return ctr;
+```
+
+Note the call to `registerFacets`, which is needed for the data mapping functions that we are about to introduce.
 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:
 
 ```
-  _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);
-  }
+mapDataToFacet(
+  ['filtering', 'inputItems'],
+  getm(['inputs', 'todoById']),
+  (x: TodoByIdT) => Object.values(x)
+)(ctr);
+
+const listToItemById = items => items.reduce((acc: any, x: TodoT) => ({ ...acc, [x.id]: x }), {})
+
+mapDataToFacet(
+  ['outputs', 'filteredTodoById'],
+  getm(['filtering', 'filteredItems']),
+  listToItemById,
+)(ctr);
 ```
 
 Notes:
 
-- 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 first argument to `mapDataToFacet` is a reference to the the facet member that receives the data. SkandhaJS will patch the
+  facet, which - in the above example - means replacing the `inputItems` of `ctr.filtering` with a `get inputItems()` property.
+- the second 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 `ctr.inputs.todoById`.
 - 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))`,
+  it means that `get inputItems()` returns `Object.values(getm(Inputs, 'todoById')(ctr))`.
+- in the calls to `mapDataToFacet`, we have to be careful to correctly spell the facet member names, such as 'filtering'.
+  It's also possible to use a class instead of a member name. For example, we could replace `['filtering', 'inputItems']` with
+  `[Filtering, 'inputItems']`.
 
 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`:
+and `Highlight.item` (these data mappings allow us to not only access the ids, but also the items themselves):
 
 ```
-  _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);
-  }
+mapDataToFacet(
+  ['selection', 'selectableIds'],
+  getm(['outputs', 'filteredTodoById']),
+  (x: TodoByIdT) => Object.keys(x)
+)(ctr);
+
+mapDatasToFacet(
+  ['selection', 'items'],
+  [
+    getm(['selections', 'ids']),
+    getm(['inputs', 'todoById']),
+  ],
+  (ids: string[], todoById: TodoByIdT) => ids.map((id) => todoById[id])
+)(ctr);
+
+mapDatasToFacet(
+  [Highlight, 'item'],
+  [
+    getm([Highlight, 'id']),
+    getm([Inputs, 'todoById']),
+  ],
+  (id: string, todoById: TodoByIdT) => todoById[id]
+)(ctr);
 ```
 
 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:
+library then we can shorten the code to the following:
 
 ```
-  _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);
-  }
+const filteredTodoById = ['outputs', 'filteredTodoById'];
+const inputTodoById = ['inputs', 'todoById'];
+const filteredItems = ['filtering', 'filteredItems'];
+
+const policies = [
+  // selection
+  selectionUsesSelectableIds(filteredTodoById, Object.keys),
+  selectionUsesItemLookUpTable(inputTodoById),
+
+  // highlighting
+  highlightUsesItemLookUpTable(inputTodoById),
+
+  // filtering
+  filteringUsesInputItems(inputTodoById, Object.values),
+  mapDataToFacet(filteredTodoById, getm(filteredItems), listToItemById),
+]
+
+installPolicies<TodosCtr>(policies, ctr);
 ```
 
 ### Logging
@@ -344,25 +364,21 @@ 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 (this function call replaces the call to `registerFacets`):
 
 ```
-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,
+  details: {
+    name: 'TodosCtr',
+  },
+});
 ```
 
+This means that by decorating your render function with `observer` you will get a re-render for any changes
+(in observable facet members) in the container.
+
 ## Conclusion
 
 SkandhaJS introduces a lot of new patterns and ideas (that are of course not in fact new) to allow you to

package/index.d.ts

@@ -1,12 +1,12 @@
-export { facetName, facetClassName, 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 { getc, getFacetMemberNames } from './lib/ctr';
+export { data, getDataMemberNames, getLoggedMemberNames, input, log, output, } from './lib/data';
+export { facet, getf, getm, registerFacets } from './lib/facet';
+export { installPolicies } from './lib/install';
+export { getOperationMemberNames, operation } from './lib/operation';
+export { mapDatasToFacet, mapDataToFacet, mapDataToProp, patchFacet, } from './lib/patch';
 export declare type ClassT = any;
 export declare type MemberNameT = string;
-export declare type ClassMemberT = [ClassT, MemberNameT];
+export declare type ClassMemberT = [ClassT, MemberNameT, any?];
 export declare type GetterT<T = any> = (ctr: any) => T;

package/index.js

@@ -1,8 +1,8 @@
-export { facetName, facetClassName, 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 { getc, getFacetMemberNames } from './lib/ctr';
+export { data, getDataMemberNames, getLoggedMemberNames, input, log, output, } from './lib/data';
+export { facet, getf, getm, registerFacets } from './lib/facet';
+export { installPolicies } from './lib/install';
+export { getOperationMemberNames, operation } from './lib/operation';
+export { mapDatasToFacet, mapDataToFacet, mapDataToProp, patchFacet, } from './lib/patch';

package/internal/logging.d.ts

@@ -1,6 +1,6 @@
-export declare function facetClassName(facetClass: any): any;
-export declare function facetName(facet: any): string;
-export declare const opName: (operationMember: any) => any;
+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,39 +9,39 @@ var __assign = (this && this.__assign) || function () {
     };
     return __assign.apply(this, arguments);
 };
-import { getLoggedMemberNames } from "../lib/data";
-import { getc, getFacetMemberNames } from "../lib/ctr";
-import { options } from "./options";
-export function facetClassName(facetClass) {
-    return facetClass.name;
-}
-export function facetName(facet) {
+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) {
+    var _a;
+    return (_a = getFacetAdmin(facet).logName) !== null && _a !== void 0 ? _a : _defaultFacetLogName(facet);
+}
 function camelToSnake(string) {
     return string
         .replace(/[\w]([A-Z])/g, function (m) {
-        return m[0] + "_" + m[1];
+        return m[0] + '_' + m[1];
     })
         .toLowerCase();
 }
-export var opName = function (operationMember) {
-    return camelToSnake(operationMember).toUpperCase();
-};
+var opName = function (operationMember) { return camelToSnake(operationMember).toUpperCase(); };
 export function log(facet, operationMember, args, start) {
     var ctr = getc(facet);
-    var getState = ctr ? function () { return ctrState(ctr); } : function () { return facetState(facet); };
+    var getState = ctr ? function () { return getCtrState(ctr); } : function () { return facetState(facet); };
     var operationName = opName(operationMember);
-    var label = facetName(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);
     }
@@ -58,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;
@@ -67,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.js

@@ -1,11 +1,13 @@
-var __spreadArrays = (this && this.__spreadArrays) || function () {
-    for (var s = 0, i = 0, il = arguments.length; i < il; i++) s += arguments[i].length;
-    for (var r = Array(s), k = 0, i = 0; i < il; i++)
-        for (var a = arguments[i], j = 0, jl = a.length; j < jl; j++, k++)
-            r[k] = a[j];
-    return r;
+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();
@@ -18,7 +20,7 @@ export var zip = function (arr) {
         arrs[_i - 1] = arguments[_i];
     }
     return arr.map(function (val, i) {
-        return arrs.reduce(function (a, arr) { return __spreadArrays(a, [arr[i]]); }, [val]);
+        return arrs.reduce(function (a, arr) { return __spreadArray(__spreadArray([], a, true), [arr[i]], false); }, [val]);
     });
 };
 export function getCtrClassAdmin(ctrClass) {

package/lib/ctr.js

@@ -1,4 +1,4 @@
-import { getCtrClassAdmin, getFacetAdmin } from "../internal/utils";
+import { getCtrAdmin, getFacetAdmin } from '../internal/utils';
 export function getc(facet) {
     return getFacetAdmin(facet).parentContainer;
 }
@@ -7,5 +7,5 @@ export function setCtr(facet, ctr) {
 }
 export function getFacetMemberNames(ctr) {
     var _a;
-    return (_a = getCtrClassAdmin(ctr.constructor).facetMembers) !== null && _a !== void 0 ? _a : [];
+    return (_a = getCtrAdmin(ctr).facetMembers) !== null && _a !== void 0 ? _a : [];
 }

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

package/lib/facet.js

@@ -1,6 +1,8 @@
-import { getFacetMemberNames, setCtr } from "./ctr";
-import { getCtrClassAdmin, getCtrAdmin } from "../internal/utils";
-import { facetClassName } from "../internal/logging";
+import { getCtrState } from '../internal/logging';
+import { options as skandhaOptions } from '../internal/options';
+import { getCtrAdmin, getCtrClassAdmin, getFacetAdmin, } from '../internal/utils';
+import { setCtr } from './ctr';
+// Registers facetMember as a facet in the facetHost class
 export function facet(facetHost, facetMember, descriptor) {
     var _a;
     if (descriptor === void 0) { descriptor = undefined; }
@@ -9,33 +11,50 @@ export function facet(facetHost, facetMember, descriptor) {
     ctrClassAdmin.facetMembers.push(facetMember);
     return descriptor;
 }
-export function registerFacets(ctr) {
-    var _a;
+export function facetClassName(facetClass) {
+    return facetClass.className ? facetClass.className() : facetClass.name;
+}
+// Registers members of ctr as facets in ctr. Each facet is registered by its class name.
+export function registerFacets(ctr, options) {
+    var _a, _b, _c, _d, _e;
     var ctrAdmin = getCtrAdmin(ctr);
-    ctrAdmin.facetByFacetClassName = (_a = ctrAdmin.facetByFacetClassName) !== null && _a !== void 0 ? _a : {};
-    getFacetMemberNames(ctr).forEach(function (member) {
+    ctrAdmin.logName = (_a = options.name) !== null && _a !== void 0 ? _a : ctr.constructor.name;
+    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 = "".concat(ctrAdmin.logName, "/").concat(facetClassName(facet.constructor));
         var className = facetClassName(facet.constructor);
         if (ctrAdmin.facetByFacetClassName[className] !== undefined) {
-            console.error("Two facets of same type " + className + " in container " + ctr.constructor.name);
+            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));
+    }
 }
 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) { return getf(classMember[0], ctr)[classMember[1]]; };
-    f.className = classMember[0].name;
-    f.memberName = classMember[1];
+    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 ease debugging later
+    f.facetClassName = facetClassName(classMember[0]);
+    f.facetMemberName = classMember[1];
     return f;
 }

package/lib/operation.js

@@ -34,16 +34,17 @@ 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;
     var facetClassAdmin = getFacetClassAdmin(target.constructor);
-    facetClassAdmin.operationMemberNames = (_a = facetClassAdmin.operationMemberNames) !== null && _a !== void 0 ? _a : [];
+    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,5 @@
-import { GetterT, ClassMemberT } from "..";
+import { ClassMemberT, GetterT } 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]: ClassMemberT, getter: GetterT, transform?: Function | undefined) => (ctr: any) => void;
-export declare const mapDatasToFacet: ([toFacetClass, toMember]: ClassMemberT, getters: Array<GetterT>, transform: Function) => (ctr: any) => void;
+export declare const mapDataToFacet: ([toFacetClass, toMember, toCtr]: ClassMemberT, getter: GetterT, transform?: Function) => (ctr: any) => void;
+export declare const mapDatasToFacet: ([toFacetClass, toMember, toCtr]: ClassMemberT, getters: Array<GetterT>, transform: Function) => (ctr: any) => void;

package/lib/patch.js

@@ -9,9 +9,9 @@ var __assign = (this && this.__assign) || function () {
     };
     return __assign.apply(this, arguments);
 };
-import { getf } from "./facet";
-import { facetName } from "../internal/logging";
-import { getDataMemberNames } from "./data";
+import { facetLogName } from '../internal/logging';
+import { getDataMemberNames } from './data';
+import { getf } from './facet';
 export function mapDataToProp(facet, prop, getter) {
     delete facet[prop];
     Object.defineProperty(facet, prop, {
@@ -26,23 +26,34 @@ export function patchFacet(facet, members, options) {
     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 " + facetName(facet)));
+                console.error("Patching a property ".concat(prop, " that wasn't decorated with ") +
+                    "@data, @input or @output in ".concat(facetLogName(facet)));
             }
         }
-        delete facet[prop];
+        try {
+            delete facet[prop];
+        }
+        catch (_b) {
+            console.error("Could not delete property ".concat(prop, " from facet ").concat(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];
+    var toFacetClass = _a[0], toMember = _a[1], toCtr = _a[2];
     return function (ctr) {
         var _a;
         var patch = (_a = {},
             _a[toMember] = {
                 get: function () {
+                    // This context variable is not necessary, it has redundant data and
+                    // could be inlined, but it makes debugging easier.
                     var context = {
-                        ctr: ctr,
+                        ctr: toCtr !== null && toCtr !== void 0 ? toCtr : ctr,
                         getter: getter,
                         toClassMember: [toFacetClass, toMember],
                         data: getter(ctr),
@@ -51,18 +62,18 @@ export var mapDataToFacet = function (_a, getter, transform) {
                 },
             },
             _a);
-        patchFacet(getf(toFacetClass, ctr), patch);
+        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];
+    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: ctr,
+                        ctr: toCtr !== null && toCtr !== void 0 ? toCtr : ctr,
                         getters: getters,
                         toClassMember: [toFacetClass, toMember],
                         datas: getters.map(function (getter) { return getter(ctr); }),
@@ -71,6 +82,6 @@ export var mapDatasToFacet = function (_a, getters, transform) {
                 },
             },
             _a);
-        patchFacet(getf(toFacetClass, ctr), patch);
+        patchFacet(getf(toFacetClass, toCtr !== null && toCtr !== void 0 ? toCtr : ctr), patch);
     };
 };

package/package.json

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