Legacy Elements Selector Syntax

These formats keep working without changes, but when a policy uses them the plugin emits a one-time runtime console warning encouraging migration to object-based selectors. When you are ready to migrate, the v6 to v7 migration guide covers the full transition, including the entity selector form.

String and tuple selectors

String and tuple selectors were the original way to match elements. They still work, but they can only match an element type and its captured values. The modern object-based selectors — and especially the entity selector form — can also match a file's categories, a module's origin, and more.

String selector format

Format: <string>

A micromatch pattern matched against the element type.

// Matches all helpers
"helper"

// Matches helpers and components
"helper|component"

// Matches any element type ending in "-component"
"*-component"

Modern equivalent:

// Entity selector (canonical form)
{ element: { type: "helper" } }

// Match multiple types with an array of selectors
[{ element: { type: "helper" } }, { element: { type: "component" } }]

// Pattern matching on the type
{ element: { type: "*-component" } }

Tuple selector format

Format: [<string>, <capturedValuesObject>]

The first entry is a micromatch pattern matched against the element type. The second entry is an object of captured values to match.

Matches when both the element type matches and all the listed captured values match.

// Match helpers captured in the "data" family
["helper", { family: "data" }]

// Match helpers in the "data" OR "permissions" family
["helper", { family: "data|permissions" }]

// Match helpers whose elementName starts with "parse"
["helper", { elementName: "parse*" }]

Modern equivalent:

// Single captured property
{ element: { type: "helper", captured: { family: "data" } } }

// Micromatch pattern in a captured value
{ element: { type: "helper", captured: { family: "data|permissions" } } }

// Multiple captured conditions
{ element: { type: "helper", captured: { elementName: "parse*" } } }

Array of strings

// Matches helper OR component
["helper", "component"]

Modern equivalent:

// OR within the type pattern
{ element: { type: ["helper", "component"] } }

// OR across selectors
[
  { element: { type: "helper" } },
  { element: { type: "component" } }
]

Mixed array of strings and tuples

// Match data helpers OR all components
[
  ["helper", { family: "data" }],
  "component"
]

Modern equivalent:

[
  { element: { type: "helper", captured: { family: "data" } } },
  { element: { type: "component" } }
]

Element selector properties

The following element selector properties still work but are kept only for backward compatibility. They will be removed in a future major version.

Category

The category property on element descriptors is deprecated, so the category property on element selectors is also deprecated. The replacement is a file descriptor category matched through the file sub-selector. File descriptors let you assign multiple categories to different files within the same element.

Deprecated	Replacement
{ element: { category: "test" } }	{ file: { categories: "test" } }

Origin

Module origin describes where an imported module comes from, so it now lives on the module sub-selector. The legacy form keeps working.

Deprecated	Replacement
{ element: { origin: "external" } }	{ module: { origin: "external" } }

internalPath

The internalPath property on an element selector is deprecated. Use the module sub-selector internalPath to match the path within an external or core module, or fileInternalPath to match the path within a local element.

Deprecated	Replacement
{ element: { internalPath: "index.js" } }	{ file: { fileInternalPath: "index.js" } }
{ element: { internalPath: "index.js" } }	{ module: { internalPath: "index.js" } }

filePath

The filePath property on an element selector is deprecated. Use the module sub-selector internalPath to match the path within an external or core module, or fileInternalPath to match the file internal path within a local element relative to the element root.

Deprecated	Replacement
{ element: { filePath: "index.js" } }	{ file: { fileInternalPath: "index.js" } }
{ element: { filePath: "index.js" } }	{ module: { internalPath: "index.js" } }

Using element selectors as entity selectors

From v7, the element selector is a sub-selector of the entity selector syntax. But, for backward compatibility, the element selector can still be used as a top-level selector. The following two selectors are equivalent in places where an entity selector is expected, such as the from and to properties of a policy. The first form is deprecated and will be removed in a future major version.

// Top-level element selector (deprecated)
{ type: "helper" }

// Entity selector (canonical form)
{ element: { type: "helper" } }

Why migrate?

The object-based and entity selector syntax gives you:

• Self-documenting selectors — Object properties read clearly, especially in long policy lists.
• Entity matching — Wrap element properties in { element: { ... } } to also match file.categories (file descriptors) and module.origin/module.source (external and local module origin). These are only reachable through entity selectors.
• Richer element matching — Object selectors support element.type, element.path, element.fileInternalPath, element.captured, element.parent, and the isIgnored/isUnknown flags.
• Future features — New capabilities are added to the object-based syntax only.

Migration guide

For step-by-step migration instructions and examples, see the v6 to v7 migration guide. If you are migrating from an earlier version, the v5 to v6 migration guide covers the original move from string and tuple selectors to object selectors.

See Also

• Selectors — modern object-based and entity selector reference.
• Policies — where selectors are used in from/to/dependency.
• Settings — configure boundaries/files and boundaries/elements-single-type.
• Elements — element descriptors and captured values.
• v6 to v7 Migration Guide — full migration instructions.