@mayademcom/nestjs-hasura

A powerful and flexible NestJS module for seamless integration with Hasura GraphQL Engine.

Features

✨ Fluent Builder API - Chain methods for clean and readable code
🔐 Built-in Authentication - Admin secret and JWT token support
📁 GraphQL File Loading - Load queries from .gql files with caching
🎯 TypeScript First - Full type safety and IntelliSense support
🚀 Flexible Configuration - Sync and async module registration
🎨 Custom Decorators - Extract auth tokens from request headers
⚡ Performance Optimized - Query caching for improved performance
🧪 Well Tested - Comprehensive unit and integration tests

Installation

npm install @mayademcom/nestjs-hasura graphql-request

Quick Start

1. Import the Module

Synchronous Configuration:

import { Module } from '@nestjs/common';
import { HasuraModule } from '@mayademcom/nestjs-hasura';

@Module({
  imports: [
    HasuraModule.forRoot({
      endpoint: 'https://your-hasura.app/v1/graphql',
      adminSecret: 'your-admin-secret', // Optional
    }),
  ],
})
export class AppModule {}

Asynchronous Configuration (Recommended for Production):

import { Module } from '@nestjs/common';
import { ConfigModule, ConfigService } from '@nestjs/config';
import { HasuraModule } from '@mayademcom/nestjs-hasura';

@Module({
  imports: [
    ConfigModule.forRoot({ isGlobal: true }),
    HasuraModule.forRootAsync({
      imports: [ConfigModule],
      useFactory: (configService: ConfigService) => ({
        endpoint: configService.get<string>('HASURA_ENDPOINT'),
        adminSecret: configService.get<string>('HASURA_ADMIN_SECRET'),
      }),
      inject: [ConfigService],
    }),
  ],
})
export class AppModule {}

2. Use in Your Service

import { Injectable } from '@nestjs/common';
import { HasuraService } from '@mayademcom/nestjs-hasura';

@Injectable()
export class UserService {
  constructor(private readonly hasura: HasuraService) {}

  async getUsers(limit: number) {
    const query = `
      query GetUsers($limit: Int!) {
        users(limit: $limit) {
          id
          name
          email
        }
      }
    `;

    return this.hasura
      .requestBuilder()
      .withAdminSecret()
      .withQuery(query)
      .withVariables({ limit })
      .execute();
  }
}

Usage Guide

Request Builder API

The module provides a fluent builder API for constructing GraphQL requests:

Basic Query

const result = await this.hasura
  .requestBuilder()
  .withQuery('query { users { id name } }')
  .execute();

With Variables

const result = await this.hasura
  .requestBuilder()
  .withQuery('query GetUser($id: uuid!) { users_by_pk(id: $id) { id name } }')
  .withVariables({ id: 'user-id' })
  .execute();

With Admin Secret

const result = await this.hasura
  .requestBuilder()
  .withAdminSecret()
  .withQuery('query { users { id } }')
  .execute();

With Authorization Token

const result = await this.hasura
  .requestBuilder()
  .withAuthorizationToken(jwtToken)
  .withQuery('query { me { id name } }')
  .execute();

With Custom Headers

const result = await this.hasura
  .requestBuilder()
  .withHeaders({
    'x-hasura-role': 'user',
    'x-hasura-user-id': '123',
  })
  .withQuery('query { users { id } }')
  .execute();

Chaining Multiple Methods

const result = await this.hasura
  .requestBuilder()
  .withAdminSecret()
  .withAuthorizationToken(token)
  .withHeaders({ 'x-tenant-id': 'tenant-123' })
  .withQuery(query)
  .withVariables(variables)
  .execute();

Loading Queries from Files

Store your GraphQL queries in .gql files for better organization:

Create a query file:

# src/queries/get-users.gql
query GetUsers($limit: Int!) {
  users(limit: $limit) {
    id
    name
    email
    created_at
  }
}

Use in your service:

@Injectable()
export class UserService {
  constructor(private readonly hasura: HasuraService) {}

  async getUsers(limit: number) {
    return this.hasura
      .requestBuilder()
      .withAdminSecret()
      .withQueryFromFile('src/queries/get-users.gql')
      .withVariables({ limit })
      .execute();
  }
}

Benefits:

• ✅ Queries are cached automatically after first load
• ✅ Better syntax highlighting in IDE
• ✅ Easier to maintain and version control
• ✅ Separation of concerns

Authorization Decorator

Extract authorization tokens from request headers:

import { Controller, Post, Body } from '@nestjs/common';
import { Authorization, HasuraService } from '@mayademcom/nestjs-hasura';

@Controller('webhooks')
export class WebhookController {
  constructor(private readonly hasura: HasuraService) {}

  // Optional token
  @Post('public')
  async publicWebhook(
    @Authorization() token: string | null,
    @Body() payload: any,
  ) {
    if (token) {
      // Authenticated request
      return this.hasura
        .requestBuilder()
        .withAuthorizationToken(token)
        .withQuery('query { me { id } }')
        .execute();
    }
    // Public request
    return { message: 'Public endpoint' };
  }

  // Required token
  @Post('protected')
  async protectedWebhook(
    @Authorization({ required: true }) token: string,
    @Body() payload: any,
  ) {
    return this.hasura
      .requestBuilder()
      .withAuthorizationToken(token)
      .withQuery('query { me { id name } }')
      .execute();
  }

  // Custom prefix
  @Post('api-key')
  async apiKeyWebhook(
    @Authorization({ prefix: 'ApiKey' }) apiKey: string | null,
    @Body() payload: any,
  ) {
    // Header: "ApiKey xxx-yyy-zzz"
    return { apiKey };
  }
}

Decorator Options:

Option	Type	Default	Description
required	boolean	false	Throws UnauthorizedException if token is missing
prefix	string	'Bearer'	Token prefix to strip from header

Module Configuration

Module Registration Methods

The module provides four registration methods:

forRoot(config)

Global module with synchronous configuration:

HasuraModule.forRoot({
  endpoint: 'https://hasura.app/v1/graphql',
  adminSecret: 'secret',
});

forRootAsync(config)

Global module with asynchronous configuration:

HasuraModule.forRootAsync({
  imports: [ConfigModule],
  useFactory: (config: ConfigService) => ({
    endpoint: config.get('HASURA_ENDPOINT'),
    adminSecret: config.get('HASURA_ADMIN_SECRET'),
  }),
  inject: [ConfigService],
});

register(config)

Module-scoped with synchronous configuration:

HasuraModule.register({
  endpoint: 'https://hasura.app/v1/graphql',
});

registerAsync(config)

Module-scoped with asynchronous configuration:

HasuraModule.registerAsync({
  imports: [ConfigModule],
  useFactory: (config: ConfigService) => ({
    endpoint: config.get('HASURA_ENDPOINT'),
  }),
  inject: [ConfigService],
});

Configuration Options

interface HasuraConfig {
  endpoint: string; // Hasura GraphQL endpoint URL
  adminSecret?: string; // Optional admin secret for admin operations
}

Advanced Usage

Multiple Hasura Instances

Use module-scoped registration for different Hasura endpoints:

// user.module.ts
@Module({
  imports: [
    HasuraModule.register({
      endpoint: 'https://users-hasura.app/v1/graphql',
      adminSecret: 'users-secret',
    }),
  ],
  providers: [UserService],
})
export class UserModule {}

// analytics.module.ts
@Module({
  imports: [
    HasuraModule.register({
      endpoint: 'https://analytics-hasura.app/v1/graphql',
      adminSecret: 'analytics-secret',
    }),
  ],
  providers: [AnalyticsService],
})
export class AnalyticsModule {}

Direct GraphQL Client Access

The HasuraService extends GraphQLClient from graphql-request, so you can use it directly:

// Using the native GraphQLClient request method
const result = await this.hasura.request(query, variables, headers);

TypeScript Type Safety

Define your GraphQL response types:

interface User {
  id: string;
  name: string;
  email: string;
}

interface GetUsersResponse {
  users: User[];
}

const result = await this.hasura
  .requestBuilder()
  .withQuery(query)
  .execute<GetUsersResponse>();

// result.users is now typed as User[]

Environment Variables

Create a .env file in your project root:

HASURA_ENDPOINT=https://your-hasura.app/v1/graphql
HASURA_ADMIN_SECRET=your-admin-secret

API Reference

HasuraService

requestBuilder(): HasuraRequestBuilder

Creates a new request builder instance.

HasuraRequestBuilder

withQuery(query: string): HasuraRequestBuilder

Sets the GraphQL query string.

withQueryFromFile(filePath: string): HasuraRequestBuilder

Loads and sets the GraphQL query from a .gql file.

withVariables(variables: Variables): HasuraRequestBuilder

Sets the GraphQL query variables.

withAdminSecret(): HasuraRequestBuilder

Includes the admin secret header from module configuration.

withAuthorizationToken(token: string): HasuraRequestBuilder

Adds Bearer token authorization header.

withHeaders(headers: Record<string, string>): HasuraRequestBuilder

Adds custom headers to the request.

execute<T>(): Promise<T>

Executes the GraphQL request and returns the response.

Authorization Decorator

@Authorization(options?: AuthorizationOptions)

Extracts and validates authorization token from request headers.

Options:

• required?: boolean - Throws error if token is missing (default: false)
• prefix?: string - Token prefix to remove (default: 'Bearer')

Best Practices

1. Use Environment Variables

Never hardcode credentials:

HasuraModule.forRootAsync({
  imports: [ConfigModule],
  useFactory: (config: ConfigService) => ({
    endpoint: config.get('HASURA_ENDPOINT'),
    adminSecret: config.get('HASURA_ADMIN_SECRET'),
  }),
  inject: [ConfigService],
});

2. Organize Queries in Files

Keep your queries in .gql files:

src/
├── queries/
│   ├── users/
│   │   ├── get-users.gql
│   │   ├── create-user.gql
│   │   └── update-user.gql
│   └── posts/
│       ├── get-posts.gql
│       └── create-post.gql

3. Use Type Safety

Define response types for better IDE support:

interface GetUsersResponse {
  users: Array<{
    id: string;
    name: string;
    email: string;
  }>;
}

const result = await hasura
  .requestBuilder()
  .withQuery(query)
  .execute<GetUsersResponse>();

4. Handle Errors Properly

try {
  const result = await this.hasura
    .requestBuilder()
    .withAdminSecret()
    .withQuery(query)
    .execute();
  return result;
} catch (error) {
  this.logger.error('Hasura query failed', error);
  throw new InternalServerErrorException('Failed to fetch data');
}

How to Release

This package uses release-it for automated releases. To create a new release:

Prerequisites

1. Ensure you're on the main branch
2. All tests must pass
3. Code quality checks must pass
4. You have npm publish permissions

Release Process

# 1. Pull latest changes
git checkout main
git pull origin main

# 2. Run release command (automated versioning)
npm run release

The npm run release command will:

• Run the tests
• Analyze commits since last release using Conventional Commits
• Determine version bump automatically (major/minor/patch)
• Update package.json version
• Generate/update CHANGELOG.md
• Create git commit and tag
• Push changes and tags to GitHub
• Publish to npm registry

Manual Version Specification

If you need to manually specify the version:

# Patch release (1.0.0 -> 1.0.1)
npm run release -- patch

# Minor release (1.0.0 -> 1.1.0)
npm run release -- minor

# Major release (1.0.0 -> 2.0.0)
npm run release -- major

# Specific version
npm run release -- 1.2.3

# Pre-release versions
npm run release -- prepatch --preRelease=beta  # 1.0.0 -> 1.0.1-beta.0
npm run release -- preminor --preRelease=alpha # 1.0.0 -> 1.1.0-alpha.0

Dry Run

Test the release process without actually releasing:

npm run release -- --dry-run

This will show you what would happen without making any changes.

Commit Message Convention

Follow Conventional Commits for automatic versioning.

Troubleshooting

Authentication Issues:

# Login to npm
npm login

# Verify authentication
npm whoami

Git Issues:

# Ensure working directory is clean
git status

# Ensure you're on main branch
git checkout main

# Pull latest changes
git pull origin main

Dry Run First:

# Always test first
npm run release -- --dry-run

This will show you exactly what will happen without making any changes.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Development Setup

# Clone the repository
git clone https://github.com/mayademcom/nestjs-hasura.git
cd nestjs-hasura

# Install dependencies
npm install

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:cov

# Build the package
npm run build

# Lint code
npm run lint

Running Tests

# All tests
npm test

# Unit tests only
npm run test:unit

# Integration tests only
npm run test:integration

# Watch mode
npm run test:watch

# Coverage report
npm run test:cov

License

MIT © Mayadem

Support

• 📫 Issues
• 📖 Documentation

Changelog

See CHANGELOG.md for release history.

---

Made with ❤️ by Mayadem