firead

README

firead

Create Go microservices that read Firestore documents.

Very easy to use, create a working service by adding just one line of code to your main method.

Either read documents with a string ID:

firead.RunStringId()

Or read documents with an int ID:

firead.RunIntId()

Examples

Try working examples of firead here

Getting started

Create a new Go project

mkdir firead-example
cd firead-example
go mod init firead/example

Get firead

go get github.com/jonnyorman/firead

Add a main.go file with the following

package main

import "github.com/jonnyorman/firead"

func main() {
	firead.RunStringId()
}

Add a firead-config.json file with the following

{
    "projectID": "your-firebase-project",
    "collectionName": "FirestoreCollection"
}

Tidy and run with access to a Firebase project or emulator

    go mod tidy
    go run .

Submit a GET to the service's /{id} path, replaceing {id} with the ID of the document you want to read. You will get a 200 response with the document in the response body.

You can also create a struct with the data you want to read from Firestore. Create a struct and use it:

package main

import "github.com/jonnyorman/firead"

type DocumentModel struct {
	Prop1 string
	Prop2 int
}

func main() {
	firead.RunTypedStringId[DocumentModel]()
}

Environment configuration

The configuration can also be provided by the environment with the following keys:

• projectID - PROJECT_ID
• collectionName - COLLECTION_NAME

A combination of the firead-config.json file and environment variables can be used. For example, the project ID could be provided as the PROJECT_ID environment variable, while the collection name is provided with the following configuration file:

{
    "collectionName": "FirestoreCollection"
}

If a configuration value is provided in both firead-config.json and the environment, then the configuration file with take priority. For example, if the PROJECT_ID envronment variable has value "env-project-id" and the following firead-config.json file is provided:

{
    "projectID": "config-project-id",
    "collectionName": "FirestoreCollection"
}

then the project ID will be "config-project-id".

Running integration tests

To run integration tests in Docker against a local Firebase emulator, run the following:

• For typed documents with int IDs: make test-firead-int-id-typed
• For untyped documents with int IDs: make test-firead-int-id-untyped
• For typed documents with string IDs: make test-firead-string-id-typed
• For untyped documents with string IDs: make test-firead-string-id-untyped

Documentation

Index

• func BuildApplication[TDocument any, TId Id](idReader ParamReader[TId], snapshotRetriever SnapshotRetriever[TId], ...) *fireworks.Application
• func BuildApplicationMapped[TDocument any, TResponse any, TId Id](idReader ParamReader[TId], snapshotRetriever SnapshotRetriever[TId], ...) *fireworks.Application
• func RunMapped[TDocument any, TResponse any, TId Id](idReader ParamReader[TId], snapshotRetriever SnapshotRetriever[TId], ...)
• func RunTyped[TDocument any, TId Id](idReader ParamReader[TId], snapshotRetriever SnapshotRetriever[TId], ...)
• type DataDecoder
• type DataHandler
• type DataMapper
• type DecodedDataHandler
  • func NewDecodedDataHandler[T any]() *DecodedDataHandler[T]
  • func (this DecodedDataHandler[T]) Handle(decodedData T) (int, any)
• type DecodedDataHandlerMapped
  • func NewDecodedDataHandlerMapped[TDocument any, TResponse any](documentToResponseMapper DataMapper[TDocument, TResponse]) *DecodedDataHandlerMapped[TDocument, TResponse]
  • func (this DecodedDataHandlerMapped[TDocument, TResponse]) Handle(decodedData TDocument) (int, any)
• type DocumentRequestHandler
  • func NewDocumentRequestHandler[TDocument any, TId Id](paramReader ParamReader[TId], responseResolver ResponseResolver[TId], ...) *DocumentRequestHandler[TDocument, TId]
  • func (this DocumentRequestHandler[TDocument, TId]) Handle(ginContext *gin.Context)
• type DocumentResponseResolver
  • func NewDocumentResponseResolver[TId Id](configuration *fireworks.Configuration, ...) *DocumentResponseResolver[TId]
  • func (this DocumentResponseResolver[TId]) Resolve(id TId) (int, any)
• type ExistingDocumentDataHandler
  • func NewExistingDocumentDataHandler[T any](dataDecoder DataDecoder[T], decodedDataHandler DataHandler[T]) *ExistingDocumentDataHandler[T]
  • func (this ExistingDocumentDataHandler[T]) Handle(data map[string]interface{}) (int, any)
• type Id
• type IdSnapshotRetriever
  • func NewIdSnapshotRetriever() *IdSnapshotRetriever
  • func (this IdSnapshotRetriever) Retrieve(collection *firestore.CollectionRef, id string) *firestore.DocumentSnapshot
• type JsonResponseWriter
  • func NewJsonResponseWriter() *JsonResponseWriter
  • func (this JsonResponseWriter) Write(response Response, code int, body any)
• type MapStructureDataDecoder
  • func NewMapStructureDataDecoder[T any]() *MapStructureDataDecoder[T]
  • func (this MapStructureDataDecoder[T]) Decode(data map[string]interface{}) T
• type NoDataHandler
• type NonExistingDocumentHandler
  • func NewNonExistingDocumentHandler() *NonExistingDocumentHandler
  • func (this NonExistingDocumentHandler) Handle() (int, any)
• type ParamProvider
• type ParamReader
• type Response
• type ResponseResolver
• type ResponseWriter
• type SnapshotRetriever

Functions

func BuildApplication

func BuildApplication[TDocument any, TId Id](
	idReader ParamReader[TId],
	snapshotRetriever SnapshotRetriever[TId],
	configuration *fireworks.Configuration,
) *fireworks.Application

func BuildApplicationMapped

func BuildApplicationMapped[TDocument any, TResponse any, TId Id](
	idReader ParamReader[TId],
	snapshotRetriever SnapshotRetriever[TId],
	documentToResponseMapper DataMapper[TDocument, TResponse],
	configuration *fireworks.Configuration,
) *fireworks.Application

func RunMapped

func RunMapped[TDocument any, TResponse any, TId Id](
	idReader ParamReader[TId],
	snapshotRetriever SnapshotRetriever[TId],
	documentToResponseMapper DataMapper[TDocument, TResponse],
	configuration *fireworks.Configuration,
)

func RunTyped

func RunTyped[TDocument any, TId Id](
	idReader ParamReader[TId],
	snapshotRetriever SnapshotRetriever[TId],
	configuration *fireworks.Configuration,
)

Types

type DataDecoder

type DataDecoder[T any] interface {
	Decode(map[string]interface{}) T
}

type DataHandler

type DataHandler[TData any] interface {
	Handle(data TData) (int, any)
}

type DataMapper

type DataMapper[TFrom any, TTo any] interface {
	Map(dataFrom TFrom) TTo
}

type DecodedDataHandler

type DecodedDataHandler[T any] struct{}

func NewDecodedDataHandler

func NewDecodedDataHandler[T any]() *DecodedDataHandler[T]

func (DecodedDataHandler[T]) Handle

func (this DecodedDataHandler[T]) Handle(decodedData T) (int, any)

type DecodedDataHandlerMapped

type DecodedDataHandlerMapped[TDocument any, TResponse any] struct {
	// contains filtered or unexported fields
}

func NewDecodedDataHandlerMapped

func NewDecodedDataHandlerMapped[TDocument any, TResponse any](
	documentToResponseMapper DataMapper[TDocument, TResponse],
) *DecodedDataHandlerMapped[TDocument, TResponse]

func (DecodedDataHandlerMapped[TDocument, TResponse]) Handle

func (this DecodedDataHandlerMapped[TDocument, TResponse]) Handle(decodedData TDocument) (int, any)

type DocumentRequestHandler

type DocumentRequestHandler[TDocument any, TId Id] struct {
	// contains filtered or unexported fields
}

func NewDocumentRequestHandler

func NewDocumentRequestHandler[TDocument any, TId Id](

	paramReader ParamReader[TId],
	responseResolver ResponseResolver[TId],
	responseSetter ResponseWriter,
) *DocumentRequestHandler[TDocument, TId]

func (DocumentRequestHandler[TDocument, TId]) Handle

func (this DocumentRequestHandler[TDocument, TId]) Handle(ginContext *gin.Context)

type DocumentResponseResolver

type DocumentResponseResolver[TId Id] struct {
	// contains filtered or unexported fields
}

func NewDocumentResponseResolver

func NewDocumentResponseResolver[TId Id](
	configuration *fireworks.Configuration,
	snapshotRetriever SnapshotRetriever[TId],
	existingDocumentDataHandler DataHandler[map[string]interface{}],
	nonExistingDocumentHandler NoDataHandler,
) *DocumentResponseResolver[TId]

func (DocumentResponseResolver[TId]) Resolve

func (this DocumentResponseResolver[TId]) Resolve(id TId) (int, any)

type ExistingDocumentDataHandler

type ExistingDocumentDataHandler[T any] struct {
	// contains filtered or unexported fields
}

func NewExistingDocumentDataHandler

func NewExistingDocumentDataHandler[T any](
	dataDecoder DataDecoder[T],
	decodedDataHandler DataHandler[T],
) *ExistingDocumentDataHandler[T]

func (ExistingDocumentDataHandler[T]) Handle

func (this ExistingDocumentDataHandler[T]) Handle(data map[string]interface{}) (int, any)

type Id

type Id interface {
	string | int
}

type IdSnapshotRetriever

type IdSnapshotRetriever struct{}

func NewIdSnapshotRetriever

func NewIdSnapshotRetriever() *IdSnapshotRetriever

func (IdSnapshotRetriever) Retrieve

func (this IdSnapshotRetriever) Retrieve(collection *firestore.CollectionRef, id string) *firestore.DocumentSnapshot

type JsonResponseWriter

type JsonResponseWriter struct{}

func NewJsonResponseWriter

func NewJsonResponseWriter() *JsonResponseWriter

func (JsonResponseWriter) Write

func (this JsonResponseWriter) Write(response Response, code int, body any)

type MapStructureDataDecoder

type MapStructureDataDecoder[T any] struct{}

func NewMapStructureDataDecoder

func NewMapStructureDataDecoder[T any]() *MapStructureDataDecoder[T]

func (MapStructureDataDecoder[T]) Decode

func (this MapStructureDataDecoder[T]) Decode(data map[string]interface{}) T

type NoDataHandler

type NoDataHandler interface {
	Handle() (int, any)
}

type NonExistingDocumentHandler

type NonExistingDocumentHandler struct{}

func NewNonExistingDocumentHandler

func NewNonExistingDocumentHandler() *NonExistingDocumentHandler

func (NonExistingDocumentHandler) Handle

func (this NonExistingDocumentHandler) Handle() (int, any)

type ParamProvider

type ParamProvider interface {
	Param(key string) string
}

type ParamReader

type ParamReader[T Id] interface {
	Read(paramProvider ParamProvider) T
}

type Response

type Response interface {
	JSON(code int, obj any)
}

type ResponseResolver

type ResponseResolver[TId Id] interface {
	Resolve(id TId) (int, any)
}

type ResponseWriter

type ResponseWriter interface {
	Write(response Response, code int, body any)
}

type SnapshotRetriever

type SnapshotRetriever[TId Id] interface {
	Retrieve(collection *firestore.CollectionRef, id TId) *firestore.DocumentSnapshot
}