sandlot 0.1.3 → 0.2.0

package/src/shared-resources.ts

@@ -1,166 +0,0 @@
-/**
- * Shared resources for sandbox environments.
- *
- * Provides centralized management of expensive shared resources:
- * - TypeScript lib files (~5MB) - loaded once, shared across all sandboxes
- * - esbuild WASM (~10MB) - singleton bundler initialization
- * - Types cache - avoids redundant network fetches when multiple sandboxes
- *   install the same packages
- */
-
-import { fetchAndCacheLibs, getDefaultBrowserLibs } from "./ts-libs";
-import { initBundler } from "./bundler";
-import { InMemoryTypesCache, type TypesCache } from "./packages";
-
-// Re-export for consumers
-export type { TypesCache } from "./packages";
-export { InMemoryTypesCache } from "./packages";
-
-/**
- * Shared resources that can be reused across multiple sandboxes
- */
-export interface SharedResources {
-  /**
-   * Pre-loaded TypeScript lib files for type checking
-   */
-  libFiles: Map<string, string>;
-
-  /**
-   * Promise that resolves when the bundler is ready
-   */
-  bundlerReady: Promise<void>;
-
-  /**
-   * Cache for package type definitions.
-   * Avoids redundant network fetches when multiple sandboxes
-   * install the same packages.
-   */
-  typesCache: TypesCache;
-}
-
-/**
- * Options for creating shared resources
- */
-export interface SharedResourcesOptions {
-  /**
-   * TypeScript libs to load. Defaults to browser libs (ES2020 + DOM).
-   */
-  libs?: string[];
-
-  /**
-   * If true, skip fetching TypeScript libs.
-   * libFiles will be an empty Map.
-   * Default: false
-   */
-  skipLibs?: boolean;
-
-  /**
-   * If true, skip pre-initializing the bundler.
-   * bundlerReady will resolve immediately.
-   * Default: false
-   */
-  skipBundler?: boolean;
-}
-
-/**
- * Create a new SharedResources instance.
- *
- * Use this when you want to manage resource lifecycle explicitly,
- * or when you need custom libs configuration.
- *
- * @example
- * ```ts
- * // Create resources with custom libs
- * const resources = await createSharedResources({
- *   libs: ['es2022', 'dom', 'webworker'],
- * });
- *
- * // Pass to sandbox creation
- * const sandbox = await createSandbox({
- *   resources,
- *   fsOptions: { ... },
- * });
- * ```
- */
-export async function createSharedResources(
-  options: SharedResourcesOptions = {}
-): Promise<SharedResources> {
-  const { libs = getDefaultBrowserLibs(), skipLibs = false, skipBundler = false } = options;
-
-  // Start both in parallel
-  const libsPromise = skipLibs
-    ? Promise.resolve(new Map<string, string>())
-    : fetchAndCacheLibs(libs);
-
-  const bundlerPromise = skipBundler ? Promise.resolve() : initBundler();
-
-  // Create types cache (synchronous, just an in-memory Map)
-  const typesCache = new InMemoryTypesCache();
-
-  // Wait for async initialization
-  const [libFiles] = await Promise.all([libsPromise, bundlerPromise]);
-
-  return {
-    libFiles,
-    bundlerReady: Promise.resolve(), // Already initialized
-    typesCache,
-  };
-}
-
-// ============ Module-level Singleton ============
-
-/**
- * Module-level singleton for default shared resources.
- * Used by createSandbox() when no resources are provided.
- */
-let defaultResourcesInstance: SharedResources | null = null;
-let defaultResourcesPromise: Promise<SharedResources> | null = null;
-
-/**
- * Get the default shared resources singleton.
- *
- * Loads resources once and returns the same instance for all callers.
- * This is the recommended way to get shared resources for most use cases.
- *
- * @example
- * ```ts
- * // Get default resources (creates on first call)
- * const resources = await getDefaultResources();
- *
- * // Create multiple sandboxes sharing the same resources
- * const sandbox1 = await createSandbox({ resources, ... });
- * const sandbox2 = await createSandbox({ resources, ... });
- * ```
- */
-export async function getDefaultResources(): Promise<SharedResources> {
-  if (defaultResourcesInstance) {
-    return defaultResourcesInstance;
-  }
-
-  if (!defaultResourcesPromise) {
-    defaultResourcesPromise = createSharedResources().then((resources) => {
-      defaultResourcesInstance = resources;
-      return resources;
-    });
-  }
-
-  return defaultResourcesPromise;
-}
-
-/**
- * Clear the default resources singleton (for testing).
- *
- * Note: This doesn't unload the bundler WASM - that stays in memory
- * until page reload. This only clears the cached lib files reference.
- */
-export function clearDefaultResources(): void {
-  defaultResourcesInstance = null;
-  defaultResourcesPromise = null;
-}
-
-/**
- * Check if the default resources have been initialized.
- */
-export function hasDefaultResources(): boolean {
-  return defaultResourcesInstance !== null;
-}

package/src/ts-libs.ts

@@ -1,320 +0,0 @@
-/**
- * TypeScript standard library fetcher and cache.
- *
- * Fetches TypeScript's lib.*.d.ts files from jsDelivr CDN and caches
- * them in IndexedDB for reuse. These files provide types for built-in
- * JavaScript APIs (Array, Number, String) and browser APIs (console, window, document).
- */
-
-/**
- * TypeScript version to fetch libs for.
- * MUST match the version in package.json dependencies.
- */
-const TS_VERSION = "5.9.3";
-
-/**
- * CDN base URL for TypeScript lib files
- */
-const CDN_BASE = `https://cdn.jsdelivr.net/npm/typescript@${TS_VERSION}/lib`;
-
-/**
- * IndexedDB database name for lib cache
- */
-const DB_NAME = "ts-lib-cache";
-const DB_VERSION = 1;
-const STORE_NAME = "libs";
-
-/**
- * Default libs for browser environment with ES2020 target.
- * These provide types for console, DOM APIs, and modern JS features.
- */
-export function getDefaultBrowserLibs(): string[] {
-  return ["es2020", "dom", "dom.iterable"];
-}
-
-/**
- * Parse `/// <reference lib="..." />` directives from a lib file.
- * These directives indicate dependencies on other lib files.
- *
- * @param content - The content of a lib.*.d.ts file
- * @returns Array of lib names referenced (without "lib." prefix or ".d.ts" suffix)
- */
-export function parseLibReferences(content: string): string[] {
-  const refs: string[] = [];
-  const regex = /\/\/\/\s*<reference\s+lib="([^"]+)"\s*\/>/g;
-  let match;
-
-  while ((match = regex.exec(content)) !== null) {
-    if (match[1]) {
-      refs.push(match[1]);
-    }
-  }
-
-  return refs;
-}
-
-/**
- * Convert a lib name to its filename.
- * e.g., "es2020" -> "lib.es2020.d.ts"
- */
-export function libNameToFileName(name: string): string {
-  return `lib.${name}.d.ts`;
-}
-
-/**
- * Extract lib name from a file path.
- * e.g., "/node_modules/typescript/lib/lib.es2020.d.ts" -> "es2020"
- *       "lib.dom.d.ts" -> "dom"
- */
-export function extractLibName(filePath: string): string | null {
-  const match = filePath.match(/lib\.([^/]+)\.d\.ts$/);
-  return match?.[1] ?? null;
-}
-
-/**
- * Fetch a single lib file from the CDN.
- *
- * @param name - The lib name (e.g., "es2020", "dom")
- * @returns The content of the lib file
- * @throws Error if the fetch fails
- */
-export async function fetchLibFile(name: string): Promise<string> {
-  const fileName = libNameToFileName(name);
-  const url = `${CDN_BASE}/${fileName}`;
-
-  const response = await fetch(url);
-  if (!response.ok) {
-    throw new Error(`Failed to fetch ${url}: ${response.status} ${response.statusText}`);
-  }
-
-  return response.text();
-}
-
-/**
- * Recursively fetch all lib files needed for the given libs.
- * Parses `/// <reference lib="..." />` directives and fetches dependencies.
- *
- * @param libs - Initial lib names to fetch (e.g., ["es2020", "dom"])
- * @returns Map of lib name to content
- */
-export async function fetchAllLibs(libs: string[]): Promise<Map<string, string>> {
-  const result = new Map<string, string>();
-  const pending = new Set<string>(libs);
-  const fetched = new Set<string>();
-
-  while (pending.size > 0) {
-    // Get next batch of libs to fetch
-    const batch = Array.from(pending);
-    pending.clear();
-
-    // Fetch all in parallel
-    const results = await Promise.all(
-      batch.map(async (name) => {
-        if (fetched.has(name)) {
-          return { name, content: null };
-        }
-        fetched.add(name);
-
-        try {
-          const content = await fetchLibFile(name);
-          return { name, content };
-        } catch (err) {
-          console.warn(`Failed to fetch lib.${name}.d.ts:`, err);
-          return { name, content: null };
-        }
-      })
-    );
-
-    // Process results and find new dependencies
-    for (const { name, content } of results) {
-      if (content === null) continue;
-
-      result.set(name, content);
-
-      // Parse references and add unfetched ones to pending
-      const refs = parseLibReferences(content);
-      for (const ref of refs) {
-        if (!fetched.has(ref) && !pending.has(ref)) {
-          pending.add(ref);
-        }
-      }
-    }
-  }
-
-  return result;
-}
-
-/**
- * Open the IndexedDB database for lib caching.
- */
-async function openDatabase(): Promise<IDBDatabase> {
-  return new Promise((resolve, reject) => {
-    const request = indexedDB.open(DB_NAME, DB_VERSION);
-
-    request.onerror = () => reject(request.error);
-    request.onsuccess = () => resolve(request.result);
-
-    request.onupgradeneeded = (event) => {
-      const db = (event.target as IDBOpenDBRequest).result;
-      if (!db.objectStoreNames.contains(STORE_NAME)) {
-        db.createObjectStore(STORE_NAME);
-      }
-    };
-  });
-}
-
-/**
- * Promisify an IDBRequest
- */
-function promisifyRequest<T>(request: IDBRequest<T>): Promise<T> {
-  return new Promise((resolve, reject) => {
-    request.onsuccess = () => resolve(request.result);
-    request.onerror = () => reject(request.error);
-  });
-}
-
-/**
- * Cache key for the current TypeScript version
- */
-function getCacheKey(): string {
-  return `libs-${TS_VERSION}`;
-}
-
-/**
- * Serializable format for storing libs in IndexedDB
- */
-interface CachedLibs {
-  version: string;
-  timestamp: number;
-  libs: Record<string, string>;
-}
-
-/**
- * LibCache provides IndexedDB-backed caching for TypeScript lib files.
- *
- * Usage:
- * ```ts
- * const cache = await LibCache.create();
- * const libs = await cache.getOrFetch(getDefaultBrowserLibs());
- * ```
- */
-export class LibCache {
-  private db: IDBDatabase;
-
-  private constructor(db: IDBDatabase) {
-    this.db = db;
-  }
-
-  /**
-   * Create and initialize a LibCache instance.
-   */
-  static async create(): Promise<LibCache> {
-    const db = await openDatabase();
-    return new LibCache(db);
-  }
-
-  /**
-   * Get cached libs if available, otherwise fetch from CDN and cache.
-   *
-   * @param libs - Lib names to fetch (e.g., ["es2020", "dom"])
-   * @returns Map of lib name to content (includes all transitive dependencies)
-   */
-  async getOrFetch(libs: string[]): Promise<Map<string, string>> {
-    // Try to get from cache first
-    const cached = await this.get();
-    if (cached) {
-      // Verify all requested libs are in cache
-      const missing = libs.filter((lib) => !cached.has(lib));
-      if (missing.length === 0) {
-        return cached;
-      }
-      // Some libs missing, fetch all and update cache
-      console.log(`Cache missing libs: ${missing.join(", ")}, fetching all...`);
-    }
-
-    // Fetch from CDN
-    console.log(`Fetching TypeScript libs from CDN: ${libs.join(", ")}...`);
-    const fetched = await fetchAllLibs(libs);
-    console.log(`Fetched ${fetched.size} lib files`);
-
-    // Cache the results
-    await this.set(fetched);
-
-    return fetched;
-  }
-
-  /**
-   * Get cached libs if available.
-   */
-  async get(): Promise<Map<string, string> | null> {
-    const tx = this.db.transaction(STORE_NAME, "readonly");
-    const store = tx.objectStore(STORE_NAME);
-    const key = getCacheKey();
-
-    const cached = await promisifyRequest<CachedLibs | undefined>(store.get(key));
-    if (!cached) {
-      return null;
-    }
-
-    // Verify version matches
-    if (cached.version !== TS_VERSION) {
-      console.log(`Cache version mismatch: ${cached.version} vs ${TS_VERSION}`);
-      return null;
-    }
-
-    return new Map(Object.entries(cached.libs));
-  }
-
-  /**
-   * Store libs in the cache.
-   */
-  async set(libs: Map<string, string>): Promise<void> {
-    const tx = this.db.transaction(STORE_NAME, "readwrite");
-    const store = tx.objectStore(STORE_NAME);
-    const key = getCacheKey();
-
-    const cached: CachedLibs = {
-      version: TS_VERSION,
-      timestamp: Date.now(),
-      libs: Object.fromEntries(libs),
-    };
-
-    await promisifyRequest(store.put(cached, key));
-  }
-
-  /**
-   * Clear all cached libs.
-   */
-  async clear(): Promise<void> {
-    const tx = this.db.transaction(STORE_NAME, "readwrite");
-    const store = tx.objectStore(STORE_NAME);
-    await promisifyRequest(store.clear());
-  }
-
-  /**
-   * Close the database connection.
-   */
-  close(): void {
-    this.db.close();
-  }
-}
-
-/**
- * Convenience function to fetch and cache libs in one call.
- * Creates a temporary LibCache, fetches libs, and returns the result.
- *
- * For repeated use, prefer creating a LibCache instance directly.
- *
- * @param libs - Lib names to fetch (defaults to getDefaultBrowserLibs())
- * @returns Map of lib name to content
- */
-export async function fetchAndCacheLibs(
-  libs: string[] = getDefaultBrowserLibs()
-): Promise<Map<string, string>> {
-  const cache = await LibCache.create();
-  try {
-    return await cache.getOrFetch(libs);
-  } finally {
-    cache.close();
-  }
-}