Neverending Programming Mistakes

    akita
    TypeScript icon, indicating that this package has built-in type declarations

    0.12.1 • Public • Published

    Akita

    Javascript network client library for Akita protocol.

    Protocol

    Akita protocol is based on HTTP, which is a superset of RESTful.

    Compared to the basic RESTful, Akita support list paging, limit, filters, update/remove multi record.

    If server has an error, the response body should contain error message and error code optionally.

    {
      "error": "Can not connect to database",
      "code": 1233 // optional
    }

    1. Get records list without paging.

    GET /path/to/res

    Query params:

    param type default
    _limit number
    _sort string
    _search string
    ...filters string/Object

    Result:

    [ /* Records list */
      { id: 1 /* Record 1 */ },
      { id: 2 /* Record 2 */ }
    ]

    Example:

    • Find all records sort by createdAt DESC

      GET /res?_sort=-createdAt

      await akita('res').find().sort('-createdAt')
    • Find 100 records where user is 12

      GET /res?user=12&_limit=100

      await akita('res').find({ user: 12 }).limit(100)

    2. Get records list with paging.

    GET /path/to/res/paginate

    Query params:

    param type default
    _page number 1
    _limit number
    _sort string
    _search string
    ...filters string/Object

    Result:

    {
      "total": 121, // total record
      "page": 1, // current page, default 1
      "limit": 10, // page limit
      "totalPage": 13,
      "previous": 0, // previous page index, zore for none
      "next": 2, // next page index, zore for none
      "search": "",
      "filters": {},
      "results":[ /* Records list */
        { id: 1 /* Record 1 */ },
        { id: 2 /* Record 2 */ }
      ]
    }

    Example:

    • Find records sort by createdAt DESC

      GET /res/paginate?_sort=-createdAt

      await akita('res').paginate().sort('-createdAt')
    • Find records where user is 12

      GET /res/paginate?user=12&_page=2

      await akita('res').paginate().where('user',12).page(2)
    • Find records where views great than 100

      GET /res/paginate?views[$gt]=100

      await akita('res').paginate().where('views').gt(100)

    3. Find one record by id

    GET /path/to/res/{ID}

    Query params:

    param type default
    ...filters string/Object

    Result:

    {
      "id": 123,
      // ... others
    }

    Example:

    • find record 123 and ensure user is 12

      GET /res/123?user=12

      await akita('res').findByPk(123).where({ user: 12})

    4. Get records count

    GET /path/to/res/count

    Query params:

    param type default
    _search string
    ...filters string/Object

    Result:

    {
      "count": 123
    }

    5. Create record

    POST /path/to/res

    Post body:

    {
      "title": "my book",
      // ... others data for creation
    }

    Result:

    {
      "id": 123,
      "title": "my book",
      // ... others data for creation
    }

    6. Remove record by id

    DELETE /path/to/res/{ID}

    Query params:

    param type default
    ...filters string/Object

    Result:

    {
      "removed": 1 // removed records count
    }

    7. Remove multi records by filters

    DELETE /path/to/res

    Query params:

    param type default
    _limit number
    _sort string
    _search string
    ...filters string/Object

    Result:

    {
      "removed": 5 // removed records count
    }

    8. Update one record by id

    PATCH /path/to/res/{ID}

    Query params:

    param type default
    ...filters string/Object

    Post body:

    {
      "title": "my book",
      // ... others data for update
    }

    Result:

    {
      "id": 123,
      "title": "my book",
      // ... others
    }

    9. Update multi records by filters

    PATCH /path/to/res

    Query params:

    param type default
    _limit number
    _sort string
    _search string
    ...filters string/Object

    Post body:

    {
      "title": "my book",
      // ... others data for update
    }

    Result:

    {
      "updated": 2, // updated records count
      "ids": [127, 342] // updated records id
    }

    10. Watch changes

    GET /path/to/res/watch

    Query params:

    param type default
    _search string
    ...filters string/Object

    Result:

    // JSON Stream
    {"type":"ADDED","object":{"id":1 /* Record 1 */ }}
    {"type":"MODIFIED","object":{"id":2 /* Record 1 */ }}
    {"type":"DELETED","object":{"id":2 /* Record 1 */ }}

    Javascript client usage

    Client Options

    option type defualt description
    apiRoot string '' API root path
    fetch Function window.fetch custom fetch function
    FormData Function window.FormData custom FormData class
    init Object fetch(url,init) init options https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/fetch#Parameters

    Client API

    • client(path: string): Query;

    create a query object

    • client.create(options: Object): Client;

    create a new client instance

    • client.resolve(key: string): Client;

    resolve a client instance by key, create a new instance if not found

    • client.setOptions(options: Object);

    update client instance options

    • client.request(path: string, init: Object): Promise;

    send a http request

    • client.get(path: string, init?: Object): Promise;

    send a http request with GET method

    • client.post(path: string, init?: Object): Promise;

    send a http request with POST method

    • client.put(path: string, init?: Object): Promise;

    send a http request with PUT method

    • client.patch(path: string, init?: Object): Promise;

    send a http request with PATCH method

    • client.delete(path: string, init?: Object): Promise;

    send a http request with DELETE method

    • client.head(path: string, init?: Object): Promise;

    send a http request with HEAD method

    • client.options(path: string, init?: Object): Promise;

    send a http request with OPTIONS method

    • client.trace(path: string, init?: Object): Promise;

    send a http request with TRACE method

    • client.connect(path: string, init?: Object): Promise;

    send a http request with CONNECT method

    Query API

    • query.create(data?: Object): Query;

    Create new record

    • query.arg(key: string | Object, value?: any): Query;

    Specifies custom arg.

    • query.find(conditions?: Object): Query;

    Find multi records without paging.

    • query.paginate(conditions?: Object): Query;

    Find records with paging.

    • query.findOne(conditions: Object): Query;

    Find one record by filters.

    • query.findByPk(id: string): Query;

    Find one record by id.

    • query.update(id?: Object, data: Object): Query;

    Update multi records or one record by id.

    • query.remove(conditions?: string|Object): Query;

    Remove multi records or one record by id.

    • query.search(keyword: string): Query;

    Specifies a search param

    • query.where(conditions: Object|string, value?: any): Query;

    Specifies query filter conditions

    • query.eq(value: any): Query;

    Specifies a filter condition

    • query.ne(value: any): Query;

    Specifies a $ne filter condition

    • query.regex(value: any): Query;

    Specifies a $regex filter condition

    • query.in(value: any[]): Query;

    Specifies a $in filter condition

    • query.nin(value: any[]): Query;

    Specifies a $nin filter condition

    • query.lt(value: any): Query;

    Specifies a $lt filter condition

    • query.lte(value: any): Query;

    Specifies a $lte filter condition

    • query.gt(value: any): Query;

    Specifies a $gt filter condition

    • query.gte(value: any): Query;

    Specifies a $gte filter condition

    • query.sort(value: any): Query;

    Specifies query sort

    • query.page(value: any): Query;

    Specifies query page

    • query.limit(value: any): Query;

    Specifies query page limit or update/remove limit.

    • query.exec(): Promise;

    Execute the query.

    Create new client instance

    import akita from 'akita';
    
    const client = akita.create({ /* options */});

    Examples

    // import default client instance
    import akita, { Model } from 'akita';
    
    // set options for defualt instance
    akita.setOptions({ /* options */});
    
    // create new instance
    const client = akita.create({ /* options */});
    // set options for new client
    client.setOptions({ apiRoot: 'http://your.domain/' /* other options */});
    
    // send plain HTTP POST request
    // POST http://your.domain/blog
    await client.post('blog',{ 
      body:{ 
        title: 'my book',
        file: fs.createReadStream('file.zip') // upload file
      } 
    });
    
    // define akita model:
    
    const User = client('user');
    
    // define akita model by class extends
    
    class Blog extends Model{
      static client = client;
      static path = 'blog';
      static pk = 'id';
    }
    
    // create / update record
    let blog = await Blog.create({ title: 'my book' });
    blog.title = 'changed';
    blog.file = fs.createReadStream('file.zip'); // upload file when save record
    await blog.save();
    
    // find records with paging
    await Blog.paginate();
    
    // find one record by id
    await Blog.findByPk(12);
    
    // find one record by filters
    await Blog.findOne({ category: 'js' }).sort('-createdAt');
    
    // update multi records
    await Blog.update({ hot: true }).sort('-views').limit(10);
    
    // update one record by id
    await Blog.update(12, { hot: true });
    
    // update multi records by filters & limit
    await Blog.update({ hot: true }).sort('-views').limit(5);
    
    // remove on record by id
    await Blog.remove(12);
    
    // remove multi records by filters
    await Blog.remove({ state: 1 });
    
    // or
    await Blog.remove().where('views').lt(100);
    

    Contribute

    Maichong Software

    Liang Xingchen

    Li Yudeng

    Zhao Lei

    License

    This project is licensed under the terms of the MIT license

    Keywords

    none

    Install

    npm i akita

    DownloadsWeekly Downloads

    31

    Version

    0.12.1

    License

    MIT

    Unpacked Size

    73 kB

    Total Files

    17

    Last publish

    Collaborators

    • liangxingchen