Hasura ORM library

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