目录

依赖选择器语法和查询

依赖选择器语法和查询

选择命令行版本：

目录

描述

¥Description

npm query 命令公开了一种新的依赖选择器语法（由 & 尊重 CSS 选择器 4 规范 的许多方面提供信息），它：

¥The npm query commmand exposes a new dependency selector syntax (informed by & respecting many aspects of the CSS Selectors 4 Spec) which:

  • 使用健壮的对象模型、元数据和选择器语法标准化依赖图的形状和查询

    ¥Standardizes the shape of, & querying of, dependency graphs with a robust object model, metadata & selector syntax

  • 利用 CSS 中现有的已知语言语法和运算符来广泛访问不同的包信息

    ¥Leverages existing, known language syntax & operators from CSS to make disparate package information broadly accessible

  • 解锁回答有关依赖、它们的关系和关联元数据的复杂、多方面问题的能力

    ¥Unlocks the ability to answer complex, multi-faceted questions about dependencies, their relationships & associative metadata

  • 合并 npm 中类似查询命令的冗余逻辑（例如 npm fund、npm ls、npm outdated、npm audit ...）

    ¥Consolidates redundant logic of similar query commands in npm (ex. npm fund, npm ls, npm outdated, npm audit ...)

依赖选择器语法 v1.0.0

¥Dependency Selector Syntax v1.0.0

概述

¥Overview:

  • 没有 "type" 或 "tag" 选择器（例如 div, h1, a），因为依赖/目标是唯一可以查询的 Node 类型

    ¥there is no "type" or "tag" selectors (ex. div, h1, a) as a dependency/target is the only type of Node that can be queried

  • "dependencies" 一词是指在 Arborist 返回的 tree 中找到的任何 Node

    ¥the term "dependencies" is in reference to any Node found in a tree returned by Arborist

组合器

¥Combinators

  • > 直系后代/子代

    ¥> direct descendant/child

  • 任何后代/子级

    ¥ any descendant/child

  • ~ 兄弟姐妹

    ¥~ sibling

选择器

¥Selectors

  • * 万能选择器

    ¥* universal selector

  • #<name> 依赖选择器（相当于 [name="..."]）

    ¥#<name> dependency selector (equivalent to [name="..."])

  • #<name>@<version>（相当于 [name=<name>]:semver(<version>)）

    ¥#<name>@<version> (equivalent to [name=<name>]:semver(<version>))

  • , 选择器列表分隔符

    ¥, selector list delimiter

  • . 依赖类型选择器

    ¥. dependency type selector

  • : 伪选择器

    ¥: pseudo selector

依赖类型选择器

¥Dependency Type Selectors

  • 在 package.json 的 dependencies 部分中找到的 .prod 依赖，或者是所述依赖的子项

    ¥.prod dependency found in the dependencies section of package.json, or is a child of said dependency

  • 在 package.json 的 devDependencies 部分中找到的 .dev 依赖，或者是所述依赖的子项

    ¥.dev dependency found in the devDependencies section of package.json, or is a child of said dependency

  • 在 package.json 的 optionalDependencies 部分中找到 .optional 依赖，或者在 package.json 的 peerDependenciesMeta 部分的条目中设置了 "optional": true，或者所述依赖的子项

    ¥.optional dependency found in the optionalDependencies section of package.json, or has "optional": true set in its entry in the peerDependenciesMeta section of package.json, or a child of said dependency

  • 在 package.json 的 peerDependencies 部分中找到 .peer 依赖

    ¥.peer dependency found in the peerDependencies section of package.json

  • 在 package.json 的 workspaces 部分中找到 .workspace 依赖

    ¥.workspace dependency found in the workspaces section of package.json

  • 在 package.json 的 bundleDependencies 部分中找到的 .bundled 依赖，或者是所述依赖的子项

    ¥.bundled dependency found in the bundleDependencies section of package.json, or is a child of said dependency

伪选择器

¥Pseudo Selectors

  • :not(<selector>)

  • :has(<selector>)

  • :is(<selector list>)

  • :root 匹配根 node/依赖

    ¥:root matches the root node/dependency

  • :scope 匹配它被查询的 node/依赖

    ¥:scope matches node/dependency it was queried against

  • :empty 当一个依赖没有依赖时

    ¥:empty when a dependency has no dependencies

  • :private 当一个依赖是私有的

    ¥:private when a dependency is private

  • :link 当依赖被链接时（例如，工作区或手动包 linked

    ¥:link when a dependency is linked (for instance, workspaces or packages manually linked

  • :deduped 当依赖已被数据去重时（注意这并不总是意味着依赖已被提升到 node_modules 的根目录）

    ¥:deduped when a dependency has been deduped (note that this does not always mean the dependency has been hoisted to the root of node_modules)

  • :overridden 当依赖被覆盖时

    ¥:overridden when a dependency has been overridden

  • :extraneous 存在依赖但未定义为任何 node 的依赖时

    ¥:extraneous when a dependency exists but is not defined as a dependency of any node

  • :invalid 当依赖版本超出其祖级指定范围时

    ¥:invalid when a dependency version is out of its ancestors specified range

  • :missing 当在磁盘上找不到依赖时

    ¥:missing when a dependency is not found on disk

  • :semver(<spec>) 匹配有效的 node-semver 规范

    ¥:semver(<spec>) matching a valid node-semver spec

  • :path(<path>) glob 匹配基于相对于项目的依赖路径

    ¥:path(<path>) glob matching based on dependencies path relative to the project

  • :type(<type>) 基于当前识别的类型

    ¥:type(<type>) based on currently recognized types

属性选择器

¥Attribute Selectors

属性选择器评估 package.json 中的键/值对（如果它们是 String）。

¥The attribute selector evaluates the key/value pairs in package.json if they are Strings.

  • [] 属性选择器（即属性的存在）

    ¥[] attribute selector (ie. existence of attribute)

  • [attribute=value] 属性值是等价的...

    ¥[attribute=value] attribute value is equivalant...

  • [attribute~=value] 属性值包含单词...

    ¥[attribute~=value] attribute value contains word...

  • [attribute*=value] 属性值包含字符串...

    ¥[attribute*=value] attribute value contains string...

  • [attribute|=value] 属性值等于或以...开头

    ¥[attribute|=value] attribute value is equal to or starts with...

  • [attribute^=value] 属性值以...开头

    ¥[attribute^=value] attribute value starts with...

  • [attribute$=value] 属性值以...结尾

    ¥[attribute$=value] attribute value ends with...

Array & Object 属性选择器

¥Array & Object Attribute Selectors

通用的 :attr() 伪选择器标准化了一个模式，该模式可用于通过 Arborist 的 Node.package 元数据访问 Object 的 Object、Array 或 Arrays 的属性选择。这允许在顶层 String 评估之外进行迭代属性选择。传递给 :attr() 的最后一个参数必须是 attribute 选择器或嵌套的 :attr()。请参阅以下示例：

¥The generic :attr() pseudo selector standardizes a pattern which can be used for attribute selection of Objects, Arrays or Arrays of Objects accessible via Arborist's Node.package metadata. This allows for iterative attribute selection beyond top-level String evaluation. The last argument passed to :attr() must be an attribute selector or a nested :attr(). See examples below:

Objects

/* return dependencies that have a `scripts.test` containing `"tap"` */
*: attr(scripts, [test~=tap]);

嵌套 Objects

¥Nested Objects

嵌套对象表示为 :attr() 的顺序参数。

¥Nested objects are expressed as sequential arguments to :attr().

/* return dependencies that have a testling config for opera browsers */
*: attr(testling, browsers, [~=opera]);

Arrays

Array 专门使用特殊/保留的 . 字符代替典型的属性名称。将 String 传递给选择器时，Arrays 还支持精确的 value 匹配。

¥Arrays specifically uses a special/reserved . character in place of a typical attribute name. Arrays also support exact value matching when a String is passed to the selector.

Array 属性选择示例：

¥Example of an Array Attribute Selection:

/* removes the distinction between properties & arrays */
/* ie. we'd have to check the property & iterate to match selection */
*:attr([keywords^=react])
*:attr(contributors, :attr([name~=Jordan]))
直接匹配值的 Array 示例：

¥Example of an Array matching directly to a value:

/* return dependencies that have the exact keyword "react" */
/* this is equivalent to `*:keywords([value="react"])` */
*: attr([keywords=react]);
Object 中的 Array 示例：

¥Example of an Array of Objects:

/* returns */
*: attr(contributors, [email=ruyadorno @github.com]);

组

¥Groups

依赖组由与其祖级的包关系定义（即 package.json 中定义的依赖类型）。这种方法以用户为中心，因为生态系统已被教导首先考虑这些组中的依赖。依赖允许包含在多个组中（例如，prod 依赖也可能是 dev 依赖（因为另一个 dev 依赖也需要它）&也可能是 bundled - 该类型依赖的选择器如下所示：*.prod.dev.bundled).

¥Dependency groups are defined by the package relationships to their ancestors (ie. the dependency types that are defined in package.json). This approach is user-centric as the ecosystem has been taught to think about dependencies in these groups first-and-foremost. Dependencies are allowed to be included in multiple groups (ex. a prod dependency may also be a dev dependency (in that it's also required by another dev dependency) & may also be bundled - a selector for that type of dependency would look like: *.prod.dev.bundled).

  • .prod

  • .dev

  • .optional

  • .peer

  • .bundled

  • .workspace

请注意，当前 workspace 依赖始终是 prod 依赖。此外，.root 依赖也被认为是 prod 依赖。

¥Please note that currently workspace deps are always prod dependencies. Additionally the .root dependency is also considered a prod dependency.

程序化用法

¥Programmatic Usage

  • Arborist 的 Node 类有一个 .querySelectorAll() 方法

    ¥Arborist's Node Class has a .querySelectorAll() method

    • 此方法将根据有效的查询选择器返回过滤的、扁平的依赖 Arborist Node 列表

      ¥this method will return a filtered, flattened dependency Arborist Node list based on a valid query selector

const Arborist = require("@npmcli/arborist");
const arb = new Arborist({});
// root-level
arb.loadActual().then(async (tree) => {
  // query all production dependencies
  const results = await tree.querySelectorAll(".prod");
  console.log(results);
});
// iterative
arb.loadActual().then(async (tree) => {
  // query for the deduped version of react
  const results = await tree.querySelectorAll("#react:not(:deduped)");
  // query the deduped react for git deps
  const deps = await results[0].querySelectorAll(":type(git)");
  console.log(deps);
});

也可以看看

¥See Also

npm 中文网 - 粤ICP备13048890号