|
| 1 | +# <a href="https://structure.js.org/v/structure-2/"><img src="https://raw.githubusercontent.com/talyssonoc/structure/master/structure.jpg" width="300"></a> |
| 2 | + |
| 3 | +## A simple schema/attributes library built on top of modern JavaScript |
| 4 | + |
| 5 | +## [](https://www.npmjs.com/package/structure) [](https://travis-ci.org/talyssonoc/structure) [](https://coveralls.io/github/talyssonoc/structure?branch=master) [](https://codeclimate.com/github/talyssonoc/structure) [](https://js.org/) |
| 6 | + |
| 7 | +Structure provides a simple interface which allows you to add attributes to your ES6 classes based on a schema, with validations and type coercion. |
| 8 | + |
| 9 | +## Use cases |
| 10 | + |
| 11 | +You can use Structure for a lot of different cases, including: |
| 12 | + |
| 13 | +- Domain entities and value objects |
| 14 | +- Model business rules |
| 15 | +- Validation and coercion of request data |
| 16 | +- Map pure objects and JSON to your application classes |
| 17 | +- Add attributes to classes that you can't change the class hierarchy |
| 18 | + |
| 19 | +Structure was inspired by Ruby's [Virtus](https://github.com/solnic/virtus). |
| 20 | + |
| 21 | +What Structure is **not**: |
| 22 | + |
| 23 | +- It's not a database abstraction |
| 24 | +- It's not a MVC framework (but it can be used to domain entities) |
| 25 | +- It's not an attempt to simulate classic inheritance in JavaScript |
| 26 | + |
| 27 | +## Getting started |
| 28 | + |
| 29 | +`npm install --save structure` |
| 30 | + |
| 31 | +## Usage |
| 32 | + |
| 33 | +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. |
| 34 | + |
| 35 | +```js |
| 36 | +const { attributes } = require('structure'); |
| 37 | + |
| 38 | +const User = attributes({ |
| 39 | + name: String, |
| 40 | + age: { |
| 41 | + type: Number, |
| 42 | + default: 18, |
| 43 | + }, |
| 44 | + birthday: Date, |
| 45 | +})( |
| 46 | + class User { |
| 47 | + greet() { |
| 48 | + return `Hello ${this.name}`; |
| 49 | + } |
| 50 | + } |
| 51 | +); |
| 52 | + |
| 53 | +/* The attributes "wraps" the Class, still providing access to its methods: */ |
| 54 | + |
| 55 | +const user = new User({ |
| 56 | + name: 'John Foo', |
| 57 | +}); |
| 58 | + |
| 59 | +user.name; // 'John Foo' |
| 60 | +user.greet(); // 'Hello John Foo' |
| 61 | +``` |
| 62 | + |
| 63 | +## Support and compatibility |
| 64 | + |
| 65 | +Structure is built on top of modern JavaScript, using new features like [Proxy](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Proxy), [Reflect](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Reflect) and [Symbol](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Symbol). That being so, there are some things regarding compatibility you should consider when using Structure. |
| 66 | + |
| 67 | +### Node |
| 68 | + |
| 69 | +Node has only implemented all the used features at version 10, so for using Structure for a backend application you'll need Node 10 or later. |
| 70 | + |
| 71 | +### Browser |
| 72 | + |
| 73 | +We have a [UMD version](https://github.com/talyssonoc/structure/blob/master/dist/structure.js) for usage in browsers. Right now the tests are ran both in Node (using the original code) and in Electron (using the UMD version) and the whole test suite passes for both cases. Since we use modern JavaScript features inside the lib (like [Proxy](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy)), older browsers may not support it. Polyfilling them may be an option but it's not oficially supported. |
| 74 | + |
| 75 | +## BattleCry generators |
| 76 | + |
| 77 | +There are configurable [BattleCry](https://github.com/pedsmoreira/battlecry) generators ready to be downloaded and help scaffolding schema: |
| 78 | + |
| 79 | +```sh |
| 80 | +npm install -g battlecry |
| 81 | +cry download generator talyssonoc/structure |
| 82 | +cry g schema user name age:int:required cars:string[] favoriteBook:book friends:user[]:default :updateAge |
| 83 | +``` |
| 84 | + |
| 85 | +Run `cry --help` to check more info about the generators available; |
| 86 | + |
| 87 | +## [Contributing](contributing.md) |
| 88 | + |
| 89 | +## [LICENSE](license.md) |
0 commit comments