yuku-ast 0.1.1 → 0.1.3

package/README.md

@@ -6,6 +6,7 @@ node builders, type guards, a walker, and identifier validators. No runtime depe
 | Import                | Provides                                                     |
 | --------------------- | ------------------------------------------------------------ |
 | `yuku-ast`            | `walk`, `walkAsync`, `b` (node builders), `is` (type guards) |
+| `yuku-ast/utils`      | node utilities such as `nameOf`                              |
 | `yuku-ast/identifier` | identifier and reserved-word validators                      |
 
 ```ts
@@ -114,6 +115,9 @@ is.StringLiteral(node); // Literal variants
 is.StaticMemberExpression(node); // MemberExpression variants
 is.BindingIdentifier(node); // Identifier roles, via `kind`
 
+is.Identifier(node, "this"); // an Identifier with that exact name
+is.oneOf(node, ["CallExpression", "NewExpression"]); // any of these types
+
 walk(program, {
   Literal(node, path) {
     if (is.ArrayExpression(path.parent)) {
@@ -123,6 +127,32 @@ walk(program, {
 });
 ```
 
+`is.oneOf(node, types)` narrows to the union of the listed types, and
+`is.Identifier(node, name?)` narrows to `Identifier`. Both accept `null` or
+`undefined`.
+
+## Reading names (`nameOf`)
+
+`nameOf(node)` returns the static name a node denotes, an `Identifier`'s `name`
+or a string `Literal`'s `value`, and `null` for anything else (including `null`
+or `undefined`). It reads the common `Identifier | StringLiteral` slots, such as
+a `ModuleExportName` or a static property or member key, in one call.
+
+```ts
+import { walk } from "yuku-ast";
+import { nameOf } from "yuku-ast/utils";
+
+walk(program, {
+  ExportSpecifier(node) {
+    // `export { x as y }` and `export { x as "z" }` both resolve.
+    nameOf(node.exported); // "y", "z"
+  },
+  Property(node) {
+    if (!node.computed) nameOf(node.key); // static key name, else null
+  },
+});
+```
+
 ## Builders (`b`)
 
 A builder for every node type. Required fields are positional, the rest go in a

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 import * as t from "yuku-parser";
-import { BigIntLiteral, BindingIdentifier, BooleanLiteral, ComputedMemberExpression, Directive, IdentifierName, IdentifierReference, LabelIdentifier, Node, NullLiteral, NumericLiteral, PrivateFieldExpression, RegExpLiteral, StaticMemberExpression, StringLiteral } from "yuku-parser";
+import { BigIntLiteral, BindingIdentifier, BooleanLiteral, ComputedMemberExpression, Directive, Identifier, IdentifierName, IdentifierReference, LabelIdentifier, Node, NullLiteral, NumericLiteral, PrivateFieldExpression, RegExpLiteral, StaticMemberExpression, StringLiteral } from "yuku-parser";
 
 //#region src/types.d.ts
 /** Discriminant `type` string of every AST node. */
@@ -95,6 +95,8 @@ type AliasMap = { [K in AliasName]: NodeOfType<(typeof ALIAS_GROUPS)[K][number]>
 //#region src/predicates.d.ts
 type MaybeNode = Node | null | undefined;
 declare const is: {
+  /** True when `node`'s `type` is one of `types`, narrowing to that union. */oneOf: <const K extends NodeType>(node: MaybeNode, types: readonly K[]) => node is NodeOfType<K>; /** An `Identifier`, optionally with the exact `name` (e.g. `is.Identifier(node, "this")`). */
+  Identifier: (node: MaybeNode, name?: string) => node is Identifier;
   Expression: (node: MaybeNode) => node is NodeOfType<"Identifier" | "Literal" | "ThisExpression" | "Super" | "ArrayExpression" | "ObjectExpression" | "FunctionExpression" | "ArrowFunctionExpression" | "ClassExpression" | "TaggedTemplateExpression" | "TemplateLiteral" | "MemberExpression" | "CallExpression" | "NewExpression" | "ChainExpression" | "SequenceExpression" | "ParenthesizedExpression" | "BinaryExpression" | "LogicalExpression" | "ConditionalExpression" | "UnaryExpression" | "UpdateExpression" | "AssignmentExpression" | "YieldExpression" | "AwaitExpression" | "ImportExpression" | "MetaProperty" | "TSAsExpression" | "TSSatisfiesExpression" | "TSTypeAssertion" | "TSNonNullExpression" | "TSInstantiationExpression" | "JSXElement" | "JSXFragment">;
   Statement: (node: MaybeNode) => node is AliasMap["Statement"];
   Declaration: (node: MaybeNode) => node is AliasMap["Declaration"];
@@ -122,7 +124,6 @@ declare const is: {
   Directive: (node: MaybeNode) => node is Directive;
   TSTypeAnnotation: (node: MaybeNode) => node is import("yuku-parser").TSTypeAnnotation;
   Decorator: (node: MaybeNode) => node is import("yuku-parser").Decorator;
-  Identifier: (node: MaybeNode) => node is import("yuku-parser").Identifier;
   PrivateIdentifier: (node: MaybeNode) => node is import("yuku-parser").PrivateIdentifier;
   Literal: (node: MaybeNode) => node is NodeOfType<"Literal">;
   TemplateElement: (node: MaybeNode) => node is import("yuku-parser").TemplateElement;

package/dist/index.mjs

@@ -548,6 +548,10 @@ function aliasGuard(name) {
 }
 const is = {
 	...Object.fromEntries(Object.keys(VISITOR_KEYS).map((type) => [type, (node) => node != null && node.type === type])),
+	/** True when `node`'s `type` is one of `types`, narrowing to that union. */
+	oneOf: (node, types) => node != null && types.includes(node.type),
+	/** An `Identifier`, optionally with the exact `name` (e.g. `is.Identifier(node, "this")`). */
+	Identifier: (node, name) => node?.type === "Identifier" && (name === void 0 || node.name === name),
 	Expression: aliasGuard("Expression"),
 	Statement: aliasGuard("Statement"),
 	Declaration: aliasGuard("Declaration"),

package/dist/utils.d.mts

@@ -0,0 +1,18 @@
+import { Node } from "yuku-parser";
+
+//#region src/utils/index.d.ts
+type MaybeNode = Node | null | undefined;
+/**
+ * The static name a node denotes: an `Identifier`'s `name`, or a string
+ * `Literal`'s `value`. Returns `null` for anything else, and for `null` or
+ * `undefined`, so the common `Identifier | StringLiteral` name slots (a
+ * `ModuleExportName`, or a static property or member key) read in one call.
+ *
+ * @example
+ * nameOf(b.identifier("x")) // "x"
+ * nameOf(b.stringLiteral("y")) // "y"
+ * nameOf(b.numericLiteral(1)) // null
+ */
+declare function nameOf(node: MaybeNode): string | null;
+//#endregion
+export { nameOf };

package/dist/utils.mjs

@@ -0,0 +1,20 @@
+//#region src/utils/index.ts
+/**
+* The static name a node denotes: an `Identifier`'s `name`, or a string
+* `Literal`'s `value`. Returns `null` for anything else, and for `null` or
+* `undefined`, so the common `Identifier | StringLiteral` name slots (a
+* `ModuleExportName`, or a static property or member key) read in one call.
+*
+* @example
+* nameOf(b.identifier("x")) // "x"
+* nameOf(b.stringLiteral("y")) // "y"
+* nameOf(b.numericLiteral(1)) // null
+*/
+function nameOf(node) {
+	if (node == null) return null;
+	if (node.type === "Identifier") return node.name;
+	if (node.type === "Literal" && typeof node.value === "string") return node.value;
+	return null;
+}
+//#endregion
+export { nameOf };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yuku-ast",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "A fast, typed AST toolkit for yuku-parser's ESTree / TypeScript-ESTree AST: node builders, type guards, a walker, and identifier validators.",
   "keywords": [
     "ast",
@@ -30,6 +30,7 @@
   "exports": {
     ".": "./dist/index.mjs",
     "./identifier": "./dist/identifier.mjs",
+    "./utils": "./dist/utils.mjs",
     "./package.json": "./package.json"
   },
   "scripts": {