Registry / web-framework / melody-parser

melody-parser

library1.7.5jsnpmunverified

melody-parser is an extensible JavaScript parser specifically designed for the Twig template language, generating a detailed Abstract Syntax Tree (AST) from source code. Currently at version 1.7.5, the library maintains a steady release cadence with focus on robustness and extensibility. A key differentiator is its ability to be extended with custom parsing rules via "extensions," allowing it to handle custom Twig tags or specialized template syntaxes beyond standard Twig. It also provides granular control over error handling for unknown tags, differentiating between strict parsing for code generation and lenient parsing for mere AST inspection. It is an essential component for projects requiring deep analysis, transformation, or tooling around Twig templates.

web-framework

npm install melody-parser

package ↗

INSTALL

IMPORT

SIG · MELODY-PARSER

melody-parser

web-frameworkjavascriptv1.7.5

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 'melody-parser';

✗ const { parse } = require('melody-parser');

While CommonJS `require` is shown in some examples, modern Node.js and browser-first applications should prefer ES module `import`.

coreExtensions (named import from melody-extension-core)

✓ import { extension as coreExtensions } from 'melody-extension-core';

✗ import coreExtensions from 'melody-extension-core';

Extensions are typically named exports, often aliased for clarity.

customExtension (default import from a custom module)

✓ import customExtension from 'melody-extension-custom';

Custom extensions might be default exports or named exports depending on their implementation. Follow the extension's specific documentation.

Demonstrates basic parsing, parsing with configuration options, and extending the parser with custom logic using `melody-extension-core` and a hypothetical custom extension.

import { parse } from 'melody-parser'; import { extension as coreExtensions } from 'melody-extension-core'; // Example 1: Basic parsing const twigCodeBasic = '{% spaceless %} Hello, {{ name }}! {% endspaceless %}'; const astBasic = parse(twigCodeBasic); console.log('Basic AST:', JSON.stringify(astBasic, null, 2)); // Example 2: Parsing with options const twigCodeWithOptions = '{# This is a comment #} {{ var }}'; const astWithOptions = parse(twigCodeWithOptions, { ignoreComments: false, // Ensure comments are included in the AST decodeEntities: true, }); console.log('AST with options:', JSON.stringify(astWithOptions, null, 2)); // Example 3: Parsing with extensions (core and a hypothetical custom one) // For a real custom extension, you'd implement its parser logic. const customExtension = { tags: { exit: { parse(parser, token) { // Simplified parsing for an {% exit 404 %} tag parser.advance(); // consume 'exit' const parts = [parser.expression()]; parser.expect(token.type, 'end of tag'); return { type: 'GenericTwigTag', tagName: 'exit', parts: parts, sections: [], }; } } } }; const twigCodeWithExtensions = '{% exit 404 %}'; const astWithExtensions = parse( twigCodeWithExtensions, { allowUnknownTags: true }, // Important for custom or unknown tags coreExtensions, customExtension ); console.log('AST with extensions:', JSON.stringify(astWithExtensions, null, 2));

Debug

Known issues

gotchaBy default, `melody-parser` throws an error when it encounters an unknown Twig tag. This is strict behavior intended for scenarios where all tags must be explicitly handled (e.g., code generation).

fix

To allow parsing of unknown tags into `GenericTwigTag` AST nodes, set the `allowUnknownTags` option to `true` in the parse function's options object: `parse(code, { allowUnknownTags: true })`. Alternatively, provide a custom extension to explicitly handle the unknown tag.

affects: >=1.0.0

gotchaEnsure `melody-types` peer dependency is installed and compatible. This package defines the AST node types, and version mismatches could lead to unexpected type errors or runtime issues, especially in TypeScript projects.

fix

Always install `melody-types` alongside `melody-parser`, adhering to the peer dependency version range specified (e.g., `npm install melody-types@^1.1.0`). Regularly update both packages to their latest compatible versions.

affects: >=1.0.0

Errors

Common errors & fixes

Error: Unknown tag "mytag"

The parser encountered a Twig tag not recognized by its built-in rules or any provided extensions, and the `allowUnknownTags` option was not enabled.

fix

Enable the `allowUnknownTags` option: `parse(code, { allowUnknownTags: true })`. If 'mytag' is a custom tag you intend to support fully, create and pass a `melody-parser` extension that defines how to parse 'mytag'.

Upgrade

Version history

1.7.5latest on npm

Audit

Dependencies

melody-typesrequiredProvides the type definitions for the Abstract Syntax Tree (AST) nodes generated by the parser. It's a peer dependency for type compatibility.

Agent activity

2 hits · last 30 days

node

Resources

packagehttps://www.npmjs.com/package/melody-parser ↗