{"id":27775759,"url":"https://github.com/hueristiq/hq-go-errors","last_synced_at":"2025-08-20T07:11:00.755Z","repository":{"id":290363416,"uuid":"974185499","full_name":"hueristiq/hq-go-errors","owner":"hueristiq","description":"A Go (Golang) package for rich, structured error handling with full stack-trace support, error wrapping, classification, and formatting.","archived":false,"fork":false,"pushed_at":"2025-07-07T12:42:00.000Z","size":86,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-07-07T13:26:19.471Z","etag":null,"topics":["error-formatting","error-handing","errors","go","golang"],"latest_commit_sha":null,"homepage":"https://pkg.go.dev/github.com/hueristiq/hq-go-errors","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hueristiq.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-04-28T11:40:52.000Z","updated_at":"2025-07-07T12:07:50.000Z","dependencies_parsed_at":"2025-04-28T12:47:05.861Z","dependency_job_id":"5bbe88fc-72ba-4f71-a39d-8f50019b3746","html_url":"https://github.com/hueristiq/hq-go-errors","commit_stats":null,"previous_names":["hueristiq/hq-go-errors"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/hueristiq/hq-go-errors","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hueristiq%2Fhq-go-errors","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hueristiq%2Fhq-go-errors/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hueristiq%2Fhq-go-errors/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hueristiq%2Fhq-go-errors/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hueristiq","download_url":"https://codeload.github.com/hueristiq/hq-go-errors/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hueristiq%2Fhq-go-errors/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264816727,"owners_count":23668256,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["error-formatting","error-handing","errors","go","golang"],"created_at":"2025-04-30T04:21:37.197Z","updated_at":"2025-07-11T13:11:22.953Z","avatar_url":"https://github.com/hueristiq.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# hq-go-errors\n\n![made with go](https://img.shields.io/badge/made%20with-Go-1E90FF.svg) [![go report card](https://goreportcard.com/badge/github.com/hueristiq/hq-go-errors)](https://goreportcard.com/report/github.com/hueristiq/hq-go-errors) [![license](https://img.shields.io/badge/license-MIT-gray.svg?color=1E90FF)](https://github.com/hueristiq/hq-go-errors/blob/master/LICENSE) ![maintenance](https://img.shields.io/badge/maintained%3F-yes-1E90FF.svg) [![open issues](https://img.shields.io/github/issues-raw/hueristiq/hq-go-errors.svg?style=flat\u0026color=1E90FF)](https://github.com/hueristiq/hq-go-errors/issues?q=is:issue+is:open) [![closed issues](https://img.shields.io/github/issues-closed-raw/hueristiq/hq-go-errors.svg?style=flat\u0026color=1E90FF)](https://github.com/hueristiq/hq-go-errors/issues?q=is:issue+is:closed) [![contribution](https://img.shields.io/badge/contributions-welcome-1E90FF.svg)](https://github.com/hueristiq/hq-go-errors/blob/master/CONTRIBUTING.md)\n\n`hq-go-errors` is a [Go (Golang)](http://golang.org/) package for rich, structured error handling with full stack-trace support, error wrapping, classification, and formatting.\n\n## Resource\n\n- [Features](#features)\n- [Installation](#installation)\n- [Usage](#usage)\n\t- [Creating Errors](#creating-errors)\n\t- [Wrapping Errors](#wrapping-errors)\n\t- [Unwrapping, `Is`, `As`, and `Cause`](#unwrapping-is-as-and-cause)\n\t- [Formatting Errors](#formatting-errors)\n\t\t- [... to String](#-to-string)\n\t\t- [... to JSON](#-to-json)\n- [Contributing](#contributing)\n- [Licensing](#licensing)\n\n## Features\n\n- **Full Stack Traces:** Capture detailed call stacks at error creation and wrap points, with customizable formatting (e.g., reverse order, separators).\n- **Error Chaining:** Wrap errors to add context while preserving the original stack trace and error details.\n- **Error Classification:** Assign `ErrorType` values to categorize errors for programmatic handling.\n- **Structured Fields:** Attach arbitrary key-value metadata (e.g., request IDs, parameters) to errors for enhanced debugging.\n- **Flexible Formatting:** Render errors as human-readable strings or JSON-like maps, with options to include/exclude stack traces, invert chain order, or handle external errors.\n- **Standards-Compliant:** Implements Go’s standard `error`, `Unwrap`, `Is`, and `As` interfaces, plus additional helpers like `Cause` for root cause analysis.\n\n## Installation\n\nTo install `hq-go-errors`, run the following command in your Go project:\n\n```bash\ngo get -v -u github.com/hueristiq/hq-go-errors\n```\n\nMake sure your Go environment is set up properly (Go 1.13 or later is recommended).\n\n## Usage\n\n### Creating Errors\n\nUse `hqgoerrors.New` to create a root error with a full call stack captured at the point of invocation.\n\n```go\npackage main\n\nimport (\n\t\"fmt\"\n\n\thqgoerrors \"github.com/hueristiq/hq-go-errors\"\n)\n\nfunc main() {\n\terr := hqgoerrors.New(\"failed to initialize database\")\n\tif err != nil {\n\t\tfmt.Println(err.Error())\n\t}\n}\n```\n\n### Wrapping Errors\n\nUse `hqgoerrors.Wrap` to add context to an existing error, capturing a single stack frame at the wrap point while preserving the original error’s stack trace.\n\n```go\npackage main\n\nimport (\n\t\"fmt\"\n\n\thqgoerrors \"github.com/hueristiq/hq-go-errors\"\n)\n\nfunc loadConfig() error {\n\treturn hqgoerrors.New(\"cannot read config file\")\n}\n\nfunc main() {\n\tif err := loadConfig(); err != nil {\n\t\terr = hqgoerrors.Wrap(err, \"failed to load configuration\")\n\n\t\tfmt.Println(err.Error())\n\t}\n}\n```\n\n### Structured Types \u0026 Fields\n\nYou can classify errors and attach structured data:\n\n```go\nerr := hqgoerrors.New(\"payment declined\",\n\thqgoerrors.WithType(\"PaymentError\"),\n\thqgoerrors.WithField(\"order_id\", 1234),\n\thqgoerrors.WithField(\"amount\", 49.95),\n)\n```\n\n- Retrieve type:\n\n\t```go\n\tif e, ok := err.(hqgoerrors.Error); ok {\n\t\tfmt.Println(\"Type:\", e.Type())\n\t\tfmt.Println(\"Fields:\", e.Fields())\n\t}\n\t```\n\n### Unwrapping, `Is`, `As`, and `Cause`\n\n- Standard Unwrap:\n\n\t```go\n\tnext := hqgoerrors.Unwrap(err)\n\t```\n\n- Deep equality:\n\n\t```go\n\tif hqgoerrors.Is(err, targetErr) { … }\n\t```\n\n- Type assertion:\n\n\t```go\n\tvar myErr *hqgoerrors.Error\n\n\tif hqgoerrors.As(err, \u0026myErr) {\n\t\tfmt.Println(\"Got:\", myErr.Msg)\n\t}\n\t```\n\n- Root cause:\n\n\t```go\n\tcause := hqgoerrors.Cause(err)\n\t```\n\n### Formatting Errors\n\n#### ... to String\n\n```go\npackage main\n\nimport (\n\t\"fmt\"\n\n\thqgoerrors \"github.com/hueristiq/hq-go-errors\"\n)\n\nfunc main() {\n\terr := hqgoerrors.New(\"root error example!\", hqgoerrors.WithType(\"ERROR_TYPE\"), hqgoerrors.WithField(\"FIELD_KEY_1\", \"FIELD_VALUE_1\"), hqgoerrors.WithField(\"FIELD_KEY_2\", \"FIELD_VALUE_2\"))\n\n\terr = hqgoerrors.Wrap(err, \"wrap error example 1!\")\n\terr = hqgoerrors.Wrap(err, \"wrap error example 2!\", hqgoerrors.WithType(\"ERROR_TYPE_2\"), hqgoerrors.WithField(\"FIELD_KEY_1\", \"FIELD_VALUE_1\"), hqgoerrors.WithField(\"FIELD_KEY_2\", \"FIELD_VALUE_2\"))\n\n\tformattedStr := hqgoerrors.ToString(err, true)\n\n\tfmt.Println(formattedStr)\n}\n```\n\noutput:\n\n```\n[ERROR_TYPE_2] wrap error example 2!\n\nFields:\n  FIELD_KEY_1=FIELD_VALUE_1,  FIELD_KEY_2=FIELD_VALUE_2\n\nStack:\n  main.main:/home/.../hq-go-errors/examples/string_format/main.go:13\n\nwrap error example 1!\n\nStack:\n  main.main:/home/.../hq-go-errors/examples/string_format/main.go:12\n\n[ERROR_TYPE] root error example!\n\nFields:\n  FIELD_KEY_1=FIELD_VALUE_1,  FIELD_KEY_2=FIELD_VALUE_2\n\nStack:\n  main.main:/home/.../hq-go-errors/examples/string_format/main.go:13\n  main.main:/home/.../hq-go-errors/examples/string_format/main.go:12\n  main.main:/home/.../hq-go-errors/examples/string_format/main.go:10\n```\n\n#### ... to JSON\n\n```go\npackage main\n\nimport (\n\t\"encoding/json\"\n\t\"fmt\"\n\n\thqgoerrors \"github.com/hueristiq/hq-go-errors\"\n)\n\nfunc main() {\n\terr := hqgoerrors.New(\"root error example!\", hqgoerrors.WithType(\"ERROR_TYPE\"), hqgoerrors.WithField(\"FIELD_KEY_1\", \"FIELD_VALUE_1\"), hqgoerrors.WithField(\"FIELD_KEY_2\", \"FIELD_VALUE_2\"))\n\n\terr = hqgoerrors.Wrap(err, \"wrap error example 1!\")\n\terr = hqgoerrors.Wrap(err, \"wrap error example 2!\", hqgoerrors.WithType(\"ERROR_TYPE_2\"), hqgoerrors.WithField(\"FIELD_KEY_1\", \"FIELD_VALUE_1\"), hqgoerrors.WithField(\"FIELD_KEY_2\", \"FIELD_VALUE_2\"))\n\n\tformattedJSON := hqgoerrors.ToJSON(err, true)\n\n\tbytes, _ := json.Marshal(formattedJSON)\n\n\tfmt.Println(string(bytes))\n}\n```\n\noutput:\n\n```json\n{\n  \"root\": {\n    \"fields\": {\n      \"FIELD_KEY_1\": \"FIELD_VALUE_1\",\n      \"FIELD_KEY_2\": \"FIELD_VALUE_2\"\n    },\n    \"message\": \"root error example!\",\n    \"stack\": [\n      \"main.main:/home/.../hq-go-errors/examples/JSON_format/main.go:14\",\n      \"main.main:/home/.../hq-go-errors/examples/JSON_format/main.go:13\",\n      \"main.main:/home/.../hq-go-errors/examples/JSON_format/main.go:11\"\n    ],\n    \"type\": \"ERROR_TYPE\"\n  },\n  \"wrap\": [\n    {\n      \"fields\": {\n        \"FIELD_KEY_1\": \"FIELD_VALUE_1\",\n        \"FIELD_KEY_2\": \"FIELD_VALUE_2\"\n      },\n      \"message\": \"wrap error example 2!\",\n      \"stack\": \"main.main:/home/.../hq-go-errors/examples/JSON_format/main.go:14\",\n      \"type\": \"ERROR_TYPE_2\"\n    },\n    {\n      \"message\": \"wrap error example 1!\",\n      \"stack\": \"main.main:/home/.../hq-go-errors/examples/JSON_format/main.go:13\"\n    }\n  ]\n}\n```\n\n## Contributing\n\nContributions are welcome and encouraged! Feel free to submit [Pull Requests](https://github.com/hueristiq/hq-go-errors/pulls) or report [Issues](https://github.com/hueristiq/hq-go-errors/issues). For more details, check out the [contribution guidelines](https://github.com/hueristiq/hq-go-errors/blob/master/CONTRIBUTING.md).\n\nA big thank you to all the [contributors](https://github.com/hueristiq/hq-go-errors/graphs/contributors) for your ongoing support!\n\n![contributors](https://contrib.rocks/image?repo=hueristiq/hq-go-errors\u0026max=500)\n\n## Licensing\n\nThis package is licensed under the [MIT license](https://opensource.org/license/mit). You are free to use, modify, and distribute it, as long as you follow the terms of the license. You can find the full license text in the repository - [Full MIT license text](https://github.com/hueristiq/hq-go-errors/blob/master/LICENSE).","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhueristiq%2Fhq-go-errors","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhueristiq%2Fhq-go-errors","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhueristiq%2Fhq-go-errors/lists"}