Merge branch 'dev'

.travis.yml

@@ -6,7 +6,7 @@ branches:
   only:
   - master
 install:
-- npm install -g gulp mocha webpack phantomjs
+- npm install -g gulp mocha webpack
 - npm install
 script:
-- npm run build
+- npm test

README.en_US.md

@@ -0,0 +1,190 @@
+Logline
+=======
+
+[中文](https://github.com/latel/logline/blob/master/README.md) | English
+
+[![Build Status][travis-image]][travis-url]
+
+Logline is a light-weighted, useful log agent for front-end on the client-side.
+
+Why position problems is difficult for the front-end?
+---------------------------------------------------
+Most front-enders should have similar experience, when codes are deployed for production, running on countless clients. In most caes, we can only guess the problems, especially some occasional visible problems, because we have no idea what's our user's acctual operations, thus it's hard for us to reproduce the scenes. At this moment, we think, it will be great help if we have a detailed and classified log agent, just like the backend do.
+
+Application scenario
+-------------------
++ Reproduce user operations
+
+    In the production environment, user's operations are un-predicable, even they
+    cannot remember the details themselves, with log, we have the ability to
+    reproduce the operation paths and running state.
+
++ Monitoring core processes
+
+    In the core processes in our products, we can upload the logs positively,
+    as we can focus our user's problems and count the amount quickly.
+
++ Positively get user's logs and analysis user's activities
+
+    Don't believe on the users to coordinate you, we can design a strategy, such as
+    deploy an json file online, configure a list containing the target users we
+    wanted, when our product is opened on their client, they will download this
+    json file after a certain delay(to prevent affections on the core process's
+    performance), if the user id is in the list, we will upload the logs positively.
+
++ Count errors and help to analysis
+
+    We can make use of Logline to count js errors. With the error stack, we can speed
+    up the analysis.
+
+Features
+-------
+
++ No extra dependencies
++ client-side(reach when acctually needed, save bandwith and traffic)
++ multiple filter dimension(namespace, degree and keyword)
++ multiple stores(IndexDB, Websql, localStorage)
++ cleanable(in case take too much user space)
+
+Quick to get started
+-------------------
+
+### 1. Installation
+
+#### with Bower
+
+``` shell
+bower install logline
+```
+
+#### Download archive
+access [https://github.com/latel/logline/releases](https://github.com/latel/logline/releases), selecte the version you wanted.
+
+### 2. Import to your project
+Logline is an UMD ready module, choose to import it as your project needed.
+CMD is evil, which is not supported, wrapper it yourself if you need it indeed.
+
+``` javascript
+// using <script> element
+<script src="./mod/logline.min.js"></script>
+
+// using AMD loader
+var Logline = require('./mod/logline.min');
+```
+### 3. Choose a log protocol
+Logline implements three protocols, all of them are mounted on the `Logline` object for special uses, together with better semantics.
+
++ `websql:` Logline.PROTOCOL.WEBSQL
++ `indexeddb:` Logline.PROTOCOL.INDEXEDDB
++ `localstorage:` Logline.PROTOCOL.LOCALSTORAGE
+
+you can use `using` method to specialfy a protocol.
+
+``` javascript
+Logline.using(Logline.PROTOCOL.WEBSQL);
+```
+
+***If you call Logline related APIs, without specialfy a protocol in advance***, Logline will choose a available protocol automatically, respect the priority according to the configuration parameters during the compile process.
+
+such as, your compile command is `npm run configure -- --with-indexeddb --with-websql --with-localstorage`,
+if protocol indexeddb is available, then indexeddb protocol with be chosen automatically,
+otherwise, if indexeddb protocol is not available and websql protocol is available, then websql protocol will be chosen, and so on.
+
+If none of the compiled protocols are available, an error will be thrown.
+
+#### 4. Record logs
+``` javascript
+var spaLog = new Logline('spa'),
+    sdkLog = new Logline('sdk');
+
+// with description, without extra data
+spaLog.info('init.succeed');
+
+// with description and extra data
+spaLog.error('init.failed', {
+	retcode: 'EINIT',
+	retmsg: 'invalid signature'
+});
+
+// with description, without extra data
+sdkLog.warning('outdated');
+
+// with description and extra data
+sdkLog.critical('system.vanish', {
+    // debug infos here
+});
+```
+
+### 5. Read logs
+``` javascript
+// collect all logs
+Logline.all(function(logs) {
+    // process logs here
+});
+
+// collet logs within .3 days
+Logline.get('.3d', function(logs) {
+    // process logs here
+});
+
+// collect logs from 3 days before, and earlier than 1 days ago
+Logline.get('3d', '1d', function(logs) {
+    // process logs here
+});
+```
+
+### 6. Clean logs
+``` javascript
+Logline.keep(.5); // keep logs within half a day, if `.5` is not provided, will clean up all logs
+Logline.clean(); // clean all logs and delete database
+```
+
+Custom database name
+-------------------
+Because indexeddb, websql and localstorage are all domain shared storage, the default database name `logline` may have already been taken, you can specialfy a custom database name in two ways as follows:
+
+``` javascript
+// special a second parameter when calling `using` API
+Logline.using(Logline.PROTOCOL.WEBSQL, 'newlogline');
+
+// call `database` API
+Logline.database('newlogline');
+```
+
+Custom Compile
+--------------
+Logline implements `localstorage`, `websql` and `indexeddb` protocols, all of them are compiled by default, if you don't need all of them, you can use `npm run configure` and `npm run build` to compile your custom build with partial protocols packed. This helps to reduces the package size.
+
+``` shell
+// pack all protocols with no parameters
+npm run configure
+// pack only wanted protocols, remove corresponding --with-xx
+npm run configure -- --with-localstorage --with-websql
+
+// re-compile
+npm run build
+// find the custom build in dist fold
+ls -l dist/
+```
+
+FAQ
+---
+
+### How to upload logs
+since v1.0.1, log upload ability is removed, as the upload procedures varies upon different projects,
+and we do hope Logline to focus on log recording and maintenance.
+Anyway, you can still use `Logline.all` and `Logline.get` to get the logs,
+and implement your own upload procedure.
+
+### How to analysis
+As the format Logline provited is standard with good readability,
+thus you can read the logs in the terminal or certain text editors.
+
+We still provids [Logline-viewer] to helps you to do so.
+
+
+
+[travis-image]: https://api.travis-ci.org/latel/logline.svg
+[travis-url]: https://travis-ci.org/latel/logline
+[logline-viewer]: https://github.com/latel/logline-viewer
+[logline-uploader]: https://github.com/latel/logline-uploader