Merge 106da9f into b48d1ba

talyssonoc · Mar 21, 2020 · c4b1e86 · c4b1e86
2 parents b48d1ba + 106da9f
commit c4b1e86
Show file tree

Hide file tree

Showing 30 changed files with 251 additions and 232 deletions.
diff --git a/README.md b/README.md
@@ -1,28 +1,28 @@
-# <a href="https://structure.js.org/"><img src="https://raw.githubusercontent.com/talyssonoc/structure/master/structure.jpg" width="300"></a>
+# Introduction
 
 ## A simple schema/attributes library built on top of modern JavaScript
 
-[![npm](https://img.shields.io/npm/v/structure.svg?style=flat)](https://www.npmjs.com/package/structure) [![Build Status](https://travis-ci.org/talyssonoc/structure.svg?branch=master)](https://travis-ci.org/talyssonoc/structure) [![Coverage Status](https://coveralls.io/repos/github/talyssonoc/structure/badge.svg?branch=master)](https://coveralls.io/github/talyssonoc/structure?branch=master) [![Code Climate](https://codeclimate.com/github/talyssonoc/structure/badges/gpa.svg)](https://codeclimate.com/github/talyssonoc/structure) [![JS.ORG](https://img.shields.io/badge/js.org-structure-ffb400.svg?style=flat)](https://js.org/)
----
+## [![npm](https://img.shields.io/npm/v/structure.svg?style=flat)](https://www.npmjs.com/package/structure) [![Build Status](https://travis-ci.org/talyssonoc/structure.svg?branch=master)](https://travis-ci.org/talyssonoc/structure) [![Coverage Status](https://coveralls.io/repos/github/talyssonoc/structure/badge.svg?branch=master)](https://coveralls.io/github/talyssonoc/structure?branch=master) [![Code Climate](https://codeclimate.com/github/talyssonoc/structure/badges/gpa.svg)](https://codeclimate.com/github/talyssonoc/structure) [![JS.ORG](https://img.shields.io/badge/js.org-structure-ffb400.svg?style=flat)](https://js.org/)
+
 Structure provides a simple interface which allows you to add attributes to your ES6 classes based on a schema, with validations and type coercion.
 
 ## Use cases
 
 You can use Structure for a lot of different cases, including:
 
-- Domain entities and value objects
-- Model business rules
-- Validation and coercion of request data
-- Map pure objects and JSON to your application classes
-- Add attributes to classes that you can't change the class hierarchy
+* Domain entities and value objects
+* Model business rules
+* Validation and coercion of request data
+* Map pure objects and JSON to your application classes
+* Add attributes to classes that you can't change the class hierarchy
 
 Structure was inspired by Ruby's [Virtus](https://github.com/solnic/virtus).
 
-What Structure is __not__:
+What Structure is **not**:
 
-- It's not a database abstraction
-- It's not a MVC framework (but it can be used to domain entities)
-- It's not an attempt to simulate classic inheritance in JavaScript
+* It's not a database abstraction
+* It's not a MVC framework \(but it can be used to domain entities\)
+* It's not an attempt to simulate classic inheritance in JavaScript
 
 ## Getting started
 
@@ -32,7 +32,7 @@ What Structure is __not__:
 
 For each attribute on your schema, a getter and a setter will be created into the given class. It'll also auto-assign those attributes passed to the constructor.
 
-```js
+```javascript
 const { attributes } = require('structure');
 
 const User = attributes({
@@ -78,7 +78,7 @@ Right now 95.5% of the tests will pass on Chrome 55, and 95% will pass on Firefo
 
 There are configurable [BattleCry](https://github.com/pedsmoreira/battlecry) generators ready to be downloaded and help scaffolding schema:
 
-```sh
+```bash
 npm install -g battlecry
 cry download generator talyssonoc/structure
 cry g schema user name age:int:required cars:string[] favoriteBook:book friends:user[]:default :updateAge
@@ -89,3 +89,4 @@ Run `cry --help` to check more info about the generators available;
 ## [Contributing](contributing.md)
 
 ## [LICENSE](license.md)
+
diff --git a/docs/cloning.md → cloning.md b/docs/cloning.md → cloning.md
@@ -2,7 +2,7 @@
 
 Structure adds a method `#clone` in order to be able to create a **shallow** copy of an instance. This methods accepts an optional overwrite object that permits you to overwrite some attributes of the copy.
 
-```js
+```javascript
 const { attributes } = require('structure');
 
 const User = attributes({
@@ -20,7 +20,7 @@ const cloneWithOverwrite = user.clone({ name: 'Myself' }); // User { name: 'Myse
 
 If the structure has a nested structure inside of it, the `#clone` method **will not** clone it but just point the new instance to the old value of the nested attribute.
 
-```js
+```javascript
 const { attributes } = require('structure');
 
 const Book = attributes({
@@ -51,7 +51,7 @@ cloneWithOverwrite.favoriteBook; // Book { name: 'The Lord of the Rings' }
 
 When cloning an instance, you can clone it in [strict mode](strict-mode.md) as well, so if the resulting clone is invalid it throws an error. To do that, pass a second argument to the `#clone` method with the option `strict` as `true`.
 
-```js
+```javascript
 const { attributes } = require('structure');
 
 const User = attributes({
@@ -76,3 +76,4 @@ const clonedUser = user.clone(
 //   { message: '"name" is required', path: 'name' }
 // ]
 ```
+
diff --git a/coercion/README.md b/coercion/README.md
@@ -0,0 +1,10 @@
+# Coercion
+
+Structure does type coercion based on the declared [schema](../schema-concept/). It's important to note that it **never** coerces the following scenarios:
+
+* `undefined`;
+* `null` when `nullable` option is enabled;
+* value is already of the declared type \(except for arrays, we'll talk more about this soon\).
+
+Let's break the coercion into 3 categories.
+
diff --git a/docs/coercion/arrays-and-array-subclasses.md → coercion/arrays-and-array-subclasses.md b/docs/coercion/arrays-and-array-subclasses.md → coercion/arrays-and-array-subclasses.md
@@ -1,4 +1,4 @@
-# Arrays and Array subclasses
+# Arrays coercion
 
 It's also possible to coerce values to `Array` or some other class that extends `Array`. On these circumstances Structure will use the `itemType` value of the type descriptor on the schema to coerce the items as well. Note that, when coercing arrays, it'll always create a new instance of the type and then push each item of the passed value to the new instance:
 
@@ -26,3 +26,4 @@ libraryOne.users; // ['John', 'Jane'] => new instance of Array
 ```
 
 The passed raw value have to be non-null and have a `length` attribute or implement the `Symbol.iterator` method, otherwise it'll fail to coerce and throw a `TypeError`.
+
diff --git a/docs/coercion/generic-coercion.md → coercion/generic-coercion.md b/docs/coercion/generic-coercion.md → coercion/generic-coercion.md
@@ -1,6 +1,6 @@
 # Generic coercion
 
-If the declared type is not a primitive nor Array (or an array subclass) it'll do generic coercion. When generic coercing a value, Structure will just instantiate the declared type (using `new`) passing the raw value as the parameter (only if the raw value isn't of the declared type already).
+If the declared type is not a primitive nor Array \(or an array subclass\) it'll do generic coercion. When generic coercing a value, Structure will just instantiate the declared type \(using `new`\) passing the raw value as the parameter \(only if the raw value isn't of the declared type already\).
 
 ```javascript
 class Location {
@@ -29,3 +29,4 @@ userTwo.location; // Location { x: 3, y: 4 } => coerced plain object to Location
 ```
 
 Coercion to `Date` type enters in this same category, so if you have an attribute of the type `Date`, it'll use `new Date(<raw value>)` to coerce it. For more info about how this coercion works check the cases for `value` and `dateString` parameters on [Date documentation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date).
+
diff --git a/docs/coercion/observations.md → coercion/observations.md b/docs/coercion/observations.md → coercion/observations.md
@@ -1,6 +1,6 @@
 # Observations
 
-__Important: Structure only does coercion during object creation, so mutating an array (using push, for example) won't coerce the new item:__
+**Important: Structure only does coercion during object creation, so mutating an array \(using push, for example\) won't coerce the new item:**
 
 ```javascript
 const Library = attributes({
@@ -19,5 +19,5 @@ library.books; // ['1984'] => coerced number to string
 library.books.push(42);
 
 library.books; // ['1984', 42] => new item was not coerced
-
 ```
+
diff --git a/docs/coercion/primitive-type-coercion.md → coercion/primitive-type-coercion.md b/docs/coercion/primitive-type-coercion.md → coercion/primitive-type-coercion.md
@@ -2,9 +2,9 @@
 
 It's said to be primitive type coercion when it tries to coerce values to `String`, `Number` or `Boolean` types.
 
-For those types we basically use the type as a function (without using `new`), with a subtle difference: When coercing `null` to `String`, it'll coerce to empty string instead of the string `'null'`. For example:
+For those types we basically use the type as a function \(without using `new`\), with a subtle difference: When coercing `null` to `String`, it'll coerce to empty string instead of the string `'null'`. For example:
 
-```js
+```javascript
 const User = attributes({
   name: String,
   age: Number,
@@ -31,3 +31,4 @@ userTwo.name; // '' => coerced `null` to empty string
 userTwo.age; // 100 => coerced string to number
 userTwo.isAdmin; // undefined => it'll never coerce `undefined`
 ```
+
diff --git a/docs/coercion/recursive-coercion.md → coercion/recursive-coercion.md b/docs/coercion/recursive-coercion.md → coercion/recursive-coercion.md
@@ -27,3 +27,4 @@ const user = new User({
 user.favoriteBook; // Book { name: 'The Silmarillion' } => coerced plain object to Book
 user.books; // BooksCollection [ Book { name: '1984' } ] => coerced array to BooksCollection and plain object to Book
 ```
+
diff --git a/contributing.md b/contributing.md
@@ -8,7 +8,7 @@ In short: _Be nice_. Pay attention to the fact that Structure is free software,
 
 ## Opening issues
 
-When opening an issue be descriptive about the bug or the feature suggestion, don't simply paste the error message on the issue title or description. Also, __provide code to simulate the bug__, we need to know the exact circumstances in which the bug occurs. Again, follow our [code of conduct](#code-of-conduct).
+When opening an issue be descriptive about the bug or the feature suggestion, don't simply paste the error message on the issue title or description. Also, **provide code to simulate the bug**, we need to know the exact circumstances in which the bug occurs. Again, follow our [code of conduct](contributing.md#code-of-conduct).
 
 ## Pull requests
 
@@ -22,4 +22,5 @@ When opening a pull request to Structure, follow this steps:
 6. Open the pull request;
 7. Write a complete description about the bug or the feature the pull request is about.
 
-Be aware that we keep __100% of code coverage__, any change that makes the code coverage less than 100% covered will be requested to write more tests.
+Be aware that we keep **100% of code coverage**, any change that makes the code coverage less than 100% covered will be requested to write more tests.
+
diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
@@ -1,28 +1,29 @@
 # Table of contents
 
-- [Introduction](../README.md)
-- [Schema concept](schema-concept/README.md)
-  - [Shorthand and complete type descriptor](schema-concept/shorthand-and-complete-type-descriptor.md)
-  - [Circular reference](schema-concept/circular-references-and-dynamic-types.md)
-  - [Nullable attributes](schema-concept/nullable-attributes.md)
-- [Coercion](coercion/README.md)
-  - [Primitive type coercion](coercion/primitive-type-coercion.md)
-  - [Arrays coercion](coercion/arrays-and-array-subclasses.md)
-  - [Generic coercion](coercion/generic-coercion.md)
-  - [Recursive coercion](coercion/recursive-coercion.md)
-  - [Observations](coercion/observations.md)
-- [Validation](validation/README.md)
-  - [String validations](validation/string-validations.md)
-  - [Number validations](validation/number-validations.md)
-  - [Boolean validations](validation/boolean-validations.md)
-  - [Date validations](validation/date-validations.md)
-  - [Array validations](validation/array-validations.md)
-  - [Attribute reference](validation/attribute-reference.md)
-  - [Nested validations](validation/nested-validations.md)
-  - [Validate raw data](validation/validate-raw-data.md)
-- [Strict mode](strict-mode.md)
-- [Cloning an instance](cloning.md)
-- [Serialization](serialization.md)
-- [Contributing](../contributing.md)
-- [License](../license.md)
-- [GitHub](https://github.com/talyssonoc/structure)
+* [Introduction](../README.md)
+* [Schema concept](../schema-concept/README.md)
+  * [Shorthand and complete type descriptor](../schema-concept/shorthand-and-complete-type-descriptor.md)
+  * [Circular reference](../schema-concept/circular-references-and-dynamic-types.md)
+  * [Nullable attributes](../schema-concept/nullable-attributes.md)
+* [Coercion](../coercion/README.md)
+  * [Primitive type coercion](../coercion/primitive-type-coercion.md)
+  * [Arrays coercion](../coercion/arrays-and-array-subclasses.md)
+  * [Generic coercion](../coercion/generic-coercion.md)
+  * [Recursive coercion](../coercion/recursive-coercion.md)
+  * [Observations](../coercion/observations.md)
+* [Validation](../validation/README.md)
+  * [String validations](../validation/string-validations.md)
+  * [Number validations](../validation/number-validations.md)
+  * [Boolean validations](../validation/boolean-validations.md)
+  * [Date validations](../validation/date-validations.md)
+  * [Array validations](../validation/array-validations.md)
+  * [Attribute reference](../validation/attribute-reference.md)
+  * [Nested validations](../validation/nested-validations.md)
+  * [Validate raw data](../validation/validate-raw-data.md)
+* [Strict mode](../strict-mode.md)
+* [Cloning an instance](../cloning.md)
+* [Serialization](../serialization.md)
+* [Contributing](../contributing.md)
+* [License](../license.md)
+* [GitHub](https://github.com/talyssonoc/structure)
+
diff --git a/docs/coercion/README.md b/docs/coercion/README.md
diff --git a/docs/validation/number-validations.md b/docs/validation/number-validations.md
diff --git a/docs/validation/string-validations.md b/docs/validation/string-validations.md
diff --git a/license.md b/license.md
@@ -1,21 +1,12 @@
+# License
+
 MIT License
 
-Copyright (c) 2017 Structure
+Copyright \(c\) 2017 Structure
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files \(the "Software"\), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
 
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
diff --git a/docs/schema-concept/README.md → schema-concept/README.md b/docs/schema-concept/README.md → schema-concept/README.md
@@ -1,11 +1,13 @@
-# Schema Concept
+# Schema concept
+
 The schema is an object responsible to map the attributes Structure should handle, it is the parameter of the `attributes` function.
 
-```js
+```javascript
 attributes({
   name: String,
   age: Number
 })(class User { });
 ```
 
-There are two ways to declare an attribute of the schema, the __shorthand type descriptor__ and the __complete type descriptor__.
+There are two ways to declare an attribute of the schema, the **shorthand type descriptor** and the **complete type descriptor**.
+