style-dictionary 4.0.1 → 4.1.0

package/README.md

@@ -1,12 +1,8 @@
 <pre>
-<a href="https://amzn.github.io/style-dictionary/#/version_3">What's new in Style Dictionary 3.0!</a>
+<a href="https://styledictionary.com/version-4/migration/">What's new in Style Dictionary 4.0!</a>
 </pre>
 
-<pre>
-<a href="https://github.com/amzn/style-dictionary#version-4">What's coming in Style Dictionary 4.0?</a>
-</pre>
-
-<img src="docs/assets/logo.png" alt="Style Dictionary logo and mascot" title="&quot;Pascal&quot;" width="100" align="right" />
+<img src="docs/src/assets/logo.png" alt="Style Dictionary logo and mascot" title="&quot;Pascal&quot;" width="100" align="right" />
 
 [![npm version](https://img.shields.io/npm/v/style-dictionary.svg?style=flat-square)](https://badge.fury.io/js/style-dictionary)
 ![license](https://img.shields.io/npm/l/style-dictionary.svg?style=flat-square)
@@ -136,7 +132,7 @@ A style dictionary is a collection of design tokens, key/value pairs that descri
 
 ### config.json
 
-This tells the style dictionary build system how and what to build. The default file path is `config.json` or `config.js` in the root of the project, but you can name it whatever you want by passing in the `--config` flag to the [CLI](https://amzn.github.io/style-dictionary/#/using_the_cli).
+This tells the style dictionary build system how and what to build. The default file path is `config.json` or `config.js` in the root of the project, but you can name it whatever you want by passing in the `--config` flag to the [CLI](https://styledictionary.com/getting-started/using_the_cli/).
 
 ```json
 {
@@ -176,7 +172,7 @@ This tells the style dictionary build system how and what to build. The default
 | platform.buildPath                   | String (optional) | Base path to build the files, must end with a trailing slash.                                                                                                                                                                                                                 |
 | platform.files                       | Array (optional)  | Files to be generated for this platform.                                                                                                                                                                                                                                      |
 | platform.file.destination            | String (optional) | Location to build the file, will be appended to the buildPath.                                                                                                                                                                                                                |
-| platform.file.format                 | String (optional) | Format used to generate the file. Can be a built-in one or you can create your own. [More on formats](https://amzn.github.io/style-dictionary/#/formats)                                                                                                                      |
+| platform.file.format                 | String (optional) | Format used to generate the file. Can be a built-in one or you can create your own. [More on formats](https://styledictionary.com/reference/hooks/formats/)                                                                                                                   |
 | platform.file.options                | Object (optional) | A set of extra options associated with the file.                                                                                                                                                                                                                              |
 | platform.file.options.showFileHeader | Boolean           | If the generated file should have a "Do not edit + Timestamp" header (where the format supports it). By default is "true".                                                                                                                                                    |
 
@@ -224,7 +220,7 @@ float const SizeFontBase = 16.00f;
 
 The style dictionary framework comes with some example code to get you started. Install the node module globally, create a directory and `cd` into it.
 
-```
+```bash
 $ npm i -g style-dictionary
 $ mkdir MyStyleDictionary
 $ cd MyStyleDictionary
@@ -232,13 +228,13 @@ $ cd MyStyleDictionary
 
 Now run:
 
-```
+```bash
 $ style-dictionary init basic
 ```
 
 This command will copy over the example files found in [example](examples/) in this repo. Now you have an example project set up. You can make changes to the style dictionary and rebuild the project by running:
 
-```
+```bash
 $ style-dictionary build
 ```
 
@@ -313,7 +309,7 @@ StyleDictionary.registerTransform({
 StyleDictionary.buildAllPlatforms();
 ```
 
-For more information on creating your own transforms and formats, take a look at our [docs](https://amzn.github.io/style-dictionary/).
+For more information on creating your own transforms and formats, take a look at our [docs](https://styledictionary.com).
 
 ## Version 4
 
@@ -340,7 +336,7 @@ We are very open to feedback and collaboration, feel free to reach out to us in
 
 The mascot for Style Dictionary is ["Pascal"](https://github.com/amzn/style-dictionary/issues/97) the chameleon (seen below). You can also find them blending in as the logo throughout the documentation.
 
-<img src="docs/assets/logo.png" alt="Style Dictionary logo and mascot" title="&quot;Pascal&quot;" width="240" />
+<img src="docs/src/assets/logo.png" alt="Style Dictionary logo and mascot" title="&quot;Pascal&quot;" width="240" />
 
 ## Contributing
 

package/examples/advanced/assets-base64-embed/package.json

@@ -12,6 +12,6 @@
   "author": "",
   "license": "Apache-2.0",
   "devDependencies": {
-    "style-dictionary": "^4.0.1"
+    "style-dictionary": "^4.1.0"
   }
 }

package/examples/advanced/create-react-app/package.json

@@ -12,7 +12,7 @@
   },
   "devDependencies": {
     "eslint-config-react-app": "^7.0.1",
-    "style-dictionary": "^4.0.1"
+    "style-dictionary": "^4.1.0"
   },
   "resolutions": {
     "immer": "8.0.1",

package/examples/advanced/create-react-native-app/package.json

@@ -29,7 +29,7 @@
     "eslint-config-react-app": "^7.0.1",
     "jest": "~25.2.6",
     "react-test-renderer": "~16.13.1",
-    "style-dictionary": "^4.0.1"
+    "style-dictionary": "^4.1.0"
   },
   "jest": {
     "preset": "react-native"

package/examples/advanced/custom-parser/package.json

@@ -10,6 +10,6 @@
   "author": "",
   "license": "Apache-2.0",
   "devDependencies": {
-    "style-dictionary": "^4.0.1"
+    "style-dictionary": "^4.1.0"
   }
 }

package/examples/advanced/custom-transforms/package.json

@@ -16,6 +16,6 @@
   "author": "",
   "license": "Apache-2.0",
   "devDependencies": {
-    "style-dictionary": "^4.0.1"
+    "style-dictionary": "^4.1.0"
   }
 }

package/examples/advanced/font-face-rules/package.json

@@ -9,6 +9,6 @@
   },
   "license": "Apache-2.0",
   "devDependencies": {
-    "style-dictionary": "^4.0.1"
+    "style-dictionary": "^4.1.0"
   }
 }

package/examples/advanced/format-helpers/package.json

@@ -10,6 +10,6 @@
   "author": "",
   "license": "Apache-2.0",
   "devDependencies": {
-    "style-dictionary": "^4.0.1"
+    "style-dictionary": "^4.1.0"
   }
 }

package/examples/advanced/format-helpers/sd.config.js

@@ -3,7 +3,7 @@ import {
   fileHeader,
   formattedVariables,
   sortByReference,
-} from 'style-dictionary';
+} from 'style-dictionary/utils';
 
 export default {
   hooks: {

package/examples/advanced/matching-build-files/package.json

@@ -17,6 +17,6 @@
   "author": "Kelly Harrop <kn.harrop@gmail.com>",
   "license": "Apache-2.0",
   "devDependencies": {
-    "style-dictionary": "^4.0.1"
+    "style-dictionary": "^4.1.0"
   }
 }

package/examples/advanced/multi-brand-multi-platform/package.json

@@ -16,6 +16,6 @@
   "author": "",
   "license": "Apache-2.0",
   "devDependencies": {
-    "style-dictionary": "^4.0.1"
+    "style-dictionary": "^4.1.0"
   }
 }

package/examples/advanced/node-modules-as-config-and-properties/package.json

@@ -20,7 +20,7 @@
   },
   "homepage": "https://github.com/dbanksdesign/style-dictionary-node#readme",
   "devDependencies": {
-    "style-dictionary": "^4.0.1",
+    "style-dictionary": "^4.1.0",
     "tinycolor2": "^1.4.1"
   }
 }

package/examples/advanced/npm-module/package.json

@@ -17,6 +17,6 @@
   "author": "",
   "license": "Apache-2.0",
   "devDependencies": {
-    "style-dictionary": "^4.0.1"
+    "style-dictionary": "^4.1.0"
   }
 }

package/examples/advanced/referencing_aliasing/package.json

@@ -16,6 +16,6 @@
   "author": "",
   "license": "Apache-2.0",
   "devDependencies": {
-    "style-dictionary": "^4.0.1"
+    "style-dictionary": "^4.1.0"
   }
 }

package/examples/advanced/s3/package.json

@@ -16,6 +16,6 @@
   "devDependencies": {
     "aws-sdk": "^2.7.21",
     "fs-extra": "^1.0.0",
-    "style-dictionary": "^4.0.1"
+    "style-dictionary": "^4.1.0"
   }
 }

package/examples/advanced/tokens-deprecation/package.json

@@ -16,6 +16,6 @@
   "author": "",
   "license": "Apache-2.0",
   "devDependencies": {
-    "style-dictionary": "^4.0.1"
+    "style-dictionary": "^4.1.0"
   }
 }

package/examples/advanced/transitive-transforms/package.json

@@ -12,6 +12,6 @@
   "license": "ISC",
   "devDependencies": {
     "colorjs.io": "^0.5.2",
-    "style-dictionary": "^4.0.1"
+    "style-dictionary": "^4.1.0"
   }
 }

package/examples/advanced/variables-in-outputs/package.json

@@ -11,6 +11,6 @@
   "author": "",
   "license": "MIT",
   "devDependencies": {
-    "style-dictionary": "^4.0.1"
+    "style-dictionary": "^4.1.0"
   }
 }

package/examples/advanced/yaml-tokens/package.json

@@ -10,7 +10,7 @@
   "author": "",
   "license": "Apache-2.0",
   "devDependencies": {
-    "style-dictionary": "^4.0.1",
+    "style-dictionary": "^4.1.0",
     "yaml": "^1.10.0"
   }
 }

package/lib/StyleDictionary.d.ts

@@ -32,10 +32,10 @@ export default class StyleDictionary extends Register {
     get options(): import("../types/Config.ts").Config;
     _options: import("../types/Config.ts").Config | undefined;
     config: string | import("../types/Config.ts").Config;
-    /** @type {Tokens|TransformedTokens|PreprocessedTokens} */
-    tokens: Tokens | TransformedTokens | PreprocessedTokens;
-    /** @type {TransformedToken[]} */
-    allTokens: TransformedToken[];
+    /** @type {PreprocessedTokens} */
+    tokens: PreprocessedTokens;
+    /** @type {PreprocessedTokens[]} */
+    allTokens: PreprocessedTokens[];
     /** @type {boolean | undefined} */
     usesDtcg: boolean | undefined;
     /** @type {LogConfig} */
@@ -64,6 +64,14 @@ export default class StyleDictionary extends Register {
     unfilteredAllTokens: TransformedToken[];
     hasInitialized: Promise<any>;
     hasInitializedResolve: (value: any) => void;
+    /**
+     * Storing the platform specific transformed tokens so we can prevent re-running exportPlatform when we already know the outcome
+     * Same thing for platform specific configs, we don't need to call transformConfig again if we already know the outcome
+     */
+    /** @type {Record<string,Dictionary>} */
+    _dictionaries: Record<string, Dictionary>;
+    /** @type {Record<string,PlatformConfig>} */
+    _platformConfigs: Record<string, PlatformConfig>;
     /**
      * @param {{verbosity?: LogConfig['verbosity'], warnings?: LogConfig['warnings']}} [opts]
      * @returns
@@ -95,20 +103,47 @@ export default class StyleDictionary extends Register {
     shouldRunExpansion(expandCfg?: import("../types/Config.ts").ExpandConfig | undefined): boolean;
     /**
      * @param {string} platform
+     * @param {{ cache?: boolean }} [opts]
+     */
+    getPlatformConfig(platform: string, opts?: {
+        cache?: boolean;
+    } | undefined): import("../types/Config.ts").PlatformConfig;
+    /**
+     * @param {string} platform
+     * @param {{ cache?: boolean }} [opts]
+     */
+    getPlatformTokens(platform: string, opts?: {
+        cache?: boolean;
+    } | undefined): Promise<import("../types/DesignToken.ts").Dictionary>;
+    /**
+     * Public wrapper around _exportPlatform, returns only tokens object
+     * Here for backwards compatibility.
+     * @deprecated use getPlatformTokens instead
+     *
+     * @param {string} platform
+     * @param {{ cache?: boolean }} [opts]
      * @returns {Promise<TransformedTokens>}
      */
-    exportPlatform(platform: string): Promise<TransformedTokens>;
+    exportPlatform(platform: string, opts?: {
+        cache?: boolean;
+    } | undefined): Promise<TransformedTokens>;
+    /**
+     * @param {string} platform
+     * @returns {Promise<Dictionary>}
+     */
+    _exportPlatform(platform: string): Promise<Dictionary>;
     /**
      * This will get the dictionary / platformConfig for specified platform name
      * Runs transforms, reference resolutions
+     * @deprecated use getPlatformConfig / getPlatformTokens instead
      * @param {string} platform
+     * @param {{ cache?: boolean }} [opts]
      * @returns
      */
-    getPlatform(platform: string): Promise<{
-        dictionary: {
-            tokens: import("../types/DesignToken.ts").TransformedTokens;
-            allTokens: import("../types/DesignToken.ts").TransformedToken[];
-        };
+    getPlatform(platform: string, opts?: {
+        cache?: boolean;
+    } | undefined): Promise<{
+        dictionary: import("../types/DesignToken.ts").Dictionary;
         platformConfig: import("../types/Config.ts").PlatformConfig;
     }>;
     /**
@@ -134,24 +169,51 @@ export default class StyleDictionary extends Register {
     }>;
     /**
      * @param {string} platform
+     * @param {{ cache?: boolean }} [opts]
      */
-    formatPlatform(platform: string): Promise<{
+    formatPlatform(platform: string, opts?: {
+        cache?: boolean;
+    } | undefined): Promise<{
         output: unknown;
         destination: string | undefined;
     }[]>;
-    formatAllPlatforms(): Promise<{}>;
+    /**
+     * @param {{ cache?: boolean }} [opts]
+     * @returns
+     */
+    formatAllPlatforms(opts?: {
+        cache?: boolean;
+    } | undefined): Promise<{}>;
     /**
      * @param {string} platform
+     * @param {{ cache?: boolean }} [opts]
      * @returns
      */
-    buildPlatform(platform: string): Promise<this>;
-    buildAllPlatforms(): Promise<this>;
+    buildPlatform(platform: string, opts?: {
+        cache?: boolean;
+    } | undefined): Promise<this>;
+    /**
+     * @param {{ cache?: boolean }} [opts]
+     * @returns
+     */
+    buildAllPlatforms(opts?: {
+        cache?: boolean;
+    } | undefined): Promise<this>;
     /**
      * @param {string} platform
+     * @param {{ cache?: boolean }} [opts]
+     * @returns
+     */
+    cleanPlatform(platform: string, opts?: {
+        cache?: boolean;
+    } | undefined): Promise<this>;
+    /**
+     * @param {{ cache?: boolean }} [opts]
      * @returns
      */
-    cleanPlatform(platform: string): Promise<this>;
-    cleanAllPlatforms(): Promise<this>;
+    cleanAllPlatforms(opts?: {
+        cache?: boolean;
+    } | undefined): Promise<this>;
 }
 export type Volume = import("../types/Volume.ts").Volume;
 export type Config = import("../types/Config.ts").Config;

package/lib/StyleDictionary.js

@@ -78,7 +78,7 @@ export default class StyleDictionary extends Register {
   // Placeholder is transformed on prepublish -> see scripts/inject-version.js
   // Another option might be import pkg from './package.json' with { "type": "json" } which would work in both browser and node, but support is not there yet.
   // https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import#browser_compatibility
-  static VERSION = '4.0.1';
+  static VERSION = '4.1.0';
 
   /** @returns {Config} */
   get options() {
@@ -110,9 +110,9 @@ export default class StyleDictionary extends Register {
     super();
     this.config = config;
     this.options = {};
-    /** @type {Tokens|TransformedTokens|PreprocessedTokens} */
+    /** @type {PreprocessedTokens} */
     this.tokens = {};
-    /** @type {TransformedToken[]} */
+    /** @type {PreprocessedTokens[]} */
     this.allTokens = [];
     /** @type {boolean | undefined} */
     this.usesDtcg = undefined;
@@ -156,6 +156,15 @@ export default class StyleDictionary extends Register {
       this.hasInitializedResolve = resolve;
     });
 
+    /**
+     * Storing the platform specific transformed tokens so we can prevent re-running exportPlatform when we already know the outcome
+     * Same thing for platform specific configs, we don't need to call transformConfig again if we already know the outcome
+     */
+    /** @type {Record<string,Dictionary>} */
+    this._dictionaries = {};
+    /** @type {Record<string,PlatformConfig>} */
+    this._platformConfigs = {};
+
     // By default, always call async extend function when constructing new SD instance
     // However, for testability and managing error handling,
     // you can call constructor with { init: false }
@@ -352,6 +361,7 @@ export default class StyleDictionary extends Register {
       preprocessedTokens = expandTokens(preprocessedTokens, this.options);
     }
     this.tokens = preprocessedTokens;
+    this.allTokens = flattenTokens(/** @type {PreprocessedTokens} */ (this.tokens), this.usesDtcg);
     this.hasInitializedResolve(null);
 
     // For chaining
@@ -380,17 +390,51 @@ export default class StyleDictionary extends Register {
 
   /**
    * @param {string} platform
-   * @returns {Promise<TransformedTokens>}
+   * @param {{ cache?: boolean }} [opts]
    */
-  async exportPlatform(platform) {
-    await this.hasInitialized;
-
+  getPlatformConfig(platform, opts) {
     if (!platform || !this.platforms?.[platform]) {
-      throw new Error('Please supply a valid platform');
+      throw new Error(`Please supply a valid platform, "${platform}" does not exist`);
+    }
+    if (!this._platformConfigs[platform] || opts?.cache === false) {
+      this._platformConfigs[platform] = transformConfig(this.platforms[platform], this, platform);
+    }
+    return this._platformConfigs[platform];
+  }
+
+  /**
+   * @param {string} platform
+   * @param {{ cache?: boolean }} [opts]
+   */
+  async getPlatformTokens(platform, opts) {
+    if (!this._dictionaries[platform] || opts?.cache === false) {
+      const dictionary = await this._exportPlatform(platform);
+      this._dictionaries[platform] = dictionary;
     }
+    return this._dictionaries[platform];
+  }
+
+  /**
+   * Public wrapper around _exportPlatform, returns only tokens object
+   * Here for backwards compatibility.
+   * @deprecated use getPlatformTokens instead
+   *
+   * @param {string} platform
+   * @param {{ cache?: boolean }} [opts]
+   * @returns {Promise<TransformedTokens>}
+   */
+  async exportPlatform(platform, opts) {
+    const dictionary = await this.getPlatformTokens(platform, opts);
+    return dictionary.tokens;
+  }
 
-    // We don't want to mutate the original object
-    const platformConfig = transformConfig(this.platforms[platform], this, platform);
+  /**
+   * @param {string} platform
+   * @returns {Promise<Dictionary>}
+   */
+  async _exportPlatform(platform) {
+    await this.hasInitialized;
+    const platformConfig = this.getPlatformConfig(platform);
 
     let platformProcessedTokens = /** @type {PreprocessedTokens} */ (this.tokens);
 
@@ -541,35 +585,25 @@ export default class StyleDictionary extends Register {
         console.log(chalk.rgb(255, 140, 0).bold(err));
       }
     }
-
-    return exportableResult;
+    return { tokens: exportableResult, allTokens: flattenTokens(exportableResult, this.usesDtcg) };
   }
 
   /**
    * This will get the dictionary / platformConfig for specified platform name
    * Runs transforms, reference resolutions
+   * @deprecated use getPlatformConfig / getPlatformTokens instead
    * @param {string} platform
+   * @param {{ cache?: boolean }} [opts]
    * @returns
    */
-  async getPlatform(platform) {
+  async getPlatform(platform, opts) {
     await this.hasInitialized;
-    if (!this.platforms?.[platform]) {
-      throw new Error(`Platform "${platform}" does not exist`);
-    }
-
-    // We don't want to mutate the original object
-    const platformConfig = transformConfig(this.platforms[platform], this, platform);
-
-    // We need to transform the object before we resolve the
-    // variable names because if a value contains concatenated
-    // values like "1px solid {color.border.base}" we want to
-    // transform the original value (color.border.base) before
-    // replacing that value in the string.
-    const tokens = await this.exportPlatform(platform);
-    this.allTokens = /** @type {TransformedToken[]} */ (flattenTokens(tokens, this.usesDtcg));
-    // This is the dictionary object we pass to the file
-    // building and action methods.
-    return { dictionary: { tokens, allTokens: this.allTokens }, platformConfig };
+    const platformConfig = this.getPlatformConfig(platform, opts);
+    const dictionary = await this.getPlatformTokens(platform, opts);
+    return {
+      dictionary,
+      platformConfig,
+    };
   }
 
   /**
@@ -758,10 +792,13 @@ export default class StyleDictionary extends Register {
 
   /**
    * @param {string} platform
+   * @param {{ cache?: boolean }} [opts]
    */
-  async formatPlatform(platform) {
+  async formatPlatform(platform, opts) {
     await this.hasInitialized;
-    const { dictionary, platformConfig } = await this.getPlatform(platform);
+    const platformConfig = this.getPlatformConfig(platform, opts);
+    const dictionary = await this.getPlatformTokens(platform, opts);
+
     if (
       platformConfig.buildPath &&
       platformConfig.buildPath.slice(-1) !== '/' &&
@@ -805,7 +842,11 @@ export default class StyleDictionary extends Register {
     return formattedFiles.map(({ output, destination }) => ({ output, destination }));
   }
 
-  async formatAllPlatforms() {
+  /**
+   * @param {{ cache?: boolean }} [opts]
+   * @returns
+   */
+  async formatAllPlatforms(opts) {
     await this.hasInitialized;
     if (!this.platforms) {
       throw new Error('Cannot format platforms due to missing property "platforms" on config');
@@ -815,7 +856,7 @@ export default class StyleDictionary extends Register {
      * @param {string} platformKey
      */
     const getOutputsForPlatform = async (platformKey) => {
-      const outputs = await this.formatPlatform(platformKey);
+      const outputs = await this.formatPlatform(platformKey, opts);
       return { platform: platformKey, outputs };
     };
 
@@ -833,11 +874,13 @@ export default class StyleDictionary extends Register {
 
   /**
    * @param {string} platform
+   * @param {{ cache?: boolean }} [opts]
    * @returns
    */
-  async buildPlatform(platform) {
+  async buildPlatform(platform, opts) {
     await this.hasInitialized;
-    const { dictionary, platformConfig } = await this.getPlatform(platform);
+    const platformConfig = this.getPlatformConfig(platform, opts);
+    const dictionary = await this.getPlatformTokens(platform, opts);
 
     /**
      * @param {string} destination
@@ -853,7 +896,7 @@ export default class StyleDictionary extends Register {
       return this.volume.promises.writeFile(destination, output);
     };
 
-    const files = await this.formatPlatform(platform);
+    const files = await this.formatPlatform(platform, opts);
     if (files) {
       await Promise.all(
         files.map(({ destination, output }) => {
@@ -879,10 +922,14 @@ export default class StyleDictionary extends Register {
     return this;
   }
 
-  async buildAllPlatforms() {
+  /**
+   * @param {{ cache?: boolean }} [opts]
+   * @returns
+   */
+  async buildAllPlatforms(opts) {
     await this.hasInitialized;
     if (this.platforms) {
-      await Promise.all(Object.keys(this.platforms).map((key) => this.buildPlatform(key)));
+      await Promise.all(Object.keys(this.platforms).map((key) => this.buildPlatform(key, opts)));
     }
     // For chaining
     return this;
@@ -890,10 +937,12 @@ export default class StyleDictionary extends Register {
 
   /**
    * @param {string} platform
+   * @param {{ cache?: boolean }} [opts]
    * @returns
    */
-  async cleanPlatform(platform) {
-    const { dictionary, platformConfig } = await this.getPlatform(platform);
+  async cleanPlatform(platform, opts) {
+    const platformConfig = this.getPlatformConfig(platform, opts);
+    const dictionary = await this.getPlatformTokens(platform, opts);
     // collect logs, cleanFiles happens in parallel but we want to log in sequence
     const logs = await cleanFiles(platformConfig, this.volume);
     if (logs) {
@@ -918,10 +967,14 @@ export default class StyleDictionary extends Register {
     return this;
   }
 
-  async cleanAllPlatforms() {
+  /**
+   * @param {{ cache?: boolean }} [opts]
+   * @returns
+   */
+  async cleanAllPlatforms(opts) {
     await this.hasInitialized;
     if (this.platforms) {
-      await Promise.all(Object.keys(this.platforms).map((key) => this.cleanPlatform(key)));
+      await Promise.all(Object.keys(this.platforms).map((key) => this.cleanPlatform(key, opts)));
     }
     // For chaining
     return this;

package/lib/common/formatHelpers/createPropertyFormatter.d.ts

@@ -1,3 +1,12 @@
+/**
+ * Split a string comment by newlines and
+ * convert to multi-line comment if necessary
+ * @param {string} to_ret_token
+ * @param {string} comment
+ * @param {Formatting} options
+ * @returns {string}
+ */
+export function addComment(to_ret_token: string, comment: string, options: Formatting): string;
 /**
  * Creates a function that can be used to format a token. This can be useful
  * to use as the function on `dictionary.allTokens.map`. The formatting

package/lib/common/formatHelpers/createPropertyFormatter.js

@@ -40,7 +40,7 @@ const defaultFormatting = {
  * @param {Formatting} options
  * @returns {string}
  */
-function addComment(to_ret_token, comment, options) {
+export function addComment(to_ret_token, comment, options) {
   const { commentStyle, indentation } = options;
   let { commentPosition } = options;
 

package/lib/common/formatHelpers/fileHeader.js

@@ -12,6 +12,7 @@
  */
 
 /**
+ *
  * @typedef {import('../../../types/File.ts').File} File
  * @typedef {import('../../../types/File.ts').FileHeader} FileHeader
  * @typedef {import('../../../types/File.ts').FormattingOptions} Formatting

package/lib/common/formats.d.ts

@@ -1,7 +1,7 @@
 export default formats;
 export type Format = import("../../types/Format.ts").Format;
 export type FormatArgs = import("../../types/Format.ts").FormatFnArguments;
-export type FormattingOptions = import("../../types/File").FormattingOptions;
+export type FormattingOverrides = import("../../types/File").FormattingOverrides;
 export type OutputReferences = import("../../types/Format.ts").OutputReferences;
 export type Token = import("../../types/DesignToken.ts").TransformedToken;
 export type Tokens = import("../../types/DesignToken.ts").TransformedTokens;

package/lib/common/formats.js

@@ -49,7 +49,7 @@ import plistTemplate from './templates/ios/plist.template.js';
 /**
  * @typedef {import('../../types/Format.ts').Format} Format
  * @typedef {import('../../types/Format.ts').FormatFnArguments} FormatArgs
- * @typedef {import('../../types/File').FormattingOptions} FormattingOptions
+ * @typedef {import('../../types/File').FormattingOverrides} FormattingOverrides
  * @typedef {import('../../types/Format.ts').OutputReferences} OutputReferences
  * @typedef {import('../../types/DesignToken.ts').TransformedToken} Token
  * @typedef {import('../../types/DesignToken.ts').TransformedTokens} Tokens
@@ -60,11 +60,13 @@ import plistTemplate from './templates/ios/plist.template.js';
  */
 
 /**
- * remove prefix because the prefix option for createPropertyFormatting is not the same as the prefix inside header comment
- * @param {FormattingOptions} [formatting]
+ * Remove prefix because the prefix option for createPropertyFormatter
+ * is not the same as the prefix inside header comment
+ * @param {FormattingOverrides} [formatting]
  */
 function getFormattingCloneWithoutPrefix(formatting) {
   const formattingWithoutPrefix = structuredClone(formatting) ?? {};
+  // @ts-expect-error users are not supposed to pass "prefix" but they might because it used to be supported
   delete formattingWithoutPrefix.prefix;
   return formattingWithoutPrefix;
 }

package/lib/common/templates/scss/map-deep.template.js

@@ -12,6 +12,7 @@
  * @param {number} depth
  */
 function processJsonNode(obj, options, depth = 0) {
+  const indent = options.formatting?.indentation ?? '  ';
   let output = '';
   if (obj === null) {
     output += `''`;
@@ -22,15 +23,18 @@ function processJsonNode(obj, options, depth = 0) {
     output += `$${obj.name}`;
   } else {
     // if we have found a group of tokens, use the Sass group "(...)" syntax and loop -recursively- on the children
-    output += '(\n';
+    output += `(\n`;
     output += Object.keys(obj)
       .map(function (newKey) {
         const newProp = obj[newKey];
-        const indent = '  '.repeat(depth + 1);
-        return `${indent}'${newKey}': ${processJsonNode(newProp, options, depth + 1)}`;
+        return `${indent.repeat(depth + 1)}'${newKey}': ${processJsonNode(
+          newProp,
+          options,
+          depth + 1,
+        )}`;
       })
-      .join(',\n');
-    output += '\n' + '  '.repeat(depth) + ')';
+      .join(`,\n`);
+    output += `\n` + indent.repeat(depth) + ')';
   }
   return output;
 }
@@ -41,6 +45,8 @@ function processJsonNode(obj, options, depth = 0) {
  *   options: Config & LocalOptions
  * }} opts
  */
-export default ({ dictionary, options }) => `
+export default ({ dictionary, options }) => {
+  return `
 $${options.mapName ?? 'tokens'}: ${processJsonNode(dictionary.tokens, options)};
 `;
+};

package/lib/common/templates/scss/map-flat.template.js

@@ -1,3 +1,5 @@
+import { addComment } from '../../formatHelpers/createPropertyFormatter.js';
+
 /**
  * @typedef {import('../../../../types/DesignToken.ts').TransformedToken} TransformedToken
  * @typedef {import('../../../../types/Config.ts').Config} Config
@@ -11,14 +13,24 @@
  *   header: string
  * }} opts
  */
-export default ({ allTokens, options, header }) => `
-${header}$${options.mapName ?? 'tokens'}: (
-${allTokens
-  .map(
-    (token) =>
-      `${token.comment ? `  // ${token.comment}\n` : ''}  '${token.name}': ${
+export default ({ allTokens, options, header }) => {
+  const _f = options.formatting ?? {};
+  const f = {
+    ..._f,
+    indentation: _f.indentation ?? '  ',
+    commentStyle: _f.commentStyle ?? 'short',
+    commentPosition: _f.commentPosition ?? 'above',
+  };
+  return `
+${header}$${options.mapName ?? 'tokens'}: (\n${allTokens
+    .map((token, i, arr) => {
+      const tokenString = `${f.indentation}'${token.name}': ${
         options.usesDtcg ? token.$value : token.value
-      }`,
-  )
-  .join(',\n')}
-);`;
+      }${i !== arr.length - 1 ? ',' : ''}`;
+      if (token.comment && f.commentStyle !== 'none') {
+        return addComment(tokenString, token.comment, f);
+      }
+      return tokenString;
+    })
+    .join(`\n`)}\n);`;
+};

package/lib/common/transforms.js

@@ -832,6 +832,7 @@ export default {
       }
       const parsedVal = parseFloat(nonParsed);
       if (isNaN(parsedVal)) throwSizeError(token.name, nonParsed, 'rem');
+      if (parsedVal === 0) return Number.isInteger(nonParsed) ? 0 : '0';
       return parsedVal + 'rem';
     },
   },

package/lib/utils/groupMessages.d.ts

@@ -1,4 +1,4 @@
-export const verbosityInfo: "Use log.verbosity \"verbose\" or use CLI option --verbose for more details.";
+export const verbosityInfo: "Use log.verbosity \"verbose\" or use CLI option --verbose for more details.\nRefer to: https://styledictionary.com/reference/logging/";
 export class GroupMessages {
     /** @type {{[key: string]: string[]}} */
     groupedMessages: {

package/lib/utils/groupMessages.js

@@ -11,7 +11,7 @@
  * and limitations under the License.
  */
 
-export const verbosityInfo = `Use log.verbosity "verbose" or use CLI option --verbose for more details.`;
+export const verbosityInfo = `Use log.verbosity "verbose" or use CLI option --verbose for more details.\nRefer to: https://styledictionary.com/reference/logging/`;
 
 export class GroupMessages {
   constructor() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "style-dictionary",
-  "version": "4.0.1",
+  "version": "4.1.0",
   "description": "Style once, use everywhere. A build system for creating cross-platform styles.",
   "keywords": [
     "style dictionary",
@@ -59,6 +59,8 @@
     "test:coverage": "cd coverage/lcov-report && npx http-server -o -c-1",
     "test:update-snapshots": "web-test-runner --update-snapshots",
     "test:node": "mocha -r mocha-hooks.mjs './__integration__/**/*.test.js' './__tests__/**/*.test.js' './__node_tests__/**/*.test.js'",
+    "test:perf": "mocha -r mocha-hooks.mjs './__perf_tests__/**/*.test.js'",
+    "test:perf:debug": "web-test-runner --config wtr-perf.config.mjs --watch",
     "install-cli": "npm install -g $(npm pack)",
     "release": "npm run build && changeset publish",
     "prepare": "husky install",

package/types/Config.d.ts

@@ -1,6 +1,6 @@
 import type { DesignToken, DesignTokens, PreprocessedTokens } from './DesignToken.ts';
 import type { Filter } from './Filter.ts';
-import type { FileHeader, File, FormattingOptions } from './File.ts';
+import type { FileHeader, File, FormattingOverrides } from './File.ts';
 import type { Parser } from './Parser.ts';
 import type { Preprocessor } from './Preprocessor.ts';
 import type { Transform } from './Transform.ts';
@@ -21,7 +21,7 @@ export interface LocalOptions {
     fileHeader?: string | FileHeader;
     outputReferences?: OutputReferences;
     outputReferenceFallbacks?: boolean;
-    formatting?: FormattingOptions;
+    formatting?: FormattingOverrides;
     [key: string]: any;
 }
 export interface RegexOptions {

package/types/File.d.ts

@@ -2,16 +2,18 @@ import type { TransformedToken } from './DesignToken.ts';
 import type { FormatFn } from './Format.ts';
 import type { LocalOptions, Config } from './Config.ts';
 import type { Filter } from './Filter.ts';
-export interface FormattingOptions {
+export interface FormattingOptions extends FormattingOverrides {
     prefix?: string;
     suffix?: string;
     lineSeparator?: string;
-    header?: string;
-    footer?: string;
+    separator?: string;
+}
+export interface FormattingOverrides {
     commentStyle?: 'short' | 'long' | 'none';
     commentPosition?: 'above' | 'inline';
     indentation?: string;
-    separator?: string;
+    header?: string;
+    footer?: string;
     fileHeaderTimestamp?: boolean;
 }
 export type FileHeader = (defaultMessage: string[], options?: Config) => Promise<string[]> | string[];