Merge strategy API for useDefaults

[patzick]

References:

• [BUG] apiDefaults definition loses data in defaults #1341 - original issue
• current docs: https://shopware-pwa-docs.vuestorefront.io/landing/resources/api/composables.usedefaults.html#usedefaults-variable

Description

We need a setting for merge strategy when adding/overwriting API defaults in shopware-pwa.config.js file.

1. Ability to just add new fields to defaults
2. Ability to redefine all fields for a specific field, allowing to reduce the number of fields

Requirements:

1. API for that setting should be additional and non-breaking (unless the discussion would show it's worth it)

Proposition

cocreated with @SimonMarx

Global setting

Example:

module.exports = {
  apiDefaults: {
    _mergeStrategy: "extend" // Alowed: extend | replace.  Default: replace
    useCms: {
     limit: 8,
     includes: {
       product: ["manufacturer"]
     },
  }
}

props:

• simple API, easy to understand and straightforward
• not breaking additional API

cons:

• you cannot have different strategies for different keys
• config file is a bit more complicated than now

Per key setting

/// API TBD

pros:

• bigger flexibility for extending defaults

cons:

• probably a much more complicated settings structure

---

What do you think? Let's discuss it :)

[niklaswolf]

I think the overwhelming majority will use the extend-mode. In my opinion, this should also be the default, although it would potentially break some current projects. But there would be a very clear migration path, so this shouldn't be that much of an issue.

I think because the defaultParams should be as minimal as possible anyways, most of the folks just want to add some fields on top.

[patzick]

I agree with that. As I think it wouldn't even be BC that much, but a potential performance issue.
if we have ['manufacturer', 'id', 'media'] as defaults and would use extend strategy with ['id', 'media', 'otherField'] as a result there would be ['manufacturer', 'id', 'media', 'otherField'] so only manufacturer is potentially unnecessary in here but it would not break the app.

Either way keeping defaults as small as possible (and extend them in the theme later on the road) would not affect the users that much.

[SimonMarx]

First of all, how @niklaswolf already mentioned most of us only want to add fields on top.
When the defaultsParams already includes only necessary includes/associations/fields you should not be able to replace / remove them with your Project configuration, because this will break (in worst case) your application.

To reach a minimal apiDefaults config, themes must be able to provide apiDefaults (themes are the ones, who have requirements to the api, collect data and send data). But how we already discuss in Discord, this is another topic.

tl;dr
Per-Key configurations are cool, but in in most cases not needed.

The case where you may want to remove apiDefaults

Maybe this are thoughts of me, which are not necessary at all, but could make a config file highly configurable while merging different layers of config files (project - theme - shopware-pwa - storefront)

Lets take the CrossSelling Component as example.
When i remove this component by overwriting Theme components, i do not need the crossSelling association in my "useCms" defaults anymore, so how do i remove this association to prevent unnecessary payload in the request/reponse?

Case 1: Global Settings _mergeStrategy using replace

// apiDefaults
{
  "useCms": {
    "limit": 10,
    "associations": {
      // many more associations
      "crossSellings": {
        "associations": {
          "assignedProducts": {
            "associations": {
              "product": {
                "associations": {
                  "media": {},
                  "cover": {},
                  "seoUrls": {}
                }
              }
            }
          }
        }
      },
    },
    "includes": {
      "media": ["thumbnails", "width", "height", "url"],
    }
  }
}

// projectDefaults
{
  "useCms": {
    "limit": 8,
    "includes": {
      "media": ["name"],
    }
  }
}

Will maybe result in:

{
  "useCms": {
    "limit": 8,  // maybe or not, see below 
    "includes": {
      "media": ["name"],
    }
  }
}

Questions for the global option:

• On which layer the "replace" begins? (On the object "useCms" itself, or only for defined keys in that object like "includes / associtations / limit")
• Are keys ignored which are present in the apiDefault but not are present in the project settings while replacing?
• How do i remove keys with the replace option, when Question 2 is answered with "yes"

Case 2: Per Key options

Per key options are more complex in the config structure to write, but makes it possible to configure your theme/project defaults specific for your needs and let developers create configuration files where other developers directly understand what is going on while merging multiple default definitions (once they understood the configuration structure).

An example could be:

// Api Defaults  (e.g. by theme or shopware-pwa)

const apiDefaults = {
    useCms: {
        limit: 10,
        associations: {
            crossSellings: {
                associations: {
                    assignedProducts: {
                        associations: {
                            product: {
                                associations: {
                                    media: {},
                                    cover: {},
                                    seoUrls: {}
                                }
                            }
                        }
                    }
                }
            },

            manufacturer: {
                associations: {
                    media: {}
                }
            },
        },

        includes: {
            media: ["thumbnails", "width", "height", "url"]
        }
    }
}



// Your project configs
module.exports = {
    // other configs

    defaultMergeStrategy: 'extend',  // Allowed:  extend | replace     Default: extend  (Yes its breaking, but makes per-key configuration much more easier and less writing effort)

    // Example 1    - prevent nesting of keys, instead using dot notation for key/field access
    mergeStrategies: {
        apiDefaults: {
            useCms: {
                associations: [
                    // exclude single keys
                    {
                        field: 'crossSelling.associations.assignedProducts.product.associations.media',
                        strategy: 'remove' // Allowed:      remove | extend | replace
                    },
                    {
                        field: 'manufacturer.association',
                        strategy: 'replace'
                    }
                ],

                includes: [
                    {field: 'media', strategy: 'extend'}
                ]
            }
        }
    },

    // Example 2    - same as Example 1, but with nested keys instead dot notation
    mergeStrategies: {
        apiDefaults: {
            associations: {
                crossSellings: {
                    associations: {
                        assignedProducts: {
                            associations: {
                                product: {
                                    associations: {
                                        media: 'remove',
                                    }
                                }
                            }
                        }
                    }
                },
                manufacturer: {
                    associations: 'replace'
                }
            },
        }
    },


    
    // projects api defaults
    apiDefaults: {
        useCms: {
            associations: {
                manufacturer: {
                    associations: {
                        someAssociation: {}   
                    }
                }
            },
            includes: {
                media: ["cdn"]
            }
        }
    }
}



// result

const finalApiDefaults = {
    useCms: {
        limit: 10,
        associations: {
            crossSellings: {
                associations: {
                    assignedProducts: {
                        associations: {
                            product: {
                                associations: {
                                    // removed the "media: {}" associations
                                    cover: {},
                                    seoUrls: {}
                                }
                            }
                        }
                    }
                }
            },

            manufacturer: {
                associations: {
                    someAssociation: {}     // replaced the whole object, removed "media: {}" and placed "someAssociation: {}" in it.
                }
            },
        },

        includes: {
            media: ["thumbnails", "width", "height", "url", "cdn"]  // extend "cdn" to the media include
        }
    }
}

Another advantage of per-key configuration is, that updates of theme / shopware-pwa are a lot easier to make compatible with your project, in case a theme e.g. adds a new associations / includes in their apiDefaults within the update.

[patzick]

Hey folks, I've come with another proposition to solve our case, I believe it's pretty clean and straightforward :)

Api defaults builder

You could be able to use it in nuxt config sile, shopware-pwa config file or move logic to dedicated file.

The base:

import defaultsConfigBuilder from "@shopware-pwa/nuxt-module/api-defaults"
// or in CJS
const defaultsConfigBuilder =
  require("@shopware-pwa/nuxt-module/api-defaults").default

console.info('defaultsConfigBuilder', defaultsConfigBuilder().get()); // will print default config

Now we could have many abilities to edit the config, I'll leave the API with examples

Adding new value

// merge object (including arrays), in this case add one value to array
defaultsConfigBuilder().add("useCms.includes.cms_page_slot",  "someCustomValue")

// result for defaultsConfigBuilder().get()["useCms"]["includes"]["cms_page_slot"]
[ 
  'id',
  'type',
  'slot',
  'blockId',
  'config',
  'data',
  'backgroundMediaMode',
  'backgroundMedia',
  'someCustomValue',
]

Removing value

// merge object (including arrays), in this case add one value to array
defaultsConfigBuilder().remove("useCms.includes.cms_page_slot",  "type")

// result for defaultsConfigBuilder().get()["useCms"]["includes"]["cms_page_slot"]
[ 
  'id',
  'slot',
  'blockId',
  'config',
  'data',
  'backgroundMediaMode',
  'backgroundMedia',
]

Replacing value

defaultsConfigBuilder().replace("useCms.includes.cms_page_slot",  ["id", "myValue"])
// another examples
defaultsConfigBuilder().replace("useCms", { limit: 3 }) // replace whole useCms setting
defaultsConfigBuilder().replace("useCms.limit", 5)

Implementation details for some cases

• add would replace value if it's not an object or array, for example with limit property
• you could chain methods like defaultsConfigBuilder().add(...).remove(...).add(...)

Let me know what do you think!
cc @SimonMarx @niklaswolf

[niklaswolf]

This looks really clean and in my view also more understandable how to extend the default api-Params, as you'd have a clean API that speaks for itself to work with.

I maybe would opt for another name for the get-method, because what my first instinct was, especially when looking at add() and replace(), is that it would take a parameter and get only that part of the config, so e.g. .get("useCms").
My questions:

• would this also allow for changes during runtime? If yes, is that intended? I don't know why anyone would want to change the defaults during runtime, but yeah...
• will this replace the current apiDefaults key in shopware-pwa.config.js, or is it used like this:

{
    ...
    apiDefaults: defaultsConfigBuilder().get(),
    ...
}

[patzick]

because get() is exactly what your instinct told you - you can get whole config or just part of it by path .get("useCms"), it's used here to show the outcome, probably you wouldn't use it (only for debugging why the config is different than you wanted)

As for runtime - no, this is purely for the build time. If you want to change the params during runtime you can call API client passing the params you need. You can also add your own composable with different default params.

This would replace the current shopware-pwa.config.js key apiDefaults - if we'd detect it, then we can print deprecation info with link to docs about how to extend defaults.