[Package Importer] Embedded Host

lib/index.mjs

@@ -4,6 +4,7 @@ export const compile = sass.compile;
 export const compileAsync = sass.compileAsync;
 export const compileString = sass.compileString;
 export const compileStringAsync = sass.compileStringAsync;
+export const nodePackageImporter = sass.nodePackageImporter;
 export const Logger = sass.Logger;
 export const CalculationInterpolation = sass.CalculationInterpolation
 export const CalculationOperation = sass.CalculationOperation
@@ -60,6 +61,10 @@ export default {
     defaultExportDeprecation();
     return sass.compileStringAsync;
   },
+  get nodePackageImporter() {
+    defaultExportDeprecation();
+    return sass.nodePackageImporter;
+  },
   get Logger() {
     defaultExportDeprecation();
     return sass.Logger;

lib/index.ts

@@ -31,6 +31,7 @@ export {
   compileString,
   compileAsync,
   compileStringAsync,
+  nodePackageImporter,
 } from './src/compile';
 export {render, renderSync} from './src/legacy';
 

lib/src/compile.ts

@@ -24,6 +24,8 @@ import {
   legacyImporterProtocol,
 } from './legacy/utils';
 
+export {nodePackageImporter} from './importer-registry';
+
 /// Allow the legacy API to pass in an option signaling to the modern API that
 /// it's being run in legacy mode.
 ///
@@ -45,7 +47,7 @@ export function compile(
   path: string,
   options?: OptionsWithLegacy<'sync'>
 ): CompileResult {
-  const importers = new ImporterRegistry(options);
+  const importers = new ImporterRegistry(options, path);
   return compileRequestSync(
     newCompilePathRequest(path, importers, options),
     importers,
@@ -57,7 +59,7 @@ export function compileString(
   source: string,
   options?: StringOptionsWithLegacy<'sync'>
 ): CompileResult {
-  const importers = new ImporterRegistry(options);
+  const importers = new ImporterRegistry(options, options?.url);
   return compileRequestSync(
     newCompileStringRequest(source, importers, options),
     importers,
@@ -69,7 +71,7 @@ export function compileAsync(
   path: string,
   options?: OptionsWithLegacy<'async'>
 ): Promise<CompileResult> {
-  const importers = new ImporterRegistry(options);
+  const importers = new ImporterRegistry(options, path);
   return compileRequestAsync(
     newCompilePathRequest(path, importers, options),
     importers,
@@ -81,7 +83,7 @@ export function compileStringAsync(
   source: string,
   options?: StringOptionsWithLegacy<'async'>
 ): Promise<CompileResult> {
-  const importers = new ImporterRegistry(options);
+  const importers = new ImporterRegistry(options, options?.url);
   return compileRequestAsync(
     newCompileStringRequest(source, importers, options),
     importers,

lib/src/importer-registry.ts

@@ -7,10 +7,20 @@ import {URL} from 'url';
 import {inspect} from 'util';
 
 import * as utils from './utils';
-import {FileImporter, Importer, Options} from './vendor/sass';
+import {legacyImporterProtocol} from './legacy/utils';
+
+import {
+  FileImporter,
+  Importer,
+  NodePackageImporter,
+  Options,
+} from './vendor/sass';
 import * as proto from './vendor/embedded_sass_pb';
 import {catchOr, thenOr, PromiseOr} from './utils';
 
+export const nodePackageImporter: NodePackageImporter =
+  Symbol() as NodePackageImporter;
+
 /**
  * A registry of importers defined in the host that can be invoked by the
  * compiler.
@@ -28,9 +38,9 @@ export class ImporterRegistry<sync extends 'sync' | 'async'> {
   /** The next ID to use for an importer. */
   private id = 0;
 
-  constructor(options?: Options<sync>) {
+  constructor(options?: Options<sync>, entryPointURL?: string | URL) {
     this.importers = (options?.importers ?? [])
-      .map(importer => this.register(importer))
+      .map(importer => this.register(importer, entryPointURL))
       .concat(
         (options?.loadPaths ?? []).map(
           path =>
@@ -43,10 +53,31 @@ export class ImporterRegistry<sync extends 'sync' | 'async'> {
 
   /** Converts an importer to a proto without adding it to `this.importers`. */
   register(
-    importer: Importer<sync> | FileImporter<sync>
+    importer: Importer<sync> | FileImporter<sync> | NodePackageImporter,
+    _entryPointURL?: string | URL
   ): proto.InboundMessage_CompileRequest_Importer {
     const message = new proto.InboundMessage_CompileRequest_Importer();
-    if ('canonicalize' in importer) {
+    if (typeof importer === 'symbol') {
+      if (importer !== nodePackageImporter) {
+        throw 'Incorrect Node Package Importer used';
+      }
+      const importerMessage = new proto.NodePackageImporter();
+      let entryPointURL = _entryPointURL ?? require.main?.filename;
+      entryPointURL = entryPointURL?.toString();
+      if (entryPointURL === legacyImporterProtocol)
+        entryPointURL = require.main?.filename;
+
+      if (!entryPointURL) {
+        throw new Error(
+          'Node Package Importer requires access to a filesystem.'
+        );
+      }
+      importerMessage.entryPointUrl = entryPointURL;
+      message.importer = {
+        case: 'nodePackageImporter',
+        value: importerMessage,
+      };
+    } else if ('canonicalize' in importer) {
       if ('findFileUrl' in importer) {
         throw new Error(
           'Importer may not contain both canonicalize() and findFileUrl(): ' +

lib/src/legacy/index.ts

@@ -5,6 +5,7 @@
 import * as fs from 'fs';
 import * as p from 'path';
 import {pathToFileURL, URL} from 'url';
+import {nodePackageImporter} from '../importer-registry';
 
 import {Exception} from '../exception';
 import {
@@ -31,6 +32,8 @@ import {
   LegacyStringOptions,
   Options,
   StringOptions,
+  Importer,
+  FileImporter,
 } from '../vendor/sass';
 import {wrapFunction} from './value/wrap';
 import {endOfLoadProtocol, LegacyImporterWrapper} from './importer';
@@ -140,25 +143,26 @@ function convertOptions<sync extends 'sync' | 'async'>(
     functions[signature.trimLeft()] = wrapFunction(self, callback, sync);
   }
 
-  const importers =
+  let importers;
+  if (
     options.importer &&
     (!(options.importer instanceof Array) || options.importer.length > 0)
-      ? [
-          new LegacyImporterWrapper(
-            self,
-            options.importer instanceof Array
-              ? options.importer
-              : [options.importer],
-            options.includePaths ?? [],
-            options.file ?? 'stdin',
-            sync
-          ),
-        ]
-      : undefined;
+  ) {
+    importers = [
+      new LegacyImporterWrapper(
+        self,
+        options.importer instanceof Array
+          ? options.importer
+          : [options.importer],
+        options.includePaths ?? [],
+        options.file ?? 'stdin',
+        sync
+      ),
+    ];
+  }
 
-  return {
+  const convertedOptions = {
     functions,
-    importers,
     sourceMap: wasSourceMapRequested(options),
     sourceMapIncludeSources: options.sourceMapContents,
     loadPaths: importers ? undefined : options.includePaths,
@@ -167,8 +171,24 @@ function convertOptions<sync extends 'sync' | 'async'>(
     verbose: options.verbose,
     charset: options.charset,
     logger: options.logger,
-    legacy: true,
+    legacy: true as const,
   };
+
+  // Use separate return statements, as applying logic directly to the inclusion
+  // of `nodePackageImporter` causes the symbol to use its unique flag.
+  // See https://github.com/microsoft/TypeScript/issues/55901
+  if (options.pkgImporter === 'node') {
+    importers = importers || [];
+    return {
+      ...convertedOptions,
+      importers: [nodePackageImporter, ...importers],
+    };
+  } else {
+    return {
+      ...convertedOptions,
+      importers,
+    };
+  }
 }
 
 // Converts `LegacyStringOptions` into new API `StringOptions`.
@@ -178,14 +198,20 @@ function convertStringOptions<sync extends 'sync' | 'async'>(
 ): StringOptions<sync> & {legacy: true} {
   const modernOptions = convertOptions(options, sync);
 
+  // Find the first non-nodePackageImporter to pass as legacy `importer` option.
+  // nodePackageImporter will be passed in `modernOptions.importers`.
+  const importer = modernOptions.importers?.find(
+    _importer => _importer !== nodePackageImporter
+  ) as Importer<sync> | FileImporter<sync>;
+
   return {
     ...modernOptions,
     url: options.file
       ? options.importer
         ? pathToLegacyFileUrl(options.file)
         : pathToFileURL(options.file)
       : new URL(legacyImporterProtocol),
-    importer: modernOptions.importers ? modernOptions.importers[0] : undefined,
+    importer,
     syntax: options.indentedSyntax ? 'indented' : 'scss',
   };
 }

package.json

@@ -1,7 +1,7 @@
 {
   "name": "sass-embedded",
   "version": "1.69.5",
-  "protocol-version": "2.3.0",
+  "protocol-version": "3.0.0-dev",
   "compiler-version": "1.69.5",
   "description": "Node.js library that communicates with Embedded Dart Sass using the Embedded Sass protocol",
   "repository": "sass/embedded-host-node",