@alloy-js/core 0.23.0-dev.8 → 0.23.0

package/src/library-symbol-reference.ts

@@ -1,10 +1,62 @@
 import { RefkeyableObject } from "./refkey.js";
 import { OutputSymbol } from "./symbols/output-symbol.js";
 
+/**
+ * Well-known symbol for the lazy-symbol-creation protocol used by external
+ * library descriptors. Objects implementing `[TO_SYMBOL]()` are recognized as
+ * {@link LibrarySymbolReference} values that can be passed anywhere a refkey
+ * is accepted.
+ *
+ * @remarks
+ *
+ * Implement `[TO_SYMBOL]()` on a descriptor object to register it as a
+ * referenceable library symbol. Inside the method:
+ *
+ * 1. Call {@link useBinder} to get the current binder context.
+ * 2. Look up (or create) the symbol for that binder in a
+ *    `WeakMap<object, OutputSymbol>` (use a sentinel object for the
+ *    no-binder case, since `WeakMap` keys must be objects).
+ * 3. On first creation, construct the symbol and register it into the
+ *    appropriate space for your library, passing `{ binder }`
+ *    (see {@link OutputSymbolOptions.binder}).
+ *
+ * The method is called by language package code each time the descriptor is
+ * used as a reference (e.g. inside `ref()`). It is NOT called by the binder
+ * itself.
+ *
+ * @example
+ *
+ * ```ts
+ * const defaultKey = {};
+ * const symbols = new WeakMap<object, MySymbol>();
+ * const descriptor: LibrarySymbolReference = {
+ *   [REFKEYABLE]() {
+ *     return descriptor[TO_SYMBOL]().refkeys[0];
+ *   },
+ *   [TO_SYMBOL]() {
+ *     const binder = useBinder();
+ *     const key = binder ?? defaultKey;
+ *     let sym = symbols.get(key);
+ *     if (!sym) {
+ *       sym = new MySymbol("SomeType", space, { binder });
+ *       symbols.set(key, sym);
+ *     }
+ *     return sym;
+ *   },
+ * };
+ * ```
+ */
 export const TO_SYMBOL: unique symbol = Symbol(
   "Alloy.RefkeyableObject.TO_SYMBOL",
 );
 
+/**
+ * An object that acts as a lazy reference to an external library symbol.
+ * Implements {@link REFKEYABLE} and `[TO_SYMBOL]()`.
+ *
+ * Use {@link isLibrarySymbolReference} to test whether an unknown value is a
+ * library symbol reference.
+ */
 export interface LibrarySymbolReference extends RefkeyableObject {
   [TO_SYMBOL](): OutputSymbol;
 }

package/src/name-policy.ts

@@ -1,20 +1,47 @@
+/**
+ * A function that transforms a name according to a naming policy for a
+ * specific element kind. Obtained from {@link NamePolicy.for}.
+ */
 export interface NamePolicyGetter {
   (originalName: string): string;
 }
 export interface NamePolicy<TElements extends string> {
   /**
-   * Apply the language policy to the provided name for the provided element
-   * type.
+   * Apply the language policy to the provided name for the provided element type.
+   * When `element` is `undefined`, returns `originalName` unchanged.
    */
   getName(originalName: string, element: TElements | undefined): string;
   /**
    * Get a function that takes a name and applies the naming policy to it.
+   * When `element` is `undefined`, returns an identity function.
    */
   for(element: TElements | undefined): NamePolicyGetter;
 }
 
+/**
+ * Creates a name policy that transforms symbol names based on element kind.
+ *
+ * @example
+ * ```ts
+ * const policy = createNamePolicy((name, element) => {
+ *   if (element === "value") return toCamelCase(name);
+ *   if (element === "type")  return toPascalCase(name);
+ *   return name;
+ * });
+ * <Output namePolicy={policy}>...</Output>
+ * ```
+ *
+ * @remarks
+ * `element` identifies the kind of declaration (e.g., `"value"`, `"type"`).
+ * The set of valid element strings is defined by the language package.
+ *
+ * When `element` is `undefined` (outside a declaration context), {@link NamePolicy.getName}
+ * and {@link NamePolicy.for} short-circuit and return the original name unchanged — the
+ * namer callback is **not** invoked. The namer therefore always receives a defined `T`.
+ * This means names outside a declaration context cannot be transformed by the policy.
+ */
 export function createNamePolicy<T extends string>(
-  namer: (name: string, elements: T) => string,
+  namer: (name: string, element: T) => string,
 ): NamePolicy<T> {
   const forCache = new Map<string, NamePolicyGetter>();
   const noopGetter = (name: string) => name;

package/src/reactive-union-set.ts

@@ -1,14 +1,13 @@
 import {
   ITERATE_KEY,
   ReactiveFlags,
-  shallowReactive,
   shallowReadonly,
   track,
   TrackOpTypes,
   trigger,
   TriggerOpTypes,
 } from "@vue/reactivity";
-import { effect, untrack } from "./reactivity.js";
+import { effect, root, shallowReactive, untrack } from "./reactivity.js";
 
 export interface ReactiveUnionSetOptions<T> {
   onAdd?: OnReactiveSetAddCallback<T>;
@@ -129,6 +128,7 @@ export class ReactiveUnionSet<T> extends Set<T> {
      * that were added to the parent set.
      */
     const prevValues = new Map<T, T>();
+    const itemDisposers = new Map<T, () => void>();
 
     effect(
       () => {
@@ -137,13 +137,24 @@ export class ReactiveUnionSet<T> extends Set<T> {
             untrack(() => onDelete?.(prevSourceValue));
             prevValues.delete(prevSourceValue);
             this.delete(prevTargetValue);
+            const disposer = itemDisposers.get(prevSourceValue);
+            if (disposer) {
+              disposer();
+              itemDisposers.delete(prevSourceValue);
+            }
           }
         }
 
         for (const value of subset) {
           if (!prevValues.has(value)) {
             if (onAdd) {
-              const added = untrack(() => onAdd(value));
+              const added = untrack(() =>
+                root((disposer) => {
+                  const result = onAdd(value);
+                  itemDisposers.set(value, disposer);
+                  return result;
+                }),
+              );
               prevValues.set(value, added);
             } else {
               this.add(value);