livegollection

README

livegollection

livegollection is a Golang library for live data synchronization between backend and frontend of a custom user-implemented collection. It's aimed for web applications since it works over websockets.

To interact with livegollection from client-side JavaScript/TypeScript check out livegollection-client.

Install

To install livegollection you just need to:

go get github.com/m1gwings/livegollection

NOTE: livegollection makes use of type parameters so you need go1.18 or above in order to use it (at the time of writing go1.18 has not been released yet but there is a beta version and a release candidate available).

How to use

Define the user-implemented collection

We need to define the user-implemented collection that is going to be synchronized between the server and multiple web-clients with live updates.

This collection must satisfy the livegollection.Collection interface which requires the following methods: All, Item, Create, Update, Delete. This is a simple template that you can use for implementing such a collection (you need to substitute IdType with a concrete type for items' id):

cat mycollection/mycollection.go

package mycollection

// IMPORTANT: export all the fields of MyItem, livegollection internally uses json.Marshal.
type MyItem struct {
	Id       IdType         `json:"id,omitempty"`
	FieldOne TypeOfFieldOne `json:"fieldOne,omitempty"`
    FieldTwo TypeOfFIeldTwo `json:"fieldTwo,omitempty"`
    // ...
}

func (myItem MyItem) ID() IdType {
    return myItem.Id
}

type MyCollection struct {
    // ...
}

// NewMyCollection creates and initialize an instance of MyCollection.
func NewMyCollection() (*MyCollection, error) {
    
}

// All retreives all the items in MyCollecttion and returns them in a slice.
func (myColl *MyCollection) All() ([]MyItem, error) {

}

// Item retreives the item with the given ID from MyCollection and returns it.
func (myColl *MyCollection) Item(ID IdType) (MyItem, error) {

}

// Create adds the given item to the collection and returns it AFTER having set its id.
func (myColl *MyCollection) Create(myItem MyItem) (MyItem, error) {
    // ...
    // Set item id
    myItem.Id = // ...
    // ...
    return myItem, nil
}

// Update updates the given item in the collection.
func (myColl *MyCollection) Update(myItem MyItem) error {

}

// Delete deletes the given item from the collection.
func (myColl *MyCollection) Delete(ID IdType) error {

}

Implement server executable

It's time to implement our backend logic and add to our server the livegollection handler:

cat server/main.go

package main

import (
    "github.com/m1gwings/livegollection"
    "module-name/mycollection"
)

func main() {
	// ...

	myColl, err := mycollection.NewMyCollection()
	if err != nil {
		log.Fatal(fmt.Errorf("error when creating MyCollection: %v", err))
	}

	// When we create the LiveGollection we need to specify the type parameters for items' id and items themselves.
	liveGoll := livegollection.NewLiveGollection[IdType, mycollection.MyItem](context.TODO(), myColl, log.Default())

	// After we created liveGoll, to enable it we just need to register a route handled by liveGoll.Join.
	http.HandleFunc("/livegollection", liveGoll.Join)

	log.Fatal(http.ListenAndServe("localhost:8080", nil))
}
// ...

As you can see, once you have implemented MyCollection you just need to register an HTTP handler and server-side livegollection is ready to use.

Further steps

As anticipated to interact with server-side livegollection from client-side JavaScript/TypeScript check out livegollection-client.

Example app

If you want a concrete example of usage of livegollection and livegollection-client check out this example app.

Documentation

Overview

Package livegollection implements a library for live synchronization between backend and frontend of a custom user-implemented collection. It's aimed for web applications since it works over websockets.

Index

• type Collection
• type Item
• type LiveGollection
  • func NewLiveGollection[IdType any, ItemType Item[IdType]](ctx context.Context, coll Collection[IdType, ItemType], logger *log.Logger) *LiveGollection[IdType, ItemType]
  • func (lG *LiveGollection[IdType, ItemType]) Join(w http.ResponseWriter, r *http.Request)

Types

type Collection

type Collection[IdType any, ItemType Item[IdType]] interface {
	All() ([]ItemType, error)
	Item(ID IdType) (ItemType, error)
	Create(ItemType) (ItemType, error)
	Update(ItemType) error
	Delete(ID IdType) error
}

Collection is the interface that the user-implemented collection (which is going to be synchronized) must satisfy. It wraps the following methods: All, Item, Create, Update, Delete. All returns all the items inside the collection (as a slice of items) or an error if something goes wrong. Item takes an id and returns the correspondant item or an error if something goes wrong. Create takes an item which will be added to the collection. It returns the newly added item AFTER its id field has been set or an error if something goes wrong. Update takes an item which will be updated inside the collection and returns an error if something goes wrong. Delete takes an id and deletes the correspondant item from the collection. It returns an error if something goes wrong. It takes two type parameters: IdType and ItemType. The first is the type of items' id, the second is the type of items that must satisfy Item[IdType] interface.

type Item

type Item[IdType any] interface {
	ID() IdType
}

Item is the interface that the items of the user-implemented collection (which is going to be synchronized) must satisfy. It wraps the ID method, which is supposed to return the item's id as an IdType where IdType is a type parameter.

type LiveGollection

type LiveGollection[IdType any, ItemType Item[IdType]] struct {
	// contains filtered or unexported fields
}

LiveGollection represents the instance of the livegollection server. It handles the pool of clients by sending and receiving live updates and calls the appropriate methods on the underlying user-implemented collection to keep it synchronized. It takes two type parameters: IdType and ItemType. The first is the type of items' id, the second is the type of items that must satisfy Item[IdType] interface.

func NewLiveGollection

func NewLiveGollection[IdType any, ItemType Item[IdType]](ctx context.Context,
	coll Collection[IdType, ItemType], logger *log.Logger) *LiveGollection[IdType, ItemType]

NewLiveGollection returns a pointer to a new LiveGollection instance after having set it properly. It takes the following parameters: ctx, coll, logger. ctx is the Context object that can be used to terminate the LiveGollection and close the connections with all the clients in the pool. Pass context.TODO() if it's unclear which context to use. coll is the istance of the underlying user-implemented collection that will be synchronized. logger is where all the errors and messages will be reported. Pass nil if logging is not needed. It takes two type parameters: IdType and ItemType. The first is the type of items' id in coll, the second is the type of items in coll that must satisfy Item[IdType] interface.

func (*LiveGollection[IdType, ItemType]) Join

func (lG *LiveGollection[IdType, ItemType]) Join(w http.ResponseWriter, r *http.Request)

Join is an http.HandlerFunc. The proper way to set the websocket server-side handler of livegollection is to add a route to this function with, for example, http.HandleFunc("route/to/livegollection", liveGoll.Join) .