@alloy-js/core 0.1.0

package/test/symbols.test.ts

@@ -0,0 +1,406 @@
+import { describe, expect, it } from "vitest";
+import {
+  Binder,
+  createOutputBinder,
+  OutputScope,
+  OutputScopeFlags,
+  OutputSymbol,
+  OutputSymbolFlags,
+} from "../src/binder.js";
+import { Refkey, refkey } from "../src/refkey.js";
+
+it("works", () => {
+  const binder = createOutputBinder();
+  const scope = binder.createScope({
+    kind: "foo",
+    name: "scope",
+    parent: binder.globalScope,
+  });
+
+  const symbol = binder.createSymbol({
+    name: "sym",
+    scope,
+    refkey: "foo",
+  });
+
+  expect([...scope.getSymbolNames()]).toEqual(["sym"]);
+
+  symbol.name = "bar";
+
+  expect([...scope.getSymbolNames()]).toEqual(["bar"]);
+});
+
+it("resolves symbol conflicts", () => {
+  const binder = createOutputBinder();
+  const scope = binder.createScope({
+    kind: "foo",
+    name: "scope",
+    parent: binder.globalScope,
+  });
+
+  const _s1 = binder.createSymbol({
+    name: "sym",
+    scope,
+    refkey: "foo",
+  });
+
+  const s2 = binder.createSymbol({
+    name: "sym",
+    scope,
+    refkey: "foo",
+  });
+
+  expect(s2.name).toEqual("sym_2");
+});
+
+type ScopeRecords = Record<string, ScopeDescriptor>;
+type SymbolRecords = Record<string, SymbolDescriptor>;
+
+interface ScopeDescriptor {
+  flags?: OutputScopeFlags;
+  scopes?: ScopeRecords;
+  symbols: SymbolRecords;
+}
+
+interface SymbolDescriptor {
+  refkey?: Refkey;
+  flags?: OutputSymbolFlags;
+  instanceMembers?: SymbolRecords;
+  staticMembers?: SymbolRecords;
+}
+
+interface ScopeTreeResult {
+  symbols: Record<string, OutputSymbol>;
+  scopes: Record<string, OutputScope>;
+}
+function createScopeTree(binder: Binder, tree: ScopeRecords): ScopeTreeResult {
+  const createdItems: ScopeTreeResult = {
+    symbols: {},
+    scopes: {},
+  };
+
+  for (const [name, desc] of Object.entries(tree)) {
+    createScope(name, desc);
+  }
+
+  return createdItems;
+
+  function createScope(
+    name: string,
+    descriptor: ScopeDescriptor,
+    parent = binder.globalScope,
+  ) {
+    const scope = binder.createScope({
+      kind: "useless",
+      name,
+      parent,
+      flags: descriptor.flags ?? OutputScopeFlags.None,
+    });
+
+    createdItems.scopes[name] = scope;
+
+    for (const [name, desc] of Object.entries(descriptor.symbols)) {
+      createSymbol(name, desc, scope);
+    }
+
+    for (const [name, desc] of Object.entries(descriptor.scopes ?? {})) {
+      createScope(name, desc, scope);
+    }
+  }
+
+  function createSymbol(
+    name: string,
+    descriptor: SymbolDescriptor,
+    parent: OutputScope,
+  ) {
+    const symbol = binder.createSymbol({
+      name,
+      scope: parent,
+      refkey: descriptor.refkey ?? refkey(),
+      flags: descriptor.flags ?? OutputSymbolFlags.None,
+    });
+
+    createdItems.symbols[name] = symbol;
+
+    if (descriptor.instanceMembers) {
+      for (const [name, desc] of Object.entries(descriptor.instanceMembers)) {
+        createSymbol(name, desc, symbol.instanceMemberScope!);
+      }
+    }
+
+    if (descriptor.staticMembers) {
+      for (const [name, desc] of Object.entries(descriptor.staticMembers)) {
+        createSymbol(name, desc, symbol.staticMemberScope!);
+      }
+    }
+  }
+}
+describe("static members", () => {
+  it("resolves static symbols", () => {
+    const binder = createOutputBinder();
+    const {
+      scopes: { root },
+      symbols: { root: rootSym, static: staticSym },
+    } = createScopeTree(binder, {
+      root: {
+        symbols: {
+          root: {
+            flags:
+              OutputSymbolFlags.InstanceMemberContainer |
+              OutputSymbolFlags.StaticMemberContainer,
+            staticMembers: {
+              static: {
+                flags: OutputSymbolFlags.StaticMember,
+              },
+            },
+          },
+        },
+      },
+    });
+
+    const resolution = binder.resolveDeclarationByKey(
+      root,
+      undefined,
+      staticSym.refkey,
+    );
+    expect(resolution.value).toBeDefined();
+    const { commonScope, pathUp, pathDown, targetDeclaration, memberPath } =
+      resolution.value!;
+    expect(commonScope).toBe(root);
+    expect(targetDeclaration).toBe(rootSym);
+    expect(pathDown).toEqual([]);
+    expect(pathUp).toEqual([]);
+    expect(memberPath!.map((s) => s.name)).toEqual(["root", "static"]);
+  });
+
+  it("resolves deeply nested static symbols", () => {
+    const binder = createOutputBinder();
+    const {
+      scopes: { root },
+      symbols: { root: rootSym, nested_static },
+    } = createScopeTree(binder, {
+      root: {
+        symbols: {
+          root: {
+            flags:
+              OutputSymbolFlags.InstanceMemberContainer |
+              OutputSymbolFlags.StaticMemberContainer,
+            staticMembers: {
+              static: {
+                flags:
+                  OutputSymbolFlags.StaticMember |
+                  OutputSymbolFlags.StaticMemberContainer,
+                staticMembers: {
+                  nested_static: {
+                    flags: OutputSymbolFlags.StaticMember,
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+    });
+
+    const resolution = binder.resolveDeclarationByKey(
+      root,
+      undefined,
+      nested_static.refkey,
+    );
+    expect(resolution.value).toBeDefined();
+    const { commonScope, pathUp, pathDown, targetDeclaration, memberPath } =
+      resolution.value!;
+    expect(commonScope).toBe(root);
+    expect(targetDeclaration).toBe(rootSym);
+    expect(pathDown).toEqual([]);
+    expect(pathUp).toEqual([]);
+    expect(memberPath!.map((s) => s.name)).toEqual([
+      "root",
+      "static",
+      "nested_static",
+    ]);
+  });
+
+  it("resolves static symbols lazily", () => {
+    const staticSymRefkey = refkey();
+
+    const binder = createOutputBinder();
+    const {
+      scopes: { root },
+      symbols: { root: rootSym },
+    } = createScopeTree(binder, {
+      root: {
+        symbols: {
+          root: {
+            flags:
+              OutputSymbolFlags.InstanceMemberContainer |
+              OutputSymbolFlags.StaticMemberContainer,
+          },
+        },
+      },
+    });
+
+    const resolution = binder.resolveDeclarationByKey(
+      root,
+      undefined,
+      staticSymRefkey,
+    );
+    expect(resolution.value).toBeUndefined();
+    binder.createSymbol({
+      name: "static",
+      scope: rootSym.staticMemberScope!,
+      refkey: staticSymRefkey,
+      flags: OutputSymbolFlags.StaticMember,
+    });
+
+    expect(resolution.value).toBeDefined();
+    const { commonScope, pathUp, pathDown, targetDeclaration, memberPath } =
+      resolution.value!;
+    expect(commonScope).toBe(root);
+    expect(targetDeclaration).toBe(rootSym);
+    expect(pathDown).toEqual([]);
+    expect(pathUp).toEqual([]);
+    expect(memberPath!.map((s) => s.name)).toEqual(["root", "static"]);
+  });
+});
+
+describe("instance members", () => {
+  it("resolves", () => {
+    const binder = createOutputBinder();
+    const {
+      symbols: { root: rootSym, instance },
+    } = createScopeTree(binder, {
+      root: {
+        symbols: {
+          root: {
+            flags: OutputSymbolFlags.InstanceMemberContainer,
+            instanceMembers: {
+              instance: {
+                flags: OutputSymbolFlags.InstanceMember,
+              },
+            },
+          },
+        },
+      },
+    });
+
+    const resolution = binder.resolveDeclarationByKey(
+      undefined,
+      rootSym.instanceMemberScope!,
+      instance.refkey,
+    );
+    expect(resolution.value).toBeDefined();
+    const { commonScope, pathUp, pathDown, targetDeclaration, memberPath } =
+      resolution.value!;
+
+    expect(commonScope).toBe(rootSym.instanceMemberScope);
+    expect(targetDeclaration).toBe(instance);
+    expect(pathDown).toEqual([]);
+    expect(pathUp).toEqual([]);
+    expect(memberPath).toEqual([instance]);
+  });
+
+  it("doesn't resolve from outside the member scope", () => {
+    const binder = createOutputBinder();
+    const {
+      scopes: { root },
+      symbols: { instance },
+    } = createScopeTree(binder, {
+      root: {
+        symbols: {
+          root: {
+            flags: OutputSymbolFlags.InstanceMemberContainer,
+            instanceMembers: {
+              instance: {
+                flags: OutputSymbolFlags.InstanceMember,
+              },
+            },
+          },
+        },
+      },
+    });
+
+    expect(() =>
+      binder.resolveDeclarationByKey(root, undefined, instance.refkey),
+    ).toThrow(/Cannot resolve member symbols/);
+  });
+});
+
+describe("instantiating members", () => {
+  it("instantiates static symbols", () => {
+    const binder = createOutputBinder();
+    const {
+      symbols: { rootSymbol, instance, instantiation },
+    } = createScopeTree(binder, {
+      rootScope: {
+        symbols: {
+          rootSymbol: {
+            flags: OutputSymbolFlags.InstanceMemberContainer,
+            instanceMembers: {
+              instance: {
+                flags: OutputSymbolFlags.StaticMember,
+              },
+            },
+          },
+          instantiation: {},
+        },
+      },
+    });
+
+    binder.instantiateSymbolInto(rootSymbol, instantiation);
+    expect(
+      instantiation.flags & OutputSymbolFlags.InstanceMemberContainer,
+    ).toBeTruthy();
+    expect(instantiation.instanceMemberScope).toBeDefined();
+    const expectedRefkey = refkey(instantiation.refkey, instance.refkey);
+    expect(
+      instantiation.instanceMemberScope!.symbolsByRefkey.get(expectedRefkey),
+    ).toBeDefined();
+  });
+
+  it("instantiates static symbols that are added after the instantiation", () => {
+    const binder = createOutputBinder();
+    const {
+      symbols: { rootSymbol, instance, instantiation },
+    } = createScopeTree(binder, {
+      rootScope: {
+        symbols: {
+          rootSymbol: {
+            flags: OutputSymbolFlags.InstanceMemberContainer,
+            instanceMembers: {
+              instance: {
+                flags: OutputSymbolFlags.StaticMember,
+              },
+            },
+          },
+          instantiation: {},
+        },
+      },
+    });
+
+    binder.instantiateSymbolInto(rootSymbol, instantiation);
+    expect(
+      instantiation.flags & OutputSymbolFlags.InstanceMemberContainer,
+    ).toBeTruthy();
+    expect(instantiation.instanceMemberScope).toBeDefined();
+    const expectedRefkey = refkey(instantiation.refkey, instance.refkey);
+    expect(
+      instantiation.instanceMemberScope!.symbolsByRefkey.get(expectedRefkey),
+    ).toBeDefined();
+
+    const newInstanceMemberRefkey = refkey();
+    binder.createSymbol({
+      name: "newInstanceMember",
+      scope: rootSymbol.instanceMemberScope!,
+      refkey: newInstanceMemberRefkey,
+      flags: OutputSymbolFlags.InstanceMember,
+    });
+    const newExpectedRefkey = refkey(
+      instantiation.refkey,
+      newInstanceMemberRefkey,
+    );
+    expect(
+      instantiation.instanceMemberScope!.symbolsByRefkey.get(newExpectedRefkey),
+    ).toBeDefined();
+  });
+});

package/test/utils.test.tsx

@@ -0,0 +1,150 @@
+import { describe, expect, it } from "vitest";
+import { join, mapJoin } from "../src/utils.js";
+import "../testing/extend-expect.js";
+
+describe("mapJoin", () => {
+  it("can map a map", () => {
+    const map = new Map([
+      ["a", 1],
+      ["b", 2],
+    ]);
+
+    function Foo(props: { key: string; value: number }) {
+      return <>Key: {props.key}, Value: {props.value}</>;
+    }
+
+    const joined = mapJoin(map, (
+      key,
+      value,
+    ) => <Foo key={key} value={value} />);
+
+    expect(joined).toRenderTo(`
+      Key: a, Value: 1
+      Key: b, Value: 2
+    `);
+  });
+
+  it("can map an array", () => {
+    const arr = [1, 2];
+
+    function Foo(props: { value: number }) {
+      return <>Value: {props.value}</>;
+    }
+
+    const joined = mapJoin(arr, (value) => <Foo value={value} />);
+
+    expect(joined).toRenderTo(`
+      Value: 1
+      Value: 2
+    `);
+  });
+
+  it("can map a joiner", () => {
+    const arr = [1, 2];
+
+    function Foo(props: { value: number }) {
+      return <>Value: {props.value}</>;
+    }
+
+    const joined = mapJoin(arr, (value) => <Foo value={value} />, {
+      joiner: "-",
+    });
+
+    expect(joined).toRenderTo(`
+      Value: 1-Value: 2
+    `);
+  });
+
+  it("can map an ender", () => {
+    const arr = [1, 2];
+
+    function Foo(props: { value: number }) {
+      return <>Value: {props.value}</>;
+    }
+
+    const joined = mapJoin(arr, (value) => <Foo value={value} />, {
+      joiner: "-",
+      ender: ";",
+    });
+
+    expect(joined).toRenderTo(`
+      Value: 1-Value: 2;
+    `);
+  });
+
+  it("can map using an iterator", () => {
+    const arr = [1, 2].values();
+
+    function Foo(props: { value: number }) {
+      return <>Value: {props.value}</>;
+    }
+
+    const joined = mapJoin(arr, (value) => <Foo value={value} />, {
+      joiner: "-",
+      ender: ";",
+    });
+
+    expect(joined).toRenderTo(`
+      Value: 1-Value: 2;
+    `);
+  });
+});
+
+describe("join", () => {
+  it("can join an array", () => {
+    const arr = [<Foo value={1} />, <Foo value={2} />];
+
+    function Foo(props: { value: number }) {
+      return <>Value: {props.value}</>;
+    }
+
+    const joined = join(arr);
+
+    expect(joined).toRenderTo(`
+      Value: 1
+      Value: 2
+    `);
+  });
+
+  it("can join an array with a joiner", () => {
+    const arr = [<Foo value={1} />, <Foo value={2} />];
+
+    function Foo(props: { value: number }) {
+      return <>Value: {props.value}</>;
+    }
+
+    const joined = join(arr, { joiner: "-" });
+
+    expect(joined).toRenderTo(`
+      Value: 1-Value: 2
+    `);
+  });
+
+  it("can join an array with an ender", () => {
+    const arr = [<Foo value={1} />, <Foo value={2} />];
+
+    function Foo(props: { value: number }) {
+      return <>Value: {props.value}</>;
+    }
+
+    const joined = join(arr, { joiner: "-", ender: ";" });
+
+    expect(joined).toRenderTo(`
+      Value: 1-Value: 2;
+    `);
+  });
+
+  it("can join using an iterator", () => {
+    const arrIter = [<Foo value={1} />, <Foo value={2} />].values();
+
+    function Foo(props: { value: number }) {
+      return <>Value: {props.value}</>;
+    }
+
+    const joined = join(arrIter, { joiner: "-", ender: ";" });
+
+    expect(joined).toRenderTo(`
+      Value: 1-Value: 2;
+    `);
+  });
+});

package/testing/extend-expect.ts

@@ -0,0 +1,20 @@
+import { Children, renderTree } from "@alloy-js/core";
+import { expect } from "vitest";
+import { dedent, printTree } from "./render.js";
+
+expect.extend({
+  toRenderTo(received: Children, expectedRaw: string) {
+    const { isNot } = this;
+    const tree = renderTree(received);
+    const actual = printTree(tree);
+    const expected = dedent(expectedRaw);
+    return {
+      pass: actual === expected,
+      message: () => {
+        return `Render is${isNot ? " not" : ""} incorrect`;
+      },
+      actual,
+      expected,
+    };
+  },
+});

package/testing/index.ts

@@ -0,0 +1,2 @@
+import "./extend-expect.js";
+export * from "./render.js";

package/testing/render.ts

@@ -0,0 +1,37 @@
+import { RenderTextTree, renderTree } from "@alloy-js/core";
+import { Children } from "@alloy-js/core/jsx-runtime";
+
+export function printTree(tree: RenderTextTree) {
+  return (tree as any).flat(Infinity).join("");
+}
+
+export function renderToString(element: Children) {
+  return printTree(renderTree(element));
+}
+
+export function d(strings: TemplateStringsArray, ...values: any[]): string {
+  // Combine the strings and values
+  const result = strings.reduce(
+    (acc, str, i) => acc + str + (values[i] ?? ""),
+    "",
+  );
+
+  return dedent(result);
+}
+
+export function dedent(str: string): string {
+  // Remove leading and trailing line breaks
+  str = str.replace(/^\n|\n[ ]*$/g, "");
+
+  // Find the indent of the first line
+  const match = str.match(/^[ \t]+/);
+  const indent = match ? match[0] : "";
+
+  // Remove the indent from each line
+  const dedented = str
+    .split("\n")
+    .map((line) => (line.startsWith(indent) ? line.slice(indent.length) : line))
+    .join("\n");
+
+  return dedented;
+}

package/testing/vitest.d.ts

@@ -0,0 +1,10 @@
+import "vitest";
+
+interface CustomMatchers<R = unknown> {
+  toRenderTo: (str: string) => R;
+}
+
+declare module "vitest" {
+  interface Assertion<T = any> extends CustomMatchers<T> {}
+  interface AsymmetricMatchersContaining extends CustomMatchers {}
+}

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "emitDeclarationOnly": true,
+    "declaration": true,
+    "outDir": "dist"
+  },
+  "include": [
+    "src/**/*.ts",
+    "src/**/*.tsx",
+    "test/**/*.ts",
+    "test/**/*.tsx",
+    "testing/**/*.ts",
+    "testing/**/*.d.ts"
+  ],
+  "exclude": ["node_modules", "dist"]
+}

package/vitest.config.ts

@@ -0,0 +1,18 @@
+import { babel } from "@rollup/plugin-babel";
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  esbuild: {
+    jsx: "preserve",
+    sourcemap: "both",
+  },
+  plugins: [
+    babel({
+      inputSourceMap: true as any,
+      sourceMaps: "both",
+      babelHelpers: "bundled",
+      extensions: [".ts", ".tsx"],
+      presets: ["@babel/preset-typescript", ["@alloy-js/babel-preset", {}]],
+    }),
+  ],
+});