Merge 678c0c7 into 8ce0b36

svg-sprite · Mar 14, 2022 · 8228a7a · 8228a7a
2 parents 8ce0b36 + 678c0c7
commit 8228a7a
Show file tree

Hide file tree

Showing 5 changed files with 134 additions and 31 deletions.
diff --git a/README.md b/README.md
@@ -90,6 +90,17 @@ spriter.compile((error, result) => {
         }
     }
 });
+
+// Or compile the sprite async
+const { result } = await spriter.compileAsync();
+/* Write `result` files to disk (or do whatever with them ...) */
+for (const mode in result) {
+    for (const resource in result[mode]) {
+        fs.mkdirSync(path.dirname(result[mode][resource].path), { recursive: true });
+        fs.writeFileSync(result[mode][resource].path, result[mode][resource].contents);
+    }
+}
+
 ```
 
 As you can see, big parts of the above are dealing with disk I/O. In this regard, you can make your life easier by [using the Grunt or Gulp wrappers](docs/grunt-gulp.md) instead of the [standard API](docs/api.md).

diff --git a/docs/api.md b/docs/api.md
@@ -12,6 +12,7 @@ This file is part of the documentation of *svg-sprite* — a free low-level Node
 * [SVGSpriter([ config ])](#svgspriter-config-) — The spriter's constructor (always the entry point)
 * [SVGSpriter.add(file [, name, svg ])](#svgspriteraddfile--name-svg-) — Registering source SVG files
 * [SVGSpriter.compile([ config ,] callback )](#svgspritercompile-config--callback-) — Triggering the sprite compilation
+* [SVGSpriter.compileAsync([ config ,])](#svgspritercompileasync-config-) — Triggering the sprite compilation
 * [SVGSpriter.getShapes( dest , callback )](#svgspritergetshapes-dest--callback-) — Accessing the intermediate SVG resources
 
 To understand these methods' roles and interactions, please have a look at the following basic example first.
@@ -178,6 +179,47 @@ For each configured output mode (`css` in the example), the `result` object hold
 
 Please note that the resources are always returned as [vinyl](https://github.com/gulpjs/vinyl) files. Have a look above for an [example of how to write these files to disk](#example-using-glob-and-vinyl).
 
+#### SVGSpriter.compileAsync([ config ,])
+
+**Sprite async compilation** — Simple Promise wrapper on [SVGSpriter.compile](#svgspritercompile-config--callback-).
+
+##### Arguments
+
+**config** `{Object}` *(optional)* — Configuration object (same as in [SVGSpriter.compile](#svgspritercompile-config--callback-))
+
+##### Returns
+
+Promise
+
+* **Compilation Result** `{Object}` Object containing fields:
+    * **result** `{Object}` — Same as in [SVGSpriter.compile](#svgspritercompile-config--callback-)
+    * **data** `{Object}` — Same as in [SVGSpriter.compile](#svgspritercompile-config--callback-)
+
+##### Throws
+
+**error** `{Error}` — Error message in case the compilation has failed
+
+##### Compilation example
+
+Depending on the particular mode and render configuration, quite a lot of resources might be generated during a single compilation run. To understand the way *svg-sprite* returns these resources, please have a look at the following example:
+
+```js
+try {
+    const { result, data } = await spriter.compileAsync({
+        css: {
+            render: {
+                scss: true
+            },
+            example: true
+        }
+    });
+
+    console.log(result, data);
+} catch (error) {
+    console.error(error);
+}
+```
+
 #### SVGSpriter.getShapes( dest , callback )
 
 **Accessing the intermediate SVG resources** — Sometimes you may want to access the single transformed/optimized SVG files that *svg-sprite* produces in an intermediate step. Depending on the [configured shape transformations](configuration.md#shape-transformations) (e.g. SVG optimization with [SVGO](https://github.com/svg/svgo)), *svg-sprite* will need some time for transforming the files, which is why accessing them must be an asynchronous task.

diff --git a/lib/svg-sprite.js b/lib/svg-sprite.js
@@ -220,6 +220,23 @@ SVGSpriter.prototype.compile = function(config, cb) {
     this._compile();
 };
 
+/**
+ *
+ * @param {object} config                                   Configuration
+ * @returns {Promise<{result:{object}, data:{object}}>}     Results
+ */
+SVGSpriter.prototype.compileAsync = function(config) {
+    return new Promise((resolve, reject) => {
+        this.compile(config, (error, result, data) => {
+            if (error) {
+                return reject(error);
+            }
+
+            resolve({ result, data });
+        });
+    });
+};
+
 /**
  * Run the next compile task
  */

diff --git a/test/svg-sprite/minimal-configuration/error.test.js b/test/svg-sprite/minimal-configuration/error.test.js
@@ -0,0 +1,39 @@
+'use strict';
+
+const assert = require('assert').strict;
+const SVGSpriter = require('../../../lib/svg-sprite.js');
+
+class TestError extends Error {}
+
+describe('svg-sprite: errors', () => {
+    let spriter;
+
+    beforeEach(() => {
+        spriter = new SVGSpriter({
+            shape: {
+                dest: 'svg'
+            }
+        });
+    });
+
+    it('should throw error if compilation has failed in async mode', async() => {
+        spriter._layout = (_, cb) => {
+            cb(new TestError(), {}, {});
+        };
+
+        await assert.rejects(async() => {
+            await spriter.compileAsync();
+        }, TestError);
+    });
+
+    it('should throw error if compilation has failed in callback mode', done => {
+        spriter._layout = (_, cb) => {
+            cb(new TestError('test'), {}, {});
+        };
+
+        spriter.compile(error => {
+            assert.equal(error instanceof TestError, true);
+            done();
+        });
+    });
+});
diff --git a/test/svg-sprite/minimal-configuration/no-arguments.test.js b/test/svg-sprite/minimal-configuration/no-arguments.test.js
@@ -24,47 +24,41 @@ describe('svg-sprite: with no arguments', () => {
     });
 
     describe('with no SVG files', () => {
-        it('has an empty result', done => {
-            spriter.compile((error, result, data) => {
-                should(error).not.ok;
-                should(result).be.an.Object;
-                should(result).be.empty;
-                should(data).be.an.Object;
-                should(data).be.empty;
-                done();
-            });
+        it('has an empty result', async() => {
+            const { result, data } = await spriter.compileAsync();
+
+            should(result).be.an.Object;
+            should(result).be.empty;
+            should(data).be.an.Object;
+            should(data).be.empty;
         });
     });
 
     describe(`with ${weather.length} SVG files`, () => {
-        it(`returns ${weather.length} optimized shapes`, done => {
+        it(`returns ${weather.length} optimized shapes`, async() => {
             addFixtureFiles(spriter, weather, cwdWeather);
-            spriter.compile((error, result, data) => {
-                should(error).not.ok;
-                should(result).be.an.Object;
-                should(result).have.property('shapes');
-                should(result.shapes).be.an.Array;
-                should(result.shapes).have.lengthOf(weather.length);
-                should(data).be.an.Object;
-                should(data).be.empty;
-                done();
-            });
+            const { result, data } = await spriter.compileAsync();
+
+            should(result).be.an.Object;
+            should(result).have.property('shapes');
+            should(result.shapes).be.an.Array;
+            should(result.shapes).have.lengthOf(weather.length);
+            should(data).be.an.Object;
+            should(data).be.empty;
         });
     });
 
     describe(`with ${weather.length} SVG files with relative paths`, () => {
-        it(`returns ${weather.length} optimized shapes`, done => {
+        it(`returns ${weather.length} optimized shapes`, async() => {
             addRelativeFixtureFiles(spriter, weather, cwdWeather);
-            spriter.compile((error, result, data) => {
-                should(error).not.ok;
-                should(result).be.an.Object;
-                should(result).have.property('shapes');
-                should(result.shapes).be.an.Array;
-                should(result.shapes).have.lengthOf(weather.length);
-                should(data).be.an.Object;
-                should(data).be.empty;
-                done();
-            });
+            const { result, data } = await spriter.compileAsync();
+
+            should(result).be.an.Object;
+            should(result).have.property('shapes');
+            should(result.shapes).be.an.Array;
+            should(result.shapes).have.lengthOf(weather.length);
+            should(data).be.an.Object;
+            should(data).be.empty;
         });
     });
 });