@remigius42/morg 0.9.2 → 0.10.0

package/dist/translate.d.ts

@@ -0,0 +1,34 @@
+import type { MarkdownStyleOptions } from "./options.js";
+import { type PresetOptions } from "./presets/sides.js";
+/**
+ * The presets of a translation, its warning callback and the org-ism
+ * key names Vanilla Markdown writes planning under.
+ */
+export type TranslateOptions = PresetOptions & {
+    onWarning?: (message: string) => void;
+    orgismKeys?: Record<string, string>;
+    /** The Markdown markers to write; others stay as written. */
+    markdownStyle?: MarkdownStyleOptions;
+};
+/**
+ * Translates an Org string from the Input Preset's dialect into the
+ * Output Preset's, changing only what the two dialects write
+ * differently (ADR 0006): a block's content is kept as written.
+ * @param org The Org string to translate.
+ * @param options The preset of each side, which must differ.
+ * @returns The Org string in the output's dialect.
+ * @throws If both sides name the same preset (that is `normalizeOrg`),
+ * or a side preset has no org dialect.
+ */
+export declare function translateOrg(org: string, options?: TranslateOptions): string;
+/**
+ * Translates a Markdown string from the Input Preset's dialect into the
+ * Output Preset's, changing only what the two dialects write
+ * differently (ADR 0006): a block's content is kept as written.
+ * @param markdown The Markdown string to translate.
+ * @param options The preset of each side, which must differ.
+ * @returns The Markdown string in the output's dialect.
+ * @throws If both sides name the same preset (that is
+ * `normalizeMarkdown`).
+ */
+export declare function translateMarkdown(markdown: string, options?: TranslateOptions): string;

package/dist/translate.js

@@ -0,0 +1,82 @@
+import { restyleMarkdown } from "./core/restyle.js";
+import { resolveSides } from "./presets/sides.js";
+/**
+ * Translates an Org string from the Input Preset's dialect into the
+ * Output Preset's, changing only what the two dialects write
+ * differently (ADR 0006): a block's content is kept as written.
+ * @param org The Org string to translate.
+ * @param options The preset of each side, which must differ.
+ * @returns The Org string in the output's dialect.
+ * @throws If both sides name the same preset (that is `normalizeOrg`),
+ * or a side preset has no org dialect.
+ */
+export function translateOrg(org, options = {}) {
+    const { input, output } = twoSides(options, "org", "normalizeOrg");
+    // Vanilla has no dialect to translate, so the other side does it
+    const side = input?.translateOrg ? "input" : "output";
+    const translate = (side === "input" ? input : output)?.translateOrg;
+    return translate
+        ? translate(org, {
+            side,
+            ...(options.onWarning && { onWarning: options.onWarning })
+        })
+        : org;
+}
+/**
+ * Translates a Markdown string from the Input Preset's dialect into the
+ * Output Preset's, changing only what the two dialects write
+ * differently (ADR 0006): a block's content is kept as written.
+ * @param markdown The Markdown string to translate.
+ * @param options The preset of each side, which must differ.
+ * @returns The Markdown string in the output's dialect.
+ * @throws If both sides name the same preset (that is
+ * `normalizeMarkdown`).
+ */
+export function translateMarkdown(markdown, options = {}) {
+    const { input, output } = twoSides(options, "markdown", "normalizeMarkdown");
+    const context = hookContext(options, pageLinks({ input, output }));
+    // into Vanilla from the input's dialect, then from it into the
+    // output's; a dialect does what its side needs
+    const vanilla = input?.translateMarkdown?.(markdown, { ...context, side: "input" }) ??
+        markdown;
+    const translated = output?.translateMarkdown?.(vanilla, { ...context, side: "output" }) ??
+        vanilla;
+    const style = outputStyle(options, output);
+    return style ? restyleMarkdown(translated, style) : translated;
+}
+// the style to write, but for a bullet the output's outline needs
+function outputStyle({ markdownStyle, onWarning }, output) {
+    const needed = output?.markdown?.bullet;
+    if (!markdownStyle?.bullet || !needed || markdownStyle.bullet === needed) {
+        return markdownStyle;
+    }
+    onWarning?.(`${output.name} Markdown writes its blocks with '${needed}'; bullet '${markdownStyle.bullet}' not applied`);
+    const style = { ...markdownStyle };
+    delete style.bullet;
+    return style;
+}
+// what a dialect's translation learns of the options
+function hookContext({ onWarning, orgismKeys }, relink) {
+    return {
+        ...(onWarning && { onWarning }),
+        ...(orgismKeys && { orgismKeys }),
+        ...(relink && { relink })
+    };
+}
+// page links between two dialects; a Vanilla side carries the other's
+function pageLinks({ input, output }) {
+    const read = input?.markdown?.links?.read;
+    const write = output?.markdown?.links?.write;
+    return read && write
+        ? (text, inTable) => write(read(text), inTable)
+        : undefined;
+}
+// a translation is between two dialects; one on both sides normalizes
+function twoSides(options, format, normalize) {
+    const sides = resolveSides(options, format, format);
+    const name = sides.input?.name ?? "vanilla";
+    if (name === (sides.output?.name ?? "vanilla")) {
+        throw new Error(`translation takes two presets; for '${name}' on both sides, use ${normalize}`);
+    }
+    return sides;
+}

package/dist/withinFormat.d.ts

@@ -0,0 +1,12 @@
+import type { NormalizeOptions } from "./normalize.js";
+import type { Format } from "./presets/sides.js";
+/**
+ * Converts within one format: two presets translate between their
+ * dialects, one normalizes (ADR 0006). What both adapters do with one
+ * format on both sides.
+ * @param text The document.
+ * @param format Its format, on both sides.
+ * @param options The conversion's options, presets included.
+ * @returns The translated or normalized document.
+ */
+export declare function convertWithinFormat(text: string, format: Format, options?: NormalizeOptions): string;

package/dist/withinFormat.js

@@ -0,0 +1,18 @@
+import { normalizeMarkdown, normalizeOrg } from "./normalize.js";
+import { translateMarkdown, translateOrg } from "./translate.js";
+/**
+ * Converts within one format: two presets translate between their
+ * dialects, one normalizes (ADR 0006). What both adapters do with one
+ * format on both sides.
+ * @param text The document.
+ * @param format Its format, on both sides.
+ * @param options The conversion's options, presets included.
+ * @returns The translated or normalized document.
+ */
+export function convertWithinFormat(text, format, options = {}) {
+    const markdown = format === "markdown";
+    if (options.inputPreset || options.outputPreset) {
+        return (markdown ? translateMarkdown : translateOrg)(text, options);
+    }
+    return (markdown ? normalizeMarkdown : normalizeOrg)(text, options);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remigius42/morg",
-  "version": "0.9.2",
+  "version": "0.10.0",
   "description": "Bidirectional Markdown ↔ Org-mode converter with round-trip convergence",
   "keywords": [
     "org-mode",
@@ -40,7 +40,7 @@
     "provenance": true
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=24"
   },
   "scripts": {
     "prepare": "husky",