refactor!: Remove createPubSubServer (#255)

Author: simenandre

README.md

@@ -1,30 +1,25 @@
 # PubSub HTTP Handler
 
-![Build & Deploy][build-badge] [![Total alerts][lgtm-badge]][lgtm-alerts]
-[![LGTM Grade][lgtm-grade]][lgtm-alerts]
-[![Maintainability][codeclimate-badge]][codeclimate]
-
 ![PubSub HTTP Handler](.github/header.jpg)
 
 PubSub HTTP Handler is a simple Typescript/Javascript package that solves
-serving an HTTP endpoint that can consume PubSub messages. It is intended to use
-with Google Cloud Functions or Google Cloud Run.
+serving an HTTP endpoint that can consume PubSub messages. To do this task we
+utilize the [Fastify][] framework or Google Cloud Functions.
 
-This package was built so that when creating microservices that subscribes to a
+This package was built so that when creating microservices that subscribe to a
 PubSub-topic, we don't have to implement a server or validate the request.
 
-The package utilizes [Fastify][] to serve HTTP.
-
 ## Quickstart
 
 ```shell
 ▶ yarn add pubsub-http-handler
 ```
 
-## Example
+## Example with Fastify Server
 
 ```typescript
-import { createPubSubServer, PubSubHandler } from 'pubsub-http-handler';
+import Fastify from 'fastify';
+import { pubSubFastifyPlugin, PubSubHandler } from 'pubsub-http-handler';
 
 interface MyHandler {
   hello: string;
@@ -38,19 +33,34 @@ const server = async () => {
     // ...
   };
 
-  const { listen } = await createPubSubServer(handler);
-  await listen();
+  const app = Fastify().withTypeProvider<TypeBoxTypeProvider>();
+
+  app.register(pubSubFastifyPlugin, makePubSubConfig({ handler }));
+
+  await app.listen(8000);
 };
 ```
 
-We also support `fastify-plugin` and `cloud-functions`. See [more examples in
-the `examples/` folder][examples].
+## Example with Google Cloud Functions
+
+```typescript
+import { pubSubCloudFunction, PubSubHandler } from 'pubsub-http-handler';
+
+interface MyHandler {
+  hello: string;
+  world: string;
+}
+
+export const helloWorld = createPubSubCloudFunctions<MyHandler>(
+  ({ data, log }) => {
+    log.info(`Hello, ${data.name}`);
+  },
+);
+```
 
 Read more about [configuration here][configuration] or check out the [API
 documentation][docs]
 
-[examples]: ./examples
-
 ## Options
 
 - `onError` (function, default is undefined). Use to ensure that the function
@@ -76,19 +86,6 @@ We love contributions! 🙏 Bug reports and pull requests are welcome on [GitHub
 
 [banner]: ./assets/banner.jpg
 [npm]: https://www.npmjs.com/package/pubsub-http-handler
-[build-badge]:
-  https://img.shields.io/github/actions/workflow/status/cobraz/pubsub-http-handler/workflow.yml?branch=main&style=flat-square
-[codeclimate-badge]:
-  https://img.shields.io/codeclimate/maintainability/cobraz/pubsub-http-handler?style=flat-square
-[codeclimate]:
-  https://codeclimate.com/github/cobraz/pubsub-http-handler/maintainability
-[lgtm-badge]:
-  https://img.shields.io/lgtm/alerts/g/cobraz/pubsub-http-handler.svg?logo=lgtm&logoWidth=18?style=flat-square
-[lgtm-alerts]: https://lgtm.com/projects/g/cobraz/pubsub-http-handler/alerts/
-[lgtm-grade]:
-  https://img.shields.io/lgtm/grade/javascript/github/cobraz/pubsub-http-handler?style=flat-square
-[semantic-release-badge]:
-  https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg?style=flat-square
 [fastify]: https://www.fastify.io/
 [configuration]: ./docs/interfaces/pubsubconfig.md
 [docs]: ./docs/

examples/server.ts

@@ -0,0 +1,64 @@
+# Migrate from v4 to v5
+
+v5 is mainly a refactor of the codebase, to make it more maintainable and
+improve developer experience. The API is the same, but we have officially
+removed the `createPubSubServer`.
+
+We also changed from using `@sinclair/typebox` to
+`@fastify/type-provider-typebox` which probably will not affect most users, this
+bumped `@sinclair/typebox` from `0.24` to `0.27`.
+
+## Replacing `createPubSubServer` with Fastify instance
+
+The reasoning behind removing `createPubSubServer` is that it was not really
+needed. It was a function that created a `fastify` instance, and then returned a
+`listen` function. The `fastify` instance can be created by the user with almost
+the same amount of code.
+
+### Before
+
+```typescript
+import { createPubSubServer, PubSubHandler } from 'pubsub-http-handler';
+
+interface MyHandler {
+  hello: string;
+  world: string;
+}
+
+const server = async () => {
+  const handler: PubSubHandler<MyHandler> = ({ message, data }) => {
+    // `message` contains attributes, data (as string), messageId
+    // `data` contains a base64 decoded JSON serialized object (type is MyHandler in the example)
+    // ...
+  };
+
+  const { listen } = await createPubSubServer(handler);
+  await listen();
+};
+```
+
+### After
+
+```typescript
+import Fastify from 'fastify';
+import { pubSubFastifyPlugin, PubSubHandler } from 'pubsub-http-handler';
+
+interface MyHandler {
+  hello: string;
+  world: string;
+}
+
+const server = async () => {
+  const handler: PubSubHandler<MyHandler> = ({ message, data }) => {
+    // `message` contains attributes, data (as string), messageId
+    // `data` contains a base64 decoded JSON serialized object (type is MyHandler in the example)
+    // ...
+  };
+
+  const app = Fastify().withTypeProvider<TypeBoxTypeProvider>();
+
+  app.register(pubSubFastifyPlugin, makePubSubConfig({ handler }));
+
+  await app.listen(8000);
+};
+```

migrate-from-v4-to-v5.md

@@ -1,4 +1,4 @@
-import { createPubSubCloudFunctions } from '../methods/cloud-functions';
+import { createPubSubCloudFunctions } from '../cloud-functions';
 import { createPubSubRequest } from './fixtures';
 import type * as express from 'express';
 
@@ -24,13 +24,18 @@ describe('cloud functions', () => {
     };
     const onError = jest.fn();
     const send = jest.fn();
-    const fun = createPubSubCloudFunctions(handle, { onError });
+    const fun = createPubSubCloudFunctions(handle, {
+      onError,
+      context: () => ({ hello: 'world' }),
+    });
     await fun(
       { body: payload } as any,
       { status: () => ({ send }) } as unknown as any,
     );
 
-    expect(onError).toHaveBeenCalledWith(new Error('error'), payload);
+    expect(onError).toHaveBeenCalledWith(new Error('error'), {
+      hello: 'world',
+    });
   });
 
   it('should throw when onError is undefined', async () => {

src/__tests__/cloud-functions.test.ts

@@ -1,10 +1,12 @@
 import { handlePubSubMessage } from '../common';
-import jsf from 'json-schema-faker';
-import { PubSubMessage, PubSubMessageType } from '../types';
+import { JSONSchemaFaker } from 'json-schema-faker';
+import { PubSubMessage, pubSubMessageSchema } from '../types';
 import pino from 'pino';
 
-function createPubSubdata(input: unknown, stringify = true): PubSubMessageType {
-  const message = jsf.generate(PubSubMessage) as PubSubMessageType;
+function createPubSubdata(input: unknown, stringify = true): PubSubMessage {
+  const message = JSONSchemaFaker.generate(
+    pubSubMessageSchema,
+  ) as PubSubMessage;
   const data = Buffer.from(
     stringify ? JSON.stringify(input) : (input as string),
   ).toString('base64');

src/__tests__/common.test.ts

@@ -1,6 +1,8 @@
 import Fastify, { FastifyInstance } from 'fastify';
-import { pubSubFastifyPlugin } from '../methods/fastify-plugin';
-import { PubSubConfig } from '../types';
+import {
+  PubSubHandlerFastifyConfig,
+  pubSubFastifyPlugin,
+} from '../fastify-plugin';
 import { createPubSubRequest } from './fixtures';
 
 describe('fastify-plugin', () => {
@@ -75,7 +77,7 @@ describe('fastify-plugin', () => {
 
     expect(onError).toHaveBeenCalledWith(
       new Error('error'),
-      expect.objectContaining({ body: payload }),
+      expect.any(Object),
     );
   });
 
@@ -105,10 +107,10 @@ describe('fastify-plugin', () => {
     });
     const payload = createPubSubRequest('forward me');
 
-    app.register(pubSubFastifyPlugin, { handler, parser } as PubSubConfig<
-      any,
-      any
-    >);
+    app.register(pubSubFastifyPlugin, {
+      handler,
+      parser,
+    } as PubSubHandlerFastifyConfig<any, any>);
 
     const res = await app.inject({
       method: 'POST',

src/__tests__/fastify-plugin.test.ts

@@ -1,11 +1,11 @@
-import { PubSubRequest, PubSubRequestType } from '../types';
-import jsf from 'json-schema-faker';
+import { PubSubRequest, pubSubRequestSchema } from '../types';
+import { JSONSchemaFaker } from 'json-schema-faker';
 
 export function createPubSubRequest(
   input: unknown,
   stringify = true,
-): PubSubRequestType {
-  const data = jsf.generate(PubSubRequest) as PubSubRequestType;
+): PubSubRequest {
+  const data = JSONSchemaFaker.generate(pubSubRequestSchema) as PubSubRequest;
   data.message.data = Buffer.from(
     stringify ? JSON.stringify(input) : (input as string),
   ).toString('base64');