Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/mrspartak/hasura-om
👺 Fragment based orm request generator for Hasura with built in auto-table lookup and base fragment builder
https://github.com/mrspartak/hasura-om
automatic-api fragments graphql graphql-api graphql-client graphql-js graphql-schema graphql-server graphql-subscriptions graphql-tools hasura hasura-orm microservice nodejs orm orm-framework postgres
Last synced: 3 months ago
JSON representation
👺 Fragment based orm request generator for Hasura with built in auto-table lookup and base fragment builder
- Host: GitHub
- URL: https://github.com/mrspartak/hasura-om
- Owner: mrspartak
- License: mit
- Created: 2020-05-17T15:05:44.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2023-03-04T18:42:51.000Z (almost 2 years ago)
- Last Synced: 2024-05-19T14:31:15.760Z (8 months ago)
- Topics: automatic-api, fragments, graphql, graphql-api, graphql-client, graphql-js, graphql-schema, graphql-server, graphql-subscriptions, graphql-tools, hasura, hasura-orm, microservice, nodejs, orm, orm-framework, postgres
- Language: JavaScript
- Homepage: https://hasura-om.js.org/
- Size: 5.17 MB
- Stars: 21
- Watchers: 2
- Forks: 2
- Open Issues: 28
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-hasura - hasura-om - Fragment based orm request generator with built in auto-table lookup and base fragment builder. Also comes with a query/mutation/subscribe libraries built in (Tools and Extensions)
README
# Hasura ORM library
[](https://www.npmjs.com/package/hasura-om)
[](https://coveralls.io/github/mrspartak/hasura-om?branch=master)
[](https://github.com/xojs/xo)
[](https://github.com/aaronhayes/awesome-hasura)
[](https://app.fossa.com/projects/git%2Bgithub.com%2Fmrspartak%2Fhasura-om?ref=badge_shield)
[](https://www.npmjs.com/package/hasura-om)
[](https://www.npmjs.com/package/hasura-om)
[](https://www.npmjs.com/package/hasura-om)
[](https://www.npmjs.com/package/hasura-om)
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](https://mrspartak.github.io/hasura-om/)
## 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
```javascript
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.
```javascript
//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.
```javascript
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
[](https://app.fossa.com/projects/git%2Bgithub.com%2Fmrspartak%2Fhasura-om?ref=badge_large)