espolar 0.2.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "espolar",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "type": "module",
   "types": "./dist/index.d.ts",
   "exports": {
@@ -11,7 +11,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "src"
   ],
   "license": "MIT",
   "repository": {

package/src/api.ts

@@ -0,0 +1,87 @@
+import type { Mapping } from "@volar/source-map";
+import type { AST, AST_NODE_TYPES, Comment } from "./types.ts";
+import type { SourceRange } from "./mappings.ts";
+
+export interface PrintResult<Data> {
+  code: string;
+  mappings: Mapping<Data>[];
+}
+
+export interface PrintOptionsBase<Data> {
+  source: string;
+  isUntouched?: (node: AST.Node) => boolean | SourceRange;
+  combineMappingData?: (left: Data, right: Data) => Data;
+  printers?: Printers<Data>;
+  getLeadingComments?: (node: AST.Node) => Comment[] | undefined;
+  getTrailingComments?: (node: AST.Node) => Comment[] | undefined;
+  /**
+   * Provide additional source range for the left parenthesis of `CallExpression` and `NewExpression`.
+   * This is useful for language tools that want to provide signature hints when user enter `(`.
+   *
+   * @notes This hook will not interact with parentheses around the callee.
+   *
+   * @param node The `CallExpression` or `NewExpression` node.
+   * @returns The source range of the left parenthesis, `undefined` if not available.
+   */
+  experimentalGetLeftParenSourceRange?: (
+    node: AST.CallExpression | AST.NewExpression,
+  ) => SourceRange | undefined;
+}
+
+export interface MappingDataOptions<Data> {
+  getMappingData: (node?: AST.Node | null) => Data;
+}
+
+type MappingDataUndefinedOptions = {
+  [K in keyof MappingDataOptions<0>]?: undefined;
+};
+
+export type PrintOptions<Data> = PrintOptionsBase<Data> &
+  ([Data] extends [undefined]
+    ? MappingDataUndefinedOptions
+    : MappingDataOptions<Data>);
+
+export interface PrinterContext<Data = any> {
+  readonly options: PrintOptions<Data>;
+  readonly source: string;
+  readonly generatedOffset: number;
+  write(text: string): void;
+  writeMapped(
+    text: string,
+    sourceStart: number,
+    sourceEnd: number,
+    data?: Data,
+  ): void;
+  writeNode(node: AST.Node | null | undefined): void;
+  writeNodeList(nodes: readonly (AST.Node | null)[], separator: string): void;
+  writeExpressionListWithCommaSep(
+    nodes: readonly (AST.Expression | AST.SpreadElement | null)[],
+  ): void;
+  writeNodeListWithNewLineSep(
+    nodes: readonly (AST.ProgramStatement | AST.ClassElement)[],
+  ): void;
+  writeSource(start: number, end: number, data?: Data): void;
+  writePreservedNode(node: AST.Node): void;
+  appendMapping(
+    sourceRange: SourceRange,
+    generatedStart: number,
+    generatedEnd: number,
+    data?: Data,
+  ): void;
+  /** Extra mappings that won't be merged automatically */
+  createExtraMapping(
+    sourceRange: SourceRange,
+    generatedStart: number,
+    generatedEnd: number,
+    data?: Data,
+  ): void;
+}
+
+export type NodePrinter<Key extends AST_NODE_TYPES, Data> = (
+  node: Extract<AST.Node, { type: Key }>,
+  context: PrinterContext<Data>,
+) => void;
+
+export type Printers<Data> = {
+  [K in AST_NODE_TYPES]?: NodePrinter<K, Data>;
+};

package/src/index.ts

@@ -0,0 +1,14 @@
+export {
+  defaultCombineMappingData,
+  defaultIsUntouched,
+  print,
+} from "./printer.ts";
+export { defaultPrinters } from "./printers.ts";
+export type {
+  NodePrinter,
+  PrintOptions,
+  PrintResult,
+  PrinterContext,
+} from "./api.ts";
+export type { AST, NodeLike, Comment } from "./types.ts";
+export type { SourceRange } from "./mappings.ts";

package/src/mappings.ts

@@ -0,0 +1,85 @@
+import type { Mapping } from "@volar/source-map";
+import type { AST } from "./types.ts";
+
+export interface InternalMapping<Data = unknown> {
+  sourceStart: number;
+  sourceEnd: number;
+  generatedStart: number;
+  generatedEnd: number;
+  data: Data;
+}
+
+export interface SourceRange {
+  start: number;
+  end: number;
+}
+
+export function getNodeRange(node: AST.Node): SourceRange | undefined {
+  if (Array.isArray(node.range) && node.range.length === 2) {
+    const [start, end] = node.range;
+    if (Number.isInteger(start) && Number.isInteger(end) && start <= end) {
+      return { start, end };
+    }
+  }
+  const { start, end } = node;
+  if (
+    typeof start === "number" &&
+    typeof end === "number" &&
+    Number.isInteger(start) &&
+    Number.isInteger(end) &&
+    start <= end
+  ) {
+    return { start, end };
+  }
+
+  return undefined;
+}
+
+export function pushMapping<Data>(
+  mappings: InternalMapping<Data>[],
+  mapping: InternalMapping<Data>,
+  combineMappingData: (left: Data, right: Data) => Data,
+): void {
+  const previous = mappings.at(-1);
+  if (previous && canMerge(previous, mapping)) {
+    previous.sourceEnd = mapping.sourceEnd;
+    previous.generatedEnd = mapping.generatedEnd;
+    previous.data = combineMappingData(previous.data, mapping.data);
+    return;
+  }
+
+  mappings.push(mapping);
+}
+
+/**
+ * Two adjacent mappings with identical lengths can be merged into one mapping.
+ * @param left 
+ * @param right 
+ * @returns 
+ */
+function canMerge<Data>(
+  left: InternalMapping<Data>,
+  right: InternalMapping<Data>,
+): boolean {
+  return (
+    left.sourceEnd - left.sourceStart === left.generatedEnd - left.generatedStart &&
+    right.sourceEnd - right.sourceStart === right.generatedEnd - right.generatedStart &&
+    left.sourceEnd === right.sourceStart &&
+    left.generatedEnd === right.generatedStart
+  );
+}
+
+export function toVolarMapping<Data>(
+  mapping: InternalMapping<Data>,
+): Mapping<Data> {
+  const sourceLength = mapping.sourceEnd - mapping.sourceStart;
+  const generatedLength = mapping.generatedEnd - mapping.generatedStart;
+  return {
+    sourceOffsets: [mapping.sourceStart],
+    generatedOffsets: [mapping.generatedStart],
+    lengths: [sourceLength],
+    generatedLengths:
+      generatedLength !== sourceLength ? [generatedLength] : undefined,
+    data: mapping.data,
+  };
+}

package/src/printer.ts

@@ -0,0 +1,301 @@
+import type {
+  NodePrinter,
+  PrintOptions,
+  PrintResult,
+  PrinterContext,
+  Printers,
+} from "./api.ts";
+import {
+  defaultPrinters,
+  expectAssignmentExprNeedsParen,
+  writeComment,
+} from "./printers.ts";
+import type { AST, AST_NODE_TYPES, Comment, NodeLike } from "./types.ts";
+import {
+  getNodeRange,
+  pushMapping,
+  toVolarMapping,
+  type InternalMapping,
+  type SourceRange,
+} from "./mappings.ts";
+
+interface InternalPrinterContext extends PrinterContext<any> {
+  // make typescript happy about complex types
+  options: any;
+  result(): PrintResult<any>;
+}
+
+export function print<Data = undefined>(
+  node: AST.Node,
+  options: PrintOptions<Data>,
+): PrintResult<Data>;
+export function print<Data = undefined>(
+  node: import("estree").Node,
+  options: PrintOptions<Data>,
+): PrintResult<Data>;
+export function print<Data = undefined>(
+  node: NodeLike,
+  options: PrintOptions<Data>,
+): PrintResult<Data>;
+export function print<Data = undefined>(
+  node: unknown,
+  options: PrintOptions<Data>,
+): PrintResult<Data> {
+  const context = createPrinterContext(options);
+  context.writeNode(node as AST.Node);
+  return context.result();
+}
+
+export function defaultIsUntouched(node: AST.Node): boolean | SourceRange {
+  return getNodeRange(node) || false;
+}
+
+export function defaultCombineMappingData<T>(left: T, right: T): T {
+  if (left === right) {
+    return left;
+  }
+  throw new Error(
+    "Cannot combine mapping data with different values when no custom combineMappingData function is provided",
+  );
+}
+
+function createPrinterContext<Data>(
+  options: PrintOptions<Data>,
+): InternalPrinterContext {
+  const chunks: string[] = [];
+  const mappings: InternalMapping<Data>[] = [];
+  const extraMappings: InternalMapping<Data>[] = [];
+  let generatedOffset = 0;
+
+  const isUntouched = options.isUntouched ?? defaultIsUntouched;
+  const getMappingData = options.getMappingData ?? ((): any => undefined);
+  const combineMappingData =
+    options.combineMappingData ?? defaultCombineMappingData;
+  const printers: Printers<Data> = {
+    ...defaultPrinters,
+    ...options.printers,
+  };
+
+  const appendMapping = (
+    sourceRange: SourceRange,
+    generatedStart: number,
+    generatedEnd: number,
+    data: Data,
+  ) => {
+    pushMapping(
+      mappings,
+      {
+        sourceStart: sourceRange.start,
+        sourceEnd: sourceRange.end,
+        generatedStart,
+        generatedEnd,
+        data,
+      },
+      combineMappingData,
+    );
+  };
+
+  const context: InternalPrinterContext = {
+    options: options,
+    source: options.source,
+    get generatedOffset() {
+      return generatedOffset;
+    },
+    write(text) {
+      if (text.length === 0) {
+        return;
+      }
+      chunks.push(text);
+      generatedOffset += text.length;
+    },
+    writeMapped(text, sourceStart, sourceEnd, data) {
+      if (text.length === 0 || sourceEnd < sourceStart) {
+        return;
+      }
+      const generatedStart = generatedOffset;
+      context.write(text);
+      appendMapping(
+        { start: sourceStart, end: sourceEnd },
+        generatedStart,
+        generatedOffset,
+        data ?? getMappingData(null),
+      );
+    },
+    writeNode(node) {
+      if (!node) {
+        return;
+      }
+
+      const range = getNodeRange(node);
+      const untouchedRet = isUntouched(node);
+      if (untouchedRet) {
+        const sourceRange = untouchedRet === true ? range : untouchedRet;
+        if (!sourceRange) {
+          throw new Error(
+            `Node of type ${node.type} is marked as untouched but does not have valid source offsets`,
+          );
+        }
+        context.writeSource(
+          sourceRange.start,
+          sourceRange.end,
+          getMappingData(node),
+        );
+        return;
+      }
+
+      const printer = printers[node.type] as
+        | NodePrinter<AST_NODE_TYPES, Data>
+        | undefined;
+      if (!printer) {
+        throw new Error(`No printer registered for node type ${node.type}`);
+      }
+
+      const leadingComments = options.getLeadingComments?.(node);
+      if (leadingComments) {
+        for (const comment of leadingComments) {
+          writeComment(comment, context);
+        }
+      }
+
+      const generatedStart = generatedOffset;
+      printer(node, context);
+      const generatedEnd = generatedOffset;
+
+      const trailingComments = options.getTrailingComments?.(node);
+      if (trailingComments) {
+        for (const comment of trailingComments) {
+          writeComment(comment, context);
+        }
+      }
+      // If children nodes don't emit any mapping but the parent node itself
+      // can produce mapping, add that mapping
+      const lastMappingGeneratedEnd = mappings.at(-1)?.generatedEnd ?? 0;
+      if (range && lastMappingGeneratedEnd <= generatedStart) {
+        appendMapping(
+          range,
+          generatedStart,
+          generatedEnd,
+          getMappingData(node),
+        );
+      }
+    },
+    writeNodeList(nodes, separator) {
+      let needsSeparator = false;
+      for (const node of nodes) {
+        if (!node) {
+          if (needsSeparator) {
+            context.write(separator);
+          }
+          continue;
+        }
+
+        if (needsSeparator) {
+          context.write(separator);
+        }
+        context.writeNode(node);
+        needsSeparator = true;
+      }
+    },
+    writeExpressionListWithCommaSep(nodes) {
+      let needsSeparator = false;
+      for (const node of nodes) {
+        if (!node) {
+          if (needsSeparator) {
+            context.write(", ");
+          }
+          continue;
+        }
+
+        if (needsSeparator) {
+          context.write(", ");
+        }
+        const needsParens = expectAssignmentExprNeedsParen(node);
+        if (needsParens) {
+          context.write("(");
+          context.writeNode(node);
+          context.write(")");
+        } else {
+          context.writeNode(node);
+        }
+        needsSeparator = true;
+      }
+    },
+    writeNodeListWithNewLineSep(nodes) {
+      let lastRangeEnd: number | undefined;
+      let wroteNode = false;
+
+      for (const node of nodes) {
+        if (!node) {
+          continue;
+        }
+
+        const range = getNodeRange(node);
+        if (wroteNode) {
+          if (
+            lastRangeEnd !== undefined &&
+            range &&
+            range.start >= lastRangeEnd
+          ) {
+            context.writeSource(
+              lastRangeEnd,
+              range.start,
+              getMappingData(null),
+            );
+          } else {
+            context.write("\n");
+          }
+        }
+
+        context.writeNode(node);
+        wroteNode = true;
+
+        if (range) {
+          lastRangeEnd = range.end;
+        } else {
+          lastRangeEnd = undefined;
+        }
+      }
+    },
+    writeSource(start, end, data) {
+      if (end < start) {
+        return;
+      }
+
+      const generatedStart = generatedOffset;
+      context.write(options.source.slice(start, end));
+      appendMapping(
+        { start, end },
+        generatedStart,
+        generatedOffset,
+        data ?? getMappingData(null),
+      );
+    },
+    writePreservedNode(node) {
+      const range = getNodeRange(node);
+      if (!range) {
+        throw new Error(
+          `Cannot preserve node ${node.type} without source offsets`,
+        );
+      }
+      context.writeSource(range.start, range.end, getMappingData(node));
+    },
+    appendMapping,
+    createExtraMapping(sourceRange, generatedStart, generatedEnd, data) {
+      extraMappings.push({
+        sourceStart: sourceRange.start,
+        sourceEnd: sourceRange.end,
+        generatedStart,
+        generatedEnd,
+        data,
+      });
+    },
+    result() {
+      return {
+        code: chunks.join(""),
+        mappings: [...mappings, ...extraMappings].map(toVolarMapping),
+      };
+    },
+  };
+
+  return context;
+}