@doc-kit/core 0.0.0

package/src/utils/unist.mjs

@@ -0,0 +1,75 @@
+'use strict';
+
+import { pointEnd, pointStart } from 'unist-util-position';
+
+/**
+ * Escapes HTML entities ("<" and ">") in a string
+ * @param {string} string The string
+ */
+const escapeHTMLEntities = string =>
+  string.replace(/</g, '&lt;').replace(/>/g, '&gt;');
+
+/**
+ * Extracts text content from a node recursively
+ *
+ * @param {import('unist').Node} node The Node to be transformed into a string
+ * @param {boolean} [escape] Escape HTML entities ("<", ">")?
+ * @returns {string} The transformed Node as a string
+ */
+export const transformNodeToString = (node, escape) => {
+  switch (node.type) {
+    case 'inlineCode':
+      return `\`${escape ? escapeHTMLEntities(node.value) : node.value}\``;
+    case 'typeAnnotation':
+      return `{${escape ? escapeHTMLEntities(node.value) : node.value}}`;
+    case 'strong':
+      return `**${transformNodesToString(node.children, escape)}**`;
+    case 'emphasis':
+      return `_${transformNodesToString(node.children, escape)}_`;
+    default: {
+      if (node.children) {
+        return transformNodesToString(node.children, escape);
+      }
+
+      const string = node.value?.replace(/\n/g, ' ') || '';
+
+      // Replace line breaks (\n) with spaces to keep text in a single line
+      return escape ? escapeHTMLEntities(string) : string;
+    }
+  }
+};
+
+/**
+ * This utility allows us to join children Nodes into one
+ * and transfor them back to what their source would look like
+ *
+ * @param {Array<import('unist').Parent & import('unist').Literal>} nodes Nodes to parsed and joined
+ * @param {boolean} [escape] Escape HTML entities ("<", ">")?
+ * @returns {string} The parsed and joined nodes as a string
+ */
+export const transformNodesToString = (nodes, escape) => {
+  const mappedChildren = nodes.map(node => transformNodeToString(node, escape));
+
+  return mappedChildren.join('');
+};
+
+/**
+ * This method is an utility that allows us to conditionally invoke/call a callback
+ * based on test conditions related to a Node's position relative to another one
+ * being before or not the other Node
+ *
+ * NOTE: Not yet used, but probably going to be used by the JSON generator.
+ *
+ * @param {import('unist').Node | undefined} nodeA The Node to be used as a position reference to check against
+ * the other Node. If the other Node is before this one, the callback will be called.
+ * @param {import('unist').Node | undefined} nodeB The Node to be checked against the position of the first Node
+ * @param {(nodeA: import('unist').Node, nodeB: import('unist').Node) => void} callback The callback to be called
+ */
+export const callIfBefore = (nodeA, nodeB, callback) => {
+  const positionA = pointEnd(nodeA);
+  const positionB = pointStart(nodeB);
+
+  if (positionA && positionB && positionA.line > positionB.line) {
+    callback(nodeA, nodeB);
+  }
+};

package/src/utils/url.mjs

@@ -0,0 +1,27 @@
+/**
+ * Kind of like `path.posix.relative`, however, this functions more like a URL resolution
+ * @param {string} to
+ * @param {string} from
+ * @returns {string}
+ */
+export const relative = (to, from) => {
+  if (to.includes('://')) {
+    return to;
+  }
+
+  const a = to.split('/').filter(Boolean);
+  const b = from.split('/').slice(0, -1).filter(Boolean);
+
+  // The last segment of `to` is the target itself, not a directory; it must
+  // never be consumed as a common prefix (`/generators` from `/generators/web`
+  // is `../generators`, not `.`).
+  const file = a.pop();
+
+  while (a[0] !== undefined && a[0] === b[0]) {
+    a.shift();
+    b.shift();
+  }
+
+  const rel = [...b.map(() => '..'), ...a, ...(file ? [file] : [])].join('/');
+  return rel || '.';
+};