Nearest Phase Modulator

    hasura-om

    1.4.6 • Public • Published

    Hasura ORM library

    NPM

    Coverage Status XO code style Awesome FOSSA Status

    Docs Test/Lint/Coverage NPM package

    npm bundle size npm npm

    This library provides an object way to interact with Hasura from backend. Main focus is on fragments, queries are autogenerated. Base fragments (base - all table fields/pk - primary keys) are autogenerated, then you can extend them or create new.

    Instalation

    npm i hasura-om
    

    Motivation

    We have a microservice infrastructure and need cross-service transactions. One way to do it is to send a graphql query + variables to one service and perform a query there. So this library helps to send more standardized data via JS Objects. If you know a better way to solve this problem, you are welcome to issues or email.

    Docs

    Current guide is here

    Roadmap

    • [x] Fragment extending (v0.0.7)
    • [x] Subscriptions (v0.0.10)
    • [x] Aggregate queries (v0.0.12)
    • [x] Nested queries (v0.0.15)
    • [x] Hasura class extend EventEmitter (v0.0.18)
    • [x] Docs (v0.0.19)
    • [x] Browser bundle (v1.2.0) with bundler only
    • [x] Jwt authorization support (v1.2.0)
    • [ ] Cache interface
    • [ ] Refactor query builder code
    • [ ] Support directives
    • [ ] Support new Hasura event scheduler
    • [ ] Tune performance

    Simple example

    const { Hasura } = require('hasura-om')
    
    const om = new Hasura({
        graphqlUrl: 'your hasura endpoint',
        adminSecret: 'your hasura admin secret'
    })
    /*
        this command loads data from Hasura about tables/fields/keys 
        to build base table fragments for simple queries
        So the fragments are:
            -base 
                All table fields
            -pk
                Only primary keys
    */
    await om.generateTablesFromAPI()
    
    //query 
    let [err, result] = await om.query({
        user: {
            where: {
                is_live: {
                    _eq: true
                }
            },
            limit: 10,
            order_by: {
                rating: 'desc'
            }
        },
        pets: {
            select: {
                where: {
                    type: {
                        _eq: 'dog'
                    }
                },
                fields: `
                    id
                    name
                `
            },
            aggregate: {
                count: {},
                avg: ['age']
            }
        }
    })
    
    /* 
    result = {
        user: [
            {
                ...all_user_base_fields
            },
        ],
        pets: {
            select: [
                {
                    id,
                    name
                }
            ],
            aggregate: {
                count: 23,
                avg: {
                    age: 3.5
                }
            }
        }
    } 
    */
    
    
    //mutation
    let [err, result] = await om.mutate({
        user: {
            update: {
                where: {
                    _eq: {
                        id: 666
                    }
                },
                _inc: {
                    money: 100
                }
            }
        },
        wallet: {
            insert: {
                objects: {
                    user_id: 666,
                    type: 'deposit',
                    amount: 100
                },
                fragment: 'pk'
            }
        }
    })
    
    /* 
    result = {
        user: {
            update: [
                {
                    id: 666,
                    money: 100
                    ...all_user_base_fields
                }
            ]
        },
        wallet: {
            insert: [
                {
                    id: 1002
                }
            ]
        }
    } 
    */
    
    
    //subscription
    let unsub = om.subscribe({
        user: {
            where: {
                is_live: {
                    _eq: true
                }
            },
            limit: 10,
            order_by: {
                rating: 'desc'
            }
        },
        pets: {
            where: {
                type: {
                    _eq: 'dog'
                }
            },
            fields: `
                id
                name
            `
        }
    }, ([err, data]) => {
        //so data will come in the same format as the query
    })

    Fragments

    The only control you have is fragments. So this library provides base fragments with all table fields without relations. Of course you need them, so you have many ways to do so.

    //here is an example of simple query
    var [err, response] = await orm.query({
        user: {}
    })
    
    //So here some examples with fields key
    var [err, response] = await orm.query({
        user: {
            fields: `
                name
                posts {
                    title
                }
            `,
            
            //or
            fields: [
                'name',
                {
                    key: 'posts',
                    values: [
                        'title'
                    ]
                }
            ],
    
            //or
            fields: {
                name: null,
                posts: {
                    children: {
                        title: null
                    }
                }
            }
        }
    })
    
    //or we can create new Fragment
    let newFragment = new Fragment({
        name: 'some_unique_name',
        table: 'user',
        fields: `
            name
            posts {
                title
            }
        `//any from abobe
    })
    var [err, response] = await orm.query({
        user: {
            fragment: newFragment
        }
    })
    
    //or even better, we can extend user fragments and use it anytime
    orm.table('user').createFragment('some_unique_name', `
        name
        posts {
            title
        }
    `)
    var [err, response] = await orm.query({
        user: {
            fragment: 'some_unique_name'
        }
    })
    
    //of course we can use other fragments to create new one
    let baseUserFragment = orm.table('user').fragment('base')
    let basePostFragment = orm.table('post').fragment('base')
    
    orm.table('user').createFragment('some_unique_name', [
        baseUserFragment,
        {
            key: 'posts',
            values: [
                basePostFragment,
            ]
        }
    ])

    Nested fields arguments

    This is really hard to implement and I hope current implementation works fine. I will investigate it later, when I will have troubles or get any issues.

    const fragment2 = new Fragment({
        table: 'test',
        name: 'with_nested_args',
        fields: [
            'id',
            [
                'logo',
                ['url'],
                {
                    _table: 'images',
                    limit: 'logo_limit',
                    offset: 'logo_offset',
                    where: 'logo_where',
                    order_by: 'logo_order_by',
                    distinct_on: 'logo_distinct_on',
                },
            ],
        ],
    });
    
    /* 
    This will generate such fragment
    
    Fragment with_nested_args_fragment_test on test {
        id
        logo (limit: $logo_limit, ...) {
            url
        }
    }
    */
    
    await orm.query({
        test: {
            fragment: 'with_nested_args',
            variables: {
                'logo_limit': 1
            }
        }
    })

    License

    FOSSA Status

    Install

    npm i hasura-om

    DownloadsWeekly Downloads

    4

    Version

    1.4.6

    License

    MIT

    Unpacked Size

    91.3 kB

    Total Files

    28

    Last publish

    Collaborators

    • mrspartak