feat: add TypeScript type definitions

This commit adds type definitions for the following:
  * `Invokable`: The user provided function
  * `Context`: The invocation context
  * `CloudEventResponse`: Convenience class for constructing events
  * `Logger`: The logging interface
  * `LogLevel`: Logging enumeration
  * `start`: A function to start the invoker
  * `InvokerOptions`: Options for `start`

The definitions are statically tested with `tsd`.

These type definitions are not actually used by the JS files. This does not
convert the module to TypeScript; it just adds these type definitions to our
exports. This will allow us to create TypeScript function templates without
a full conversion of this code base to TypeScript. Ultimately, I think it's
probably best to make the change.

This change also bumps to `[email protected]` which does have a breaking
change. See: cloudevents/sdk-javascript#332
As a result, we accept all versions of CloudEvents. Actually, I think this
is probably a fine change in the long run. Loose validation upon receipt
of an event allows functions to handle event sources that may be producing
malformed events. I've commented out the test for now. If we decide it makes
sense to leave this as-is instead of waiting for a fix from upstream, then
we should remove the test and the existing logic for dealing with this,
since it's no longer necessary.

Finally, I've really simplified the `start` funtion interface. It now just
takes a function and a bag of options. It doesn't deal with callbacks anymore.
Promises are used to deal with async server startup.

Signed-off-by: Lance Ball <[email protected]>

Author: lance

.eslintrc

@@ -1,10 +1,16 @@
 {
-  "extends": "eslint:recommended",
+  "parser": "@typescript-eslint/parser",
+  "parserOptions": {
+    "ecmaVersion": 2020,
+    "sourceType": "module"
+  },
+  "extends": [
+    "prettier"
+  ],
   "env": {
     "es2020": true,
     "node": true
   },
-  "parser": "babel-eslint",
   "rules": {
     "standard/no-callback-literal": "off",
     "arrow-spacing": "error",

index.d.ts

@@ -0,0 +1,22 @@
+import { Server } from 'http';
+import { Context } from './lib/context';
+
+export declare const start: {
+  (func: Invokable, options: InvokerOptions): Promise<Server>
+}
+
+export type InvokerOptions = {
+    'logLevel': LogLevel,
+    'port': Number
+}
+
+export enum LogLevel {
+    'debug', 'info', 'warn', 'error'
+}
+
+export interface Invokable {
+    (context: Context, data?:string|Record<string, any>): any
+}
+
+// re-export
+export { Context, Logger, CloudEventResponse } from './lib/context';

index.js

@@ -10,18 +10,9 @@ const fastify = require('fastify');
 
 const DEFAULT_PORT = 8080;
 
-function start(func, port, cb, options) {
-  switch (typeof port) {
-    case 'function':
-      options = cb;
-      cb = port;
-      port = DEFAULT_PORT;
-      break;
-    case 'undefined':
-      port = DEFAULT_PORT;
-      break;
-  }
-  const { logLevel = 'info' } = { ...options };
+// Invoker
+function start(func, options) {
+  const { logLevel = 'warn', port = DEFAULT_PORT } = { ...options };
 
   const server = fastify({ logger: { level: logLevel } });
 
@@ -56,7 +47,6 @@ function start(func, port, cb, options) {
   return new Promise((resolve, reject) => {
     server.listen(port, '0.0.0.0', err => {
       if (err) return reject(err);
-      if (cb) cb(server.server);
       resolve(server.server);
     });
   });

lib/context.d.ts

@@ -0,0 +1,32 @@
+import { IncomingHttpHeaders, IncomingMessage } from 'http';
+import { CloudEvent } from 'cloudevents';
+
+export interface Logger {
+  debug: (msg: any) => void,
+  info:  (msg: any) => void,
+  warn:  (msg: any) => void,
+  error: (msg: any) => void,
+  fatal: (msg: any) => void,
+  trace: (msg: any) => void,
+}
+
+export interface Context {
+    log: Logger;
+    req: IncomingMessage;
+    query?: Record<string, any>;
+    body?: Record<string, any>|string;
+    method: string;
+    headers: IncomingHttpHeaders;
+    httpVersion: string;
+    httpVersionMajor: number;
+    httpVersionMinor: number;
+    cloudEventResponse(data: string|object): CloudEventResponse;
+}
+
+export interface CloudEventResponse {
+    id(id: string): CloudEventResponse;
+    source(source: string): CloudEventResponse;
+    type(type: string): CloudEventResponse;
+    version(version: string): CloudEventResponse;
+    response(): CloudEvent;
+}

lib/event-handler.js

@@ -15,6 +15,7 @@ function use(fastify, opts, done) {
      if (request.isCloudEvent()) {
       try {
         request.fcontext.cloudevent = HTTP.toEvent(request);
+        request.fcontext.cloudevent.validate();
       } catch (err) {
         if (err.message.startsWith('invalid spec version')) {
           reply.code(406);