Repository files navigation

Node server for dynamic, fake JSON.

Dyson allows you to define JSON endpoints based on a simplepath +template object:

#my-stubs/users.jsmodule.exports={path:'/users/:userId',template:{id:params=>Number(params.userId),name:()=>faker.name.findName(),email:()=>faker.internet.email(),status:(params,query)=>query.status,lorem:true}};

$ dyson ./my-stubs$ curl http://localhost:3000/users/1?status=active

{"id":1,"name":"Josie Greenfelder","email":"Raoul_Aufderhar@yahoo.com","status":"active","lorem":true}

When developing client-side applications, often either static JSON files, or an actual server, backend, datastore, or API, is used. Sometimes static files are too static, and sometimes an actual server is not available, not accessible, or too tedious to set up.

This is where dyson comes in. Get a full fake server for your application up and running in minutes.

• Installation notes
• Demo

• Dynamic responses, based on
  • Request path
  • GET/POST parameters
  • Query parameters
  • Cookies
• HTTP Methods: GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS
• Dynamic HTTP status codes
• CORS
• Proxy (e.g. fallback to actual services)
• Delayed responses
• Required parameter validation
• Includes random data generators
• Includes dummy image generator
  • Use any external or local image service (included)
  • Supports base64 encoded image strings

Configure endpoints using simple objects:

module.exports={path:'/user/:id',method:'GET',template:{id:(params,query,body)=>params.id,name:g.name,address:{zip:g.zipUS,city:g.city}}};

Thepath string is the usual argument provided toExpress, as inapp.get(path, callback);.

Thetemplate object may contain properties of the following types:

• AFunction will be invoked with arguments(params, query, body, cookies, headers).
• Primitives of typeString,Boolean,Number,Array are returned as-is
• AnObject will be recursively iterated.
• APromise will be replaced with its resolved value.

Note: thetemplate itself can also be afunction returning the actual data. The template function itself is also invoked with arguments(params, query, body, cookies, headers).

The default values for the configuration objects:

module.exports={cache:false,delay:false,proxy:false,size:()=>_.random(2,10),collection:false,callback:response.generate,render:response.render};

• cache: true means that multiple requests to the same path will result in the same response
• delay: n will delay the response withn milliseconds (or between[n, m] milliseconds)
• proxy: false means that requests to this file can be skipped and sent to the configured proxy
• size: fn is the number of objects in the collection
• collection: true will return a collection
• callback: fn
  • the provided default function is doing the hard work (can be overridden)
  • used as middleware in Express
  • must setres.body and callnext() to render response
• render: fn
  • the default function to render the response (basicallyres.send(200, res.body);)
  • used as middleware in Express

You can useanything to generate data. Here are some suggestions:

• Faker.js
• Chance.js
• dyson-generators

Just install the generator(s) in your project to use them in your templates:

npm install dyson-generators --save-dev

Containers can help if you need to send along some meta data, or wrap the response data in a specific way. Just use thecontainer object, and return thedata where you want it. Functions in thecontainer object are invoked with arguments(params, query, data):

module.exports={path:'/users',template:user.template,container:{meta:(params,query,data)=>({userCount:data.length}),data:{all:[],the:{way:{here:(params,query,data)=>data}}}}};

And an example response:

{"meta": {"userCount":2  },"data": {"all": [],"the": {"way": {"here": [          {"id":412,"name":"John"          },          {"id":218,"name":"Olivia"          }        ]      }    }  }}

Basic support for "combined" requests is available, by means of a comma separated path fragment.

For example, a request to/user/5,13 will result in an array of the responses from/user/5 and/user/13.

The, delimiter can beconfigured (or disabled).

By default, all responses are sent with a status code200 (and theContent-Type: application/json header).

This can be overridden with your ownstatus middleware, e.g.:

module.exports={path:'/feature/:foo?',status:(req,res,next)=>{if(req.params.foo==='999'){res.status(404);}next();}};

Would result in a404 when requesting/feature/999.

In addition to configured endpoints, dyson registers adummy image service at/image. E.g. requesting/image/300x200 serves an image with given dimensions.

This service is a proxy toDynamic Dummy Image Generator byRussell Heimlich.

Override therender method of the Express middleware in the endpoint definition. In the example below, depending on the existence of thecallback parameter, either raw JSON response is returned or it is wrapped with the provided callback:

module.exports={render:(req,res)=>{constcallback=req.query.callback;if(callback){res.append('Content-Type','application/javascript');res.send(`${callback}(${JSON.stringify(res.body)});`);}else{res.send(res.body);}}};

Ex: return file name
formDataName = 'file'

module.exports={render:(req,res)=>{if(callback){res.send({fileName:req.files.file.name});}else{res.send(res.body);}}};

If you want to run dyson over SSL you have to provide a (authority-signed or self-signed) certificate into theoptions.https the same way it's required for NodeJS built-inhttps module. Example:

constfs=require('fs');constapp=dyson.createServer({configDir:`${__dirname}/dummy`,port:3001,https:{key:fs.readFileSync(`${__dirname}'/certs/sample.key`),crt:fs.readFileSync(`${__dirname}/certs/sample.crt`)}});

Note: if running SSL on port 443, it will requiresudo privileges.

If you want dyson to support GraphQL endpoints, you can build your own logic with therender override, or usedyson-graphql. Example:

npm install dyson-graphql --save-dev

constdysonGraphQl=require('dyson-graphql');constschema=`  type User {    id: Int!    name: String!  }  type Query {    currentUser: User!  }  type Mutation {    createUser(name: String!): User!    updateUser(id: Int!, name: String!): User!  }`;module.exports={path:'/graphql',method:'POST',render:dysonGraphQl(schema).query('currentUser',{id:987,name:'Jane Smart'}).mutation('createUser',({ name})=>({id:456, name})).mutation('updateUser',({ id, name})=>{if(id<1000){return{ id, name};}thrownewError("Can't update user");}).build()};

If you need some custom middleware before or after the endpoints are registered, dyson can be initialized programmatically.Then you can use the Express server instance (appBefore orappAfter in the example below) to install middleware before or after the dyson services are registered. An example:

constdyson=require('dyson');constpath=require('path');constoptions={configDir:path.join(__dirname,'services'),port:8765};constconfigs=dyson.getConfigurations(options);constappBefore=dyson.createServer(options);constappAfter=dyson.registerServices(appBefore,options,configs);console.log(`Dyson listening at port${options.port}`);

Dyson configuration can also be installed into any Express server:

constexpress=require('express');constdyson=require('./lib/dyson');constpath=require('path');constoptions={configDir:path.join(__dirname,'services')};constmyApp=express();constconfigs=dyson.getConfigurations(options);dyson.registerServices(myApp,options,configs);myApp.listen(8765);

The recommended way to install dyson is to install it locally and put it in yourpackage.json:

npm install dyson --save-dev

Then you can use it fromscripts inpackage.json using e.g.npm run mocks:

{"name":"my-package","version":"1.0.0","scripts": {"mocks":"dyson mocks/"  }}

You can also install dyson globally to start it from anywhere:

npm install -g dyson

You can put your configuration files anywhere. The HTTP method is based on:

• Themethod property in the configuration itself.
• The folder, or an ancestor folder, containing the configuration is an HTTP method. For examplemocks/post/sub/endpoint.js will be an endpoint listening toPOST requests.
• Defaults toGET.

dyson [dir]

This starts the services configured in[dir] atlocalhost:3000.

You can also provide an alternative port number by just adding it as a second argument (e.g.dyson path/ 8181).

• For a demo project, seewebpro/dyson-demo.
• This demo was also installed withHeroku todyson-demo.herokuapp.com.

Optionally, you can put adyson.json file next to the configuration folders (inside[dir]). It enables to configure some behavior of dyson:

{"multiRequest":",","proxy":true,"proxyHost":"http://dyson.jit.su","proxyPort":8080,"proxyDelay": [200,800]}

• SettingmultiRequest tofalse disables thecombined requests feature.
• SettingbodyParserJsonLimit orbodyParserUrlencodedLimit to1mb increases the limit to 1mb from the bodyParser's default of 100kb.
• By default, theproxy is set tofalse

If you want to automatically restart dyson when you change your configuration objects, you can addnodemon as adevDependency. Say your configuration files are in the./api folder, you can put this in yourpackage.json:

"scripts": {  "mocks": "dyson mocks/",  "watch": "nodemon --watch mocks --exec dyson mocks"}

git clone git@github.com:webpro/dyson.gitcd dysonnpm installnpmtest

• How do I create a Fake Server with Dyson? | Apiumhub
• Stubbing Network Calls (Api) Using Dyson for Emberjs Apps
• Our Ember.js Toolchain
• Dyson, construye un servidor de pruebas que devuelva fake JSON para simular una API
• Mockear la capa back con Dyson
• Serve JSONP in Dyson
• Videos_Dyson - HTTP Service mocking_How to implement HTTP Mock Services into Webpack - Dyson

MIT