Marcheur: XSLT-like Tree Processor Builder

Warnings

• breaking As a pre-1.0 release (version 0.9.0), Marcheur's API is not yet stable. Expect potential breaking changes in minor or even patch versions before a stable 1.0 release.
  Fix: Always pin exact versions (`npm install marcheur@0.9.0`) and review changelogs carefully when upgrading. Be prepared for manual code adjustments.
• gotcha The provided README contains 'XXX TDB' placeholders, indicating incomplete or missing documentation for key API sections (Core, Matcher, Nodal). This makes understanding the full capabilities and precise usage challenging without diving into the source code.
  Fix: Consult the GitHub repository's source code for deeper insights into the API, or open issues for clarification from the maintainers.
• gotcha The library's design is heavily inspired by XSLT 1.0. Developers unfamiliar with XSLT's tree-walking and pattern-matching paradigm may face a steeper learning curve.
  Fix: Familiarize yourself with basic XSLT 1.0 concepts or review examples of tree transformation patterns before implementing complex processors with Marcheur.

Install

• npm install marcheur npm
• yarn add marcheur yarn
• pnpm add marcheur pnpm

Imports

• Matcher
  wrong:

  const { Matcher } = require('marcheur');

  correct:

  import { Matcher } from 'marcheur';

  Marcheur is primarily used in ESM environments. Matcher is a core utility for defining pattern-matching conditions.
• Nodal
  wrong:

  const { Nodal } = require('marcheur/nodal');

  correct:

  import { Nodal } from 'marcheur/nodal';

  Nodal is a specialized utility for element creation and attribute remapping, imported from its own sub-path.
• qname
  wrong:

  const { qname } = require('marcheur/qname');

  correct:

  import { qname } from 'marcheur/qname';

  The `qname` function for qualified name parsing and namespace handling is available as a named export from its specific sub-path.

Quickstart

This quickstart demonstrates how to define and apply transformation rules to a JavaScript object tree using Marcheur's `Matcher` and `qname` utilities. It illustrates a conceptual `createTreeWalker` for processing.

import { createTreeWalker } from 'marcheur'; // Hypothetical core processor builder
import { Matcher } from 'marcheur';
import { qname } from 'marcheur/qname';

// Example source data representing an XML-like JS object tree
const document = {
  element: 'root',
  attrs: { 'xmlns:foo': 'http://foo.com/ns', version: '1.0' },
  children: [
    { element: 'item', attrs: { id: 'a' }, children: ['Text A'] },
    { element: 'foo:data', attrs: { value: '123' }, children: ['Some Foo Data'] },
  ],
};

const nsMap = { foo: 'http://foo.com/ns' };

// Define transformation rules using Matcher and qname for pattern matching
const rules = [
  {
    // Match any 'item' element and transform it
    match: new Matcher().element('item'),
    apply: (node) => ({
      element: 'transformedItem',
      attrs: { ...node.attrs, processed: 'true' },
      children: node.children.map(c => typeof c === 'string' ? `MODIFIED: ${c}` : c),
    }),
  },
  {
    // Match 'foo:data' using qname for namespace-aware matching
    match: new Matcher().element(qname('foo:data', nsMap)),
    apply: (node) => ({
      element: 'foo:transformedData',
      attrs: { originalValue: node.attrs.value },
      children: ['Namespace handled!'],
    }),
  },
  {
    // Default rule: copy nodes and recurse for unmatched elements
    match: new Matcher().any(), // Assumes a generic 'any' matcher
    apply: (node, walk) => {
      if (typeof node === 'string') return node; // Handle text nodes
      return {
        ...node,
        children: node.children ? node.children.map(walk) : [],
      };
    },
  },
];

// Hypothetical function to create and execute a tree walker/processor
const walker = createTreeWalker(rules); // 'createTreeWalker' is an assumed API
const transformedDoc = walker.walk(document);

console.log('Original Document:', JSON.stringify(document, null, 2));
console.log('\nTransformed Document:', JSON.stringify(transformedDoc, null, 2));

// Direct usage of the qname utility
const qualifiedNameInfo = qname('foo:bar', nsMap);
console.log('\nqname("foo:bar", nsMap):', qualifiedNameInfo); 
// Expected output: { ns: 'http://foo.com/ns', ln: 'bar' }

const simpleNameInfo = qname('baz');
console.log('qname("baz"):', simpleNameInfo);
// Expected output: { qn: 'baz' }