docs(General): Add JSDoc on all exported functions and types

.github/workflows/naming.yml

@@ -2,7 +2,7 @@ name: Naming Conventions
 
 on:
   pull_request:
-    types: [opened, edited]
+    types: [opened, edited, synchronize]
     branches:
       - develop
 
@@ -11,6 +11,14 @@ jobs:
     name: Naming Conventions
     runs-on: ubuntu-latest
     steps:
-      - uses: deepakputhraya/action-pr-title@master
+      - uses: amannn/action-semantic-pull-request@v5
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         with:
-          regex: '(feat|fix|ci|docs|test|refactor|build|chore|script)\(.+\): .+'
+          types: |
+            feat
+            fix
+            ci
+            docs
+            chore
+          requireScope: true

doc/matchers/cognito.md

@@ -30,11 +30,11 @@ Asserts that a user exists in the given user pool, and matches a subset of the p
 await expect(
   cognitoUser({
     userPoolId: 'my-pool',
-    username: 'user-1'
+    username: 'user-1',
   }),
 ).toExistAndMatchObject({
   Enabled: true,
-  Username: 'user-1'
+  Username: 'user-1',
 });
 ```
 
@@ -46,7 +46,7 @@ Asserts that a user exists in the given user pool, and that it matches the most
 await expect(
   cognitoUser({
     userPoolId: 'my-pool',
-    username: 'user-1'
+    username: 'user-1',
   }),
 ).toExistAndMatchSnapshot();
 ```
@@ -56,11 +56,10 @@ await expect(
 Asserts that a user exists in the given user pool, and that it matches the most recent inline snapshot. It works similarly to jest's [toMatchInlineSnapshot](https://jestjs.io/docs/expect#tomatchinlinesnapshotpropertymatchers-inlinesnapshot).
 
 ```typescript
-
 await expect(
   cognitoUser({
     userPoolId: 'my-pool',
-    username: 'user-1'
+    username: 'user-1',
   }),
 ).toExistAndMatchInlineSnapshot(
   {

doc/utils/cognito.md

@@ -2,15 +2,14 @@
 
 ## Functions
 
-### `cognitoSignUp`
-
+### `signUpCognitoUser`
 
 Create a new user in cognito, auto confirm it and return its credentials.
 
 example:
 
 ```typescript
-const credentials = await cognitoSignUp({
+const credentials = await signUpCognitoUser({
   clientId: 'client_id',
   userPoolId: 'user_pool_id',
   username: '[email protected]',
@@ -25,17 +24,17 @@ const credentials = await cognitoSignUp({
 
 // credentials = {AccessToken: string, IdToken: string, ...}
 ```
+
 The returned value is of type [AuthenticationResultType](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AuthenticationResultType.html) from @aws-sdk/client-cognito-identity-provider.
 
 Note: this function is not idempotent, if the user already exists it will fail.
 
-### `cognitoSignIn`
+### `signInWithCognitoUser`
 
 Sign in a user in cognito and return its credentials.
 
-
 ```typescript
-const credentials = await cognitoSignIn({
+const credentials = await signInWithCognitoUser({
   clientId: 'client_id',
   userPoolId: 'user_pool_id',
   username: '[email protected]',
@@ -47,15 +46,13 @@ const credentials = await cognitoSignIn({
 
 The returned value is of type [AuthenticationResultType](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AuthenticationResultType.html) from @aws-sdk/client-cognito-identity-provider.
 
-### `cognitoDeleteUser`
+### `deleteCognitoUser`
 
 Delete a user in cognito.
 
-
 ```typescript
-await cognitoDeleteUser({
+await deleteCognitoUser({
   userPoolId: 'user_pool_id',
   username: '[email protected]',
 });
 ```
-

examples/__tests__/cognito.test.ts

@@ -1,5 +1,9 @@
 import { Chance } from 'chance';
-import { cognitoSignIn, cognitoSignUp, cognitoUser } from 'sls-jest';
+import {
+  signInWithCognitoUser,
+  signUpCognitoUser,
+  cognitoUser,
+} from 'sls-jest';
 
 const chance = new Chance();
 
@@ -8,11 +12,11 @@ const clientId = '3oed3rv2h43sleqojqtt2bb43a';
 const userPoolId = 'us-east-1_2KFDP3x2n';
 
 describe('Utils', () => {
-  describe('cognitoSignUp', () => {
+  describe('signUpCognitoUser', () => {
     it('should sign up a user and return its credentials, when user does not exist', async () => {
       const email = chance.email();
       const password = chance.string({ length: 8 });
-      const credentials = await cognitoSignUp({
+      const credentials = await signUpCognitoUser({
         clientId,
         userPoolId,
         username: email,
@@ -35,7 +39,7 @@ describe('Utils', () => {
       const email = chance.email();
       const password = chance.string({ length: 8 });
 
-      await cognitoSignUp({
+      await signUpCognitoUser({
         clientId,
         userPoolId,
         username: email,
@@ -49,7 +53,7 @@ describe('Utils', () => {
       });
 
       await expect(
-        cognitoSignUp({
+        signUpCognitoUser({
           clientId,
           userPoolId,
           username: email,
@@ -65,12 +69,12 @@ describe('Utils', () => {
     });
   });
 
-  describe('cognitoSignIn', () => {
+  describe('signInWithCognitoUser', () => {
     it('should sign in a user and return its credentials, when user exists', async () => {
       const email = chance.email();
       const password = chance.string({ length: 8 });
 
-      await cognitoSignUp({
+      await signUpCognitoUser({
         clientId,
         userPoolId,
         username: email,
@@ -83,9 +87,9 @@ describe('Utils', () => {
         ],
       });
 
-      const credentials = await cognitoSignIn({
-        clientId,
+      const credentials = await signInWithCognitoUser({
         userPoolId,
+        clientId,
         username: email,
         password,
       });
@@ -101,7 +105,7 @@ describe('Utils', () => {
       const password = chance.string({ length: 8 });
 
       await expect(
-        cognitoSignIn({
+        signInWithCognitoUser({
           clientId,
           userPoolId,
           username: email,
@@ -120,7 +124,7 @@ describe('Matchers', () => {
   beforeAll(async () => {
     existingUser = chance.email();
 
-    await cognitoSignUp({
+    await signUpCognitoUser({
       clientId,
       userPoolId,
       username: existingUser,

src/helpers/appsync.ts

@@ -8,6 +8,9 @@ import { Context } from '@aws-appsync/utils';
 import { O } from 'ts-toolbelt';
 import { z } from 'zod';
 
+/**
+ * Partial AWS AppSync context
+ */
 type PartialContext = O.Partial<
   Context<
     Record<string, unknown>,
@@ -23,8 +26,17 @@ type PartialContext = O.Partial<
  * AppSync mapping template helper input
  */
 export type AppSyncMappingTemplateInput = {
+  /**
+   * The path to a file containing containing a mapping template.
+   */
   template: string;
+  /**
+   * The context to pass to the resolver function.
+   */
   context: PartialContext;
+  /**
+   * An optional AppSync SDK client configuration.
+   */
   clientConfig?: AppSyncClientConfig;
 };
 
@@ -39,14 +51,28 @@ const appSyncMappingTemplateInputSchema: HelperZodSchema<
 });
 
 /**
- * AppSync mapping template matcher helper.
+ * Helper function to describe an AppSync mapping template to test.
+ *
+ * Use with {@link expect} and any compatible matcher.
+ * @see https://serverlessguru.gitbook.io/sls-jest/matchers/appsync
  *
- * Use it to evaluate a mapping template and assert on the result.
+ * @param input {@link AppSyncMappingTemplateInput}
  *
- * @param {string} template The path to a file containing containing a mapping template.
- * The path can either be absolute, or relative to the working directory (`process.cwd()`).
- * @param {object} context The context to pass to the resolver function.
- * @param {object} clientConfig An optional AppSync SDK client configuration.
+ * @example
+ *
+ * expect(appSyncMappingTemplate({
+ *   template: 'src/resolvers/Query.getUser.request.vtl',
+ *   context: {
+ *     arguments: {
+ *       id: '123'
+ *     }
+ *   }
+ * })).toEvaluateTo({
+ *   operation: 'GetItem',
+ *   key: {
+ *     id: { S: '123' }
+ *   }
+ * });
  */
 export const appSyncMappingTemplate: MatcherHelper<
   'appSyncMappingTemplate',
@@ -68,9 +94,21 @@ export const appSyncMappingTemplate: MatcherHelper<
  * AppSync js resolver helper input
  */
 export type AppSyncResolverInput = {
+  /**
+   * The path to a file containing an `APPSYNC_JS` resolver code.
+   */
   code: string;
+  /**
+   * The function to evaluate. `request` or `response`.
+   */
   function: 'request' | 'response';
+  /**
+   * The context to pass to the resolver function.
+   */
   context: PartialContext;
+  /**
+   * An optional AppSync SDK client configuration.
+   */
   clientConfig?: AppSyncClientConfig;
 };
 
@@ -85,15 +123,29 @@ const appSyncResolverInputSchema: HelperZodSchema<typeof appSyncResolver> =
   });
 
 /**
- * AppSync Resolver matcher helper.
+ * Helper function that describes an AppSync js resolver to test.
+ *
+ * Use with {@link expect} and any compatible matcher.
+ * @see https://serverlessguru.gitbook.io/sls-jest/matchers/appsync
+ *
+ * @param input {@link AppSyncResolverInput}
  *
- * Use it to evaluate a js resolver and assert on the result.
+ * @example
  *
- * @param {string} code The path to a file containing an `APPSYNC_JS` resolver code.
- * The path can either be absolute, or relative to the working directory (`process.cwd()`).
- * @param {string} function The function to evaluate. `request` or `response`.
- * @param {object} context The context to pass to the resolver function.
- * @param {object} clientConfig An optional AppSync SDK client configuration.
+ * expect(appSyncResolver({
+ *   code: 'src/resolvers/Query.getUser.js',
+ *   function: 'request',
+ *   context: {
+ *     arguments: {
+ *       id: '123'
+ *     }
+ *   }
+ * })).toEvaluateTo({
+ *   operation: 'GetItem',
+ *   key: {
+ *     id: { S: '123' }
+ *   }
+ * });
  */
 export const appSyncResolver: MatcherHelper<
   'appSyncResolver',

src/helpers/cognito.ts

@@ -10,8 +10,17 @@ import {
  * Cognito User helper input
  */
 export type CognitoUserInput = {
+  /**
+   * The cognito user pool id.
+   */
   userPoolId: string;
+  /**
+   * The cognito user username.
+   */
   username: string;
+  /**
+   * An optional Cognito SDK client configuration.
+   */
   clientConfig?: CognitoIdentityProviderClientConfig;
 };
 
@@ -24,7 +33,18 @@ const cognitoUserInputSchema: HelperZodSchema<typeof cognitoUser> = z.object({
 });
 
 /**
- * Cognito User helper
+ * Helper function that describes a Cognito User to test.
+ *
+ * Use with {@link expect} and any compatible matcher.
+ *
+ * @param input {@link CognitoUserInput}
+ *
+ * @example
+ *
+ * expect(cognitoUser({
+ *   userPoolId: 'us-east-1_123456789',
+ *   username: 'john'
+ * })).toExist();
  */
 export const cognitoUser: RetryableMatcherHelper<
   'cognitoUser',