Updated README

Author: cloudshiftchris

README.md

@@ -11,3 +11,61 @@
 [6]: https://goreportcard.com/report/github.com/cloudshiftinc/aws-lambda-demux
 [7]: https://codecov.io/gh/cloudshiftinc/aws-lambda-demux/branch/main/graph/badge.svg
 [8]: https://codecov.io/gh/cloudshiftinc/aws-lambda-demux
+
+Library to help Go developers handle multiple types of events (de-multiplexing) in AWS Lambda functions.
+
+# Getting Started
+
+The primary function of this library is to create events of a specific type and dispatch those to appropriate handlers.
+
+To do so the demuxxer is configured with `Factory` and `Handler` instances.
+
+Factories are responsible for determining the type of the event (based off the incoming JSON) and creating an instance of that event.
+
+Handlers are responsible for, well, handling that event.  Handlers are as used in [aws-lambda-go ](https://github.com/aws/aws-lambda-go), with the restriction
+of having a signature of `func(context.Context, *eventType) (*responseType, error)`.
+
+A minimal usage showing a lambda that handles REST API request and Websocket lifecycle events:
+
+```go
+// main.go
+package main
+
+import (
+  "github.com/aws/aws-lambda-go/lambda"
+  "github.com/cloudshiftinc/aws-lambda-demux"
+)
+
+func main() {
+
+  cfg := &demux.Cfg{
+    Factories: []demux.Factory{
+      func(ctx *demux.EventContext) any {
+        if demux.HasAttribute(ctx.event, "connectionId") {
+          return &events.APIGatewayWebsocketProxyRequest{}
+        }
+        return &events.APIGatewayProxyRequest{}
+      },
+    },
+    Handlers: []any{
+      func(ctx context.Context, event *events.APIGatewayWebsocketProxyRequest) (
+        *events.APIGatewayProxyResponse, error) {
+        // TODO - your code here to handle websocket event
+        return &events.APIGatewayProxyResponse{}, nil
+      },
+      func(ctx context.Context, event *events.APIGatewayProxyRequest) (
+        *events.APIGatewayProxyResponse,
+        error) {
+        // TODO - your code here to handle HTTP/REST event
+        return &events.APIGatewayProxyResponse{}, nil
+      },
+    },
+  }
+
+  lambda.Start(demux.NewHandler(cfg))
+}
+
+```
+
+This library is not limited to event types in aws-lambda-go; any event type (including your own custom ones) that as appropriate JSON mappings can be used.
+

demux/entry.go

@@ -10,7 +10,7 @@ func NewHandler(cfg *Cfg) any {
 		return errorHandler(err)
 	}
 
-	return func(ctx context.Context, rawEvent RawEvent) (any, error) {
+	return func(ctx context.Context, rawEvent map[string]any) (any, error) {
 		return processEvent(demuxCfg, ctx, rawEvent)
 	}
 }

demux/event.go

@@ -11,14 +11,14 @@ import (
 type Factory func(ctx *EventContext) any
 
 type EventContext struct {
-	event           RawEvent
-	resourceContext RawResourceContext
+	event           map[string]any
+	resourceContext map[string]any
 }
 
 func processEvent(
 	cfg *demuxCfg,
 	ctx context.Context,
-	rawEvent RawEvent) (any, error) {
+	rawEvent map[string]any) (any, error) {
 	event := createEvent(rawEvent, cfg.factories)
 	if event == nil {
 		return nil, errors.New("unable to determine event type for demux")
@@ -60,14 +60,14 @@ func processEvent(
 	return returnValues[0].Interface(), nil
 }
 
-func createEvent(rawEvent RawEvent, eventFactories []Factory) any {
+func createEvent(rawEvent map[string]any, eventFactories []Factory) any {
 	if rawEvent == nil {
-		rawEvent = RawEvent{}
+		rawEvent = map[string]any{}
 	}
 
-	rawResourceContext, ok := rawEvent["resourceContext"].(RawResourceContext)
+	rawResourceContext, ok := rawEvent["resourceContext"].(map[string]any)
 	if !ok {
-		rawResourceContext = RawResourceContext{}
+		rawResourceContext = map[string]any{}
 	}
 
 	ctx := &EventContext{

demux/eventStruct.go

@@ -1,16 +1,11 @@
 package demux
 
-type EventStruct map[string]any
-type RawEvent EventStruct
-
-type RawResourceContext EventStruct
-
-func (e EventStruct) HasAttribute(name string) bool {
+func HasAttribute(e map[string]any, name string) bool {
 	_, ok := e[name]
 	return ok
 }
 
-func (e EventStruct) StringAttributeValue(name string) *string {
+func StringAttributeValue(e map[string]any, name string) *string {
 	v, ok := e[name]
 	if !ok {
 		return nil
@@ -24,8 +19,8 @@ func (e EventStruct) StringAttributeValue(name string) *string {
 	return &vStr
 }
 
-func (e EventStruct) StringAttributeMatches(name string, value string) bool {
-	v := e.StringAttributeValue(name)
+func StringAttributeMatches(e map[string]any, name string, value string) bool {
+	v := StringAttributeValue(e, name)
 	if v == nil {
 		return false
 	}

demux/eventStruct_test.go

@@ -5,32 +5,32 @@ import (
 	"testing"
 )
 
-var mockEvent EventStruct = map[string]any{
+var mockEvent = map[string]any{
 	"abc":           "def",
 	"something":     true,
 	"somethingElse": 5,
 	"nullValue":     nil,
 }
 
 func TestHasAttributeWorks(t *testing.T) {
-	assert.True(t, mockEvent.HasAttribute("abc"))
-	assert.False(t, mockEvent.HasAttribute("def"))
+	assert.True(t, HasAttribute(mockEvent, "abc"))
+	assert.False(t, HasAttribute(mockEvent, "def"))
 }
 
 func TestStringAttributeValueWorks(t *testing.T) {
-	v := mockEvent.StringAttributeValue("abc")
+	v := StringAttributeValue(mockEvent, "abc")
 	assert.NotNil(t, v)
 	assert.Equal(t, "def", *v)
 
-	v = mockEvent.StringAttributeValue("something")
+	v = StringAttributeValue(mockEvent, "something")
 	assert.Nil(t, v)
 
-	v = mockEvent.StringAttributeValue("missingAttr")
+	v = StringAttributeValue(mockEvent, "missingAttr")
 	assert.Nil(t, v)
 }
 
 func TestStringAttributeMatches(t *testing.T) {
-	assert.True(t, mockEvent.StringAttributeMatches("abc", "def"))
-	assert.False(t, mockEvent.StringAttributeMatches("abc", "xxxf"))
-	assert.False(t, mockEvent.StringAttributeMatches("something", "true"))
+	assert.True(t, StringAttributeMatches(mockEvent, "abc", "def"))
+	assert.False(t, StringAttributeMatches(mockEvent, "abc", "xxxf"))
+	assert.False(t, StringAttributeMatches(mockEvent, "something", "true"))
 }

demux/handler_test.go

@@ -213,18 +213,27 @@ func TestHandlerMapCreationFailsWithBadHandler(t *testing.T) {
 }
 
 func foo() {
-	h := &someHandler{}
 	cfg := &Cfg{
 		Factories: []Factory{
 			func(ctx *EventContext) any {
-				return nil
+				if HasAttribute(ctx.event, "connectionId") {
+					return &events.APIGatewayWebsocketProxyRequest{}
+				}
+				return &events.APIGatewayProxyRequest{}
 			},
 		},
 		Handlers: []any{
 			func(ctx context.Context, event *events.APIGatewayWebsocketProxyRequest) (
 				*events.APIGatewayProxyResponse,
 				error) {
-				return h.HandleEvent(ctx, event)
+				// TODO - your code here to handle websocket event
+				return &events.APIGatewayProxyResponse{}, nil
+			},
+			func(ctx context.Context, event *events.APIGatewayProxyRequest) (
+				*events.APIGatewayProxyResponse,
+				error) {
+				// TODO - your code here to handle HTTP/REST event
+				return &events.APIGatewayProxyResponse{}, nil
 			},
 		},
 	}