![](\"https://sdl-stickershop.line.naver.jp/products/0/0/1/1087538/LINEStorePC/main.png?__=20150924\")
\n[](https://travis-ci.org/devlucky/Kakapo.js)\n[](https://codecov.io/github/devlucky/Kakapo.js?branch=master)\n[](https://npmjs.com/package/kakapo)\n[](https://david-dm.org/devlucky/Kakapo.js)\n[](https://tldrlegal.com/license/mit-license)\n![](\"http://benschwarz.github.io/bower-badges/badge@2x.png\")
\n\n> Next generation mocking framework in Javascript - [docs](http://devlucky.github.io/kakapo-js) \n\n## Contents\n- [Getting started](#getting-started)\n - [Installation](#installation)\n- [Examples](#examples)\n - [Basic](#basic)\n - [Using the DB](#using-the-db)\n - [Unchaining the Router](#unchaining-the-router)\n - [Fetch & XMLHttpRequest support](#fetch--xmlhttprequest-support)\n - [Database candyness](#database-candyness)\n - [Passthrough](#passthrough)\n- [Demo Apps](#demo-apps)\n - [TODO App](#todo-app)\n - [Github explorer](#github-explorer)\n- [Components](#components)\n - [Server](#server)\n - [Router](#router)\n - [Database](#database)\n - [Response](#response)\n - [Serializers](#serializers)\n - [Interceptors](#interceptors)\n - [Scenarios](#scenarios)\n - [Fake data](#fake-data)\n- [Browser support](#browser-support)\n- [Roadmap](#roadmap)\n\nKakapo its a full featured http mocking library, he allows you to entirely replicate your backend logic in simple and declaritive way directly in the browser. This way you can easily prototype and develop the whole Application without backend and just deactivate Kakapo when you go production. In order to achieve that Kakapo gives you a set of utilities like Routing, Database, Response, Request and so on...\n\n## Installation\n\n`$ npm i kakapo -D`\n\n`$ bower i kakapo -D`\n\n\n# Examples\n\nBefore going deep into the Kakapo docs, we want to show you some examples of how to use Kakapo in your apps, in order to demonstrate how easy to integrate it is\n\n## Basic\n\nUse the kakapo router to declare two custom routes and returning custom data.\n\n```javascript\nimport {Router, Server} from 'Kakapo';\n \nconst router = new Router();\n\nrouter.get('/users', _ => {\n return [{\n id: 1,\n name: 'Hector'\n }, {\n id: 2,\n name: 'Zarco'\n }]\n});\n\nrouter.get('/users/:user_id', request => {\n const userId = request.params.user_id;\n return [{\n id: userId,\n name: 'Hector'\n }];\n});\n\nconst server = new Server();\n\nserver.use(router);\n\nfetch('/users', users => {\n console.log(users[0].id === 1);\n console.log(users[1].id === 2);\n});\n\nfetch('/users/3', user => {\n console.log(user.id === 3);\n console.log(user.name === 'Hector');\n});\n``` \n\n### Using the DB\n \nCombine the usage of the Router and the Database to have a more consistent way of managing the mock data. In the following example we are defining the user factory and later using some access methods provided by the db.\n\n```javascript\nimport {Database, Router, Server} from 'Kakapo';\n\nconst db = new Database();\n\ndb.register('user', () => ({\n firstName: 'Hector',\n lastName: 'Zarco'\n}));\ndb.create('user', 10);\n\nconst router = new Router();\n\nrouter.get('/users', (request, db) => {\n return db.all('user');\n});\n\nrouter.get('/users/:user_id', (request, db) => {\n const userId = request.params.user_id;\n return db.findOne('user', userId);\n});\n\nconst server = new Server();\n\nserver.use(db);\nserver.use(router);\n\nfetch('/users', users => {\n console.log(users[0].id === 1);\n console.log(users[1].id === 2);\n console.log(users[2].id === 3);\n});\n\nfetch('/users/7', user => {\n console.log(user.id === 7);\n console.log(user.name === 'Hector');\n});\n``` \n\nAs you can see, the database automatically handles the **id** generation, so you don't have to worry about assigning incremental id's of any kind.\n\n### Unchaining the Router\n\nNext you will see how to use other features of the router and figure out the things you can build with it. In this example we show you how easy is to create a fake pagination handling, which is based in the actual requested page. \n\n```javascript\nimport {Router, Server} from 'Kakapo';\n \nconst router = new Router();\n\nrouter.get('/users', (request) => {\n const currentPage = request.query.page;\n let count = request.query.count;\n let users = []\n\n while (--count) {\n users.push({name: 'hector', age: 24});\n }\n\n return {\n data: users,\n metadata: {\n previous_page: currentPage - 1,\n current_page: currentPage,\n next_page: currentPage + 1\n }\n }\n});\n\nrouter.post('/users/:user_id/friends/:friend_id', (request) => {\n const token = request.headers.get('X-auth-token');\n const userId = request.params.friend_id;\n const friendId = request.params.friend_id;\n let message;\n\n if (token === 'foo-bar') {\n message = `successs friend: ${friendId} created for userId: ${userId}`;\n } else {\n message = 'Unauthorized';\n }\n\n return {\n message\n }\n});\nconst server = new Server();\n\nserver.use(router);\n\nfetch('/users?page=1&count=3', response => {\n console.log(response.data.length === 3);\n console.log(response.metadata.previous_page === 1);\n console.log(response.metadata.next_page === 2);\n});\n\nconst headers = new Headers();\nheaders.append('X-auth-token', 'foo-bar');\nconst request = new Request('/users/10/friends/55');\n\nfetch(request, {method: 'POST', headers}).then(response => {\n console.log(response.message);\n});\n```\n\n### Fetch & XMLHttpRequest support\n\nKakapo have Fetch and XMLHttpRequest support by default, but you can always change that if you want, see the [interceptors docs](#interceptors).\n\n```javascript\nimport {Router, Server} from 'Kakapo';\n \nconst router = new Router();\n\nrouter.get('/users/', () => {\n return 'meh';\n});\n\nconst server = new Server();\n\nserver.use(router);\n\nfetch('/users', users => {\n console.log(users[0].id === 1);\n console.log(users[1].id === 2);\n});\n\nconst xhr = new XMLHttpRequest();\n\nxhr.onreadystatechange = () => {\n if (xhr.readyState !== 4) return;\n\n const response = JSON.parse(xhr.responseText);\n console.log(response[0].id === 1);\n console.log(response[1].id === 2);\n};\nxhr.open('GET', '/users', true);\nxhr.send();\n\n```\n\n### Database candyness\n\nCheck how easy to build a consistent CRUD Api with the kakapo db.\n\n```javascript\nimport {Database, Router, Server, Response as KakapoResponse} from 'Kakapo';\n \nconst sever = new Server();\nconst router = new Router();\nconst databse = new Database();\n\ndatabase.register('user', faker => {\n return {\n firstName: faker.name.firstName,\n lastName: faker.name.lastName,\n age: 24\n };\n});\n\ndatabase.create('user', 5);\n\nrouter.get('/users', (request, db) => {\n return db.all('user');\n});\nrouter.post('/users', (request, db) => {\n const user = JSON.parse(request.body);\n\n db.push('user', user);\n\n return user;\n});\nrouter.put('/users/:user_id', (request, db) => {\n const newLastName = JSON.parse(request.body).lastName;\n const user = db.findOne('user', request.params.user_id);\n\n user.lastName = newLastName;\n user.save();\n\n return user;\n});\nrouter.delete('/users/:user_id', (request, db) => {\n const user = db.findOne('user', request.params.user_id);\n const code = user ? 200 : 400;\n const body = {code};\n \n user && user.delete();\n\n return new KakapoResponse(code, body);\n});\n\nconst server = new Server();\n\nserver.use(database);\nserver.use(router);\n\nconst getUsers = () => {\n return fetch('/users').then(r => r.json());\n}\n\nconst createUser = (user) => {\n return $.post('/users', user);\n};\n\nconst updateLast = () => {\n return $.ajax({\n url: '/users/6',\n method: 'PUT',\n data: {lastName: 'Zarco'}\n });\n};\n\nconst deleteFirst = () => {\n return $.ajax({\n url: '/users/1',\n method: 'DELETE'\n });\n};\n\ngetUsers() // users[0].id === 1, users.length === 5\n .then(createUser.bind(null, {firstName: 'Hector'})) // response.id === 6, response.firstName === 'Hector'\n .then(deleteFirst) // response.code === 200\n .then(getUsers) // users[0].id == 2, users[4].id == 6, users.length == 5\n .then(updateLast) // user.id == 6, user.lastName == 'Zarco'\n .then(getUsers) // users.length == 5\n\n```\n\n### Passthrough\n\nYou don't need to do anything in order to keep your existing request working as they were before. Kakapo will just passthrough all the request that doesn't match any of the defined routes and fire the associated callback.\n\n```javascript\nimport {Router, Server} from 'Kakapo';\n \nconst server = new Server();\nconst router = new Router();\n\nrouter.get('/users', (request) => {\n return 'Kakapo';\n});\n\nconst server = new Server();\n\nserver.use(router);\n\nfetch('/users', users => {\n users == 'Kakapo';\n});\n\nfetch('https://api.github.com/users', users => {\n //Real Github users data\n});\n\n```\n\n\n# Demo Apps\n\n## TODO App\n\nEvery project needs a TODO App, so here is the Kakapo one. Straightforward vanilla js app, uses the **fetch api** for the networking part.\n\n[Check the demo](https://kakapo-todo-app.firebaseapp.com/) or [look at the code](https://github.com/devlucky/Kakapo.js/tree/master/examples/todo-app)\n\n\n\n## Github explorer\n\nBasic github users search example, based 100% on the (Github Api)[https://developer.github.com/v3]. It shows you how easy is to replicate the logic of a backend with Kakapo and iterate faster when building the UI. This example also uses jQuery just to demostrate the compatibility with Kakapo.\n\n[Check the demo](https://kakapo-github-explorer.firebaseapp.com) or [look at the code](https://github.com/devlucky/Kakapo.js/tree/master/examples/github-explorer)\n\n\n\n# Components\n\n## Server\n The Kakapo Server is the main component of the framework, he is charge of activate things and link components like the router or the database.\n\n **Linking components**\n \n So, in order to make your router to start intercepting requests, you must connect him with your server using the *use* method. Also is a good practice to connect your *current database* with your server, that way you will receive her as a parameter in your request handlers. This practice is very useful when you have multiple databases and routers, since you can easily swicth them without rewriting anything, see [Scenarios](#scenarios) section\n\n```javascript\nconst myDB = new Database();\nconst router = new Router();\nconst server = new Server();\n\nrouter.get('/posts', (request, db) => {\n console.log(db === myDB);\n});\n\nserver.use(myDB);\nserver.use(router);\n\nfetch('/posts');\n\n```\n\n## Router\nThe Router class gives you the functionality to \nit has a very intuitive interface, so if you ever had to build any kind of rest api in any server-side language, you are already familiar with the Kakapo router. that allows you to define complex routes (like in a real server)\n\n**Method handling**\n\nThose are the supported http methods\n\n```javascript\nimport {Router} from 'kakapo';\n\nconst router = new Router();\n\nrouter.get('/users/:user_id')\nrouter.post('/users/:user_id')\nrouter.put('/users/:user_id')\nrouter.delete('/users/:user_id')\n```\n\n**Request object**\n\nYou can access to all the request properties through the request object passed in the request handler\n\n```javascript\nrouter.get('/posts/:post_id/comments/:comment_id', request => {\n console.log(request.params.post_id);\n console.log(request.params.comment_id);\n console.log(request.query.page);\n console.log(request.query.count);\n console.log(request.body);\n console.log(request.headers);\n});\n\n$.ajax({\n url: '/posts/1/comments/5?page=1&count=10',\n data: {text: 'Foo comment'},\n headers: {'X-Access-token': '12345'}\n})\n```\n\n**Options**\n\nOther useful router options are the **host** and the **requestDelay**, you just need to pass them at the initialization moment\n\n```javascript\nimport {Router} from 'kakapo';\n\nconst router = new Router({\n host: 'https://api.github.com',\n requestDelay: 2000\n});\n```\n \n## Database\n\nDatabase along with the Router is also one of the most important components, if you learn how to use it properly you can reuse tons of code and become really productive, that's why Kakapo promotes the use of the Database but you can still don't use it and return whatever you want from the request handlers.\n\n**Factories**\n\nThey come with [Faker](https://github.com/Marak/faker.js) a cool library to generate fake data\nJust a brief example of what you can achieve with the db:\n\n```javascript\nimport {Server, Router, Database} from 'kakapo';\n\nconst router = new Router();\nconst database = new Database();\nconst server = new Server();\n\ndb.register('user', faker => {\n const name = faker.internet.userName();\n\n return {\n name,\n avatar_url: faker.internet.avatar,\n url: `https://api.github.com/users/${name}`,\n type: \"User\",\n company: faker.company.companyName, \n blog: faker.internet.url, \n location: faker.address.city,\n email: faker.internet.email,\n bio: faker.hacker.phrase,\n created_at: faker.date.past, \n updated_at: faker.date.recent\n }\n});\ndb.create('user', 10);\n\nrouter.get('/users', (request, db) => {\n return db.all('user');\n});\n\nrouter.get('/users/:user_id', (request, db) => {\n return db.findOne('user', request.params.user_id);\n});\n\nrouter.post('/users', (request, db) => {\n return db.push('user', request.params.body);\n});\n\nserver.use(database);\nserver.use(router);\n```\n\n\n**Relationships**\n\nSometimes while mocking, you miss some sort of consistency in your responses. Let's say you have a blog and when you ask for comments of a post you return a **post_id** that doesn't match any of the post ids...\n\nYou can solve that using relationships, they are designed to help you create this consistent state across all your requests. The methods are **belongsTo** and **hasMany**\n\n```javascript\nimport {Server, Database, Router} from 'kakapo';\n\nconst server = new Server();\nconst db = new Database();\nconst router = new Router();\n\nconst blogFactory = () => ({\n posts: db.hasMany('post'),\n authors: db.hasMany('user', 2) //Notice how we expecify the author id, to force to return that record always\n});\nconst postFactory = () => ({\n title: 'Js for the lulz',\n body: 'html body',\n blog: db.belongsTo('blog')\n});\nconst userFactory = () => ({\n name: 'devlucky',\n followers: 1000,\n});\n\ndb.register('blog', blogFactory);\ndb.register('post', postFactory);\ndb.register('user', userFactory);\n\ndb.create('post', 10);\ndb.create('user', 5);\ndb.create('blog', 1);\n```\n\n## Response\n\nThe Response object is a helper class mostly used inside the request handlers to provide rich responses to your real handlers\n \n```javascript\nimport { Server, Response, Router } from 'kakapo';\n\nconst server = new Server();\nconst router = new Router();\n\nrouter.get('/user/:user_id', request => {\n const code = request.params.user_id < 10 ? 200 : 400;\n const headers = {'X-request-date': new Date().getTime()};\n\n return new Response(code, {status: code}, headers);\n});\n\nserver.use(router);\n```\n\n## Serializers\n\nThis is another component very familiar in backend laguages, Serializers offers you a way to abstract the **render** part of your entities. \nIn this example we cover a common case in which you have different versions of your Api and you want to represent that in Kakapo in the same way\n\n```javascript\nconst ApiV2Serializer = (record, type) => {\n const id = record.id;\n const metadata = {created_at: new Date()};\n const attributes = Object.assign({}, record, metadata);\n\n return {\n id,\n type,\n attributes\n };\n};\n\nconst db = new Database();\n\ndb.register('user', () => ({\n firstName: 'Hector',\n lastName: 'Zarco',\n age: 24,\n}), ApiV2Serializer);\n\ndb.register('comment', () => ({\n text: 'msg'\n}), ApiV2Serializer);\n\n```\n\n## Interceptors\n\nThis component is the one that actually handles the original request, is a private one but you can configure it in the Router. Just pass **strategies** in the constructor, by default both **fetch** and **XMLHttpRequest** are used.\n\n```javascript\nimport {Server, Router} from 'kakapo';\n\nconst server = new Server();\nconst fetchRouter = new Router({\n strategies: ['fetch']\n});\nconst xhrRouter = new Router({\n strategies: ['XMLHttpRequest']\n});\n\nserver.use(fetchRouter);\n\n//LATER\n\nserver.use(xhrRouter);\n \n```\n\n## Scenarios\n\nThe **scenario** concept is nothing else than the ability of having different presets of Kakapo, like router, database, etc... and later, allow the user to decide when he wants to use one of other. \n\nLet's say you want to check how the spinners looks in your app, in that case you probably will put a higher value as a **requestDelay**, to make sure that the requests are intercepted late and you can check the UI... other good use case might be one in which you want to test the performance of a view when you have thousands of elements, in order to achieve that you will just need to pass a high number to the **create** method of the **Database**: \n\n```javascript\nimport {Server, Router, Database} from 'kakapo';\n\nconst userFactory = (faker) => {\n return {\n name: faker.name.findName,\n age: 24,\n city: 'Valencia'\n }\n};\nconst usersHandler = (request, db) => db.all('user');\nconst wifiServer = new Server({requestDelay: 150});\nconst threeGServer = new Server({requestDelay: 1000});\nconst router = new Router();\nconst chillDB = new Database();\nconst stressfulDB = new Database();\n\nchillDB.register('user', userFactory);\nchillDB.create('user', 5);\n\nstressfulDB.register('user', userFactory);\nstressfulDB.create('user', 1000);\n\nwifiServer.get('/users', usersHandler);\nthreeGServer.get('/users', usersHandler);\n\n//Pick the server with more latency if you want to check how the spinner looks like\n//server.use(wifiServer);\nserver.use(threeGServer);\n\n//Here you just have to switch between different databases in order to test the UI with tons of users\n//server.use(chillDB);\nserver.use(stressfulDB);\n\n``` \n\n## Fake data\n\nAs mention above, you can use [Faker](https://github.com/Marak/faker.js) for generate fake data, take a look at the full demo [here](http://marak.com/faker.js/). Also note that you can define nested properties and use Faker on them:\n\n```javascript\ndb.register('user', faker => {\n return {\n user: {\n name: faker.name.findName,\n nick: 'nick'\n },\n company: faker.company.companyName, \n location: 'Valencia, Spain'\n }\n});\n```\n\n# ROADMAP\n\n**Full support for JSONApiSerializer**\n\n**Node.js compatibility**\n\n**Node.js interceptors**\n\n# Authors \n\n[@rpunkfu](https://github.com/rpunkfu) - [@zzarcon](https://github.com/zzarcon)\n"
},
{
"path": "__tests__/data/users.ts",
"content": "import * as Faker from 'faker';\n\nexport type UserId = string;\n\nexport type User = {\n id: UserId,\n firstName: string,\n lastName: string,\n age: number\n};\n\nexport const userFactory = ({\n id = Faker.random.uuid(),\n firstName = Faker.name.firstName(),\n lastName = Faker.name.lastName(),\n age = Faker.random.number()\n}: Partial