Declare helper functions for TypeScript (#327)

This lets you write code like:

```tsx
const hi = namekey("hi");
<ts.SourceFile path="test1.ts">
  {code`
    const ${decl(hi)} = 12;
    console.log(${hi});
  `}
</ts.SourceFile>
```

Author: bterlson

.chronus/changes/declare-helper-2025-9-27-1-50-14.md

@@ -0,0 +1,7 @@
+---
+changeKind: fix
+packages:
+  - "@alloy-js/core"
+---
+
+Fix a bug where tracing would track additional signals.

.chronus/changes/declare-helper-2025-9-27-1-51-37.md

@@ -0,0 +1,7 @@
+---
+changeKind: feature
+packages:
+  - "@alloy-js/typescript"
+---
+
+Introduce `decl`, `declType`, and `declMember` functions to declare a symbol given a namekey and return the new symbol name. Allows avoiding the use of declaration components if desired.

packages/core/src/tracer.ts

@@ -198,7 +198,7 @@ export function trace(
         fg: { r: 50, g: 50, b: 50 },
       }) +
       " " +
-      cb() +
+      untrack(cb) +
       "\n",
   );
 }

packages/typescript/src/symbols/index.ts

@@ -1,4 +1,10 @@
-import { Namekey, OutputScopeOptions } from "@alloy-js/core";
+import {
+  createComponent,
+  Namekey,
+  onCleanup,
+  OutputScopeOptions,
+  toRef,
+} from "@alloy-js/core";
 import { useLexicalScope, useMemberOwner } from "../utils.js";
 import { useTSScope } from "./scopes.js";
 import { TSLexicalScope } from "./ts-lexical-scope.js";
@@ -24,7 +30,7 @@ export function createTypeAndValueSymbol(
 
 export function createTypeSymbol(
   name: string | Namekey,
-  options: CreateTsSymbolOptions,
+  options: CreateTsSymbolOptions = {},
 ) {
   const scope = useLexicalScope();
   if (scope && !scope.types) {
@@ -125,3 +131,46 @@ export function createMemberScope(
   const parent = useTSScope();
   return new TSMemberScope(name, parent, ownerSymbol, options);
 }
+
+export function decl(namekey: Namekey, options?: CreateTsSymbolOptions) {
+  return createComponent(() => {
+    const symbol = createValueSymbol(namekey, options);
+
+    onCleanup(() => {
+      symbol.delete();
+    });
+
+    return toRef(symbol, "name");
+  }, {});
+}
+
+export function declType(namekey: Namekey, options?: CreateTsSymbolOptions) {
+  return createComponent(() => {
+    const symbol = createTypeSymbol(namekey, options);
+
+    onCleanup(() => {
+      symbol.delete();
+    });
+
+    return toRef(symbol, "name");
+  }, {});
+}
+
+export function declMember(
+  namekey: Namekey,
+  locationOptions: { jsPrivate?: boolean; static?: boolean } = {},
+  options?: CreateTsSymbolOptions,
+) {
+  // Create the symbol inside a component so that we only get these side
+  // effects when this function is rendered (and not from something like
+  // children()/childrenArray() invoking the memo) and we get cleanup logic.
+  return createComponent(() => {
+    const symbol = createMemberSymbol(namekey, locationOptions, options);
+
+    onCleanup(() => {
+      symbol.delete();
+    });
+
+    return toRef(symbol, "name");
+  }, {});
+}

packages/typescript/test/decl-helpers.test.tsx

@@ -0,0 +1,129 @@
+import { code, namekey, Output } from "@alloy-js/core";
+import "@alloy-js/core/testing";
+import { d } from "@alloy-js/core/testing";
+import { expect, it } from "vitest";
+import * as ts from "../src/index.js";
+import { decl, declMember, declType } from "../src/symbols/index.js";
+
+it("declares variables", () => {
+  const hi = namekey("hi");
+
+  expect(
+    <Output>
+      <ts.SourceFile path="test1.ts">
+        {code`
+          const ${decl(hi)} = 12;
+          console.log(${hi});
+        `}
+      </ts.SourceFile>
+      <ts.SourceFile path="test2.ts">{hi};</ts.SourceFile>
+    </Output>,
+  ).toRenderTo({
+    "test1.ts": d`
+      const hi = 12;
+      console.log(hi);
+    `,
+    "test2.ts": d`
+      import { hi } from "./test1.js";
+
+      hi;
+    `,
+  });
+});
+
+it("declares types", () => {
+  const hi = namekey("hi");
+
+  expect(
+    <Output>
+      <ts.SourceFile path="test1.ts">
+        {code`
+          interface ${declType(hi)} {
+            value: number;
+          }
+        `}
+      </ts.SourceFile>
+      <ts.SourceFile path="test2.ts">
+        <ts.VarDeclaration name="test" type={hi} />
+      </ts.SourceFile>
+    </Output>,
+  ).toRenderTo({
+    "test1.ts": d`
+      interface hi {
+        value: number;
+      }
+    `,
+    "test2.ts": d`
+      import type { hi } from "./test1.js";
+
+      const test: hi
+    `,
+  });
+});
+
+it("declares variables", () => {
+  const hi = namekey("hi");
+
+  expect(
+    <Output>
+      <ts.SourceFile path="test1.ts">
+        {code`
+          interface ${declType(hi)} {
+            value: number;
+          }
+        `}
+      </ts.SourceFile>
+      <ts.SourceFile path="test2.ts">
+        <ts.VarDeclaration name="test" type={hi} />
+      </ts.SourceFile>
+    </Output>,
+  ).toRenderTo({
+    "test1.ts": d`
+      interface hi {
+        value: number;
+      }
+    `,
+    "test2.ts": d`
+      import type { hi } from "./test1.js";
+
+      const test: hi
+    `,
+  });
+});
+
+it("declares members", () => {
+  const publicMember = namekey("publicMember");
+  const privateMember = namekey("privateMember");
+  const staticMethod = namekey("staticMethod");
+  expect(
+    <Output>
+      <ts.SourceFile path="test1.ts">
+        <ts.ClassDeclaration name="Foo">
+          {code`
+            public ${declMember(publicMember)} = 12;
+            #${declMember(privateMember, { jsPrivate: true })} = 34;
+            constructor() {
+              ${publicMember} = 24;
+              ${privateMember} = 10;
+            }
+          `}
+          <hbr />
+          static ${declMember(staticMethod, { static: true })}() {"{}"};
+        </ts.ClassDeclaration>
+        <hbr />
+        {staticMethod}();
+      </ts.SourceFile>
+    </Output>,
+  ).toRenderTo(d`
+    class Foo {
+      public publicMember = 12;
+      #privateMember = 34;
+      constructor() {
+        this.publicMember = 24;
+        this.#privateMember = 10;
+      }
+      static $staticMethod() {};
+    }
+    Foo.staticMethod();
+  `);
+});