added in-code docs

Author: loreanvictor

src/agent/deep.ts

@@ -7,6 +7,17 @@ import { KeyedDeep } from "./keyed-deep";
 
 export function deep(state: State): SimpleDeep;
 export function deep(state: State, key: KeyFunc): KeyedDeep;
+/**
+ *
+ * Creates a [deep state](https://connective.dev/docs/deep) from given state.
+ * You can track indexes, properties and keyed entities on deep states as bound
+ * reactive states.
+ * [Checkout the docs](https://connective.dev/docs/deep) for examples and further information.
+ *
+ * @param state the state to be used as the basis of the returned deep state
+ * @param key the key function to be used to track entities in the deep state
+ *
+ */
 export function deep(state: State, key?: KeyFunc): SimpleDeep | KeyedDeep {
   if (key) return new KeyedDeep(state, key);
   else return new SimpleDeep(state);

src/agent/keyed-deep.ts

@@ -14,13 +14,24 @@ import { SimpleDeep, DeepAccessor } from "./simple-deep";
 import { State, EqualityFunc } from "./state";
 
 
+/**
+ *
+ * Represents a [keyed deep state](https://connective.dev/docs/deep#keyed-deep).
+ *
+ */
 export class KeyedDeep extends SimpleDeep {
   private _keyMap: KeyMap = {};
 
   constructor(state: State, keyfunc: KeyFunc);
   constructor(accessor: DeepAccessor, keyfunc: KeyFunc, compare?: EqualityFunc);
   constructor(stateOrAccessor: State | DeepAccessor, keyfunc: KeyFunc, compare?: EqualityFunc | undefined);
-
+  /**
+   *
+   * @param stateOrAccessor underlying state of this deep state or a state tree accessor (for sub-states)
+   * @param keyfunc key function to be used to track entities within the state's value
+   * @param compare equality function used to detect changes. If state is passed as first argument this is ignored.
+   *
+   */
   constructor(stateOrAccessor: State | DeepAccessor, readonly keyfunc: KeyFunc, compare?: EqualityFunc | undefined) {
     super(stateOrAccessor, compare, {
       inputs: ['value'],
@@ -30,14 +41,23 @@ export class KeyedDeep extends SimpleDeep {
 
   public key(key: string | number): SimpleDeep;
   public key(key: string | number, subkeyfunc: KeyFunc): KeyedDeep;
+  /**
+   *
+   * Creates a sub-state bound to entity identified by given key. Entity `x` is
+   * said to be identified by key `k` if `state.keyfunc(x) === k`.
+   *
+   * @param key the identifier of the entity to track
+   * @param subkeyfunc a key function for the sub-state. provide IF the sub-state also needs to be keyed.
+   *
+   */
   public key(key: string | number, subkeyfunc?: KeyFunc): SimpleDeep | KeyedDeep {
     let initialized = false;
     let _this = this;
 
     this.output; // --> wire output before hand
 
     let accessor: DeepAccessor = {
-      initial: (_this._keyMap[key] || {item: undefined}).item 
+      initial: (_this._keyMap[key] || {item: undefined}).item
               || (Object.values(this.value) || []).find((i: any) => this.keyfunc(i) == key),
       get: group(_this.changes, _this.reemit).to(map(() => (_this._keyMap[key] || {item: undefined}).item)),
       set: sink((v, context) => {
@@ -67,11 +87,20 @@ export class KeyedDeep extends SimpleDeep {
     else return new SimpleDeep(accessor, this.state.compare);
   }
 
+  /**
+   *
+   * Returns a [pin](https://connective.dev/docs/pin) that reflects the reactive value of
+   * the index of entity identified by given key in the state's value. Entity `x` is said
+   * to be identified by key `k` if `state.keyfunc(x) === k`.
+   *
+   * @param key the key to identify target entity with
+   *
+   */
   public index(key: string | number) {
     let initial: string | number;
 
     if (this._keyMap[key]) initial = this._keyMap[key].index;
-    else initial = ((Object.entries(this.value) || []).find(([index, item]) => this.keyfunc(item) == key) 
+    else initial = ((Object.entries(this.value) || []).find(([index, item]) => this.keyfunc(item) == key)
                     || [-1, undefined])[0];
 
     return group(
@@ -80,16 +109,47 @@ export class KeyedDeep extends SimpleDeep {
     ).to(pipe(distinctUntilKeyChanged('value')));
   }
 
+  /**
+   *
+   * Will bind the underlying state, and cause deep change-detection to happen upon
+   * changes of the state value. [Read this](https://connective.dev/docs/deep#change-detection)
+   * for more information on deep change-detection.
+   *
+   * If this is a sub-state, also enables up-propagation
+   * of state value, causing the parent state to pick up changes made to the value of this
+   * sub-state. [Read this](https://connective.dev/docs/deep#two-way-keyed) for more details
+   * and examples.
+   *
+   */
   bind() {
     super.bind();
     this.track(this.changes.subscribe());
     return this;
   }
 
+  /**
+   *
+   * Keys that entities within the value of the state are identified with. Entity
+   * `x` is said to be indetified with key `k` if `state.keyfunc(x) === k`.
+   *
+   * **WARNING** the keys will not be calculcated unless deep change-detection is active.
+   * You can ensure deep change-detection is active by subscribing on `.changes` or
+   * calling `.bind()`. [Read this](https://connective.dev/docs/deep#change-detection)
+   * for more information on deep change-detection.
+   *
+   */
   public get keys() {
-    return Object.keys(this._keyMap); 
+    return Object.keys(this._keyMap);
   }
 
+  /**
+   *
+   * A [pin](https://connective.dev/docs/pin) that emits changes to this deep state's list value.
+   * These changes include entities being added to the list, removed from it or moved around in it.
+   * [Read this](https://connective.dev/docs/deep#change-detection) for more information on 
+   * deep change-detection.
+   *
+   */
   public get changes() { return this.out('changes'); }
 
   protected createOutput(label: string): PinLike {

src/agent/simple-deep.ts

@@ -15,14 +15,25 @@ import { Signature } from "./signature";
 
 export interface DeepAccessor {
   initial: any;
-  set: PinLike; 
+  set: PinLike;
   get: PinLike;
   bind(): void;
 }
 
 
+/**
+ *
+ * Represents non-keyed (simple) [deep states](https://connective.dev/docs/deep).
+ *
+ */
 export class SimpleDeep extends Agent {
+  /**
+   *
+   * can be used to force re-emission of state value.
+   *
+   */
   readonly reemit: Source;
+
   protected state: State;
   protected accessor: DeepAccessor;
   private downPropageteKey: string;
@@ -32,6 +43,13 @@ export class SimpleDeep extends Agent {
   constructor(accessor: DeepAccessor, compare?: EqualityFunc);
   constructor(stateOrAccessor: State | DeepAccessor, compare?: EqualityFunc | undefined);
   constructor(stateOrAccessor: State | DeepAccessor, compare?: EqualityFunc | undefined, signature?: Signature);
+  /**
+   *
+   * @param stateOrAccessor underlying state of this deep state or a state tree accessor (for sub-states)
+   * @param compare equality function used to detect changes. If state is passed as first argument this is ignored.
+   * @param signature the signature of the state, to be overriden by child classes.
+   *
+   */
   constructor(stateOrAccessor: State | DeepAccessor, compare?: EqualityFunc | undefined, signature?: Signature) {
     super(signature || {
       inputs: ['value'],
@@ -60,13 +78,21 @@ export class SimpleDeep extends Agent {
     }
   }
 
+  /**
+   *
+   * Creates a sub-state for given index/property.
+   * [Read this](https://connective.dev/docs/deep) for more details
+   *
+   * @param index
+   *
+   */
   public sub(index: string | number): SimpleDeep {
     let initialized = false;
     let _this = this;
 
     return new SimpleDeep({
       initial: (_this.value || [])[index],
-      get: _this.output.to(map((v: any) => (v || [])[index])), 
+      get: _this.output.to(map((v: any) => (v || [])[index])),
       set: sink((v, context) => {
         try {
           if (!_this.value) _this.value = [];
@@ -88,14 +114,45 @@ export class SimpleDeep extends Agent {
     }, this.state.compare);
   }
 
+  /**
+   *
+   * Allows reading or updating state's value directly.
+   *
+   */
   public get value(): any { return this.state.value; }
   public set value(v: any) { this.state.value = v; }
 
+  /**
+   *
+   * The equality function used by this deep state. Is used for change detection.
+   *
+   */
   public get compare() { return this.state.compare; }
 
+  /**
+   *
+   * Shortcut for `.in('value')`, on which the state receives new values.
+   * [Read this](https://connective.dev/docs/state#signature) for more details.
+   *
+   */
   get input() { return this.in('value'); }
+
+  /**
+   *
+   * Shortcut for `.out('value')`, on which the state emits new values.
+   * [Read this](https://connective.dev/docs/state#signature) for more details.
+   *
+   */
   get output() { return this.out('value'); }
 
+  /**
+   *
+   * Binds the underlying state. If this is a sub-state, it will also
+   * allow up-propagation of state value, causing the parent state to pick up
+   * changes made to the value of this sub-state. [Read this](https://connective.dev/docs/deep#two-way-data)
+   * for more details and examples.
+   *
+   */
   bind() {
     if (!this.bound) {
       if (this.accessor) this.accessor.bind();

src/agent/state.ts

@@ -91,11 +91,11 @@ export class State extends Agent implements Bindable {
   get output() { return this.out('value'); }
 
   /**
-   * 
+   *
    * Allows reading or updating `State`'s value directly. It will be equal
    * to the latest value emitted by the `State`, and setting it, if the value
    * has changed truly, will cause the `State` to emit the new value.
-   * 
+   *
    */
   public get value() { return (this._subject.value.value !== _Unset)?(this._subject.value.value):undefined }
   public set value(v: any) { this._injector.send(v); }
@@ -112,10 +112,10 @@ export class State extends Agent implements Bindable {
   }
 
   /**
-   * 
-   * @note `State`'s `.clear()` also causes a complete 
+   *
+   * @note `State`'s `.clear()` also causes a complete
    * notification to be sent to observers.
-   * 
+   *
    */
   public clear(): this {
     this._subject.complete();
@@ -150,7 +150,7 @@ export function state(initial: any, compare: EqualityFunc): State;
  *
  */
 export function state(initialOrCompare?: any | EqualityFunc | undefined, compare?: EqualityFunc | undefined) {
-    return new State(initialOrCompare, compare); 
+    return new State(initialOrCompare, compare);
 }
 
 

src/agent/test/keyed-deep.test.ts

@@ -121,7 +121,7 @@ describe('KeyedDeep', () => {
       let gc2 = c2.sub('name').bind(); let rgc2 = 0; gc2.subscribe(() => rgc2++);
 
       r.should.equal(1); // --> initial value
-      rc1.should.equal(1); 
+      rc1.should.equal(1);
       rgc1.should.equal(1);
       rc2.should.equal(1);
       rgc2.should.equal(1);

src/agent/test/simple-deep.test.ts

@@ -174,7 +174,7 @@ describe('SimpleDeep', () => {
       let gc2 = c2.sub('y').bind(); let rgc2 = 0; gc2.subscribe(() => rgc2++);
 
       r.should.equal(1); // --> initial value
-      rc1.should.equal(1); 
+      rc1.should.equal(1);
       rgc1.should.equal(1);
       rc2.should.equal(1);
       rgc2.should.equal(1);

src/util/keyed-array-diff.ts

@@ -1,10 +1,82 @@
 export type KeyFunc = (obj: any) => string | number;
 export type KeyMap = {[key: string]: {item: any, index: string}};
 
-export type AdditionList = {index: string, item: any}[];
-export type DeletionList = {index: string, item: any}[];
-export type MoveList = {oldIndex: string, newIndex: string, item: any}[];
-export type ChangeMap = { additions: AdditionList, deletions: DeletionList, moves: MoveList };
+export type AdditionList = {
+  /**
+   *
+   * The index that the item was added on.
+   *
+   */
+  index: string, 
+
+  /**
+   *
+   * The added item
+   *
+   */
+  item: any
+}[];
+
+export type DeletionList = {
+  /**
+   *
+   * The index the deleted item used to be on
+   *
+   */
+  index: string,
+
+  /**
+   *
+   * The deleted item
+   *
+   */
+  item: any
+}[];
+
+export type MoveList = {
+  /**
+   *
+   * The index the item used to be on
+   *
+   */
+  oldIndex: string,
+  /**
+   *
+   * The new index of the item
+   *
+   */
+  newIndex: string,
+
+  /**
+   *
+   * The moved item
+   *
+   */
+  item: any
+}[];
+
+export type ChangeMap = {
+  /**
+   *
+   * List of items added to the list
+   *
+   */
+  additions: AdditionList,
+
+  /**
+   *
+   * List of items removed from the list
+   *
+   */
+  deletions: DeletionList,
+
+  /**
+   *
+   * List of items moved around in the list
+   *
+   */
+  moves: MoveList
+};
 
 
 export function diff(value: any, oldKeyMap: KeyMap, keyfunc: KeyFunc): {