Update docs

.jsdoc.json

@@ -1,3 +1,3 @@
 {
-  "plugins": ["./node_modules/jsdoc-escape-at"]
+  "plugins": ["./node_modules/jsdoc-escape-at", "./node_modules/jsdoc-tsimport-plugin/index.js"]
 }

CHANGELOG.md

@@ -146,8 +146,6 @@
 
   By default, it uses an in-memory filesystem shim `@bundled-es-modules/memfs` in browser context, `node:fs` built-in module in Node context.
 
-All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
-
 ## [3.8.0](https://github.com/amzn/style-dictionary/compare/v3.7.2...v3.8.0) (2023-04-25)
 
 ### Features

bin/style-dictionary.js

@@ -2,11 +2,11 @@
 
 'use strict';
 
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import node_fs from 'node:fs';
 import JSON5 from 'json5';
 import program from 'commander';
-import path from 'path';
-import { fileURLToPath } from 'url';
-import node_fs from 'node:fs';
 // usually also node:fs in this context, but can be customized by user
 import { fs } from 'style-dictionary/fs';
 import StyleDictionary from 'style-dictionary';

docs/_coverpage.md

@@ -10,5 +10,6 @@
 [Get Started](README.md)
 
 [See what's new in 3.0!](version_3.md)
+[See what's new in 4.0!](version_4.md)
 
 ![color](#D9F8F5)

docs/_sidebar.md

@@ -2,6 +2,7 @@
 
   - [Overview](README.md)
   - [What's new in 3.0](version_3.md)
+  - [What's new in 4.0](version_4.md)
   - [Quick Start](quick_start.md)
   - [Examples](examples.md)
   - [Config](config.md)
@@ -13,6 +14,7 @@
   - [Architecture](architecture.md)
   - [Using the CLI](using_the_cli.md)
   - [Using the NPM Module](using_the_npm_module.md)
+  - [Using reference utilities](using_reference_utils.md)
   - [API](api.md)
   - [Parsers](parsers.md)
   - [Preprocessors](preprocessors.md)

docs/api.md

@@ -1,29 +1,108 @@
-<!--
-DO NOT EDIT THIS FILE DIRECTLY, THIS FILE IS GENERATED BY JSDOC!
-EDIT scripts/handlebars/templates/api.hbs OR JSDOC COMMENT INSTEAD!
--->
-
 # API
 
-### buildAllPlatforms
+## new StyleDictionary()
+
+> new StyleDictionary() ⇒ [<code>style-dictionary</code>](#module_style-dictionary)
+
+Create a new StyleDictionary instance.
+
+| Param        | Type                           | Description                                                                                                                                                                      |
+| ------------ | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| config       | [<code>Config</code>](#Config) | Configuration options to build your style dictionary. If you pass a string, it will be used as a path to a JSON config file. You can also pass an object with the configuration. |
+| options      | <code>Object</code>            | Options object when creating a new StyleDictionary instance.                                                                                                                     |
+| options.init | <code>Boolean</code>           | `true` by default but can be disabled to delay initializing the dictionary. You can then call `sdInstance.init()` yourself, e.g. for testing or error handling purposes.         |
+
+**Example**
+
+```js
+import StyleDictionary from 'style-dictionary';
+
+const sd = new StyleDictionary('config.json');
+const sdTwo = new StyleDictionary({
+  source: ['tokens/*.json'],
+  platforms: {
+    scss: {
+      transformGroup: 'scss',
+      buildPath: 'build/',
+      files: [
+        {
+          destination: 'variables.scss',
+          format: 'scss/variables',
+        },
+      ],
+    },
+    // ...
+  },
+});
+```
+
+## init
+
+> StyleDictionary.init() ⇒ [<code>Promise<style-dictionary></code>](#module_style-dictionary)
+
+Called automatically when doing `new StyleDictionary(config)` unless passing a second argument with `init` property set to `false`. In this scenario, you can call `.init()` manually, e.g. for testing or error handling purposes.
+
+## extend
+
+> StyleDictionary.extend(config) ⇒ [<code>Promise<style-dictionary></code>](#module_style-dictionary)
+
+Extend a Style Dictionary instance with a config object, to create an extension instance.
+
+| Param          | Type                            | Description                                                                                                                                                                       |
+| -------------- | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| config         | [<code>Config</code>](#Config)  | Configuration options to build your style dictionary. If you pass a string, it will be used as a path to a JSON config file. You can also pass an object with the configuration.  |
+| mutateOriginal | [<code>Boolean</code>](#Config) | Whether or not the original SD instance should be mutated during extension. `false` by default. You will likely never need to set this to `true`, consider this argument private. |
+
+**Example**
+
+```js
+import StyleDictionary from 'style-dictionary';
+
+const sd = new StyleDictionary('config.json');
+
+const sdExtended = await sd.extend({
+  source: ['tokens/*.json'],
+  platforms: {
+    scss: {
+      transformGroup: 'scss',
+      buildPath: 'build/',
+      files: [
+        {
+          destination: 'variables.scss',
+          format: 'scss/variables',
+        },
+      ],
+    },
+    // ...
+  },
+});
+```
+
+---
 
-> StyleDictionary.buildAllPlatforms() ⇒ [<code>style-dictionary</code>](#module_style-dictionary)
+## buildAllPlatforms
+
+> StyleDictionary.buildAllPlatforms() ⇒ [<code>Promise<style-dictionary></code>](#module_style-dictionary)
 
 The only top-level method that needs to be called
 to build the Style Dictionary.
 
 **Example**
 
 ```js
-const StyleDictionary = require('style-dictionary').extend('config.json');
-StyleDictionary.buildAllPlatforms();
+import StyleDictionary from 'style-dictionary';
+const sd = new StyleDictionary('config.json');
+
+// Async, so you can do `await` or .then() if you
+// want to execute code after buildAllPlatforms has completed
+await sd.buildAllPlatforms();
 ```
 
 ---
 
-### buildPlatform
+## buildPlatform
 
-> StyleDictionary.buildPlatform(platform) ⇒ [<code>style-dictionary</code>](#module_style-dictionary)
+> StyleDictionary.buildPlatform(platform) ⇒ [<code>Promise<style-dictionary></code>](#module_style-dictionary)
 
 Takes a platform and performs all transforms to
 the tokens object (non-mutative) then
@@ -40,7 +119,9 @@ build each platform defined in the config.
 **Example**
 
 ```js
-StyleDictionary.buildPlatform('web');
+// Async, so you can do `await` or .then() if you
+// want to execute code after buildAllPlatforms has completed
+await sd.buildPlatform('web');
 ```
 
 ```bash
@@ -49,19 +130,19 @@ $ style-dictionary build --platform web
 
 ---
 
-### cleanAllPlatforms
+## cleanAllPlatforms
 
-> StyleDictionary.cleanAllPlatforms() ⇒ [<code>style-dictionary</code>](#module_style-dictionary)
+> StyleDictionary.cleanAllPlatforms() ⇒ [<code>Promise<style-dictionary></code>](#module_style-dictionary)
 
 Does the reverse of [buildAllPlatforms](#buildAllPlatforms) by
 performing a clean on each platform. This removes all the files
 defined in the platform and calls the undo method on any actions.
 
 ---
 
-### cleanPlatform
+## cleanPlatform
 
-> StyleDictionary.cleanPlatform(platform) ⇒ [<code>style-dictionary</code>](#module_style-dictionary)
+> StyleDictionary.cleanPlatform(platform) ⇒ [<code>Promise<style-dictionary></code>](#module_style-dictionary)
 
 Takes a platform and performs all transforms to
 the tokens object (non-mutative) then
@@ -73,9 +154,9 @@ cleans all the files and performs the undo method of any [actions](actions.md).
 
 ---
 
-### exportPlatform
+## exportPlatform
 
-> StyleDictionary.exportPlatform(platform) ⇒ <code>Object</code>
+> StyleDictionary.exportPlatform(platform) ⇒ <code>Promise<Object></code>
 
 Exports a tokens object with applied
 platform transforms.
@@ -89,42 +170,7 @@ dictionary in JS build tools like webpack.
 
 ---
 
-### extend
-
-> StyleDictionary.extend(config) ⇒ [<code>style-dictionary</code>](#module_style-dictionary)
-
-Create a Style Dictionary
-
-| Param  | Type                           | Description                                                                                                                                                                      |
-| ------ | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| config | [<code>Config</code>](#Config) | Configuration options to build your style dictionary. If you pass a string, it will be used as a path to a JSON config file. You can also pass an object with the configuration. |
-
-**Example**
-
-```js
-const StyleDictionary = require('style-dictionary').extend('config.json');
-
-const StyleDictionary = require('style-dictionary').extend({
-  source: ['tokens/*.json'],
-  platforms: {
-    scss: {
-      transformGroup: 'scss',
-      buildPath: 'build/',
-      files: [
-        {
-          destination: 'variables.scss',
-          format: 'scss/variables',
-        },
-      ],
-    },
-    // ...
-  },
-});
-```
-
----
-
-### registerAction
+## registerAction
 
 > StyleDictionary.registerAction(action) ⇒ [<code>style-dictionary</code>](#module_style-dictionary)
 
@@ -165,7 +211,7 @@ StyleDictionary.registerAction({
 
 ---
 
-### registerFileHeader
+## registerFileHeader
 
 > StyleDictionary.registerFileHeader(options) ⇒ [<code>style-dictionary</code>](#module_style-dictionary)
 
@@ -191,7 +237,7 @@ StyleDictionary.registerFileHeader({
 
 ---
 
-### registerFilter
+## registerFilter
 
 > StyleDictionary.registerFilter(filter) ⇒ [<code>style-dictionary</code>](#module_style-dictionary)
 
@@ -216,7 +262,7 @@ StyleDictionary.registerFilter({
 
 ---
 
-### registerFormat
+## registerFormat
 
 > StyleDictionary.registerFormat(format) ⇒ [<code>style-dictionary</code>](#module_style-dictionary)
 
@@ -241,7 +287,7 @@ StyleDictionary.registerFormat({
 
 ---
 
-### registerParser
+## registerParser
 
 > StyleDictionary.registerParser(pattern, parse) ⇒ [<code>style-dictionary</code>](#module_style-dictionary)
 
@@ -265,7 +311,7 @@ StyleDictionary.registerParser({
 
 ---
 
-### registerPreprocessor
+## registerPreprocessor
 
 > StyleDictionary.registerPreprocessor({ name, preprocessor }) => [<code>style-dictionary</code>](#module_style-dictionary)
 
@@ -291,32 +337,7 @@ StyleDictionary.registerPreprocessor({
 
 ---
 
-### registerTemplate
-
-> ~~StyleDictionary.registerTemplate(template) ⇒ [<code>style-dictionary</code>](#module_style-dictionary)~~
-
-**_Deprecated_**
-
-Add a custom template to the Style Dictionary
-
-| Param             | Type                | Description                                                                 |
-| ----------------- | ------------------- | --------------------------------------------------------------------------- |
-| template          | <code>Object</code> |                                                                             |
-| template.name     | <code>String</code> | The name of your template. You will refer to this in your config.json file. |
-| template.template | <code>String</code> | Path to your lodash template                                                |
-
-**Example**
-
-```js
-StyleDictionary.registerTemplate({
-  name: 'Swift/colors',
-  template: __dirname + '/templates/swift/colors.template',
-});
-```
-
----
-
-### registerTransform
+## registerTransform
 
 > StyleDictionary.registerTransform(transform) ⇒ [<code>style-dictionary</code>](#module_style-dictionary)
 
@@ -352,7 +373,7 @@ StyleDictionary.registerTransform({
 
 ---
 
-### registerTransformGroup
+## registerTransformGroup
 
 > StyleDictionary.registerTransformGroup(transformGroup) ⇒ [<code>style-dictionary</code>](#module_style-dictionary)
 

docs/config.md

@@ -56,7 +56,7 @@ Here is an example using a CommonJS module for configuration:
 
 ```javascript
 // config.js
-module.exports = {
+export default {
   source: [`tokens/**/*.json`],
   // If you don't want to call the registerTransform method a bunch of times
   // you can override the whole transform object directly. This works because
@@ -116,20 +116,20 @@ You can also use Style Dictionary as an [npm module](using_the_npm_module.md) an
 
 ```javascript
 // build.js
-const StyleDictionary = require('style-dictionary');
+import StyleDictionary from 'style-dictionary';
 
-const myStyleDictionary = StyleDictionary.extend({
+const myStyleDictionary = new StyleDictionary({
   // configuration
 });
 
-myStyleDictionary.buildAllPlatforms();
+await myStyleDictionary.buildAllPlatforms();
 
 // You can also extend Style Dictionary multiple times:
-const myOtherStyleDictionary = myStyleDictionary.extend({
+const myOtherStyleDictionary = await myStyleDictionary.extend({
   // new configuration
 });
 
-myOtherStyleDictionary.buildAllPlatforms();
+await myOtherStyleDictionary.buildAllPlatforms();
 ```
 
 You would then change your npm script or CLI command to run that file with Node: