{"id":15850,"library":"tagged-comment-parser","title":"Tagged Comment Parser","description":"This package, `tagged-comment-parser`, provides a straightforward utility for extracting structured data from specially formatted string comments. Its current stable version is 1.3.8. The library focuses on simplicity, offering two main functions: `parse` for strict parsing which throws errors on invalid input, and `tryParse` for a more resilient approach that returns an empty object on invalid input rather than an exception. It handles various tag syntaxes, including boolean flags (`@tag`), key-value pairs (`@tag:value`), and array-like values (`@tag(val1, \"val2\")`). The library ships with TypeScript types, enhancing developer experience. It appears to have a stable, though not rapid, release cadence, characteristic of a focused utility. Its key differentiator is its minimal API and focused scope on comment parsing, contrasting with larger AST parsing libraries.","status":"active","version":"1.3.8","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/kristiandupont/tagged-comment-parser","tags":["javascript","typescript"],"install":[{"cmd":"npm install tagged-comment-parser","lang":"bash","label":"npm"},{"cmd":"yarn add tagged-comment-parser","lang":"bash","label":"yarn"},{"cmd":"pnpm add tagged-comment-parser","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Primarily designed for ESM; `import` is the recommended and type-safe approach.","wrong":"const { parse } = require('tagged-comment-parser')","symbol":"parse","correct":"import { parse } from 'tagged-comment-parser'"},{"note":"Use `tryParse` to avoid exceptions when input may be invalid or null.","wrong":"const { tryParse } = require('tagged-comment-parser')","symbol":"tryParse","correct":"import { tryParse } from 'tagged-comment-parser'"},{"note":"Import this type for explicit type annotations on the parsed output structure.","symbol":"CommentParseResult","correct":"import type { CommentParseResult } from 'tagged-comment-parser'"}],"quickstart":{"code":"import { parse, tryParse } from \"tagged-comment-parser\";\n\n// Example 1: Basic tags\nconst comment1 = \"@cached @alias:foo this comment is tagged!\";\nconst result1 = parse(comment1);\nconsole.log(\"Result 1:\", result1);\n/* Expected: { comment: 'this comment is tagged!', tags: { cached: true, alias: 'foo' } } */\n\n// Example 2: Tags with array values\nconst comment2 = \"@auth(admin, user) @roles:editor A comment with multiple roles.\";\nconst result2 = parse(comment2);\nconsole.log(\"Result 2:\", result2);\n/* Expected: { comment: 'A comment with multiple roles.', tags: { auth: ['admin', 'user'], roles: 'editor' } } */\n\n// Example 3: Handling invalid input gracefully with tryParse\nconst invalidComment = null;\nconst result3 = tryParse(invalidComment);\nconsole.log(\"Result 3 (tryParse null):\", result3);\n/* Expected: { comment: undefined, tags: {} } */\n\n// Example 4: Parsing a string that is just a tag\nconst tagOnly = \"@onlytag\";\nconst result4 = parse(tagOnly);\nconsole.log(\"Result 4 (tag only):\", result4);\n/* Expected: { comment: undefined, tags: { onlytag: true } } */\n\n// Example 5: Handling a comment without any tags\nconst noTagComment = \"This is a plain comment.\";\nconst result5 = parse(noTagComment);\nconsole.log(\"Result 5 (no tags):\", result5);\n/* Expected: { comment: 'This is a plain comment.', tags: {} } */","lang":"typescript","description":"Demonstrates basic usage of `parse` and `tryParse` with various tag syntaxes and input types, logging the structured output."},"warnings":[{"fix":"Wrap calls to `parse` in a `try/catch` block, or use `tryParse(input)` instead.","message":"Using `parse` with invalid input (e.g., `null`, `undefined`, non-string) will throw an exception. Always use `tryParse` or validate input yourself if exceptions are undesirable.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Standardize your comment format or implement post-parsing logic to handle positional ambiguity if needed.","message":"Ambiguity in tag placement: tags can appear at the beginning or end of the string. Ensure consistent input patterns if specific tag ordering or position is critical for your application logic, as the parser only extracts tags, not their original relative position to the comment text.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Use TypeScript type guards or runtime checks (e.g., `typeof result.tags.myTag === 'string'`) to handle different tag value types.","message":"Type of tag values vary: Single tags become `boolean` (`true`), `@tag:value` becomes `string`, and `@tag(val1, val2)` becomes `string[]`. This implicit type conversion requires runtime checks or TypeScript narrowing if strict type handling is necessary.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Consult the package's changelog or migration guide for detailed instructions when upgrading to a new major version.","message":"Future major versions (e.g., v2.0) may introduce breaking changes to tag syntax, parsing behavior, or the API surface. Always review release notes carefully when upgrading across major versions.","severity":"breaking","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Ensure the input to `parse` is always a valid string. Use `tryParse(input ?? '')` or `parse(String(input))` for potentially non-string inputs.","cause":"Passing `null`, `undefined`, or a non-string value directly to the `parse` function.","error":"TypeError: Cannot read properties of undefined (reading 'trim')"},{"fix":"Migrate to ES module imports: `import { parse, tryParse } from 'tagged-comment-parser';`. Ensure your project is correctly configured for ESM.","cause":"Attempting to use `require('tagged-comment-parser')` in an ES Module context (`\"type\": \"module\"` in `package.json` or a `.mjs` file).","error":"ReferenceError: require is not defined"},{"fix":"Access tags with a type guard (e.g., `if ('myTag' in result.tags) { /* ... */ }`) or cast the result to a more specific type if known: `const result = parse(...) as CommentParseResult & { tags: { myTag?: boolean } };`","cause":"TypeScript compiler cannot infer the specific tags that will be present at compile time without explicit type assertions or guards, leading to stricter type checking for the `tags` object.","error":"Property 'myTag' does not exist on type '{ comment: string | undefined; tags: {}; }'."}],"ecosystem":"npm"}