@openstax/ts-utils 1.33.1 → 1.34.0

package/packages/lambda/src/functions/serviceApi/versions/v0/example/routes.spec.ts

@@ -0,0 +1,306 @@
+import { ApiRouteRequest } from '../../../core';
+import { apiV0AccessControl, apiV0ExampleError, apiV0ExampleReverseRouting, apiV0GetExampleDoc, apiV0GetExampleDocHistory, apiV0SearchExampleDoc, apiV0WriteExampleDoc } from './routes';
+
+let request: ApiRouteRequest;
+
+beforeEach(async () => {
+  request = {} as ApiRouteRequest;
+});
+
+afterEach(() => {
+  jest.clearAllMocks();
+});
+
+describe('apiV0ExampleReverseRouting', () => {
+  it('matches snapshot', async() => {
+    const response = await apiV0ExampleReverseRouting.handler(undefined, {request} as any);
+    expect(response).toMatchInlineSnapshot(`
+{
+  "body": "{"links":{"apiV0GetExampleDoc":"/api/v0/get-example-document/foo","apiV0WriteExampleDoc":"/api/v0/write-example-document/bar"}}",
+  "data": {
+    "links": {
+      "apiV0GetExampleDoc": "/api/v0/get-example-document/foo",
+      "apiV0WriteExampleDoc": "/api/v0/write-example-document/bar",
+    },
+  },
+  "headers": {
+    "content-type": "application/json",
+  },
+  "statusCode": 200,
+}
+`);
+  });
+});
+
+describe('apiV0AccessControl', () => {
+  it('fails', async() => {
+    const assertUserRole = jest.fn().mockImplementation(() => { throw new Error(); });
+    const requestServices = {
+      roleValidator: {assertUserRole}
+    } as any;
+    await expect(() => apiV0AccessControl.handler(undefined, requestServices)).rejects.toThrow();
+  });
+
+  it('passes', async() => {
+    const assertUserRole = jest.fn();
+    const requestServices = {
+      roleValidator: {assertUserRole}
+    } as any;
+    await expect(apiV0AccessControl.handler(undefined, requestServices)).resolves.not.toThrow();
+  });
+});
+
+describe('apiV0SearchExampleDoc', () => {
+  it('searches', async() => {
+    const search = jest.fn();
+    const requestServices = {
+      pagination: {
+        getPaginationParams: () => ({}),
+        getPaginationResponse: (x: any) => x,
+      },
+      exampleDocumentSearch: {search},
+      request: {
+        queryStringParameters: {
+          query: 'cool query',
+          someFilter: 'filter value'
+        }
+      }
+    } as any;
+    search.mockReturnValue([{result: 'value'}]);
+    const result = await apiV0SearchExampleDoc.handler(undefined, requestServices);
+
+    expect(search).toHaveBeenCalledWith(expect.objectContaining({
+      query: 'cool query',
+      filter: [{key: 'someFilter', value: ['filter value']}]
+    }));
+    expect(result).toMatchInlineSnapshot(`
+{
+  "body": "[{"result":"value"}]",
+  "data": [
+    {
+      "result": "value",
+    },
+  ],
+  "headers": {
+    "content-type": "application/json",
+  },
+  "statusCode": 200,
+}
+`);
+  });
+
+  it('works with no query', async() => {
+    const search = jest.fn();
+    const requestServices = {
+      pagination: {
+        getPaginationParams: () => ({}),
+        getPaginationResponse: (x: any) => x,
+      },
+      exampleDocumentSearch: {search},
+      request: {
+      }
+    } as any;
+    search.mockReturnValue([{result: 'value'}]);
+    const result = await apiV0SearchExampleDoc.handler(undefined, requestServices);
+
+    expect(search).toHaveBeenCalledWith(expect.objectContaining({
+      query: undefined,
+      filter: []
+    }));
+    expect(result).toMatchInlineSnapshot(`
+{
+  "body": "[{"result":"value"}]",
+  "data": [
+    {
+      "result": "value",
+    },
+  ],
+  "headers": {
+    "content-type": "application/json",
+  },
+  "statusCode": 200,
+}
+`);
+  });
+
+  it('omits empty filters', async() => {
+    const search = jest.fn();
+    const requestServices = {
+      pagination: {
+        getPaginationParams: () => ({}),
+        getPaginationResponse: (x: any) => x,
+      },
+      exampleDocumentSearch: {search},
+      request: {
+        queryStringParameters: {
+          query: 'cool query',
+          someFilter: ''
+        }
+      }
+    } as any;
+    search.mockReturnValue([{result: 'value'}]);
+    const result = await apiV0SearchExampleDoc.handler(undefined, requestServices);
+
+    expect(search).toHaveBeenCalledWith(expect.objectContaining({
+      query: 'cool query',
+      filter: []
+    }));
+    expect(result).toMatchInlineSnapshot(`
+{
+  "body": "[{"result":"value"}]",
+  "data": [
+    {
+      "result": "value",
+    },
+  ],
+  "headers": {
+    "content-type": "application/json",
+  },
+  "statusCode": 200,
+}
+`);
+  });
+});
+
+describe('apiV0GetExampleDocHistory', () => {
+  it('gets versions', async() => {
+    const getVersions = jest.fn();
+    const requestServices = {
+      pagination: {
+        getPageTokenNumber: () => 1111,
+        getPaginationResponse: (x: any) => x,
+      },
+      exampleDocumentStore: {getVersions}
+    } as any;
+    getVersions.mockReturnValue([{foo: 'bar'}]);
+    const result = await apiV0GetExampleDocHistory.handler({key: 'example-id'}, requestServices);
+
+    expect(getVersions).toHaveBeenCalledWith('example-id', 1111);
+    expect(result).toMatchInlineSnapshot(`
+{
+  "body": "[{"foo":"bar"}]",
+  "data": [
+    {
+      "foo": "bar",
+    },
+  ],
+  "headers": {
+    "content-type": "application/json",
+  },
+  "statusCode": 200,
+}
+`);
+  });
+
+  it('returns 404 for missing item', async() => {
+    const getVersions = jest.fn();
+    const requestServices = {
+      pagination: {
+        getPageTokenNumber: () => 1111,
+        getPaginationResponse: (x: any) => x,
+      },
+      exampleDocumentStore: {getVersions}
+    } as any;
+    getVersions.mockReturnValue(undefined);
+    const result = await apiV0GetExampleDocHistory.handler({key: 'example-id'}, requestServices);
+
+    expect(getVersions).toHaveBeenCalledWith('example-id', 1111);
+    expect(result).toMatchInlineSnapshot(`
+{
+  "body": "{"message":"requested item not found"}",
+  "data": {
+    "message": "requested item not found",
+  },
+  "headers": {
+    "content-type": "application/json",
+  },
+  "statusCode": 404,
+}
+`);
+  });
+});
+
+describe('apiV0GetExampleDoc', () => {
+  it('returns result from document store', async() => {
+    const getItem = jest.fn();
+    const requestServices = {
+      exampleDocumentStore: {getItem}
+    } as any;
+    getItem.mockReturnValue({foo: 'bar'});
+    const result = await apiV0GetExampleDoc.handler({key: 'example-id'}, requestServices);
+
+    expect(getItem).toHaveBeenCalledWith('example-id');
+    expect(result).toMatchInlineSnapshot(`
+{
+  "body": "{"foo":"bar"}",
+  "data": {
+    "foo": "bar",
+  },
+  "headers": {
+    "content-type": "application/json",
+  },
+  "statusCode": 200,
+}
+`);
+  });
+
+  it('returns 404 for missing item', async() => {
+    const getItem = jest.fn();
+    const requestServices = {
+      exampleDocumentStore: {getItem}
+    } as any;
+    getItem.mockReturnValue(undefined);
+    const result = await apiV0GetExampleDoc.handler({key: 'example-id'}, requestServices);
+
+    expect(getItem).toHaveBeenCalledWith('example-id');
+    expect(result).toMatchInlineSnapshot(`
+{
+  "body": "{"message":"requested item not found"}",
+  "data": {
+    "message": "requested item not found",
+  },
+  "headers": {
+    "content-type": "application/json",
+  },
+  "statusCode": 404,
+}
+`);
+  });
+});
+
+describe('apiV0WriteExampleDoc', () => {
+  it('saves item', async() => {
+    const item = {asdf: 'foo'};
+    const putItem = jest.fn();
+    const requestServices = {
+      request,
+      exampleDocumentStore: {putItem},
+      payload: item
+    } as any;
+    putItem.mockReturnValue(Promise.resolve({...item, id: 'example-id'}));
+    const result = await apiV0WriteExampleDoc.handler({key: 'example-id'}, requestServices);
+
+    expect(putItem).toHaveBeenCalledWith({...item, id: 'example-id'});
+
+    expect(result).toMatchInlineSnapshot(`
+{
+  "body": "{"asdf":"foo","id":"example-id"}",
+  "data": {
+    "asdf": "foo",
+    "id": "example-id",
+  },
+  "headers": {
+    "content-type": "application/json",
+  },
+  "statusCode": 201,
+}
+`);
+  });
+});
+
+describe('apiV0ExampleError', () => {
+  it('saves item', async() => {
+    const requestServices = {} as any;
+    await expect(apiV0ExampleError.handler(undefined, requestServices)).rejects.toThrow();
+  });
+});

package/packages/lambda/src/functions/serviceApi/versions/v0/example/routes.ts

@@ -0,0 +1,176 @@
+import { isDefined } from '@openstax/ts-utils/guards';
+import { apiJsonResponse, ApiResponse, apiTextResponse, METHOD, requestPayloadProvider, routesList } from '@openstax/ts-utils/routing';
+import { zodPayloadValidator } from '@openstax/ts-utils/routing/validators/zod';
+import { z } from 'zod';
+import { renderRouteUrl } from '../../../core/routes';
+import { composeServiceMiddleware, createRoute } from '../../../core/services';
+import { authMiddleware } from '../middleware/authMiddleware';
+import { loadMorePaginationMiddleware, pageNumberPaginationMiddleware } from '../middleware/paginationMiddleware';
+import { searchMiddleware } from '../middleware/searchMiddleware';
+import { userRoleValidatorMiddleware } from '../middleware/userRoleValidatorMiddleware';
+import { documentSearchMiddleware } from './documentSearchMiddleware';
+import { documentStoreMiddleware } from './documentStoreMiddleware';
+
+// shared middleware can be gathered separately like this
+const requestServiceProvider = composeServiceMiddleware(
+  authMiddleware,
+  userRoleValidatorMiddleware,
+  searchMiddleware,
+  documentStoreMiddleware,
+  documentSearchMiddleware,
+);
+
+export const apiV0ExampleError = createRoute({name: 'apiV0ExampleError', method: METHOD.GET, path: '/api/v0/example-error',
+  requestServiceProvider, // if you don't need any other middleware just pass it through
+  handler: async() => {
+    throw new Error('cool message');
+  }
+});
+
+export const apiV0AccessControl = createRoute({name: 'apiV0AccessControl', method: METHOD.GET, path: '/api/v0/access-control',
+  requestServiceProvider, // if you don't need any other middleware just pass it through
+  handler: async(_: undefined, {roleValidator}) => {
+
+    await roleValidator.assertUserRole(['admin', 'manager']);
+
+    return apiTextResponse(200, 'for sure either an admin or a manager');
+  }
+});
+
+export const apiV0ExampleReverseRouting = createRoute({name: 'apiV0ExampleReverseRouting', method: METHOD.GET, path: '/api/v0/example',
+  requestServiceProvider,
+  /*
+   * you can provide an explicit response type like this, or let typescript figure it out from the return statements,
+   * in either case the apiGateway helper will pull this response type through to the client code.
+   */
+  handler: async(): Promise<ApiResponse<200, {links: {[key: string]: string}}>> => {
+    return apiJsonResponse(200, {
+      links: {
+        [apiV0GetExampleDoc.name]: renderRouteUrl(apiV0GetExampleDoc, {key: 'foo'}),
+        [apiV0WriteExampleDoc.name]: renderRouteUrl(apiV0WriteExampleDoc, {key: 'bar'}),
+      }
+    });
+  }
+});
+
+/*
+ * loading version history of a document is an example of "load more" style pagination, this is necessary
+ * because of the way dynamodb does its pagination
+ */
+export const apiV0GetExampleDocHistory = createRoute({name: 'apiV0GetExampleDocHistory', method: METHOD.GET, path: '/api/v0/get-example-document/:key/history',
+  requestServiceProvider: composeServiceMiddleware( // more middleware can be composed in the same way
+    requestServiceProvider,
+    loadMorePaginationMiddleware,
+  )},
+  /*
+   * if you specify the requestServiceProvider inline, like the previous line, then TS has trouble figuring out the types if
+   * the handler is part of the same argument, so in this case you need to specify the handler in the second argument
+   */
+  async(params: {key: string}, services) => {
+    const result = await services.exampleDocumentStore.getVersions(params.key, services.pagination.getPageTokenNumber());
+
+    /*
+     * if a route returns more than one response format, the apiGateway will help clients keep track of that
+     * and provides a narrowing helper based on the status code (the client can also just throw on unexpected statuses)
+     */
+    if (!result) {
+      return apiJsonResponse(404, { message: 'requested item not found' });
+    }
+
+    return apiJsonResponse(200, services.pagination.getPaginationResponse(result));
+  }
+);
+
+export const apiV0GetExampleDoc = createRoute({name: 'apiV0GetExampleDoc', method: METHOD.GET, path: '/api/v0/get-example-document/:key',
+  requestServiceProvider,
+  handler: async(params: {key: string}, services) => {
+    const result = await services.exampleDocumentStore.getItem(params.key);
+
+    if (!result) {
+      return apiJsonResponse(404, { message: 'requested item not found' });
+    }
+
+    return apiJsonResponse(200, result);
+  }
+});
+
+/*
+ * document search is an example of "page number" style pagination, this is necessary
+ * because of the way elastic search does its pagination
+ */
+export const apiV0SearchExampleDoc = createRoute({name: 'apiV0SearchExampleDoc', method: METHOD.GET, path: '/api/v0/search-example-document',
+  requestServiceProvider: composeServiceMiddleware(
+    requestServiceProvider,
+    pageNumberPaginationMiddleware,
+  )},
+  async(_: undefined, services) => {
+    const queryParams = services.request.queryStringParameters || {};
+    const {query, ...filters} = queryParams;
+
+    const result = await services.exampleDocumentSearch.search({
+      ...services.pagination.getPaginationParams(),
+      query,
+      filter: Object.entries(filters).map(([key, value]) => key && value
+        ? {key, value: value.split(',')}
+        : undefined
+      ).filter(isDefined),
+      fields: [
+        {key: 'name', weight: 5},
+        {key: 'description', weight: 1}
+      ]
+    });
+
+    return apiJsonResponse(200,
+      services.pagination.getPaginationResponse(result)
+    );
+  }
+);
+
+/*
+ * zod is a validation library that generates a type for the payload.
+ *
+ * if the payload type generated by zod and the application type expected by your documentStore
+ * don't line up, you will correctly get a typescript error.
+ *
+ * the `zodPayloadValidator` takes the zod schema and throws a ValidationError if validation fails.
+ *
+ * zod generates robust failure messages that are included on the ValidationError response and
+ * can be shown in the UI.
+ */
+const exampleDocValidator = z.object({
+  name: z.string()
+    .min(1, {message: 'name is required'})
+    .max(100, {message: 'name is too long'}),
+  description: z.string()
+    .min(1, {message: 'description is required'})
+    .max(100, {message: 'description is too long'}),
+}).strict();
+
+
+export const apiV0WriteExampleDoc = createRoute({name: 'apiV0WriteExampleDoc', method: METHOD.POST, path: '/api/v0/write-example-document/:key',
+  requestServiceProvider: composeServiceMiddleware(
+    requestServiceProvider,
+    /*
+     * the presence of this requestPayloadProvider and the type provided by the validator/guard you pass into it is what
+     * allows the apiGateway to provide a strong payload type
+     */
+    requestPayloadProvider(zodPayloadValidator(exampleDocValidator))
+  )},
+  async(params: {key: string}, services) => {
+    const result = await services.exampleDocumentStore.putItem({
+      ...services.payload,
+      id: params.key,
+    });
+    return apiJsonResponse(201, result);
+  }
+);
+
+export const apiV0ExampleRoutes = () => routesList([
+  apiV0ExampleError,
+  apiV0AccessControl,
+  apiV0ExampleReverseRouting,
+  apiV0GetExampleDocHistory,
+  apiV0GetExampleDoc,
+  apiV0SearchExampleDoc,
+  apiV0WriteExampleDoc,
+]);