cartridge-resolver-plugin - npm Package Compare versions

Comparing version 1.0.1 to 2.0.0

package.json

 {
     "name": "cartridge-resolver-plugin",
-    "version": "1.0.1",
-    "description": "Provide the cartridge inheritance behavior same as Demandware server side scripts.",
+    "version": "2.0.0",
+    "description": "Webpack Plugin: Provide the cartridge inheritance behavior same as Demandware server side scripts.",
+    "keywords": ["webpack", "salesforce", "demandware", "cartridge", "compile"],
     "author": "Vinh Trinh <[e-mail]>",
-    "contributers": [{
-        "name": "Amblique Team",
-        "email": "[e-mail]",
-        "url": "https://amblique.com/"
-    }],
-    "license": "ISC",
-    "main": "index.js"
+    "contributers": [
+        {
+            "name": "Amblique Team",
+            "email": "[e-mail]",
+            "url": "https://amblique.com/"
+        }
+    ],
+    "license": "MIT",
+    "main": "src/index.js",
+    "devDependencies": {
+        "chai": "^4.2.0",
+        "mocha": "^5.2.0",
+        "webpack": "^4.27.1"
+    },
+    "scripts": {
+        "test": "./node_modules/.bin/mocha"
+    }
 }

README.md

@@ -1,25 +0,101 @@
-## Installation
+## Table of Contents
+- [Table of Contents](#table-of-contents)
+- [Badges and Build status](#badges-and-build-status)
+- [Webpack: Cartridge Resolver Plugin](#webpack-cartridge-resolver-plugin)
+  - [Asset Solving Rules](#asset-solving-rules)
+  - [Installation](#installation)
+  - [Usage](#usage)
+- [API Documentation](#api-documentation)
+  - [CartridgeResolverPlugin](#cartridgeresolverplugin)
+    - [new CartridgeResolverPlugin(cartridges, aliases)](#new-cartridgeresolverplugincartridges-aliases)
+    - [cartridgeResolverPlugin.apply(resolver)](#cartridgeresolverpluginapplyresolver)
+    - [cartridgeResolverPlugin.resolve(resolver, requestContext, resolveContext, callback)](#cartridgeresolverpluginresolveresolver-requestcontext-resolvecontext-callback)
+    - [cartridgeResolverPlugin.isAbsoluteCartridge(assetPath) ⇒ <code>boolean</code>](#cartridgeresolverpluginisabsolutecartridgeassetpath-%E2%87%92-codebooleancode)
+    - [cartridgeResolverPlugin.isAliasRequest(assetPath) ⇒ <code>boolean</code>](#cartridgeresolverpluginisaliasrequestassetpath-%E2%87%92-codebooleancode)
+    - [cartridgeResolverPlugin.getRelativeAsset(assetPath) ⇒ <code>string</code>](#cartridgeresolverplugingetrelativeassetassetpath-%E2%87%92-codestringcode)
+    - [cartridgeResolverPlugin.getCartridge(assetPath) ⇒ <code>string</code>](#cartridgeresolverplugingetcartridgeassetpath-%E2%87%92-codestringcode)
+    - [cartridgeResolverPlugin.getLocale(assetPath) ⇒ <code>string</code>](#cartridgeresolverplugingetlocaleassetpath-%E2%87%92-codestringcode)
+    - [cartridgeResolverPlugin.resolveFromCartrdiges(relativeAsset, cartridges, locale) ⇒ <code>string</code> \| <code>null</code>](#cartridgeresolverpluginresolvefromcartrdigesrelativeasset-cartridges-locale-%E2%87%92-codestringcode--codenullcode)
 
-```shell
-npm install --save-dev cartridge-resolver-plugin
+## Badges and Build status
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-brightgreen.svg)](https://opensource.org/licenses/MIT)
+![Coverage: 98.55%](https://img.shields.io/badge/Coverage-98.55%-brightgreen.svg)
+[![npm version](https://badge.fury.io/js/cartridge-resolver-plugin.svg)](https://badge.fury.io/js/cartridge-resolver-plugin)
+
 ```
+Test Coverage: 98.55%
++-----------+----------+----------+----------+----------+-------------------+
+| File      |  % Stmts | % Branch |  % Funcs |  % Lines | Uncovered Line #s |
++-----------+----------+----------+----------+----------+-------------------+
+| All files |    98.55 |    90.91 |      100 |    98.44 |                   |
+|  index.js |    98.55 |    90.91 |      100 |    98.44 |                62 |
++-----------+----------+----------+----------+----------+-------------------+
+```
 
-## Usage
 
+## Webpack: Cartridge Resolver Plugin
 
+Provide the cartridge inheritance behavior same as Demandware server side scripts with additional functionalities suports.
+
+### Asset Solving Rules
+
 ``` js
-const CartridgeResolverPlugin = require('cartridge-resolver-plugin');
++ ----------- + ----- + --------------------------- +
+| Cartridge   | Alias |            Assets           |
++ ----------- + ----- + --- - --- - --- - --- - --- +
+| cartridge_a |   a   |  1  |     |  3  |     |  5  |
+| cartridge_b |   b   |     |  2  |  3  |  4  |     |
+| cartridge_c |       |     |     |     |  4  |  5  |
+| cartridge_d |   d   |  1  |  2  |     |     |  5  |
++ ----------- + ----- + --------------------------- +
 ```
 
+1. Cartridge lookup priority follow the order of registered cartridges object ASC.
+2. Use special symbols to require the target asset.
+    1. `^` flag used to lookup super module asset, Example:
+        - `require('^')` - require same asset from lower priority cartridges
+        - `require('^/some/asset')` - require `some/asset` from lower priority cartridges
+        - `require('^:some/asset')` - same as above, require `some/asset` from lower priority cartridges
+    2. `*` flag used to lookup across registered cartridges
+        - `require('*/some/asset')` - require `some/asset` from any cartridges
+        - `require('*:some/asset')` - same as above, require `some/asset` from any cartridges
+    3. `~` flag used to lookup asset in current cartridge
+        - `require('~/some/asset')` - require `some/asset` from current cartridge
+        - `require('~:some/asset')` - same as above, require `some/asset` from current cartridge
+3. `superModule` are modules loaded from lower priority cartridges . For example: in `cartridge_b:2.js`, require super module mean lookup for asset `2.js` in 2 other lower priority `cartridge_c` and `cartridge_d`. The result will be `cartridge_d:2.js`
+4. Absolute cartridge can be used follow pattern: `{cartridge_name}:{asset_path}` or `{alias_name}:{asset_path}`. Solving the `asset_path` from exactly `cartridge_name` or `alias_name`. For example:
+    - `require('cartridge_d:1')` will return `cartridge_d/1.js`
+    - `require('c:5')` will return `cartridge_c/5.js`
+5. Named alias asset:
+    1. difference path with origin will be solve using asterisk `*` behavior. For example:
+        - From `cartridge_a/1.js` - `require('d/2')` which looking for `2.js` using `d` alias _(difference path with origin `1.js`)_ will equal `require('*/2')` and return `cartridge_b/2.js` _(since the `cartridge_b` has higher priority than `cartridge_d`)_
+        - From `cartridge_b/2.js` - `require('c/5')` which looking for `5.js` using `c` alias _(difference path with origin `2.js`)_ will equal `require('*/5')` and return `cartridge_a/5.js` _(since the `cartridge_a` has higher priority than `cartridge_c`)_
+    2. same path with origin will be solve using super module `^` behavior: For example:
+        - From `cartridge_a/1.js` - `require('a/1')` which looking for `1.js` using `a` alias _(same path with origin `1.js`)_ will equal `require('^/1')` and return `cartridge_d/1.js`
+6. By default, an asset will be lookup across cartridges and return the fist found. Except super module and absolute cartridge path. For example: in `cartridge_a:1.js`, require relative `./2` asset will return the first asset found from cartridge path. The result will be `cartridge_b:2.js`
+7. Required asset same path with the origin will considered as super module. For example: in `cartridge_a:1.js`, all requirements `require('^')` or `require('^:1')` or `require('^/1')` or `require('.')` or `require('./1')` will looking for `1.js` from lower priority cartridges . The result will be `cartridge_d:1.js`
+
+
+### Installation
+
+```shell
+npm install --save-dev cartridge-resolver-plugin
+```
+
+### Usage
+
 Register plugin to your `webpack.config.js`.
-For more informations, please have a look inside class `CartridgeResolverPlugin`
+For more informations, please have a look inside class [`CartridgeResolverPlugin`](./src/index.js)
 
 ``` js
 const cwd = process.cwd();
+const CartridgeResolverPlugin = require('cartridge-resolver-plugin');
 
-{
+module.exports = {
+    // your other webpack configs...
     resolve: {
         plugins: [new CartridgeResolverPlugin({
-            milwaukee_storefront: path.resolve(cwd, 'cartridges/milwaukee_storefront/cartridge/client'),
-            milwaukee_storefront_style_guide: path.resolve(cwd, 'cartridges/milwaukee_storefront_style_guide/cartridge/client'),
+            your_storefront: path.resolve(cwd, 'cartridges/your_storefront/cartridge/client'),
+            your_storefront_style_guide: path.resolve(cwd, 'cartridges/your_storefront_style_guide/cartridge/client'),
             plugin_wishlists: path.resolve(cwd, 'vendors/plugin_wishlists/cartridge/client'),
@@ -29,5 +105,182 @@ app_storefront_style_guide: path.resolve(cwd, 'cartridges/app_storefront_style_guide/cartridge/client'),
             app_storefront_base: path.resolve(cwd, 'cartridges/app_storefront_base/cartridge/client')
-        }, ['base', 'wishlist'])]
+        }, {
+            base: 'app_storefront_base',
+            core: 'app_storefront_core'
+        })]
     }
 }
-```
+```
+
+## API Documentation
+<a name="CartridgeResolverPlugin"></a>
+
+### CartridgeResolverPlugin
+Webpack: Cartridge Resolver Plugin
+
+Provide the cartridge inheritance behavior same as DW server side.
+
+- **Kind**: global class
+- **Author**: Vinh Trinh <[e-mail]>
+
+<a name="new_CartridgeResolverPlugin_new"></a>
+
+#### new CartridgeResolverPlugin(cartridges, aliases)
+Constructor
+
+
+| Param | Type | Description |
+| --- | --- | --- |
+| cartridges | <code>object</code> | An associative object where the key is the cartridge name                            and the value is the local installed cartridge path |
+| aliases | <code>object</code> | An associative object where the key is the alias name                            and the value is the full cartridge name |
+
+<a name="CartridgeResolverPlugin+apply"></a>
+
+#### cartridgeResolverPlugin.apply(resolver)
+Applying the plugin
+
+**Kind**: instance method of [<code>CartridgeResolverPlugin</code>](#CartridgeResolverPlugin)
+
+| Param | Type |
+| --- | --- |
+| resolver | <code>Resolver</code> |
+
+<a name="CartridgeResolverPlugin+resolve"></a>
+
+#### cartridgeResolverPlugin.resolve(resolver, requestContext, resolveContext, callback)
+Do the resolve asset for the given request
+
+Flags:
+```
+  *: solving asset from across registered cartridges
+  ^: solving asset from registered cartridges which have lower priority with current cartridge
+  ~: solving asset in current cartridge
+```
+
+Absolute asset path using with cartridge name or alias {@see isAbsoluteCartridge}
+ app_storefront_base:product/product === base:product/product
+
+**Kind**: instance method of [<code>CartridgeResolverPlugin</code>](#CartridgeResolverPlugin)
+
+| Param | Type | Description |
+| --- | --- | --- |
+| resolver | <code>Resolver</code> |  |
+| requestContext | <code>object</code> | The asset request object |
+| resolveContext | <code>object</code> |  |
+| callback | <code>function</code> | The callback function |
+
+<a name="CartridgeResolverPlugin+isAbsoluteCartridge"></a>
+
+#### cartridgeResolverPlugin.isAbsoluteCartridge(assetPath) ⇒ <code>boolean</code>
+Checks if the given asset is a cartrdige absolute path.
+A cartridge absolute path start with cartridge name or alias and separate with asset path a colon `:`
+
+**Kind**: instance method of [<code>CartridgeResolverPlugin</code>](#CartridgeResolverPlugin)
+**Returns**: <code>boolean</code> - True if the given asset path is a cartridge absolute path
+
+| Param | Type | Description |
+| --- | --- | --- |
+| assetPath | <code>string</code> | The asset path |
+
+**Example**
+```js
+base:checkout/address.js                            -> true
+app_storefront_base:orderHistory/orderHistory.js    -> true
+wishlists:components/miniCart.js                    -> true
+plugin_wishlists:product/wishlist.js                -> true
+
+not_registered_alias:product/details.js             -> false
+not_registered_cartridge:product/details.js         -> false
+```
+<a name="CartridgeResolverPlugin+isAliasRequest"></a>
+
+#### cartridgeResolverPlugin.isAliasRequest(assetPath) ⇒ <code>boolean</code>
+Checks if the given request asset using an aliased path
+
+**Kind**: instance method of [<code>CartridgeResolverPlugin</code>](#CartridgeResolverPlugin)
+**Returns**: <code>boolean</code> - True if the given asset path start with an aliased
+
+| Param | Type |
+| --- | --- |
+| assetPath | <code>string</code> |
+
+**Example**
+```js
+base/components/consentTracking         -> true
+base/components/footer                  -> true
+./components/miniCart                   -> false
+base/components/collapsibleItem         -> true
+base/components/search                  -> true
+base/components/clientSideValidation    -> true
+```
+<a name="CartridgeResolverPlugin+getRelativeAsset"></a>
+
+#### cartridgeResolverPlugin.getRelativeAsset(assetPath) ⇒ <code>string</code>
+Gets relative path for the given asset without extension follow pattern:
+ /cartridge/client/{locale}/js/{relativeAsset}.js
+
+**Kind**: instance method of [<code>CartridgeResolverPlugin</code>](#CartridgeResolverPlugin)
+**Returns**: <code>string</code> - The relative path to cartridge asset path without extension
+
+| Param | Type | Description |
+| --- | --- | --- |
+| assetPath | <code>string</code> | The asset path |
+
+**Example**
+```js
+app_storefront_base/cartridge/client/default/js/product/base.js             -> product/base
+app_storefront_base/cartridge/client/default/js/components/../cart/cart.js  -> cart/cart
+plugin_wishlists/cartridge/client/default/js/components/miniCart.js         -> components/miniCart
+plugin_wishlists/cartridge/client/default/js/product/wishlist.js            -> product/wishlist
+```
+<a name="CartridgeResolverPlugin+getCartridge"></a>
+
+#### cartridgeResolverPlugin.getCartridge(assetPath) ⇒ <code>string</code>
+Extract the cartridge name from the given asset path follow pattern:
+ /{cartridgeName}/cartridge/client/
+
+**Kind**: instance method of [<code>CartridgeResolverPlugin</code>](#CartridgeResolverPlugin)
+**Returns**: <code>string</code> - The extracted cartridge name, null if no cartridge found
+
+| Param | Type | Description |
+| --- | --- | --- |
+| assetPath | <code>string</code> | The absolute asset path |
+
+**Example**
+```js
+project_root/cartridges/app_storefront_base/cartridge/client/default/js/cart/cart.js                       -> app_storefront_base
+project_root/vendors/plugin_wishlists/cartridge/client/default/js/main.js                                  -> plugin_wishlists
+project_root/vendors/link_adyen/cartridges/int_adyen_SFRA/cartridge/client/default/js/checkout/billing.js  -> int_adyen_SFRA
+```
+<a name="CartridgeResolverPlugin+getLocale"></a>
+
+#### cartridgeResolverPlugin.getLocale(assetPath) ⇒ <code>string</code>
+Extract locale from the given asset path follow pattern:
+ /cartridge/client/{locale}/js/
+
+**Kind**: instance method of [<code>CartridgeResolverPlugin</code>](#CartridgeResolverPlugin)
+**Returns**: <code>string</code> - The extracted locale, null if no cartridge found
+
+| Param | Type | Description |
+| --- | --- | --- |
+| assetPath | <code>string</code> | The absolute asset path |
+
+**Example**
+```js
+app_storefront_base/cartridge/client/default/js/profile/profile.js      -> default
+app_storefront_base/cartridge/client/default/js/checkout/billing.js     -> default
+app_storefront_base/cartridge/client/fr_FR/js/account/addressBook.js    -> fr_FR
+```
+<a name="CartridgeResolverPlugin+resolveFromCartrdiges"></a>
+
+#### cartridgeResolverPlugin.resolveFromCartrdiges(relativeAsset, cartridges, locale) ⇒ <code>string</code> \| <code>null</code>
+Resolve the relative asset using the given cartridge names
+
+**Kind**: instance method of [<code>CartridgeResolverPlugin</code>](#CartridgeResolverPlugin)
+**Returns**: <code>string</code> \| <code>null</code> - The absolute path of solved asset. `null` will be returned if nothing found.
+
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| relativeAsset | <code>string</code> |  | The relative request asset without extension |
+| cartridges | <code>Array.&lt;string&gt;</code> |  | List of cartridge names will be lookup for the given request asset |
+| locale | <code>string</code> | <code>&quot;default&quot;</code> | Asset locale |
+

New alerts

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Uses eval

Supply chain risk

Package uses dynamic code execution (e.g., eval()), which is a dangerous practice. This can prevent the code from running in certain environments and increases the risk that the code may contain exploits or malicious behavior.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

44563

617.25%

Number of package files

19

533.33%

Lines of code

476

317.54%

Number of lines in readme file

286

793.75%

Worsened metrics

Dev dependency count

3

Infinity%

Number of low supply chain risk alerts

3

50%

Number of medium supply chain risk alerts

2

Infinity%

No dependency changes