feat: Update eyeglass integration to support synchronous preprocessing.

Author: chriseppstein

packages/@css-blocks/eyeglass/README.md

@@ -12,16 +12,18 @@ Here's an example `css-blocks.config.js` file using this package.
 ```js
 import sass from "node-sass";
 import eyeglass from "eyeglass";
-import { adaptor } from "@css-blocks/eyeglass";
+import { adaptor, adaptorSync } from "@css-blocks/eyeglass";
 
 const sassOptions = {
   outputStyle: "expanded"
 };
 
 const scss = adaptor(sass, eyeglass, sassOptions);
+const scssSync = adaptorSync(sass, eyeglass, sassOptions);
 
 module.exports = {
   preprocessors: { scss }
+  preprocessorsSync: { scss: scssSync }
 };
 ```
 
@@ -67,7 +69,7 @@ eyeglass adaptors from other libraries that use this integration.
 
 const sass = require("node-sass");
 const Eyeglass = require("eyeglass");
-import { adaptAll } from "@css-blocks/eyeglass";
+import { adaptAll, adaptAllSync } from "@css-blocks/eyeglass";
 
 // See the documentation for your module to know how to import
 // its adaptors.
@@ -79,6 +81,10 @@ const sassOptions = {
   // Where important, these options might be overridden by the module itself.
 };
 
+const sassOptionsSync = Object.assign({}, sassOptions, {
+  // if necessary use different options for synchronous compilation (e.g. synchronous versions of JS functions)
+});
+
 // While it's probably irrelevant, the order of the adaptors here
 // does matter, the first one that wants to process a file will win.
 const eyeglassAdaptors = [
@@ -90,5 +96,8 @@ export default {
   preprocesors: {
     scss: adaptAll(eyeglassAdaptors, sass, eyeglass, sassOptions),
   }
+  preprocesorsSync: {
+    scss: adaptAllSync(eyeglassAdaptors, sass, eyeglass, sassOptionsSync),
+  }
 };
 ```

packages/@css-blocks/eyeglass/src/index.ts

@@ -1,11 +1,13 @@
-import type { OptionalPreprocessor, Preprocessor, ProcessedFile, ResolvedConfiguration } from "@css-blocks/core";
+import type { OptionalPreprocessor, OptionalPreprocessorSync, Preprocessor, PreprocessorSync, ProcessedFile, ResolvedConfiguration } from "@css-blocks/core";
 import type { EyeglassOptions, default as Eyeglass } from "eyeglass"; // works, even tho a cjs export. huh.
 import type { Result, SassError } from "node-sass";
 import type SassImplementation from "node-sass";
 import { sep as PATH_SEPARATOR } from "path";
 
 export type Adaptor = (sass: typeof SassImplementation, eyeglass: typeof Eyeglass, options: EyeglassOptions) => Preprocessor;
+export type AdaptorSync = (sass: typeof SassImplementation, eyeglass: typeof Eyeglass, options: EyeglassOptions) => PreprocessorSync;
 export type OptionalAdaptor = (sass: typeof SassImplementation, eyeglass: typeof Eyeglass, options: EyeglassOptions) => OptionalPreprocessor;
+export type OptionalAdaptorSync = (sass: typeof SassImplementation, eyeglass: typeof Eyeglass, options: EyeglassOptions) => OptionalPreprocessorSync;
 
 /**
  * Given a Sass compiler (either dart-sass or node-sass), an Eyeglass
@@ -40,13 +42,40 @@ export const adaptor: Adaptor = (sass: typeof SassImplementation, eyeglass: type
     };
 };
 
+/**
+ * Given a Sass compiler (either dart-sass or node-sass), an Eyeglass
+ * constructor, and common eyeglass/sass options. This function returns a
+ * sync preprocessor, which is a function that can be used preprocess a single file.
+ *
+ * This function ensures that Sass is properly configured using the common
+ * options for each file and that source map information is passed along to CSS
+ * Blocks for correct error reporting.
+ */
+export const adaptorSync: AdaptorSync = (sass: typeof SassImplementation, eyeglass: typeof Eyeglass, options: EyeglassOptions = {}) => {
+    return (file: string, data: string) => {
+        const sassOptions = Object.assign({}, options, {
+            file,
+            data,
+            sourceMap: true,
+            outFile: file.replace(/scss$/, "css"),
+        });
+        let res = sass.renderSync(eyeglass(sassOptions));
+        return {
+            content: res.css.toString(),
+            sourceMap: res.map.toString(),
+            dependencies: res.stats.includedFiles,
+        };
+    };
+};
+
 /**
  * This is the core interface that adaptAll depends on to use an object (as
  * opposed to an OptionalAdaptor function) to create a preprocessor.
  */
 export interface PreprocessorProvider {
     init(sass: typeof SassImplementation, eyeglass: typeof Eyeglass, options: EyeglassOptions): void;
     preprocessor(): Preprocessor | OptionalPreprocessor;
+    preprocessorSync(): PreprocessorSync | OptionalPreprocessorSync;
 }
 
 /**
@@ -56,7 +85,8 @@ export interface PreprocessorProvider {
 function isPreprocessorProvider(obj: unknown): obj is PreprocessorProvider {
     if (typeof obj !== "object" || obj === null) return false;
     let provider = <PreprocessorProvider>obj;
-    return typeof provider.init === "function" && typeof provider.preprocessor === "function";
+    return typeof provider.init === "function" && typeof provider.preprocessor === "function"
+        && typeof provider.preprocessorSync === "function";
 }
 
 /**
@@ -66,6 +96,7 @@ function isPreprocessorProvider(obj: unknown): obj is PreprocessorProvider {
 export class DirectoryScopedPreprocessor implements PreprocessorProvider {
     protected filePrefix: string;
     protected scssProcessor: Preprocessor | undefined;
+    protected scssProcessorSync: PreprocessorSync | undefined;
 
     /**
      * Instantiates the preprocessor provider.
@@ -91,7 +122,10 @@ export class DirectoryScopedPreprocessor implements PreprocessorProvider {
      * eyeglass.VERSION.
      */
     init(sass: typeof SassImplementation, eyeglass: typeof Eyeglass, options: EyeglassOptions = {}) {
-        this.scssProcessor = adaptor(sass, eyeglass, this.setupOptions(options));
+        let sassOptions = this.setupOptions(options);
+        let sassOptionsSync = this.setupOptionsSync ? this.setupOptionsSync(sassOptions) : sassOptions;
+        this.scssProcessor = adaptor(sass, eyeglass, sassOptions);
+        this.scssProcessorSync = adaptorSync(sass, eyeglass, sassOptionsSync);
     }
 
     /**
@@ -107,6 +141,20 @@ export class DirectoryScopedPreprocessor implements PreprocessorProvider {
         return options;
     }
 
+    /**
+     * Subclasses can override this to manipulate/override the eyeglass options
+     * provided from the application that will be used for compiling this
+     * package's block files synchronously.
+     *
+     * The options passed into this function are those returned by
+     * setupOptions(), so this method only needs to update those options as
+     * appropriate to support synchronous compilation.
+     *
+     * If not provided, the options returned from setupOptions() are used for
+     * synchronous compilation.
+     */
+    setupOptionsSync?(options: EyeglassOptions): EyeglassOptions;
+
     /**
      * Subclasses can override this to decide whether a file should be processed.
      * By default it just checks that the file is within the directory for this
@@ -130,6 +178,23 @@ export class DirectoryScopedPreprocessor implements PreprocessorProvider {
             }
         };
     }
+
+    /**
+     * Subclasses shouldn't need to override this.
+     * @returns the preprocessor expected by adaptAll.
+     */
+    preprocessorSync(): OptionalPreprocessorSync {
+        return (file: string, data: string, config: ResolvedConfiguration) => {
+            if (!this.scssProcessorSync) {
+                throw new Error("Adaptor was not initialized!");
+            }
+            if (this.shouldProcessFile(file)) {
+                return this.scssProcessorSync(file, data, config);
+            } else {
+                return null;
+            }
+        };
+    }
 }
 
 /**
@@ -160,3 +225,32 @@ export function adaptAll(adaptors: Array<OptionalAdaptor | PreprocessorProvider>
         return lastResortProcessor(file, data, config);
     };
 }
+
+/**
+ * Creates a unified preprocessor for an application to use when consuming
+ * css blocks that have Sass preprocessed.
+ *
+ * The application provides a list of preprocessor adaptors, as well as the
+ * desired versions of sass, eyeglass and common Sass/Eyeglass options for
+ * compiling the sass files with eyeglass support.
+ */
+export function adaptAllSync(adaptors: Array<OptionalAdaptorSync | PreprocessorProvider>, sass: typeof SassImplementation, eyeglass: typeof Eyeglass, options: EyeglassOptions): PreprocessorSync {
+    let processors = adaptors.map(adaptor => {
+        if (isPreprocessorProvider(adaptor)) {
+            adaptor.init(sass, eyeglass, options);
+            return adaptor.preprocessorSync();
+        } else {
+            return adaptorSync(sass, eyeglass, options);
+        }
+    });
+    let lastResortProcessor = adaptorSync(sass, eyeglass, options);
+    return (file: string, data: string, config: ResolvedConfiguration) => {
+        for (let processor of processors) {
+            let result = processor(file, data, config);
+            if (result) {
+                return result;
+            }
+        }
+        return lastResortProcessor(file, data, config);
+    };
+}

packages/@css-blocks/eyeglass/test/package-test.ts

@@ -9,7 +9,7 @@ import SassImplementation = require("node-sass");
 import * as path from "path";
 import * as sinon from "sinon";
 
-import { DirectoryScopedPreprocessor, adaptAll, adaptor } from "../src/";
+import { DirectoryScopedPreprocessor, adaptAll, adaptAllSync, adaptor } from "../src/";
 
 const fakeSass = {
     render: sinon.spy(),
@@ -32,7 +32,7 @@ describe("@css-blocks/eyeglass", async () => {
     expect(adaptor(fakeSass, fakeEyeglass, {})).to.be.a("function");
   });
 
-  it("returned function returns a Promise when called", async () => {
+  it("returned function that returns a Promise when called", async () => {
     const injector = adaptor(fakeSass, fakeEyeglass, {});
     const result = injector("file", "data", resolveConfiguration({}));
 
@@ -139,6 +139,37 @@ describe("@css-blocks/eyeglass", async () => {
         name: "dos";
       }
 
+      /*# sourceMappingURL=two.block.css.map */`));
+  });
+  it("can adapt from several optional adaptors - synchronous", () => {
+    let package1Dir = fixture("package-1");
+    let package1File = fixture("package-1/one.block.scss");
+    let package2Dir = fixture("package-2");
+    let package2File = fixture("package-2/two.block.scss");
+    class Adaptor1 extends DirectoryScopedPreprocessor {
+      setupOptions(options: EyeglassOptions): EyeglassOptions {
+        return Object.assign({}, options, {outputStyle: "compact"});
+      }
+    }
+    class Adaptor2 extends DirectoryScopedPreprocessor {
+      setupOptions(options: EyeglassOptions): EyeglassOptions {
+        return Object.assign({}, options, {outputStyle: "expanded"});
+      }
+    }
+    let adaptor1 = new Adaptor1(package1Dir);
+    let adaptor2 = new Adaptor2(package2Dir);
+    let processor = adaptAllSync([adaptor1, adaptor2], SassImplementation, Eyeglass, {});
+    let result1 = processor(package1File, fs.readFileSync(package1File, "utf-8"), resolveConfiguration({}));
+    assert.equal(result1.content, dedent(`
+      :root { name: "uno"; }
+
+      /*# sourceMappingURL=one.block.css.map */`));
+    let result2 = processor(package2File, fs.readFileSync(package2File, "utf-8"), resolveConfiguration({}));
+    assert.equal(result2.content, dedent(`
+      :root {
+        name: "dos";
+      }
+
       /*# sourceMappingURL=two.block.css.map */`));
   });
 });