Skip to content

Commit 21d334a

Browse files
author
Chasen Le Hara
committed
Update README generated by DoneJS
1 parent 0e5a583 commit 21d334a

File tree

1 file changed

+16
-93
lines changed

1 file changed

+16
-93
lines changed

‎README.md

Lines changed: 16 additions & 93 deletions
Original file line numberDiff line numberDiff line change
@@ -1,105 +1,28 @@
11
# can-query-logic
22

3-
[![Build Status](https://travis-ci.org/canjs/can-query-logic.svg?branch=master)](https://travis-ci.org/canjs/can-query-logic)
3+
[![Join our Slack](https://img.shields.io/badge/slack-join%20chat-611f69.svg)](https://www.bitovi.com/community/slack?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
4+
[![Join our Discourse](https://img.shields.io/discourse/https/forums.bitovi.com/posts.svg)](https://forums.bitovi.com/?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
5+
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/canjs/can-query-logic/blob/master/LICENSE)
6+
[![npm version](https://badge.fury.io/js/can-query-logic.svg)](https://www.npmjs.com/package/can-query-logic)
7+
[![Travis build status](https://travis-ci.org/canjs/can-query-logic.svg?branch=master)](https://travis-ci.org/canjs/can-query-logic)
8+
[![AppVeyor build status](https://ci.appveyor.com/api/projects/status/github/canjs/can-query-logic?branch=master&svg=true)](https://ci.appveyor.com/project/matthewp/can-query-logic)
9+
[![Coverage status](https://coveralls.io/repos/github/canjs/can-query-logic/badge.svg?branch=master)](https://coveralls.io/github/canjs/can-query-logic?branch=master)
10+
[![Greenkeeper badge](https://badges.greenkeeper.io/canjs/can-query-logic.svg)](https://greenkeeper.io/)
411

5-
## Purpose
6-
7-
`can-query-logic` is used to give CanJS an _understanding_ of what __the parameters used to
812
retrieve a list of data__ represent. This awareness helps other libraries like
9-
[can-connect] and [can-fixture] provide real-time, caching and other behaviors.
10-
11-
__The parameters used to retrieve a list of data?__
12-
13-
In many applications, you request a list of data by making a `fetch` or `XMLHTTPRequest`
14-
to a url like:
15-
16-
```
17-
/api/todos?filter[complete]=true&sort=name
18-
```
19-
20-
The values after the `?` are used to control the data that comes back. Those values are
21-
deserialized into
22-
a query object look like this:
23-
24-
```js
25-
{
26-
filter: {complete: true},
27-
sort: "name"
28-
}
29-
```
30-
31-
This object represents a `Query`. This specific query is for requesting completed todos and have the todos sorted by their _name_.
32-
33-
A `QueryLogic` instance _understands_ what a `Query` represents. For example, it can filter records
34-
that match a particular query:
35-
36-
```js
37-
var todos = [
38-
{ id: 1, name: "learn CanJS", complete: true },
39-
{ id: 2, name: "wash the car", complete: false },
40-
{ id: 3, name: "do the dishes", complete: true }
41-
]
42-
43-
var queryLogic = new QueryLogic();
44-
45-
var result = queryLogic.filterMembers({
46-
filter: {complete: true}
47-
}, todos);
48-
49-
result //-> [
50-
// { id: 3, name: "do the dishes", complete: true },
51-
// { id: 1, name: "learn CanJS", complete: true }
52-
//]
53-
```
54-
55-
The `filterMembers` method allows `QueryLogic` to be used similar to a database. `QueryLogic` instances methods help solve other problems too:
56-
57-
- __real-time__ - `.isMember` returns if a particular item
58-
belongs to a query and `.index` returns the location where that item belongs.
59-
- __caching__ - `.isSubset` can tell you if you've already loaded
60-
data you are looking for. `.difference` can tell you what data
61-
you need to load that already isn't in your cache.
62-
63-
In fact, `can-query-logic`'s most unique ability is to be able to directly compare
64-
queries that represent sets of data instead of having to compare
65-
the data itself. For example, if you already loaded all completed todos,
66-
`can-query-logic` can tell you how to get all remaining todos:
67-
68-
```js
69-
var completedTodosQuery = {filter: {complete: false}};
70-
var allTodosQuery = {};
71-
var remainingTodosQuery = queryLogic.difference(allTodosQuery, completedTodosQuery);
72-
73-
remainingTodosQuery //-> {filter: {complete: {$ne: false}}}
74-
```
75-
7613

77-
### Matching the default query structure
14+
## Documentation
7815

79-
By default, `can-query-logic` assumes your service layer will match a default query structure
80-
that looks like:
16+
Read the [can-query-logic API docs on CanJS.com](https://canjs.com/doc/can-query-logic.html).
8117

82-
```js
83-
{
84-
// Selects only the todos that match.
85-
filter: {
86-
complete: {$in: [false, null]}
87-
},
88-
// Sort the results of the selection
89-
sort: "-name",
90-
// Selects a range of the sorted result
91-
page: {start: 0, end: 19}
92-
}
93-
```
18+
## Changelog
9419

95-
This structures follows the [Fetching Data JSONAPI specification](http://jsonapi.org/format/#fetching).
20+
See the [latest releases on GitHub](https://github.com/canjs/can-query-logic/releases).
9621

97-
There's:
22+
## Contributing
9823

99-
- a [filter](http://jsonapi.org/format/#fetching-filtering) property for filtering records,
100-
- a [sort](http://jsonapi.org/format/#fetching-sorting) property for specifying the order to sort records, and
101-
- a [page](http://jsonapi.org/format/#fetching-pagination) property that selects a range of the sorted result. _The range indexes are inclusive_.
24+
The [contribution guide](https://github.com/canjs/can-query-logic/blob/master/CONTRIBUTING.md) has information on getting help, reporting bugs, developing locally, and more.
10225

26+
## License
10327

104-
If you control the service layer, we __encourage__ you to make it match the default
105-
query structure. The default query structure also supports the following comparison operators: `$eq`, `$gt`, `$gte`, `$in`, `$lt`, `$lte`, `$ne`, `$nin`.
28+
[MIT](https://github.com/canjs/can-query-logic/blob/master/LICENSE)

0 commit comments

Comments
 (0)