🎀

Decorators

Introduction

When working with Graphweaver, you'll often come across scenarios where you need to add additional functionality or behavior to your entities or resolvers.

This is where decorators come into play, allowing you to easily extend and customize your code.

Understanding a Decorator

Before we dive into usage, let's take a moment to understand what decorators are. In Graphweaver, decorators are functions that modify the behavior of a class or its members, such as properties or methods.

They are prefixed with an @ symbol and applied using the decorator syntax.

TypeGraphQL Decorators

There are two TypeGraphQL decorators that you will use on an entity @ObjectType() and @Field .

For more information on these decorators can be found on their Types and Fields documentation.

Graphweaver Decorators

The RelationshipField Decorator

This decorator is used to link one entity to another. There are two options linking to a collection of entities or linking to one entity. Let’s look at each one in-turn starting with linking to a collection. To link to a collection you would use the relatedField property. Here is an example: 

@ObjectType('Tag')
export class Tag extends GraphQLEntity<OrmTag> {
	public dataEntity!: OrmTag;

	@Field(() => ID)
	id!: string;

  @ReadOnlyProperty()
	@Field(() => String)
	name!: string;

	@RelationshipField<Task>(() => [Task], { relatedField: 'tags' })
	tasks!: Task[];
}

In the above the Tag entity has many Tasks and the related field on the Task entity is tags.

Now let’s look at linking to a single entity:

@ApplyAccessControlList(acl)
@ObjectType('Task')
export class Task extends GraphQLEntity<OrmTask> {
	public dataEntity!: OrmTask;

	@Field(() => ID)
	id!: string;

	@Field(() => String)
	description!: string;

	@RelationshipField<Task>(() => User, { id: 'userId' })
	user!: User;
}

In the above example the Task entity has one User entity attached and here we need to link the id of the user entity. The userId here is the column name on the data entity that holds the user ID field.

The ReadOnlyProperty Decorator

This decorator is designed to mark a property as read-only, indicating that it cannot be modified once set. Let's explore how to use this decorator within an entity. 

@ObjectType('Tag')
export class Tag extends GraphQLEntity<OrmTag> {
	public dataEntity!: OrmTag;

	@Field(() => ID)
	id!: string;

  @ReadOnlyProperty()
	@Field(() => String)
	name!: string;

	@RelationshipField<Task>(() => [Task], { relatedField: 'tags' })
	tasks!: Task[];
}

In the above example, we have set the name field on this entity as read-only so it cannot be modified via a GraphQL mutation.

The ReadOnlyProperty decorator can accept an optional configuration object with the following options.

  • adminUI Indicates whether the property should be exposed in the admin UI. If set to false, the property will be editable in the admin user interface. Default: true
  • backend Indicates whether the property is relevant to the backend. If set to false, the property may not be used or processed in backend operations. Default: true

The ReadOnly Decorator

The ReadOnly decorator is used to mark a whole entity class as read-only. This means that no mutation resolvers will be generated for the class, allowing only read operations on the data.

Here's an example:

@ReadOnly()
@ObjectType('Tag')
export class Tag extends GraphQLEntity<OrmTag> {
	public dataEntity!: OrmTag;

	@Field(() => ID)
	id!: string;
}

In this case, the ReadOnly decorator is applied to the Tag class, making it read-only and preventing the generation of any mutation resolvers for the tag entity.

The ReadOnly decorator can accept an optional configuration object with the following options.

  • adminUI Indicates whether the property should be exposed in the admin UI. If set to false, the property will be editable in the admin user interface. Default: true
  • backend Indicates whether the property is relevant to the backend. If set to false, the property may not be used or processed in backend operations. Default: true

The ExcludeFromFilterType Decorator

The ExcludeFromFilterType decorator enables you to mark a field as excluded from filter input types generated by BaseResolver. This means that the field won't be included in any filter input types used by queries.

Here's an example:

@ObjectType('Tag')
export class Tag extends GraphQLEntity<OrmTag> {
	public dataEntity!: OrmTag;

	@Field(() => ID)
	id!: string;

  @ExcludeFromFilterType()
	@Field(() => String)
	name!: string;

	@RelationshipField<Task>(() => [Task], { relatedField: 'tags' })
	tasks!: Task[];
}

By applying the ExcludeFromFilterType decorator to a field in the Tag entity, we have prevented the name field from being included in any filter input types generated by BaseResolver.

The Hook Decorator

The Hook decorator is used to “hook” into lifecycle events for an entity such as beforeRead or afterUpdate. See the hook section for more information.

The MediaField Decorator

The @MediaField decorator is used to describe a field that represents media. Graphweaver supports uploading media to a storage provider, and rendering images in the admin ui. To do this, Graphweaver supplies a storage provider class and a MediaField decorator to connect and describe the media being uploaded. An example of using AWS S3 to handle images can be seen in the examples folder.

MediaField accepts:

  • storageProvider - A provider that supplies a getDownloadUrl method to the decorator to get the resource.
  • resourceId - An identifier for the storage provider to get the media, this is another field on the entity.
  • mediaType - A enum describing the kind of media.

An example of a storage provider and usage of the @MediaField decorator can be seen below:


const s3 = new S3StorageProvider({
	bucketName: process.env.AWS_S3_BUCKET,
	region: process.env.AWS_REGION,
	type: StorageType.S3,
	expiresIn: 3600,
});

@ObjectType('Submission')
export class Submission extends GraphQLEntity<OrmSubmission> {
	public dataEntity!: OrmSubmission;

	@Field(() => ID)
	id!: string;

	@ReadOnlyProperty({ adminUI: true, backend: false })
	@Field(() => String, { nullable: true })
	key?: string;

	// "resourceId" must match the name of the field on the entity that gets the url from s3
	@MediaField({ storageProvider: s3, resourceId: 'key', mediaType: MediaTypes.IMAGE })
	downloadUrl?: string;
}

Exogee