UniPin Angular GQL

UniPin Angular GQL is internal tool used by UniPin to allows our website to fetch data from GraphQL server and use it in building complex and reactive UIs using the Angular framework. UniPin Angular GQL requires no complex build setup to get up and running. UniPin Angular GQL works out of the box with both Angular CLI (npm i @unipin/angular-gql) with a single install.

UniPin Angular GQL is:

1. Incrementally adoptable, so that you can drop it into an existing Angular app and start using GraphQL for just part of your UI.
2. Universally compatible, so that works with any build setup, any GraphQL server, and any GraphQL schema.
3. Simple to get started with, so you can start loading data right away.
4. Inspectable and understandable, so that you can have great developer tools to understand exactly what is happening in your app.
5. Small and flexible, so it doesn't need any additional dependencies. It uses Angular HttpClient under the hood.

Versions

| Angular | @unipin/angular-gql | |------------------|:-------------------:| | >=18.0.0 | v1.0.4 |

Table of contents

• Getting started
• API
• Development
• Release
• Inspiration

Getting started

Step 1: Install @unipin/angular-gql:

NPM

npm install --save @unipin/angular-gql

Step 2: Provide UniPin Angular GQL configuration

Standalone: Call provideUniPinGql function inside ApplicationConfig providers array:

import { provideUniPinGql } from '@unipin/angular-gql';

export const appConfig: ApplicationConfig = {
  providers: [
    provideUniPinGql({
      uri: 'https://api.unipin.com/graphql'
    }),
  ]
};

NgModule: Call provideUniPinGql function inside AppModule providers array:

import { provideUniPinGql } from '@unipin/angular-gql';

@NgModule({
  providers: [
    provideUniPinGql({
      uri: 'https://api.unipin.com/graphql'
    }),
  ]
})
export class AppModule {}

Step 3: Use it inside service

import { GqlParser, QueryResult } from '@unipin/gql-parser';

@Injectable({ 
  providedIn: 'root' 
})
export class Service {

  constructor(
    protected readonly gql: GqlParser
  ) { }

  public query(): Observable<QueryResult<{ queryUser: User }>>{
    return this.gql.query({
      variables: { 
        input: {
          name: 'John Doe'
        } 
      },
      query: `
        query Query($input: UserCriteria) {
          queryUser(input: $input) {
            guid
            name
            code
          }
        }
      `
    });
  }
}

API

UniPin Angular GQl Configuration

| Input | Type | Default | Required | Description | |------------------|---------------------|------------|----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | uri | string | - | true | GraphQL server URI | | cacheSize | number | 100 | false | GraphQL cache size | | useOperationPath | boolean | false | false | When it's true, client will use operation name at GraphQL url, ex: https://api.unipin.com/graphql/QueryUser. Please make sure that the GraphQL server is ready for this path pattern |

Gql Parser Methods

| Name | Parameters | Return Type | Description | |---------------|---------------------|---------------------------------|------------------------------------| | query | QueryOptions | Observable<QueryResult<T>> | GraphQL server URI | | mutate | MutationOptions | Observable<MutationResult<T>> | GraphQL server URI |

QueryOptions

| Input | Type | Default | Required | Description | |---------------|--------------------------|---------------|----------|------------------------------------| | query | string | - | true | GraphQL query | | variables | object | undefined | false | GraphQL variables | | operationName | string | undefined | false | GraphQL operation name | | cacheStrategy | string | cache-first | false | Cache strategy | | headers | Record<string, string> | undefined | false | HTTP headers |

MutationOptions

| Input | Type | Default | Required | Description | |---------------|--------------------------|---------------|----------|------------------------------------| | mutation | string | - | true | GraphQL mutation | | variables | object | - | true | GraphQL variables | | operationName | string | undefined | false | GraphQL operation name | | headers | Record<string, string> | undefined | false | HTTP headers |

QueryResult | MutationResult

| Input | Type | Default | Required | Description | |---------------|---------------------|---------------|----------|------------------------------------| | data | object | {} | true | GraphQL data | | errors | any[] | undefined | false | GraphQL errors |

CacheStrategy

| Name | Description | |-------------------|----------------------------------------------------------------------------------------------------| | cache-first | If cache existed, data retrieved from cache. If not existed, client will retrieve data from server | | network-only | Client will retrieve data from server | | cache-and-network | Client will retrieve data from cache storage and update the cache from server | | cache-only | Client will retrieve data from cache storage | | no-cache | No cache |

Development

Perform the clone-to-launch steps with these terminal commands.

Run demo page in watch mode

git clone [email protected]:MobileArts/unipin-angular-gql.git
cd unipin-angular-gql
npm run start

Release

To release to npm just run npm run publish, of course if you have permissions ;)

Inspiration

This library is inspired by Apollo Angular. Check theirs amazing work and components :)