A little cleanup.

Author: JSuder-xx

README.md

@@ -1,5 +1,54 @@
 # TypeScript Pseudo Dependent Typing Example with Mobx & React
 
+# Static Typing Stragegies 
+## Discriminated Unions 
+### Representing Field States
+A common idiom in View/View Model architectures is to represent an editable field's visibility and read-only state with two independent properties on the View Model. For example, a firstName property that may be invisible in some contexts and read-only in other contexts may be represented with three separate properties on the view model:
+* firstName - a read/write property to which the view two-way data-binds.
+* isFirstNameVisible - a read-only property that may change in time.
+* isFirstNameReadOnly - a read-only property that may change in time.
+
+This information representation is fraught with opportunities for improper usage/access such as
+* Reading the firstName property when not isFirstNameVisible.
+* Writing the firstName property when isFirstNameReadOnly.
+
+The view model may protect itself from inappropriate access by throwing exceptions but this is terribly opaque and leads to the likelihood of run-time faults. 
+
+Run-time faults can be avoided altogether by employing Discriminated Unions to represent the valid states in such a way that meaning and usage are explicit and compiler verifiable.
+
+Consider instead the Mobx code below
+```TypeScript
+@computed firstName: null | string | (firstName?: string) => string;
+```
+
+The property is computed because it changes reactively based on the state of the editor. 
+
+The type signature clearly indicates three possible cases
+* null - indicates that the field is not available. This corresponds to invisible.
+* string - denotes a read-only state of the field. The user can read but not modify.
+* (firstName?: string) => string - represents a getter/setter function which can be used to both read and write the value.
+
+By using a discriminated union the TypeScript compiler can guarantee that developers cannot expose a hidden field or allow mutation of a read-only field (without intentionally subverting the type system). 
+
+### Representing Actions
+Similarly, the common idiom for representing an action in a View Model is to provide a method on the view model for the action and a read-only property that indicates whether the action is available or enabled at the current time. 
+
+Once again, when modeled this way the type system cannot stop code from attempting to execute the method. Developers only recourse is to check for validity inside the method and throw an exception.
+
+This can be modeled in a type-safe fashion with
+```TypeScript
+@computed doAwesomeThing: null | () => void;
+```
+
+ 
+## Dependent Typing - Cases By Values
+Object oriented code is no stranger to representing Cases with data types (the [State Pattern]( https://www.geeksforgeeks.org/state-design-pattern/)  concerns itself explicitly with such concerns). A class is a "classificaiton" of thing; a set with members (object instances of the class).
+
+An OO class in a nominal type system is 
+* A named type where the name has semantic significance i.e. significance is related to the name.
+* A _structure_ of data with accompanying _behaviors_.
+
+_Work in progress (i.e. more to come)_
 
 
 # Installation

src/api/models/fn.ts

@@ -0,0 +1,5 @@
+/** Represents a side-effecting function. */
+export type ThunkAction = () => void;
+
+/** Represents a side-effecting routine accepting a single argument. */
+export type Action<T> = (input: T) => void;

src/api/models/numbers.ts

@@ -38,3 +38,5 @@ export const sumOfCardinal = <TLeft extends Zero | NonZero, TRight extends Zero
 
 export const sum = (left: number, right: number): number =>
     left + right;
+
+export const sumArray = (nums: number[]): number => nums.reduce(sum, 0);

src/api/views/button.tsx

@@ -0,0 +1,9 @@
+import * as React from 'react';
+import { ThunkAction } from "../models/fn";
+
+/** Create a button that is conditionally [dis/en]abled based upon when the action is available. */
+export const buttonForAction = (caption: string, action: null | ThunkAction) =>
+    action === null
+        ? <button disabled={true}>{caption}</button>
+        : <button onClick={action}>{caption}</button>;
+ 

src/models/add_todo.ts

@@ -1,36 +1,33 @@
 import { observable, action, computed } from 'mobx';
+import { ThunkAction } from "../api/models/fn";
 
-/**
- * Represents the user interaction when adding a To-Do.
- */
+/** Represents the composite user interaction of adding a To-Do. */
 class AddTodo {
 
-    @observable
-    private _taskName = "";
+    @observable private _taskName = "";
 
     constructor(private _injected: { 
+        /** Injected strategy for adding a to-do. */
         addIncompleteTodo: (taskName: string) => void;
     }) {}
 
-    public get taskName() { return this._taskName; }
+    public get taskName(): string { 
+        return this._taskName; 
+    }
 
-    @action
-    public updateTaskName(taskName: string) {
+    /** Update the candidate todo task name. When populated with more than whitespace the user will have the option to add a todo with with name. */
+    @action public updateTaskName(taskName: string): void {
         this._taskName = taskName;
     }
 
-    /**
-     * The action to add a to-do is conditionally available based on the state of the task.
-     */
-    @computed
-    public get addTodoMaybe() {
+    /** The action to add a to-do is conditionally available when the taskName is sufficiently populated. */
+    @computed public get addTodoMaybe(): null | ThunkAction {
         return (this._taskName || "").trim().length > 0
             ? () => this._addTodo()
             : null;
     }    
 
-    @action
-    private _addTodo() {                        
+    @action private _addTodo(): void {                        
         this._injected.addIncompleteTodo(this._taskName);
         this._taskName = "";
     }

src/models/todo.transitions.ts

@@ -0,0 +1,79 @@
+import { succ } from "../api/models/numbers";
+import { 
+  Todo,
+  TodoTimeClock, 
+  NeverStartedTodo, 
+  InProgressTodo, 
+  CompleteTodo, 
+  PausedTodo, 
+  totalMinutesLoggedForTimeClock,
+} from "./todo";
+
+let _id = 1;
+/** Create a new Todo in a paused state. */
+export function create(taskName: string): NeverStartedTodo {
+    return {
+        id: _id++,
+        taskName,
+        minutesLoggedHistorically: 0,
+        todoTimeClock: null,
+        isComplete: false,
+        pauseCount: 0
+    };
+}
+
+/** Represents the result of transitioning a Todo from one state to the next. */
+export type TodoStateTransition<TResultTodo extends Todo, TTimeClock extends null | TodoTimeClock> = {
+    todo: TResultTodo;
+    todoTimeClock: TTimeClock;
+}
+
+/** Complete this in-progress todo. */
+export function complete({ currentTime, todo }: {
+    currentTime: Date;
+    todo: InProgressTodo;
+}): TodoStateTransition<CompleteTodo, null> {
+    return {
+        todoTimeClock: null,
+        todo: {
+            ...todo,
+            minutesLoggedHistorically: totalMinutesLoggedForTimeClock({ todoTimeClock: todo.todoTimeClock, currentTime }),
+            todoTimeClock: null,
+            isComplete: true
+        }
+    };
+}
+
+/** Pause this in-progress todo. */
+export function pause({ currentTime, todo }: {
+    currentTime: Date;
+    todo: InProgressTodo;
+}): TodoStateTransition<PausedTodo, null> {
+    return {
+        todoTimeClock: null,
+        todo: {
+            ...todo,
+            todoTimeClock: null,
+            pauseCount: succ(todo.pauseCount),
+            minutesLoggedHistorically: totalMinutesLoggedForTimeClock({ todoTimeClock: todo.todoTimeClock, currentTime }) 
+        }
+    }
+}
+
+/** Start a Todo (transition to In-Progress) that is Paused or Never Started. */
+export function start({ todo }: {
+    todo: PausedTodo | NeverStartedTodo;
+    todoTimeClock: null;
+}): TodoStateTransition<InProgressTodo, TodoTimeClock> {
+    let inProgressTodo: InProgressTodo;
+    const todoTimeClock: TodoTimeClock = {
+        startTime: new Date(),
+        todo: () => inProgressTodo
+    }
+    inProgressTodo = {
+        ...todo,
+        todoTimeClock
+    };
+    
+    return { todoTimeClock, todo: inProgressTodo };
+}

src/models/todo.ts

@@ -1,29 +1,45 @@
 import { Zero, NonZero, succ } from "../api/models/numbers";
 import { minutesElapsed } from "../api/models/date";
 
-/**
- * A running clock for a Todo item. 
- */
+/** A Todo item - which can be in one of four states/classifications. */
+export type Todo = 
+    NeverStartedTodo 
+    | PausedTodo 
+    | InProgressTodo 
+    | CompleteTodo;
+
+/** Running clock for a Todo item. */
 export type TodoTimeClock = {
-    /**  */
     todo(): InProgressTodo;
     readonly startTime: Date;
 }
 
+/** Returns the total minutes for the timeclock entry which includes the historical todo minutes logged and the current elapsed time on the timer. */
 export const totalMinutesLoggedForTimeClock = ({ currentTime, todoTimeClock }: {
     currentTime: Date;
     todoTimeClock: TodoTimeClock;
 }): number =>
-     todoTimeClock.todo().minutesLogged 
-        + minutesElapsed({ currentTime, startTime: todoTimeClock.startTime });
+    todoTimeClock.todo().minutesLoggedHistorically 
+    + minutesElapsed({ currentTime, startTime: todoTimeClock.startTime });
 
-export type BaseTodo = Readonly<{
+/** Return the minutes logged for the todo. */
+export const minutesLogged = ({ currentTime, todo }: {
+    currentTime: Date;
+    todo: Todo;
+}): number =>
+    isInProgress(todo)     
+        ? totalMinutesLoggedForTimeClock({ todoTimeClock: todo.todoTimeClock, currentTime })
+        : todo.minutesLoggedHistorically;
+        
+/** Properties common to all Todo representations. */
+type BaseTodo = Readonly<{
     id: number;
     taskName: string;
-    minutesLogged: number;
+    minutesLoggedHistorically: number;    
     pauseCount: Zero | NonZero;
 }>
 
+/** A Todo item that is incomplete, not currently being work, and has never been paused. */
 export type NeverStartedTodo = BaseTodo & Readonly<{ 
     todoTimeClock: null;
     isComplete: false; 
@@ -35,6 +51,7 @@ export function isNeverStarted(todo: Todo): todo is NeverStartedTodo {
         && !todo.isComplete;
 }
 
+/** A Todo item that is incomplete, not currently being worked, and has been paused at some point. */
 export type PausedTodo = BaseTodo & Readonly<{ 
     todoTimeClock: null;
     isComplete: false; 
@@ -47,6 +64,7 @@ export function isPaused(todo: Todo): todo is PausedTodo {
         && !todo.isComplete;
 }
 
+/** A Todo item that is incomplete and currently being worked. */
 export type InProgressTodo = BaseTodo & Readonly<{
     todoTimeClock: TodoTimeClock;
     isComplete: false;
@@ -57,6 +75,7 @@ export function isInProgress(todo: Todo): todo is InProgressTodo {
         && !todo.isComplete;
 }
 
+/** A Todo item that is complete. */
 export type CompleteTodo = BaseTodo & Readonly<{
     todoTimeClock: null;
     isComplete: true;
@@ -65,81 +84,3 @@ export type CompleteTodo = BaseTodo & Readonly<{
 export function isComplete(todo: Todo): todo is CompleteTodo {
     return todo.isComplete;
 }
-
-export type Todo = NeverStartedTodo | PausedTodo | InProgressTodo | CompleteTodo;
-
-let _id = 1;
-export function create(taskName: string): NeverStartedTodo {
-    return {
-        id: _id++,
-        taskName,
-        minutesLogged: 0,
-        todoTimeClock: null,
-        isComplete: false,
-        pauseCount: 0
-    };
-}
-
-export function complete({ currentTime, todo }: {
-    currentTime: Date;
-    todo: InProgressTodo;
-}): {
-    todo: CompleteTodo;
-    todoTimeClock: null;
-} {
-    return {
-        todoTimeClock: null,
-        todo: {
-            ...todo,
-            minutesLogged: totalMinutesLoggedForTimeClock({ todoTimeClock: todo.todoTimeClock, currentTime }),
-            todoTimeClock: null,
-            isComplete: true
-        }
-    };
-}
-
-export function pause({ currentTime, todo }: {
-    currentTime: Date;
-    todo: InProgressTodo;
-}): {
-    todoTimeClock: null;
-    todo: PausedTodo;
-} {
-    return {
-        todoTimeClock: null,
-        todo: {
-            ...todo,
-            todoTimeClock: null,
-            pauseCount: succ(todo.pauseCount),
-            minutesLogged: totalMinutesLoggedForTimeClock({ todoTimeClock: todo.todoTimeClock, currentTime }) 
-        }
-    }
-}
-
-export function start({ todo }: {
-    todo: PausedTodo | NeverStartedTodo;
-    todoTimeClock: null;
-}): {
-    todoTimeClock: TodoTimeClock;
-    todo: InProgressTodo;
-} {
-    let inProgressTodo: InProgressTodo;
-    const todoTimeClock: TodoTimeClock = {
-        startTime: new Date(),
-        todo: () => inProgressTodo
-    }
-    inProgressTodo = {
-        ...todo,
-        todoTimeClock
-    };
-    
-    return { todoTimeClock, todo: inProgressTodo };
-}
-
-export const minutesLoggedForTodo = ({ currentTime, todo }: {
-    currentTime: Date;
-    todo: Todo;
-}): number =>
-    isInProgress(todo)     
-        ? totalMinutesLoggedForTimeClock({ todoTimeClock: todo.todoTimeClock, currentTime })
-        : todo.minutesLogged;