{"id":16383659,"url":"https://github.com/ainsleyclark/errors","last_synced_at":"2025-03-23T03:33:26.800Z","repository":{"id":39056267,"uuid":"493662457","full_name":"ainsleyclark/errors","owner":"ainsleyclark","description":"🫠 A drop-in replacement for Go errors, with some added sugar! Error handling in Go made easy with codes, messages and more. Failure is your domain!","archived":false,"fork":false,"pushed_at":"2022-09-12T06:20:03.000Z","size":107,"stargazers_count":14,"open_issues_count":2,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-18T17:24:49.607Z","etag":null,"topics":["custom-errors","error-handling","errors","go","golang"],"latest_commit_sha":null,"homepage":"","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/ainsleyclark.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null},"funding":{"github":["ainsleyclark"]}},"created_at":"2022-05-18T12:54:03.000Z","updated_at":"2024-11-02T13:26:44.000Z","dependencies_parsed_at":"2022-09-15T01:02:46.615Z","dependency_job_id":null,"html_url":"https://github.com/ainsleyclark/errors","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ainsleyclark%2Ferrors","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ainsleyclark%2Ferrors/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ainsleyclark%2Ferrors/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ainsleyclark%2Ferrors/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ainsleyclark","download_url":"https://codeload.github.com/ainsleyclark/errors/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245052646,"owners_count":20553162,"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":["custom-errors","error-handling","errors","go","golang"],"created_at":"2024-10-11T04:09:21.664Z","updated_at":"2025-03-23T03:33:26.420Z","avatar_url":"https://github.com/ainsleyclark.png","language":"Go","funding_links":["https://github.com/sponsors/ainsleyclark"],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\u003cimg height=\"250\" src=\"res/logo.svg\" alt=\"Errors Logo\" /\u003e\n\n[![made-with-Go](https://img.shields.io/badge/Made%20with-Go-1f425f.svg)](http://golang.org)\n[![Go Report Card](https://goreportcard.com/badge/github.com/ainsleyclark/errors)](https://goreportcard.com/report/github.com/ainsleyclark/errors)\n[![Maintainability](https://api.codeclimate.com/v1/badges/b3afd7bf115341995077/maintainability)](https://codeclimate.com/github/ainsleyclark/errors/maintainability)\n[![Test](https://github.com/ainsleyclark/errors/actions/workflows/test.yml/badge.svg?branch=master)](https://github.com/ainsleyclark/errors/actions/workflows/test.yml)\n[![codecov](https://codecov.io/gh/ainsleyclark/errors/branch/master/graph/badge.svg?token=K27L8LS7DA)](https://codecov.io/gh/ainsleyclark/errors)\n[![go.dev reference](https://img.shields.io/badge/go.dev-reference-007d9c?logo=go\u0026logoColor=white\u0026style=flat)](https://pkg.go.dev/github.com/ainsleyclark/errors)\n\n\u003c/div\u003e\n\n# 🫠 Errors\n\nA drop-in replacement for Go errors, with some added sugar! Error handling in Go made easy with codes, messages and\nmore. Failure is your domain!\n\n## Overview\n\n- ✅ A humble selection of errors codes that touches most bases.\n- ✅ User friendly error messages for returning via an API for example.\n- ✅ Operation support `(Struct.Method)` naming convention.\n- ✅ Retrieve call stacks as preformatted or as a string slice.\n- ✅ Generate HTTP response codes from all error types.\n- ✅ Extremely lightweight with no external dependencies.\n\n## Why?\n\nErrors are as important in your domain and application as the entities such as a User or Database. They should be\ntreated as individual types. Not only do they give a clear meaning to the users of the application if something goes\nwrong, they can save hours of debugging time when used effectively.\n\nCoupled with consistent and effective use of a logging package, we are able to tell if something goes wrong, where it\nwent wrong, how it went wrong and.\n\n## Installation\n\n```bash\ngo get -u github.com/ainsleyclark/errors\n```\n\n## How to use\n\nSee below on some common examples on how to use the error package.\n\n### The Error Type\n\nThe `Error` struct below describes an application error that's returned when using the `New...()` constructors such\nas `NewInternal()`. See below on more detail on what each field contains.\n\n```go\n// Error defines a standard application error.\ntype Error struct {\n\t// The application error code.\n\tCode string `json:\"code\" bson:\"code\"`\n\t// A human-readable message to send back to the end user.\n\tMessage string `json:\"message\" bson:\"message\"`\n\t// Defines what operation is currently being run.\n\tOp string `json:\"operation\" bson:\"op\"`\n\t// The error that was returned from the caller.\n\tErr error `json:\"error\" bson:\"err\"`\n}\n```\n\n### Returning\n\nBelow is an example of returning a formatted `Error` type in a database call for obtaining a singular user. If no rows\nare found, we return a `NOTFOUND` code. Likewise if there was an error executing the SQL query, we return a `NOTFOUND`\ncode with user-friendly messages.\n\n```go\nfunc (s *UserStore) Find(ctx context.Context, schema string, id int64) (core.User, error) {\n\tconst op = \"UserStore.Find\"\n\n\tq := \"SELECT from users WHERE ID = ? LIMIT 1\"\n\n\tvar out core.User\n\terr := s.DB().GetContext(ctx, \u0026out, q.Build(), id)\n\tif err == sql.ErrNoRows {\n\t\treturn core.User{}, errors.NewNotFound(err, fmt.Sprintf(\"Error obtaining User with the ID: %d\", id), op)\n\t} else if err != nil {\n\t\treturn core.User{}, errors.NewInternal(err, \"Error executing SQL query\", op)\n\t}\n\n\treturn out, nil\n}\n```\n\n### Output\n\nLet's assume that an SQL error occurred during the execution of the query and no rows were returned. Without any context\nof the error, we simply get:\n\n```\nsyntax error near SELECT\n```\n\nHowever, by calling `err.Error()` on our wrapped error, it will return:\n\n```\n\u003cinternal\u003e /Users/me/project/store/users.go:27 - UserStore.Find: syntax error near SELECT, Error executing SQL query\n```\n\nNow we know exactly where the error occurred, why it occurred and what file line and method.\n\n### Checking Types\n\nThe package comes built in with handy functions for obtaining messages, codes and casting to the Error type, see below\nfor some examples.\n\n#### To Error\n\n```go\ne := errors.New(\"error\")\nerr := errors.ToError(e)\n```\n\n#### Obtaining a message\n\n```go\nerr := errors.NewInternal(errors.New(\"error\"), \"My Message\", \"Operation\")\nmsg := errors.Message(err)\nfmt.Println(msg) // Output - \"My Message\"\n```\n\n#### Obtaining an error code\n\n```go\nerr := errors.NewInternal(errors.New(\"error\"), \"My Message\", \"Operation\")\ncode := errors.Code(err)\nfmt.Println(code) // Output - \"internal\"\n```\n\n## Available Error Codes\n\nBelow is a list of available error codes within the errors package. It's tempting to build fine-grained error codes, but\nit's a lot easier to manage more generic codes. The codes below are a good start to set off on, if you feel there is one\nmissing, please open a [pull request](https://github.com/ainsleyclark/errors/pulls).\n\n| Code            | Value                | Notes                          |\n|-----------------|:---------------------|:-------------------------------|\n| CONFLICT        | `\"conflict\"`         | An action cannot be performed. |\n| INTERNAL        | `\"internal\"`         | Error within the application.  |\n| INVALID         | `\"invalid\"`          | Validation failed.             |\n| NOTFOUND        | `\"not_found\"`        | Entity does not exist.         |\n| UNKNOWN         | `\"unknown\"`          | Application unknown error.     |\n| MAXIMUMATTEMPTS | `\"maximum_attempts\"` | More than allowed action.      |\n| EXPIRED         | `\"expired\"`          | Subscription expired.          |\n\n## Benchmarks\n\nRan on 19/05/2022\n\n```bash\n$ go version\ngo version go1.18.1 darwin/amd64\n\n$ go test -benchmem -bench .\ngoos: darwin\ngoarch: amd64\npkg: github.com/ainsleyclark/errors\ncpu: AMD Ryzen 7 5800X 8-Core Processor\nBenchmarkNew-16                          1000000              1026 ns/op            1320 B/op          6 allocs/op\nBenchmarkNewInternal-16                  1000000              1023 ns/op            1320 B/op          6 allocs/op\nBenchmarkError_Error-16                  6582385               180.6 ns/op           464 B/op          4 allocs/op\nBenchmarkError_Code-16                  637953824                1.883 ns/op           0 B/op          0 allocs/op\nBenchmarkError_Message-16               628838649                1.906 ns/op           0 B/op          0 allocs/op\nBenchmarkError_ToError-16               705541435                1.699 ns/op           0 B/op          0 allocs/op\nBenchmarkError_HTTPStatusCode-16        1000000000               0.6282 ns/op          0 B/op          0 allocs/op\n```\n\n## Contributing\n\nPlease feel free to make a pull request if you think something should be added to this package!\n\n## Credits\n\nShout out to the incredible [Maria Letta](https://github.com/MariaLetta) for her excellent Gopher illustrations.\n\n## Licence\n\nCode Copyright 2022 Errors. Code released under the [MIT Licence](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fainsleyclark%2Ferrors","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fainsleyclark%2Ferrors","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fainsleyclark%2Ferrors/lists"}