v3 Add Async modules and type checking

Author: theKashey

.babelrc

@@ -1,7 +1,38 @@
 {
- "presets": ["latest"],
- "plugins": [
-  ["transform-object-rest-spread", { "useBuiltIns": true }],
-  "dynamic-import-node"
- ]
+  "presets": [],
+  "env": {
+    "cjs": {
+      "presets": [
+        "env"
+      ],
+      "plugins": [
+        [
+          "transform-object-rest-spread",
+          {
+            "useBuiltIns": true
+          }
+        ],
+        "dynamic-import-node"
+      ]
+    },
+    "ejs": {
+      "presets": [
+        [
+          "env",
+          {
+            "modules": false
+          }
+        ]
+      ],
+      "plugins": [
+        [
+          "transform-object-rest-spread",
+          {
+            "useBuiltIns": true
+          }
+        ],
+        "dynamic-import-node"
+      ]
+    }
+  }
 }

.flowconfig

@@ -0,0 +1,11 @@
+[ignore]
+
+[include]
+
+[libs]
+
+[lints]
+
+[options]
+
+[strict]

README.md

@@ -24,22 +24,22 @@ and magic of [proxyquire-webpack-alias](https://github.com/theKashey/proxyquire-
 - be fast, to be faster.
 
 # Goal:
-- give ability to mock everything
-- give ability to do correctly.
+- give ability to mock everything - CommonJS, ES6, Webpack, anything.
+- give ability to do correctly - isolation, typechecks, powerfull API
 
 I have wrote some articles about these ideas - https://medium.com/tag/rewiremock/latest
 
 # API
 
  ## main API
  - rewiremock.enable() - wipes cache and enables interceptor.
- - rewiremock.disable() - wipes cache and disables interceptor.
- - rewiremock.inScope(callback) - place callback inside a sandbox.
- - rewiremock.around(loader, creator) - loads a module in an asynchronous sandbox.
- - rewiremock.proxy(file, stubs) - _proxyquire_ like mocking api, where file is file name, and stubs are an object or a function.
- - rewiremock.module(loader, stubs) - async version of proxy, where loader is a function.
+ - rewiremock.disable() - wipes cache and disables interceptor.    
+ - rewiremock.around(loader, creator):Promise< T > - loads a module in an **asynchronous** sandbox.
+ - rewiremock.proxy(file, stubs):T - _proxyquire_ like mocking api, where file is file name, and stubs are an object or a function.
+ - rewiremock.module(loader, stubs):Promise< T > - async version of proxy, where loader is a function.
  ## mocking API 
- - rewiremock(moduleName: string) - set name of overloading module
+ - rewiremock(moduleName: string) - fabric for a moduleNames's mock
+ - rewiremock(moduleImport: loader) - async fabric for a module import function.
     - .enable/disable() - to enable or disable mock (enabled by default).
     - .with(stubs: function | Object) - overloads module with a value
     - .withDefault(stub: function | Object) - overload `default` es6 export
@@ -52,20 +52,23 @@ I have wrote some articles about these ideas - https://medium.com/tag/rewiremock
  - rewiremock.isolation() - enables isolation
  - rewiremock.withoutIsolation() - disables isolation
  - rewiremock.passBy(pattern or function) - enables some modules to pass thought isolation.
+ ## sandboxing
+ - rewiremock.inScope(callback) - place synchronous callback inside a sandbox.
 
 # Which one?
 Yep - there is 4 top level ways to activate a mock - inScope, around, proxy or just enable.
 
 Which one to choose? Any! It just depends:
-  - If everything is simply - use __proxy__.
-  - If you have issues with name resolve - use __module__ and resolve names by yourself.
-  - If you need scope isolation - use __around__. inScope is just creating a scope and can be used in all cases.
+  - If everything is simply - use __rewiremock.proxy__.
+  - If you have issues with name resolve - use __rewiremock.module__ and resolve names by yourself.
+  - If you need scope isolation - use __rewiremock.around__, or inScope.
+  - If you advanced syntax and type checking - use __rewiremock.around__.
   - If you need full control - you will always have it.
-  - As long all internal API will call __.enable/.disable__ - I would not recommend using them directly.  
+  - You always can just use __.enable/.disable__.  
 
 #Usage
 ```js
-// 1. proxy will load a file by it's own ( name resolution is a hard thing)
+// 1. proxy will load a file by it's own ( keep in mind - name resolution is a complex thing)
 const mock = rewiremock.proxy('somemodule', (r) => ({
    'dep1': { name: 'override' },
    'dep2': r.with({name: 'override' }).toBeUsed().directChildOnly() // use all `mocking API`  
@@ -78,6 +81,7 @@ const mock = rewiremock.proxy(() => require('somemodule'), {
 }));
 
 // 3. or use es6 import (not for node.js mjs `real` es6 modules) 
+// PS: module is an async version of proxy, so you can use imports
 const mock = await rewiremock.module(() => import('somemodule'), {
    'dep1': { name: 'override' },
    'dep2': { onlyDump: 'stubs' }  
@@ -95,6 +99,49 @@ const mock = await rewiremock.around(() => import('somemodule'), () => {
   rewiremock.disable();
 ```
 
+# Type safety
+Rewiremock is able to provide a type-safe mocks. To enable type-safety follow these steps:
+1. Use TypeScript or Flow.
+2. Use dynamic import syntax.
+3. Use rewiremock.around or rewiremock.module to perform a mock.
+4. Use async form of rewiremock mock declaration.  
+
+```js
+// @flow
+
+import rewiremock  from 'rewiremock';
+
+rewiremock.around(
+  () => import('./a.js'), 
+  mock => {
+  mock(() => import('./b.js'))
+    .withDefault(() => "4")
+    .with({testB: () => 10})
+    .nonStrict() // turn off type system
+    .with({ absolutely: "anything" })
+  }
+);
+```
+If default export is not exists on module 'b', or there is no named export testB, or types do not match - type system will throw.
+
+If you will declare an async mock, you it will not be resolved by the time of execution - Rewiremock will throw on Error.
+
+If you have async imports inside mocked file, follow this syntax
+```js
+rewiremock.around(
+  () => import('./a.js'), 
+  mock => {
+  // just before loader function rewiremock enabled itself
+  mock(() => import('./b.js').then(mock=>mock)) // mocks `live` one `tick` more
+  // just after loader function resolved rewiremock disables itself
+    mock => {
+    ....
+    }
+  }
+);
+```
+ 
+
 # Setup
 
 ## To run with node.js

_tests/lib/typed/a-delayed.js

@@ -0,0 +1,6 @@
+// @flow
+let a=42;
+
+import('./b.js').then(t => a=t.default());
+
+export default () => a;

_tests/lib/typed/a.js

@@ -0,0 +1,5 @@
+// @flow
+
+import test from './b.js';
+
+export default () => test();

_tests/lib/typed/b.js

@@ -0,0 +1,2 @@
+// @flow
+export default () => 10;

_tests/typedImport.spec.js

@@ -0,0 +1,62 @@
+// @flow
+
+import { expect } from 'chai';
+import rewiremock from '../src/index';
+
+describe('typed import ', () => {
+  it('should throw: ', () => {
+    rewiremock.inScope(() => {
+      rewiremock(() => import('./lib/typed/b.js')).with(() => 42);
+      rewiremock.enable();
+      try {
+        require('./lib/typed/a.js');
+        expect("should throw").to.be.false();
+      } catch (e) {
+        expect(true).to.be.equal(true);
+      }
+      rewiremock.disable();
+    });
+  });
+
+  it('import as a mock name: ', () => {
+    const unmockedBaz = require('./lib/typed/a.js');
+    expect(unmockedBaz.default()).to.be.equal(10);
+
+    const mockedBazLoad = rewiremock.around(
+      () => import('./lib/typed/a.js'),
+      mock => {
+        mock(() => import('./lib/typed/b.js')).with(() => 42).toBeUsed();
+      });
+
+    return mockedBazLoad.then(mockedBaz => {
+      expect(mockedBaz.default()).to.be.equal(42)
+    })
+  });
+
+  describe('import delayed: ', () => {
+    it('import after: ', () => {
+      const mockedBazLoad = rewiremock.around(
+        () => import('./lib/typed/a-delayed.js'),
+        mock => {
+          mock(() => import('./lib/typed/b.js')).with(() => 0);
+        });
+
+      return mockedBazLoad.then(mockedBaz => {
+        expect(mockedBaz.default()).not.to.be.equal('aa')
+      })
+    });
+
+    it('import before: ', () => {
+      return rewiremock.around(
+        () =>
+          import('./lib/typed/a-delayed.js')
+            .then(module => module) // emulate time tick
+            .then(mockedBaz => {
+              expect(mockedBaz.default()).to.be.equal(5)
+            }),
+        mock => {
+          mock(() => import('./lib/typed/b.js')).with(() => 5);
+        });
+    });
+  });
+});

es/_common.js

@@ -0,0 +1,5 @@
+var extensions = ['', '.js', '.jsx'];
+
+var magicProps = ['__esModule'];
+
+export { extensions, magicProps };

es/asyncModules.js

@@ -0,0 +1,38 @@
+import { getAllAsyncMocks, insertMock } from "./mocks";
+
+var currentModule = void 0;
+
+var loadInRoll = function loadInRoll(mocks) {
+  if (mocks.length) {
+    currentModule = mocks[0];
+    return Promise.resolve().then(currentModule.creator).then(function () {
+      return loadInRoll(mocks.slice(1));
+    });
+  } else {
+    return Promise.resolve();
+  }
+};
+
+var probeAsyncModules = {
+  hasAsyncModules: function hasAsyncModules() {
+    var mocks = getAllAsyncMocks();
+    return mocks.length ? mocks : false;
+  },
+
+
+  load: function load(Module) {
+    return function (request, parent) {
+      currentModule.loaded = true;
+      var baseRequest = Module._resolveFilename(request, parent);
+      currentModule.mock.name = baseRequest;
+      insertMock(baseRequest, currentModule.mock);
+    };
+  },
+
+  execute: function execute() {
+    var mocks = getAllAsyncMocks();
+    return loadInRoll(mocks);
+  }
+};
+
+export default probeAsyncModules;