@alloy-js/core 0.20.0-dev.3 → 0.20.0-dev.6

package/src/components/Declaration.tsx

@@ -1,9 +1,12 @@
 import { useContext } from "../context.js";
 import { BinderContext } from "../context/binder.js";
 import { DeclarationContext } from "../context/declaration.js";
+import { useScope } from "../context/scope.js";
 import { onCleanup } from "../reactivity.js";
-import { Refkey } from "../refkey.js";
+import { Namekey, Refkey } from "../refkey.js";
 import type { Children } from "../runtime/component.js";
+import { BasicScope } from "../symbols/basic-scope.js";
+import { BasicSymbol } from "../symbols/basic-symbol.js";
 import { OutputSymbol } from "../symbols/output-symbol.js";
 
 /**
@@ -27,7 +30,7 @@ export interface DeclarationPropsWithInfo {
   /**
    * The name of this declaration.
    */
-  name: string;
+  name: string | Namekey;
 
   /**
    * The unique key or array of unique keys for this declaration.
@@ -73,7 +76,14 @@ export function Declaration(props: DeclarationProps) {
   if ("symbol" in props) {
     declaration = props.symbol;
   } else {
-    declaration = new OutputSymbol(props.name, {
+    const scope = useScope();
+    if (!(scope instanceof BasicScope)) {
+      throw new Error(
+        "Declaration component cannot create a symbol in a non-basic scope",
+      );
+    }
+
+    declaration = new BasicSymbol(props.name, scope.symbols, {
       binder,
       refkeys: [props.refkey ?? []].flat(),
       metadata: props.metadata,

package/src/components/MemberDeclaration.tsx

@@ -1,9 +1,10 @@
 import { useContext } from "../context.js";
 import { BinderContext } from "../context/binder.js";
 import { MemberDeclarationContext } from "../context/member-declaration.js";
-import type { Refkey } from "../refkey.js";
+import { useMemberContext } from "../context/member-scope.js";
+import type { Namekey, Refkey } from "../refkey.js";
 import type { Children } from "../runtime/component.js";
-import { OutputSymbolFlags } from "../symbols/flags.js";
+import { BasicSymbol } from "../symbols/basic-symbol.js";
 import { OutputSymbol } from "../symbols/output-symbol.js";
 
 /**
@@ -14,7 +15,7 @@ export interface MemberDeclarationPropsWithInfo {
   /**
    * The name of this declaration.
    */
-  name: string;
+  name: string | Namekey;
 
   /**
    * The refkey or array refkeys for this declaration.
@@ -87,13 +88,19 @@ export function MemberDeclaration(props: MemberDeclarationProps) {
       );
     }
 
-    declaration = new OutputSymbol(infoProps.name!, {
+    const scopeContext = useMemberContext()!;
+    if (!(scopeContext.ownerSymbol instanceof BasicSymbol)) {
+      throw new Error(
+        "MemberDeclaration component cannot create a symbol in a non-basic scope",
+      );
+    }
+    const space =
+      infoProps.static ?
+        scopeContext.ownerSymbol.staticMembers
+      : scopeContext.ownerSymbol.instanceMembers;
+    declaration = new BasicSymbol(infoProps.name, space, {
       refkeys: infoProps.refkey,
       metadata: infoProps.metadata,
-      flags:
-        infoProps.static ?
-          OutputSymbolFlags.StaticMember
-        : OutputSymbolFlags.InstanceMember,
     });
   }
 

package/src/components/MemberScope.tsx

@@ -1,41 +1,82 @@
-import { MemberScopeContext } from "../context/member-scope.js";
+import { MemberContext } from "../context/member-scope.js";
+
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+import { ScopeContext } from "../context/scope.js";
 import type { Children } from "../runtime/component.js";
+import { OutputScope } from "../symbols/output-scope.js";
 import type { OutputSymbol } from "../symbols/output-symbol.js";
-export interface MemberScopeProps {
+import { Scope } from "./Scope.jsx";
+
+/**
+ * Declare a member scope by providing an already created scope. The scope is
+ * exposed via {@link ScopeContext}.
+ */
+export interface MemberScopePropsWithValue {
+  /**
+   * The scope to use. If not provided, a new scope will be created.
+   */
+  value: OutputScope;
+
+  children?: Children;
+}
+
+/**
+ * Create a member scope by providing a name and optional metadata.
+ */
+export interface MemberScopePropsWithInfo {
   /**
-   * The name of the member scope.
+   * The name of this scope.
    */
   name?: string;
 
   /**
-   * The symbol that owns these members. This symbol must have either
-   * {@link OutputSymbolFlags.InstanceMemberContainer} or
-   * {@link OutputSymbolFlags.StaticMemberContainer}.
+   * The symbol whose members provide the symbols for this scope.
+   */
+  ownerSymbol: OutputSymbol;
+
+  /**
+   * Additional metadata for the scope.
    */
-  owner: OutputSymbol;
+  metadata?: Record<string, unknown>;
+
   children?: Children;
 }
 
+export type MemberScopeProps =
+  | MemberScopePropsWithValue
+  | MemberScopePropsWithInfo;
+
 /**
- * Declare a member scope, which is a scope that holds instance and static
- * members. This scope is then used for nested instance or static member
- * declarations and resolution of instance members.
+ * Declare a member scope, which is a lexical scope whose symbols are provided
+ * by the owner symbol.
  *
  * @remarks
  *
- * The member scope contains scopes for both instance and static members.
- * However, it does not affect the resolution of static members.
- *
- * @see {@link (MemberScopeContext:variable)}
+ * This is used to create members of a symbol, e.g. for class members and the
+ * like. In some languages, this scope may provide symbols which are can be
+ * referenced lexically, but in other languages, these members may not be in
+ * scope and instead must be referenced via the owner symbol itself.
  */
 export function MemberScope(props: MemberScopeProps) {
-  const context: MemberScopeContext = {
-    instanceMembers: props.owner.instanceMemberScope,
-    staticMembers: props.owner.staticMemberScope,
+  if ("value" in props) {
+    const sym = props.value;
+    if (!sym.isMemberScope) {
+      throw new Error(
+        "MemberScope must be passed a value that is a member scope.",
+      );
+    }
+  }
+
+  const context: MemberContext = {
+    ownerSymbol:
+      "value" in props ? props.value.ownerSymbol! : props.ownerSymbol!,
   };
+
   return (
-    <MemberScopeContext.Provider value={context}>
-      {props.children}
-    </MemberScopeContext.Provider>
+    <Scope {...props}>
+      <MemberContext.Provider value={context}>
+        {props.children}
+      </MemberContext.Provider>
+    </Scope>
   );
 }

package/src/components/Output.tsx

@@ -9,7 +9,6 @@ import { NamePolicy } from "../name-policy.js";
 import { getContext } from "../reactivity.js";
 import { PrintTreeOptions } from "../render.js";
 import type { Children } from "../runtime/component.js";
-import { extensionEffects } from "../slot.js";
 import { SourceDirectory } from "./SourceDirectory.js";
 
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
@@ -71,9 +70,6 @@ export function Output(props: OutputProps) {
 
   return (
     <BinderContext.Provider value={binder}>
-      {() => {
-        extensionEffects.forEach((e) => e());
-      }}
       {props.namePolicy ?
         <NamePolicyContext.Provider value={props.namePolicy}>
           {dir}

package/src/components/Scope.tsx

@@ -1,6 +1,8 @@
-import { ScopeContext } from "../context/scope.js";
+import { ScopeContext, useScope } from "../context/scope.js";
 import type { Children } from "../runtime/component.js";
+import { BasicScope } from "../symbols/basic-scope.js";
 import { OutputScope } from "../symbols/output-scope.js";
+import { OutputSymbol } from "../symbols/output-symbol.js";
 
 /**
  * Declare a scope by providing an already created scope. The scope is merely
@@ -19,12 +21,6 @@ export interface ScopePropsWithValue {
  * Create a scope by providing a name and optional metadata.
  */
 export interface ScopePropsWithInfo {
-  /**
-   * The kind of scope. This may be used by application code to determine how
-   * to handle symbols in this scope. It is not used by the core framework.
-   */
-  kind?: string;
-
   /**
    * The name of this scope.
    */
@@ -35,6 +31,11 @@ export interface ScopePropsWithInfo {
    */
   metadata?: Record<string, unknown>;
 
+  /**
+   * Create a member scope with the owner symbol providing the in-scope symbols.
+   */
+  ownerSymbol?: OutputSymbol;
+
   children?: Children;
 }
 
@@ -51,9 +52,15 @@ export function Scope(props: ScopeProps) {
   if ("value" in props) {
     scope = props.value;
   } else {
-    scope = new OutputScope(props.name ?? "", {
-      kind: props.kind,
+    const parentScope = useScope();
+    if (parentScope && !(parentScope instanceof BasicScope)) {
+      throw new Error(
+        "Scope component can only make scopes within a BasicScope",
+      );
+    }
+    scope = new BasicScope(props.name ?? "", parentScope, {
       metadata: props.metadata,
+      ownerSymbol: props.ownerSymbol,
     });
   }
 

package/src/context/member-scope.ts

@@ -3,19 +3,19 @@ import {
   createNamedContext,
   useContext,
 } from "../context.js";
-import type { OutputScope } from "../symbols/output-scope.js";
+import { OutputSymbol } from "../symbols/output-symbol.js";
 
 /**
- * The member scope context provides the instance and static member scopes that
- * are used for member declarations and instance member resolution.
+ * The member context provides the symbol upon which new member symbols
+ * should be created.
  */
-export interface MemberScopeContext {
-  staticMembers?: OutputScope;
-  instanceMembers?: OutputScope;
+export interface MemberContext {
+  ownerSymbol: OutputSymbol;
 }
-export const MemberScopeContext: ComponentContext<MemberScopeContext> =
-  createNamedContext("MemberScope");
 
-export function useMemberScope() {
-  return useContext(MemberScopeContext)!;
+export const MemberContext: ComponentContext<MemberContext> =
+  createNamedContext("MemberContext");
+
+export function useMemberContext() {
+  return useContext(MemberContext);
 }

package/src/context/name-policy.ts

@@ -10,6 +10,9 @@ export const NamePolicyContext: ComponentContext<NamePolicy<string>> =
     getName(name) {
       return name;
     },
+    for(element) {
+      return (name) => name;
+    },
   });
 
 export function useNamePolicy() {

package/src/context/scope.ts

@@ -11,3 +11,12 @@ export const ScopeContext: ComponentContext<OutputScope> =
 export function useScope() {
   return useContext(ScopeContext)!;
 }
+
+export function useMemberScope() {
+  const scope = useScope();
+  if (!scope.isMemberScope) {
+    throw new Error("Expected a member scope, but got a non-member scope.");
+  }
+
+  return scope;
+}

package/src/inspect.browser.ts

@@ -0,0 +1,6 @@
+// inspection is not supported in browsers
+export function inspect() {
+  return "custom inspect";
+}
+
+inspect.custom = Symbol();

package/src/inspect.ts

@@ -0,0 +1 @@
+export { inspect } from "util";

package/src/name-policy.ts

@@ -1,5 +1,16 @@
+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.
+   */
   getName(originalName: string, element: TElements): string;
+  /**
+   * Get a function that takes a name and applies the naming policy to it.
+   */
+  for(element: TElements): NamePolicyGetter;
 }
 
 export function createNamePolicy<T extends string>(
@@ -9,5 +20,8 @@ export function createNamePolicy<T extends string>(
     getName(name, element) {
       return namer(name, element);
     },
+    for(element) {
+      return (name) => namer(name, element);
+    },
   };
 }

package/src/reactive-union-set.ts

@@ -8,7 +8,7 @@ import {
   trigger,
   TriggerOpTypes,
 } from "@vue/reactivity";
-import { effect } from "./reactivity.js";
+import { effect, untrack } from "./reactivity.js";
 
 export interface ReactiveUnionSetOptions<T> {
   onAdd?: OnReactiveSetAddCallback<T>;
@@ -133,7 +133,7 @@ export class ReactiveUnionSet<T> extends Set<T> {
     effect(() => {
       for (const [prevSourceValue, prevTargetValue] of prevValues) {
         if (!subset.has(prevSourceValue)) {
-          onDelete?.(prevSourceValue);
+          untrack(() => onDelete?.(prevSourceValue));
           prevValues.delete(prevSourceValue);
           this.delete(prevTargetValue);
         }
@@ -142,7 +142,7 @@ export class ReactiveUnionSet<T> extends Set<T> {
       for (const value of subset) {
         if (!prevValues.has(value)) {
           if (onAdd) {
-            const added = onAdd(value);
+            const added = untrack(() => onAdd(value));
             prevValues.set(value, added);
           } else {
             this.add(value);
@@ -207,22 +207,28 @@ export class ReactiveUnionSet<T> extends Set<T> {
 
     return shallowReadonly(set);
   }
+
   createIndex<U>(mapper: (value: T) => U | U[]): ReadonlyMap<U, T> {
     const index = shallowReactive(new Map<U, T>());
     this._indexes.push({
       add: (value: T) => {
         effect((oldValue) => {
-          for (const id of [oldValue].flat()) {
-            index.delete(id as U);
+          if (oldValue) {
+            for (const id of [oldValue].flat()) {
+              index.delete(id as U);
+            }
           }
 
-          const mappedValue = mapper(value);
+          // we filter to avoid overwriting existing values (first wins)
+          const mappedValues = [mapper(value)]
+            .flat()
+            .filter((v) => untrack(() => !index.has(v as U)));
 
-          for (const id of [mappedValue].flat()) {
+          for (const id of mappedValues) {
             index.set(id as U, value as any);
           }
 
-          return mappedValue;
+          return mappedValues;
         });
       },
       delete: (value: T) => {

package/src/refkey.ts

@@ -1,14 +1,14 @@
 import { markRaw } from "@vue/reactivity";
 
-const objectIds = new WeakMap<WeakKey, Refkey>();
+const objectIds = new WeakMap<WeakKey, string>();
 let objId = 0;
 
-function getObjectKey(value: WeakKey) {
+function getObjectKey(value: WeakKey): string {
   if (objectIds.has(value)) {
     return objectIds.get(value)!;
   }
 
-  const key = createRefkey(`o${objId++}`);
+  const key = `o${objId++}`;
   objectIds.set(value, key);
 
   return key;
@@ -16,10 +16,34 @@ function getObjectKey(value: WeakKey) {
 
 const RefkeySym: unique symbol = Symbol();
 
-export type Refkey = { key: string; [RefkeySym]: true };
+export type RefkeyBase = {
+  [RefkeySym]: true;
+};
 
-function createRefkey(key: string): Refkey {
-  const refkey: Refkey = {
+export type Refkey = SymbolRefkey | MemberRefkey | Namekey;
+
+export interface SymbolRefkey extends RefkeyBase {
+  key: string;
+}
+
+export interface NamekeyOptions {
+  ignoreNamePolicy?: boolean;
+  ignoreNameConflict?: boolean;
+}
+
+export interface Namekey<TOptions extends NamekeyOptions = NamekeyOptions>
+  extends SymbolRefkey {
+  name: string;
+  options: TOptions;
+}
+
+export interface MemberRefkey extends RefkeyBase {
+  base: Refkey;
+  member: Refkey;
+}
+
+function createSymbolRefkey(key: string): SymbolRefkey {
+  const refkey: SymbolRefkey = {
     key,
     [RefkeySym]: true,
   };
@@ -37,13 +61,34 @@ export function isRefkey(value: unknown): value is Refkey {
   );
 }
 
-function getKey(value: unknown): Refkey {
-  if (isRefkey(value)) {
-    return value;
+export function isSymbolRefkey(value: unknown): value is SymbolRefkey {
+  return isRefkey(value) && Object.hasOwn(value, "key");
+}
+
+export function isMemberRefkey(value: unknown): value is MemberRefkey {
+  return (
+    isRefkey(value) &&
+    Object.hasOwn(value, "base") &&
+    Object.hasOwn(value, "member")
+  );
+}
+
+export function isNamekey(value: unknown): value is Namekey {
+  return isRefkey(value) && Object.hasOwn(value, "name");
+}
+
+/**
+ * This gets the key for a symbol refkey based on the value provided. Refkey values
+ * 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;
   } else if (typeof value === "object" && value !== null) {
     return getObjectKey(value);
   } else {
-    return createRefkey(`s${String(value)}`);
+    return `s${String(value)}`;
   }
 }
 
@@ -65,16 +110,41 @@ const knownRefkeys = new Map<string, Refkey>();
 export function refkey(...args: unknown[]): Refkey {
   const keys = args.length === 0 ? [getKey({})] : args.map((v) => getKey(v));
 
-  const compositeKey = keys.map((v) => v.key).join("\u2063");
+  const compositeKey = keys.join("\u2063");
   if (knownRefkeys.has(compositeKey)) {
     return knownRefkeys.get(compositeKey)!;
   }
 
-  const key = createRefkey(compositeKey);
+  const key = createSymbolRefkey(compositeKey);
   knownRefkeys.set(compositeKey, key);
   return key;
 }
 
+/**
+ * Create a namekey with the given name. The namekey is a unique refkey that
+ * represents a single symbol with the given name and the provided
+ * naming-related options.
+ *
+ * @example
+ * ```tsx
+ * const myClass = namekey("MyClass");
+ *
+ * return <>
+ *   <ClassDeclaration name={myClass} />
+ *   {myClass}
+ * </>
+ * ```
+ *
+ * Renders a class and a reference to that class.
+ */
+export function namekey(name: string, options: NamekeyOptions = {}): Namekey {
+  return {
+    key: getObjectKey({}),
+    name,
+    options,
+    [RefkeySym]: true,
+  };
+}
 /**
  * Create a refkey for an instantiation of a symbol.
  *
@@ -97,6 +167,10 @@ export function refkey(...args: unknown[]): Refkey {
  * instantiated variable refkey and the refkey of the inner member
  * `refkey(rk1, rk3)`.
  */
-export function memberRefkey(base: Refkey, member: Refkey): Refkey {
-  return refkey(base, member);
+export function memberRefkey(base: Refkey, member: Refkey): MemberRefkey {
+  return {
+    base,
+    member,
+    [RefkeySym]: true,
+  };
 }

package/src/symbols/basic-scope.ts

@@ -0,0 +1,23 @@
+import { OutputScope } from "./output-scope.js";
+
+/**
+ * BasicScope is a kind of OutputScope that has a single declaration space named
+ * `symbols`. It is suitable for use in simple language implementations where
+ * there isn't much in the way of unique scope semantics.
+ */
+export class BasicScope extends OutputScope {
+  public static readonly defaultDeclarationSpace = "symbols";
+  public static readonly declarationSpaces = ["symbols"] as const;
+
+  get symbols() {
+    return this.spaceFor("symbols")!;
+  }
+
+  get symbolNames() {
+    return this.spaceFor("symbols")!.symbolNames;
+  }
+
+  get symbolsByRefkey() {
+    return this.spaceFor("symbols")!.symbolsByRefkey;
+  }
+}

package/src/symbols/basic-symbol.ts

@@ -0,0 +1,32 @@
+import { OutputSymbol } from "./output-symbol.js";
+
+/**
+ * BasicSymbol is a kind of OutputSymbol that has instance and static members.
+ * It is suitable for use in simple language implementations where there isn't
+ * much in the way of unique symbol semantics.
+ *
+ * @remarks
+ *
+ * Instantiation is done by copying symbols from instance members to static
+ * members of the instantiation target.
+ *
+ */
+export class BasicSymbol extends OutputSymbol {
+  public static readonly memberSpaces = ["static", "instance"];
+
+  copy() {
+    const options = this.getCopyOptions();
+    const copiedSymbol = new BasicSymbol(this.name, undefined, options);
+    this.initializeCopy(copiedSymbol);
+
+    return copiedSymbol;
+  }
+
+  get instanceMembers() {
+    return this.memberSpaceFor("instance")!;
+  }
+
+  get staticMembers() {
+    return this.memberSpaceFor("static")!;
+  }
+}

package/src/symbols/index.ts

@@ -1,5 +1,7 @@
-export * from "./flags.js";
+export * from "./basic-scope.js";
+export * from "./basic-symbol.js";
 export * from "./output-scope.js";
+export * from "./output-space.js";
 export * from "./output-symbol.js";
 export * from "./symbol-flow.js";
 export * from "./symbol-slot.js";