@effindomv2/fui-as 0.1.37 → 0.1.39

package/scripts/hostgen/assemblyscript-host-events.ts

@@ -0,0 +1,165 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { listHostEventMethods, type HostServiceTypeName } from "./registry";
+import { loadModuleExport, relativeImport, sourcePathForHeader } from "./common";
+
+function asTypeName(type: HostServiceTypeName): string {
+  switch (type) {
+    case "string":
+      return "string";
+    case "bool":
+      return "bool";
+    case "i32":
+      return "i32";
+    case "u32":
+      return "u32";
+    case "i64":
+      return "i64";
+    case "u64":
+      return "u64";
+    case "f64":
+      return "f64";
+    case "bytes":
+      return "Uint8Array";
+    case "i32_array":
+      return "Int32Array";
+    case "u32_array":
+      return "Uint32Array";
+    case "i64_array":
+      return "Int64Array";
+    case "u64_array":
+      return "Uint64Array";
+    case "f64_array":
+      return "Float64Array";
+    case "void":
+      return "void";
+  }
+}
+
+function callbackTypeFor(argTypes: readonly HostServiceTypeName[]): string {
+  if (argTypes.length === 0) {
+    return "Callback0";
+  }
+  if (argTypes.length === 1) {
+    return `Callback1<${asTypeName(argTypes[0])}>`;
+  }
+  if (argTypes.length === 2) {
+    return `Callback2<${asTypeName(argTypes[0])}, ${asTypeName(argTypes[1])}>`;
+  }
+  throw new Error(`Host event uses ${String(argTypes.length)} args; only 0-2 are supported right now.`);
+}
+
+function emitExportArgs(argTypes: readonly HostServiceTypeName[]): string {
+  const parts: string[] = [];
+  argTypes.forEach((type, index) => {
+    if (
+      type === "string" ||
+      type === "bytes" ||
+      type === "i32_array" ||
+      type === "u32_array" ||
+      type === "i64_array" ||
+      type === "u64_array" ||
+      type === "f64_array"
+    ) {
+      parts.push(`arg${String(index)}Ptr: usize`, `arg${String(index)}Len: u32`);
+      return;
+    }
+    parts.push(`arg${String(index)}: ${asTypeName(type)}`);
+  });
+  return parts.join(", ");
+}
+
+function emitDecodedArgs(argTypes: readonly HostServiceTypeName[]): string[] {
+  const lines: string[] = [];
+  argTypes.forEach((type, index) => {
+    if (type === "string") {
+      lines.push(
+        `  const arg${String(index)} = arg${String(index)}Len == 0 ? "" : String.UTF8.decodeUnsafe(arg${String(index)}Ptr, <usize>arg${String(index)}Len, false);`,
+      );
+      return;
+    }
+    if (type === "bytes") {
+      lines.push(`  const arg${String(index)} = new Uint8Array(<i32>arg${String(index)}Len);`);
+      lines.push(`  if (arg${String(index)}Len > 0) {`);
+      lines.push(`    memory.copy(arg${String(index)}.dataStart, arg${String(index)}Ptr, <usize>arg${String(index)}Len);`);
+      lines.push("  }");
+      return;
+    }
+    if (type === "i32_array" || type === "u32_array") {
+      const arrayType = type === "i32_array" ? "Int32Array" : "Uint32Array";
+      lines.push(`  const arg${String(index)} = new ${arrayType}(<i32>arg${String(index)}Len);`);
+      lines.push(`  if (arg${String(index)}Len > 0) {`);
+      lines.push(`    memory.copy(arg${String(index)}.dataStart, arg${String(index)}Ptr, <usize>arg${String(index)}Len << 2);`);
+      lines.push("  }");
+      return;
+    }
+    if (type === "i64_array" || type === "u64_array" || type === "f64_array") {
+      const arrayType =
+        type === "i64_array" ? "Int64Array" : type === "u64_array" ? "Uint64Array" : "Float64Array";
+      lines.push(`  const arg${String(index)} = new ${arrayType}(<i32>arg${String(index)}Len);`);
+      lines.push(`  if (arg${String(index)}Len > 0) {`);
+      lines.push(`    memory.copy(arg${String(index)}.dataStart, arg${String(index)}Ptr, <usize>arg${String(index)}Len << 3);`);
+      lines.push("  }");
+      return;
+    }
+  });
+  return lines;
+}
+
+export async function generateAssemblyScriptHostEventsFile(
+  modulePath: string,
+  exportName: string,
+  outputPath: string,
+  primitivesImportOverride: string | undefined,
+): Promise<void> {
+  const registry = await loadModuleExport(modulePath, exportName, "fui-host-events-");
+  const methods = listHostEventMethods(registry as never);
+  const callbackImport =
+    primitivesImportOverride ??
+    relativeImport(outputPath, path.resolve(path.dirname(modulePath), "..", "..", "src/FuiPrimitives.ts"));
+  const blocks: string[] = [
+    "// @ts-nocheck",
+    `// Generated by hostgen from ${sourcePathForHeader(modulePath)}#${exportName}.`,
+    `import { Callback0, Callback1, Callback2 } from "${callbackImport}";`,
+    "",
+  ];
+  methods.forEach((method, index) => {
+    const callbackType = callbackTypeFor(method.args);
+    const exportArgs = emitExportArgs(method.args);
+    const decodedArgs = emitDecodedArgs(method.args);
+    const publicName =
+      method.eventName.length === 0
+        ? method.eventName
+        : `${method.eventName.charAt(0).toUpperCase()}${method.eventName.slice(1)}`;
+    blocks.push(`let __${method.eventName}Handler: ${callbackType} | null = null;`);
+    blocks.push("");
+    blocks.push(`export function on${publicName}(callback: ${callbackType} | null): void {`);
+    blocks.push(`  __${method.eventName}Handler = callback;`);
+    blocks.push("}");
+    blocks.push("");
+    blocks.push(`export function clear${publicName}(): void {`);
+    blocks.push(`  __${method.eventName}Handler = null;`);
+    blocks.push("}");
+    blocks.push("");
+    blocks.push(`export function ${method.exportName}(${exportArgs}): void {`);
+    blocks.push(`  const callback = __${method.eventName}Handler;`);
+    blocks.push("  if (callback === null) {");
+    blocks.push("    return;");
+    blocks.push("  }");
+    blocks.push(...decodedArgs);
+    if (method.args.length === 0) {
+      blocks.push("  callback.invoke();");
+    } else {
+      blocks.push(
+        `  callback.invoke(${method.args.map((_type, index) => `arg${String(index)}`).join(", ")});`,
+      );
+    }
+    blocks.push("}");
+    if (index + 1 < methods.length) {
+      blocks.push("");
+      blocks.push("");
+    }
+  });
+  await fs.mkdir(path.dirname(outputPath), { recursive: true });
+  await fs.writeFile(outputPath, `${blocks.join("\n")}\n`, "utf8");
+}

package/scripts/hostgen/assemblyscript-host-services.ts

@@ -0,0 +1,207 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { listHostServiceMethods, type HostServiceTypeName } from "./registry";
+import { loadModuleExport, relativeImport, sourcePathForHeader } from "./common";
+
+function asTypeName(type: HostServiceTypeName): string {
+  switch (type) {
+    case "string":
+      return "string";
+    case "bool":
+      return "bool";
+    case "i32":
+      return "i32";
+    case "u32":
+      return "u32";
+    case "i64":
+      return "i64";
+    case "u64":
+      return "u64";
+    case "f64":
+      return "f64";
+    case "bytes":
+      return "Uint8Array";
+    case "i32_array":
+      return "Int32Array";
+    case "u32_array":
+      return "Uint32Array";
+    case "i64_array":
+      return "Int64Array";
+    case "u64_array":
+      return "Uint64Array";
+    case "f64_array":
+      return "Float64Array";
+    case "void":
+      return "void";
+  }
+}
+
+function isPointerLengthType(type: HostServiceTypeName): boolean {
+  return (
+    type === "string" ||
+    type === "bytes" ||
+    type === "i32_array" ||
+    type === "u32_array" ||
+    type === "i64_array" ||
+    type === "u64_array" ||
+    type === "f64_array"
+  );
+}
+
+function returnsBufferType(type: HostServiceTypeName): boolean {
+  return isPointerLengthType(type);
+}
+
+function emitExternalSignature(
+  importName: string,
+  args: readonly HostServiceTypeName[],
+  returns: HostServiceTypeName,
+  moduleName: string,
+): string {
+  const signatureParts: string[] = [];
+  args.forEach((type, index) => {
+    if (isPointerLengthType(type)) {
+      signatureParts.push(`arg${String(index)}Ptr: usize`, `arg${String(index)}Len: u32`);
+      return;
+    }
+    signatureParts.push(`arg${String(index)}: ${asTypeName(type)}`);
+  });
+  if (returnsBufferType(returns)) {
+    signatureParts.push("resultPtr: usize", "resultCap: u32");
+  }
+  const returnType = returnsBufferType(returns) ? "u32" : asTypeName(returns);
+  return [
+    `@external("${moduleName}", "${importName}")`,
+    `declare function __host_${importName}(${signatureParts.join(", ")}): ${returnType};`,
+  ].join("\n");
+}
+
+function emitWrapper(
+  importName: string,
+  args: readonly HostServiceTypeName[],
+  returns: HostServiceTypeName,
+): string {
+  const wrapperArgs = args.map((type, index) => `arg${String(index)}: ${asTypeName(type)}`);
+  const lines: string[] = [];
+  args.forEach((type, index) => {
+    if (type === "string") {
+      lines.push(
+        `  const arg${String(index)}Bytes = Uint8Array.wrap(String.UTF8.encode(arg${String(index)}, false));`,
+      );
+      return;
+    }
+    if (
+      type === "bytes" ||
+      type === "i32_array" ||
+      type === "u32_array" ||
+      type === "i64_array" ||
+      type === "u64_array" ||
+      type === "f64_array"
+    ) {
+      lines.push(`  const arg${String(index)}Bytes = arg${String(index)};`);
+    }
+  });
+  const callArgs: string[] = [];
+  args.forEach((type, index) => {
+    if (type === "string" || type === "bytes") {
+      callArgs.push(`arg${String(index)}Bytes.length > 0 ? arg${String(index)}Bytes.dataStart : 0`);
+      callArgs.push(`<u32>arg${String(index)}Bytes.length`);
+      return;
+    }
+    if (
+      type === "i32_array" ||
+      type === "u32_array" ||
+      type === "i64_array" ||
+      type === "u64_array" ||
+      type === "f64_array"
+    ) {
+      callArgs.push(`arg${String(index)}Bytes.length > 0 ? arg${String(index)}Bytes.dataStart : 0`);
+      callArgs.push(`<u32>arg${String(index)}Bytes.length`);
+      return;
+    }
+    callArgs.push(`arg${String(index)}`);
+  });
+  if (returnsBufferType(returns)) {
+    lines.push("  const resultPtr = hostServiceResultBufferPtr();");
+    lines.push("  const resultCap = hostServiceResultBufferSize();");
+    callArgs.push("resultPtr", "resultCap");
+    lines.push(`  const resultLen = __host_${importName}(${callArgs.join(", ")});`);
+    if (returns === "string") {
+      lines.push(`  return decodeHostServiceStringResult(resultPtr, resultLen, "${importName}");`);
+    } else if (returns === "bytes") {
+      lines.push(`  return decodeHostServiceBytesResult(resultPtr, resultLen, "${importName}");`);
+    } else if (returns === "i32_array") {
+      lines.push(`  return decodeHostServiceI32ArrayResult(resultPtr, resultLen, "${importName}");`);
+    } else if (returns === "u32_array") {
+      lines.push(`  return decodeHostServiceU32ArrayResult(resultPtr, resultLen, "${importName}");`);
+    } else if (returns === "i64_array") {
+      lines.push(`  return decodeHostServiceI64ArrayResult(resultPtr, resultLen, "${importName}");`);
+    } else if (returns === "u64_array") {
+      lines.push(`  return decodeHostServiceU64ArrayResult(resultPtr, resultLen, "${importName}");`);
+    } else {
+      lines.push(`  return decodeHostServiceF64ArrayResult(resultPtr, resultLen, "${importName}");`);
+    }
+  } else if (returns === "void") {
+    lines.push(`  __host_${importName}(${callArgs.join(", ")});`);
+  } else {
+    lines.push(`  return __host_${importName}(${callArgs.join(", ")});`);
+  }
+  return [
+    `export function ${importName}(${wrapperArgs.join(", ")}): ${returns === "string" ? "string" : asTypeName(returns)} {`,
+    ...lines,
+    "}",
+  ].join("\n");
+}
+
+export async function generateAssemblyScriptHostServicesFile(
+  modulePath: string,
+  exportName: string,
+  outputPath: string,
+  primitivesImportOverride: string | undefined,
+  moduleName: string,
+): Promise<void> {
+  const registry = await loadModuleExport(modulePath, exportName, "fui-host-services-");
+  const methods = listHostServiceMethods(registry as never);
+  const runtimeImport =
+    primitivesImportOverride ??
+    relativeImport(outputPath, path.resolve(path.dirname(modulePath), "..", "..", "src/FuiPrimitives.ts"));
+  const blocks: string[] = [
+    "// @ts-nocheck",
+    `// Generated by hostgen from ${sourcePathForHeader(modulePath)}#${exportName}.`,
+  ];
+  if (methods.some((method) => returnsBufferType(method.returns))) {
+    const helpers = [
+      "hostServiceResultBufferPtr",
+      "hostServiceResultBufferSize",
+      ...new Set(
+        methods
+          .map((method) => method.returns)
+          .filter((type) => returnsBufferType(type))
+          .map((type) => {
+            if (type === "string") return "decodeHostServiceStringResult";
+            if (type === "bytes") return "decodeHostServiceBytesResult";
+            if (type === "i32_array") return "decodeHostServiceI32ArrayResult";
+            if (type === "u32_array") return "decodeHostServiceU32ArrayResult";
+            if (type === "i64_array") return "decodeHostServiceI64ArrayResult";
+            if (type === "u64_array") return "decodeHostServiceU64ArrayResult";
+            return "decodeHostServiceF64ArrayResult";
+          }),
+      ),
+    ];
+    blocks.push(`import { ${helpers.join(", ")} } from "${runtimeImport}";`);
+    blocks.push("");
+  } else {
+    blocks.push("");
+  }
+  methods.forEach((method, index) => {
+    blocks.push(emitExternalSignature(method.importName, method.args, method.returns, moduleName));
+    blocks.push("");
+    blocks.push(emitWrapper(method.importName, method.args, method.returns));
+    if (index + 1 < methods.length) {
+      blocks.push("");
+    }
+  });
+  await fs.mkdir(path.dirname(outputPath), { recursive: true });
+  await fs.writeFile(outputPath, `${blocks.join("\n")}\n`, "utf8");
+}
+

package/scripts/hostgen/common.ts

@@ -0,0 +1,73 @@
+import { build } from "esbuild";
+import { promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+export function toPosix(value: string): string {
+  return value.split(path.sep).join("/");
+}
+
+export function relativeImport(fromFile: string, targetFile: string): string {
+  let relative = path.relative(path.dirname(fromFile), targetFile);
+  relative = relative.replace(/\.[^.]+$/, "");
+  if (!relative.startsWith(".")) {
+    relative = `./${relative}`;
+  }
+  return toPosix(relative);
+}
+
+export function sourcePathForHeader(sourceModulePath: string): string {
+  const relative = path.relative(process.cwd(), sourceModulePath);
+  return toPosix(relative.startsWith(".") ? relative : `./${relative}`);
+}
+
+export async function loadModuleExport(
+  modulePath: string,
+  exportName: string,
+  tempPrefix: string,
+): Promise<unknown> {
+  const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), tempPrefix));
+  const bundledFile = path.join(tempDir, "module.mjs");
+  try {
+    await build({
+      entryPoints: [modulePath],
+      outfile: bundledFile,
+      bundle: true,
+      format: "esm",
+      platform: "node",
+      target: "node20",
+      logLevel: "silent",
+    });
+    const loaded = await import(pathToFileURL(bundledFile).href) as Record<string, unknown>;
+    if (!(exportName in loaded)) {
+      throw new Error(`Module does not export "${exportName}".`);
+    }
+    return loaded[exportName];
+  } finally {
+    await fs.rm(tempDir, { recursive: true, force: true });
+  }
+}
+
+export function snakeCaseIdentifier(value: string): string {
+  let result = "";
+  for (let index = 0; index < value.length; index += 1) {
+    const char = value[index] ?? "";
+    const previous = index > 0 ? value[index - 1] ?? "" : "";
+    const next = index + 1 < value.length ? value[index + 1] ?? "" : "";
+    const isUpper = char >= "A" && char <= "Z";
+    const prevIsLowerOrDigit =
+      (previous >= "a" && previous <= "z") || (previous >= "0" && previous <= "9");
+    const nextIsLower = next >= "a" && next <= "z";
+    if (
+      index > 0 &&
+      isUpper &&
+      (prevIsLowerOrDigit || ((previous >= "A" && previous <= "Z") && nextIsLower))
+    ) {
+      result += "_";
+    }
+    result += char.toLowerCase();
+  }
+  return result;
+}
+

package/scripts/hostgen/registry.ts

@@ -0,0 +1,159 @@
+export type HostServiceTypeName =
+  | "string"
+  | "bool"
+  | "i32"
+  | "u32"
+  | "i64"
+  | "u64"
+  | "f64"
+  | "bytes"
+  | "i32_array"
+  | "u32_array"
+  | "i64_array"
+  | "u64_array"
+  | "f64_array"
+  | "void";
+
+interface HostServiceMethodDefinition {
+  readonly importName?: string;
+  readonly args: readonly HostServiceTypeName[];
+  readonly returns: HostServiceTypeName;
+  readonly implementation: (...args: readonly unknown[]) => unknown;
+}
+
+type HostServicesDefinition = Record<string, Record<string, HostServiceMethodDefinition>>;
+
+interface HostEventMethodDefinition {
+  readonly args: readonly HostServiceTypeName[];
+  readonly subscribe: (emit: (...args: readonly unknown[]) => void) => (() => void) | undefined;
+}
+
+type HostEventsDefinition = Record<string, Record<string, HostEventMethodDefinition>>;
+
+export interface NormalizedHostServiceMethod {
+  readonly serviceName: string;
+  readonly methodName: string;
+  readonly importName: string;
+  readonly args: readonly HostServiceTypeName[];
+  readonly returns: HostServiceTypeName;
+  readonly implementation: (...args: readonly unknown[]) => unknown;
+}
+
+export interface NormalizedHostEventMethod {
+  readonly serviceName: string;
+  readonly methodName: string;
+  readonly eventName: string;
+  readonly exportName: string;
+  readonly args: readonly HostServiceTypeName[];
+  readonly subscribe: (emit: (...args: readonly unknown[]) => void) => (() => void) | undefined;
+}
+
+const IDENTIFIER_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+function assertIdentifier(value: string, context: string): void {
+  if (!IDENTIFIER_RE.test(value)) {
+    throw new Error(`${context} "${value}" must be a valid identifier.`);
+  }
+}
+
+function capitalize(value: string): string {
+  return value.length === 0 ? value : `${value.slice(0, 1).toUpperCase()}${value.slice(1)}`;
+}
+
+function validateServiceType(type: string, context: string): asserts type is HostServiceTypeName {
+  if (
+    type === "string" ||
+    type === "bool" ||
+    type === "i32" ||
+    type === "u32" ||
+    type === "i64" ||
+    type === "u64" ||
+    type === "f64" ||
+    type === "bytes" ||
+    type === "i32_array" ||
+    type === "u32_array" ||
+    type === "i64_array" ||
+    type === "u64_array" ||
+    type === "f64_array" ||
+    type === "void"
+  ) {
+    return;
+  }
+  throw new Error(`${context} uses unsupported host-service type "${type}".`);
+}
+
+function validateEventType(type: string, context: string): asserts type is HostServiceTypeName {
+  if (type !== "void") {
+    validateServiceType(type, context);
+    return;
+  }
+  throw new Error(`${context} uses unsupported host-event type "${type}".`);
+}
+
+export function listHostServiceMethods(services: HostServicesDefinition | undefined): readonly NormalizedHostServiceMethod[] {
+  if (services === undefined) {
+    return [];
+  }
+  const methods: NormalizedHostServiceMethod[] = [];
+  const seenImports = new Set<string>();
+  for (const [serviceName, serviceMethods] of Object.entries(services)) {
+    assertIdentifier(serviceName, "Host service");
+    for (const [methodName, definition] of Object.entries(serviceMethods)) {
+      assertIdentifier(methodName, `Host service ${serviceName} method`);
+      const importName = definition.importName ?? `${serviceName}${capitalize(methodName)}`;
+      assertIdentifier(importName, `Host service ${serviceName}.${methodName} import`);
+      if (seenImports.has(importName)) {
+        throw new Error(`Duplicate host-service import name "${importName}".`);
+      }
+      seenImports.add(importName);
+      const args = [...definition.args];
+      args.forEach((type, index) => {
+        validateServiceType(type, `Host service ${serviceName}.${methodName} arg ${String(index)}`);
+      });
+      validateServiceType(definition.returns, `Host service ${serviceName}.${methodName} return`);
+      methods.push({
+        serviceName,
+        methodName,
+        importName,
+        args,
+        returns: definition.returns,
+        implementation: definition.implementation,
+      });
+    }
+  }
+  methods.sort((left, right) => left.importName.localeCompare(right.importName));
+  return methods;
+}
+
+export function listHostEventMethods(events: HostEventsDefinition | undefined): readonly NormalizedHostEventMethod[] {
+  if (events === undefined) {
+    return [];
+  }
+  const methods: NormalizedHostEventMethod[] = [];
+  const seenEvents = new Set<string>();
+  for (const [serviceName, serviceMethods] of Object.entries(events)) {
+    assertIdentifier(serviceName, "Host event service");
+    for (const [methodName, definition] of Object.entries(serviceMethods)) {
+      assertIdentifier(methodName, `Host event ${serviceName} method`);
+      const eventName = `${serviceName}${capitalize(methodName)}`;
+      if (seenEvents.has(eventName)) {
+        throw new Error(`Duplicate host-event name "${eventName}".`);
+      }
+      seenEvents.add(eventName);
+      const args = [...definition.args];
+      args.forEach((type, index) => {
+        validateEventType(type, `Host event ${serviceName}.${methodName} arg ${String(index)}`);
+      });
+      methods.push({
+        serviceName,
+        methodName,
+        eventName,
+        exportName: `__fui_host_event_${eventName}`,
+        args,
+        subscribe: definition.subscribe,
+      });
+    }
+  }
+  methods.sort((left, right) => left.eventName.localeCompare(right.eventName));
+  return methods;
+}