yuku-ast 0.1.2 → 0.1.4

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
@@ -112,7 +113,9 @@ is.CallExpression(node); // every concrete type
 is.Expression(node); // families
 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) {
@@ -123,6 +126,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/identifier.d.mts

@@ -19,10 +19,7 @@ declare function isIdentifierStart(cp: number): boolean;
 declare function isIdentifierChar(cp: number): boolean;
 /**
  * Returns `true` if `name` is a valid ECMAScript `IdentifierName`: the grammar
- * an identifier token must satisfy.
- *
- * Unlike the `is.IdentifierName` node guard, this validates a raw string rather
- * than an AST node.
+ * an identifier token must satisfy. Validates a raw string, not an AST node.
  *
  * @example
  * isIdentifierName("foo");     // true

package/dist/identifier.mjs

@@ -29,10 +29,7 @@ function isIdentifierChar(cp) {
 }
 /**
 * Returns `true` if `name` is a valid ECMAScript `IdentifierName`: the grammar
-* an identifier token must satisfy.
-*
-* Unlike the `is.IdentifierName` node guard, this validates a raw string rather
-* than an AST node.
+* an identifier token must satisfy. Validates a raw string, not an AST node.
 *
 * @example
 * isIdentifierName("foo");     // true

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, BooleanLiteral, ComputedMemberExpression, Directive, Identifier, 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"];
@@ -106,10 +108,6 @@ declare const is: {
   Pattern: (node: MaybeNode) => node is AliasMap["Pattern"];
   JSX: (node: MaybeNode) => node is AliasMap["JSX"];
   TSType: (node: MaybeNode) => node is AliasMap["TSType"];
-  IdentifierReference: (node: MaybeNode) => node is IdentifierReference;
-  BindingIdentifier: (node: MaybeNode) => node is BindingIdentifier;
-  LabelIdentifier: (node: MaybeNode) => node is LabelIdentifier;
-  IdentifierName: (node: MaybeNode) => node is IdentifierName;
   StringLiteral: (node: MaybeNode) => node is StringLiteral;
   NumericLiteral: (node: MaybeNode) => node is NumericLiteral;
   BooleanLiteral: (node: MaybeNode) => node is BooleanLiteral;
@@ -149,7 +147,6 @@ declare const is: {
   TSEnumDeclaration: (node: MaybeNode) => node is import("yuku-parser").TSEnumDeclaration;
   TSModuleDeclaration: (node: MaybeNode) => node is import("yuku-parser").TSModuleDeclaration;
   TSImportEqualsDeclaration: (node: MaybeNode) => node is import("yuku-parser").TSImportEqualsDeclaration;
-  Identifier: (node: MaybeNode) => node is import("yuku-parser").Identifier;
   Literal: (node: MaybeNode) => node is NodeOfType<"Literal">;
   ThisExpression: (node: MaybeNode) => node is import("yuku-parser").ThisExpression;
   Super: (node: MaybeNode) => node is import("yuku-parser").Super;
@@ -289,7 +286,7 @@ declare const is: {
 //#endregion
 //#region src/builders.d.ts
 declare const b: {
-  identifier(name: string, kind?: t.IdentifierKind, opts?: {
+  identifier(name: string, opts?: {
     typeAnnotation?: t.TSTypeAnnotation | null;
     optional?: boolean;
     decorators?: t.Decorator[];

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"),
@@ -559,10 +563,6 @@ const is = {
 	Pattern: aliasGuard("Pattern"),
 	JSX: aliasGuard("JSX"),
 	TSType: aliasGuard("TSType"),
-	IdentifierReference: (node) => node?.type === "Identifier" && node.kind === "reference",
-	BindingIdentifier: (node) => node?.type === "Identifier" && node.kind === "binding",
-	LabelIdentifier: (node) => node?.type === "Identifier" && node.kind === "label",
-	IdentifierName: (node) => node?.type === "Identifier" && node.kind === "name",
 	StringLiteral: (node) => node?.type === "Literal" && typeof node.value === "string",
 	NumericLiteral: (node) => node?.type === "Literal" && typeof node.value === "number",
 	BooleanLiteral: (node) => node?.type === "Literal" && typeof node.value === "boolean",
@@ -582,11 +582,10 @@ const span = {
 };
 const isComputedKey = (key) => key.type !== "Identifier" && key.type !== "PrivateIdentifier";
 const b = {
-	identifier(name, kind = "reference", opts = {}) {
+	identifier(name, opts = {}) {
 		return {
 			type: "Identifier",
 			name,
-			kind,
 			...opts,
 			...span
 		};
@@ -893,8 +892,8 @@ const b = {
 	metaProperty(meta, property) {
 		return {
 			type: "MetaProperty",
-			meta: b.identifier(meta, "name"),
-			property: b.identifier(property, "name"),
+			meta: b.identifier(meta),
+			property: b.identifier(property),
 			...span
 		};
 	},

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.2",
+  "version": "0.1.4",
   "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": {
@@ -48,9 +49,9 @@
     "tsdown": "^0.22.0",
     "typescript": "^6.0.3",
     "yuku-codegen": "^0.5.18",
-    "yuku-parser": "^0.5.18"
+    "yuku-parser": "^0.5.20"
   },
   "peerDependencies": {
-    "yuku-parser": ">=0.5.18"
+    "yuku-parser": ">=0.5.20"
   }
 }