vue-apollo-smart-ops/README.md

vue-apollo-smart-ops

Creates TypeScript-typed operation functions for GraphQL queries and mutations compatible with Vue Apollo.

This library is intended to be used together with the typescript-vue-apollo-smart-ops plugin for GraphQL Code Generator, but it may also be useful standalone.

Installation

npm install --save vue-apollo-smart-ops

Smart Query Usage

createSmartQueryOptionsFunction(query, onError?)

Returns a generated function which returns a Vue Apollo Smart Query options object for the given query when called.

⚠️ Note: The returned function is not meant to execute the query itself. It is only used to configure a Vue Apollo Smart Query. The responsibility for executing the query lies with Vue Apollo.

The returned function accepts an options object as its first argument, allowing variables and other parameters to be customised in runtime usage. Compared with creating an options object directly, the advantage here is that the options accepted by the generated function are fully type-checked based on the query definition - and without needing to pass type arguments at every usage.

Using the @graphql-codegen/typescript-vue-apollo-smart-ops plugin you can automatically generate options functions for all the query operations in your project.

The following example manually creates an options function and assigns it to the variable useTodoListQuery:

const useTodoListQuery = createSmartQueryOptionsFunction<TodosQuery, TodosQueryVariables>(gql`
  query Todos($skip: Int, $limit: Int) {
    todos(skip: $skip, limit: $limit) {
      id
      title
    }
  }
`);

This function can subsequently be called inside the apollo options of a Vue component to configure a Smart Query. The following example adds a todos Smart Query to a component, in Vue class component style:

@Component<TodoList>({
  apollo: {
    todos: useTodoListQuery<TodoList>({
      skip() {
        return this.foo === 'bar';
      },
      variables() {
        return {
          limit: 10,
          skip: 0,
        };
      },
    }),
  },
})
class TodoList extends Vue {
  todos: Todo[] | null = null;

  get foo(): string {
    return 'bar';
  }
}

@SmartQuery(options)

The @SmartQuery() decorator works with your generated options functions to enable the declaration of Smart Queries within the body of a Vue class component, instead of in the component options. This helps to keep the data property and its query options together in one place.

The following example is equivalent to the previous example but using the decorated syntax style:

@Component
class TodoList extends Vue {
  @SmartQuery(
    useTodoListQuery<TodoList>({
      skip() {
        return this.foo === 'bar';
      },
      variables() {
        return this.vars;
      },
    }),
  )
  todos: Todo[] | null = null;

  get foo(): string {
    return 'bar';
  }
}

Mutations Usage

createMutationFunction(mutation, onError?)

Returns a generated function which executes a mutation and returns the result when called.

The returned function requires a Vue app instance as its first argument (from which the $apollo client will be accessed), and accepts an options object as its second argument, allowing variables and other parameters to be customised in runtime usage. Compared with executing a mutation using the Vue Apollo client directly, the advantage here is that the options accepted by the generated function are fully type-checked based on the operation definition - and without needing to pass type arguments at every usage.

Using the @graphql-codegen/typescript-vue-apollo-smart-ops plugin you can automatically generate mutation functions for all the mutation operations in your project.

The following example manually creates a mutation function and assigns it to the variable todoCreateMutation:

const todoCreateMutation = createMutationFunction<TodoCreateMutation, TodoCreateMutationVariables>(gql`
  mutation TodoCreate($input: TodoInput!) {
    todoCreate(input: $input) {
      todo {
        id
        title
      }
    }
  }
`);

The following example demonstrates how to call this mutation from a method on a component:

@Component
class TodoList extends Vue {
  async onClickCreateTodoButton(): Promise<void> {
    const result = await todoCreateMutation(this, {
      variables: {
        title: 'Bake a cake',
      },
    });

    if (!result.success) {
      throw new Error(`Failed to create Todo!`);
    }
  }
}

Credits

• @SmartQuery() decorator is based on the vue-apollo-decorator package by chanlito, with some alteration to the types.