@vltpkg/vsr 0.2.0 → 0.2.2

package/test/waituntil-correct.test.js

@@ -1,208 +0,0 @@
-import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
-
-/**
- * This test correctly demonstrates Cloudflare's waitUntil API behavior
- * by properly simulating how background tasks are queued and executed.
- */
-describe('Cloudflare waitUntil Pattern', () => {
-  /**
-   * The key issue with the waitUntil API is that when using an IIFE, it executes immediately
-   * before waitUntil gets the resulting promise:
-   *
-   * c.waitUntil((async () => { ... })());  <-- runs immediately!
-   *
-   * To simulate properly in tests, we need to:
-   * 1. Store the function reference, not the promise
-   * 2. Execute the function only when we want to run background tasks
-   */
-
-  // Simulate the Cloudflare Worker environment
-  function createCloudflareEnvironment() {
-    // Queue to store background task functions
-    const backgroundTaskFns = [];
-
-    // Execution context with waitUntil method
-    const executionCtx = {
-      waitUntil: vi.fn((promise) => {
-        // Instead of accepting the promise, we'll wrap it
-        // This stops the execution until we explicitly run it
-        const promiseCreator = () => promise;
-        backgroundTaskFns.push(promiseCreator);
-      })
-    };
-
-    // Function to run all queued background tasks
-    const runBackgroundTasks = async () => {
-      const tasks = [...backgroundTaskFns];
-      backgroundTaskFns.length = 0;
-
-      for (const taskFn of tasks) {
-        try {
-          await taskFn();
-        } catch (error) {
-          console.error('Background task error:', error);
-        }
-      }
-    };
-
-    return {
-      executionCtx,
-      runBackgroundTasks,
-      backgroundTaskFns
-    };
-  }
-
-  it('should run the main handler first, then background tasks', async () => {
-    // Setup
-    const { executionCtx, runBackgroundTasks, backgroundTaskFns } = createCloudflareEnvironment();
-
-    // Track execution order
-    const executionOrder = [];
-    let backgroundRan = false;
-
-    // Handler function (simulates a Cloudflare Worker)
-    async function handler() {
-      executionOrder.push('main-start');
-
-      // Queue a background task - this is how it's done in Cloudflare
-      executionCtx.waitUntil(new Promise((resolve) => {
-        const bgTask = () => {
-          executionOrder.push('background');
-          backgroundRan = true;
-          resolve();
-        };
-
-        // Store the function reference so we can call it later
-        // In real code, this would start executing immediately
-        // but in our mock, we'll delay it
-        setTimeout(bgTask, 0);
-      }));
-
-      executionOrder.push('main-end');
-
-      return { status: 'success' };
-    }
-
-    // Execute the handler
-    const result = await handler();
-
-    // Verify:
-    // 1. The main handler completed
-    expect(result).toEqual({ status: 'success' });
-
-    // 2. Main handler started and completed before any background tasks ran
-    expect(executionOrder).toEqual(['main-start', 'main-end']);
-    expect(backgroundRan).toBe(false);
-
-    // 3. Background task was queued but not executed yet
-    expect(backgroundTaskFns.length).toBe(1);
-
-    // Now run the background tasks
-    await runBackgroundTasks();
-
-    // 4. Verify the execution order after background tasks were run
-    expect(executionOrder).toEqual(['main-start', 'main-end', 'background']);
-    expect(backgroundRan).toBe(true);
-  });
-
-  it('should implement the stale-while-revalidate caching pattern', async () => {
-    // Setup
-    const { executionCtx, runBackgroundTasks, backgroundTaskFns } = createCloudflareEnvironment();
-
-    // Mock cache with stale data
-    const cache = {
-      data: {
-        value: 'stale-data',
-        timestamp: Date.now() - 3600000 // 1 hour old (stale)
-      },
-      get: vi.fn(function() { return this.data; }),
-      set: vi.fn(function(newData) { this.data = newData; })
-    };
-
-    // Mock external API
-    const fetchFromUpstream = vi.fn().mockResolvedValue('fresh-data');
-
-    // Track execution
-    const executionOrder = [];
-    let refreshStarted = false;
-    let refreshCompleted = false;
-
-    // Handler function implementing stale-while-revalidate
-    async function handleRequest() {
-      executionOrder.push('handler-start');
-
-      // Get data from cache
-      const cachedData = cache.get();
-
-      // Check if data is stale (older than 5 minutes)
-      const isStale = Date.now() - cachedData.timestamp > 5 * 60 * 1000;
-
-      if (isStale) {
-        // Queue background refresh without waiting
-        executionCtx.waitUntil(new Promise(async (resolve) => {
-          // In a real implementation this would run immediately
-          // In our test, we'll run it only when specifically requested
-          const bgRefresh = async () => {
-            refreshStarted = true;
-            executionOrder.push('refresh-start');
-            const freshData = await fetchFromUpstream();
-            cache.set({
-              value: freshData,
-              timestamp: Date.now()
-            });
-            executionOrder.push('refresh-end');
-            refreshCompleted = true;
-            resolve();
-          };
-
-          // Don't call bgRefresh() here - we'll call it during runBackgroundTasks
-          setTimeout(bgRefresh, 0);
-        }));
-      }
-
-      // Return cached data immediately
-      executionOrder.push('handler-end');
-      return cachedData.value;
-    }
-
-    // Execute the handler
-    const result = await handleRequest();
-
-    // Verify:
-    // 1. We got the stale data immediately
-    expect(result).toBe('stale-data');
-
-    // 2. Handler completed without waiting for refresh
-    expect(executionOrder).toEqual(['handler-start', 'handler-end']);
-    expect(refreshStarted).toBe(false);
-    expect(refreshCompleted).toBe(false);
-
-    // 3. The upstream API was not called yet
-    expect(fetchFromUpstream).not.toHaveBeenCalled();
-
-    // 4. Background task was queued
-    expect(backgroundTaskFns.length).toBe(1);
-
-    // Now run the background tasks
-    await runBackgroundTasks();
-
-    // 5. Verify the API was called during background refresh
-    expect(fetchFromUpstream).toHaveBeenCalled();
-    expect(refreshStarted).toBe(true);
-    expect(refreshCompleted).toBe(true);
-
-    // 6. Cache was updated with fresh data
-    expect(cache.set).toHaveBeenCalledWith({
-      value: 'fresh-data',
-      timestamp: expect.any(Number)
-    });
-
-    // 7. Execution order shows background refresh happened after handler
-    expect(executionOrder).toEqual([
-      'handler-start',
-      'handler-end',
-      'refresh-start',
-      'refresh-end'
-    ]);
-  });
-});

package/test/waituntil-demo.test.js

@@ -1,138 +0,0 @@
-import { describe, it, expect, vi } from 'vitest';
-
-/**
- * This is a minimalist test to demonstrate the waitUntil API in Cloudflare Workers.
- * The waitUntil API allows a Worker to return a response to the client immediately
- * while continuing to perform work in the background.
- *
- * This is especially useful for caching scenarios where:
- * 1. We want to return cached data to the client as quickly as possible
- * 2. We may need to refresh that cache in the background without blocking the response
- */
-describe('waitUntil API', () => {
-  it('allows background work to continue after a response is sent', async () => {
-    // In a Cloudflare Worker, the execution context has a waitUntil method
-    // Here we create a mock of that context
-    let backgroundWorkCompleted = false;
-
-    const executionContext = {
-      // This mock implementation runs the task after a short delay
-      waitUntil: (promise) => {
-        // In a real Worker, this would track the promise and ensure
-        // the Worker doesn't terminate until all promises are resolved
-        setTimeout(async () => {
-          try {
-            await promise;
-          } catch (error) {
-            console.error('Background task error:', error);
-          }
-        }, 0);
-
-        // waitUntil itself returns immediately
-        return Promise.resolve();
-      }
-    };
-
-    // Record start time
-    const startTime = Date.now();
-
-    // This is how you use waitUntil in a real worker handler:
-    async function handleRequest(request, env, ctx) {
-      // Do some quick work and prepare a response
-      const quickData = { message: "Here's your fast response!" };
-
-      // Queue up some slow work to happen in the background
-      ctx.waitUntil((async () => {
-        // Simulate slow work (e.g., refreshing a cache, calling external API)
-        await new Promise(resolve => setTimeout(resolve, 500));
-        backgroundWorkCompleted = true;
-      })());
-
-      // Return the response immediately, without waiting for background work
-      return quickData;
-    }
-
-    // Call our handler with the mock execution context
-    const response = await handleRequest({}, {}, executionContext);
-
-    // Measure response time
-    const responseTime = Date.now() - startTime;
-
-    // VERIFY:
-
-    // 1. We got a quick response (much less than 500ms)
-    expect(response).toEqual({ message: "Here's your fast response!" });
-    expect(responseTime).toBeLessThan(100);
-
-    // 2. Background work has NOT completed yet
-    expect(backgroundWorkCompleted).toBe(false);
-
-    // 3. Wait for background work and verify it completes
-    await new Promise(resolve => setTimeout(resolve, 600));
-    expect(backgroundWorkCompleted).toBe(true);
-  });
-
-  /**
-   * Conceptual demonstration of the caching pattern
-   */
-  it('explains the stale-while-revalidate caching pattern', async () => {
-    // This test explains the concept without actually testing code
-
-    // 1. Mock a waitUntil function
-    const waitUntil = vi.fn();
-
-    // 2. Mock a database record with stale cached data
-    const mockCacheResponse = {
-      data: { version: '1.0.0' },
-      updated: Date.now() - 3600000 // 1 hour old (stale)
-    };
-
-    // 3. Log what would happen in an actual implementation
-    console.log('In a real implementation, a stale-while-revalidate caching strategy would:');
-    console.log('1. Check if data exists in cache');
-    console.log('2. If it exists but is stale, queue a background task to refresh it');
-    console.log('3. Return the cached data immediately, without waiting for the refresh');
-
-    // 4. Show what the implementation pattern looks like conceptually
-    function conceptualImplementationPattern() {
-      // Simulate the pattern without actually executing code
-      const code = `
-async function getDataWithBackgroundRefresh(key, db, ctx) {
-  // Get data from cache
-  const cached = await db.getData(key);
-
-  if (cached) {
-    // Check if cache is stale
-    const isStale = Date.now() - cached.updated > FIVE_MINUTES;
-
-    if (isStale) {
-      // Queue background refresh WITHOUT awaiting it
-      ctx.waitUntil((async () => {
-        const fresh = await fetchFromUpstream(key);
-        await db.saveToCache(key, fresh);
-      })());
-    }
-
-    // Return cached data immediately
-    return cached.data;
-  }
-
-  // If not in cache, fetch directly
-  const data = await fetchFromUpstream(key);
-  await db.saveToCache(key, data);
-  return data;
-}`;
-      return code;
-    }
-
-    // 5. Verify the explanation was provided
-    expect(conceptualImplementationPattern()).toContain('ctx.waitUntil');
-    expect(conceptualImplementationPattern()).toContain('return cached.data');
-
-    // Note: In a real implementation, we would:
-    // 1. Return stale cached data immediately
-    // 2. In parallel, refresh the cache in the background
-    // 3. The client gets a fast response with slightly stale data
-    // 4. The next client gets fresh data
-  });
-});

package/test/waituntil-readme.md

@@ -1,113 +0,0 @@
-# Testing Cloudflare Workers' `waitUntil` API
-
-## Background
-
-Cloudflare Workers have a special `waitUntil` API that allows background tasks to continue running after a response has been sent. This is particularly useful for implementing caching patterns like "stale-while-revalidate" where:
-
-1. We return cached data to the client immediately
-2. We refresh stale data in the background
-3. The next client gets the fresh data
-
-## The Challenge with Testing
-
-Testing `waitUntil` behavior can be tricky because:
-
-1. In real Cloudflare Workers, the main handler function completes and returns a response, *then* the background tasks run.
-2. In a test environment, we need to simulate this behavior correctly.
-3. Most test implementations incorrectly execute background tasks immediately.
-
-## Common Testing Mistake
-
-The most common mistake when testing `waitUntil` is to use an Immediately Invoked Function Expression (IIFE) that gets executed before `waitUntil` can store it:
-
-```javascript
-// PROBLEMATIC: This will execute the fetch immediately, before waitUntil gets it
-ctx.waitUntil((async () => {
-  const freshData = await fetch('https://api.example.com/data');
-  return freshData;
-})());
-```
-
-JavaScript evaluates function arguments before passing them to functions, so the IIFE executes immediately, and only its *resulting Promise* is passed to `waitUntil`.
-
-## Correct Testing Approach
-
-The correct way to test `waitUntil` is to simulate the Cloudflare Worker runtime:
-
-```javascript
-function simulateCloudflareWorker(handler) {
-  const bgTasks = [];
-  const executionCtx = {
-    waitUntil: (promise) => {
-      bgTasks.push(promise);
-    }
-  };
-
-  return async () => {
-    // Run the main handler first to completion
-    const response = await handler(executionCtx);
-
-    // Then run background tasks
-    for (const task of bgTasks) {
-      await task;
-    }
-
-    return response;
-  };
-}
-```
-
-This approach:
-1. Collects promises passed to `waitUntil` without executing them
-2. Completes the main handler function first
-3. Only then executes the background tasks
-
-## Test Files in This Directory
-
-1. `waituntil-demo.test.js` - A conceptual explanation of how `waitUntil` works
-2. `cloudflare-waituntil.test.js` - A test that correctly simulates the Cloudflare Worker runtime
-
-## Best Practices for Testing `waitUntil`
-
-1. **Use a task queue:** Collect tasks to be executed later, don't execute them immediately.
-2. **Complete the main handler first:** Make sure the main handler completes before running background tasks.
-3. **Avoid relying on mock implementations:** Most mock implementations don't correctly simulate the timing behavior.
-4. **Test the end state:** Verify that background tasks eventually complete, not when they run.
-
-## Implementing the Pattern in Your Code
-
-When implementing the stale-while-revalidate pattern:
-
-```javascript
-async function getDataWithBackgroundRefresh(c) {
-  // Get data from cache
-  const cached = await c.db.getData(key);
-
-  if (cached) {
-    // Check if cache is stale
-    const isStale = Date.now() - cached.timestamp > FIVE_MINUTES;
-
-    if (isStale) {
-      // Queue background refresh
-      c.executionCtx.waitUntil((async () => {
-        try {
-          const fresh = await fetch('https://upstream.api/data');
-          await c.db.saveData(fresh);
-        } catch (err) {
-          console.error('Background refresh failed:', err);
-        }
-      })());
-    }
-
-    // Return cached data immediately
-    return cached.data;
-  }
-
-  // If not in cache, fetch directly
-  const data = await fetch('https://upstream.api/data');
-  await c.db.saveData(data);
-  return data;
-}
-```
-
-This pattern ensures users get a fast response while keeping your data fresh.