skandha 0.9.1 → 0.10.1

package/README.md

@@ -14,16 +14,18 @@ The goal of SkandhaJS is to provide data containers that have reusable behaviors
 
 ## Glossary (conceptual)
 
+- callback function: a function that is called by an operation to help implement that operation
 - callbacks object: a collection of callback functions that is used by an operation.
-- container: a class that contains multiple facets.
+- container: a class that contains multiple facets. Typically, these facets are made to work together using callback functions.
 - facet: a class that implements a reusable behaviour, such as selection.
 - operation: a member function of a facet that changes the data of that facet.
 
 ## Glossary (technical)
 
 - aspiration: a library that implements a form of Aspect Oriented Programming using callback functions.
+- mapDataToProps: a helper function that maps data from one object to another. It's also used to map data between facets.
 - registerCtr: the function that tells SkandhaJS which containers and facets exist.
-- setCallbacks: the function that installs the callbacks objects that are used by a facet.
+- setCallbackMap: the function that installs the callbacks objects that are used by a facet.
 
 ## Example: a simplified Selection facet
 
@@ -52,52 +54,52 @@ export class Selection<ValueT = any> {
 
 ## Fact: facets have @input, @data and @output members
 
-In `Selection.ts` we see the Selection facet class. It has a `selectableIds` field that stores the list of ids from which we can select. It is marked with the `@input` decorator because this field stores an input. The `ids`, `anchorId` and `items` fields are marked as `@output` fields. They are used to store the result of calling `selectItem()`.
+In `Selection.ts` we see the Selection facet class. It has a `selectableIds` field that stores the list of ids from which we can select. It is marked with the `@input` decorator because this field stores an input. The `ids`, `anchorId` and `items` fields are marked as `@output` fields. They are used to store the result of calling `selectItem()`. Fields that are decorated with `@data` are used both as output and input.
 
 ## Fact: operations are decorated with `@operation`.
 
-Conceptually, an operation is a member function that is used to manipulate the facet. The `Selection` facet has a `selectItems` operation that allows you to select from the selectable ids. It stores its results in the `ids`, `anchorId` and `items` fields.
+The `Selection` facet has a `selectItem()` operation that allows you to select from the selectable ids. It stores its results in the `ids`, `anchorId` and `items` fields.
 As the comment mentions, `selectItem()` calls a callback function to do the actual work. The reason is that the correct way to make a selection (e.g. what should happen if shift is pressed?) depends on the use-case. Therefore, we want to leave it up to the client to decide this.
 
 ## Fact: operations are logged
 
-As a side effect of calling an operation, the entire container is logged to the console; this includes the Selection facet, and any other facets that the container may have. The log message contains all @input, @data and @output fields of all facets in the container.
+As a side effect of calling an operation, the entire container is logged to the console; this includes the Selection facet, and any other facets that the container may have (such as filtering, or highlight). The log message contains all @input, @data and @output fields of all facets in the container.
 
 ## Example: a container with Selection, Highlight and Filtering
 
 Now that we have some idea of what a facet is, we will discuss containers.
-In this example we will take a look at a todos container. It uses the `Selection` facet that we saw earlier.
+In this example we will take a look at a todos container. It uses the `Selection` facet that we saw earlier (and some other facets that we haven't defined yet).
 
 ```
 // file: createContainer.ts
 import { Selection_selectItem } from 'SelectionCbs';
 
 const createContainer() {
-  const ctr = {
+  const todosCtr = {
     selection: new Selection(),
     highlight: new Highlight(),
     filtering: new Filtering()
   };
 
-  setCallbacks(ctr.selection, {
+  setCallbackMap(todosCtr.selection, {
     selectItem: {
       select(this: Selection_selectItem): {
-        handleSelectItem(ctr.selection, this.selectionParams);
-        highlightFollowsSelection(ctr, this.selectionParams);
+        handleSelectItem(todosCtr.selection, this.selectionParams);
+        highlightFollowsSelection(todosCtr, this.selectionParams);
       },
     }
   });
 
-  setCallbacks(ctr.filtering, {
+  setCallbackMap(todosCtr.filtering, {
     apply: {
       exit() {
-        highlightIsCorrectedOnFilterChange(ctr);
+        highlightIsCorrectedOnFilterChange(todosCtr);
       },
     },
   });
 
-  registerCtr({ ctr: ctr, options: { name: 'Todos'} });
-  return ctr;
+  registerCtr({ ctr: todosCtr, options: { name: 'Todos'} });
+  return todosCtr;
 }
 ```
 
@@ -141,11 +143,11 @@ export function handleSelectItem(
 
 ## Note: the todos container has selection, highlight and filtering
 
-In `createContainer.ts` we see how `createContainer()` creates a `ctr` object that has three facets: selection, highlight and filtering. After creating the container, the `installCallbacks` function is called to determine how the facet operations are implemented. Finally, `registerCtr()` is called to allow SkandhaJS to introspect the container. This is necessary for two reasons. First, it makes it possible to look up a facet by its name or class, e.g. `getf(ctr, Selection)` returns `ctr.selection`. Second, it informs SkandhaJS how to log all facets of the container
+In `createContainer.ts` we see how `createContainer()` creates a `todosCtr` object that has three facets: selection, highlight and filtering. After creating the container, the `installCallbacks()` function is called to determine how the facet operations are implemented. In this case, we only install the `select()` callback function.
 
-## Fact: callbacks are installed with `setCallbacks`
+## Fact: callbacks are installed with `setCallbackMap()`
 
-We call `setCallbacks` to install a callbacks object for each operation of the `Selection` facet. The callbacks object contains all callbacks for an operation. In our case we only have one operation (`selectItem()`) that has only one callback (`select()`). This callback function calls `handleSelectItem` to take care of doing the selection. This is a typical pattern: you want the call to `setCallbacks` to be as short and readable as possible, so that it's easy to understand what happens in each operation of each facet.
+We call `setCallbackMap()` to install a callbacks object for each operation of the `Selection` facet. In our case we only have one operation (`selectItem()`) that has only one callback (`select()`). This callback function calls `handleSelectItem()` to take care of doing the selection. This is a typical pattern: you want the call to `setCallbackMap()` to be as short and readable as possible, so that it's easy to understand what happens in each operation of each facet.
 
 ## Fact: callbacks can take care of side effects
 
@@ -153,12 +155,16 @@ An important advantage of using callbacks is that they can also take care of sid
 
 ## Fact: the callback function can access the callbacks object through `this`.
 
-When the clients calls `ctr.selection.selectItem()` and `select` is called back, then all arguments of the operation are available through `this`. In our case, we see that the `select` callback function is accessing `this.selectionParams`.
+When the clients calls `todosCtr.selection.selectItem()` and `select()` is called back, then all arguments of the operation are available through `this`. In our case, we see that the `select()` callback function is accessing `this.selectionParams`.
 
-## Fact: the `exit` callback function is called at the end of an operation
+## Fact: the `exit()` callback function is called at the end of an operation
 
 In `createContainer.ts` we also have a `Filtering` facet that has an `apply(f)` operation (where `f` is the filter function). In this operation, we install the `exit()` callback that corrects the highlight when the filter function changes (because the new filter may hide the highlighted item). The `exit()` callback is called automatically at the end of each operation. Similarly, the `enter()` callback is called at the beginning.
 
+## Fact: the `registerCtr()` allows SkandhaJS to introspect the container
+
+At the end of `createContainer.ts` we call `registerCtr()` so that SkandhaJS can introspect the container. This is necessary for two reasons. First, it makes it possible to look up a facet by its name or class, e.g. `getf(todosCtr, Selection)` returns `todosCtr.selection`. Second, it informs SkandhaJS how to log all facets of the container
+
 ## Example: a complete Selection facet
 
 It's time now to return to the Selection facet and show how callbacks really work.
@@ -203,7 +209,7 @@ export class Selection_selectItem extends Cbs {
 
 The `@host` decorator comes from the `Aspiration` library. When you call a function `f` that is decorated with `@host` then the following happens:
 
-- Aspiration looks up the callbacks object for the operation (that was installed with `setCallbacks`)
+- Aspiration looks up the callbacks object for the operation (that was installed with `setCallbackMap()`)
 - it copies the operation arguments to the callbacks object (so that callback functions can access these arguments)
 - if calls `f(arguments)(callbacksObject)`.
 
@@ -217,63 +223,74 @@ As we mentioned earlier, each callback function of the callbacks object has acce
 
 To allow SkandhaJS to introspect the container, you need to add the `className()` function to each facet class, so that Skandha knows the name of the facet.
 
-## Example: a Connector maps data onto each facet
+## Example: `mapDataToProps()` maps data onto each facet
 
-We've seen how facets are implemented, and how they can be added to a container in a way that allows us to create interactions between them. Since our container contains selection and filtering, we should only allow selection of todos that have not been filtered out. In other words, the list of selectable ids should be derived from the list of filtered todos. Moreover, we need to load the todos and set them as the inputs of the filtering facet. In this example, we show two containers (data and todos) and how to map data between them.
+We've seen how facets are implemented, and how they can be added to a container in a way that allows us to create interactions between them. Since our container contains selection and filtering, we should only allow selection of todos that have not been filtered out. In other words, the list of selectable ids should be derived from the list of filtered todos. In this example, we will see how we can create such a mapping from the filtering facet to the selection facet. Moreover, we will add code to load the todos and set them as the inputs of the filtering facet.
 
 ```
 // file: createContainer.ts
 import * from 'ramda' as R;
+import { mapDataToProps, pmap } from 'skandha';
 
-const connectContainer(ctr: any) {
-  const data = {
-    inputs: { todos: loadTodos() },
-    outputs: { filteredTodoById: {} },
-  };
-
-  const todos = {
+const createContainer = () => {
+  const todosCtr = {
+    data: {
+      todos: loadTodos(),
+      filteredTodoById: {},
+    },
     selection: new Selection(),
     highlight: new Highlight(),
     filtering: new Filtering(),
   }
 
-  const con = createConnector({ data: data, todos: todos });
-  const lookUpTodo = (id: string) => outputsCtr.filteredTodoById[id];
-
-  con['todos.filtering'].inputItems = con['inputs'].todos;
-  con['outputs'].filteredTodoById = con['todos.filtering'].filteredItems.tf(R.indexBy('id));
-  con['todos.selection'].selectableIds = con['outputs'].filteredTodoById.tf(R.keys);
-  con['todos.selection'].item = con['todos.selection'].ids.tf(lookUpTodos);
-  con['todos.highlight'].item = con['todos.highlight'].id.tf(lookUpTodo);
+  const lookUpTodo = (id?: string) => id ? todosCtr.data.filteredTodoById[id] : undefined;
+
+  mapDataToProps(
+    pmap(
+      [todosCtr.filtering, 'inputItems'],
+      () => todosCtr.data.todos
+    ),
+    pmap(
+      [todosCtr.data, 'filteredTodoById'],
+      () => R.indexBy('id')(todosCtr.filtering.filteredItems)
+    ),
+    pmap(
+      [todosCtr.selection, 'selectableIds'],
+      () => R.keys(todosCtr.data.filteredTodoById)
+    ),
+    pmap(
+      [todosCtr.selection, 'item'],
+      () => R.map(lookUpTodo, todosCtr.selection.ids)
+    ),
+    pmap(
+      [todosCtr.highlight, 'item'],
+      () => lookUpTodo(todosCtr.highlight.id)
+    ),
+  )
+}
 
-  con.connect();
+setOptions({logging: true});
 ```
 
-## Fact: the Connector class maps data between objects
+## Fact: the `mapDataToProps()` function maps data between objects
+
+The `mapDataToProp()` function takes a container, field name and function then it turns that field into a `get` property that executes the given function. The `mapDataToProps()` is a small convenience function that calls `mapDataToProp()` on each of its arguments. In our example, we see that the `todosCtr.data.todos` field is mapped onto the `todosCtr.filtering.inputItems` field.
+
+## Fact: the `pmap()` function adds type-checking
 
-The Connector instance allows you to map data from one object onto another object.
-In our example, the `data.inputs.todos` field is mapped onto the `todos.filtering.inputItems` field. What this means is that `Connector` turns `todos.filtering.inputItems` into a `get` property that returns `data.inputs.todos`.
+The `pmap()` function takes two arguments. The first argument is an array that has a container and a container-member. The second argument is a function. The `pmap` function checks that the output of this function can be stored in the container-member (if not, then a compile-time error results). It returns an array that contains its two arguments (because that is the format that `mapDataToProps` expects). As you can see, `pmap` does not do any useful work at run-time, but it adds type-checking at compile-time.
 
-### Logging
+## Fact: logging can be enabled using `setOptions()`
 
-By calling `setOptions({logging: true})`, the SkandhaJS library allows you to inspect each facet before and after calling an operation.
-All facet members that are decorated with `@data` (or `@input`, or `@output`) are logged in a way that looks similar to what you are used to from Redux:
+By calling `setOptions({logging: true})`, the SkandhaJS library allows you to inspect each facet before and after calling an operation. All facet members that are decorated with `@data` (or `@input`, or `@output`) are logged in a way that looks similar to what you are used to from Redux:
 
 - before and after each operation, the entire container that holds the facet is logged
 - all data members of each facet in the container are included in the log
 - log entries are nested so that you can see how operation calls are nested
 
-### Making facets observable with Mobx
+## Fact: the `registerCtr()` function from facets-mobx makes facets observable
 
-If you want to render the facets with React then we need to let React know when data changes. The [skandha-mobx](http://github.com/mnieber/skandha-mobx) library was created for this purpose. It has a `registerCtr` function that turns each `@data` member into a Mobx property that is
-either observable or computed:
-
-```
-registerCtr({
-  ctr: ctr,
-  options: { name: 'Todos'},
-});
-```
+If you want to render the facets with React then we need to let React know when data changes. The [skandha-mobx](http://github.com/mnieber/skandha-mobx) library was created for this purpose. It has a `registerCtr()` function that can be used instead of the default one from `skandha`. This replacement version of `registerCtr()` function turns each `@data` member into a Mobx property that is either observable or computed.
 
 ## Conclusion
 

package/index.d.ts

@@ -1,12 +1,11 @@
 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 { mapDataToProp, mapDataToProps, pmap } from './lib/patch';
 export { registerCtr } from './lib/registerCtr';
 export type { OptionsT as RegisterCtrOptionsT } from './lib/registerCtr';
 export declare type ClassT = any;

package/index.js

@@ -1,10 +1,9 @@
 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 { mapDataToProp, mapDataToProps, pmap } from './lib/patch';
 export { registerCtr } from './lib/registerCtr';

package/internal/utils.js

@@ -1,11 +1,7 @@
-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));
+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;
 };
 import { symbols } from './symbols';
 export function getOrCreate(obj, key, fn) {
@@ -20,7 +16,7 @@ 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, true), [arr[i]], false); }, [val]);
+        return arrs.reduce(function (a, arr) { return __spreadArray(__spreadArray([], a), [arr[i]]); }, [val]);
     });
 };
 export function getCtrAdmin(ctr) {

package/lib/facet.js

@@ -11,7 +11,7 @@ export function getf(facetClass, ctr) {
         : (_a = getCtrAdmin(ctr).facetByFacetClassName) === null || _a === void 0 ? void 0 : _a[facetClassName(facetClass)];
     if (!facet) {
         var facetName = facetClass === 'string' ? facetClass : facetClassName(facetClass);
-        console.error("No facet ".concat(facetName, " in container ").concat(getCtrAdmin(ctr).logName));
+        console.error("No facet " + facetName + " in container " + getCtrAdmin(ctr).logName);
     }
     return facet;
 }

package/lib/patch.d.ts

@@ -1 +1,3 @@
-export declare function mapDataToProp(facet: any, prop: string, getter: () => any): void;
+export declare function mapDataToProp<F, P extends keyof F>(facet: F, prop: P, getter: () => F[P]): void;
+export declare function mapDataToProps(...mappings: any[]): void;
+export declare function pmap<F, P extends keyof F>(member: [F, P], getter: () => F[P]): ([F, P] | (() => F[P]))[];

package/lib/patch.js

@@ -6,3 +6,16 @@ export function mapDataToProp(facet, prop, getter) {
         configurable: true,
     });
 }
+export function mapDataToProps() {
+    var mappings = [];
+    for (var _i = 0; _i < arguments.length; _i++) {
+        mappings[_i] = arguments[_i];
+    }
+    for (var _a = 0, mappings_1 = mappings; _a < mappings_1.length; _a++) {
+        var mapping = mappings_1[_a];
+        mapDataToProp(mapping[0][0], mapping[0][1], mapping[1]);
+    }
+}
+export function pmap(member, getter) {
+    return [member, getter];
+}

package/lib/registerCtr.js

@@ -15,13 +15,13 @@ export function registerCtr(ctr, options) {
         setCtr(facet, ctr);
         ctrAdmin.facetMembers.push(facetName);
         if (!facet.constructor.className) {
-            console.error("Facet ".concat(facetName, " of container ").concat(ctrAdmin.logName, " ") +
+            console.error("Facet " + facetName + " of container " + ctrAdmin.logName + " " +
                 "does not have a static className function");
         }
         var className = facetClassName(facet.constructor);
-        getFacetAdmin(facet).logName = "".concat(ctrAdmin.logName, "/").concat(className);
+        getFacetAdmin(facet).logName = ctrAdmin.logName + "/" + className;
         if (ctrAdmin.facetByFacetClassName[className] !== undefined) {
-            console.error("Two facets of same type ".concat(className, " in container ").concat(ctrAdmin.logName));
+            console.error("Two facets of same type " + className + " in container " + ctrAdmin.logName);
         }
         ctrAdmin.facetByFacetClassName[className] = facet;
     });

package/package.json

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

package/lib/Connector.d.ts

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

package/lib/Connector.js

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