improved documentation and typings for tutorial & tutorials modules

Author: ShMcK

lib/modules/tutorial/reducer.js

@@ -4,14 +4,17 @@ var types_1 = require('./types');
 var config_1 = require('./utils/config');
 var config_paths_1 = require('./utils/config-paths');
 exports._tutorial = {
-    name: null,
-    version: null,
-    info: null,
+    name: 'default',
+    version: '0.1.0',
+    info: {
+        title: 'error',
+        description: 'Something went wrong. Tutorial not loaded.'
+    },
     pages: [],
     packageJson: null,
     config: null,
 };
-var configured = [];
+var configured = new Set();
 function tutorialReducer(t, action) {
     if (t === void 0) { t = exports._tutorial; }
     switch (action.type) {
@@ -22,10 +25,12 @@ function tutorialReducer(t, action) {
             var config = config_1.tutorialConfig(packageJson, dir);
             var coderoadJsonPath = path_1.join(packagePath, packageJson.main);
             var _b = require(coderoadJsonPath), info = _b.info, pages = _b.pages;
-            if (configured.indexOf(name_1) === -1) {
+            if (configured.has(name_1)) {
                 pages = config_paths_1.default(dir, name_1, config, pages || []);
             }
-            configured.push(name_1);
+            else {
+                configured.add(name_1);
+            }
             return {
                 name: packageJson.name,
                 version: version,

lib/modules/tutorial/utils/config-paths.js

@@ -22,12 +22,16 @@ function configPaths(dir, name, config, pages) {
             page.tasks = [];
         }
         page.tasks.map(function (task) {
+            if (!task.tests) {
+                return task;
+            }
             task.tests = task.tests.map(function (testPath) {
                 if (typeof testPath === 'string') {
                     return configTestString(dir, name, config, testPath);
                 }
                 else {
                     console.error('Invalid task test', testPath);
+                    return 'ERROR';
                 }
             });
             return task;

lib/modules/tutorial/utils/config.js

@@ -5,7 +5,6 @@ var config_runner_1 = require('./config-runner');
 function tutorialConfig(tutorialPj, dir) {
     var config = tutorialPj.config, name = tutorialPj.name;
     var repo = config_repo_1.configRepo(tutorialPj.repo);
-    var tutorialDir = path_1.join(dir, 'node_modules', name, config.dir);
     var runner = config.runner;
     var runnerOptions = config.runnerOptions || {};
     var configEdit = tutorialPj.config.edit;
@@ -14,12 +13,12 @@ function tutorialConfig(tutorialPj, dir) {
         console.log('Error loading test runner', getRunner);
     }
     return {
-        dir: tutorialDir,
+        dir: path_1.join(dir, 'node_modules', name, config.dir),
         runner: runner,
         runnerOptions: runnerOptions,
         run: getRunner.run,
         load: getRunner.load,
-        testSuffix: configTestSuffix(config.testSuffix),
+        testSuffix: configTestSuffix(config.testSuffix || 'js'),
         issuesPath: config_repo_1.configIssuesPath(tutorialPj.bugs),
         repo: repo,
         edit: !!repo && configEdit || false,

src/modules/tutorial/reducer.test.ts

@@ -1,3 +1,5 @@
+/// <reference path="../../typings/globals/jest/index.d.ts" />
+
 import reducer, { _tutorial } from './reducer';
 
 describe('tutorial reducer', () => {

src/modules/tutorial/reducer.ts

@@ -5,15 +5,18 @@ import { tutorialConfig } from './utils/config';
 import configPaths from './utils/config-paths';
 
 export const _tutorial: CR.Tutorial = {
-  name: null,
-  version: null,
-  info: null,
+  name: 'default',
+  version: '0.1.0',
+  info: {
+    title: 'error',
+    description: 'Something went wrong. Tutorial not loaded.'
+  },
   pages: [],
   packageJson: null,
   config: null,
 };
 
-const configured = [];
+const configured = new Set();
 
 export default function tutorialReducer(
   t = _tutorial, action: Action
@@ -32,10 +35,11 @@ export default function tutorialReducer(
       let {info, pages} = require(coderoadJsonPath);
 
       // configure test paths to absolute paths. Only once.
-      if (configured.indexOf(name) === -1) {
+      if (configured.has(name)) {
         pages = configPaths(dir, name, config, pages || []);
+      } else {
+        configured.add(name);
       }
-      configured.push(name);
 
       // return tutorial (info, pages) & tutorial package.json
       return {

src/modules/tutorial/utils/config-paths.ts

@@ -2,6 +2,14 @@ import {join} from 'path';
 
 import {isWindows} from './system';
 
+/**
+ * set paths to tests as absolute paths 
+ * @param  {string} dir
+ * @param  {string} name
+ * @param  {Tutorial.Config} config
+ * @param  {string} testPath
+ * @returns string
+ */
 function configTestString(
   dir: string, name: string, config: Tutorial.Config, testPath: string
 ): string {
@@ -25,7 +33,14 @@ function configTestString(
 
   return testPath;
 }
-
+/**
+ * loops over task tests and set paths to absolute paths
+ * @param  {string} dir
+ * @param  {string} name
+ * @param  {Tutorial.Config} config
+ * @param  {CR.Page[]} pages
+ * @returns CR
+ */
 export default function configPaths(
   dir: string, name: string, config: Tutorial.Config, pages: CR.Page[]
 ): CR.Page[] {
@@ -34,13 +49,17 @@ export default function configPaths(
       page.tasks = [];
     }
     page.tasks.map((task: CR.Task): CR.Task => {
+
+      if (!task.tests) { return task; }
+      
       // change testPaths to use absolute URLs
       task.tests = task.tests.map((testPath: string) => {
         // add unique string to tests
         if (typeof testPath === 'string') {
           return configTestString(dir, name, config, testPath);
         } else {
           console.error('Invalid task test', testPath);
+          return 'ERROR';
         }
       });
       return task;

src/modules/tutorial/utils/config-repo.test.ts

@@ -0,0 +1,23 @@
+/// <reference path="../../../typings/globals/jest/index.d.ts" />
+
+import {configRepo, configIssuesPath} from './config-repo';
+
+describe('config functions:', () => {
+
+  it('configRepo should capture a repo name', () => {
+    const url = 'path/to/repo'; 
+    const repo = {
+      url 
+    };
+    expect(configRepo(repo)).toBe(url);
+  });
+
+  it('configIssuesPath should capture an issues path', () => {
+    const url = 'path/to/issues';
+    const bugs = {
+      url
+    };
+    expect(configIssuesPath(bugs)).toBe(url);
+  });
+
+});

src/modules/tutorial/utils/config-repo.ts

@@ -1,3 +1,9 @@
+/**
+ * configure repo name from package.json
+ * possible formats include: repo: string, or repo: { url: string }
+ * @param  {{url:string}} repo?
+ * @returns string
+ */
 export function configRepo(repo?: { url: string }): string|null {
   if (repo && repo.url) {
     let url: string = repo.url;
@@ -9,6 +15,12 @@ export function configRepo(repo?: { url: string }): string|null {
   return null;
 }
 
+/**
+ * configure Github issues path from package.json
+ * possible formats include bugs: { url: string }
+ * @param  {{url:string}} bugs?
+ * @returns string
+ */
 export function configIssuesPath(bugs?: { url: string }): string|null {
   return bugs && bugs.url ? bugs.url : null;
 }

src/modules/tutorial/utils/config-runner.ts

@@ -1,13 +1,20 @@
 import {join} from 'path';
-
 import {isWindows} from './system';
 import fileExists from 'node-file-exists';
 
+/**
+ * sets tutorial runner (load & run)
+ * @param  {string} name
+ * @param  {string} runner
+ * @param  {string} dir
+ */
 export default function configRunner(name: string, runner: string, dir: string): { run: () => any, load: () => any } {
-  // test runner dir
+  
+  // flat dep in NPM 3
   let flatDep = join(
     dir, 'node_modules', runner, 'package.json'
   );
+  // tree dep occurs in NPM 2 & when using npm link
   let treeDep = join(
     dir, 'node_modules', name, 'node_modules', runner, 'package.json'
   );

src/modules/tutorial/utils/config.ts

@@ -5,13 +5,18 @@ import configRunner from './config-runner';
 import {isWindows} from './system';
 import fileExists from 'node-file-exists';
 
+/**
+ * capture configuration variables
+ * @param  {PackageJson} tutorialPj tutorial package.json
+ * @param  {string} dir use directory
+ * @returns Tutorial.Config
+ */
 export function tutorialConfig(
   tutorialPj: PackageJson, dir: string
 ): Tutorial.Config {
   // package.json: name, config
   const {config, name} = tutorialPj;
   const repo = configRepo(tutorialPj.repo);
-  const tutorialDir: string = join(dir, 'node_modules', name, config.dir);
   const runner: string = config.runner;
   const runnerOptions: Object = config.runnerOptions || {};
   const configEdit = tutorialPj.config.edit;
@@ -23,18 +28,24 @@ export function tutorialConfig(
   }
 
   return {
-    dir: tutorialDir,
+    dir: join(dir, 'node_modules', name, config.dir),
     runner,
     runnerOptions,
     run: getRunner.run,
     load: getRunner.load,
-    testSuffix: configTestSuffix(config.testSuffix),
+    testSuffix: configTestSuffix(config.testSuffix || 'js'),
     issuesPath: configIssuesPath(tutorialPj.bugs),
     repo,
     edit: !!repo && configEdit || false,
   };
 }
 
+/**
+ * add test suffix to the end of files
+ * example: '.js' -> '.js'
+ * example: 'js' -> '.js'
+ * @param  {string} suffix
+ */
 function configTestSuffix(suffix: string) {
   return suffix.length && suffix[0] === '.' ? suffix : '.' + suffix || null;
 }