jaguar 1.3.11

  • README.md
  • CHANGELOG.md
  • Example
  • Installing
  • Versions
  • 88

Pub Build Status Gitter

Jaguar

Jaguar is a production ready HTTP server framework built for speed, simplicity and extensiblity

Getting started

Familiar way to write routes

Jaguar class provides methods get, put, post, delete and options to quickly add route handlers for specific HTTP methods at desired path to the server.

main() async {
  final server = new Jaguar();  // Serves the API at localhost:8080 by default
  // Add a route handler for 'GET' method at path '/hello'
  server.get('/hello', (Context ctx) => 'Hello world!');
  await server.serve();
}

Powerful route matching

Easily define and access Path parameters

Path segments prefixed with : can match any value and are also captured as path variables. Path variables can be accessed using pathParams member of Context object.

main(List<String> args) async {
  final quotes = <String>[
    'But man is not made for defeat. A man can be destroyed but not defeated.',
    'When you reach the end of your rope, tie a knot in it and hang on.',
    'Learning never exhausts the mind.',
  ];

  final server = new Jaguar();
  server.get('/api/quote/:index', (ctx) { // The magic!
    final int index = ctx.pathParams.getInt('index', 1);  // The magic!
    return quotes[index + 1];
  });
  await server.serve();
}
  • A path can have multiple path variables.
  • A path variable can appear at any position in the path.
  • A path variable can be matched against a Regular expression.
  • getInt, getDouble, getNum and getBool methods can be used to easily typecast path variables.
  • Using * as the final path segment captures/matches all following segments.

Easily access Query parameters

Query parameters can be accessed using queryParams member of Context object.

main(List<String> args) async {
  final quotes = <String>[
    'But man is not made for defeat. A man can be destroyed but not defeated.',
    'When you reach the end of your rope, tie a knot in it and hang on.',
    'Learning never exhausts the mind.',
  ];

  final server = new Jaguar();
  server.get('/api/quote', (ctx) {
    final int index = ctx.queryParams.getInt('index', 1); // The magic!
    return quotes[index + 1];
  });
  await server.serve();
}

getInt, getDouble, getNum and getBool methods can be used to easily typecast query parameters into desired type.

One liner to access Forms

A single line is all it takes to obtain a form as a Map<String, String> using method bodyAsUrlEncodedForm on Request object.

main(List<String> arguments) async {
  final server = new Jaguar(port: 8005);

  server.postJson('/api/add', (ctx) async {
      final Map<String, String> map = await ctx.req.bodyAsUrlEncodedForm(); // The magic!
      contacts.add(Contact.create(map));
      return contacts.map((ct) => ct.toMap).toList();
    });


  await server.serve();
}

One liner to serve static files

The method staticFiles adds static files to Jaguar server. The first argument determines the request Uri that much be matched and the second argument determines the directory from which the target files are fetched.

main() async {
  final server = new Jaguar();
  server.staticFiles('/static/*', 'static'); // The magic!
  await server.serve();
}

JSON serialization with little effort

Decoding JSON requests can't be simpler than using one of the built-in bodyAsJson, bodyAsJsonMap or bodyAsJsonList methods on Request object.

Future<Null> main(List<String> args) async {
  final server = new Jaguar();
  server.postJson('/api/book', (Context ctx) async {
    // Decode request body as JSON Map
    final Map<String, dynamic> json = await ctx.req.bodyAsJsonMap();
    Book book = new Book.fromMap(json);
    // Encode Map to JSON
    return book.toMap();
  });

  await server.serve();
}

Out-of-the-box Sessions support

main() async {
  final server = new Jaguar();
  server.get('/api/add/:item', (ctx) async {
    final Session session = await ctx.req.session;
    final String newItem = ctx.pathParams.item;

    final List<String> items = (session['items'] ?? '').split(',');

    // Add item to shopping cart stored on session
    if (!items.contains(newItem)) {
      items.add(newItem);
      session['items'] = items.join(',');
    }

    return Response.redirect('/');
  });
  server.get('/api/remove/:item', (ctx) async {
    final Session session = await ctx.req.session;
    final String newItem = ctx.pathParams.item;

    final List<String> items = (session['items'] ?? '').split(',');

    // Remove item from shopping cart stored on session
    if (items.contains(newItem)) {
      items.remove(newItem);
      session['items'] = items.join(',');
    }

    return Response.redirect('/');
  });
  await server.serve();
}

Advantages of Jaguar

  1. Batteries included
    1. Database
      1. Fluent query builder
      2. ORM
      3. Migration support
      4. Various databases support
        1. Mongo
        2. PostgreSQL (Query)
        3. MySQL (Query)
        4. OracleDB
        5. MS SQL
    2. Authentication and Authorization
    3. OAuth
    4. Session management
  2. Build your routes the way you prefer
    1. Controller based
      1. Reflect
      2. Generate
    2. Mux based
  3. Extensible interceptor infrastructure
  4. Extensive respository of examples
    1. Annotation based
    2. Reflection based
    3. Mux based
    4. MongoDB
    5. PostgreSQL
    6. MySQL
    7. Upload files using Jaguar

Changelog

1.3.11

  • Fixed args package dependency issue

1.3.10

  • Work on websockets

1.3.9

  • Better JSON decoding and encoding support
  • Mutable Jaguar fields

1.3.8

  • More stuff for map

1.3.7

  • Fixed RouteBuilder functions

1.3.6

  • Fixed to map method in Muxable

1.3.5

  • RouteBuilder functions
  • Route maper for Muxable

1.3.2

  • Uses Dart 2's void as type to FutureOr in Interceptor return type

1.3.1

  • Faster streamlined request handling

1.2.10

  • More streamlining of route handlers

1.2.9

  • Stream lined request handling
  • Removed global interceptors
  • Removed debug streams

1.2.8

  • Added ResponseProcessor
  • Route now has responseProcessor to allow processing response outside handlers
  • Interceptor.chain uses responseProcessor
  • Added GetJson, PutJson, PostJson, DeleteJson, GetHtml route annotations
  • JSON route annotations and mux methods now use responseProcessor

1.2.7

  • staticFiles now respects index.html

1.2.6

  • Wrap and WrapOne take function or Symbol as interceptor creator

1.2.2-dev

  • Loosened type of WrapOne

1.2.1-dev

  • Wrap and WrapOne take function as interceptor creator
  • parse and write methods of SessionManager takes Context instead of Request
  • Removed session related methods and fields from Request

0.7.1

  • Stripped out all mirror dependent elements to jaguar_reflect
  • Added RouteChainSimple to improve performance
  • Renamed queryParams to query

0.6.27

  • Widened dependency on meta package

0.6.27

  • Widened dependency on args package

0.6.26

  • Simplified request handling code

0.6.25

  • Context gets session accessors session and parsedSession

0.6.24

  • Fixed RouteChain building issue

0.6.23

  • Added staticFiles method to Jaguar to serve static files!
  • Added staticFile method to Jaguar to serve a single static file!

Breaking Changed

  • Renamed ReflectedRoute to RouteChain
  • Renamed JaguarReflected to ReflectedApi
  • Renamed reflectJaguar to reflectApi

0.6.22

  • Added html, json, getJson, putJson, postJson, deleteJson methods to Muxable and RouteBuilder

0.6.21

  • Added socketHandler to make WebSocket handling easier

0.6.20

  • Preserve order of RequestHandlers

0.6.19

  • Bug fix for Session

0.6.18

  • Sessions are now only written when necessary
  • Added HMAC based signing to session data

0.6.14

  • Session in Request
  • SessionManager in Jaguar to parse and write session data

0.6.13

  • bodyAsText's encoding parameter is optional

0.6.12

  • Upgraded intl dependency

0.6.11

  • Bootstrapping root APIs using bootstrap method
  • Supports package:dice based DI during bootstrapping

0.6.10

  • Jaguar shall log only unknown exceptions

0.6.9

  • Return types of route handlers are now FutureOr

0.6.8

  • Mux methods now take response members
  • Definition of RouteHandlerFunc

0.6.7

  • wrap method on Jaguar

0.6.6

  • XML rendering support
  • New error rendering mechanism
  • Debug stream

0.6.5

  • Merged jaguar_reflect and jaguar_mux into jaguar core

0.6.1

  • Global interceptors

0.6.0

  • Context based RequestHandler

0.5.10

  • Expose Logger to Interceptors and Routes
  • Configurable ErrorWriter

0.5.9

  • Fixed writing headers to response by Response

0.5.4

  • Added redirect to Response class

0.5.0

  • Removed RouteWrapper
  • Removed injection

0.2.7

  • Added properly handling List<int> response type
  • Implemented Route redirection

0.1.14

  • Remove Settings from Configuration

0.1.13

  • Removed isolate creation. Control is given to the programmer.
  • Bug fix for "Page not found!" error

0.0.3

Breaking Changes:

Annotation to build annotation from annotated function has changed.<br>

  • PreProcessorFunction has changed to PreInterceptorFunction
  • PostProcessorFunction has changed to PostInterceptorFunction

jaguar.yaml parameters has also changed

  • pre_processors has changed to pre_interceptors
  • post_processors has changed to post_interceptors

example/example.dart

library example.body.json;

import 'dart:async';
import 'package:jaguar/jaguar.dart';

Future<Null> main(List<String> args) async {
  final server = new Jaguar();
  server.getJson(
      '/moto',
      (Context ctx) => {
            'server': 'Jaguar',
            'motto': 'Speed. Simplicity. Flexiblity. Extensiblity.'
          });

  await server.serve();
}

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  jaguar: "^1.3.11"

2. Install it

You can install packages from the command line:

with pub:


$ pub get

with Flutter:


$ flutter packages get

Alternatively, your editor might support pub get or packages get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:jaguar/jaguar.dart';
        
Version Uploaded Documentation Archive
1.3.11 Mar 12, 2018 Go to the documentation of jaguar 1.3.11 Download jaguar 1.3.11 archive
1.3.10 Mar 11, 2018 Go to the documentation of jaguar 1.3.10 Download jaguar 1.3.10 archive
1.3.9 Mar 11, 2018 Go to the documentation of jaguar 1.3.9 Download jaguar 1.3.9 archive
1.3.8 Feb 28, 2018 Go to the documentation of jaguar 1.3.8 Download jaguar 1.3.8 archive
1.3.7 Feb 28, 2018 Go to the documentation of jaguar 1.3.7 Download jaguar 1.3.7 archive
1.3.6 Feb 28, 2018 Go to the documentation of jaguar 1.3.6 Download jaguar 1.3.6 archive
1.3.5 Feb 28, 2018 Go to the documentation of jaguar 1.3.5 Download jaguar 1.3.5 archive
1.3.4 Feb 2, 2018 Go to the documentation of jaguar 1.3.4 Download jaguar 1.3.4 archive
1.3.3 Feb 2, 2018 Go to the documentation of jaguar 1.3.3 Download jaguar 1.3.3 archive
1.3.2 Feb 2, 2018 Go to the documentation of jaguar 1.3.2 Download jaguar 1.3.2 archive

All 98 versions...

Analysis

We analyzed this package on Apr 23, 2018, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.0.0-dev.49.0
  • pana: 0.10.6

Scores

Popularity:
Describes how popular the package is relative to other packages. [more]
78 / 100
Health:
Code health derived from static analysis. [more]
99 / 100
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
100 / 100
Overall score:
Weighted score of the above. [more]
88
Learn more about scoring.

Platforms

Detected platforms: Flutter, other

Primary library: package:jaguar/jaguar.dart with components: io.

Suggestions

  • Fix analysis and formatting issues.

    Analysis or formatting checks reported 29 hints.

    Strong-mode analysis of lib/src/http/request/form_field.dart gave the following hint:

    line: 15 col: 11
    Always override hashCode if overriding ==.

    Strong-mode analysis of lib/src/http/request/request.dart gave the following hint:

    line: 111 col: 50
    'UTF8' is deprecated and shouldn't be used.

    Similar analysis of the following files failed:

    • lib/src/http/request/request_impl.dart (hint)
    • lib/src/http/response/response.dart (hint)
    • lib/src/http/session/session.dart (hint)
    • lib/src/http/session/session_on_cookie.dart (hint)
    • lib/src/utils/string/import.dart (hint)

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=1.8.0 <3.0.0
args >=0.13.7 <2.0.0 1.4.2
collection >=1.14.5 <2.0.0 1.14.9
crypto ^2.0.2 2.0.2+1
http_server >=0.9.6 <0.10.0 0.9.7
logging >=0.11.3 <0.12.0 0.11.3+1
meta >=1.0.2 <1.2.0 1.1.2
mime >=0.9.3 <0.10.0 0.9.6
path >=0.9.0 <2.0.0 1.5.1
stack_trace >=1.7.0 <2.0.0 1.9.2
yaml ^2.1.12 2.1.13
Transitive dependencies
charcode 1.1.1
convert 2.0.1
source_span 1.4.0
string_scanner 1.0.2
typed_data 1.1.5
Dev dependencies
build_runner ^0.7.0
cookies
dice ^1.7.0
http
jaguar_generator ^1.3.1
jaguar_reflect ^1.3.2
jaguar_resty ^1.1.1
mongo_dart
test ^0.12.15+10