AWS.AppSync reference

ApiAssociationResource

Source: src/AWS/AppSync/ApiAssociation.ts

Associates a GraphQL API with a custom DomainName (existence-only resource — a domain serves exactly one API).

ApiAssociationResource: Associating an API

yield* AppSync.ApiAssociation("Assoc", { domain, api });

ApiKeyResource

Source: src/AWS/AppSync/ApiKey.ts

An AppSync API key for API_KEY-authenticated GraphQL APIs.

The key’s id attribute is the secret value (da2-…) sent in the x-api-key request header. It is wrapped in Redacted; unwrap with Redacted.value(key.id) where the raw header value is needed.

ApiKeyResource: Creating API Keys

Key with the default 7-day expiry

const key = yield* AppSync.ApiKey("Key", { api });
// Redacted.value(key.id) → "da2-…" — send as the x-api-key header

Key with a managed expiry

const key = yield* AppSync.ApiKey("Key", {
  api,
  description: "mobile clients",
  expires: 1893456000, // rounded down to the hour by AWS
});

DataSourceResource

Source: src/AWS/AppSync/DataSource.ts

An AppSync data source — the target a resolver reads from or writes to.

For AWS_LAMBDA and AMAZON_DYNAMODB targets a least-privilege service role is created automatically (unless an explicit serviceRoleArn is given): lambda:InvokeFunction on the function, or the DynamoDB read/write actions on the table and its indexes.

DataSourceResource: Creating Data Sources

Lambda data source (auto-created invoke role)

const ds = yield* AppSync.DataSource("LambdaDS", {
  api,
  type: "AWS_LAMBDA",
  lambdaConfig: { lambdaFunctionArn: fn.functionArn },
});

NONE data source (local compute)

const local = yield* AppSync.DataSource("Local", {
  api,
  type: "NONE",
});

DynamoDB data source

const ds = yield* AppSync.DataSource("TableDS", {
  api,
  type: "AMAZON_DYNAMODB",
  dynamodbConfig: { tableName: table.tableName },
});

DomainName

Source: src/AWS/AppSync/DomainName.ts

A custom domain name for AppSync GraphQL APIs.

Requires an ACM certificate in us-east-1 (the domain is CloudFront-backed). Attach an API with ApiAssociation and point DNS at the appsyncDomainName attribute.

DomainName: Creating Custom Domains

const domain = yield* AppSync.DomainName("Domain", {
  domainName: "api.example.com",
  certificateArn: usEast1Cert.certificateArn,
});
yield* AppSync.ApiAssociation("Assoc", { domain, api });
// CNAME api.example.com → domain.appsyncDomainName

EvaluateCode

Source: src/AWS/AppSync/EvaluateCode.ts

Runtime binding for appsync:EvaluateCode — evaluate APPSYNC_JS resolver/function code against a mock context without touching a deployed resolver. Useful for CI/tooling functions that validate resolver code before it ships.

An account-level operation: the binding takes no resource. GraphQL evaluation errors do not fail the effect — they surface on the response’s error field. Provide AppSync.EvaluateCodeHttp on the hosting function’s Effect to implement the binding.

EvaluateCode: Evaluating Resolver Code

// init — account-level binding takes no resource
const evaluateCode = yield* AppSync.EvaluateCode();

// runtime
const result = yield* evaluateCode({
  runtime: AppSync.APPSYNC_JS,
  code: `
    export function request(ctx) { return { payload: ctx.args.a + ctx.args.b }; }
    export function response(ctx) { return ctx.result; }
  `,
  context: JSON.stringify({ arguments: { a: 2, b: 3 } }),
  function: "request",
});
// JSON.parse(result.evaluationResult!) → { payload: 5 }

EvaluateMappingTemplate

Source: src/AWS/AppSync/EvaluateMappingTemplate.ts

Runtime binding for appsync:EvaluateMappingTemplate — evaluate a VTL request/response mapping template against a mock context without touching a deployed resolver. The VTL twin of EvaluateCode, for resolvers defined with requestMappingTemplate/responseMappingTemplate instead of APPSYNC_JS code.

An account-level operation: the binding takes no resource. Template evaluation errors do not fail the effect — they surface on the response’s error field. Provide AppSync.EvaluateMappingTemplateHttp on the hosting function’s Effect to implement the binding.

EvaluateMappingTemplate: Evaluating Mapping Templates

// init — account-level binding takes no resource
const evaluateTemplate = yield* AppSync.EvaluateMappingTemplate();

// runtime
const result = yield* evaluateTemplate({
  template: `{ "sum": $util.toJson($ctx.args.a + $ctx.args.b) }`,
  context: JSON.stringify({ arguments: { a: 2, b: 3 } }),
});
// JSON.parse(result.evaluationResult!) → { sum: 5 }

FlushApiCache

Source: src/AWS/AppSync/FlushApiCache.ts

Runtime binding for appsync:FlushApiCache — flush a GraphqlApi’s server-side cache from a Lambda (or other AWS runtime), e.g. after writing to the underlying data store out of band.

Fails with the typed NotFoundException when the API has no cache provisioned. Provide AppSync.FlushApiCacheHttp on the hosting function’s Effect to implement the binding.

FlushApiCache: Flushing the API Cache

const flushCache = yield* AppSync.FlushApiCache(api);

yield* flushCache().pipe(
  // no cache provisioned — nothing to flush
  Effect.catchTag("NotFoundException", () => Effect.void),
);

FunctionResource

Source: src/AWS/AppSync/Function.ts

An AppSync pipeline function — a reusable step composed by PIPELINE resolvers.

FunctionResource: Creating Pipeline Functions

const step = yield* AppSync.Function("InvokeStep", {
  api,
  dataSource: lambdaDS,
  code: `
    export function request(ctx) {
      return { operation: "Invoke", payload: { args: ctx.args } };
    }
    export function response(ctx) {
      return ctx.result;
    }
  `,
});
// reference from a PIPELINE resolver:
// pipelineFunctionIds: [step.functionId]

GetIntrospectionSchema

Source: src/AWS/AppSync/GetIntrospectionSchema.ts

Runtime binding for appsync:GetIntrospectionSchema — read a GraphqlApi’s live schema (SDL or introspection JSON) from a Lambda (or other AWS runtime), e.g. for schema registries, codegen services, or federation gateways that discover the schema at runtime.

The response schema is a streaming body — collect it with Stream.mkString(Stream.decodeText(response.schema!)). Provide AppSync.GetIntrospectionSchemaHttp on the hosting function’s Effect to implement the binding.

GetIntrospectionSchema: Reading the Schema

const getSchema = yield* AppSync.GetIntrospectionSchema(api);

const response = yield* getSchema({ format: "SDL" });
const sdl = yield* Stream.mkString(Stream.decodeText(response.schema!));

GraphQL

Source: src/AWS/AppSync/GraphQL.ts

Runtime binding for the appsync:GraphQL data-plane action — execute GraphQL operations against a GraphqlApi’s endpoint from a Lambda (or other AWS runtime), SigV4-signed with the host Function’s IAM role.

The API must accept AWS_IAM authentication (as its primary mode or an additional provider). Provide AppSync.GraphQLHttp on the hosting function’s Effect to implement the binding.

GraphQL: Executing GraphQL Operations

const api = yield* AppSync.GraphqlApi("Api", {
  authenticationType: "AWS_IAM",
  schema,
});
const graphql = yield* AppSync.GraphQL(api);

const result = yield* graphql.execute<{ add: number }>({
  query: "query($a: Int!, $b: Int!) { add(a: $a, b: $b) }",
  variables: { a: 2, b: 3 },
});
// result.data?.add === 5; field errors appear on result.errors

GraphqlApi

Source: src/AWS/AppSync/GraphqlApi.ts

An AWS AppSync GraphQL API.

Owns the API, its SDL schema (applied via startSchemaCreation and awaited until active), its authentication modes, and an optional server-side cache. Pair with DataSource, Resolver, and ApiKey to serve GraphQL over Lambda or DynamoDB.

GraphqlApi: Creating a GraphQL API

import * as AppSync from "alchemy/AWS/AppSync";

const api = yield* AppSync.GraphqlApi("Api", {
  schema: `
    type Query { hello: String! }
    schema { query: Query }
  `,
});
const key = yield* AppSync.ApiKey("Key", { api });

GraphqlApi: Authentication Modes

Lambda authorizer

const api = yield* AppSync.GraphqlApi("Api", {
  authenticationType: "AWS_LAMBDA",
  lambdaAuthorizerConfig: { authorizerUri: authorizer.functionArn },
  schema,
});
// AppSync must be allowed to invoke the authorizer:
yield* AWS.Lambda.Permission("AppSyncInvoke", {
  functionName: authorizer.functionName,
  principal: "appsync.amazonaws.com",
  action: "lambda:InvokeFunction",
  sourceArn: api.apiArn,
});

Cognito user pools as an additional auth mode

const api = yield* AppSync.GraphqlApi("Api", {
  authenticationType: "API_KEY",
  additionalAuthenticationProviders: [
    {
      authenticationType: "AMAZON_COGNITO_USER_POOLS",
      userPoolConfig: { userPoolId: pool.userPoolId },
    },
  ],
  schema,
});

GraphqlApi: Caching

const api = yield* AppSync.GraphqlApi("Api", {
  schema,
  cache: { type: "SMALL", behavior: "FULL_REQUEST_CACHING", ttl: "60 seconds" },
});

GraphqlApi: Environment Variables

const api = yield* AppSync.GraphqlApi("Api", {
  schema,
  environmentVariables: { STAGE: "prod" },
});
// in APPSYNC_JS resolver code:
//   export function response(ctx) { return ctx.env.STAGE; }

ResolverResource

Source: src/AWS/AppSync/Resolver.ts

An AppSync resolver — attaches request/response logic to a schema field.

UNIT resolvers target a single data source; PIPELINE resolvers run a sequence of Functions. The modern default is APPSYNC_JS code (a module exporting request(ctx) / response(ctx)); VTL mapping templates remain supported.

ResolverResource: Unit Resolvers

const resolver = yield* AppSync.Resolver("AddResolver", {
  api,
  typeName: "Query",
  fieldName: "add",
  dataSource: lambdaDS,
  code: `
    export function request(ctx) {
      return { operation: "Invoke", payload: { args: ctx.args } };
    }
    export function response(ctx) {
      return ctx.result;
    }
  `,
});

ResolverResource: Pipeline Resolvers

const fn = yield* AppSync.Function("Step", {
  api,
  dataSource: lambdaDS,
  code: fnCode,
});
const resolver = yield* AppSync.Resolver("PipelineResolver", {
  api,
  typeName: "Query",
  fieldName: "double",
  kind: "PIPELINE",
  pipelineFunctionIds: [fn.functionId],
  code: `
    export function request(ctx) { return {}; }
    export function response(ctx) { return ctx.prev.result; }
  `,
});