filter

This parser helps you filter a SDTF graph.

Interface

interface parser {
  name: 'filter';
  options: {
    query: SDTFQuery;
    resolveAliases?: boolean;
    allowUnresolvableAliases?: boolean;
    deduplicate: true | undefined;
    failOnMutate: true | undefined;
  };
}

Options

Parameter	Required	Type	Default	Description
query	required	SDTFQuery		The query that select items in the graph.
resolveAliases	false	boolean	false	Whether to resolve the aliases of the graph. Thus, preventing aliases to become unresolvable when their source is not included in the selected items.
allowUnresolvableAliases	false	boolean	true	Whether to allow unresolvable aliases to flow through. This option is only available when resolveAliases = true
deduplicate	false	true | undefined	undefined	When you target tokens from different areas in your graph you can end up with tokens that will have the same name which will lead to an override. When set to true, this option will suffix tokens with a -{number} to prevent the override.
failOnMutate	false	true | undefined	undefined	By default, this parser mutates your graph. When set to true this option will make your pipeline return an error when your tokens respective path differ from their original one in the graph. Set this option to true if you want to be 100% aligned between design and code.

Basic usage: select all tokens from a group in a collection

Input

{
  "colors": {
    "$collection": {
      "$modes": ["light", "dark"]
    },
    "info": {
      "infoToken": {
        "$type": "color",
        "$value": {
          "light": {
            "model": "rgb",
            "red": 219,
            "green": 234,
            "blue": 254,
            "alpha": 1
          },
          "dark": {
            "model": "rgb",
            "red": 219,
            "green": 234,
            "blue": 254,
            "alpha": 1
          }
        }
      }
    },
    "danger": {
      "dangerToken": {
        "$type": "color",
        "$value": {
          "light": {
            "model": "rgb",
            "red": 209,
            "green": 204,
            "blue": 204,
            "alpha": 1
          },
          "dark": {
            "model": "rgb",
            "red": 19,
            "green": 34,
            "blue": 54,
            "alpha": 1
          }
        }
      }
    }
  }
}

Config

1. We want to get all tokens in all groups named "info"

2. We also want to get the parent collection...

3. ... and all children tokens within the "info" group(s)

4. We eventually generate our transformed SDTF graph in a JSON file thanks to the to-sdtf parser.

.specifyrc.json

{
  "version": "2",
  "repository": "@organization/repository",
  // Only use the personalAccessToken when working with the CLI
  "personalAccessToken": "<your-personal-access-token>",
  "rules": [
    {
      "name": "Only get tokens from a group named 'info' and gererate tokens in JSON",
      "parsers": [
        {
          "name": "filter",
          "options": {
            "query": {
              "where": {
                "group": "info",
                "select": {
                  "parents": true,
                  "children": true
                }
              }
            }
          }
        },
        {
          "name": "to-sdtf",
          "output": {
            "type": "file",
            "filePath": "tokens.json"
          }
        }
      ]
    }
  ]
}

Output

tokens.json

{
  "colors": {
    "$collection": {
      "$modes": ["light", "dark"]
    },
    "info": {
      "infoToken": {
        "$type": "color",
        "$value": {
          "light": {
            "model": "rgb",
            "red": 219,
            "green": 234,
            "blue": 254,
            "alpha": 1
          },
          "dark": {
            "model": "rgb",
            "red": 219,
            "green": 234,
            "blue": 254,
            "alpha": 1
          }
        }
      }
    }
  }
}