Support async bundling with JS resolver (parcel-bundler#263)

Author: devongovett

Cargo.lock

@@ -100,6 +100,25 @@ let {code, map} = css.bundle({
 });
 ```
 
+The `bundleAsync` API is an asynchronous version of `bundle`, which also accepts a custom `resolver` object. This allows you to provide custom JavaScript functions for resolving `@import` specifiers to file paths, and reading files from the file system (or another source). The `read` and `resolve` functions are both optional, and may either return a string synchronously, or a Promise for asynchronous resolution.
+
+```js
+let {code, map} = await css.bundleAsync({
+  filename: 'style.css',
+  minify: true,
+  resolver: {
+    read(filePath) {
+      return fs.readFileSync(filePath, 'utf8');
+    },
+    resolve(specifier, from) {
+      return path.resolve(path.dirname(from), specifier);
+    }
+  }
+});
+```
+
+Note that using a custom resolver can slow down bundling significantly, especially when reading files asynchronously. Use `readFileSync` rather than `readFile` if possible for better performance, or omit either of the methods if you don't need to override the default behavior.
+
 ### From Rust
 
 See the Rust API docs on [docs.rs](https://docs.rs/parcel_css).

README.md

@@ -19,8 +19,10 @@ parcel_sourcemap = { version = "2.1.0", features = ["json"] }
 jemallocator = { version = "0.3.2", features = ["disable_initial_exec_tls"] }
 
 [target.'cfg(not(target_arch = "wasm32"))'.dependencies]
-napi = {version = "2.2.0", default-features = false, features = ["napi4", "compat-mode", "serde-json"]}
+napi = {version = "2.2.0", default-features = false, features = ["napi4", "napi5", "compat-mode", "serde-json"]}
 napi-derive = "2"
+crossbeam-channel = "0.5.6"
+rayon = "1.5.1"
 
 [target.'cfg(target_arch = "wasm32")'.dependencies]
 js-sys = "0.3"

node/Cargo.toml

@@ -45,6 +45,22 @@ export interface TransformOptions {
 
 export type BundleOptions = Omit<TransformOptions, 'code'>;
 
+export interface BundleAsyncOptions extends BundleOptions {
+  resolver?: Resolver;
+}
+
+/** Custom resolver to use when loading CSS files. */
+export interface Resolver {
+  /** Read the given file and return its contents as a string. */
+  read?: (file: string) => string | Promise<string>;
+
+  /**
+   * Resolve the given CSS import specifier from the provided originating file to a
+   * path which gets passed to `read()`.
+   */
+  resolve?: (specifier: string, originatingFile: string) => string | Promise<string>;
+}
+
 export interface Drafts {
   /** Whether to enable CSS nesting. */
   nesting?: boolean,
@@ -226,3 +242,8 @@ export declare function browserslistToTargets(browserslist: string[]): Targets;
  * Bundles a CSS file and its dependencies, inlining @import rules.
  */
 export declare function bundle(options: BundleOptions): TransformResult;
+
+/**
+ * Bundles a CSS file and its dependencies asynchronously, inlining @import rules.
+ */
+export declare function bundleAsync(options: BundleAsyncOptions): TransformResult;

node/index.d.ts

@@ -1,4 +1,4 @@
 import index from './index.js';
 
-const { transform, transformStyleAttribute, bundle, browserslistToTargets } = index;
-export { transform, transformStyleAttribute, bundle, browserslistToTargets };
+const { transform, transformStyleAttribute, bundle, bundleAsync, browserslistToTargets } = index;
+export { transform, transformStyleAttribute, bundle, bundleAsync, browserslistToTargets };