diff --git a/.gitignore b/.gitignore index 7735a99..a7620c3 100644 --- a/.gitignore +++ b/.gitignore @@ -24,3 +24,5 @@ yarn-error.log* public/scripts/**/*.js public/scripts/**/*.js.map + +/docs diff --git a/.npmignore b/.npmignore index bb4923f..899c01a 100644 --- a/.npmignore +++ b/.npmignore @@ -25,3 +25,5 @@ src tests webpack.config.js examples + +/docs diff --git a/package-lock.json b/package-lock.json index 6785168..17b8705 100644 --- a/package-lock.json +++ b/package-lock.json @@ -829,6 +829,44 @@ "to-fast-properties": "2.0.0" } }, + "@types/events": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/@types/events/-/events-3.0.0.tgz", + "integrity": "sha512-EaObqwIvayI5a8dCzhFrjKzVwKLxjoG9T6Ppd5CEo07LRKfQ8Yokw54r5+Wq7FaBQ+yXRvQAYPrHwya1/UFt9g==", + "dev": true + }, + "@types/fs-extra": { + "version": "5.0.5", + "resolved": "https://registry.npmjs.org/@types/fs-extra/-/fs-extra-5.0.5.tgz", + "integrity": "sha512-w7iqhDH9mN8eLClQOYTkhdYUOSpp25eXxfc6VbFOGtzxW34JcvctH2bKjj4jD4++z4R5iO5D+pg48W2e03I65A==", + "dev": true, + "requires": { + "@types/node": "11.10.4" + } + }, + "@types/glob": { + "version": "7.1.1", + "resolved": "https://registry.npmjs.org/@types/glob/-/glob-7.1.1.tgz", + "integrity": "sha512-1Bh06cbWJUHMC97acuD6UMG29nMt0Aqz1vF3guLfG+kHHJhy3AyohZFFxYk2f7Q1SQIrNwvncxAE0N/9s70F2w==", + "dev": true, + "requires": { + "@types/events": "3.0.0", + "@types/minimatch": "3.0.3", + "@types/node": "11.10.4" + } + }, + "@types/handlebars": { + "version": "4.0.40", + "resolved": "https://registry.npmjs.org/@types/handlebars/-/handlebars-4.0.40.tgz", + "integrity": "sha512-sGWNtsjNrLOdKha2RV1UeF8+UbQnPSG7qbe5wwbni0mw4h2gHXyPFUMOC+xwGirIiiydM/HSqjDO4rk6NFB18w==", + "dev": true + }, + "@types/highlight.js": { + "version": "9.12.3", + "resolved": "https://registry.npmjs.org/@types/highlight.js/-/highlight.js-9.12.3.tgz", + "integrity": "sha512-pGF/zvYOACZ/gLGWdQH8zSwteQS1epp68yRcVLJMgUck/MjEn/FBYmPub9pXT8C1e4a8YZfHo1CKyV8q1vKUnQ==", + "dev": true + }, "@types/jest": { "version": "24.0.9", "resolved": "https://registry.npmjs.org/@types/jest/-/jest-24.0.9.tgz", @@ -844,6 +882,40 @@ "integrity": "sha512-yALhelO3i0hqZwhjtcr6dYyaLoCHbAMshwtj6cGxTvHZAKXHsYGdff6E8EPw3xLKY0ELUTQ69Q1rQiJENnccMA==", "dev": true }, + "@types/lodash": { + "version": "4.14.122", + "resolved": "https://registry.npmjs.org/@types/lodash/-/lodash-4.14.122.tgz", + "integrity": "sha512-9IdED8wU93ty8gP06ninox+42SBSJHp2IAamsSYMUY76mshRTeUsid/gtbl8ovnOwy8im41ib4cxTiIYMXGKew==", + "dev": true + }, + "@types/marked": { + "version": "0.4.2", + "resolved": "https://registry.npmjs.org/@types/marked/-/marked-0.4.2.tgz", + "integrity": "sha512-cDB930/7MbzaGF6U3IwSQp6XBru8xWajF5PV2YZZeV8DyiliTuld11afVztGI9+yJZ29il5E+NpGA6ooV/Cjkg==", + "dev": true + }, + "@types/minimatch": { + "version": "3.0.3", + "resolved": "https://registry.npmjs.org/@types/minimatch/-/minimatch-3.0.3.tgz", + "integrity": "sha512-tHq6qdbT9U1IRSGf14CL0pUlULksvY9OZ+5eEgl1N7t+OA3tGvNpxJCzuKQlsNgCVwbAs670L1vcVQi8j9HjnA==", + "dev": true + }, + "@types/node": { + "version": "11.10.4", + "resolved": "https://registry.npmjs.org/@types/node/-/node-11.10.4.tgz", + "integrity": "sha512-wa09itaLE8L705aXd8F80jnFpxz3Y1/KRHfKsYL2bPc0XF+wEWu8sR9n5bmeu8Ba1N9z2GRNzm/YdHcghLkLKg==", + "dev": true + }, + "@types/shelljs": { + "version": "0.8.3", + "resolved": "https://registry.npmjs.org/@types/shelljs/-/shelljs-0.8.3.tgz", + "integrity": "sha512-miY41hqc5SkRlsZDod3heDa4OS9xv8G77EMBQuSpqq86HBn66l7F+f8y9YKm+1PIuwC8QEZVwN8YxOOG7Y67fA==", + "dev": true, + "requires": { + "@types/glob": "7.1.1", + "@types/node": "11.10.4" + } + }, "abab": { "version": "2.0.0", "resolved": "https://registry.npmjs.org/abab/-/abab-2.0.0.tgz", @@ -2304,6 +2376,17 @@ "map-cache": "0.2.2" } }, + "fs-extra": { + "version": "7.0.1", + "resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-7.0.1.tgz", + "integrity": "sha512-YJDaCJZEnBmcbw13fvdAM9AwNOJwOzrE4pqMqBq5nFiEqXUqHwlK4B+3pUw6JNvfSPtX05xFHtYy/1ni01eGCw==", + "dev": true, + "requires": { + "graceful-fs": "4.1.15", + "jsonfile": "4.0.0", + "universalify": "0.1.2" + } + }, "fs-readdir-recursive": { "version": "1.1.0", "resolved": "https://registry.npmjs.org/fs-readdir-recursive/-/fs-readdir-recursive-1.1.0.tgz", @@ -3103,6 +3186,12 @@ } } }, + "highlight.js": { + "version": "9.15.6", + "resolved": "https://registry.npmjs.org/highlight.js/-/highlight.js-9.15.6.tgz", + "integrity": "sha512-zozTAWM1D6sozHo8kqhfYgsac+B+q0PmsjXeyDrYIHHcBN0zTVT66+s2GW1GZv7DbyaROdLXKdabwS/WqPyIdQ==", + "dev": true + }, "hosted-git-info": { "version": "2.7.1", "resolved": "https://registry.npmjs.org/hosted-git-info/-/hosted-git-info-2.7.1.tgz", @@ -3215,6 +3304,12 @@ "through": "2.3.8" } }, + "interpret": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/interpret/-/interpret-1.2.0.tgz", + "integrity": "sha512-mT34yGKMNceBQUoVn7iCDKDntA7SC6gycMAWzGx1z/CMCTV7b2AAtXlo3nRyHZ1FelRkQbQjprHSYGwzLtkVbw==", + "dev": true + }, "invariant": { "version": "2.2.4", "resolved": "https://registry.npmjs.org/invariant/-/invariant-2.2.4.tgz", @@ -4106,6 +4201,15 @@ } } }, + "jsonfile": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/jsonfile/-/jsonfile-4.0.0.tgz", + "integrity": "sha1-h3Gq4HmbZAdrdmQPygWPnBDjPss=", + "dev": true, + "requires": { + "graceful-fs": "4.1.15" + } + }, "jsprim": { "version": "1.4.1", "resolved": "https://registry.npmjs.org/jsprim/-/jsprim-1.4.1.tgz", @@ -4246,6 +4350,12 @@ "object-visit": "1.0.1" } }, + "marked": { + "version": "0.4.0", + "resolved": "https://registry.npmjs.org/marked/-/marked-0.4.0.tgz", + "integrity": "sha512-tMsdNBgOsrUophCAFQl0XPe6Zqk/uy9gnue+jIIKhykO51hxyu6uNx7zBPy0+y/WKYVZZMspV9YeXLNdKk+iYw==", + "dev": true + }, "mem": { "version": "4.1.0", "resolved": "https://registry.npmjs.org/mem/-/mem-4.1.0.tgz", @@ -4952,6 +5062,15 @@ "util.promisify": "1.0.0" } }, + "rechoir": { + "version": "0.6.2", + "resolved": "https://registry.npmjs.org/rechoir/-/rechoir-0.6.2.tgz", + "integrity": "sha1-hSBLVNuoLVdC4oyWdW70OvUOM4Q=", + "dev": true, + "requires": { + "resolve": "1.10.0" + } + }, "redux": { "version": "4.0.1", "resolved": "https://registry.npmjs.org/redux/-/redux-4.0.1.tgz", @@ -5323,6 +5442,17 @@ "integrity": "sha1-2kL0l0DAtC2yypcoVxyxkMmO/qM=", "dev": true }, + "shelljs": { + "version": "0.8.3", + "resolved": "https://registry.npmjs.org/shelljs/-/shelljs-0.8.3.tgz", + "integrity": "sha512-fc0BKlAWiLpwZljmOvAOTE/gXawtCoNrP5oaY7KIaQbbyHeQVg01pSEuEGvGh3HEdBU4baCD7wQBwADmM/7f7A==", + "dev": true, + "requires": { + "glob": "7.1.3", + "interpret": "1.2.0", + "rechoir": "0.6.2" + } + }, "shellwords": { "version": "0.1.1", "resolved": "https://registry.npmjs.org/shellwords/-/shellwords-0.1.1.tgz", @@ -5889,6 +6019,45 @@ "prelude-ls": "1.1.2" } }, + "typedoc": { + "version": "0.14.2", + "resolved": "https://registry.npmjs.org/typedoc/-/typedoc-0.14.2.tgz", + "integrity": "sha512-aEbgJXV8/KqaVhcedT7xG6d2r+mOvB5ep3eIz1KuB5sc4fDYXcepEEMdU7XSqLFO5hVPu0nllHi1QxX2h/QlpQ==", + "dev": true, + "requires": { + "@types/fs-extra": "5.0.5", + "@types/handlebars": "4.0.40", + "@types/highlight.js": "9.12.3", + "@types/lodash": "4.14.122", + "@types/marked": "0.4.2", + "@types/minimatch": "3.0.3", + "@types/shelljs": "0.8.3", + "fs-extra": "7.0.1", + "handlebars": "4.1.0", + "highlight.js": "9.15.6", + "lodash": "4.17.11", + "marked": "0.4.0", + "minimatch": "3.0.4", + "progress": "2.0.3", + "shelljs": "0.8.3", + "typedoc-default-themes": "0.5.0", + "typescript": "3.2.4" + }, + "dependencies": { + "typescript": { + "version": "3.2.4", + "resolved": "https://registry.npmjs.org/typescript/-/typescript-3.2.4.tgz", + "integrity": "sha512-0RNDbSdEokBeEAkgNbxJ+BLwSManFy9TeXz8uW+48j/xhEXv1ePME60olyzw2XzUqUBNAYFeJadIqAgNqIACwg==", + "dev": true + } + } + }, + "typedoc-default-themes": { + "version": "0.5.0", + "resolved": "https://registry.npmjs.org/typedoc-default-themes/-/typedoc-default-themes-0.5.0.tgz", + "integrity": "sha1-bcJDPnjti+qOiHo6zeLzF4W9Yic=", + "dev": true + }, "typescript": { "version": "3.3.3333", "resolved": "https://registry.npmjs.org/typescript/-/typescript-3.3.3333.tgz", @@ -5985,6 +6154,12 @@ } } }, + "universalify": { + "version": "0.1.2", + "resolved": "https://registry.npmjs.org/universalify/-/universalify-0.1.2.tgz", + "integrity": "sha512-rBJeI5CXAlmy1pV+617WB9J63U6XcazHHF2f2dbJix4XzpUF0RS3Zbj0FGIOCAva5P/d/GBOYaACQ1w+0azUkg==", + "dev": true + }, "unset-value": { "version": "1.0.0", "resolved": "https://registry.npmjs.org/unset-value/-/unset-value-1.0.0.tgz", diff --git a/package.json b/package.json index 939314a..2b19243 100644 --- a/package.json +++ b/package.json @@ -6,6 +6,7 @@ "scripts": { "build": "./build.sh", "build:code": "babel src --out-dir build --extensions '.ts' --ignore '**/*.test.ts'", + "build:docs": "typedoc src", "build:types": "tsc --emitDeclarationOnly", "clean": "rimraf build coverage", "lint:js": "eslint 'src/**/**?(.spec|).js'", @@ -51,6 +52,7 @@ "prettier": "^1.16.4", "redux": "^4.0.1", "rimraf": "^2.6.3", + "typedoc": "^0.14.2", "typescript": "^3.3.3333" }, "jest": { diff --git a/src/index.ts b/src/index.ts index cc23ea0..cbcd120 100644 --- a/src/index.ts +++ b/src/index.ts @@ -54,6 +54,17 @@ export interface IActionTracer { prev(): TestAction | void; } +/** + * The action runner takes an action and recursively + * calls any thunks with an action runner. + * + * @param action TestAction | Function + * @returns Promise + */ +export interface IActionRunner { + (action: TestAction | Function): Promise +}; + /** * Store for calls */ @@ -79,8 +90,7 @@ export interface IActionStore { } /** - * Normalizes actions - * converts thunks to actions with thunk payloads + * Converts thunks to actions with thunk payloads * * @param action Function * @return TestAction @@ -140,7 +150,7 @@ export function convertGenericToSnapshot(value: unknown): unknown { } /** - * Snapshots an action for comparison + * Creates a snapshot object for an action. * * @param action TestAction | Function * @returns TestAction @@ -157,7 +167,7 @@ export function actionSnapshot(action: TestAction | Function): TestAction { } /** - * Generates an array of snapshots from a list of actions + * Creates an array of snapshot objects for the list of actions. * * @param actions Array * @returns Array @@ -169,7 +179,7 @@ export function actionArraySnapshot( } /** - * Generates an array of snapshots from the action tester + * Generates an array of snapshots from an IActionStore compatible tester. * * @param tester IActionStore * @returns Array @@ -179,7 +189,7 @@ export function actionTesterSnapshot(tester: IActionStore): Array { } /** - * Creates an action runner + * Creates an action runner. * * @param tester IActionStore * @param thunkArgs getState + extraArguments @@ -188,14 +198,7 @@ export function actionTesterSnapshot(tester: IActionStore): Array { export function createActionRunner( tester: IActionStore, ...thunkArgs: ThunkArgs -) { - /** - * The action runner. - * Recursively calls the action and executes the thunk - * - * @param action TestAction | Function - * @returns Promise - */ +): IActionRunner { async function actionRunner(action: TestAction | Function): Promise { const normalised = actionNormalizer(action); @@ -212,8 +215,8 @@ export function createActionRunner( } /** - * Gets as current(), prev(), next() step methods for stepping through - * the called actions + * Gets an object with step methods for stepping through + * the called actions. * * @param tester IActionStore * @returns IActionTracer @@ -245,7 +248,7 @@ export function actionTypes(tester: IActionStore): Array { } /** - * A test-framework independent utility + * A test-framework independent test runner class */ export class ActionTester implements IActionStore { callList: CallList = []; @@ -278,7 +281,7 @@ export class ActionTester implements IActionStore { }; /** - * dispatches an action and runs through the call tree + * Dispatches an action and runs through the call tree. * * @param action TestAction | Function * @returns Promise @@ -290,21 +293,21 @@ export class ActionTester implements IActionStore { /** * Gets a list containing only the type of dispatched actions - * in the order in which they were called + * in the order in which they were called. * * @returns Array */ toTypes = (): Array => actionTypes(this); /** - * Gets a faux tracer/stepper function to step through the calls + * Gets a object containing step functions to step through the calls. * * @returns IActionTracer */ toTracer = (): IActionTracer => actionTracer(this); /** - * Generates a snapshot of actions dispatched + * Generates a snapshot of actions dispatched. * * @returns Array */ @@ -314,13 +317,13 @@ export class ActionTester implements IActionStore { } /** - * Jest compatible ActionTester + * A jest compatible test runner class */ export class JestActionTester extends ActionTester { jestFn: any; /** - * Takes in jest mock function + * Takes in jest mock function. * * @param jestFn jest.fn() */ diff --git a/typedoc.json b/typedoc.json new file mode 100644 index 0000000..085b51b --- /dev/null +++ b/typedoc.json @@ -0,0 +1,5 @@ +{ + "mode": "modules", + "out": "docs", + "exclude": ["tests", "**/*.test.ts"] +}