Merge pull request #1050 from amzn/changeset-release/v4

Version Packages (prerelease)

.changeset/pre.json

@@ -8,7 +8,11 @@
     "big-worms-collect-2",
     "big-worms-collect",
     "bright-timers-shout",
+    "fifty-dragons-heal",
+    "gorgeous-lamps-chew",
     "honest-toes-wink",
-    "nice-ears-shop"
+    "light-games-occur",
+    "nice-ears-shop",
+    "unlucky-cameras-draw"
   ]
 }

CHANGELOG.md

@@ -1,5 +1,80 @@
 # Changelog
 
+## 4.0.0-prerelease.2
+
+### Major Changes
+
+- a4542f4: BREAKING: StyleDictionaryInstance.properties & .allProperties have been removed. They were deprecated in v3 in favor of .tokens and .allTokens.
+- a4542f4: BREAKING: StyleDictionary to be initialized with a new API and have async methods. Use:
+
+  ```js
+  import StyleDictionary from 'style-dictionary';
+
+  /**
+   * old:
+   *   const sd = StyleDictionary.extend({ source: ['tokens.json'], platforms: {} });
+   *   sd.buildAllPlatforms();
+   */
+  const sd = new StyleDictionary({ source: ['tokens.json'], platforms: {} });
+  await sd.buildAllPlatforms();
+  ```
+
+  You can still extend a dictionary instance with an extended config, but `.extend()` is only used for this, it is no longer used to initialize the first instance:
+
+  ```js
+  import StyleDictionary from 'style-dictionary';
+
+  const sd = new StyleDictionary({ source: ['tokens.json'], platforms: {} });
+  const extended = await sd.extend({
+    fileHeader: {
+      myFileHeader: (defaultMessage) => {
+        return [...defaultMessage, 'hello, world!'];
+      },
+    },
+  });
+  ```
+
+  To ensure your initialized StyleDictionary instance is fully ready and has imported all your tokens, you can await `hasInitialized`:
+
+  ```js
+  import StyleDictionary from 'style-dictionary';
+
+  const sd = new StyleDictionary({ source: ['tokens.json'], platforms: {} });
+  await sd.hasInitialized;
+  console.log(sd.allTokens);
+  ```
+
+  For error handling and testing purposes, you can also manually initialize the style-dictionary config:
+
+  ```js
+  import StyleDictionary from 'style-dictionary';
+
+  const sd = new StyleDictionary({ source: ['tokens.js'], platforms: {} }, { init: false });
+  try {
+    await sd.init();
+  } catch (e) {
+    // handle error, e.g. when tokens.js file has syntax errors and cannot be imported
+  }
+  console.log(sd.allTokens);
+  ```
+
+  The main reason for an initialize step after class instantiation is that async constructors are not a thing in JavaScript, and if you return a promise from a constructor to "hack it", TypeScript will eventually trip over it.
+
+  Due to being able to dynamically (asynchronously) import ES Modules rather than synchronously require CommonJS modules, we had to make the APIs asynchronous, so the following methods are now async:
+
+  - extend
+  - exportPlatform
+  - buildAllPlatforms & buildPlatform
+  - cleanAllPlatforms & cleanPlatform
+
+  In a future release, most other methods will be made async or support async as well, such as parsers, transforms, formats etc.
+
+### Minor Changes
+
+- cedf8a0: Preprocessors are a new feature added to style-dictionary, which allows you to do any type of processing of the token dictionary **after** parsing, **before** resolving and transforming.
+  See [preprocessor docs](https://github.com/amzn/style-dictionary/tree/v4/docs/preprocessors.md) for more information.
+- a4542f4: options.log to be respected in all error logging, including platform specific logs.
+
 ## 4.0.0-prerelease.1
 
 ### Patch Changes

package.json

@@ -1,6 +1,6 @@
 {
   "name": "style-dictionary",
-  "version": "4.0.0-prerelease.1",
+  "version": "4.0.0-prerelease.2",
   "description": "Style once, use everywhere. A build system for creating cross-platform styles.",
   "keywords": [
     "style dictionary",