Upgrading from v0 to v1

• Introduction
• Prerequisites
• Breaking Changes
• Resolvers
• Entities
• Mikro Data Provider (Postgres, MySql, Sqlite)
• Optional - Entity Serialisation Changes
• Configuration Changes
• Project Dependencies
• Migration Guide
• Step 1: Resolvers
• Step 2: Entities
• Step 3: Packages
• Step 4: Get Help if You’re Stuck

Introduction

In this release, we have made significant improvements and introduced several key changes to enhance functionality and streamline the development process. Notable achievements include:

• Custom Metadata Store: We have removed TypeGraphQL and created our own metadata store, addressing issues related to excessive data being added to TypeGraphQL metadata. This makes Graphweaver more performant and much easier for us to extend in the future.
• Simplified API Definition: The need to create resolvers has been eliminated. Now, you only need to define entities to establish the API, simplifying the development workflow.
• Custom Mutations and Queries: You can now add custom mutations and queries directly from anywhere in your code, providing greater flexibility and control.
• Flexible Primary Key Naming: The primary key of an entity can now be named any key name, offering more versatility in entity definition.
• Apollo Federation v1 and v2 Compatibility: Graphweaver is now compliant with all required tests to support Apollo Federation (and Open Federation). Use Graphweaver to bring together all of the tools your team uses into one simple and easy to maintain subgraph!

These changes aim to improve the overall efficiency and flexibility of the system, making it easier to work with and more adaptable to various use cases.

Prerequisites

• Node Version Requirement: Node 18.12+ required.
• Node Version Requirement: PNPM 9+ required.
• TypeScript Version Requirement: TypeScript 5.0+ required.

Breaking Changes

Below are some of the breaking changes that you will have to support in your upgrade.

Resolvers

You no longer need to create your resolvers for each entity. Now you only need to create the entity and all the mutations and queries will be created for you.

In addition, as there are no longer any resolvers, you can remove the resolvers array from your Graphweaver instance arguments:

Entities

There have been a number of changes to the way you now create entities. The most notable changes are in the decorators. Previously we used the TypeGraphQL decorators alongside some Graphweaver decorators, which was a bit confusing. Now all decorators are Graphweaver decorators, making it easier to tell what options you have for each.

We no longer use the @ObjectType decorator to define the entity. Now we use the @Entity decorator. In the screenshot below we can see that we are also attaching a data provider.

The entity no longer needs to extends GraphQLEntity. This should now be removed.

The class property of public dataEntity! no longer needs to be defined on the entity.

The @summaryField decorator has now gone and instead the @field decorator now takes an adminUIOptions attribute where the summaryField can be defined:

The @ReadOnlyProperty decorator has also been removed. You can now mark the field as readonly in the @field decorator properties:

The @AdminUISettings decorator has also been removed. The options can now be added to the field options.

In summary, you can now tell what all the options for an Entity or Field are by looking at the options object that is passed into the decorator itself.

Mikro Data Provider (Postgres, MySql, Sqlite)

Mikro Data entities no longer need to extend the BaseEntity:

Optional - Entity Serialisation Changes

Since we no longer care as much about the shape of the backend entity and the GraphQL entity, these can be the same class if you like. This means you can use your ORM entities directly in the schema if it suits you.

If a GraphQL entity statically defines fromBackendEntity it’ll be called when instantiating GraphQL entities from the backend data source. You can also implement toBackendEntity to control the other side of the serialisation. toBackendEntityFilter transforms from a GraphQL filter to a filter object understood by your provider.

Implementing any of these functions is optional, but if you need a convenient place to transform data on the way to / from the provider, these are a great option.

Configuration Changes

Project Dependencies

We have removed TypeGraphQL from the project along with the need for the reflect-metadata package. Both of these packages can be removed from your repo:

• reflect-metadata
• type-graphql

Migration Guide

Step 1: Resolvers

Remove all the existing resolvers:

• Remove the resolvers array from your Graphweaver instance.
• Ensure entities are loaded at runtime (e.g., import './schema' in index.ts).
• Ensure any custom queries / mutations are registered using graphweaverMetadata.addQuery() and graphweaverMetadata.addMutation() as documented in 🎱Custom Queries and Mutations.

Step 2: Entities

Update your entities:

• Replace @ObjectType with @Entity.
• Remove extends GraphQLEntity.
• Remove the public dataEntity property.
• @SummaryField needs to be replaced with @Field with adminUIOptions.summaryField option specified.
• @ReadOnlyProperty is removed; use @Field with a readonly attribute.
• @AdminUISettings is removed; options are now in @Field’s options argument.

Step 3: Packages

Remove the unused dependencies from your package.json:

• Remove reflect-metadata package.
• Remove type-graphql package.

Step 4: Get Help if You’re Stuck

If you’re having any trouble upgrading to v1, reach out to us on Slack! We’re happy to help.