npm package: @scottburch/graphql-gun
Description: NOTE: This library is a new release and as such has not had good field testing.  Please feel free to use and report any issues.
Latest version: 1.0.3

# GraphQL-gun

NOTE: This library is a new release and as such has not had good field testing.  Please feel free to use and report any issues.

A GraphQL library for GunDB queries. (looking at mutations next)

GraphQL-gun returns a RxJS Observable so you have all of the RxJS goodness available to you.

### install

`npm install @scottburch/graphql-gun`

`yarn add @scottburch/graphql-gun`



### Quickstart

**1) Define a basic query**

```typescript
const query = gql`
    {
        app {
            settings {
                rememberMe 
            }
        }
	    user {
	        name
	    }
    }
`;
```

**2) Add values to GunDB**

```typescript
gun.get('app').get('settings').get('rememberMe').put(true)
gun.get('user').get('name').put('scott')
```

**3) Run the query and get the result**

```typescript
graphqlGun(query, gun).subscribe(result => {/* do something here*/})
```

NOTE: This will fire twice since there are really two values we are after.  The second time will have all of the requested data.

If you want to filter out results that you don't care about, you can use RxJS filter to look for the values you want.
```typescript
graphqlGun(query, gun).pipe(
		filter(({app, user}) => app?.settings?.rememberMe != undefined && user?.name)
).subscribe(result => {/* do something here*/})
```

### Other Options



**Using with GunDB Sets**

```typescript
gql`
    users(type: Set) {
	    name
	    age
	}
`;
```

Currently the set will be returned multiple times for each item in the set.  This is so since the length of the set is not known at the beginning.  The code below takes the first three responses and returns the last one which includes the first three elements of the set.
```typescript
const gun = Gun();

const query = gql`
    {
        users(type: Set) {
            name
        }
    }
`;

const alice = gun.get('user').get('alice').put({name: 'alice'})
const bob = gun.get('user').get('bob').put({name: 'bob'})
const charlie = gun.get('user').get('charlie').put({name: 'charlie'})
gun.get('users').set(alice);
gun.get('users').set(bob);
gun.get('users').set(charlie);

graphqlGun(query, gun).pipe(
    take(3),
    last(),
).subscribe(result => {/* { users: [ { name: 'bob' }, { name: 'charlie' }, { name: 'alice' } ] } */})
```



**Continuous live updates**

To attach a live listener you can use `@live` directive in your query.
```typescript
const query = gql`
    user {
        name @live
    }
`;
```

```typescript
graphqlGun(query, gun).subscribe(result => {/* called every time "name" changes */})
```



**Getting a gun instance in context**

To get a gun instance in context you can use a `_chain` property.
```typescript
const gun = Gun();

const query = gql`
    {
        user {
            _chain
        }
    }
`;

gun.get('user').get('name').put('alice');

graphqlGun(query, gun).subscribe(({user}) => user._chain.get('name').once((name: string) => {/* alice */}));
```



### React

To use GraphQL-gun with React you should use [react-rxjs](https://react-rxjs.org/).

```typescript
import {bind} from "@react-rxjs/core";

const query = gql`
	{
			user @live {
				name
			}
	}
`;

const username$ = graphqlGun(query, gun).pipe(
	map(({user}) => user.name)
);

export const [useUsername] = bind(username$, 'default username');
```



### Typescript

You can pass in your schema as a type to graphqlGun().  I am currently looking into ways to convert graphQL into types.
```typescript
type Schema = {
    user: {
        name: string
    }
}

graphqlGun<Schema>(query, gun).subscribe(({user}) => user?.name)
```



### Development

You will find mocha tests in the src directory in .spec.ts files.  To run the tests you can run the 'test' script in package.json.
Ex.  `yarn test`

If you want to submit a bug or feature request, it should come with a test.