{"id":28555296,"url":"https://github.com/polyseam/sherror","last_synced_at":"2025-10-26T16:09:26.060Z","repository":{"id":297712331,"uuid":"997662452","full_name":"polyseam/sherror","owner":"polyseam","description":null,"archived":false,"fork":false,"pushed_at":"2025-06-07T00:59:37.000Z","size":15,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-07T01:29:18.192Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/polyseam.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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-06T23:21:48.000Z","updated_at":"2025-06-07T00:59:41.000Z","dependencies_parsed_at":"2025-06-07T01:29:22.720Z","dependency_job_id":"449a20a7-751f-4232-9c8e-eff2ef987f24","html_url":"https://github.com/polyseam/sherror","commit_stats":null,"previous_names":["polyseam/sherror"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/polyseam/sherror","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/polyseam%2Fsherror","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/polyseam%2Fsherror/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/polyseam%2Fsherror/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/polyseam%2Fsherror/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/polyseam","download_url":"https://codeload.github.com/polyseam/sherror/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/polyseam%2Fsherror/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263718311,"owners_count":23500809,"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":[],"created_at":"2025-06-10T06:05:54.666Z","updated_at":"2025-10-26T16:09:21.036Z","avatar_url":"https://github.com/polyseam.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# sherror\n\n\u003e Pronounced _share-roar_\n\n\u003e [!CAUTION]\n\u003e Experimental. Do not use this yet!\n\nA tool to keep error codes in your codebase useful, up‑to‑date, and shareable by\nleveraging GitHub Discussions.\n\n## Features\n\n- Define error codes with rich messages and metadata in TypeScript\n- Automatically create and sync GitHub Discussions for each error\n- Enrich runtime errors with user-friendly messages and direct discussion links\n- Track error locations with automatic code path detection\n- Supports styled console output with emoji and colors\n- Customizable error printing\n\n## Table of Contents\n\n- [Installation](#installation)\n- [Quick Start](#quick-start)\n- [Configuration](#configuration)\n- [Usage](#usage)\n- [GitHub Integration](#github-integration)\n- [API Reference](#api-reference)\n- [Contributing](#contributing)\n\n## Installation\n\n```bash\ndeno add @polyseam/sherror\n```\n\n## Quick Start\n\n1. Create a configuration file (e.g., `sherror.config.ts`):\n\n```typescript\nimport type { SherrorConfig } from \"@polyseam/sherror\";\n\nexport const config: SherrorConfig = {\n  category_name: \"sherror-errors\",\n  errors: [\n    {\n      error_code: 1,\n      app_message: \"\u003c🔴\u003eYou must include a \u003c🔵\u003e--foo\u003c/🔵\u003e option\u003c/🔴\u003e\",\n      post_title: \"Error 1: Missing required option\",\n      post_body:\n        \"## Description\\nThis error occurs when the required `--foo` option is missing.\\n\\n## Resolution\\nMake sure to include the `--foo` option with a valid value.\",\n      _discussion_link: \"https://github.com/your-org/your-repo/discussions/1\",\n    },\n    {\n      error_code: 2,\n      app_message: \"\u003c🔴\u003eInvalid value for \u003c🔵\u003e--bar\u003c/🔵\u003e option\u003c/🔴\u003e\",\n      post_title: \"Error 2: Invalid option value\",\n      post_body:\n        \"## Description\\nThe value provided for `--bar` is invalid.\\n\\n## Valid Values\\n- Value 1\\n- Value 2\\n- Value 3\",\n    },\n  ],\n  printer: (error, codepath) =\u003e {\n    console.debug(\n      `Error Code: ${error.error_code}\\n` +\n        `App Message: ${error.app_message}\\n` +\n        `Codepath: ${codepath || \"N/A\"}\\n` +\n        `Discussion Link: ${error._discussion_link || \"N/A\"}`,\n    );\n  },\n} satisfies SherrorConfig;\n```\n\n2. Create a build script (e.g., `build.ts`) to sync errors with GitHub\n   Discussions:\n\n```typescript\nimport { SherrorClient } from \"@polyseam/sherror\";\nimport { config } from \"./sherror.config.ts\";\n\nconst sc = new SherrorClient(config);\nconsole.log(\"Synchronizing errors with GitHub Discussions...\");\nawait sc.sync();\n```\n\n3. Use errors in your application:\n\n```typescript\nimport { config } from \"./sherror.config.ts\";\nimport { SherrorClient } from \"@polyseam/sherror\";\n\n// Initialize the Sherror client\nconst sc = new SherrorClient(config);\n\n// Get an error by code\nconst error = sc.get(1);\nconst codepath = new error.Codepath();\n\n// Print the error with codepath\nerror.print(codepath);\n\n// Optionally, exit the process with the error code\nerror.exit();\n```\n\n## GitHub Integration\n\nTo enable GitHub Discussions integration:\n\n1. Create a personal access token with `public_repo` scope at\n   [GitHub Settings \u003e Developer Settings \u003e Personal Access Tokens](https://github.com/settings/tokens)\n2. Set the token as an environment variable:\n   ```bash\n   export GITHUB_TOKEN=your_token_here\n   ```\n3. Enable Discussions in your repository settings:\n   - Go to your repository on GitHub\n   - Click on \"Settings\" \u003e \"Options\"\n   - Scroll down to \"Features\"\n   - Enable \"Discussions\"\n   - Create a category (e.g., \"sherror-errors\") in the Discussions settings\n4. Set the `category_name` in your config to match the category you created\n5. Run your build script to sync errors with GitHub Discussions\n\n## API Reference\n\n### SherrorClient\n\n```typescript\nclass SherrorClient {\n  constructor(config: SherrorConfig);\n\n  // Get an error by its code\n  get(code: number): SherrorError;\n\n  // Sync errors with GitHub Discussions\n  sync(): Promise\u003cvoid\u003e;\n\n  // Get the current configuration\n  getConfig(): SherrorConfig;\n}\n```\n\n### SherrorConfig\n\n```typescript\ninterface SherrorConfig {\n  // Name of the GitHub Discussions category\n  category_name: string;\n\n  // Array of error definitions\n  errors: SherrorError[];\n\n  // Optional custom printer function\n  printer?: (error: SherrorError, codepath?: string) =\u003e void;\n}\n\ninterface SherrorError {\n  // Unique error code (number)\n  error_code: number;\n\n  // Message to display to users (supports HTML-like tags for styling)\n  app_message: string;\n\n  // Title for the GitHub Discussion\n  post_title: string;\n\n  // Body content for the GitHub Discussion (supports Markdown)\n  post_body: string;\n\n  // Automatically managed - link to the GitHub Discussion\n  _discussion_link?: string;\n}\n```\n\n## Styling Messages\n\nSherror supports simple styling in error messages using HTML-like tags:\n\n- `\u003c🔴\u003eRed text\u003c/🔴\u003e` - Red text for error messages\n- `\u003c🔵\u003eBlue text\u003c/🔵\u003e` - Blue text for important values\n\nThese will be converted to appropriate ANSI escape codes when logged to the\nconsole.\n\n## Custom Printing\n\nYou can customize how errors are printed by providing a `printer` function in\nyour config:\n\n```typescript\nprinter: ((error, codepath) =\u003e {\n  console.error(\n    `[ERROR ${error.error_code}] ${error.app_message}\\n` +\n      `Location: ${codepath || \"unknown\"}\\n` +\n      `For more information, see: ${\n        error._discussion_link || \"No discussion available\"\n      }`,\n  );\n});\n```\n\n## Contributing\n\nContributions are welcome! Please open an issue or submit a pull request.\n\n### Development\n\n1. Clone the repository\n2. Run tests:\n   ```bash\n   deno test\n   ```\n3. Make your changes\n4. Ensure tests pass\n5. Submit a pull request\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpolyseam%2Fsherror","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpolyseam%2Fsherror","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpolyseam%2Fsherror/lists"}