@mdscript/mds

@mdscript/mds

JavaScript/TypeScript bindings for the MDS compiler.

Installation

npm install @mdscript/mds

Note: This package is pre-release and not yet published to npm.

Node.js usage (zero-config)

Node.js auto-selects the native addon and falls back to WASM if unavailable. No initialization required.

import { compile, check, compileFile, checkFile, getBackend, isMdsError } from '@mdscript/mds';

// Compile MDS source to Markdown
const result = compile('Hello {name}', { vars: { name: 'world' } });
console.log(result.output);       // "Hello world"
console.log(result.warnings);     // string[]
console.log(result.dependencies); // string[] of imported file paths

// Validate without rendering
const checked = check('Hello {name}', { vars: { name: 'world' } });

// File-based operations (resolves @import directives)
const fileResult = await compileFile('./my-template.mds');
await checkFile('./my-template.mds');

// Which backend is active?
console.log(getBackend()); // 'native' | 'wasm'

Browser usage

The browser entry requires an explicit init() call before any compile/check operations. init() is idempotent and safe to call multiple times.

import { init, compile, check, isMdsError } from '@mdscript/mds';

await init();
// or with a custom WASM URL:
await init({ wasmUrl: '/assets/mds_bg.wasm' });

const result = compile('# {title}', { vars: { title: 'Hello' } });

compileFile and checkFile are not available in browser environments.

Backend selection (MDS_BACKEND)

Set the MDS_BACKEND environment variable in Node.js to force a specific backend:

Value	Behavior
(unset)	Native addon, WASM fallback
native	Native only, throws if addon unavailable
wasm	WASM only

MDS_BACKEND=wasm node my-script.js

Error handling

Use isMdsError to distinguish MDS compiler errors from other exceptions:

import { compile, isMdsError } from '@mdscript/mds';

try {
  compile(source);
} catch (err) {
  if (isMdsError(err)) {
    console.error(err.code);    // e.g. "mds::undefined_variable"
    console.error(err.message);
    console.error(err.help);    // optional guidance string
    console.error(err.span);    // optional { offset, length, line, column }
  } else {
    throw err;
  }
}

API

Function	Description
compile(source, options?)	Compile MDS source string to Markdown
check(source, options?)	Validate MDS source without rendering
compileFile(path, options?)	Compile an MDS file, resolving imports
checkFile(path, options?)	Validate an MDS file, resolving imports
getBackend()	Returns the active backend: 'native' or 'wasm'
init(options?)	Initialize the WASM backend (browser/explicit WASM only)
isMdsError(err)	Type guard for MDS compiler errors (requires code starting with "mds::")

Options

// CompileOptions / FileOptions
{ vars?: Record<string, unknown> }

// InitOptions
{ wasmUrl?: string | URL | Response | BufferSource }