@alloy-js/core 0.19.0-dev.3 → 0.20.0-dev.0

package/src/debug.ts

@@ -1,4 +1,3 @@
-/* eslint-disable no-console */
 import { isReactive } from "@vue/reactivity";
 import Table from "cli-table3";
 import pc from "picocolors";
@@ -19,12 +18,15 @@ const debug: DebugInterface = {
   component: {
     stack: debugStack,
     tree() {
+      //eslint-disable-next-line no-console
       console.log("tree");
     },
     watch() {
+      //eslint-disable-next-line no-console
       console.log("watch");
     },
     render() {
+      //eslint-disable-next-line no-console
       console.log("render");
     },
     context: debugContext,
@@ -78,6 +80,7 @@ function debugStack() {
 function debugContext() {
   let currentContext = getContext();
   while (currentContext !== null) {
+    //eslint-disable-next-line no-console
     console.log(printContext(currentContext));
     currentContext = currentContext.owner;
   }

package/src/host/alloy-host.browser.ts

@@ -0,0 +1,56 @@
+import { AlloyFileInterface, AlloyHostInterface } from "./interface.js";
+
+export const AlloyHost: AlloyHostInterface = {
+  read(source: string): AlloyFileInterface {
+    return new AlloyFile(source);
+  },
+
+  async write(
+    destination: string,
+    content: string | ArrayBuffer | Uint8Array | ReadableStream<Uint8Array>,
+  ): Promise<void> {
+    throw new Error(
+      "File system write operations are not supported in the browser",
+    );
+  },
+
+  async exists(source: string): Promise<boolean> {
+    throw new Error(
+      "File system exists operations are not supported in the browser",
+    );
+  },
+
+  async mkdir(path: string): Promise<void> {
+    throw new Error(
+      "File system mkdir operations are not supported in the browser",
+    );
+  },
+};
+
+export class AlloyFile implements AlloyFileInterface {
+  constructor(private source: string) {}
+
+  async text(): Promise<string> {
+    throw new Error(
+      "File system read operations are not supported in the browser",
+    );
+  }
+
+  async arrayBuffer(): Promise<ArrayBuffer> {
+    throw new Error(
+      "File system read operations are not supported in the browser",
+    );
+  }
+
+  async bytes(): Promise<Uint8Array> {
+    throw new Error(
+      "File system read operations are not supported in the browser",
+    );
+  }
+
+  stream(): ReadableStream<Uint8Array> {
+    throw new Error(
+      "File system read operations are not supported in the browser",
+    );
+  }
+}

package/src/host/alloy-host.ts

@@ -0,0 +1,160 @@
+import { createReadStream, createWriteStream } from "fs";
+import { access, mkdir, readFile, writeFile } from "fs/promises";
+import { AlloyFileInterface, AlloyHostInterface } from "./interface.js";
+
+export const AlloyHost: AlloyHostInterface = {
+  read(source: string): AlloyFileInterface {
+    return new AlloyFile(source);
+  },
+
+  async write(
+    destination: string,
+    content: string | ArrayBuffer | Uint8Array | ReadableStream<Uint8Array>,
+  ): Promise<void> {
+    if (typeof content === "string") {
+      //eslint-disable-next-line no-useless-catch
+      try {
+        await writeFile(destination, content, "utf8");
+      } catch (e) {
+        // get good callstacks
+        throw e;
+      }
+    } else if (content instanceof ArrayBuffer) {
+      //eslint-disable-next-line no-useless-catch
+      try {
+        await writeFile(destination, new Uint8Array(content));
+      } catch (e) {
+        // get good callstacks
+        throw e;
+      }
+    } else if (content instanceof Uint8Array) {
+      //eslint-disable-next-line no-useless-catch
+      try {
+        await writeFile(destination, content);
+      } catch (e) {
+        // get good callstacks
+        throw e;
+      }
+    } else {
+      // content is ReadableStream<Uint8Array>
+      //eslint-disable-next-line no-useless-catch
+      try {
+        const writeStream = createWriteStream(destination);
+        const reader = content.getReader();
+
+        try {
+          while (true) {
+            const { done, value } = await reader.read();
+            if (done) break;
+
+            await new Promise<void>((resolve, reject) => {
+              writeStream.write(value, (err) => {
+                if (err) reject(err);
+                else resolve();
+              });
+            });
+          }
+        } finally {
+          reader.releaseLock();
+          await new Promise<void>((resolve, reject) => {
+            writeStream.end((err?: Error) => {
+              if (err) reject(err);
+              else resolve();
+            });
+          });
+        }
+      } catch (e) {
+        // get good callstacks
+        throw e;
+      }
+    }
+  },
+
+  async exists(source: string): Promise<boolean> {
+    try {
+      await access(source);
+      return true;
+    } catch {
+      return false;
+    }
+  },
+
+  async mkdir(path: string): Promise<void> {
+    //eslint-disable-next-line no-useless-catch
+    try {
+      await mkdir(path, { recursive: true });
+    } catch (e) {
+      // get good callstacks
+      throw e;
+    }
+  },
+};
+
+export class AlloyFile implements AlloyFileInterface {
+  constructor(private source: string) {}
+
+  async text(): Promise<string> {
+    //eslint-disable-next-line no-useless-catch
+    try {
+      return await readFile(this.source, "utf8");
+    } catch (e) {
+      // get good callstacks
+      throw e;
+    }
+  }
+
+  async arrayBuffer(): Promise<ArrayBuffer> {
+    //eslint-disable-next-line no-useless-catch
+    try {
+      const buffer = await readFile(this.source);
+      return buffer.buffer.slice(
+        buffer.byteOffset,
+        buffer.byteOffset + buffer.byteLength,
+      );
+    } catch (e) {
+      // get good callstacks
+      throw e;
+    }
+  }
+
+  async bytes(): Promise<Uint8Array> {
+    //eslint-disable-next-line no-useless-catch
+    try {
+      const buffer = await readFile(this.source);
+      return new Uint8Array(buffer);
+    } catch (e) {
+      // get good callstacks
+      throw e;
+    }
+  }
+
+  stream(): ReadableStream<Uint8Array> {
+    //eslint-disable-next-line no-useless-catch
+    try {
+      const nodeStream = createReadStream(this.source);
+
+      return new ReadableStream<Uint8Array>({
+        start(controller) {
+          nodeStream.on("data", (chunk) => {
+            controller.enqueue(new Uint8Array(chunk as Buffer));
+          });
+
+          nodeStream.on("end", () => {
+            controller.close();
+          });
+
+          nodeStream.on("error", (err) => {
+            controller.error(err);
+          });
+        },
+
+        cancel() {
+          nodeStream.destroy();
+        },
+      });
+    } catch (e) {
+      // get good callstacks
+      throw e;
+    }
+  }
+}

package/src/host/interface.ts

@@ -0,0 +1,153 @@
+/**
+ * Interface for the Alloy host file system operations.
+ *
+ * This interface abstracts file system operations to allow different
+ * implementations across different environments (Node.js, browser, etc.).
+ */
+export interface AlloyHostInterface {
+  /**
+   * Read a file from the file system.
+   *
+   * @param source - The path to the file to read
+   * @returns An AlloyFileInterface for accessing the file content in different formats
+   *
+   * @example
+   * ```typescript
+   * const file = AlloyHost.read('./config.json');
+   * const content = await file.text();
+   * ```
+   */
+  read(source: string): AlloyFileInterface;
+
+  /**
+   * Write content to a file in the file system.
+   *
+   * Supports writing different types of content including strings, binary data,
+   * and streams. For strings, content is written with UTF-8 encoding.
+   *
+   * @param destination - The path where the file should be written
+   * @param content - The content to write (string, ArrayBuffer, Uint8Array, or ReadableStream)
+   * @returns A Promise that resolves when the write operation is complete
+   *
+   * @example
+   * ```typescript
+   * // Write a string
+   * await AlloyHost.write('./output.txt', 'Hello, world!');
+   *
+   * // Write binary data
+   * const data = new Uint8Array([72, 101, 108, 108, 111]);
+   * await AlloyHost.write('./binary.dat', data);
+   * ```
+   */
+  write(
+    destination: string,
+    content: string | ArrayBuffer | Uint8Array | ReadableStream<Uint8Array>,
+  ): Promise<void>;
+
+  /**
+   * Check if a file or directory exists at the given path.
+   *
+   * @param source - The path to check for existence
+   * @returns A Promise that resolves to true if the path exists, false otherwise
+   *
+   * @example
+   * ```typescript
+   * const fileExists = await AlloyHost.exists('./config.json');
+   * if (fileExists) {
+   *   // File exists, safe to read
+   * }
+   * ```
+   */
+  exists(source: string): Promise<boolean>;
+
+  /**
+   * Create a directory at the specified path.
+   *
+   * Creates the directory and any necessary parent directories recursively.
+   * If the directory already exists, this operation succeeds without error.
+   *
+   * @param path - The path of the directory to create
+   * @returns A Promise that resolves when the directory creation is complete
+   *
+   * @example
+   * ```typescript
+   * await AlloyHost.mkdir('./output/nested/directory');
+   * ```
+   */
+  mkdir(path: string): Promise<void>;
+}
+
+/**
+ * Interface for reading file content in different formats.
+ *
+ * This interface provides multiple ways to access the same file content,
+ * allowing consumers to choose the most appropriate format for their use case.
+ */
+export interface AlloyFileInterface {
+  /**
+   * Read the file content as a UTF-8 encoded string.
+   *
+   * @returns A Promise that resolves to the file content as a string
+   *
+   * @example
+   * ```typescript
+   * const file = AlloyHost.read('./config.json');
+   * const jsonString = await file.text();
+   * const config = JSON.parse(jsonString);
+   * ```
+   */
+  text(): Promise<string>;
+
+  /**
+   * Read the file content as an ArrayBuffer.
+   *
+   * Useful for working with binary data or when you need a raw buffer
+   * that can be used with various JavaScript APIs.
+   *
+   * @returns A Promise that resolves to the file content as an ArrayBuffer
+   *
+   * @example
+   * ```typescript
+   * const file = AlloyHost.read('./image.png');
+   * const buffer = await file.arrayBuffer();
+   * ```
+   */
+  arrayBuffer(): Promise<ArrayBuffer>;
+
+  /**
+   * Read the file content as a Uint8Array.
+   *
+   * Convenient for working with binary data when you need direct access
+   * to individual bytes.
+   *
+   * @returns A Promise that resolves to the file content as a Uint8Array
+   *
+   * @example
+   * ```typescript
+   * const file = AlloyHost.read('./binary.dat');
+   * const bytes = await file.bytes();
+   * console.log('First byte:', bytes[0]);
+   * ```
+   */
+  bytes(): Promise<Uint8Array>;
+
+  /**
+   * Get a readable stream of the file content.
+   *
+   * Useful for processing large files without loading the entire content
+   * into memory at once, or for piping data to other streams.
+   *
+   * @returns A ReadableStream that yields Uint8Array chunks of the file content
+   *
+   * @example
+   * ```typescript
+   * const file = AlloyHost.read('./large-file.dat');
+   * const stream = file.stream();
+   *
+   * for await (const chunk of stream) {
+   *   console.log('Received chunk:', chunk);
+   * }
+   * ```
+   */
+  stream(): ReadableStream<Uint8Array>;
+}

package/src/index.browser.ts

@@ -1,2 +1,2 @@
+export * from "./host/alloy-host.browser.js"; // Override writeOutput for browsers
 export * from "./index.js"; // Re-export everything
-export { writeOutput } from "./write-output.browser.js"; // Override writeOutput for browsers

package/src/render.ts

@@ -23,7 +23,7 @@ import {
   Props,
 } from "./runtime/component.js";
 import { IntrinsicElement, isIntrinsicElement } from "./runtime/intrinsic.js";
-import { flushJobs } from "./scheduler.js";
+import { flushJobs, flushJobsAsync } from "./scheduler.js";
 import { trace, TracePhase } from "./tracer.js";
 
 const {
@@ -133,13 +133,22 @@ export interface OutputDirectory {
   contents: (OutputDirectory | OutputFile)[];
 }
 
-export interface OutputFile {
+export interface OutputFileBase {
   kind: "file";
-  contents: string;
   path: string;
+}
+
+export interface CopyOutputFile extends OutputFileBase {
+  sourcePath: string;
+}
+
+export interface ContentOutputFile extends OutputFileBase {
+  contents: string;
   filetype: string;
 }
 
+export type OutputFile = ContentOutputFile | CopyOutputFile;
+
 const nodesToContext = new WeakMap<RenderedTextTree, Context>();
 
 export function getContextForRenderNode(node: RenderedTextTree) {
@@ -181,6 +190,22 @@ export function render(
 ): OutputDirectory {
   const tree = renderTree(children);
   flushJobs();
+  return sourceFilesForTree(tree, options);
+}
+
+export async function renderAsync(
+  children: Children,
+  options?: PrintTreeOptions,
+): Promise<OutputDirectory> {
+  const tree = renderTree(children);
+  await flushJobsAsync();
+  return sourceFilesForTree(tree, options);
+}
+
+export function sourceFilesForTree(
+  tree: RenderedTextTree,
+  options?: PrintTreeOptions,
+): OutputDirectory {
   let rootDirectory: OutputDirectory | undefined = undefined;
 
   // when passing Output, the first render tree child is the Output component.
@@ -234,7 +259,7 @@ export function render(
         );
       }
 
-      const sourceFile: OutputFile = {
+      const sourceFile: ContentOutputFile = {
         kind: "file",
         path: context.meta?.sourceFile.path,
         filetype: context.meta?.sourceFile.filetype,
@@ -254,6 +279,21 @@ export function render(
         }),
       };
 
+      currentDirectory.contents.push(sourceFile);
+    } else if (context.meta?.copyFile) {
+      if (!currentDirectory) {
+        // This shouldn't happen if you're using the Output component.
+        throw new Error(
+          "Copy file doesn't have parent directory. Make sure you have used the Output component.",
+        );
+      }
+
+      const sourceFile: CopyOutputFile = {
+        kind: "file",
+        path: context.meta?.copyFile.path,
+        sourcePath: context.meta?.copyFile.sourcePath,
+      };
+
       currentDirectory.contents.push(sourceFile);
     } else {
       recurse(currentDirectory);
@@ -266,7 +306,6 @@ export function render(
     }
   }
 }
-
 export function renderTree(children: Children) {
   const rootElem: RenderedTextTree = [];
   try {

package/src/resource.ts

@@ -0,0 +1,152 @@
+import { isRef, reactive, Ref } from "@vue/reactivity";
+import { AlloyHost } from "./host/alloy-host.js";
+import { effect } from "./reactivity.js";
+import { trackPromise } from "./scheduler.js";
+
+/**
+ * Represents an external resource fetched asynchronously.
+ */
+export interface Resource<T> {
+  /**
+   * The data if it's been loaded successfully. Null when not yet loaded or
+   * there was an error.
+   */
+  data: T | null;
+
+  /**
+   * Whether the resource is still being fetched.
+   */
+  loading: boolean;
+
+  /**
+   * The error loading the resource, if any.
+   */
+  error: null | Error;
+}
+
+/**
+ * Create a resource that fetches data asynchronously.
+ *
+ * This function has two overloads:
+ * 1. Simple fetcher - fetches data once when the resource is created
+ * 2. Reactive fetcher - fetches data when a reactive source changes
+ *
+ * @example
+ * ```typescript
+ * // Simple usage - fetches data once when created
+ * const userResource = createResource(async () => {
+ *   const response = await fetch('/api/user');
+ *   return response.json();
+ * });
+ *
+ * // Access the resource state
+ * console.log(userResource.loading); // true initially
+ * console.log(userResource.data);    // null initially
+ * console.log(userResource.error);   // null initially
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Reactive usage - fetches data when the ref changes
+ * const userId = ref(1);
+ *
+ * const userResource = createResource(userId, async (id) => {
+ *   const response = await fetch(`/api/user/${id}`);
+ *   return response.json();
+ * });
+ *
+ * // The fetcher will be called automatically when userId changes
+ * userId.value = 2; // This triggers a new fetch with id=2
+ * ```
+ */
+export function createResource<U>(fetcher: () => Promise<U>): Resource<U>;
+/**
+ * Create a resource that fetches data asynchronously based on a reactive source.
+ */
+export function createResource<T, U>(
+  refSource: Ref<T> | (() => T),
+  fetcher: (input: T) => Promise<U>,
+): Resource<U>;
+export function createResource<T, U>(
+  fetcherOrSource: (() => Promise<U>) | Ref<T> | (() => T),
+  maybeFetcher?: (input: T) => Promise<U>,
+): Resource<U> {
+  let getter: Ref<T> | (() => T) | null = null;
+  let fetcher: (() => Promise<U>) | ((input: T) => Promise<U>);
+
+  if (arguments.length === 1) {
+    fetcher = fetcherOrSource as () => Promise<U>;
+  } else {
+    getter = fetcherOrSource as Ref<T> | (() => T);
+    fetcher = maybeFetcher!;
+  }
+
+  const resource: Resource<U> = reactive({
+    data: null,
+    loading: true,
+    error: null,
+  });
+
+  if (!getter) {
+    const promise = (fetcher as () => Promise<U>)();
+    trackPromise(
+      promise
+        .then((result) => {
+          resource.data = result;
+          resource.loading = false;
+        })
+        .catch((error) => {
+          resource.error = error;
+          resource.loading = false;
+        }),
+    );
+  } else {
+    effect(() => {
+      let input: T;
+      if (isRef(getter)) {
+        input = getter.value;
+      } else {
+        input = getter();
+      }
+      const promise = (fetcher as (input: T) => Promise<U>)(input);
+      trackPromise(promise);
+      promise.then(
+        (result) => {
+          resource.data = result;
+          resource.loading = false;
+        },
+        (error) => {
+          resource.error = error;
+          resource.loading = false;
+        },
+      );
+    });
+  }
+
+  return resource;
+}
+
+/**
+ * Create a resource that reads a file from the file system.
+ *
+ * This is a convenience function that creates a resource for reading file content
+ * using the AlloyHost file system API. The file is read as text when the resource
+ * is created.
+ *
+ * @example
+ * ```typescript
+ * // Read a configuration file
+ * const configResource = createFileResource('./config.json');
+ *
+ * // Access the file content
+ * if (!configResource.loading && !configResource.error) {
+ *   const configText = configResource.data; // string content of the file
+ *   const config = JSON.parse(configText);
+ * }
+ * ```
+ */
+export function createFileResource(path: string) {
+  return createResource(() => {
+    return AlloyHost.read(path).text();
+  });
+}

package/src/scheduler.ts

@@ -5,6 +5,7 @@ export interface QueueJob {
 }
 const immediateQueue = new Set<QueueJob>();
 const queue = new Set<QueueJob>();
+const pendingPromises = new Set<Promise<any>>();
 
 export function scheduler(
   jobGetter: () => ReactiveEffectRunner,
@@ -25,11 +26,49 @@ export function queueJob(job: QueueJob, immediate = false) {
   }
 }
 
+/**
+ * Register a promise that the scheduler should wait for during flushJobs.
+ * This is used by async resources to ensure the scheduler waits for their completion.
+ */
+export function trackPromise(promise: Promise<any>) {
+  pendingPromises.add(promise);
+  void promise.finally(() => {
+    pendingPromises.delete(promise);
+  });
+}
+
 export function flushJobs() {
+  // First, run all synchronous jobs
   let job;
   while ((job = takeJob()) !== null) {
     job();
   }
+
+  // If there are no pending promises, we're done
+  if (pendingPromises.size > 0) {
+    throw new Error(
+      "Asynchronous jobs were found but render was called synchronously. Use `asyncRender` instead.",
+    );
+  }
+}
+
+export async function flushJobsAsync() {
+  // Keep running jobs until both the queues are empty and all promises are resolved
+  while (true) {
+    // First, run all synchronous jobs
+    let job;
+    while ((job = takeJob()) !== null) {
+      job();
+    }
+
+    // If there are no pending promises, we're done
+    if (pendingPromises.size === 0) {
+      break;
+    }
+
+    // Wait for all current promises to complete
+    await Promise.allSettled(Array.from(pendingPromises));
+  }
 }
 
 function takeJob() {