Improve dynamics import docs and tests (#135)

* Improve the way dynamic imports are done in tests

* Update dynamic import docs

* Fix typo

Author: talyssonoc

docs/schema-concept/circular-references-and-dynamic-types.md

@@ -4,7 +4,7 @@ Sometimes we may need to have a type reference itself in its attributes, or have
 
 When using dynamic types you can pass a string instead of the type itself in the type definition, this string will contain the type **identifier**, and then pass an object as the _second_ parameter of the `attributes` function with a key `dynamics` where the concrete type for each identifier is declared:
 
-```javascript
+```js
 /*
  * User.js
  */
@@ -13,27 +13,29 @@ const User = attributes(
     name: String,
     friends: {
       type: Array,
-      itemType: 'User', // << dynamic type with inferred identifier
+      itemType: 'User', // << identifier
     },
     favoriteBook: {
-      type: 'BookStructure', // << dynamic type with custom identifier
+      type: 'BookStructure', // << identifier
       required: true,
     },
     books: {
-      type: 'BooksCollection', // << dynamic type with inferred identifier
+      type: 'BooksCollection', // << identifier
       itemType: String,
     },
   },
   {
     dynamics: {
-      /* dynamic types */
+      /* dynamic types for each identifier */
       User: () => User,
       BookStructure: () => require('./Book'),
       BooksCollection: () => require('./BooksCollection'),
     },
   }
 )(class User {});
 
+module.exports = User;
+
 /*
  * Book.js
  */
@@ -46,14 +48,18 @@ const Book = attributes(
   {
     identifier: 'BookStructure', // << custom identifier
     dynamics: {
-      /* dynamic types */
+      /* dynamic types for each identifier */
       User: () => require('./User'),
       BookStructure: () => Book,
     },
   }
 )(class Book {});
+
+module.exports = Book;
 ```
 
+If you're using `import` instead of `require` (thus having to import the dynamic value in the top-level of the file), go to the [With ES Modules](#with-es-modules) section of this page.
+
 ## Dynamic type identifier
 
 The type's identifier has to be same everywhere it's used, and can be defined in two ways:
@@ -75,7 +81,7 @@ const User = attributes(
   }
 )(
   class User {
-    //   ^ the name of this class is the identifier
+    //   ⬑-- the name of this class is the identifier
     // so if we change this name to UserEntity, we'll have to change
     // both [A] and [B] to use the string 'UserEntity' instead of 'User'
   }
@@ -97,15 +103,22 @@ const User = attributes(
   {
     identifier: 'UserEntity', // << custom identifier
     dynamics: {
-      UserEntity: () => User, // << custom identifier concrete type
+      // ⬐--- custom identifier concrete type
+      UserEntity: () => User,
     },
   }
 )(class User {});
 ```
 
-### Concrete type definition inside `dynamics`
+## Concrete type definition inside `dynamics`
+
+For the cases where the dynamic type is in a different file, it's important that the actual needs type to be resolved **inside** the function with the identifier. Let's break it down in two cases:
 
-For the cases where the dynamic type is in a different file, it's important to call the `require` **inside** the function that returns the dynamic type, **not** in the top level of your file:
+### With CommonJS modules
+
+When using CommonJS modules you have two possibilities:
+
+1. Putting the `require` call directly inside the concrete type resolution function:
 
 ```js
 const Book = attributes(
@@ -122,4 +135,102 @@ const Book = attributes(
     },
   }
 )(class Book {});
+
+module.exports = Book;
+```
+
+2. Exporting an **object** containing your other structure (instead of exporting the structure itself) and only access it inside the concrete type resolution function:
+
+```js
+/*
+ * User.js
+ */
+const BookModule = require('./Book');
+
+const User = attributes(
+  {
+    name: String,
+    favoriteBook: {
+      type: 'Book',
+      required: true,
+    },
+  },
+  {
+    dynamics: {
+      User: () => User,
+      Book: () => BookModule.Book,
+    },
+  }
+)(class User {});
+
+exports.User = User;
+
+/*
+ * Book.js
+ */
+const UserModule = require('./User');
+
+const Book = attributes(
+  {
+    name: String,
+    owner: 'User',
+  },
+  {
+    dynamics: {
+      User: () => UserModule.User,
+      Book: () => Book,
+    },
+  }
+)(class Book {});
+
+exports.Book = Book;
+```
+
+### With ES Modules
+
+When using ES Modules you have a single possibility, which is importing the other structure from the top-level of your file and then returning it from the concrete type resolution function. It's important to note that this **only** works with ES Modules, if you're using CommonJS, check the [With CommonJS modules](#with-commonjs-modules) section.
+
+```javascript
+/*
+ * User.js
+ */
+import Book from './Book';
+
+const User = attributes(
+  {
+    name: String,
+    favoriteBook: {
+      type: 'Book',
+      required: true,
+    },
+  },
+  {
+    dynamics: {
+      User: () => User,
+      Book: () => Book,
+    },
+  }
+)(class User {});
+
+export default User;
+
+/*
+ * Book.js
+ */
+import User from './User';
+
+const Book = attributes(
+  {
+    name: String,
+    owner: 'User',
+  },
+  {
+    dynamics: {
+      User: () => User,
+      Book: () => Book,
+    },
+  }
+)(class Book {});
+
+export default Book;
 ```

packages/structure/test/fixtures/CircularBook.js

@@ -1,4 +1,5 @@
 const { attributes } = require('../../src');
+const UserModule = require('./CircularUser');
 
 const Book = attributes(
   {
@@ -11,10 +12,10 @@ const Book = attributes(
   },
   {
     dynamics: {
-      User: () => require('./CircularUser'),
+      User: () => UserModule.User,
       Book: () => Book,
     },
   }
 )(class Book {});
 
-module.exports = Book;
+exports.Book = Book;

packages/structure/test/fixtures/CircularBookCustomIdentifier.js

@@ -1,4 +1,5 @@
 const { attributes } = require('../../src');
+const UserModule = require('./CircularUserCustomIdentifier');
 
 const Book = attributes(
   {
@@ -12,10 +13,10 @@ const Book = attributes(
   {
     identifier: 'BookEntity',
     dynamics: {
-      UserEntity: () => require('./CircularUserCustomIdentifier'),
+      UserEntity: () => UserModule.User,
       BookEntity: () => Book,
     },
   }
 )(class Book {});
 
-module.exports = Book;
+exports.Book = Book;

packages/structure/test/fixtures/CircularUser.js

@@ -1,4 +1,6 @@
 const { attributes } = require('../../src');
+const BookModule = require('./CircularBook');
+const BooksCollection = require('./BooksCollection');
 
 const User = attributes(
   {
@@ -23,10 +25,10 @@ const User = attributes(
   {
     dynamics: {
       User: () => User,
-      Book: () => require('./CircularBook'),
-      BooksCollection: () => require('./BooksCollection'),
+      Book: () => BookModule.Book,
+      BooksCollection: () => BooksCollection,
     },
   }
 )(class User {});
 
-module.exports = User;
+exports.User = User;

packages/structure/test/fixtures/CircularUserCustomIdentifier.js

@@ -1,4 +1,5 @@
 const { attributes } = require('../../src');
+const BookModule = require('./CircularBookCustomIdentifier');
 
 const User = attributes(
   {
@@ -17,9 +18,9 @@ const User = attributes(
     identifier: 'UserEntity',
     dynamics: {
       UserEntity: () => User,
-      BookEntity: () => require('./CircularBookCustomIdentifier'),
+      BookEntity: () => BookModule.Book,
     },
   }
 )(class User {});
 
-module.exports = User;
+exports.User = User;

packages/structure/test/unit/coercion/array.spec.js

@@ -184,7 +184,7 @@ describe('type coercion', () => {
       let BooksCollection;
 
       beforeEach(() => {
-        CircularUser = require('../../fixtures/CircularUser');
+        CircularUser = require('../../fixtures/CircularUser').User;
         BooksCollection = require('../../fixtures/BooksCollection');
       });
 

packages/structure/test/unit/coercion/structure.spec.js

@@ -101,8 +101,8 @@ describe('type coercion', () => {
     let CircularBook;
 
     beforeEach(() => {
-      CircularUser = require('../../fixtures/CircularUser');
-      CircularBook = require('../../fixtures/CircularBook');
+      CircularUser = require('../../fixtures/CircularUser').User;
+      CircularBook = require('../../fixtures/CircularBook').Book;
     });
 
     describe('when there are not allowed nullable attributes', () => {

packages/structure/test/unit/instanceAndUpdate.spec.js

@@ -355,8 +355,8 @@ describe('instantiating a structure with dynamic attribute types', () => {
   let CircularBook;
 
   beforeEach(() => {
-    CircularUser = require('../fixtures/CircularUser');
-    CircularBook = require('../fixtures/CircularBook');
+    CircularUser = require('../fixtures/CircularUser').User;
+    CircularBook = require('../fixtures/CircularBook').Book;
   });
 
   it('creates instance properly', () => {
@@ -490,8 +490,8 @@ describe('updating a structure with dynamic attribute types', () => {
   let CircularBook;
 
   beforeEach(() => {
-    CircularUser = require('../fixtures/CircularUser');
-    CircularBook = require('../fixtures/CircularBook');
+    CircularUser = require('../fixtures/CircularUser').User;
+    CircularBook = require('../fixtures/CircularBook').Book;
   });
 
   it('updates instance attribute when assigned a new value', () => {

packages/structure/test/unit/serialization/nestedStructure.spec.js

@@ -81,8 +81,8 @@ describe('serialization', () => {
     let CircularBook;
 
     beforeEach(() => {
-      CircularUser = require('../../fixtures/CircularUser');
-      CircularBook = require('../../fixtures/CircularBook');
+      CircularUser = require('../../fixtures/CircularUser').User;
+      CircularBook = require('../../fixtures/CircularBook').Book;
     });
 
     describe('when all data is present', () => {

packages/structure/test/unit/validation/array.spec.js

@@ -226,7 +226,7 @@ describe('validation', () => {
       let CircularUser;
 
       beforeEach(() => {
-        CircularUser = require('../../fixtures/CircularUser');
+        CircularUser = require('../../fixtures/CircularUser').User;
       });
 
       describe('when nested value is present', () => {