@nicnocquee/dataqueue 1.22.0 → 1.24.0

package/src/handler-validation.test.ts

@@ -0,0 +1,414 @@
+import { describe, expect, it } from 'vitest';
+import {
+  validateHandlerSerializable,
+  testHandlerSerialization,
+} from './handler-validation.js';
+import { JobHandler } from './types.js';
+
+// Define test payload map
+interface TestPayloadMap {
+  simple: { data: string };
+  complex: { id: number; name: string };
+}
+
+describe('validateHandlerSerializable', () => {
+  it('should validate a simple standalone handler as serializable', () => {
+    const handler: JobHandler<TestPayloadMap, 'simple'> = async (
+      payload,
+      signal,
+    ) => {
+      await Promise.resolve();
+    };
+
+    const result = validateHandlerSerializable(handler, 'simple');
+    expect(result.isSerializable).toBe(true);
+    expect(result.error).toBeUndefined();
+  });
+
+  it('should validate a handler with local variables as serializable', () => {
+    const handler: JobHandler<TestPayloadMap, 'simple'> = async (
+      payload,
+      signal,
+    ) => {
+      const localVar = 'test';
+      const anotherVar = 123;
+      await Promise.resolve(localVar + anotherVar);
+    };
+
+    const result = validateHandlerSerializable(handler, 'simple');
+    expect(result.isSerializable).toBe(true);
+    expect(result.error).toBeUndefined();
+  });
+
+  it('should validate a handler that imports dependencies inside as serializable', () => {
+    const handler: JobHandler<TestPayloadMap, 'simple'> = async (
+      payload,
+      signal,
+    ) => {
+      const { default: something } = await import('path');
+      await Promise.resolve();
+    };
+
+    const result = validateHandlerSerializable(handler, 'simple');
+    expect(result.isSerializable).toBe(true);
+    expect(result.error).toBeUndefined();
+  });
+
+  it('should reject a handler that uses "this" context', () => {
+    // Create a handler that uses 'this' by mocking toString to show 'this.' in the body
+    const handler: JobHandler<TestPayloadMap, 'simple'> = async (
+      payload,
+      signal,
+    ) => {
+      await Promise.resolve();
+    };
+
+    // Mock toString to simulate a handler that uses 'this'
+    const originalToString = handler.toString.bind(handler);
+    (handler as any).toString = () =>
+      'async (payload) => { return this.value; }';
+
+    const result = validateHandlerSerializable(handler, 'simple');
+    expect(result.isSerializable).toBe(false);
+    expect(result.error).toContain("uses 'this' context");
+    expect(result.error).toContain('cannot be serialized');
+
+    // Restore
+    (handler as any).toString = originalToString;
+  });
+
+  it('should reject a handler with native code', () => {
+    // Create a handler that might contain native code
+    // This is tricky to test directly, but we can test the detection logic
+    const handler: JobHandler<TestPayloadMap, 'simple'> = async (
+      payload,
+      signal,
+    ) => {
+      // Native methods like Array.prototype methods might show as native code
+      Array.isArray([]);
+      await Promise.resolve();
+    };
+
+    // Mock toString to return native code indicator
+    const originalToString = handler.toString.bind(handler);
+    (handler as any).toString = () => '[native code]';
+
+    const result = validateHandlerSerializable(handler, 'simple');
+    expect(result.isSerializable).toBe(false);
+    expect(result.error).toContain('contains native code');
+    expect(result.error).toContain('cannot be serialized');
+
+    // Restore
+    (handler as any).toString = originalToString;
+  });
+
+  it('should reject a handler that cannot be parsed', () => {
+    // Create a handler with invalid syntax when stringified
+    const handler: JobHandler<TestPayloadMap, 'simple'> = async (
+      payload,
+      signal,
+    ) => {
+      await Promise.resolve();
+    };
+
+    // Mock toString to return invalid function code
+    const originalToString = handler.toString.bind(handler);
+    (handler as any).toString = () =>
+      'async (payload) => { invalid syntax here !@#$';
+
+    const result = validateHandlerSerializable(handler, 'simple');
+    expect(result.isSerializable).toBe(false);
+    expect(result.error).toContain('cannot be serialized');
+
+    // Restore
+    (handler as any).toString = originalToString;
+  });
+
+  it('should warn about potential closures but still mark as serializable', () => {
+    // This handler has a pattern that might indicate closures
+    // but the validation can't be 100% sure, so it warns
+    const handler: JobHandler<TestPayloadMap, 'simple'> = async (
+      payload,
+      signal,
+    ) => {
+      const local = 'test';
+      await Promise.resolve(local);
+    };
+
+    const result = validateHandlerSerializable(handler, 'simple');
+    // The current implementation might return a warning, but it's still considered serializable
+    // This test checks the behavior - if it warns, that's OK
+    if (result.error) {
+      expect(result.error).toContain('Warning');
+      expect(result.error).toContain('may have closures');
+    }
+  });
+
+  it('should work without jobType parameter', () => {
+    const handler: JobHandler<TestPayloadMap, 'simple'> = async (
+      payload,
+      signal,
+    ) => {
+      await Promise.resolve();
+    };
+
+    const result = validateHandlerSerializable(handler);
+    expect(result.isSerializable).toBe(true);
+  });
+
+  it('should provide helpful error messages with jobType', () => {
+    const handler: JobHandler<TestPayloadMap, 'simple'> = async (
+      payload,
+      signal,
+    ) => {
+      await Promise.resolve();
+    };
+
+    // Mock toString to simulate a handler that uses 'this'
+    const originalToString = handler.toString.bind(handler);
+    (handler as any).toString = () =>
+      'async (payload) => { return this.value; }';
+
+    const result = validateHandlerSerializable(handler, 'myJobType');
+    expect(result.isSerializable).toBe(false);
+    expect(result.error).toContain('myJobType');
+    expect(result.error).toContain("uses 'this' context");
+
+    // Restore
+    (handler as any).toString = originalToString;
+  });
+
+  it('should handle errors during validation gracefully', () => {
+    const handler: JobHandler<TestPayloadMap, 'simple'> = async (
+      payload,
+      signal,
+    ) => {
+      await Promise.resolve();
+    };
+
+    // Mock toString to throw an error
+    const originalToString = handler.toString.bind(handler);
+    (handler as any).toString = () => {
+      throw new Error('toString failed');
+    };
+
+    const result = validateHandlerSerializable(handler, 'simple');
+    expect(result.isSerializable).toBe(false);
+    expect(result.error).toContain('Failed to validate handler serialization');
+
+    // Restore
+    (handler as any).toString = originalToString;
+  });
+});
+
+describe('testHandlerSerialization', () => {
+  it('should validate a simple handler as serializable', async () => {
+    const handler: JobHandler<TestPayloadMap, 'simple'> = async (
+      payload,
+      signal,
+    ) => {
+      await Promise.resolve();
+    };
+
+    const result = await testHandlerSerialization(handler, 'simple');
+    expect(result.isSerializable).toBe(true);
+    expect(result.error).toBeUndefined();
+  });
+
+  it('should reject a handler that fails basic validation', async () => {
+    const handler: JobHandler<TestPayloadMap, 'simple'> = async (
+      payload,
+      signal,
+    ) => {
+      await Promise.resolve();
+    };
+
+    // Mock toString to simulate a handler that uses 'this'
+    const originalToString = handler.toString.bind(handler);
+    (handler as any).toString = () =>
+      'async (payload) => { return this.value; }';
+
+    const result = await testHandlerSerialization(handler, 'simple');
+    expect(result.isSerializable).toBe(false);
+    expect(result.error).toContain("uses 'this' context");
+
+    // Restore
+    (handler as any).toString = originalToString;
+  });
+
+  it('should handle handlers that complete quickly', async () => {
+    const handler: JobHandler<TestPayloadMap, 'simple'> = async (
+      payload,
+      signal,
+    ) => {
+      return Promise.resolve();
+    };
+
+    const result = await testHandlerSerialization(handler, 'simple');
+    expect(result.isSerializable).toBe(true);
+  });
+
+  it('should handle handlers that take time but still validate as serializable', async () => {
+    const handler: JobHandler<TestPayloadMap, 'simple'> = async (
+      payload,
+      signal,
+    ) => {
+      // Handler that takes longer than the test timeout (100ms)
+      await new Promise((resolve) => setTimeout(resolve, 200));
+    };
+
+    const result = await testHandlerSerialization(handler, 'simple');
+    // Should still be considered serializable even if it times out during test
+    expect(result.isSerializable).toBe(true);
+  });
+
+  it('should handle handlers that throw errors during execution', async () => {
+    const handler: JobHandler<TestPayloadMap, 'simple'> = async (
+      payload,
+      signal,
+    ) => {
+      throw new Error('Handler error');
+    };
+
+    const result = await testHandlerSerialization(handler, 'simple');
+    // Execution errors are OK - we just want to know if it can be deserialized
+    // The handler is still considered serializable
+    expect(result.isSerializable).toBe(true);
+  });
+
+  it('should handle serialization errors', async () => {
+    const handler: JobHandler<TestPayloadMap, 'simple'> = async (
+      payload,
+      signal,
+    ) => {
+      await Promise.resolve();
+    };
+
+    // Mock toString to return invalid code
+    const originalToString = handler.toString.bind(handler);
+    (handler as any).toString = () => 'invalid function code !@#$';
+
+    const result = await testHandlerSerialization(handler, 'simple');
+    expect(result.isSerializable).toBe(false);
+    expect(result.error).toBeDefined();
+
+    // Restore
+    (handler as any).toString = originalToString;
+  });
+
+  it('should work without jobType parameter', async () => {
+    const handler: JobHandler<TestPayloadMap, 'simple'> = async (
+      payload,
+      signal,
+    ) => {
+      await Promise.resolve();
+    };
+
+    const result = await testHandlerSerialization(handler);
+    expect(result.isSerializable).toBe(true);
+  });
+
+  it('should handle complex payload types', async () => {
+    const handler: JobHandler<TestPayloadMap, 'complex'> = async (
+      payload,
+      signal,
+    ) => {
+      const { id, name } = payload;
+      await Promise.resolve(`${id}: ${name}`);
+    };
+
+    const result = await testHandlerSerialization(handler, 'complex');
+    expect(result.isSerializable).toBe(true);
+  });
+
+  it('should handle handlers that use signal parameter', async () => {
+    const handler: JobHandler<TestPayloadMap, 'simple'> = async (
+      payload,
+      signal,
+    ) => {
+      if (signal.aborted) {
+        return;
+      }
+      await Promise.resolve();
+    };
+
+    const result = await testHandlerSerialization(handler, 'simple');
+    expect(result.isSerializable).toBe(true);
+  });
+});
+
+describe('handler validation edge cases', () => {
+  it('should handle arrow functions correctly', () => {
+    const handler: JobHandler<TestPayloadMap, 'simple'> = async (
+      payload,
+      signal,
+    ) => {
+      await Promise.resolve();
+    };
+
+    const result = validateHandlerSerializable(handler, 'simple');
+    expect(result.isSerializable).toBe(true);
+  });
+
+  it('should handle regular function declarations', () => {
+    async function handler(
+      payload: TestPayloadMap['simple'],
+      signal: AbortSignal,
+    ): Promise<void> {
+      await Promise.resolve();
+    }
+
+    const result = validateHandlerSerializable(handler, 'simple');
+    expect(result.isSerializable).toBe(true);
+  });
+
+  it('should handle handlers with multiple statements', () => {
+    const handler: JobHandler<TestPayloadMap, 'simple'> = async (
+      payload,
+      signal,
+    ) => {
+      const step1 = 'first';
+      const step2 = 'second';
+      const step3 = step1 + step2;
+      await Promise.resolve(step3);
+    };
+
+    const result = validateHandlerSerializable(handler, 'simple');
+    expect(result.isSerializable).toBe(true);
+  });
+
+  it('should handle handlers with conditional logic', () => {
+    const handler: JobHandler<TestPayloadMap, 'simple'> = async (
+      payload,
+      signal,
+    ) => {
+      if (signal.aborted) {
+        return;
+      }
+      if (payload.data === 'test') {
+        await Promise.resolve('matched');
+      } else {
+        await Promise.resolve('not matched');
+      }
+    };
+
+    const result = validateHandlerSerializable(handler, 'simple');
+    expect(result.isSerializable).toBe(true);
+  });
+
+  it('should handle handlers with try-catch blocks', () => {
+    const handler: JobHandler<TestPayloadMap, 'simple'> = async (
+      payload,
+      signal,
+    ) => {
+      try {
+        await Promise.resolve();
+      } catch (error) {
+        throw error;
+      }
+    };
+
+    const result = validateHandlerSerializable(handler, 'simple');
+    expect(result.isSerializable).toBe(true);
+  });
+});

package/src/handler-validation.ts

@@ -0,0 +1,168 @@
+import { JobHandler } from './types.js';
+
+/**
+ * Validates that a job handler can be serialized for use with forceKillOnTimeout.
+ *
+ * This function checks if a handler can be safely serialized and executed in a worker thread.
+ * Use this function during development to catch serialization issues early.
+ *
+ * @param handler - The job handler function to validate
+ * @param jobType - Optional job type name for better error messages
+ * @returns An object with `isSerializable` boolean and optional `error` message
+ *
+ * @example
+ * ```ts
+ * const handler = async (payload, signal) => {
+ *   await doSomething(payload);
+ * };
+ *
+ * const result = validateHandlerSerializable(handler, 'myJob');
+ * if (!result.isSerializable) {
+ *   console.error('Handler is not serializable:', result.error);
+ * }
+ * ```
+ */
+export function validateHandlerSerializable<
+  PayloadMap,
+  T extends keyof PayloadMap & string,
+>(
+  handler: JobHandler<PayloadMap, T>,
+  jobType?: string,
+): { isSerializable: boolean; error?: string } {
+  try {
+    const handlerString = handler.toString();
+    const typeLabel = jobType ? `job type "${jobType}"` : 'handler';
+
+    // Check for common patterns that indicate non-serializable handlers
+    // 1. Arrow functions that capture 'this' (indicated by 'this' in the function body but not in parameters)
+    if (
+      handlerString.includes('this.') &&
+      !handlerString.match(/\([^)]*this[^)]*\)/)
+    ) {
+      return {
+        isSerializable: false,
+        error:
+          `Handler for ${typeLabel} uses 'this' context which cannot be serialized. ` +
+          `Use a regular function or avoid 'this' references when forceKillOnTimeout is enabled.`,
+      };
+    }
+
+    // 2. Check if handler string looks like it might have closures
+    // This is a heuristic - we can't perfectly detect closures, but we can warn about common patterns
+    if (handlerString.includes('[native code]')) {
+      return {
+        isSerializable: false,
+        error:
+          `Handler for ${typeLabel} contains native code which cannot be serialized. ` +
+          `Ensure your handler is a plain function when forceKillOnTimeout is enabled.`,
+      };
+    }
+
+    // 3. Try to create a function from the string to validate it's parseable
+    // This will catch syntax errors early
+    try {
+      new Function('return ' + handlerString);
+    } catch (parseError) {
+      return {
+        isSerializable: false,
+        error:
+          `Handler for ${typeLabel} cannot be serialized: ${parseError instanceof Error ? parseError.message : String(parseError)}. ` +
+          `When using forceKillOnTimeout, handlers must be serializable functions without closures over external variables.`,
+      };
+    }
+
+    // 4. Check for common closure patterns (heuristic)
+    // Look for variable references that might be from outer scope
+    // This is not perfect but can catch some common issues
+    const hasPotentialClosure =
+      /const\s+\w+\s*=\s*[^;]+;\s*async\s*\(/.test(handlerString) ||
+      /let\s+\w+\s*=\s*[^;]+;\s*async\s*\(/.test(handlerString);
+
+    if (hasPotentialClosure) {
+      // This is just a warning, not a hard error, since we can't be 100% sure
+      // The actual serialization will fail at runtime if there's a real issue
+      return {
+        isSerializable: true, // Still serializable, but might have issues
+        error:
+          `Warning: Handler for ${typeLabel} may have closures over external variables. ` +
+          `Test thoroughly with forceKillOnTimeout enabled. If the handler fails to execute in a worker thread, ` +
+          `ensure all dependencies are imported within the handler function.`,
+      };
+    }
+
+    return { isSerializable: true };
+  } catch (error) {
+    return {
+      isSerializable: false,
+      error: `Failed to validate handler serialization${jobType ? ` for job type "${jobType}"` : ''}: ${error instanceof Error ? error.message : String(error)}`,
+    };
+  }
+}
+
+/**
+ * Test if a handler can be serialized and executed in a worker thread.
+ * This is a more thorough check that actually attempts to serialize and deserialize the handler.
+ *
+ * @param handler - The job handler function to test
+ * @param jobType - Optional job type name for better error messages
+ * @returns Promise that resolves to validation result
+ *
+ * @example
+ * ```ts
+ * const handler = async (payload, signal) => {
+ *   await doSomething(payload);
+ * };
+ *
+ * const result = await testHandlerSerialization(handler, 'myJob');
+ * if (!result.isSerializable) {
+ *   console.error('Handler failed serialization test:', result.error);
+ * }
+ * ```
+ */
+export async function testHandlerSerialization<
+  PayloadMap,
+  T extends keyof PayloadMap & string,
+>(
+  handler: JobHandler<PayloadMap, T>,
+  jobType?: string,
+): Promise<{ isSerializable: boolean; error?: string }> {
+  // First do the basic validation
+  const basicValidation = validateHandlerSerializable(handler, jobType);
+  if (!basicValidation.isSerializable) {
+    return basicValidation;
+  }
+
+  // Then try to actually serialize and deserialize in a worker-like context
+  try {
+    const handlerString = handler.toString();
+    const handlerFn = new Function('return ' + handlerString)();
+
+    // Try to call it with dummy parameters to see if it executes
+    // We use a very short timeout to avoid hanging
+    const testPromise = handlerFn({}, new AbortController().signal);
+    const timeoutPromise = new Promise((_, reject) =>
+      setTimeout(() => reject(new Error('Handler test timeout')), 100),
+    );
+
+    try {
+      await Promise.race([testPromise, timeoutPromise]);
+    } catch (execError) {
+      // Execution errors are OK - we just want to know if it can be deserialized
+      // The actual job execution will handle real errors
+      if (
+        execError instanceof Error &&
+        execError.message === 'Handler test timeout'
+      ) {
+        // Handler is taking too long, but that's OK for serialization test
+        return { isSerializable: true };
+      }
+    }
+
+    return { isSerializable: true };
+  } catch (error) {
+    return {
+      isSerializable: false,
+      error: `Handler failed serialization test: ${error instanceof Error ? error.message : String(error)}`,
+    };
+  }
+}