1 | [![Build Status](https://travis-ci.org/adleroliveira/dreamjs.svg?branch=master)](https://travis-ci.org/adleroliveira/dreamjs)
|
2 |
|
3 | # [![Dream Logo](http://www.bodamarket.cl/small_dream_logo.png)](https://github.com/adleroliveira/dreamjs)
|
4 |
|
5 | #### A lightweight json data generator.
|
6 |
|
7 | This library can output random data from a Json Schema using standard types like String, Number, Date, Boolean, Array,
|
8 | or with the 60+ built-in custom types like Name, Age, Address, Word, Sentence, paragraph, gender, (RGB) color etc.
|
9 |
|
10 | The built-in Custom Types are mostly provided by the module [Chance][Chance] but the library also allows you to create
|
11 | your own Custom Types.
|
12 |
|
13 | It can be used with multiple Schemas that can be selected before usage and the it is also chainable, meaning that you
|
14 | can chain several configurations before finally output the processed json.
|
15 |
|
16 | ## Installation
|
17 |
|
18 | ```js
|
19 | npm install --save dreamjs
|
20 | ```
|
21 |
|
22 | ## Usage
|
23 |
|
24 | ### Hello World
|
25 |
|
26 | ```js
|
27 | var dream = require('dreamjs');
|
28 |
|
29 | var helloworld = dream.output();
|
30 | ```
|
31 |
|
32 | The variable helloworld now contains:
|
33 | ```js
|
34 | { Dream: 'Hello World' }
|
35 | ```
|
36 |
|
37 | ### Callbacks
|
38 |
|
39 | Currently there is two ways you can get the output from DreamJS. By storing it in a variable or by passing a callback
|
40 | to it to receive the result. In the future it will also be possible to use it with Promises and Streams.
|
41 |
|
42 | Storing in a variable:
|
43 | ```js
|
44 | var helloword = dream.output();
|
45 | ```
|
46 |
|
47 | Passing a callback:
|
48 | ```js
|
49 | dream.output(function (err, result) {
|
50 | console.log(result);
|
51 | });
|
52 | ```
|
53 |
|
54 | ### Generic Schema / Named Schema
|
55 |
|
56 | The simplest way to use DreamJS is by defining a generic schema.
|
57 | If any other generic Schema is created after that it will replace the previous one.
|
58 |
|
59 | ```js
|
60 | var data = dream
|
61 | .schema({
|
62 | name: String
|
63 | })
|
64 | .output();
|
65 | ```
|
66 |
|
67 | The variable data now contains:
|
68 | ```js
|
69 | { name: '' }
|
70 | ```
|
71 |
|
72 | It is also possible to create named Schemas and use them when necessary.
|
73 |
|
74 | ```js
|
75 | dream.schema('User', {
|
76 | name: String,
|
77 | age: Number
|
78 | });
|
79 |
|
80 | dream.schema('Location', {
|
81 | address: String,
|
82 | postcode: Number
|
83 | });
|
84 |
|
85 | var data = dream
|
86 | .useSchema('Location')
|
87 | .output();
|
88 | ```
|
89 |
|
90 | The variable data now contains:
|
91 | ```js
|
92 | { address: '', postcode: 0 }
|
93 | ```
|
94 |
|
95 | ### Generate() and GenerateRnd()
|
96 |
|
97 | The methods `Generate()` and `GenerateRnd()` will generate a given amount of instances of the selected Schema
|
98 | respecting the data types specified on the Schema.
|
99 | The method `Generate()` will bring empty values and the method `GenerateRnd()` will bring values with random data.
|
100 |
|
101 | ```js
|
102 | dream.schema('User', {
|
103 | name: String
|
104 | });
|
105 |
|
106 | var data1 = dream
|
107 | .useSchema('User')
|
108 | .generate(3)
|
109 | .output();
|
110 |
|
111 | var data2 = dream
|
112 | .useSchema('User')
|
113 | .generateRnd(3)
|
114 | .output();
|
115 | ```
|
116 |
|
117 | The variable **data1** and **data2** now contains:
|
118 | ```js
|
119 | // data1
|
120 | [ { name: '' }, { name: '' }, { name: '' } ]
|
121 |
|
122 | // data2
|
123 | [ { name: 'Jlxokrs' }, { name: 'oHiklkss' }, { name: 'mNeiOlsaa' } ]
|
124 | ```
|
125 |
|
126 | ### Custom Types
|
127 |
|
128 | DreamJS comes with the power of the [Chance][Chance] library integrated with it and allow you to use their 60+ random
|
129 | generator as built-in Custom Types.
|
130 | It is also possible to create your own Custom Types or just just pass a function or a RegularExpression statement to
|
131 | use a generic Custom Type.
|
132 |
|
133 | A full list of all the possible built-in Custom Types provided by chance can be found on their website: http://chancejs.com
|
134 |
|
135 | ```js
|
136 |
|
137 | dream.customType('pi', function () {
|
138 | return Math.PI;
|
139 | });
|
140 |
|
141 | dream.customType('hello', /hello+ (world|to you)/);
|
142 |
|
143 | dream
|
144 | .schema({
|
145 | name: 'name',
|
146 | age: 'age',
|
147 | address: 'address',
|
148 | contact: {
|
149 | phone: 'phone',
|
150 | servicePhone: /^(800[1-9]{6})$/
|
151 | },
|
152 | foo: function () {
|
153 | return 'bar';
|
154 | },
|
155 | pi: 'pi',
|
156 | hello: 'hello'
|
157 | })
|
158 | .generateRnd(2)
|
159 | .output(function (err, result) {
|
160 | console.log(result);
|
161 | });
|
162 | ```
|
163 |
|
164 | Result:
|
165 | ```js
|
166 | [
|
167 | {
|
168 | name: 'Dorothy Conner',
|
169 | age: 32,
|
170 | address: '702 Kimes Extension',
|
171 | contact: {
|
172 | phone: '(985) 255-2142',
|
173 | servicePhone: '800493159'
|
174 | },
|
175 | foo: 'bar',
|
176 | pi: 3.141592653589793,
|
177 | hello: 'hellooooooooooo world'
|
178 | },
|
179 | {
|
180 | name: 'Nathaniel Payne',
|
181 | age: 50,
|
182 | address: '1811 Bani Manor',
|
183 | contact: {
|
184 | phone: '(212) 389-6644',
|
185 | servicePhone: '800157977'
|
186 | },
|
187 | foo: 'bar',
|
188 | pi: 3.141592653589793,
|
189 | hello: 'hellooooooooooooooooooooooo to you'
|
190 | }
|
191 | ]
|
192 | ```
|
193 |
|
194 | ## Dream Helper
|
195 |
|
196 | Whenever you build your own Custom Type, DreamJS provides to your Custom Type callback a helper object that contains
|
197 | some useful tools like:
|
198 |
|
199 | ### Chance Instance
|
200 |
|
201 | An instance of the library chance, that allows you to make full use of their methods with custom configuration.
|
202 |
|
203 | ```js
|
204 | dream.customType('FiveWordsSentence', function (helper) {
|
205 | return helper.chance.sentence({words: 5});
|
206 | });
|
207 |
|
208 | dream
|
209 | .schema({
|
210 | phrase: 'FiveWordsSentence'
|
211 | })
|
212 | .generateRnd(2)
|
213 | .output(function (err, result) {
|
214 | console.log(result);
|
215 | });
|
216 | ```
|
217 |
|
218 | Result:
|
219 | ```js
|
220 | [
|
221 | { phrase: 'Laf woelimev vu vazpazap upecu.' },
|
222 | { phrase: 'Batunwa ziti laralsuc ve rudeoze.' }
|
223 | ]
|
224 | ```
|
225 |
|
226 | ### Input
|
227 |
|
228 | It is possible to define an input to the DreamJS data flow, that will be available through the helper so you can use
|
229 | this data to interact with your Custom Type.
|
230 |
|
231 | ```js
|
232 | dream.customType('customTypeWithInput', function (helper) {
|
233 | return helper.input.value;
|
234 | });
|
235 |
|
236 | dream
|
237 | .input({value: 'Provided by an input'})
|
238 | .schema({
|
239 | result: 'customTypeWithInput'
|
240 | })
|
241 | .generateRnd()
|
242 | .output(function (err, result) {
|
243 | console.log(result);
|
244 | });
|
245 | ```
|
246 |
|
247 | Result:
|
248 | ```js
|
249 | { result: 'Provided by an input' }
|
250 | ```
|
251 |
|
252 | ### oneOf()
|
253 |
|
254 | A method that allows you to pick a single random value from a provided array. This way you can explicitly specify the
|
255 | scope of what is being returned from your Custom Type.
|
256 |
|
257 | ```js
|
258 | dream.customType('iceCreamTruckDay', function (helper) {
|
259 | var businessDays = ['Monday', 'Wednesday', 'Friday'];
|
260 | return helper.oneOf(businessDays);
|
261 | });
|
262 |
|
263 | dream
|
264 | .schema({
|
265 | iceCreamDay: 'iceCreamTruckDay'
|
266 | })
|
267 | .generateRnd(2)
|
268 | .output(function (err, result) {
|
269 | console.log(result);
|
270 | });
|
271 | ```
|
272 |
|
273 | Result:
|
274 | ```js
|
275 | [
|
276 | { iceCreamDay: 'Wednesday' },
|
277 | { iceCreamDay: 'Wednesday' }
|
278 | ]
|
279 | ```
|
280 |
|
281 | ## TODO
|
282 |
|
283 | The next step is to update DreamJS to allow the use with promises and streams.
|
284 |
|
285 | [Chance]: http://chancejs.com/
|