doc.html

<!doctype html>
<html>
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes">
<style>
h1,
h2,
h3,
h4,
h5,
h6,
p,
blockquote {
    margin: 0;
    padding: 0;
}
body {
    font-family: "Helvetica Neue", Helvetica, "Hiragino Sans GB", Arial, sans-serif;
    font-size: 13px;
    line-height: 18px;
    color: #737373;
    background-color: white;
    margin: 10px 13px 10px 13px;
}
table {
	margin: 10px 0 15px 0;
	border-collapse: collapse;
}
td,th {	
	border: 1px solid #ddd;
	padding: 3px 10px;
}
th {
	padding: 5px 10px;	
}

a {
    color: #0069d6;
}
a:hover {
    color: #0050a3;
    text-decoration: none;
}
a img {
    border: none;
}
p {
    margin-bottom: 9px;
}
h1,
h2,
h3,
h4,
h5,
h6 {
    color: #404040;
    line-height: 36px;
}
h1 {
    margin-bottom: 18px;
    font-size: 30px;
}
h2 {
    font-size: 24px;
}
h3 {
    font-size: 18px;
}
h4 {
    font-size: 16px;
}
h5 {
    font-size: 14px;
}
h6 {
    font-size: 13px;
}
hr {
    margin: 0 0 19px;
    border: 0;
    border-bottom: 1px solid #ccc;
}
blockquote {
    padding: 13px 13px 21px 15px;
    margin-bottom: 18px;
    font-family:georgia,serif;
    font-style: italic;
}
blockquote:before {
    content:"\201C";
    font-size:40px;
    margin-left:-10px;
    font-family:georgia,serif;
    color:#eee;
}
blockquote p {
    font-size: 14px;
    font-weight: 300;
    line-height: 18px;
    margin-bottom: 0;
    font-style: italic;
}
code, pre {
    font-family: Monaco, Andale Mono, Courier New, monospace;
}
code {
    background-color: #fee9cc;
    color: rgba(0, 0, 0, 0.75);
    padding: 1px 3px;
    font-size: 12px;
    -webkit-border-radius: 3px;
    -moz-border-radius: 3px;
    border-radius: 3px;
}
pre {
    display: block;
    padding: 14px;
    margin: 0 0 18px;
    line-height: 16px;
    font-size: 11px;
    border: 1px solid #d9d9d9;
    white-space: pre-wrap;
    word-wrap: break-word;
}
pre code {
    background-color: #fff;
    color:#737373;
    font-size: 11px;
    padding: 0;
}
@media screen and (min-width: 914px) {
    body {
        width: 854px;
        margin:10px auto;
    }
}
@media print {
	body,code,pre code,h1,h2,h3,h4,h5,h6 {
		color: black;
	}
	table, pre {
		page-break-inside: avoid;
	}
}
</style>

<style type="text/css">
ul.downloads {
  padding-left: 0;
  list-style-type: none;
}

ul.downloads li {
  margin: 10px 0;
}

a.download {
  -webkit-user-select: none;
  background: #fff;
  background-image: -webkit-gradient(linear, left top, left bottom, from(rgba(0,0,32,0.01)), to(rgba(0,0,32,0.08)));
  background-image: -moz-linear-gradient(rgba(0,0,32,0.01), rgba(0,0,32,0.08));
  -webkit-border-radius: 6px;
  -moz-border-radius: 6px;
  border-radius: 6px;
  color: #202028;
  padding: 4px 10px;
  border: 1px solid #a8a8af;
  text-decoration: none !important;
  text-shadow: 0 1px 1px rgba(255,255,255,0.9);
  font-size: 14px;
  line-height: 19px;
  font-family: helvetica, arial, sans-serif;
  display: inline-block;
  cursor: pointer;
  font-weight: bold;
}

a.download:hover {
  color: #202028;
  background-image: -webkit-gradient(linear, left top, left bottom, from(rgba(0,0,32,0.01)), to(rgba(0,0,32,0.16)));
  background-image: -moz-linear-gradient(rgba(0,0,32,0.01), rgba(0,0,32,0.16));
  border-color: #707078;
}

a.download:active {
  background-color: rgba(0,0,32,0.05);
  background-image: -webkit-gradient(linear, left top, left bottom, from(rgba(0,0,32,0.16)), to(rgba(0,0,32,0.01)));
  background-image: -moz-linear-gradient(rgba(0,0,32,0.16), rgba(0,0,32,0.01));
  box-shadow: inset 0 2px 2px rgba(0,0,0,0.1);
}
</style>

<title>jSQL `数据的异想世界`</title>

</head>
<body>
<h2>jSQL <code>数据的异想世界</code></h2>

<hr />

<h3>Why Should I Use jSQL?</h3>

<p>使用jSQL可以让你更加专注于业务需求和逻辑，通过jSQL可以将排序、筛选等数据查询的底层操作同业务逻辑完美分离。从而提高代码的可维护性和开发效率。jSQL不仅可以用于PC端，也可以在移动手持设备的应用中使用。除了JavaScript版本的jSQL，如果你喜欢jSQL的使用方式和API，同时你又是一个Python后端开发人员且不喜欢庞大的ORM，同样有短小精干的Python-jSQL可以让你在Python框架中方便的对MySQL进行操作。jSQL不是一个库，它是一个使得数据的查询操作变得更方便快捷高效的解决思路和思想、方法的抽象。jSQL内置IO和事件中心，天然的支持远程数据源，并且所有数据的操作行为最终都会通过事件中心广播出去，从而使得数据操作和业务逻辑解耦分离。</p>

<ul class="downloads">
    <li>
        <a href="https://raw.github.com/PaulGuo/jSQL/master/build/jsql.js" class="download">jsql.js v0.7.1 (for development)</a>
    </li>
    <li>
        <a href="https://raw.github.com/PaulGuo/jSQL/master/build/jsql-min.js" class="download">jsql-min.js v0.7.1 (for production)</a>
    </li>
</ul>

<h3>API Document</h3>

<p>jSQL是一个用SQL的思想和API实现JavaScript数据操作（查询，过滤）的方法库（同时有基于Tornado DB封装的类似API的后端SQL查询封装），它通过链式调用的方式简化数据查询和操作，同时支持多种形式的数据源。</p>

<ul>
<li><code>Object</code></li>
<li><code>Array</code></li>
<li><code>URI</code></li>
</ul>


<p>Object类型：</p>

<pre><code>{
    key: {column: value},
    key: {column: value}
}
</code></pre>

<p>Object的key对应数据表的唯一索引，cloumn映射为数据表的字段，value对应数据表相应字段的值。</p>

<p>Array类型：</p>

<pre><code>[
    {column: value},
    {column: value}
]
</code></pre>

<p>Array的每个item对应数据表的一个记录，cloumn对应字段名，value对应字段值，同Object类型不同的是，当前类型的索引key是根据指定的条件或者自动生成的。</p>

<p><code>create(dbname, db /*, indexList */)</code></p>

<p><code>create(dbname, db, /*, scope|function */)</code></p>

<p>在内存中创建一个数据库（指定indexList则根据指定字段生成唯一键）</p>

<pre><code>用法示例1:

jsql.create('local', {})

用法示例2:

jsql.create('local', 'http://uri?callback=?', 'data.result')

用法示例3:

jsql.create('local', 'http://uri', function(resp) {
    return resp.data.result;
})
</code></pre>

<p><code>use(dbname)</code></p>

<p>使用指定数据库作为当前操作的数据库，并重置缓冲区(buffer)</p>

<pre><code>local = jsql.use('local').listAll();
remote = jsql.use('remote').listAll();
</code></pre>

<p><code>drop(dbname)</code></p>

<p>丢弃指定数据库，同时从内存中抹除</p>

<pre><code>jsql.drop('local');
</code></pre>

<p><code>dbs()</code></p>

<p>获取当前内存中存在的所有数据库名称</p>

<pre><code>dbs = jsql.dbs(); // ['local', 'remote', 'test']
</code></pre>

<p><code>db()</code></p>

<p>获取当前操作的数据库名称</p>

<pre><code>cur = jsql.db(); // local
</code></pre>

<p><code>select(key)</code></p>

<p>指定获取的数据字段名称</p>

<pre><code>local = jsql.use('local').select('*').listAll();
remote = jsql.use('remote').select('name, age').listAll();
</code></pre>

<p><code>count()</code></p>

<p>获取当前操作缓冲区的数据条数</p>

<pre><code>count = jsql.use('local').count();
</code></pre>

<p><code>total(scope|function)</code></p>

<p>返回当前操作数据库中含有某字段（或者符合传入条件）的数据总条数。</p>

<pre><code>total = db.total('data.name');
total = db.total(function(item) {
    return item.data.age === 24;
});
</code></pre>

<p><code>orderby(field, /* callback, */ order)</code></p>

<p>根据指定字段的值（或者处理后的值）和排序规则对当前缓冲区的数据进行排序。</p>

<pre><code>db = jsql.use('local');
db.select('*').orderby('data.time', buildDate, 'asc');
result = db.listAll();
</code></pre>

<p><code>where(fn|[fn, …])</code></p>

<p>返回当前缓冲区中符合指定条件的数据集合（如果传入为一组fn，则为并集）。</p>

<pre><code>db = jsql.use('local');
db.where([function(item) {
    return item.data.age &lt; 24;
}, function(item) {
    return item.data.sex === 'male';
}]);
result = db.listAll();
</code></pre>

<p><code>iterate(fn)</code></p>

<p>根据指定的方法对当前缓冲区中的数据进行遍历。</p>

<pre><code>db = jsql.use('local');
db.where(function(item) {
    return item.data.age &lt; 24;
}).iterate(function(item) {
    item.data.checked = true;
});
result = db.listAll();
</code></pre>

<p><code>findAll(fn)</code></p>

<p>以Object类型返回当前缓冲区中的数据集合</p>

<p><code>find(key)</code></p>

<p>获取缓冲区中指定key的数据。</p>

<p><code>listAll()</code></p>

<p>以Array类型返回当前缓冲区中的数据集合。</p>

<p><code>update(key, data)</code></p>

<p>根据指定数据对指定key的数据进行更新操作。</p>

<p><code>insert(item, key /*, from index */)</code></p>

<p>（在指定位置）插入一条数据。</p>

<p><code>append(/* database, */ data)</code></p>

<p>向当前操作的数据库中追加数据。</p>

<pre><code>jsql.append('local', {});
</code></pre>

<p><code>remove()</code></p>

<p>从当前操作的数据库中删除缓冲区中的数据。</p>

<pre><code>db = jsql.use('local');
db.where(function(item) {
    return item.data.age &lt; 24;
}).remove();
</code></pre>

<p><code>limit(start, end)</code></p>

<p>返回当前缓冲区指定区域的数据（也可以使用<code>start:end</code>）。</p>

<pre><code>db = jsql.use('local');
db.limit('1:10');
result = db.listAll();
</code></pre>

<p><code>keys()</code></p>

<p>返回当前缓冲区中所有数据的键名集合。</p>

<p><code>first(fn)</code></p>

<p>返回满足条件的第一条数据。</p>

<p><code>last(fn)</code></p>

<p>返回满足条件的最后一条数据。</p>

<pre><code>db = jsql.use('local');
db.last(function(item) {
    return item.data.age &lt; 24;
});
result = db.find();
</code></pre>

<p><code>distinct()</code></p>

<p>以Array类型返回当前缓冲区中去重后的数组集合。</p>

<pre><code>db = jsql.use('local');
result = db.select('airLineCode').distinct(); // ['CA', 'MU', 'CZ']
</code></pre>

<p><code>rebase()</code></p>

<p>重置缓冲区数据。</p>

<p><code>noConflict()</code></p>

<p>避免命名空间冲突。</p>

<pre><code>_jSQL = jsql.noConflict();
</code></pre>

<h4>IO</h4>

<p><code>io</code></p>

<p>数据接口异步请求。</p>

<ul>
<li><code>io.ajax(uri, data, success, error)</code></li>
<li><p><code>io.jsonp(uri, data, success, error)</code></p>

<ul>
<li>uri: 请求接口的地址</li>
<li>data: 请求接口的附加数据</li>
<li>success: 调用成功的回调函数</li>
<li>error: 调用出错的回调函数</li>
</ul>
</li>
</ul>


<h4>Event</h4>

<p>jSQL内置的事件中心不仅用于广播/订阅数据库自身的操作，同时它是一个完全独立的事件中心，跟数据无关的操作也可以完全通过它进行广播/订阅，且天然支持广播域，多个域各自拥有不同的事件池，互不干扰。</p>

<p><code>on(database, event, callback)</code></p>

<p>监听数据库事件。</p>

<ul>
<li>database: 被监听的数据库名，取<code>global</code>则为全局事件，也可自定义自己的广播域</li>
<li>event: 被监听的事件名

<ul>
<li>create</li>
<li>update</li>
<li>drop</li>
<li>io:start</li>
<li>io:complete</li>
<li>io:success</li>
<li>io:error</li>
</ul>
</li>
<li>callback: 事件发生后触发的回调函数</li>
</ul>


<p><code>off(database[, event])</code></p>

<p>取消对数据库事件的监听。</p>

<p><code>trigger(database, event)</code></p>

<p>手动触发指定数据库的指定事件。</p>

<p>举例，两个不同模块之间的广播监听示例：</p>

<pre><code>Module A:

jsql.on('global', 'moduleBChange', function(arg1, arg2) {
    // do something
});

Module B:

jsql.trigger('global', 'moduleBChange', arg1, arg2);
</code></pre>

<p>举例，监听某个数据库的创建：</p>

<pre><code>jsql.on('local', 'create', function() {
    // do something
});

jsql.create('local', {});
</code></pre>

<h3>闭合操作</h3>

<p>所谓闭合操作即执行到此将重置缓冲区，是链式查询的最终状态。</p>

<ul>
<li><code>count()</code></li>
<li><code>find()</code></li>
<li><code>findAll()</code></li>
<li><code>listAll()</code></li>
<li><code>insert()</code></li>
<li><code>save()</code></li>
<li><code>saveAll()</code></li>
<li><code>update()</code></li>
</ul>


<p>除此之外，<code>use()</code>也会触发缓冲区重置的操作。</p>
</body>
</html>