espolar 0.1.6 → 0.2.1

package/README.md

@@ -75,8 +75,8 @@ Main entry point. Returns `PrintResult<Data>`.
 | --------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------ |
 | `source`              | `string`                           | The original source code (required)                                                        |
 | `isUntouched`         | `(node) => boolean \| SourceRange` | Determine if a node should be preserved from source. Default: checks `range`/`start`/`end` |
-| `getMappingData`      | `(node?) => Data`                  | Extract data for each mapping entry. Default: `() => ({})`                                 |
-| `combineMappingData`  | `(left, right) => Data`            | Merge data when adjacent mappings are combined. Default: returns `right`                   |
+| `getMappingData`      | `(node?) => Data`                  | Extract data for each mapping entry. Default: `() => undefined`                            |
+| `combineMappingData`  | `(left, right) => Data`            | Merge data when adjacent mappings are combined. Default: throws if `left !== right`        |
 | `printers`            | `Printers<Data>`                   | Override printers for specific `AST_NODE_TYPES`                                            |
 | `getLeadingComments`  | `(node) => Comment[] \| undefined` | Return comments to print before a touched node                                             |
 | `getTrailingComments` | `(node) => Comment[] \| undefined` | Return comments to print after a touched node                                              |

package/dist/index.d.ts

@@ -62,10 +62,9 @@ interface PrintResult<Data> {
   code: string;
   mappings: Mapping<Data>[];
 }
-interface PrintOptions<Data> {
+interface PrintOptionsBase<Data> {
   source: string;
   isUntouched?: (node: AST.Node) => boolean | SourceRange;
-  getMappingData?: (node?: AST.Node | null) => Data;
   combineMappingData?: (left: Data, right: Data) => Data;
   printers?: Printers<Data>;
   getLeadingComments?: (node: AST.Node) => Comment[] | undefined;
@@ -81,6 +80,11 @@ interface PrintOptions<Data> {
    */
   experimentalGetLeftParenSourceRange?: (node: AST.CallExpression | AST.NewExpression) => SourceRange | undefined;
 }
+interface MappingDataOptions<Data> {
+  getMappingData: (node?: AST.Node | null) => Data;
+}
+type MappingDataUndefinedOptions = { [K in keyof MappingDataOptions<0>]?: undefined };
+type PrintOptions<Data> = PrintOptionsBase<Data> & ([Data] extends [undefined] ? MappingDataUndefinedOptions : MappingDataOptions<Data>);
 interface PrinterContext<Data = any> {
   readonly options: PrintOptions<Data>;
   readonly source: string;
@@ -93,6 +97,8 @@ interface PrinterContext<Data = any> {
   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;
 }
 type NodePrinter<Key extends AST_NODE_TYPES, Data> = (node: Extract<AST.Node, {
   type: Key;
@@ -100,12 +106,11 @@ type NodePrinter<Key extends AST_NODE_TYPES, Data> = (node: Extract<AST.Node, {
 type Printers<Data> = { [K in AST_NODE_TYPES]?: NodePrinter<K, Data> };
 //#endregion
 //#region src/printer.d.ts
-declare function print<Data>(node: AST.Node, options: PrintOptions<Data>): PrintResult<Data>;
-declare function print<Data>(node: import("estree").Node, options: PrintOptions<Data>): PrintResult<Data>;
-declare function print<Data>(node: NodeLike, options: PrintOptions<Data>): PrintResult<Data>;
+declare function print<Data = undefined>(node: AST.Node, options: PrintOptions<Data>): PrintResult<Data>;
+declare function print<Data = undefined>(node: import("estree").Node, options: PrintOptions<Data>): PrintResult<Data>;
+declare function print<Data = undefined>(node: NodeLike, options: PrintOptions<Data>): PrintResult<Data>;
 declare function defaultIsUntouched(node: AST.Node): boolean | SourceRange;
-declare function defaultGetMappingData(node?: AST.Node | null): unknown;
-declare function defaultCombineMappingData(left: unknown, right: unknown): unknown;
+declare function defaultCombineMappingData<T>(left: T, right: T): T;
 //#endregion
 //#region src/printers.d.ts
 declare const defaultPrinters: {
@@ -385,4 +390,4 @@ declare function printKeywordType(node: Extract<AST.Node, {
   type: `${string}Keyword`;
 }>, context: PrinterContext): void;
 //#endregion
-export { type AST, type Comment, type NodeLike, type NodePrinter, type PrintOptions, type PrintResult, type PrinterContext, type SourceRange, defaultCombineMappingData, defaultGetMappingData, defaultIsUntouched, defaultPrinters, print };
+export { type AST, type Comment, type NodeLike, type NodePrinter, type PrintOptions, type PrintResult, type PrinterContext, type SourceRange, defaultCombineMappingData, defaultIsUntouched, defaultPrinters, print };

package/dist/index.js

@@ -1383,19 +1383,18 @@ function print(node, options) {
 function defaultIsUntouched(node) {
 	return getNodeRange(node) || false;
 }
-function defaultGetMappingData(node) {
-	return {};
-}
 function defaultCombineMappingData(left, right) {
-	return right;
+	if (left === right) return left;
+	throw new Error("Cannot combine mapping data with different values when no custom combineMappingData function is provided");
 }
 function createPrinterContext(options) {
 	const chunks = [];
 	const mappings = [];
+	const extraMappings = [];
 	let generatedOffset = 0;
 	const isUntouched = options.isUntouched ?? defaultIsUntouched;
-	const getMappingData = options.getMappingData ?? defaultGetMappingData;
-	const combineMappingData = options.combineMappingData ?? (options.getMappingData ? (left) => left : defaultCombineMappingData);
+	const getMappingData = options.getMappingData ?? (() => void 0);
+	const combineMappingData = options.combineMappingData ?? defaultCombineMappingData;
 	const printers = {
 		...defaultPrinters,
 		...options.printers
@@ -1492,14 +1491,23 @@ function createPrinterContext(options) {
 			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.map(toVolarMapping)
+				mappings: [...mappings, ...extraMappings].map(toVolarMapping)
 			};
 		}
 	};
 	return context;
 }
 //#endregion
-export { defaultCombineMappingData, defaultGetMappingData, defaultIsUntouched, defaultPrinters, print };
+export { defaultCombineMappingData, defaultIsUntouched, defaultPrinters, print };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "espolar",
-  "version": "0.1.6",
+  "version": "0.2.1",
   "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,88 @@
+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 | undefined)[],
+    separator: string,
+  ): void;
+  writeNodeListWithSourceGaps(
+    nodes: readonly (AST.Node | null | undefined)[],
+    fallbackSeparator: string,
+  ): 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,284 @@
+import type {
+  NodePrinter,
+  PrintOptions,
+  PrintResult,
+  PrinterContext,
+  Printers,
+} from "./api.ts";
+import { defaultPrinters } 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>;
+}
+
+function writeComment(context: InternalPrinterContext, comment: Comment): void {
+  if (comment.type === "Line") {
+    context.write("//" + comment.value + "\n");
+  } else {
+    context.write("/*" + comment.value + "*/");
+    if (comment.value.includes("\n")) {
+      context.write("\n");
+    }
+  }
+}
+
+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 c of leadingComments) {
+          writeComment(context, c);
+        }
+      }
+
+      const generatedStart = generatedOffset;
+      printer(node, context);
+      const generatedEnd = generatedOffset;
+
+      const trailingComments = options.getTrailingComments?.(node);
+      if (trailingComments) {
+        for (const c of trailingComments) {
+          writeComment(context, c);
+        }
+      }
+      // 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;
+      }
+    },
+    writeNodeListWithSourceGaps(nodes, fallbackSeparator) {
+      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(fallbackSeparator);
+          }
+        }
+
+        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;
+}