mdErrors

Typed error hierarchy — MdError + ParseError + RenderError + ContractError.

Module mdErrors | Source packages/front/office/md/src/errors.js | Deps none | Worker-safe yes

Every error thrown by @awacloud/md extends MdError and carries a kebab-case code ('md/parse-not-string', 'md/render-invalid-root', …). Consumers can match on the code rather than the message.

Stable codes

Invalid input arguments (null/undefined objects passed to replaceNode/wrapNode/cloneNode) throw a native TypeError. That is a deliberate choice, aligned with the JavaScript convention for trivially-violable argument preconditions.

Resolve

mdErrors has no dependencies — its classes are declared inside the factory body (kept serialisable to a Worker via factory.toString()). Two consumption modes:

// 1. Via a ModuleRuntime — worker-safe, and the canonical mode: every
//    other @awacloud/md module (`mdMod`, `blockParser`, `renderHtmlMod`,
//    `renderMarkdownMod`, `renderXmlMod`, `mdAstManipulation`) receives
//    this SAME resolved `mdErrors` instance as its first dependency, so
//    `instanceof` checks agree package-wide:
import { runtime } from '@awacloud/fw';
import { fw_require, modules } from '@awacloud/md';
runtime.registerAll(fw_require);
runtime.registerAll(modules);
const { MdError, ParseError, RenderError, ContractError, isMdError } = runtime.resolve('mdErrors');

// 2. Direct factory call — an isolated instance, no runtime needed
//    (`mdErrors` has zero dependencies of its own):
import { mdErrors } from '@awacloud/md';
const { MdError, ParseError, RenderError, ContractError, isMdError } = mdErrors.factory();

@awacloud/md's package root (src/main.js) is a strict descriptor manifest: it exports the modules/extras/bundle/fw_require arrays plus every module descriptor by binding name (mdErrors, mdCommon, …) — it never materializes or re-exports the error classes themselves. There is no import { MdError } from '@awacloud/md'; the classes only exist after mdErrors.factory() runs, either directly (mode 2 above) or through a ModuleRuntime (mode 1). A consumer that calls another module's factory manually (e.g. blockParser.factory(...)) must pass its own mdErrors.factory() result as the first argument, to keep a consistent class identity between that module and the consumer.

API

Fields

Examples

Typed catch

import { runtime } from '@awacloud/fw';
import { fw_require, modules } from '@awacloud/md';
runtime.registerAll(fw_require);
runtime.registerAll(modules);
const { MdError, ContractError } = runtime.resolve('mdErrors');
const { createMd } = runtime.resolve('md');

try {
    createMd().parse(123);
} catch (e) {
    if (e instanceof ContractError) console.log(e.code); // 'md/parse-not-string'
    if (e instanceof MdError)       console.log(e.name);
}

With context

const { RenderError } = runtime.resolve('mdErrors');
const node = { type: 'mystery', sourcepos: null };

try {
    throw new RenderError('md/render-invalid-root', 'Unknown node type', {
        context: { type: node.type, sourcepos: node.sourcepos }
    });
} catch (e) {
    e.code;      // 'md/render-invalid-root'
    e.context;   // { type: 'mystery', sourcepos: null }
}

Notes

• MdError is never thrown directly — always a subclass.
• The code follows the 'md/<kebab-case>' format, for consistency with @awacloud/fw errors.
• Renderers use RenderError to signal a corrupted AST (a node missing literal, an unknown type).
• ContractError is reserved for API violations by the caller (typically a wrong argument type).
• tests/errors-doc-snapshot.test.js locates the table above by splitting on the exact ### Stable codes heading — renaming that heading requires updating the test's anchor string in the same change.

See also

• md — the facade that throws ContractError on non-string input
• render/html — throws RenderError
• @awacloud/fw errors — the framework's own error pattern