Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/baderkha/typesense

An Unofficial Typesense client that uses generics
https://github.com/baderkha/typesense

client elastic generics go rest typesense

Last synced: about 1 month ago
JSON representation

An Unofficial Typesense client that uses generics

Awesome Lists containing this project

README 

        
Typesense Generic Client GoLang [Unofficial]



This project is an implementation of the rest api proided by Typesense .



For more information see https://typesense.org/docs/ . I would like to iterate that this is the Unofficial package.



If you're looking for the offical one please see https://github.com/typesense/typesense-go



## Features



- Support For Generics out of the box .

  - no passing interface{} anys

  - no Unmarshalling on your end

- Testability from a consumer's perspective built in the code

  - All the Clients in the code bases are interfaces

  - Mocks are also provided for all of them if you don't want to generate your own

- Modular Implementation

  - You can extend the imlementations any way you like

- Fluent Argument Builders

- Migration Built out of the box .

  - Automatic migration and Manual Migration Supported.

  - Aliasing ..etc

  - Tools to help you do your own migration logic

- Schema Attributes like index , sorting , facets ... etc supported with struct tags

- Logging Support (thanks to the amazing http client resty ! see https://github.com/go-resty/resty)



## Quick Start Guide



Quickly Creating a new instance , indexing and querying the documents



### 1) Installation



```bash

go get github.com/baderkha/typesense

```



### 2) Code Example With Basic Operations



- For Full Example go to https://github.com/baderkha/typesense/blob/main/cmd/example/example.go



* Define a Type



  ```go



  // UserData : a Typical model you would write for your api

  type UserData struct {

  	// your id , can be generated by you uuid , or typesense can handle it

  	ID        string `json:"id"`

  	FirstName string `json:"first_name" tsense_required:"1"`

  	// by default all fields are optional unless you specify otherwise

  	LastName string `json:"last_name" tsense_required:"true"`

  	// faceting

  	Email string `json:"email" tsense_required:"true" tsense_facet:"1"`

  	// default sorting

  	GPA float32 `json:"gpa" tsense_default_sort:"1"`

  	// default type any int is int64 , you can always override this

  	Visit     int32 `json:"visit" tsense_type:"int32"`

  	IsDeleted bool  `json:"is_deleted"  tsense_required:"true"`

  	// by default time.Time is not supported since time isn't supported in typesense

  	//this overrides this issue by turning your time data into unix epoch

  	CreatedAt types.Timestamp `json:"created_at"  tsense_required:"true"`

  	UpdatedAt types.Timestamp `json:"updated_at"  tsense_required:"true"`

  }

  ```



* Init Client



  ```go

  apiKey := os.Getenv("TYPESENSE_API_KEY")

  host := os.Getenv("TYPESENSE_URL")

  logging := os.Getenv("TYPESENSE_LOGGING") == "TRUE"

  // main facade client

  client := typesense.NewClient[UserData](apiKey, host, logging)

  ```



* Migrate Model



  ```go

  // this method will 2 resources

  // first is a collection with a version ie user_data_2022-10-10_

  // second it will create an alias called user_data -> user_data_2022-10-10_

  //

  // See the typesense documentation to understand the benefits of aliasing

  err := client.Migration().Auto()

  if err != nil {

  	log.Fatal(err)

  }



  ```



* Index A Document



  ```go

  // Document

  // This method will creat a record under your collection

  // your document will know exactly what collection to write it to

  err = client.Document().Index(

    &UserData{

  	ID:        "some-uuid-for-this",

  	FirstName: "Barry",

  	LastName:  "Allen",

  	Email:     "[email protected]",

  	GPA:       4.00,

  	Visit:     50,

  	IsDeleted: false,

  	CreatedAt: types.Timestamp(time.Now()),

  	UpdatedAt: types.Timestamp(time.Now()),

  	},

  )

  ```



* Get Document

  ```go

  // Document

  // this method will get the record we just created and return back

  // a *User pointer without us having to init a var and pass as reference

  // neet right ?

  doc, err := client.Document().GetById("some-uuid-for-this")

  ```

* Search For Documents



  ```go



  // english : give me everyone with the name of barry by first and last name

  // Give me that data as the first page + 20 per page max

  //

  // this is fluent so you can keep adding args and it will build the struct for you

  searchQuery := typesense.

  	NewSearchParams().

  	AddSearchTerm("barry").

  	AddQueryBy("first_name,last_name").

  	AddPage(1).

  	AddPerPage(20)



  // Search

  // This method will do a filter search / fuzzy search

  // res is of type typesense.SearchResult[UserData]

  res, err := client.Search().Search(searchQuery)

  ```



---



## Author : Ahmad Baderkhan ❤️☀️💚



## License : MIT