Merge pull request #4 from grissius/feat/type-safety

Type safety

Author: smolijar

README.md

@@ -11,11 +11,11 @@ Modern, minimalist type-safe gRPC framework for Node.js
 ## Quickstart
 
 ```typescript
-import { Server } from 'protocat'
+import { ProtoCat } from 'protocat'
 import { CatService } from '../dist/cat_grpc_pb' // Generated service definition
 
-server = new Server()
-server.addService(CatService, {
+app = new ProtoCat()
+app.addService(CatService, {
     getCat: async call => {
         const cat = await getCatByName(call.request?.getName() ?? '')
         call.response.setName(cat.name)
@@ -25,7 +25,7 @@ server.addService(CatService, {
     }
 }
 
-server.start('0.0.0.0:3000', ServerCredentials.createInsecure())
+app.start('0.0.0.0:3000', ServerCredentials.createInsecure())
 ```
 
 ## Features
@@ -40,19 +40,19 @@ Protocat uses pure JavaScript gRPC client implementation `@grpc/grpc-js`
 
 Middlewares can be registered
 
-1. either globally, with `server.use` for all incoming requests,
+1. either globally, with `app.use` for all incoming requests,
 2. or at method level with `addService`, where instead of a single handler, an array of handlers can be provided (handler and middleware have the same API).
 
 ```typescript
-server.use(ctx => {
+app.use(call => {
   /*...*/
 })
-server.addService(CatService, {
+app.addService(CatService, {
   getCat: [
-    ctx => {
+    call => {
       /*...*/
     },
-    ctx => {
+    call => {
       /*...*/
     },
   ],
@@ -63,21 +63,21 @@ Note that grpc does not provide API to intercept all incoming requests, only to
 
 #### `next` function
 
-Here is an example of a simple logger middleware. Apart from `context` each middleware (handler alike) has a `next` function. This is callstack of all subsequent middlewares and handlers. This feature is demonstrated in a simple logger middleware bellow.
+Here is an example of a simple logger middleware. Apart from `call` each middleware (handler alike) has a `next` function. This is callstack of all subsequent middlewares and handlers. This feature is demonstrated in a simple logger middleware bellow.
 
 ```typescript
-server.use(async (ctx, next) => {
+app.use(async (call, next) => {
   const start = performance.now()
-  console.log(` --> ${ctx.path}`, {
-    request: ctx.request?.toObject(),
-    clientMetadata: ctx.metadata.getMap(),
+  console.log(` --> ${call.path}`, {
+    request: call.request?.toObject(),
+    clientMetadata: call.metadata.getMap(),
   })
   await next()
-  console.log(` <-- ${ctx.path}`, {
-    response: ctx.response?.toObject(),
+  console.log(` <-- ${call.path}`, {
+    response: call.response?.toObject(),
     durationMillis: performance.now() - start,
-    initialMetadata: ctx.initialMetadata.getMap(),
-    trailingMetadata: ctx.trailingMetadata.getMap(),
+    initialMetadata: call.initialMetadata.getMap(),
+    trailingMetadata: call.trailingMetadata.getMap(),
   })
 })
 ```
@@ -87,17 +87,17 @@ server.use(async (ctx, next) => {
 All middlewares are executed in order they were registered, followed by an execution of handlers is provided order, regardless of middleware-service order. Not that in the following example, `C` middleware is registered after `CatService` and it is still called, even before the handlers.
 
 ```typescript
-server.use(async (ctx, next) => {
+app.use(async (call, next) => {
   console.log('A1')
   await next()
   console.log('A2')
 })
-server.use(async (ctx, next) => {
+app.use(async (call, next) => {
   console.log('B1')
   await next()
   console.log('B2')
 })
-server.addService(CatService, {
+app.addService(CatService, {
   getCat: [
     async (call, next) => {
       console.log('D1')
@@ -111,7 +111,7 @@ server.addService(CatService, {
     },
   ],
 })
-server.use(async (ctx, next) => {
+app.use(async (call, next) => {
   console.log('C1')
   await next()
   console.log('C2')
@@ -137,7 +137,7 @@ server.use(async (ctx, next) => {
 Error handling can be solved with a custom simple middleware, thanks to existing `next` cascading mechanism:
 
 ```typescript
-server.use(async (ctx, next) => {
+app.use(async (call, next) => {
   try {
     await next()
   } catch (error) {
@@ -158,17 +158,17 @@ There is an `onError` middleware creator, that can intercept all errors includin
 ```typescript
 import { onError } from 'protocat'
 
-server.use(
-  onError((e, ctx) => {
+app.use(
+  onError((e, call) => {
     // Set metadata
-    ctx.initialMetadata.set('error-code', e.code)
-    ctx.trailingMetadata.set('error-code', e.code)
+    call.initialMetadata.set('error-code', e.code)
+    call.trailingMetadata.set('error-code', e.code)
 
     // Consume the error
     if (notThatBad(e)) {
-      if (ctx.type === CallType.SERVER_STREAM || ctx.type === CallType.BIDI) {
+      if (call.type === CallType.ServerStream || call.type === CallType.Bidi) {
         // sync error not re-thrown on stream response, should end
-        ctx.end()
+        call.end()
       }
       return
     }
@@ -182,7 +182,7 @@ server.use(
 )
 ```
 
-- The handler is called with error and context for all errors (rejects from handlers, error emits from streams), meaning there can be theoretically more errors per request (multiple emitted errors) and some of them can be handled even after the executon of the next chain (error emits).
+- The handler is called with error and current call for all errors (rejects from handlers, error emits from streams), meaning there can be theoretically more errors per request (multiple emitted errors) and some of them can be handled even after the executon of the next chain (error emits).
 - Provided function can be sync on async. It can throw (or return rejected promise), but any other return value is ignored
 - Both initial and trailing metadata are available for change (unless you sent them manually)
 - In order to achieve "re-throwing", `emit` function on call is patched by `onError`. When calling `call.emit('error', e)`, the error is actually emitted in the stream only when the handler throws a new error. This means that when you emit an error in the middleware and consume it in the handler, streams are left "hanging", not errored and likely not even ended. If you truly wish to not propagate the error to client, it is recommended to end the streams in the handler. (This is not performed automatically, since there is no guarantee there should be no more than one error)
@@ -193,16 +193,16 @@ server.use(
 
 - [x] Middleware
 - [x] Error handling
-- [ ] Type safety
+- [x] Type safety
 
-- [ ] call / context terminology
-- [ ] call / stream terminology
-- [ ] metaS / metaP test naming confusion
+- [x] call / context terminology
+- [x] call / stream terminology
+- [x] status / metadata test naming confusion
 - [ ] metadata readme section
 - [ ] starter project
 - [ ] gRPC client
 - [ ] Call pool
-- [ ] Context type extension
+- [x] Context type extension
 - [ ] Partial definition
 - [ ] Serialization level caching
 - [ ] Docs

src/index.ts

@@ -1,4 +1,4 @@
-export { Server } from './lib/server'
+export { ProtoCat } from './lib/server/application'
 export { CallType } from './lib/call-types'
-export { onError } from './lib/middleware/on-error'
-export { Middleware } from './lib/context'
+export { onError } from './lib/server/middleware/on-error'
+export { Middleware, ServiceImplementation } from './lib/server/call'

src/lib/call-types.ts

@@ -1,9 +1,9 @@
 /** Call types aligned with grpc core library */
 export enum CallType {
-  BIDI = 'bidi',
-  SERVER_STREAM = 'serverStream',
-  CLIENT_STREAM = 'clientStream',
-  UNARY = 'unary',
+  Bidi = 'bidi',
+  ServerStream = 'serverStream',
+  ClientStream = 'clientStream',
+  Unary = 'unary',
 }
 
 /** Assign call type from generated definition */
@@ -12,8 +12,8 @@ export const stubToType = (
 ) =>
   s.responseStream
     ? s.requestStream
-      ? CallType.BIDI
-      : CallType.SERVER_STREAM
+      ? CallType.Bidi
+      : CallType.ServerStream
     : s.requestStream
-    ? CallType.CLIENT_STREAM
-    : CallType.UNARY
+    ? CallType.ClientStream
+    : CallType.Unary

src/lib/context.ts

@@ -0,0 +1,24 @@
+import { EventEmitter } from 'events'
+
+// List object keys without index signatures
+// KnownKeys<{ [index: string]: string; foo: string }> = 'foo'
+type KnownKeys<T> = {
+  [K in keyof T]: string extends K ? never : number extends K ? never : K
+} extends { [_ in keyof T]: infer U }
+  ? U
+  : never
+
+// Remove index signature keys from object
+// RemoveIdxSgn<{ [index: string]: string; foo: string }> = { foo: string }
+export type RemoveIdxSgn<T> = Pick<T, KnownKeys<T>>
+
+export type TypedOnData<E extends EventEmitter, T> = Omit<E, 'on'> & {
+  on(event: 'close', listener: () => void): E
+  on(event: 'data', listener: (chunk: T) => void): E
+  on(event: 'end', listener: () => void): E
+  on(event: 'error', listener: (err: Error) => void): E
+  on(event: 'pause', listener: () => void): E
+  on(event: 'readable', listener: () => void): E
+  on(event: 'resume', listener: () => void): E
+  on(event: string | symbol, listener: (...args: any[]) => void): E
+}

src/lib/grpc-helpers.ts src/lib/misc/grpc-helpers.tssrc/lib/grpc-helpers.ts renamed to src/lib/misc/grpc-helpers.ts

@@ -1,33 +1,36 @@
 import * as grpc from '@grpc/grpc-js'
 import { ChannelOptions } from '@grpc/grpc-js/build/src/channel-options'
-import { ServiceImplementation, Middleware } from './context'
-import { stubToType } from './call-types'
-import { bindAsync, tryShutdown } from './grpc-helpers'
-import { composeMiddleware } from './middleware'
+import { ServiceImplementation, Middleware } from './call'
+import { stubToType } from '../call-types'
+import { bindAsync, tryShutdown } from '../misc/grpc-helpers'
+import { composeMiddleware } from './middleware/compose-middleware'
 
-export class Server {
-  /** Underlaying gRPC server */
+export class ProtoCat<Extension = {}> {
+  /** Underlying gRPC server */
   public server: grpc.Server
   /** Map of loaded generated method stubs */
   public methodDefinitions: Record<string, grpc.MethodDefinition<any, any>>
   /** Map of loaded method service implementations */
   public serviceHandlers: Record<string, Middleware[]>
   /** Global middleware functions */
-  public middleware: Middleware[]
+  public middleware: Array<Middleware<Extension>>
   constructor(options?: ChannelOptions) {
     this.server = new grpc.Server(options)
     this.methodDefinitions = {}
     this.middleware = []
     this.serviceHandlers = {}
   }
 
-  public use(...middleware: Middleware[]) {
+  public use(...middleware: Array<Middleware<Extension>>) {
     this.middleware.push(...middleware)
   }
 
   public addService<
     T extends grpc.ServiceDefinition<grpc.UntypedServiceImplementation>
-  >(serviceDefinition: T, serviceImplementation: ServiceImplementation<T>) {
+  >(
+    serviceDefinition: T,
+    serviceImplementation: ServiceImplementation<T, Extension>
+  ) {
     for (const methodName in serviceDefinition) {
       // Path is FQN with namespace to avoid collisions
       const key = serviceDefinition[methodName].path
@@ -87,23 +90,23 @@ const wrapToHandler = (
   }
 
   return async (
-    call: any, // grpc.ServerReadableStream<any, any> | grpc.ServerUnaryCall<any, any> | grpc.ServerDuplexStream<any, any> | grpc.ServerWritableStream<any, any>
+    grpcCall: any, // grpc.ServerReadableStream<any, any> | grpc.ServerUnaryCall<any, any> | grpc.ServerDuplexStream<any, any> | grpc.ServerWritableStream<any, any>
     cb?: grpc.sendUnaryData<any> // Only for call grpc.ServerReadableStream<any, any> | grpc.ServerUnaryCall<any, any>, missing otherwise
   ) => {
-    const ctx = createContext(call)
+    const call = createContext(grpcCall)
     // @ts-ignore: Not part of public API, but only way to pair message to method
-    ctx.response = new methodDefinition.responseType()
+    call.response = new methodDefinition.responseType()
     try {
-      await methodHandler(ctx)
-      ctx.sendMetadata(ctx.initialMetadata)
+      await methodHandler(call)
+      call.sendMetadata(call.initialMetadata)
       if (cb) {
-        cb(null, ctx.response, ctx.trailingMetadata)
+        cb(null, call.response, call.trailingMetadata)
       }
     } catch (e) {
       if (cb) {
-        cb(e, null, ctx.trailingMetadata)
+        cb(e, null, call.trailingMetadata)
       } else {
-        call.emit('error', e)
+        grpcCall.emit('error', e)
       }
     }
   }