NEXT-33861 - improve selector

.changeset/tough-geckos-drum.md

@@ -0,0 +1,5 @@
+---
+"@shopware-ag/meteor-admin-sdk": minor
+---
+
+- Changed from lodash get for selectors to own implementation which supports wildcards

packages/admin-sdk/docs/docs/guide/2_api-reference/data/get.md

@@ -17,6 +17,6 @@ data.get({
 ```
 
 #### Parameters
-| Name      | Required | Description                                                                                                |
-| :-------- | :------- | :--------------------------------------------------------------------------------------------------------- |
-| `options` | true     | Options containing the unique `id` and optional `selectors` for minimizing the payload and needed privileges |
+| Name      | Required | Description                                                                                                          |
+| :-------- | :------- |:---------------------------------------------------------------------------------------------------------------------|
+| `options` | true     | Containing the unique `id` and optional `selectors`. Read more about selectors [here](../../4_concepts/selectors.md) |

packages/admin-sdk/docs/docs/guide/2_api-reference/data/subscribe.md

@@ -16,7 +16,7 @@ data.subscribe(
 
 #### Parameters
 | Name        | Required | Description                                                                                           |
-| :---------- | :------- | :---------------------------------------------------------------------------------------------------- |
+| :---------- | :------- |:------------------------------------------------------------------------------------------------------|
 | `id`        | true     | The unique id of the dataset you want to receive                                                      |
 | `callback`  | true     | A callback function which will be called every time the Shopware Administration publishes the dataset |
-| `selectors` | false    | Selectors for reducing the payload and minimizing the needed privileges                               |
+| `selectors` | false    | Read more about selectors [here](../../4_concepts/selectors.md)                                       |

packages/admin-sdk/docs/docs/guide/4_concepts/selectors.md

@@ -0,0 +1,69 @@
+# Selectors
+
+Selectors are a powerful tool to reduce the payload and minimize the needed privileges.
+They are used in `data.subscribe` and `data.get`. Selectors are an array of strings. Each string represents a path to a property in the dataset.
+
+### Example:
+
+Imagine this payload:
+```json
+{
+    "name": "My Product",
+    "manufacturer": {
+        "name": "My Manufacturer"
+    },
+    "price": 100,
+    "variants": [
+        {
+            "name": "First Variant",
+            "price": 110
+        },
+        // contains more variants
+    ],
+    // contains more properties
+}
+```
+
+If you are only interested in the names of the product and manufacturer, you can use the following selectors:
+```javascript
+data.get({
+    id: 'sw-product-detail__product',
+    selectors: ['name', 'manufacturer.name'],
+}).then((product) => {
+    console.log(product); // prints { name: "My Product", manufacturer: { name: "My Manufacturer" } }
+});
+```
+
+### Combining selectors
+
+Again for the above payload, if you are interested in multiple properties of the manufacturer, you can use the following selectors:
+```javascript
+data.get({
+    id: 'sw-product-detail__product',
+    selectors: ['manufacturer.id', 'manufacturer.name'],
+}).then((product) => {
+    console.log(product); // prints { manufacturer: { id: '065e71ab94d778a980008e8c3e890270', name: "My Manufacturer" }
+});
+```
+
+### Arrays
+
+If you are interested in a specific variant, you can use the following selectors:
+```javascript
+data.get({
+    id: 'sw-product-detail__product',
+    selectors: ['variants.[0].name'],
+}).then((product) => {
+    console.log(product); // prints { variants: [ { name: "First Variant" } ] }
+});
+```
+
+If you are interested in all variants, you can use wildcards. A wildcard is the asterix symbol (`*`)
+```javascript
+data.get({
+    id: 'sw-product-detail__product',
+    selectors: ['variants.*.name'],
+}).then((product) => {
+    console.log(product); // prints { variants: [ { name: "First Variant" }, // same structure for all entries ] }
+});
+```