Class AppSyncEventsResolver

Resolver for AWS AppSync Events APIs.

This resolver is designed to handle the onPublish and onSubscribe events from AWS AppSync Events APIs. It allows you to register handlers for these events and route them to the appropriate functions based on the event's path.

Example

import { AppSyncEventsResolver } from '@aws-lambda-powertools/event-handler/appsync-events';

const app = new AppSyncEventsResolver();

app.onPublish('/foo', async (payload) => {
  // your business logic here
  return payload;
});

export const handler = async (event, context) =>
  app.resolve(event, context);

Hierarchy (View Summary)

Router
- AppSyncEventsResolver

Index

Constructors

constructor

new AppSyncEventsResolver(options?: RouterOptions): AppSyncEventsResolver
Parameters
- Optionaloptions: RouterOptions
Returns AppSyncEventsResolver
Inherited from Router.constructor
- Defined in event-handler/src/appsync-events/Router.ts:39

Properties

`Protected` `Readonly`envService

envService: EnvironmentVariablesService

The environment variables service instance.

`Protected` `Readonly`isDev

isDev: boolean = false

Whether the router is running in development mode.

`Protected` `Readonly`logger

logger: Pick<GenericLogger, "debug" | "warn" | "error">

A logger instance to be used for logging debug, warning, and error messages.

When no logger is provided, we'll only log warnings and errors using the global console object.

`Protected` `Readonly`onPublishRegistry

onPublishRegistry: RouteHandlerRegistry

A map of registered routes for the onPublish event, keyed by their paths.

`Protected` `Readonly`onSubscribeRegistry

onSubscribeRegistry: RouteHandlerRegistry

A map of registered routes for the onSubscribe event, keyed by their paths.

Methods

`Protected`handleOnPublish

handleOnPublish(
    event: AppSyncEventsPublishEvent,
    context: Context,
    options?: ResolveOptions,
): Promise<{ error: string } | { events: unknown[] }>
Handle the onPublish event.
Parameters
- event: AppSyncEventsPublishEvent
  The incoming event from AppSync Events
- context: Context
  The context object provided by AWS Lambda
- Optionaloptions: ResolveOptions
  Optional resolve options
Returns Promise<{ error: string } | { events: unknown[] }>
- Defined in event-handler/src/appsync-events/AppSyncEventsResolver.ts:113

`Protected`handleOnSubscribe

handleOnSubscribe(
    event: AppSyncEventsSubscribeEvent,
    context: Context,
    options?: ResolveOptions,
): Promise<undefined | null | { error: string }>
Handle the onSubscribe event.

After resolving the correct handler, we call it with the event and context. If the handler throws an error, we catch it and format the error response for a friendly output to the client.
Parameters
- event: AppSyncEventsSubscribeEvent
  The incoming event from AppSync Events
- context: Context
  The context object provided by AWS Lambda
- Optionaloptions: ResolveOptions
  Optional resolve options
Returns Promise<undefined | null | { error: string }>
- Defined in event-handler/src/appsync-events/AppSyncEventsResolver.ts:174

onPublish

onPublish<T extends boolean = false>(
    path: string,
    handler: OnPublishHandler<T>,
    options?: RouteOptions<T>,
): void
Register a handler function for the onPublish event.

When setting a handler, the path must be a string with a namespace starting with /, for example /default/*. A path can have multiple namespaces, all separated by /, for example /default/foo/bar. Wildcards are allowed only at the end of the path, for example /default/* or /default/foo/*.
Type Parameters
- T extends boolean = false
Parameters
- path: string
  The path of the event to be registered, i.e. /namespace/channel
- handler: OnPublishHandler<T>
  The handler function to be called when the event is received
- Optionaloptions: RouteOptions<T>
  The options for the route handler
  
  Options for registering a route
  - Optionalaggregate?: T
    Whether the resolver will send all the events to the resolver at once or one by one
    
    Default
    false
Returns void
Example
```
import { AppSyncEventsResolver } from '@aws-lambda-powertools/event-handler/appsync-events';

const app = new AppSyncEventsResolver();

app.onPublish('/foo', async (payload) => {
  // your business logic here
  return payload;
});

export const handler = async (event, context) =>
  app.resolve(event, context);
```
By default, the handler will be called for each event message received by the AWS Lambda function. For example, if you receive 10 events, the handler will be called 10 times in parallel. When the handler is called, the first parameter is the message payload, which is an object containing the message payload sent by the publisher, for example:
Example
```
{
  "foo": "bar",
}
```
If your function throws an error, we catch it and format the error response for a friendly output to the client corresponding to the event that caused the error. In this case, that specific event will be dropped, but the other events will still be processed.

Process all events at once

If you want to receive all the events at once, you can set the aggregate option to true. In this case, the handler will be called only once with an array of events and you are responsible for handling the events in your function and returning a list of events to be sent back to AWS AppSync.
Example
```
import { AppSyncEventsResolver } from '@aws-lambda-powertools/event-handler/appsync-events';

const app = new AppSyncEventsResolver();

app.onPublish('/foo', async (payload) => {
  // your business logic here
  return payload;
}, {
  aggregate: true,
});

export const handler = async (event, context) =>
  app.resolve(event, context);
```
When the handler is called, the first parameter is an array of messages, which is an array of objects containing the message payload sent by the publisher and their id, while the second and third parameters are optional and are the original Lambda function event and context. Below is an example of the first parameter:
Example
```
[
  {
    "id": "123456",
    "payload": {
      "foo": "bar",
    }
  },
  {
    "id": "654321",
    "payload": {
    }
  }
]
```
When working with aggregate enabled, if your function throws an error, we catch it and format the error response to be sent back to AppSync. This helps the client to understand what went wrong and handle the error accordingly.

It's important to note that if your function throws an error, the entire batch of events will be dropped.

The method works also as class method decorator, so you can use it like this:
Example
```
import { AppSyncEventsResolver } from '@aws-lambda-powertools/event-handler/appsync-events';

const app = new AppSyncEventsResolver();

class Lambda {
  ⁣@app.onPublish('/foo')
  async handleFoo(payload) {
    // your business logic here
    return payload;
  }

  async handler(event, context) {
    return app.resolve(event, context);
  }
}

const lambda = new Lambda();
export const handler = lambda.handler.bind(lambda);
```
Inherited from Router.onPublish
- Defined in event-handler/src/appsync-events/Router.ts:174
onPublish<T extends boolean = false>(
path: string,
options?: RouteOptions<T>,
): MethodDecorator
Register a handler function for the onPublish event.

When setting a handler, the path must be a string with a namespace starting with /, for example /default/*. A path can have multiple namespaces, all separated by /, for example /default/foo/bar. Wildcards are allowed only at the end of the path, for example /default/* or /default/foo/*.
Type Parameters
- T extends boolean = false
Parameters
- path: string
  The path of the event to be registered, i.e. /namespace/channel
- Optionaloptions: RouteOptions<T>
  The options for the route handler
  
  Options for registering a route
  - Optionalaggregate?: T
    Whether the resolver will send all the events to the resolver at once or one by one
    
    Default
    false
Returns MethodDecorator
Example
```
import { AppSyncEventsResolver } from '@aws-lambda-powertools/event-handler/appsync-events';

const app = new AppSyncEventsResolver();

app.onPublish('/foo', async (payload) => {
  // your business logic here
  return payload;
});

export const handler = async (event, context) =>
  app.resolve(event, context);
```
By default, the handler will be called for each event message received by the AWS Lambda function. For example, if you receive 10 events, the handler will be called 10 times in parallel. When the handler is called, the first parameter is the message payload, which is an object containing the message payload sent by the publisher, for example:
Example
```
{
  "foo": "bar",
}
```
If your function throws an error, we catch it and format the error response for a friendly output to the client corresponding to the event that caused the error. In this case, that specific event will be dropped, but the other events will still be processed.

Process all events at once

If you want to receive all the events at once, you can set the aggregate option to true. In this case, the handler will be called only once with an array of events and you are responsible for handling the events in your function and returning a list of events to be sent back to AWS AppSync.
Example
```
import { AppSyncEventsResolver } from '@aws-lambda-powertools/event-handler/appsync-events';

const app = new AppSyncEventsResolver();

app.onPublish('/foo', async (payload) => {
  // your business logic here
  return payload;
}, {
  aggregate: true,
});

export const handler = async (event, context) =>
  app.resolve(event, context);
```
When the handler is called, the first parameter is an array of messages, which is an array of objects containing the message payload sent by the publisher and their id, while the second and third parameters are optional and are the original Lambda function event and context. Below is an example of the first parameter:
Example
```
[
  {
    "id": "123456",
    "payload": {
      "foo": "bar",
    }
  },
  {
    "id": "654321",
    "payload": {
    }
  }
]
```
When working with aggregate enabled, if your function throws an error, we catch it and format the error response to be sent back to AppSync. This helps the client to understand what went wrong and handle the error accordingly.

It's important to note that if your function throws an error, the entire batch of events will be dropped.

The method works also as class method decorator, so you can use it like this:
Example
```
import { AppSyncEventsResolver } from '@aws-lambda-powertools/event-handler/appsync-events';

const app = new AppSyncEventsResolver();

class Lambda {
  ⁣@app.onPublish('/foo')
  async handleFoo(payload) {
    // your business logic here
    return payload;
  }

  async handler(event, context) {
    return app.resolve(event, context);
  }
}

const lambda = new Lambda();
export const handler = lambda.handler.bind(lambda);
```
Inherited from Router.onPublish
- Defined in event-handler/src/appsync-events/Router.ts:179

onSubscribe

onSubscribe(path: string, handler: OnSubscribeHandler): void
Register a handler function for the onSubscribe event.

When setting a handler, the path must be a string with a namespace starting with /, for example /default/*. A path can have multiple namespaces, all separated by /, for example /default/foo/bar. Wildcards are allowed only at the end of the path, for example /default/* or /default/foo/*.
Parameters
- path: string
  The path of the event to be registered, i.e. /namespace/channel
- handler: OnSubscribeHandler
  The handler function to be called when the event is received
Returns void
Example
```
import { AppSyncEventsResolver } from '@aws-lambda-powertools/event-handler/appsync-events';

const app = new AppSyncEventsResolver();

app.onSubscribe('/foo', async (event) => {
  // your business logic here
});

export const handler = async (event, context) =>
  app.resolve(event, context);
```
The first parameter of the handler function is the original AWS AppSync event and the second parameter is the AWS Lambda context.

If your function throws an error, we catch it and format the error response to be sent back to AppSync. This helps the client to understand what went wrong and handle the error accordingly, however it still prevents the subscription from being established.

The method works also as class method decorator, so you can use it like this:
Example
```
import { AppSyncEventsResolver } from '@aws-lambda-powertools/event-handler/appsync-events';

const app = new AppSyncEventsResolver();

class Lambda {
  ⁣@app.onSubscribe('/foo')
  async handleFoo(event) {
    // your business logic here
  }

  async handler(event, context) {
    return app.resolve(event, context);
  }
}

const lambda = new Lambda();
export const handler = lambda.handler.bind(lambda);
```
Inherited from Router.onSubscribe
- Defined in event-handler/src/appsync-events/Router.ts:262
onSubscribe(path: string): MethodDecorator
Register a handler function for the onSubscribe event.

When setting a handler, the path must be a string with a namespace starting with /, for example /default/*. A path can have multiple namespaces, all separated by /, for example /default/foo/bar. Wildcards are allowed only at the end of the path, for example /default/* or /default/foo/*.
Parameters
- path: string
  The path of the event to be registered, i.e. /namespace/channel
Returns MethodDecorator
Example
```
import { AppSyncEventsResolver } from '@aws-lambda-powertools/event-handler/appsync-events';

const app = new AppSyncEventsResolver();

app.onSubscribe('/foo', async (event) => {
  // your business logic here
});

export const handler = async (event, context) =>
  app.resolve(event, context);
```
The first parameter of the handler function is the original AWS AppSync event and the second parameter is the AWS Lambda context.

If your function throws an error, we catch it and format the error response to be sent back to AppSync. This helps the client to understand what went wrong and handle the error accordingly, however it still prevents the subscription from being established.

The method works also as class method decorator, so you can use it like this:
Example
```
import { AppSyncEventsResolver } from '@aws-lambda-powertools/event-handler/appsync-events';

const app = new AppSyncEventsResolver();

class Lambda {
  ⁣@app.onSubscribe('/foo')
  async handleFoo(event) {
    // your business logic here
  }

  async handler(event, context) {
    return app.resolve(event, context);
  }
}

const lambda = new Lambda();
export const handler = lambda.handler.bind(lambda);
```
Inherited from Router.onSubscribe
- Defined in event-handler/src/appsync-events/Router.ts:263

resolve

resolve(
    event: unknown,
    context: Context,
    options?: ResolveOptions,
): Promise<undefined | null | { error: string } | { events: unknown[] }>

Resolve the response based on the provided event and route handlers configured.

Parameters

event: unknown
The incoming event from AppSync Events
context: Context
The context object provided by AWS Lambda
Optionaloptions: ResolveOptions

Returns Promise<undefined | null | { error: string } | { events: unknown[] }>

Example

import { AppSyncEventsResolver } from '@aws-lambda-powertools/event-handler/appsync-events';

const app = new AppSyncEventsResolver();

app.onPublish('/foo', async (payload) => {
  // your business logic here
  return payload;
});

export const handler = async (event, context) =>
  app.resolve(event, context);

The method works also as class method decorator, so you can use it like this:

Example

import { AppSyncEventsResolver } from '@aws-lambda-powertools/event-handler/appsync-events';

const app = new AppSyncEventsResolver();

class Lambda {
  ⁣@app.onPublish('/foo')
  async handleFoo(payload) {
    // your business logic here
    return payload;
  }

  async handler(event, context) {
    return app.resolve(event, context, {
      scope: this, // bind decorated methods to the class instance
    });
  }
}

const lambda = new Lambda();
export const handler = lambda.handler.bind(lambda);

Class AppSyncEventsResolver

Example

Hierarchy (View Summary)

Index

Constructors

Properties

Methods

Constructors

constructor

Parameters

Returns AppSyncEventsResolver

Properties

Protected ReadonlyenvService

Protected ReadonlyisDev

Protected Readonlylogger

Protected ReadonlyonPublishRegistry

Protected ReadonlyonSubscribeRegistry

Methods

ProtectedhandleOnPublish

Parameters

Returns Promise<{ error: string } | { events: unknown[] }>

ProtectedhandleOnSubscribe

Parameters

Returns Promise<undefined | null | { error: string }>

onPublish

Type Parameters

Parameters

Optionalaggregate?: T

Default

Returns void

Example

Example

Example

Example

Example

Type Parameters

Parameters

Optionalaggregate?: T

Default

Returns MethodDecorator

Example

Example

Example

Example

Example

onSubscribe

Parameters

Returns void

Example

Example

Parameters

Returns MethodDecorator

Example

Example

resolve

Parameters

Returns Promise<undefined | null | { error: string } | { events: unknown[] }>

Example

Example

Settings

On This Page

`Protected` `Readonly`envService

`Protected` `Readonly`isDev

`Protected` `Readonly`logger

`Protected` `Readonly`onPublishRegistry

`Protected` `Readonly`onSubscribeRegistry

`Protected`handleOnPublish

`Protected`handleOnSubscribe

`Optional`aggregate?: T

`Optional`aggregate?: T