@ttoss/appsync-api 0.22.14 → 0.23.0

package/README.md

@@ -69,6 +69,58 @@ The `createAppSyncResolverHandler` function adds the `context` object to the res
 - `request` - AppSync request object (see [Request section](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-context-reference-js.html)).
 - `identity` - AppSync identity object (see [Identity section](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-context-reference-js.html)).
 
+### createContext
+
+Use `createContext` to enrich the resolver context once per request. Its return value is shallow-merged into the base context, making it available to every resolver. This is the recommended way to resolve per-request values like a `userId` from Cognito:
+
+```ts
+import { createAppSyncResolverHandler } from '@ttoss/appsync-api';
+import { schemaComposer } from './schemaComposer';
+import { getUserIdFromCognitoSub } from './auth';
+
+export const handler = createAppSyncResolverHandler({
+  schemaComposer,
+  createContext: async ({ identity }) => ({
+    userId: await getUserIdFromCognitoSub(identity?.sub),
+  }),
+});
+```
+
+Every resolver then receives `context.userId` without having to derive it individually.
+
+### Middlewares
+
+You can use [`graphql-middleware`](https://github.com/dimatill/graphql-middleware)-compatible middlewares via the `middlewares` option. Each middleware wraps the resolver — code before `resolve()` runs **before** the resolver, code after runs **after**.
+
+In AppSync, each Lambda invocation handles a single field, so a middleware runs exactly once per request.
+Use `middlewares` for authorization rules or cross-cutting logic (logging, tracing). Combine with `createContext` for per-request context enrichment:
+
+|                     | `createContext`                                            | `middlewares`                                                      |
+| ------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------ |
+| Runs                | Once per request                                           | Once per resolver call                                             |
+| Purpose             | Enrich context (e.g. `userId`)                             | Auth rules, logging, before/after logic                            |
+| Can block execution | On error (request fails if `createContext` rejects/throws) | Yes (can conditionally block by not calling `resolve` or throwing) |
+
+#### Authorization with GraphQL Shield
+
+Use [GraphQL Shield](https://the-guild.dev/graphql/shield) to add authorization rules:
+
+```ts
+import { allow, deny, shield } from '@ttoss/graphql-api/shield';
+
+const permissions = shield(
+  {
+    Query: { '*': deny, me: allow },
+  },
+  { fallbackRule: deny }
+);
+
+export const handler = createAppSyncResolverHandler({
+  schemaComposer,
+  middlewares: [permissions],
+});
+```
+
 ### Custom domain name
 
 You can add a custom domain name to your API using the `customDomain` option.

package/dist/esm/index.js

@@ -15,19 +15,19 @@ var AppSyncGraphQLApiKeyLogicalId = "AppSyncGraphQLApiKey";
 var createApiTemplate = /* @__PURE__ */__name(({
   additionalAuthenticationProviders,
   authenticationType = "AMAZON_COGNITO_USER_POOLS",
-  schemaComposer,
+  schemaComposer: schemaComposer2,
   dataSource,
   lambdaFunction,
   userPoolConfig,
   customDomain
 }) => {
-  const sdlWithoutComments = schemaComposer.toSDL({
+  const sdlWithoutComments = schemaComposer2.toSDL({
     commentDescriptions: false,
     omitDescriptions: true,
     omitScalars: true
   });
-  graphql.validateSchema(schemaComposer.buildSchema());
-  const resolveMethods = schemaComposer.getResolveMethods();
+  graphql.validateSchema(schemaComposer2.buildSchema());
+  const resolveMethods = schemaComposer2.getResolveMethods();
   const resolveMethodsEntries = Object.entries(resolveMethods).flatMap(([typeName, fieldResolvers]) => {
     return Object.entries(fieldResolvers).map(([fieldName, resolver]) => {
       if (typeof resolver !== "function") {
@@ -100,12 +100,15 @@ var createApiTemplate = /* @__PURE__ */__name(({
           Layers: lambdaFunction.layers,
           MemorySize: 512,
           Role: lambdaFunction.roleArn,
-          Runtime: "nodejs22.x",
+          /**
+          * https://docs.aws.amazon.com/lambda/latest/dg/lambda-runtimes.html#runtimes-supported
+          */
+          Runtime: "nodejs24.x",
           /**
           * https://docs.aws.amazon.com/general/latest/gr/appsync.html
           * Request execution time for mutations, queries, and subscriptions: 30 seconds
           */
-          Timeout: 29
+          Timeout: 30
         }
       },
       [AppSyncLambdaFunctionAppSyncDataSourceLogicalId]: {
@@ -281,11 +284,12 @@ var createApiTemplate = /* @__PURE__ */__name(({
 // src/createAppSyncResolverHandler.ts
 import { buildSchema } from "@ttoss/graphql-api";
 var createAppSyncResolverHandler = /* @__PURE__ */__name(({
+  createContext,
   ...buildSchemaInput
 }) => {
   return async (event, appSyncHandlerContext) => {
     const {
-      schemaComposer
+      schemaComposer: schemaComposer2
     } = buildSchemaInput;
     const {
       info,
@@ -297,11 +301,15 @@ var createAppSyncResolverHandler = /* @__PURE__ */__name(({
       parentTypeName,
       fieldName
     } = info;
-    const context = {
+    const baseContext = {
       handler: appSyncHandlerContext,
       request,
       identity: event.identity
     };
+    const context = createContext ? {
+      ...baseContext,
+      ...(await createContext(baseContext))
+    } : baseContext;
     const schema = buildSchema(buildSchemaInput);
     const parentType = schema.getType(parentTypeName);
     if (!parentType) {
@@ -314,7 +322,7 @@ var createAppSyncResolverHandler = /* @__PURE__ */__name(({
     }
     const argsWithEnumValues = (() => {
       const fieldsArgsIsEnumType = field.args.filter(arg => {
-        return schemaComposer.isEnumType(arg.type);
+        return schemaComposer2.isEnumType(arg.type);
       });
       const enumArgs = fieldsArgsIsEnumType.map(enumArg => {
         if (!args[enumArg.name]) {
@@ -322,7 +330,7 @@ var createAppSyncResolverHandler = /* @__PURE__ */__name(({
             [enumArg.name]: enumArg.defaultValue
           };
         }
-        const values = schemaComposer.getETC(enumArg.type).getFields();
+        const values = schemaComposer2.getETC(enumArg.type).getFields();
         return {
           [enumArg.name]: values[args[enumArg.name]].value
         };
@@ -344,4 +352,16 @@ var createAppSyncResolverHandler = /* @__PURE__ */__name(({
     return response;
   };
 }, "createAppSyncResolverHandler");
-export { createApiTemplate, createAppSyncResolverHandler };
+
+// src/scalars.ts
+import { schemaComposer } from "@ttoss/graphql-api";
+var AWSJSONTC = schemaComposer.createScalarTC(`scalar AWSJSON`);
+var AWSDateTimeTC = schemaComposer.createScalarTC(`scalar AWSDateTime`);
+var AWSDateTC = schemaComposer.createScalarTC(`scalar AWSDate`);
+var AWSTimeTC = schemaComposer.createScalarTC(`scalar AWSTime`);
+var AWSTimestampTC = schemaComposer.createScalarTC(`scalar AWSTimestamp`);
+var AWSEmailTC = schemaComposer.createScalarTC(`scalar AWSEmail`);
+var AWSURLTC = schemaComposer.createScalarTC(`scalar AWSURL`);
+var AWSPhoneTC = schemaComposer.createScalarTC(`scalar AWSPhone`);
+var AWSIPAddressTC = schemaComposer.createScalarTC(`scalar AWSIPAddress`);
+export { AWSDateTC, AWSDateTimeTC, AWSEmailTC, AWSIPAddressTC, AWSJSONTC, AWSPhoneTC, AWSTimeTC, AWSTimestampTC, AWSURLTC, createApiTemplate, createAppSyncResolverHandler };

package/dist/index.d.mts

@@ -1,5 +1,6 @@
+import * as _ttoss_graphql_api from '@ttoss/graphql-api';
 import { SchemaComposer, BuildSchemaInput } from '@ttoss/graphql-api';
-import { AppSyncResolverHandler as AppSyncResolverHandler$1 } from 'aws-lambda';
+import { AppSyncResolverHandler as AppSyncResolverHandler$1, Context, AppSyncIdentity } from 'aws-lambda';
 export { AppSyncIdentityCognito } from 'aws-lambda';
 
 type CloudFormationRef = {
@@ -109,6 +110,56 @@ declare const createApiTemplate: ({ additionalAuthenticationProviders, authentic
 }) => CloudFormationTemplate;
 
 type AppSyncResolverHandler<TArguments, TResult, TSource = Record<string, any> | null> = AppSyncResolverHandler$1<TArguments, TResult, TSource>;
-declare const createAppSyncResolverHandler: ({ ...buildSchemaInput }: BuildSchemaInput) => AppSyncResolverHandler<any, any, any>;
+/**
+ * The base context object passed to all AppSync resolvers.
+ */
+type BaseAppSyncContext = {
+    /** The raw Lambda invocation context. */
+    handler: Context;
+    /** The AppSync request object (includes headers). */
+    request: any;
+    /** The caller's identity (Cognito, IAM, Lambda, or OIDC). Null when using API key auth. */
+    identity: AppSyncIdentity | null | undefined;
+};
+declare const createAppSyncResolverHandler: ({ createContext, ...buildSchemaInput }: BuildSchemaInput & {
+    /**
+     * Optional async function called once per request to enrich the resolver
+     * context. The returned object is shallow-merged into the base context and
+     * made available to every resolver.
+     *
+     * Use this for per-request setup such as resolving a `userId` from Cognito.
+     * For authorization rules or before/after resolver logic, prefer `middlewares`.
+     *
+     * @example
+     * ```ts
+     * createAppSyncResolverHandler({
+     *   schemaComposer,
+     *   createContext: async ({ identity }) => ({
+     *     userId: await getUserIdFromCognitoSub(identity?.sub),
+     *   }),
+     * });
+     * ```
+     */
+    createContext?: (baseContext: BaseAppSyncContext) => Promise<Record<string, any>> | Record<string, any>;
+}) => AppSyncResolverHandler<any, any, any>;
+
+/** AWS AppSync scalar for JSON data. Represents a JSON object or array. */
+declare const AWSJSONTC: _ttoss_graphql_api.ScalarTypeComposer<any>;
+/** AWS AppSync scalar for combined date and time values (ISO 8601, e.g. `2007-04-05T14:30:28Z`). */
+declare const AWSDateTimeTC: _ttoss_graphql_api.ScalarTypeComposer<any>;
+/** AWS AppSync scalar for date values (ISO 8601, e.g. `1970-01-01`). */
+declare const AWSDateTC: _ttoss_graphql_api.ScalarTypeComposer<any>;
+/** AWS AppSync scalar for time values (ISO 8601, e.g. `12:30:00.000Z`). */
+declare const AWSTimeTC: _ttoss_graphql_api.ScalarTypeComposer<any>;
+/** AWS AppSync scalar for Unix epoch timestamps (integer, seconds since 1970-01-01T00:00:00Z). */
+declare const AWSTimestampTC: _ttoss_graphql_api.ScalarTypeComposer<any>;
+/** AWS AppSync scalar for email addresses (RFC 822). */
+declare const AWSEmailTC: _ttoss_graphql_api.ScalarTypeComposer<any>;
+/** AWS AppSync scalar for URLs (RFC 1738). */
+declare const AWSURLTC: _ttoss_graphql_api.ScalarTypeComposer<any>;
+/** AWS AppSync scalar for phone numbers (E.164 format). */
+declare const AWSPhoneTC: _ttoss_graphql_api.ScalarTypeComposer<any>;
+/** AWS AppSync scalar for IPv4 and IPv6 addresses. */
+declare const AWSIPAddressTC: _ttoss_graphql_api.ScalarTypeComposer<any>;
 
-export { type AppSyncResolverHandler, createApiTemplate, createAppSyncResolverHandler };
+export { AWSDateTC, AWSDateTimeTC, AWSEmailTC, AWSIPAddressTC, AWSJSONTC, AWSPhoneTC, AWSTimeTC, AWSTimestampTC, AWSURLTC, type AppSyncResolverHandler, type BaseAppSyncContext, createApiTemplate, createAppSyncResolverHandler };

package/dist/index.d.ts

@@ -1,5 +1,6 @@
+import * as _ttoss_graphql_api from '@ttoss/graphql-api';
 import { SchemaComposer, BuildSchemaInput } from '@ttoss/graphql-api';
-import { AppSyncResolverHandler as AppSyncResolverHandler$1 } from 'aws-lambda';
+import { AppSyncResolverHandler as AppSyncResolverHandler$1, Context, AppSyncIdentity } from 'aws-lambda';
 export { AppSyncIdentityCognito } from 'aws-lambda';
 
 type CloudFormationRef = {
@@ -109,6 +110,56 @@ declare const createApiTemplate: ({ additionalAuthenticationProviders, authentic
 }) => CloudFormationTemplate;
 
 type AppSyncResolverHandler<TArguments, TResult, TSource = Record<string, any> | null> = AppSyncResolverHandler$1<TArguments, TResult, TSource>;
-declare const createAppSyncResolverHandler: ({ ...buildSchemaInput }: BuildSchemaInput) => AppSyncResolverHandler<any, any, any>;
+/**
+ * The base context object passed to all AppSync resolvers.
+ */
+type BaseAppSyncContext = {
+    /** The raw Lambda invocation context. */
+    handler: Context;
+    /** The AppSync request object (includes headers). */
+    request: any;
+    /** The caller's identity (Cognito, IAM, Lambda, or OIDC). Null when using API key auth. */
+    identity: AppSyncIdentity | null | undefined;
+};
+declare const createAppSyncResolverHandler: ({ createContext, ...buildSchemaInput }: BuildSchemaInput & {
+    /**
+     * Optional async function called once per request to enrich the resolver
+     * context. The returned object is shallow-merged into the base context and
+     * made available to every resolver.
+     *
+     * Use this for per-request setup such as resolving a `userId` from Cognito.
+     * For authorization rules or before/after resolver logic, prefer `middlewares`.
+     *
+     * @example
+     * ```ts
+     * createAppSyncResolverHandler({
+     *   schemaComposer,
+     *   createContext: async ({ identity }) => ({
+     *     userId: await getUserIdFromCognitoSub(identity?.sub),
+     *   }),
+     * });
+     * ```
+     */
+    createContext?: (baseContext: BaseAppSyncContext) => Promise<Record<string, any>> | Record<string, any>;
+}) => AppSyncResolverHandler<any, any, any>;
+
+/** AWS AppSync scalar for JSON data. Represents a JSON object or array. */
+declare const AWSJSONTC: _ttoss_graphql_api.ScalarTypeComposer<any>;
+/** AWS AppSync scalar for combined date and time values (ISO 8601, e.g. `2007-04-05T14:30:28Z`). */
+declare const AWSDateTimeTC: _ttoss_graphql_api.ScalarTypeComposer<any>;
+/** AWS AppSync scalar for date values (ISO 8601, e.g. `1970-01-01`). */
+declare const AWSDateTC: _ttoss_graphql_api.ScalarTypeComposer<any>;
+/** AWS AppSync scalar for time values (ISO 8601, e.g. `12:30:00.000Z`). */
+declare const AWSTimeTC: _ttoss_graphql_api.ScalarTypeComposer<any>;
+/** AWS AppSync scalar for Unix epoch timestamps (integer, seconds since 1970-01-01T00:00:00Z). */
+declare const AWSTimestampTC: _ttoss_graphql_api.ScalarTypeComposer<any>;
+/** AWS AppSync scalar for email addresses (RFC 822). */
+declare const AWSEmailTC: _ttoss_graphql_api.ScalarTypeComposer<any>;
+/** AWS AppSync scalar for URLs (RFC 1738). */
+declare const AWSURLTC: _ttoss_graphql_api.ScalarTypeComposer<any>;
+/** AWS AppSync scalar for phone numbers (E.164 format). */
+declare const AWSPhoneTC: _ttoss_graphql_api.ScalarTypeComposer<any>;
+/** AWS AppSync scalar for IPv4 and IPv6 addresses. */
+declare const AWSIPAddressTC: _ttoss_graphql_api.ScalarTypeComposer<any>;
 
-export { type AppSyncResolverHandler, createApiTemplate, createAppSyncResolverHandler };
+export { AWSDateTC, AWSDateTimeTC, AWSEmailTC, AWSIPAddressTC, AWSJSONTC, AWSPhoneTC, AWSTimeTC, AWSTimestampTC, AWSURLTC, type AppSyncResolverHandler, type BaseAppSyncContext, createApiTemplate, createAppSyncResolverHandler };

package/dist/index.js

@@ -31,6 +31,15 @@ var __toCommonJS = mod => __copyProps(__defProp({}, "__esModule", {
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  AWSDateTC: () => AWSDateTC,
+  AWSDateTimeTC: () => AWSDateTimeTC,
+  AWSEmailTC: () => AWSEmailTC,
+  AWSIPAddressTC: () => AWSIPAddressTC,
+  AWSJSONTC: () => AWSJSONTC,
+  AWSPhoneTC: () => AWSPhoneTC,
+  AWSTimeTC: () => AWSTimeTC,
+  AWSTimestampTC: () => AWSTimestampTC,
+  AWSURLTC: () => AWSURLTC,
   createApiTemplate: () => createApiTemplate,
   createAppSyncResolverHandler: () => createAppSyncResolverHandler
 });
@@ -46,19 +55,19 @@ var AppSyncGraphQLApiKeyLogicalId = "AppSyncGraphQLApiKey";
 var createApiTemplate = /* @__PURE__ */__name(({
   additionalAuthenticationProviders,
   authenticationType = "AMAZON_COGNITO_USER_POOLS",
-  schemaComposer,
+  schemaComposer: schemaComposer2,
   dataSource,
   lambdaFunction,
   userPoolConfig,
   customDomain
 }) => {
-  const sdlWithoutComments = schemaComposer.toSDL({
+  const sdlWithoutComments = schemaComposer2.toSDL({
     commentDescriptions: false,
     omitDescriptions: true,
     omitScalars: true
   });
-  import_graphql_api.graphql.validateSchema(schemaComposer.buildSchema());
-  const resolveMethods = schemaComposer.getResolveMethods();
+  import_graphql_api.graphql.validateSchema(schemaComposer2.buildSchema());
+  const resolveMethods = schemaComposer2.getResolveMethods();
   const resolveMethodsEntries = Object.entries(resolveMethods).flatMap(([typeName, fieldResolvers]) => {
     return Object.entries(fieldResolvers).map(([fieldName, resolver]) => {
       if (typeof resolver !== "function") {
@@ -131,12 +140,15 @@ var createApiTemplate = /* @__PURE__ */__name(({
           Layers: lambdaFunction.layers,
           MemorySize: 512,
           Role: lambdaFunction.roleArn,
-          Runtime: "nodejs22.x",
+          /**
+          * https://docs.aws.amazon.com/lambda/latest/dg/lambda-runtimes.html#runtimes-supported
+          */
+          Runtime: "nodejs24.x",
           /**
           * https://docs.aws.amazon.com/general/latest/gr/appsync.html
           * Request execution time for mutations, queries, and subscriptions: 30 seconds
           */
-          Timeout: 29
+          Timeout: 30
         }
       },
       [AppSyncLambdaFunctionAppSyncDataSourceLogicalId]: {
@@ -312,11 +324,12 @@ var createApiTemplate = /* @__PURE__ */__name(({
 // src/createAppSyncResolverHandler.ts
 var import_graphql_api2 = require("@ttoss/graphql-api");
 var createAppSyncResolverHandler = /* @__PURE__ */__name(({
+  createContext,
   ...buildSchemaInput
 }) => {
   return async (event, appSyncHandlerContext) => {
     const {
-      schemaComposer
+      schemaComposer: schemaComposer2
     } = buildSchemaInput;
     const {
       info,
@@ -328,11 +341,15 @@ var createAppSyncResolverHandler = /* @__PURE__ */__name(({
       parentTypeName,
       fieldName
     } = info;
-    const context = {
+    const baseContext = {
       handler: appSyncHandlerContext,
       request,
       identity: event.identity
     };
+    const context = createContext ? {
+      ...baseContext,
+      ...(await createContext(baseContext))
+    } : baseContext;
     const schema = (0, import_graphql_api2.buildSchema)(buildSchemaInput);
     const parentType = schema.getType(parentTypeName);
     if (!parentType) {
@@ -345,7 +362,7 @@ var createAppSyncResolverHandler = /* @__PURE__ */__name(({
     }
     const argsWithEnumValues = (() => {
       const fieldsArgsIsEnumType = field.args.filter(arg => {
-        return schemaComposer.isEnumType(arg.type);
+        return schemaComposer2.isEnumType(arg.type);
       });
       const enumArgs = fieldsArgsIsEnumType.map(enumArg => {
         if (!args[enumArg.name]) {
@@ -353,7 +370,7 @@ var createAppSyncResolverHandler = /* @__PURE__ */__name(({
             [enumArg.name]: enumArg.defaultValue
           };
         }
-        const values = schemaComposer.getETC(enumArg.type).getFields();
+        const values = schemaComposer2.getETC(enumArg.type).getFields();
         return {
           [enumArg.name]: values[args[enumArg.name]].value
         };
@@ -375,8 +392,29 @@ var createAppSyncResolverHandler = /* @__PURE__ */__name(({
     return response;
   };
 }, "createAppSyncResolverHandler");
+
+// src/scalars.ts
+var import_graphql_api3 = require("@ttoss/graphql-api");
+var AWSJSONTC = import_graphql_api3.schemaComposer.createScalarTC(`scalar AWSJSON`);
+var AWSDateTimeTC = import_graphql_api3.schemaComposer.createScalarTC(`scalar AWSDateTime`);
+var AWSDateTC = import_graphql_api3.schemaComposer.createScalarTC(`scalar AWSDate`);
+var AWSTimeTC = import_graphql_api3.schemaComposer.createScalarTC(`scalar AWSTime`);
+var AWSTimestampTC = import_graphql_api3.schemaComposer.createScalarTC(`scalar AWSTimestamp`);
+var AWSEmailTC = import_graphql_api3.schemaComposer.createScalarTC(`scalar AWSEmail`);
+var AWSURLTC = import_graphql_api3.schemaComposer.createScalarTC(`scalar AWSURL`);
+var AWSPhoneTC = import_graphql_api3.schemaComposer.createScalarTC(`scalar AWSPhone`);
+var AWSIPAddressTC = import_graphql_api3.schemaComposer.createScalarTC(`scalar AWSIPAddress`);
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  AWSDateTC,
+  AWSDateTimeTC,
+  AWSEmailTC,
+  AWSIPAddressTC,
+  AWSJSONTC,
+  AWSPhoneTC,
+  AWSTimeTC,
+  AWSTimestampTC,
+  AWSURLTC,
   createApiTemplate,
   createAppSyncResolverHandler
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ttoss/appsync-api",
-  "version": "0.22.14",
+  "version": "0.23.0",
   "description": "A library for building GraphQL APIs for AWS AppSync.",
   "license": "MIT",
   "author": "ttoss",
@@ -36,9 +36,9 @@
     "graphql-shield": "^7.6.5",
     "jest": "^30.2.0",
     "tsup": "^8.5.1",
+    "@ttoss/graphql-api": "^0.8.17",
     "@ttoss/config": "^1.36.0",
-    "@ttoss/ids": "^0.3.14",
-    "@ttoss/graphql-api": "^0.8.17"
+    "@ttoss/ids": "^0.3.14"
   },
   "keywords": [
     "api",