Git Product home page Git Product logo

koala's Introduction

Koalaα

Gitter chat NPM version Build status Test coverage Dependency Status License Downloads

A suite of Koa utilities allowing for quicker bootstrapping, as well as a consequential guide on how to write apps using the Koa philosophy. Think of it as a KrakenJS for Koa.

Status

Beware! Koala is alpha software!

Philosophy

Koa is a bare minimal framework, focusing on unopinionated core HTTP utilities. However, this is not sufficient for most apps as a lot is not supported out of the box. Including a bunch of dependencies in every new app you create quickly becomes annoying.

The goal of Koala is to include the most used and unopinionated parts of apps into a single framework. Many things such as body parsing, sessions, and CSRF are included. Many other things, such as routing, is too opinionated and not included.

Unlike other frameworks, Koala will not dictate how to write business logic. Thanks to generators and, eventually, ES7 Async/Await, writing business logic in Koa is much easier than other frameworks, and Koala's goal is to only make it easier. Don't expect a single option to automatically do magic for your app.

Feel free to create suggestions!

Features and Documentation

The Koala framework adds to Koa:

  • Body Parsing
    • Seamless Expect: 100-continue support
    • Per-request body limits
    • Supports JSON, urlencoded, and multipart bodies
    • Supports arbitrary strings, buffers, and files as bodies
    • Optional nested parameter support
  • File Serving
  • Sessions
    • Cookie-based sessions
    • CSRF protection
  • Response Caching - cache and serve responses using an arbitrary store
  • JSONP - safe jsonp support
  • Security Headers
  • Error Page - better default error page
  • Tracing
  • etc
    • Basic auth
    • Object stream support
    • Optional nested query string supported
  • FAQ

koala(1) will be a generator, similar to what express(1) is.

Usage

Simply replace require('koa') with require('koala'). Koala returns a koa app, except it includes more features.

const koala = require('koala');
const app = new Koala();

app.use(async () => {
  this.response.status = 204;
});

app.listen((err) => {
  if (err) {
    console.error(err);
    throw err;
  }
  console.log('Koala app listening on port %s', this.address().port);
});

Roadmap

Some additional features may include:

  • Timeout assertion
  • Server-Side Event Streams
  • Rate limiting

Let me know if you have any other suggestions.

koala's People

Contributors

cncolder avatar dependabot[bot] avatar doug-wade avatar fengmk2 avatar gitter-badger avatar greenkeeperio-bot avatar jonathanong avatar nfantone avatar nickmccurdy avatar pdehaan avatar richenlin avatar snyk-bot avatar yangeok avatar zedgu avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

koala's Issues

Update deprecated dependencies

Installing the dependencies spews deprecation errors

» npm i
npm WARN deprecated [email protected]: Please use istanbul@>=0.4.0 instead
npm WARN deprecated [email protected]: to-iso-string has been deprecated, use @segment/to-iso-string instead.
npm WARN deprecated [email protected]: Jade has been renamed to pug, please install the latest version of pug instead of jade
npm WARN deprecated [email protected]: This package is no longer maintained
npm WARN deprecated [email protected]: Please update to minimatch 3.0.2 or higher to avoid a RegExp DoS issue
npm WARN deprecated [email protected]: Please update to minimatch 3.0.2 or higher to avoid a RegExp DoS issue
npm WARN deprecated [email protected]: 'native-or-bluebird' is deprecated. Please use 'any-promise' instead.
npm notice created a lockfile as package-lock.json. You should commit this file.
added 199 packages in 7.146s

let's get off the out-of-date versions.

install error : normalize/strip-comments is no longer exist?

npm install
npm ERR! git clone [email protected]:normalize/strip-comments Cloning into bare repository '/Users/zed/.npm/_git-remotes/git-github-com-normalize-strip-comments-0f082cc4'...
npm ERR! git clone [email protected]:normalize/strip-comments Warning: Permanently added the RSA host key for IP address '192.30.252.130' to the list of known hosts.
npm ERR! git clone [email protected]:normalize/strip-comments ERROR: Repository not found.
npm ERR! git clone [email protected]:normalize/strip-comments fatal: Could not read from remote repository.
npm ERR! git clone [email protected]:normalize/strip-comments 
npm ERR! git clone [email protected]:normalize/strip-comments Please make sure you have the correct access rights
npm ERR! git clone [email protected]:normalize/strip-comments and the repository exists.
npm ERR! notarget No compatible version found: strip-comments@'normalize/strip-comments#cdf2e824c14965d3942e9874ae1f3abfbf0ec555'
npm ERR! notarget Valid install targets:
npm ERR! notarget ["0.1.0","0.1.1","0.1.2","0.1.3","0.1.4","0.1.6","0.2.0"]
npm ERR! notarget 
npm ERR! notarget This is most likely not a problem with npm itself.
npm ERR! notarget In most cases you or one of your dependencies are requesting
npm ERR! notarget a package version that doesn't exist.

npm ERR! System Darwin 13.3.0
npm ERR! command "node" "/usr/local/bin/npm" "install"
npm ERR! cwd /Users/zed/Works/oven
npm ERR! node -v v0.11.13
npm ERR! npm -v 1.4.23
npm ERR! code ETARGET
npm ERR! 
npm ERR! Additional logging details can be found in:
npm ERR!     /Users/zed/Works/oven/npm-debug.log
npm ERR! not ok code 0

Use Jest instead of Mocha

  • Koa upstream has made the switch (while I personally prefer Jest, this is the main reason).
  • Jest has more of a convention over configuration / batteries included approach vs. Mocha's more minimal and modular approach. However, the built in Jest APIs are simple and include common things like matchers and mocks. While we already have some of this set up, it could help us reduce maintenance on Mocha setup in the future.
  • Built in coverage, personally I find it more reliable and convenient than istanbul (though we could alternatively switch to nyc).
  • Seriously cool features like snapshots that are hard to find in other frameworks.
  • Built in Babel support so you can watch tests while transpiling without having to set up another tool.
  • Jest lets you put test files in the same directories as source files, making imports easier to maintain and test code easier to find an verify.

Remove bluebird

In this comment @nickmccurdy suggested we remove Bluebird in favor of native promises. While Bluebird has some nifty features that native promises lack, we should make the migration anyway, as native promises have a smaller footprint (don't need to be npm installed), and have a more standard api.

Tests fail on Node 6

Node's net library has a breaking change in Node 6, which performs validation on the port in the listen method.

~/Repos/koala → npm test

> [email protected] test /Users/nick/Repos/koala
> NODE_ENV=test mocha --reporter spec --timeout 30s --bail test/app/index.js

internal/net.js:17
    throw new RangeError('"port" argument must be >= 0 and < 65536');
    ^

RangeError: "port" argument must be >= 0 and < 65536
    at assertPort (internal/net.js:17:11)
    at Server.listen (net.js:1384:5)
    at Application.listen (/Users/nick/Repos/koala/lib/app.js:19:12)
    at Suite.<anonymous> (/Users/nick/Repos/koala/test/app/conditional-get.js:11:22)
    at context.describe.context.context (/Users/nick/Repos/koala/node_modules/mocha/lib/interfaces/bdd.js:47:10)
    at Suite.<anonymous> (/Users/nick/Repos/koala/test/app/conditional-get.js:3:3)
    at context.describe.context.context (/Users/nick/Repos/koala/node_modules/mocha/lib/interfaces/bdd.js:47:10)
    at Object.<anonymous> (/Users/nick/Repos/koala/test/app/conditional-get.js:2:1)
    at Module._compile (module.js:541:32)
    at Object.Module._extensions..js (module.js:550:10)
    at Module.load (module.js:458:32)
    at tryModuleLoad (module.js:417:12)
    at Function.Module._load (module.js:409:3)
npm ERR! Test failed.  See above for more details.

Add documentation on how to limit binary uploads

Missing documentation on how to limit binary uploads like how the other upload modes are documented (multipart, urlencoded, json, text, buffer).

It seems that the default limit is currently set to 1mb.

How to use route ?

I know that you think route is too opinionated to put route by default in koala. But how should I add it if I would like to use it correctly in koala ?

I don't understand how to run an app with koala, the idea seems good but I don't understand how it works.

I understand all the tests scripts in the package.json, but there is no start script.

Can you help me ? Or give some advice ?

Migrate away from supertest

Now that we're using Jest, we can use Promise returns, async/await, and the .resolves and .rejects matchers instead of using the expectations coupled with supertest (which I have a feeling don't fully support Jest's logging the way that the built in matchers do).

Node HTTP clients using Promises

  • util.promisify(http.request) (Node 8 or the util.promisify shim package)
  • node-fetch (implementation of fetch for Node)
  • axios
  • r2
  • request-promise

example app?

i can start to gather the gist of starting to build out an app, but a full on best practice example is always great.

Resolve npm audit issues

found 203 vulnerabilities (174 low, 9 moderate, 19 high, 1 critical) in 21585 scanned packages
  run `npm audit fix` to fix 200 of them.
  3 vulnerabilities require semver-major dependency updates.

Fix snyk errors

Currently, prs appear as broken since snyk has identified 4 errors. We should resolve them.

Enable Gitter integrations

The integrations send notifications to the Gitter room when something happens. All of them except Travis require admin access to this repository.

  • GitHub
  • Coveralls
  • Travis

Set up gitter

Let's set up a place to coordinate development and provide support for koala.

docs: Provide full list of options

I had to go thru all of source codes to discover, what functionality is enabled by default, how to disable things I don't want, and under which keys configure the rest. I would welcome (and any other newcomer), you would kindly:

  • provide info for each used library, whether it is enabled by default, which key disables/enables the feature, and under which key are the options, if any. Its not everywhere.
  • add to home page example all option keys for each library (not all its options, but to have quick view of what is where, plus possibly defaults).

Cheers

Maintaining

Hi,

I am currently building some koa utilities and saw this project is seeking a maintainer. Is this still the case?

/ Linus

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.