@alloy-js/core 0.21.0-dev.3 → 0.21.0-dev.8

package/src/binder.ts

@@ -3,7 +3,14 @@ import { useBinder } from "./context/binder.js";
 import { useMemberContext } from "./context/member-scope.js";
 import { useScope } from "./context/scope.js";
 import { effect } from "./reactivity.js";
-import { isMemberRefkey, refkey, Refkey } from "./refkey.js";
+import {
+  isMemberRefkey,
+  MemberRefkey,
+  refkey,
+  Refkey,
+  Refkeyable,
+  toRefkey,
+} from "./refkey.js";
 import { OutputScope } from "./symbols/output-scope.js";
 import { type OutputSymbol } from "./symbols/output-symbol.js";
 import {
@@ -49,7 +56,7 @@ export interface Binder {
    * ref is undefined if the symbol has not been created yet.
    */
   getSymbolForRefkey<TSymbol extends OutputSymbol>(
-    refkey: Refkey,
+    refkey: Refkeyable,
   ): Ref<TSymbol | undefined>;
 
   /**
@@ -392,8 +399,10 @@ export function createOutputBinder(options: BinderOptions = {}): Binder {
   }
 
   function getSymbolForRefkey<TSymbol extends OutputSymbol = OutputSymbol>(
-    refkey: Refkey,
+    refkeyable: Refkeyable,
   ) {
+    const refkey = toRefkey(refkeyable);
+
     if (waitingDeclarations.has(refkey)) {
       return waitingDeclarations.get(refkey)! as ShallowRef<TSymbol>;
     }
@@ -404,7 +413,9 @@ export function createOutputBinder(options: BinderOptions = {}): Binder {
       const baseSymbolRef: ShallowRef<TSymbol | undefined> =
         getSymbolForRefkey<TSymbol>(refkey.base);
       const memberSymbolRef: ShallowRef<TSymbol | undefined> =
-        getSymbolForRefkey<TSymbol>(refkey.member);
+        getMemberSymbolFromMemberRefkey(refkey) as ShallowRef<
+          TSymbol | undefined
+        >;
 
       symbolRef = computed(() => {
         // even though we don't necessarily need the base symbol to be available
@@ -558,7 +569,7 @@ export function createOutputBinder(options: BinderOptions = {}): Binder {
       return [
         ...getMemberPathFromRefkey(refkey.base),
         {
-          symbol: getSymbolForRefkey(refkey.member).value!,
+          symbol: getMemberSymbolFromMemberRefkey(refkey).value!,
           isMemberAccess: true,
         },
       ];
@@ -572,6 +583,23 @@ export function createOutputBinder(options: BinderOptions = {}): Binder {
     ];
   }
 
+  function getMemberSymbolFromMemberRefkey(
+    refkey: MemberRefkey,
+  ): Ref<OutputSymbol | undefined> {
+    if (typeof refkey.member === "string") {
+      return computed(() => {
+        const baseSymbol = getSymbolForRefkey(refkey.base).value;
+        if (!baseSymbol) {
+          return undefined;
+        }
+
+        return baseSymbol.resolveMemberByName(refkey.member as string);
+      });
+    } else {
+      return getSymbolForRefkey(refkey.member);
+    }
+  }
+
   function resolveMember(
     base: OutputSymbol,
     member: OutputSymbol,
@@ -692,7 +720,7 @@ export function resolve<
  * not found. The symbol you're looking for may not have been declared yet. When the symbol
  * is declared, the ref will be updated with the symbol.
  */
-export function symbolForRefkey(refkey: Refkey) {
+export function symbolForRefkey(refkey: Refkeyable) {
   const binder = useBinder();
   if (!binder) {
     throw new Error("Can't resolve refkey without a binder");

package/src/index.ts

@@ -27,6 +27,7 @@ export * from "./code.js";
 export * from "./components/index.js";
 export * from "./context.js";
 export * from "./context/index.js";
+export * from "./library-symbol-reference.js";
 export * from "./name-policy.js";
 export * from "./props-combinators.js";
 export * from "./reactive-union-set.js";

package/src/library-symbol-reference.ts

@@ -0,0 +1,20 @@
+import { RefkeyableObject } from "./refkey.js";
+import { OutputSymbol } from "./symbols/output-symbol.js";
+
+export const TO_SYMBOL: unique symbol = Symbol(
+  "Alloy.RefkeyableObject.TO_SYMBOL",
+);
+
+export interface LibrarySymbolReference extends RefkeyableObject {
+  [TO_SYMBOL](): OutputSymbol;
+}
+
+export function isLibrarySymbolReference(
+  value: unknown,
+): value is LibrarySymbolReference {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    Object.hasOwn(value, TO_SYMBOL)
+  );
+}

package/src/refkey.ts

@@ -14,15 +14,20 @@ function getObjectKey(value: WeakKey): string {
   return key;
 }
 
-const RefkeySym: unique symbol = Symbol();
+export const REFKEYABLE: unique symbol = Symbol("Alloy.REFKEYABLE");
 
-export type RefkeyBase = {
-  [RefkeySym]: true;
+export type RefkeyableObject = {
+  [REFKEYABLE](): Refkey;
 };
 
+export function toRefkey(refkey: Refkeyable) {
+  return refkey[REFKEYABLE]();
+}
+
+export type Refkeyable = RefkeyableObject | Refkey;
 export type Refkey = SymbolRefkey | MemberRefkey | Namekey;
 
-export interface SymbolRefkey extends RefkeyBase {
+export interface SymbolRefkey extends RefkeyableObject {
   key: string;
 }
 
@@ -37,15 +42,17 @@ export interface Namekey<TOptions extends NamekeyOptions = NamekeyOptions>
   options: TOptions;
 }
 
-export interface MemberRefkey extends RefkeyBase {
+export interface MemberRefkey extends RefkeyableObject {
   base: Refkey;
-  member: Refkey;
+  member: Refkey | string;
 }
 
 function createSymbolRefkey(key: string): SymbolRefkey {
   const refkey: SymbolRefkey = {
     key,
-    [RefkeySym]: true,
+    [REFKEYABLE]() {
+      return this;
+    },
   };
 
   markRaw(refkey);
@@ -53,11 +60,16 @@ function createSymbolRefkey(key: string): SymbolRefkey {
   return refkey;
 }
 
-export function isRefkey(value: unknown): value is Refkey {
+export function isRefkeyable(value: unknown): value is RefkeyableObject {
   return (
     typeof value === "object" &&
     value !== null &&
-    Object.hasOwn(value, RefkeySym)
+    Object.hasOwn(value, REFKEYABLE)
+  );
+}
+export function isRefkey(value: unknown): value is Refkey {
+  return (
+    isRefkeyable(value) && (value as RefkeyableObject)[REFKEYABLE]() === value
   );
 }
 
@@ -66,11 +78,7 @@ export function isSymbolRefkey(value: unknown): value is SymbolRefkey {
 }
 
 export function isMemberRefkey(value: unknown): value is MemberRefkey {
-  return (
-    isRefkey(value) &&
-    Object.hasOwn(value, "base") &&
-    Object.hasOwn(value, "member")
-  );
+  return isRefkey(value) && Object.hasOwn(value, "base");
 }
 
 export function isNamekey(value: unknown): value is Namekey {
@@ -82,9 +90,14 @@ export function isNamekey(value: unknown): value is Namekey {
  * return the key of that refkey, objects get a unique key for that specific object,
  * and otherwise the key is based on the value.
  */
-function getKey(value: unknown): SymbolRefkey["key"] {
-  if (isSymbolRefkey(value)) {
-    return value.key;
+function getKey(value: unknown): string {
+  if (isRefkeyable(value)) {
+    const refkey = toRefkey(value);
+    if (isSymbolRefkey(refkey)) {
+      return refkey.key;
+    } else {
+      return getObjectKey(value);
+    }
   } else if (typeof value === "object" && value !== null) {
     return getObjectKey(value);
   } else {
@@ -142,7 +155,9 @@ export function namekey(name: string, options: NamekeyOptions = {}): Namekey {
     key: getObjectKey({}),
     name,
     options,
-    [RefkeySym]: true,
+    [REFKEYABLE]() {
+      return this;
+    },
   };
 }
 /**
@@ -168,8 +183,8 @@ export function namekey(name: string, options: NamekeyOptions = {}): Namekey {
  * `refkey(rk1, rk3)`.
  */
 export function memberRefkey(
-  base: Refkey,
-  ...members: [Refkey, ...Refkey[]]
+  base: Refkeyable,
+  ...members: [Refkeyable | string, ...(Refkeyable | string)[]]
 ): MemberRefkey {
   if (members.length < 1) {
     throw new Error("memberRefkey needs at least one member");
@@ -177,27 +192,40 @@ export function memberRefkey(
 
   if (members.length === 1) {
     return {
-      base,
-      member: members[0],
-      [RefkeySym]: true,
+      base: toRefkey(base),
+      member:
+        typeof members[0] === "string" ? members[0] : toRefkey(members[0]),
+      [REFKEYABLE]() {
+        return this;
+      },
     };
   }
 
+  const lastMember = members.at(-1)!;
+
   return {
     base: memberRefkey(
       base,
-      ...(members.slice(0, -1) as [Refkey, ...Refkey[]]),
+      ...(members.slice(0, -1) as [Refkeyable, ...Refkeyable[]]),
     ),
-    member: members.at(-1)!,
-    [RefkeySym]: true,
+    member: typeof lastMember === "string" ? lastMember : toRefkey(lastMember),
+    [REFKEYABLE]() {
+      return this;
+    },
   };
 }
 
 export function inspectRefkey(refkey: Refkey): string {
+  const unwrapped = refkey[REFKEYABLE]();
+
   const text =
-    isMemberRefkey(refkey) ?
-      `memberRefkey[${inspectRefkey(refkey.base)} -> ${inspectRefkey(refkey.member)}]`
-    : `refkey[${refkey.key}]`;
+    isMemberRefkey(unwrapped) ?
+      `memberRefkey[${inspectRefkey(unwrapped.base)} -> ${
+        typeof unwrapped.member === "string" ?
+          unwrapped.member
+        : inspectRefkey(unwrapped.member)
+      }]`
+    : `refkey[${unwrapped.key}]`;
 
   return text;
 }

package/src/render.ts

@@ -14,7 +14,7 @@ import {
   root,
   untrack,
 } from "./reactivity.js";
-import { isRefkey } from "./refkey.js";
+import { isRefkeyable, toRefkey } from "./refkey.js";
 import {
   Child,
   Children,
@@ -541,14 +541,15 @@ function normalizeChild(child: Child): NormalizedChildren {
     return "";
   } else if (isRef(child)) {
     return () => child.value as () => Child;
-  } else if (isRefkey(child)) {
+  } else if (isRefkeyable(child)) {
+    const refkey = toRefkey(child);
     return () => {
       const sfContext = useContext(SourceFileContext);
       if (!sfContext || !sfContext.reference) {
         throw new Error("Can only emit references inside of source files");
       }
 
-      return sfContext.reference({ refkey: child });
+      return sfContext.reference({ refkey });
     };
   } else if (isRenderableObject(child)) {
     // For custom renderable objects, we will just normalize them to a bound function.

package/src/runtime/component.ts

@@ -1,6 +1,6 @@
 import { Ref } from "@vue/reactivity";
 import { CustomContext } from "../reactivity.js";
-import { Refkey } from "../refkey.js";
+import { Refkey, RefkeyableObject } from "../refkey.js";
 import { IntrinsicElement } from "./intrinsic.js";
 
 export const RENDERABLE = Symbol.for("Alloy.CustomElement");
@@ -35,6 +35,7 @@ export function isRenderableObject(item: unknown): item is RenderableObject {
 
 export type Child =
   | RenderableObject
+  | RefkeyableObject
   | string
   | boolean
   | number

package/src/symbols/output-symbol.ts

@@ -94,6 +94,11 @@ export interface OutputSymbolOptions {
    * also ignoring name conflict resolution.
    */
   ignoreNameConflict?: boolean;
+
+  /**
+   * Provide a function which lazy-initializes members when an enumeration of members are needed.
+   */
+  lazyMemberInitializer?: () => void;
 }
 
 let symbolCount = 0;
@@ -459,6 +464,40 @@ export abstract class OutputSymbol {
     return this.#namePolicy;
   }
 
+  #lazyMemberInitializer: (() => void) | undefined;
+  #lazyMembersInitialized: boolean = false;
+
+  #initializeMembers() {
+    if (this.#lazyMemberInitializer && !this.#lazyMembersInitialized) {
+      this.#lazyMemberInitializer();
+    }
+    this.#lazyMembersInitialized = true;
+  }
+
+  /**
+   * Get a member symbol by name from this symbol's member spaces. Checks member
+   * spaces in order until it finds a member with that name.
+   */
+  resolveMemberByName(name: string): OutputSymbol | undefined {
+    this.#initializeMembers();
+
+    if (this.isTyped) {
+      if (!this.hasTypeSymbol) {
+        return undefined;
+      }
+
+      return this.type!.resolveMemberByName(name);
+    }
+    for (const space of this.memberSpaces) {
+      const member = space.symbolNames.get(name);
+      if (member) {
+        return member;
+      }
+    }
+
+    return undefined;
+  }
+
   // Tell \@vue/reactivity that this symbol should never be wrapped in a reactive
   // proxy.
   [ReactiveFlags.SKIP] = true;
@@ -502,6 +541,7 @@ export abstract class OutputSymbol {
     this.#isTransient = !!options.transient;
     this.#isTyped = !!options.type;
     this.type = options.type;
+    this.#lazyMemberInitializer = options.lazyMemberInitializer;
 
     this.#handleNewSpaces(this.#spaces);
     const constructor = this.constructor as typeof OutputSymbol;