Node.js API

The JavaScript/TypeScript package provides parsing, writing, linting, and formatting for MarkBack records. Works in Node.js 18+.

Install: npm install markbackjs | View on npm

Parse Records

import { parseString } from "markbackjs";

const text = `%markback 2

@id prompt-001

# API Design Task

Create an endpoint for users.
<<< approved; clarity=high
`;

const result = parseString(text);
for (const record of result.records) {
  console.log(record.id, record.feedback);
}

Write Records

import { Record, writeString } from "markbackjs";

const records = [
  new Record({ feedback: "approved", id: "item-1", content: "First item" }),
  new Record({ feedback: "rejected", id: "item-2", content: "Second item" }),
];

const output = writeString(records);

Lint Records

import { lintString, formatDiagnostics } from "markbackjs";

const result = lintString(text, { checkSources: false });

if (result.hasErrors) {
  console.log(formatDiagnostics(result.diagnostics));
}

Lint Files

import { lintFile, lintFiles, summarizeResults } from "markbackjs";

const single = lintFile("labels.mb");
const batch = lintFiles(["a.mb", "b.mb"]);

console.log(summarizeResults(batch));

Lint Options

Option	Type	Default	Description
sourceFile	string	null	File path shown in diagnostics
checkSources	boolean	true	Verify @file/@input files exist
checkCanonical	boolean	true	Warn when output differs from canonical form

Record Model Overview

• Record: feedback (required), id, by, file (FileRef), input (FileRef), tags, content, metadata
• FileRef: points to external content (@file or @input), with optional line/character ranges
• ParseResult: records, diagnostics, hasErrors, hasWarnings, errorCount, warningCount, scope, covers, version
• Diagnostic: file, line, column, severity, code, message
• parseFeedback(raw): helper that splits a feedback string into label, attributes, comment, and optional jsonData

Attributed Feedback

Use the by field to track who provided feedback:

import { Record, writeString } from "markbackjs";

const records = [
  new Record({ feedback: "approved", id: "item-1", by: "alice", content: "First item" }),
  new Record({ feedback: "needs work", id: "item-2", by: "bob", content: "Second item" }),
];

const output = writeString(records);

Parsing Helpers

import { parseString, parseFeedback } from "markbackjs";

const result = parseString(`
%markback 2

@id example
@tag review

Inline content.
<<< good; quality=high
`);

const fb = parseFeedback("good; quality=high; needs=examples");
console.log(fb.label);      // "good"
console.log(fb.attributes); // { quality: "high", needs: "examples" }

Format Diagnostics

import { lintString, formatDiagnostics } from "markbackjs";

const result = lintString(text);

// Human-readable output
console.log(formatDiagnostics(result.diagnostics, "human"));

// JSON output
console.log(formatDiagnostics(result.diagnostics, "json"));