Registry / serialization / tagged-comment-parser

tagged-comment-parser

library1.3.8jsnpmunverified

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.

serialization

npm install tagged-comment-parser

github ↗package ↗

INSTALL

IMPORT

SIG · TAGGED-COMMENT-PAR

tagged-comment-parser

serializationjavascriptv1.3.8

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

parse

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

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

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

tryParse

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

✗ const { tryParse } = require('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.

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: {} } */

Debug

Known issues

gotchaUsing `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.

affects: >=1.0.0

gotchaAmbiguity 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.

affects: >=1.0.0

gotchaType 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.

affects: >=1.0.0

breakingFuture 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.

affects: >=2.0.0

Errors

Common errors & fixes

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

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

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: {}; }'.

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

Upgrade

Version history

1.3.8latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

3 hits · last 30 days

node

Resources

githubhttps://github.com/kristiandupont/tagged-comment-parser ↗

packagehttps://www.npmjs.com/package/tagged-comment-parser ↗