{"id":28603960,"url":"https://github.com/yanun0323/errors","last_synced_at":"2025-07-17T16:33:45.069Z","repository":{"id":297347648,"uuid":"996493468","full_name":"yanun0323/errors","owner":"yanun0323","description":"A lightweight Go errors package with stack tracing and structured fields.","archived":false,"fork":false,"pushed_at":"2025-06-25T02:16:49.000Z","size":35,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-07-03T19:07:27.997Z","etag":null,"topics":["error","go","golang","stack-trace"],"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/yanun0323.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"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-06-05T03:08:54.000Z","updated_at":"2025-06-25T02:16:51.000Z","dependencies_parsed_at":"2025-06-25T03:22:37.983Z","dependency_job_id":null,"html_url":"https://github.com/yanun0323/errors","commit_stats":null,"previous_names":["yanun0323/errors"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/yanun0323/errors","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yanun0323%2Ferrors","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yanun0323%2Ferrors/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yanun0323%2Ferrors/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yanun0323%2Ferrors/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yanun0323","download_url":"https://codeload.github.com/yanun0323/errors/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yanun0323%2Ferrors/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265630008,"owners_count":23801504,"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","go","golang","stack-trace"],"created_at":"2025-06-11T17:39:31.759Z","updated_at":"2025-07-17T16:33:45.034Z","avatar_url":"https://github.com/yanun0323.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Errors\n\nA lightweight Go errors package with stack tracing and structured fields.\n\n## Features\n\n- ✅ **Standard library compatible**: Drop-in replacement for `errors` package\n- 🔍 **Automatic stack tracing**: Captures call stack when errors are created\n- 📊 **Structured fields**: Add key-value pairs with `With()` method\n- 🎨 **Multiple formats**: Text, JSON, and colorized output\n- 🔗 **Error wrapping**: Full support for `%w` verb and error chains\n- ⚡ **High performance**: Efficient implementation with object pooling\n- 🔌 **Logs integration**: Native support for [github.com/yanun0323/logs](https://github.com/yanun0323/logs) package\n\n\u003e ⚠️ **Caution**: using `fmt.Errorf` to wrap errors is not compatible with `errors.Is` and `errors.As` methods.\n\n## Installation\n\n```bash\ngo get github.com/yanun0323/errors\n```\n\n## Requirements\n\n- Go 1.18+\n\n## Quick Start\n\n```go\nimport \"github.com/yanun0323/errors\"\n\n// Create error with fields\nerr := errors.New(\"connection failed\").\n    With(\"host\", \"localhost\").\n    With(\"port\", 5432)\n\n// Error wrapping\nwrapped := errors.Errorf(\"database error: %w\", err)\n// or\nwrapped = errors.Wrap(err)\nwrapped = errors.Wrap(err, \"database error\")\nwrapped = errors.Wrapf(err, \"database %s error\", database)\n\n// Format output\nprintln(err.Error())                        // Basic message\n\nerrors.Format(err)                          // Text with stack trace\nerrors.FormatJson(err)                      // JSON text with stack trace\nerrors.FormatColorized(err)                 // Colorized text with stack trace\n\nfmt.Printf(\"%s\\n\", err)                     // Basic message\nfmt.Printf(\"%v\\n\", err)                     // Text with stack trace\nfmt.Printf(\"%+v\\n\", err)                    // Colorized text with stack trace\nfmt.Printf(\"%#v\\n\", err)                    // JSON text with stack trace\n```\n\n## API\n\n### Creating Errors\n\n```go\nerrors.New(text string) Error\nerrors.Errorf(format string, args ...any) Error\nerrors.Wrap(err error, args ...any) Error\nerrors.Wrapf(err error, format string, args ...any) Error\n```\n\n### Template\n\nCreate error templates with predefined attributes for reuse:\n\n```go\nerrors.NewTemplate(args ...any) Template\n```\n\n#### Template Methods\n\n```go\ntemplate.With(args ...any) Template             // Add more attributes (chainable)\ntemplate.New(text string) Error                 // Create error with template attributes\ntemplate.Wrap(err error, args ...any) Error     // Wrap error with template attributes\ntemplate.Wrapf(err error, format string, args ...any) Error  // Wrap error with formatted message\ntemplate.Errorf(format string, args ...any) Error           // Create formatted error\n```\n\n### Error Methods\n\n```go\nerr.Error() string                          // Standard error message\nerr.With(args ...any) Error                 // Add fields (chainable)\n```\n\n### Standard Functions\n\n```go\nerrors.Is(err, target error) bool\nerrors.As(err error, target any) bool\nerrors.Unwrap(err error) error\n```\n\n### Formatting Functions\n\n```go\nerrors.Format(err error) string             // Text with stack trace\nerrors.FormatColorized(err error) string    // Colorized text with stack trace\nerrors.FormatJson(err error) string         // JSON text with stack trace\n```\n\n### Logs Package Integration\n\nThis package interoperates with the [github.com/yanun0323/logs](https://github.com/yanun0323/logs) package.\n\n```go\nlogger := logs.Default()\n\nerr := errors.New(\"database connection failed\").\n    With(\"host\", \"localhost\").\n    With(\"port\", 5432).\n\nlogger.WithError(err).Error(\"Operation error\")\n```\n\nWhen using with the `logs` package, errors created by this package can be directly passed to log functions and will automatically extract structured fields and stack traces.\n\n## Examples\n\n### Basic Usage\n\n```go\nerr := errors.New(\"validation failed\").\n    With(\"field\", \"email\").\n    With(\"value\", \"invalid@\").\n    With(\"rule\", \"email_format\")\n```\n\n### Error Wrapping\n\n```go\noriginal := errors.New(\"network timeout\")\nwrapped := errors.Errorf(\"failed to fetch user: %w\", original)\n```\n\n### Template Usage\n\n```go\n// Create a template with common attributes\ntemplate := errors.NewTemplate(\"service\", \"user-service\", \"version\", \"1.0.0\")\n\n// Add more attributes to the template\ndbTemplate := template.With(\"component\", \"database\", \"host\", \"localhost\")\n\n// Create errors using the template\nerr1 := dbTemplate.New(\"connection failed\")\nerr2 := dbTemplate.Errorf(\"query timeout after %d seconds\", 30)\nerr3 := dbTemplate.Wrap(originalErr, \"database operation failed\")\n```\n\n### JSON Output\n\n```go\nerr := errors.New(\"process failed\").With(\"pid\", 1234)\nfmt.Printf(\"%#v\\n\", err)\n// Outputs structured JSON with message, fields, and stack trace\n```\n\n### Logs Package Integration\n\n```go\nimport (\n    \"github.com/yanun0323/errors\"\n    \"github.com/yanun0323/logs\"\n)\n\n// Create an error with structured fields\nerr := errors.New(\"database connection failed\").\n    With(\"host\", \"localhost\").\n    With(\"port\", 5432).\n    With(\"timeout\", \"30s\")\n\n// Pass directly to logs package\nlogs.Error(\"Operation failed\", err)\n// The logs package will automatically extract:\n// - Error message\n// - Structured attributes (host, port, timeout)\n// - Stack trace information\n```\n\n### Output Formats\n\n#### Text\n\n```\nerror:\n    process user, err: user validation failed, err: root: user not found\ncause:\n    user not found\nfield:\n    validateUser:\n        user_id: 0\n        table: users\n        func: validateUser\n    processUser:\n        func: processUser\n    handleRequest:\n        host: db.example.com\n        port: 5432\n        timeout: 30s\n        func: handleRequest\nstack:\n    validateUser:\n        /Users/Shared/Project/personal/go/errors/example/main.go:58 in validateUser\n    processUser:\n        /Users/Shared/Project/personal/go/errors/example/main.go:47 in processUser\n    handleRequest:\n        /Users/Shared/Project/personal/go/errors/example/main.go:34 in handleRequest\n    main:\n        /Users/Shared/Project/personal/go/errors/example/main.go:18 in main\n```\n\n#### Colorized\n\n![Colorized](https://raw.githubusercontent.com/yanun0323/assets/refs/heads/master/errors.colorized.png)\n\n#### JSON\n\n```json\n{\n  \"cause\": \"user not found\",\n  \"error\": \"process user, err: user validation failed, err: root: user not found\",\n  \"field\": [\n    {\n      \"function\": \"validateUser\",\n      \"key\": \"user_id\",\n      \"value\": 0\n    }\n    // ...\n  ],\n  \"stack\": [\n    {\n      \"file\": \"/Users/Shared/Project/personal/go/errors/example/main.go\",\n      \"function\": \"validateUser\",\n      \"line\": \"58\"\n    }\n    // ...\n  ]\n}\n```\n\n## Important Notes\n\n⚠️ **Do not use `fmt.Errorf`**\n\n\u003e Use `errors.New` or `errors.Errorf` instead for proper compatibility with `errors.Is` and `errors.As`.\n\n## License\n\n[MIT License](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyanun0323%2Ferrors","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyanun0323%2Ferrors","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyanun0323%2Ferrors/lists"}