github.com/go-generalize/volcago@v1.7.0/README.md (about)

     1  # volcago
     2  
     3  Automatically generate code used by Cloud Firestore.  
     4  
     5  [日本語ドキュメント](./docs/ja.md)
     6  
     7  # Installation
     8  Recommend that you drop the binary from the release and use it.  
     9  Also, possible with `go install` ↓
    10  ```console
    11  $ go install github.com/go-generalize/volcago/cmd/volcago@latest
    12  ```
    13  
    14  # Usage
    15  
    16  ```go
    17  package task
    18  
    19  import (
    20  	"time"
    21  )
    22  
    23  //go:generate volcago Task
    24  
    25  type Task struct {
    26  	ID      string          `firestore:"-"           firestore_key:""`
    27  	Desc    string          `firestore:"description" indexer:"suffix,like" unique:""`
    28  	Done    bool            `firestore:"done"        indexer:"equal"`
    29  	Count   int             `firestore:"count"`
    30  	Created time.Time       `firestore:"created"`
    31  	Indexes map[string]bool `firestore:"indexes"`
    32  }
    33  ```
    34  By writing a line starting with `go:generate`, the model for firestore will be automatically generated.  
    35  
    36  When used in SubCollection, add the argument `-sub-collection`.  
    37  
    38  If you want to use Meta information (such as CreatedAt and Version used in optimistic exclusive lock) together,
    39  you can invalidate it by removing the argument `-disable-meta`.  
    40  
    41  The format of the Meta structure is as follows.
    42  ```go
    43  type Meta struct {
    44  	CreatedAt time.Time
    45  	CreatedBy string
    46  	UpdatedAt time.Time
    47  	UpdatedBy string
    48  	DeletedAt *time.Time
    49  	DeletedBy string
    50  	Version   int
    51  }
    52  ```
    53  
    54  Also, one element in the struct must have an element with `firestore_key:""`.  
    55  The type of this element must be `string`.  
    56  ID is automatically generated by setting `firestore_key:"auto"`.  
    57  
    58  If you execute `go generate` in this state, the model will be generated in a file with the suffix` _gen.go`.  
    59  ```commandline
    60  $ go generate
    61  ```
    62  
    63  ## Unique constraint
    64  If there is a tag called `unique`, a document for unique constraints will be generated in another collection called Unique.  
    65  Use when you do not want to allow duplicates such as phone numbers and email addresses.  
    66  The type of this element must be `string`.
    67  
    68  ## Search diversity
    69  The existence of a field called `Indexes` (`map[string]bool` type) enables n-gram search using _**[xim](https://github.com/go-utils/xim)**_.  
    70  Corresponding search is prefix/suffix/partial/exact match. (tag: prefix/suffix/like/equal)  
    71  Since _**xim**_ uses only Unigram Bigram, it is prone to noise (eg, when `東京都` searches in `京都`, it hits).
    72  
    73  ### Search query
    74  Task.Desc = "Hello, World!".
    75  - Partial match search
    76  ```go
    77  param := &model.TaskSearchParam{
    78  	Desc: model.NewQueryChainer().Filters("o, Wor", model.FilterTypeAddBiunigrams),
    79  }
    80  
    81  tasks, err := taskRepo.Search(ctx, param, nil)
    82  if err != nil {
    83  	// error handling
    84  }
    85  ```
    86  
    87  - Prefix match search
    88  ```go
    89  param := &model.TaskSearchParam{
    90  	Desc: model.NewQueryChainer().Filters("Hell", model.FilterTypeAddPrefix),
    91  }
    92  
    93  tasks, err := taskRepo.Search(ctx, param, nil)
    94  if err != nil {
    95  	// error handling
    96  }
    97  ```
    98  
    99  - Suffix match search
   100  ```go
   101  param := &model.TaskSearchParam{
   102  	Desc: model.NewQueryChainer().Filters("orld!", model.FilterTypeAddSuffix),
   103  }
   104  
   105  tasks, err := taskRepo.Search(ctx, param, nil)
   106  if err != nil {
   107  	// error handling
   108  }
   109  ```
   110  
   111  - Exact match search
   112  ```go
   113  chainer := model.NewQueryChainer
   114  param := &model.TaskSearchParam{
   115  	Desc: chainer().Filters("Hello, World!", model.FilterTypeAdd),
   116  	Done: chainer().Filters(true, model.FilterTypeAddSomething), // Use Add Something when it is not a string.
   117  }
   118  
   119  tasks, err := taskRepo.Search(ctx, param, nil)
   120  if err != nil {
   121  	// error handling
   122  }
   123  ```
   124  
   125  - Paging search
   126  ```go
   127  param := &model.TaskSearchParam{
   128  	Done:        model.NewQueryChainer().Equal(true),
   129  	CursorLimit: 5,
   130  	// CursorKey: "document id",
   131  }
   132  
   133  tasks, pagingResult, err := taskRepo.SearchByParam(ctx, param)
   134  if err != nil {
   135  	// error handling
   136  }
   137  // pagingResult.NextPagingKey = "next document id"
   138  ```
   139  
   140  ### Query builder
   141  The code for the query builder called `query_builder_gen.go` is generated.  
   142  
   143  ```go
   144  qb := model.NewQueryBuilder(taskRepo.GetCollection())
   145  qb.GreaterThan("count", 3)
   146  qb.LessThan("count", 8)
   147  
   148  tasks, err := taskRepo.Search(ctx, nil, qb.Query())
   149  if err != nil {
   150  	// error handling
   151  }
   152  ```
   153  
   154  ### Strict update
   155  Use a function called `StrictUpdate`.  
   156  By using this, firestore.Increment etc. can also be used.  
   157  Uniquely constrained fields are not available.
   158  
   159  ```go
   160  param := &model.TaskUpdateParam{
   161  	Done:    false,
   162  	Created: firestore.ServerTimestamp,
   163  	Count:   firestore.Increment(1),
   164  }
   165  if err = taskRepo.StrictUpdate(ctx, id, param); err != nil {
   166  	// error handling
   167  }
   168  ```
   169  
   170  ## Examples
   171  [Generated code example.](./examples)
   172  
   173  ## License
   174  - Under the [MIT License](./LICENSE)
   175  - Copyright (C) 2021 go-generalize