Tagged Comment Parser

Common errors

• TypeError: Cannot read properties of undefined (reading 'trim')

  cause Passing `null`, `undefined`, or a non-string value directly to the `parse` function.
  fix Ensure the input to `parse` is always a valid string. Use `tryParse(input ?? '')` or `parse(String(input))` for potentially non-string inputs.

• ReferenceError: require is not defined

  cause Attempting to use `require('tagged-comment-parser')` in an ES Module context (`"type": "module"` in `package.json` or a `.mjs` file).
  fix Migrate to ES module imports: `import { parse, tryParse } from 'tagged-comment-parser';`. Ensure your project is correctly configured for ESM.

• Property 'myTag' does not exist on type '{ comment: string | undefined; tags: {}; }'.

  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.
  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 } };`

Warnings

• gotcha 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.
  Fix: Wrap calls to `parse` in a `try/catch` block, or use `tryParse(input)` instead.
• gotcha 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.
  Fix: Standardize your comment format or implement post-parsing logic to handle positional ambiguity if needed.
• gotcha 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.
  Fix: Use TypeScript type guards or runtime checks (e.g., `typeof result.tags.myTag === 'string'`) to handle different tag value types.
• breaking 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.
  Fix: Consult the package's changelog or migration guide for detailed instructions when upgrading to a new major version.

Install

• npm install tagged-comment-parser npm
• yarn add tagged-comment-parser yarn
• pnpm add tagged-comment-parser pnpm

Imports

• parse
  wrong:

  const { parse } = require('tagged-comment-parser')

  correct:

  import { parse } from 'tagged-comment-parser'

  Primarily designed for ESM; `import` is the recommended and type-safe approach.
• tryParse
  wrong:

  const { tryParse } = require('tagged-comment-parser')

  correct:

  import { tryParse } from 'tagged-comment-parser'

  Use `tryParse` to avoid exceptions when input may be invalid or null.
• CommentParseResult

  import type { CommentParseResult } from 'tagged-comment-parser'

  Import this type for explicit type annotations on the parsed output structure.

Quickstart

Demonstrates basic usage of `parse` and `tryParse` with various tag syntaxes and input types, logging the structured output.

import { parse, tryParse } from "tagged-comment-parser";

// Example 1: Basic tags
const comment1 = "@cached @alias:foo this comment is tagged!";
const result1 = parse(comment1);
console.log("Result 1:", result1);
/* Expected: { comment: 'this comment is tagged!', tags: { cached: true, alias: 'foo' } } */

// Example 2: Tags with array values
const comment2 = "@auth(admin, user) @roles:editor A comment with multiple roles.";
const result2 = parse(comment2);
console.log("Result 2:", result2);
/* Expected: { comment: 'A comment with multiple roles.', tags: { auth: ['admin', 'user'], roles: 'editor' } } */

// Example 3: Handling invalid input gracefully with tryParse
const invalidComment = null;
const result3 = tryParse(invalidComment);
console.log("Result 3 (tryParse null):", result3);
/* Expected: { comment: undefined, tags: {} } */

// Example 4: Parsing a string that is just a tag
const tagOnly = "@onlytag";
const result4 = parse(tagOnly);
console.log("Result 4 (tag only):", result4);
/* Expected: { comment: undefined, tags: { onlytag: true } } */

// Example 5: Handling a comment without any tags
const noTagComment = "This is a plain comment.";
const result5 = parse(noTagComment);
console.log("Result 5 (no tags):", result5);
/* Expected: { comment: 'This is a plain comment.', tags: {} } */