github.com/go-haru/field@v0.0.2/README.md (about)

     1  # Field
     2  
     3  [![Go Reference](https://pkg.go.dev/badge/github.com/go-haru/field.svg)](https://pkg.go.dev/github.com/go-haru/field)
     4  [![License](https://img.shields.io/github/license/go-haru/field)](./LICENSE)
     5  [![Release](https://img.shields.io/github/v/release/go-haru/field.svg?style=flat-square)](https://github.com/go-haru/field/releases)
     6  [![Go Test](https://github.com/go-haru/field/actions/workflows/go.yml/badge.svg)](https://github.com/go-haru/field/actions)
     7  [![Go Report Card](https://goreportcard.com/badge/github.com/go-haru/field)](https://goreportcard.com/report/github.com/go-haru/field)
     8  
     9  provides key-value list for instant json generation, which drives data collecting feature in [`log`](https://github.com/go-haru/log) and [`errors`](https://github.com/go-haru/errors).
    10  
    11  ## Usage
    12  
    13  When observing or debug with complicated transaction with changeable data, we always need on-site data for metric or analysing purpose.
    14  
    15  With this repo, we can describe named data as `field` and append id to log or error
    16  
    17  ### field
    18  
    19  consists of a string name and arbitrary type content, it can be encoded as json bytes or write to a buffer:
    20  
    21  ```go
    22  type Field struct {
    23  	Key string // name
    24  	Content    // wrapped value
    25  }
    26  
    27  func (f Field) EncodeJSON(buffer Buffer) error { ... }
    28  
    29  func (f Field) MarshalJSON() ([]byte, error) { ... }
    30  ```
    31  
    32  We made different functions for common data types, so you need care noting about wrapping value
    33  
    34  ```go
    35  func Bool(key string, val bool) Field
    36  
    37  func Bools(key string, valArr []bool) Field
    38  
    39  func Error(key string, err error) Field
    40  
    41  func Float64(key string, val float64) Field
    42  
    43  // ... refer to go doc for more impl
    44  ```
    45  Now, we can add field to logger or error (refer to their repo for more info):
    46  
    47  ```go
    48  // data for logger
    49  logger.With(field.String("traceId", id)).Debug("data created")
    50  
    51  // data for error
    52  errors.Note(err, field.String("traceId", id))
    53  
    54  ```
    55  
    56  ### fields
    57  
    58  is list of `field`, which provides simple map-like operation and can be encoded to json object 
    59  
    60  ```go
    61  type Fields []Field
    62  
    63  func (f Fields) Unique() []Field 
    64  func (f Fields) Has(key string) bool
    65  func (f Fields) Get(key string) (Field, bool) 
    66  func (f Fields) Export() map[string]any 
    67  func (f Fields) EncodeJSON(buf Buffer) (err error) 
    68  func (f Fields) MarshalJSON() (dst []byte, err error) 
    69  ```
    70  
    71  ## Testing
    72  
    73  All types of field are supposed to be finely tested in [field_test.go](./field_test.go). you ca run test with command:
    74  
    75  ```shell
    76  go test ./...
    77  ```
    78  [Github Action](https://github.com/go-haru/field/actions) is also enabled for main branch, every release shall pass all tests.
    79  
    80  ## Contributing
    81  
    82  For convenience of PM, please commit all issue to [Document Repo](https://github.com/go-haru/go-haru/issues).
    83  
    84  ## License
    85  
    86  This project is licensed under the `Apache License Version 2.0`.
    87  
    88  Use and contributions signify your agreement to honor the terms of this [LICENSE](./LICENSE).
    89  
    90  Commercial support or licensing is conditionally available through organization email.