# paquet

> A practical REST API library

Latest version **1.4.0** (published 2016-09-02) · MIT license · 76 weekly downloads

## Install

```sh
npm install paquet
pnpm add paquet
yarn add paquet
bun add paquet
```

Provides the command `paquet`.

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.4.0 |
| Published | 2016-09-02 |
| First published | 2016-08-30 |
| Weekly downloads | 76 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 30 |
| Known vulnerabilities | 0 (+3 in 2 direct dependencies) |
| Install scripts | no |
| Author | Merciba |
| Maintainers | alfonsogoberjr, merciba |
| Keywords | REST, API, merciba, framework, paquet, node, es6, es5, koa, express, babel, javascript, cli |

## Links

- npm: https://www.npmjs.com/package/paquet
- npm.io page: https://npm.io/package/paquet

## Dependencies (30)

- [koa](https://npm.io/package/koa.md) ^1.2.1
- [swig](https://npm.io/package/swig.md) ^1.4.2
- [colors](https://npm.io/package/colors.md) ^1.1.2
- [dotenv](https://npm.io/package/dotenv.md) ^2.0.0
- [koa-qs](https://npm.io/package/koa-qs.md) ^2.0.0
- [morgan](https://npm.io/package/morgan.md) ^1.7.0
- [express](https://npm.io/package/express.md) ^4.14.0
- [fs-sync](https://npm.io/package/fs-sync.md) ^0.2.5
- [bluebird](https://npm.io/package/bluebird.md) ^3.4.3
- [co-views](https://npm.io/package/co-views.md) ^2.1.0
- [koa-body](https://npm.io/package/koa-body.md) ^1.5.0
- [koa-send](https://npm.io/package/koa-send.md) ^3.2.0
- [babel-cli](https://npm.io/package/babel-cli.md) ^6.14.0
- [koa-mount](https://npm.io/package/koa-mount.md) ^1.3.0
- [koa-serve](https://npm.io/package/koa-serve.md) ^0.1.7
- [koa-logger](https://npm.io/package/koa-logger.md) ^1.3.0
- [koa-router](https://npm.io/package/koa-router.md) ^5.4.0
- [koa-static](https://npm.io/package/koa-static.md) ^2.0.0
- [body-parser](https://npm.io/package/body-parser.md) ^1.15.2
- [koa-session](https://npm.io/package/koa-session.md) ^3.3.1
- [koa-sendfile](https://npm.io/package/koa-sendfile.md) ^2.0.0
- [cookie-parser](https://npm.io/package/cookie-parser.md) ^1.4.3
- [koa-useragent](https://npm.io/package/koa-useragent.md) ^0.1.4
- [babel-polyfill](https://npm.io/package/babel-polyfill.md) ^6.13.0
- [cookie-session](https://npm.io/package/cookie-session.md) ^2.0.0-alpha.1
- [express-session](https://npm.io/package/express-session.md) ^1.14.1
- [koa-static-folder](https://npm.io/package/koa-static-folder.md) ^0.1.6
- [koa-static-server](https://npm.io/package/koa-static-server.md) ^0.1.8
- [koa-strong-params](https://npm.io/package/koa-strong-params.md) 0.0.3
- [babel-preset-es2015](https://npm.io/package/babel-preset-es2015.md) ^6.14.0

## Alternatives

- [@salesforce/cli](https://npm.io/package/@salesforce/cli.md) — 389.7K weekly downloads
- [@mintlify/cli](https://npm.io/package/@mintlify/cli.md) — 208.9K weekly downloads
- [@grafana/e2e-selectors](https://npm.io/package/@grafana/e2e-selectors.md) — 128.7K weekly downloads
- [mintlify](https://npm.io/package/mintlify.md) — 112.0K weekly downloads
- [@intlayer/cli](https://npm.io/package/@intlayer/cli.md) — 22.8K weekly downloads

## Recent versions

- 1.4.0 (latest) — 2016-09-02
- 1.3.1 — 2016-09-02
- 1.3.0 — 2016-09-02
- 1.2.1 — 2016-09-01
- 1.2.0 — 2016-08-31
- 1.1.0 — 2016-08-31
- 1.0.0 — 2016-08-31
- 0.0.2 — 2016-08-30
- 0.0.1 — 2016-08-30

## README

# Paquet

A practical REST API framework

[![NPM](https://nodei.co/npm/paquet.png)](https://nodei.co/npm/paquet/)  

[![Build Status](https://travis-ci.org/merciba/paquet.svg?branch=master)](https://travis-ci.org/merciba/paquet)  [![License](https://img.shields.io/npm/l/paquet.svg)](https://github.com/merciba/paquet/blob/master/LICENSE) [![Gratipay](http://img.shields.io/gratipay/merciba.svg)](https://gratipay.com/merciba/)

Paquet is a REST API framework with a specific mission: To get a REST API set up as quickly and effortlessly as possible, with a full suite of production-ready features. Paquet was written so that you could use one line and an object structure to spin up a REST API - written entirely in ES6.

Under the hood, Paquet is simply leveraging [Express](https://expressjs.com) and [Koa](http://koajs.com/) to give you two basic options - ES6 with [generator functions](https://davidwalsh.name/es6-generators) and ES5.

## Table of Contents

[Install](#install)   
[Examples](#examples)   
[API](#api)  
[Notes](#notes)  
[Contributors](#contributors)  

### Okay, so who is this for? Why wouldn't I just use Express or Koa?

Paquet is for:

 * front-end developers who want to get started quickly with a basic API for their single-page React or Angular app to consume
 * anyone who wants to use ES5 and ES6 syntax without switching frameworks
 * human beings just starting out with Node.js who want a more opinionated framework
 * experienced developers who want object-based mapping between routes and controllers

Paquet is not claiming to be something new, it simply makes what's out there more accessible and intuitive to get started with, by unifying their APIs. Instead of worrying about whether you've installed and loaded all the correct middleware, Paquet ships with some basic features out of the box, such as:

 * Body parsing
 * Cookie parsing
 * Sessions support
 * URL Querystring parsing
 * Serving static files

Plus, you can still load the Express/Koa middleware you know and love!

When you create an API using `var paquet = new Paquet(mode).start(options)`, the underlyng Koa/Express app will always be accessible as `paquet.instance.app`.

## Install

### CLI

```
npm install paquet -g
```

### Module

```
npm install paquet --save
```

## Examples

### Using the CLI

```
paquet --public ./public --middleware ./middleware.js
```

This would start an API on the default port 3000 and point the static file server at ./public (relative to your project's root) and load middleware from the file `middleware.js` in your project's root.

To specify `routes`, use a `paquet.json` in your project's root. Here's an [example paquet.json](https://gist.github.com/merciba/f72f7dd0f910e7eb46a21eaf8fed9f32).

### ES6

``` JavaScript
import Paquet from 'paquet'

const paquet = new Paquet('es6')

paquet.start({
	port: 9090,																// optional, defaults to 3000
	name: 'helloworld',														// optional
	public: './test/public',												// optional, required if no routes set
    session: {                                    // optional
		name: 'paquet',
		keys: ['key1', 'key2']
	},
	middleware: {                             // optional
		'/*': function * (next) {
		  if (this.path === '/favicon.ico') return;

		  var n = this.session.views || 0;
		  this.session.views = ++n;
			yield next
		},
		'/docs': `./test/docs`
	},
	routes: {																// optional, required if no public folder set
		get: {
			'/file/:id': function * () {
				this.response.serveFile(`./test/files/${this.params.id}`)
			},
			'/post/:id': [
				function * (next) {
					yield next
				},
				function * () {
					this.response.success({ title: "My post", author: "random guy" })
				}
			],
			'/error': function * () {
				this.response.error(404, "uh oh! an error!")
			}
		},
		post: {
			'/cookie/:id': function * () {
				this.cookies.set(this.params.id, 'value')
				this.response.success({ id: this.params.id })
			}
		}
	}
})
```

That's it - all your declaraion upon instantiation. Of course, you're still able to do this:

``` JavaScript
paquet.route({
	get: {
		'/new-route': function * () {
			this.response.success("A new route for my new app")
		}
	}
})
```

after the fact.

### ES5

``` JavaScript
var Paquet = require('paquet')

var paquet = new Paquet()

paquet.start({
	port: 9090,																
	name: 'helloworld',														
	public: './test/public',												
    session: {
		name: 'paquet',
		keys: ['key1', 'key2']
	},
	middleware: {
		'/*': function () {
		  if (this.path === '/favicon.ico') return;

		  var n = this.session.views || 0;
		  this.session.views = ++n;
		},
		'/docs': './test/docs'
	},
	routes: {																// syntax is identical. except for the absence of generators
		get: {
			'/file/:id': function () {
				this.response.serveFile('./test/files/' + this.params.id)
			},
			'/post/:id': [
				function (req, res, next) {
					return next()												// You can also return a promise :)
				},															
				function () {
					this.response.success({ title: "My post", author: "random guy" })
				}
			],
			'/error': function() {
				this.response.error(404, "uh oh! an error!")
			}
		},
		post: {
			'/cookie/:id': function () {
				this.cookies.set(this.params.id, 'value')
				this.response.success({ id: this.params.id })
			}
		}
	}
})
```

And, you're still able to do this:

``` JavaScript
paquet.route({
	get: {
		'/new-route': function () {
			this.response.success("A new route for my new app")
		}
	}
})
```

after the fact, as well.

## API

### Constructor

#### `new Paquet(mode)`

Creates a new instance of class `Paquet`.  

`mode` Defaults to `es5`. When `es6`, Paquet will only accept [generator functions](https://davidwalsh.name/es6-generators) as middleware and routes.

### Instance Methods

#### `.start(options)`

Starts a Paquet API with the following available options:

 * `name: String`, required
 * `port: Number`, optional. Defaults to 3000
 * `public: String`, optional. Sets a folder as a static file server
 * `middleware: Object`, optional. Inserts middleware before the routes

`options.middleware` object has the following structure:

 ```JavaScript
 {
 	'/:path': (String|Array|Function),
 	...
 }
 ```

 When a String is passed, if it is a valid path, this path will also be set as a static file server, accessible at `/:path`.  

 When an Array of functions is passed, these will be injected as cascading middleware into the stack.  

 When a single Function is passed, the function will be injected into the stack.  

 * `routes: Object`, required. Sets the routes for your app

`options.routes` object has the following structure:

 ```JavaScript
 {
 	'(get|post|put|patch|delete)': {
 		'/:path': (Array|Function),
 		...
 	},
 	...
 }
 ```

#### `.route(routes)`

Helper method - behaves identically to `options.routes`, allowing you to add new routes later on in your code.

## Notes

This project is brand new, so there will inevitably be some bugs. Please file an issue with this repo and I'll get to it as soon as I can.

Coming soon:

 * Plugins
 * ES7 async/await support via Koa 2

## Contributors

- [Alfonso Gober](https://www.linkedin.com/in/alfonsogober)

---
_Source: https://npm.io/package/paquet · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
