web-background 1.0.3 → 1.0.5

package/README.md

@@ -1,68 +1,149 @@
-# Web Background
-This module provides background runtime available on the web.  
-웹에서 사용할 수 있는 백그라운드 실행환경을 제공합니다. 
-
-## API
-### background(fn)
-  
-  ```tsx
-    type FunctionInBackground<Fn> = (...params: Parameters<Fn>) => Promise<ReturnType<Fn>>;
-  
-    background<Fn>(fn: Fn): FunctionInBackground<Fn>
-  ```
-
-## Example
-[CodeSandbox](https://8pj3sf.csb.app/)
-
-```ts
-async function runLongTask () {
-  const getVertexCoordinates = background((imageData: ImageData) => {
-    const { data, width } = imageData;
-    let [minX, minY, maxX, maxY] = [Infinity, Infinity, 0, 0];
-
-    for(let i = 0, leng = data.length; i < leng; i += 4) {
-      const [r, g, b, a] = data.slice(i, i+4);
-      const isFilled = Math.max(r, g, b, a) > 0;
-      if(isFilled) {
-        const y = Math.floor(i / 4 / width);
-        const x = Math.floor(i / 4 - width * y);
-
-        minX = Math.min(minX, x);
-        minY = Math.min(minY, y);
-        maxX = Math.max(maxX, x);
-        maxY = Math.max(maxY, y);
-      }
-    }
-
-    return {
-      x: minX === Infinity ? 0 : minX,
-      y: minY === Infinity ? 0 : minY,
-      width: maxX,
-      height: maxY
-    };
-  })
-
-  const coordinate = await getVertexCoordinates(
-    canvas.getContext('2d').getImageData(0, 0, 1000, 1000)
-  )
-}
+# 🚀 Web Background
+
+**Simple Web Worker Library - Run complex tasks in the background!**
+
+Web Background is a simple yet powerful library that enables you to execute heavy computations in the background without blocking the main thread in web browsers.
+
+## ✨ Features
+
+- 🎯 **Simple API**: Execute workers instantly with a single function
+- 🧠 **Automatic Context Capture**: Automatically detects and transfers external variables
+- 🚀 **High-Performance Caching**: Cache identical functions for faster re-execution
+- 🧹 **Automatic Memory Management**: Auto-cleanup workers and cache on GC
+- 💪 **Full TypeScript Support**: Complete type safety
+- 📦 **Zero Dependencies**: No external dependencies
+
+## 📦 Installation
+
+```bash
+npm install web-background
+# or
+yarn add web-background
+# or
+pnpm add web-background
+```
+
+## 🚀 Quick Start
+
+### Basic Usage
+
+```typescript
+import { background } from "web-background";
+
+// Simple background execution
+const heavyCalculation = background((numbers: number[]) => {
+  // CPU intensive task
+  return numbers.reduce((sum, num) => sum + Math.sqrt(num), 0);
+});
+
+// Execute without blocking main thread
+const result = await heavyCalculation([1, 4, 9, 16, 25]);
+console.log(result); // 15
+
+// When external variables are needed (optional context passing)
+const multiplier = 10;
+const processWithContext = background(
+  (numbers: number[]) => numbers.map((x) => x * multiplier),
+  { multiplier } // Explicit passing when needed
+);
+```
+
+### Complex Real-world Example
+
+```typescript
+// Image data processing
+const processImage = background((imageData: ImageData) => {
+  const { data, width, height } = imageData;
+  const processed = new Uint8ClampedArray(data.length);
+
+  // Apply Gaussian blur
+  for (let i = 0; i < data.length; i += 4) {
+    const y = Math.floor(i / 4 / width);
+    const x = Math.floor(i / 4 - width * y);
+
+    processed[i] = data[i] * 0.8; // R
+    processed[i + 1] = data[i + 1] * 0.8; // G
+    processed[i + 2] = data[i + 2] * 0.8; // B
+    processed[i + 3] = data[i + 3]; // A
+  }
+
+  return new ImageData(processed, width, height);
+});
+
+// Usage
+const canvas = document.querySelector("canvas");
+const ctx = canvas.getContext("2d");
+const originalData = ctx.getImageData(0, 0, canvas.width, canvas.height);
+
+const blurredData = await processImage(originalData);
+ctx.putImageData(blurredData, 0, 0);
 ```
 
+## 🛠️ API Reference
+
+### `background<T>(fn: T, context?: Record<string, any>): FunctionInBackground<T>`
+
+Converts a function to run in a web worker.
+
+**Parameters:**
+
+- `fn`: Function to execute in the background
+- `context` (optional): Explicitly pass external variables when needed
+
+**Returns:**
+
+- Function with the same signature as the original but returns a `Promise`
+
+**Type:**
+
+```typescript
+type FunctionInBackground<Fn> = (
+  ...params: Parameters<Fn>
+) => Promise<ReturnType<Fn>>;
+```
+
+## 📋 Constraints & Guidelines
+
+### ✅ What's Available
+
+- Pure computation logic
+- JSON serializable data (strings, numbers, arrays, objects, etc.)
+- Built-in global objects like `Math`, `Date`, `JSON`
+- Explicitly passed functions and variables
+
+### ❌ What's Not Available
+
+- DOM APIs (`document`, `window`, etc.)
+- Web APIs (`fetch`, `localStorage`, etc. have separate worker support)
+- Non-serializable data (functions, Symbols, undefined, etc.)
+- ES6 module imports (context passing required in bundler environments)
+
+### 💡 Best Practices
+
+1. **Context is optional**:
+
+   ```typescript
+   // ✅ Pure function without external variables
+   const pureWorker = background((data) => complexCalculation(data));
 
-## Tip
-- Web Background is implemented as a Web Worker and is available in web browsers.  
-Web Background는 웹 워커로 구현되며 브라우저에서 사용할 수 있습니다. 
+   // ✅ Pass context when needed (more stable)
+   const contextWorker = background((data) => processWithConfig(data, config), {
+     config,
+   });
+   ```
 
-- In most cases, you don't need to use it. It's recommended to use it for long working  
-대부분의 경우 이 모듈을 사용할 필요는 없으나, 비용이 큰 작업을 처리해야 할 경우 사용할 것을 추천합니다. 
+2. **Use only for heavy computations**:
 
-- Most WebAPIs including DOM APIs are cannot be used.  
-DOM API를 포함한 대부분의 WebAPI를 사용하지 못합니다.  
-[Read More](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API)
+   ```typescript
+   // ❌ Simple operations
+   const add = background((a, b) => a + b);
 
-- To send arguments, you must use data from structured clone algorithm types.  
-인자로 전송 가능한 데이터 유형은 복사 가능한 타입의 데이터만 가능합니다.   
-[Read More](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm)
+   // ✅ CPU intensive operations
+   const processLargeArray = background((data) => {
+     // Complex processing logic...
+   });
+   ```
 
-- It runs in isolation, cannot be access external variables and modules
-격리된 환경에서 실행되므로 외부 모듈 및 외부 변수에 접근할 수 없습니다. 
+3. **Keep data size appropriate**:
+   - Large objects or complex contexts cause serialization overhead
+   - Pass only necessary data for performance optimization

package/dist/background.d.ts

@@ -1 +1,3 @@
-export declare function background<Payload extends any[], ReturnValue = void>(fn: (...payloads: Payload) => ReturnValue): (...payload: Payload) => Promise<ReturnValue>;
+export type FunctionInBackground<Callback extends (params: any) => any> = (...params: Parameters<Callback>) => Promise<ReturnType<Callback>>;
+export declare function background<Payload, ReturnValue>(fn: (payload: Payload) => ReturnValue): FunctionInBackground<typeof fn>;
+export declare function background<Payload, ReturnValue>(fn: (payload: Payload) => ReturnValue, context?: Record<string, any>): FunctionInBackground<typeof fn>;

package/dist/index.js

@@ -1 +1 @@
-class e extends Worker{postMessage(e){super.postMessage(e)}addEventListener(e,t){super.addEventListener(e,t)}}class t extends e{constructor(e,t){super(e,t)}request(e){return new Promise((t=>{const n=({data:e})=>{t(e),this.removeEventListener("message",n)};this.postMessage(e),this.addEventListener("message",n)}))}}"function"==typeof SuppressedError&&SuppressedError;class n{static fromModule(e,t){var{module:n}=t,r=function(e,t){var n={};for(var r in e)Object.prototype.hasOwnProperty.call(e,r)&&t.indexOf(r)<0&&(n[r]=e[r]);if(null!=e&&"function"==typeof Object.getOwnPropertySymbols){var s=0;for(r=Object.getOwnPropertySymbols(e);s<r.length;s++)t.indexOf(r[s])<0&&Object.prototype.propertyIsEnumerable.call(e,r[s])&&(n[r[s]]=e[r[s]])}return n}(t,["module"]);const s=n.toString();console.log(null);const o=`\n        self.addEventListener('message', async event => {\n          const result = await (${s})(${n.length>1?"...event.data":"event.data"});\n          \n          self.postMessage(result);\n        });\n      `.trim(),a=new Blob([o]),l=URL.createObjectURL(a),u=new e(l,r),i=u.terminate;return u.terminate=()=>{i.call(u),URL.revokeObjectURL(l)},u}}const r=new FinalizationRegistry((e=>e.terminate()));function s(e){let s=null;return function o(...a){if("undefined"==typeof window)throw new Error("[web-background] You must use background in browser");return null==s&&(s=n.fromModule(t,{module:e}),r.register(o,s)),s.request.call(s,a.length>1?a:a[0])}}export{s as background};
+class e extends Worker{postMessage(e){super.postMessage(e)}addEventListener(e,t){super.addEventListener(e,t)}}class t extends e{constructor(e,t){super(e,t)}request(e){return new Promise((t=>{const n=({data:e})=>{t(e),this.removeEventListener("message",n)};this.postMessage(e),this.addEventListener("message",n)}))}}"function"==typeof SuppressedError&&SuppressedError;class n{constructor(){this.store=new Map}get(e){return this.store.get(e)}set(e,t){this.store.set(e,t)}delete(e){this.store.delete(e)}clear(){this.store.clear()}size(){return this.store.size}}const o=new n,r=new class extends n{deleteByPrefix(e){for(const[t,n]of this.store)t.startsWith(e)&&this.delete(t)}},s=new n,i=new n;class c{static increment(e){const t=i.get(e)||0;i.set(e,t+1)}static decrement(e){const t=i.get(e)||0;return t<=1?(i.delete(e),!0):(i.set(e,t-1),!1)}static getCount(e){return i.get(e)||0}}class a{static getContext(e){return o.get(e)}static setContext(e,t){o.set(e,t),c.increment(e)}static getSerialization(e){return r.get(e)}static setSerialization(e,t){r.set(e,t);const n=e.split(":")[0];c.increment(n)}static getIdentifiers(e){return s.get(e)}static setIdentifiers(e,t){s.set(e,t),c.increment(e)}static decrementUsage(e){c.decrement(e)&&(o.delete(e),s.delete(e),r.deleteByPrefix(e+":"),console.log(`'${e.substring(0,50)}...' 함수 캐시 정리 완료`))}static getCacheStats(){return{contextCacheSize:o.size(),serializationCacheSize:r.size(),identifierCacheSize:s.size(),activeFunctions:i.size()}}static clearAllCaches(){o.clear(),r.clear(),s.clear(),i.clear(),console.log("모든 캐시가 정리되었습니다")}}const l=new Set(["function","return","var","let","const","if","else","for","while","do","break","continue","switch","case","default","try","catch","finally","throw","new","this","typeof","instanceof","in","of","class","extends","super","async","await","yield","true","false","null","undefined","delete","void","with","export","import","from"]),f=new Set(["console","Math","Date","JSON","Array","Object","String","Number","Boolean","RegExp","Error","Promise","setTimeout","setInterval","clearTimeout","clearInterval","parseInt","parseFloat","isNaN","isFinite","decodeURIComponent","encodeURIComponent","window","document","global","process","self","URL","URLSearchParams","fetch","XMLHttpRequest","localStorage","sessionStorage","location","history","navigator","Blob","File","FileReader","FormData","Headers","Request","Response","AbortController","AbortSignal","crypto","performance","requestAnimationFrame","cancelAnimationFrame","requestIdleCallback","cancelIdleCallback"]);function u(e){const t=a.getIdentifiers(e);if(t)return t;const n=new Set,o=/\b[a-zA-Z_$][a-zA-Z0-9_$]*\b/g;let r;for(;null!==(r=o.exec(e));){const t=r[0];d(t)||p(t,e)||y(t,e)||n.add(t)}const s=Array.from(n);return a.setIdentifiers(e,s),s}function d(e){return l.has(e)}function g(e){return f.has(e)}function p(e,t){return[new RegExp(`function\\s*\\([^)]*\\b${e}\\b[^)]*\\)`),new RegExp(`\\([^)]*\\b${e}\\b[^)]*\\)\\s*=>`),new RegExp(`^\\s*${e}\\s*=>`),new RegExp(`async\\s+\\([^)]*\\b${e}\\b[^)]*\\)\\s*=>`),new RegExp(`async\\s+${e}\\s*=>`)].some((e=>e.test(t)))}function y(e,t){return[new RegExp(`(?:var|let|const)\\s+${e}\\b`),new RegExp(`(?:var|let|const)\\s+\\{[^}]*\\b${e}\\b[^}]*\\}`),new RegExp(`function\\s+${e}\\b`)].some((e=>e.test(t)))}function w(e){if(null==e)return!0;if("boolean"==typeof e||"number"==typeof e||"string"==typeof e)return!0;if("function"==typeof e||"symbol"==typeof e||"bigint"==typeof e)return!1;if(Array.isArray(e))return e.every((e=>w(e)));if("object"==typeof e)try{return JSON.stringify(e),!0}catch(e){return!1}return!1}function h(e,t){const n=`${e.toString()}:${JSON.stringify(t||{})}`,o=a.getSerialization(n);if(o)return o;const r=function(e,t){const n=e.toString();let o="(function() {\n";const r=Object.entries(t),s=r.filter((([,e])=>"function"!=typeof e)),i=r.filter((([,e])=>"function"==typeof e));s.forEach((([e,t])=>{try{o+=`  const ${e} = ${JSON.stringify(t)};\n`}catch(t){o+=`  const ${e} = undefined;\n`}})),i.forEach((([e,t])=>{"function"==typeof t&&(o+=`  const ${e} = ${t.toString()};\n`)})),r.length>0&&(o+="\n");return o+=`  return ${n};\n`,o+="})()",o}(e,t||{});return a.setSerialization(n,r),r}class b{static fromModule(e,t){var{module:n,context:o}=t,r=function(e,t){var n={};for(var o in e)Object.prototype.hasOwnProperty.call(e,o)&&t.indexOf(o)<0&&(n[o]=e[o]);if(null!=e&&"function"==typeof Object.getOwnPropertySymbols){var r=0;for(o=Object.getOwnPropertySymbols(e);r<o.length;r++)t.indexOf(o[r])<0&&Object.prototype.propertyIsEnumerable.call(e,o[r])&&(n[o[r]]=e[o[r]])}return n}(t,["module","context"]);const s=o||function(e){const t=u(e.toString()),n={};return t.forEach((e=>{if(!g(e))try{const t=globalThis[e]||("undefined"!=typeof window?window[e]:void 0);void 0!==t&&("function"==typeof t||w(t))&&(n[e]=t)}catch(e){}})),n}(n),i=h(n,s);console.log(i);const c=`\n      self.addEventListener('message', async event => {\n        const func = ${i};\n        const result = await func(${n.length>1?"...event.data":"event.data"});\n        self.postMessage(result);\n      });\n    `.trim(),a=new Blob([c]),l=URL.createObjectURL(a),f=new e(l,r),d=f.terminate;return f.terminate=()=>{d.call(f),URL.revokeObjectURL(l)},f}}const m=new FinalizationRegistry((e=>{e.worker.terminate(),a.decrementUsage(e.funcStr),console.log("워커 정리 및 캐시 정리 완료")}));function S(e){const t=e.toString(),n=a.getContext(t);if(n)return console.log("캐시된 컨텍스트 사용:",n),n;const o={};console.log("함수 문자열:",t);const r=u(t),s=function(e){const t=e.match(/function[^(]*\(([^)]*)\)|^\s*\(([^)]*)\)\s*=>|^\s*([a-zA-Z_$][a-zA-Z0-9_$]*)\s*=>/),n=new Set;t&&(t[1]||t[2]||t[3]||"").split(",").forEach((e=>{const t=e.trim().split("=")[0].trim();t&&/^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(t)&&n.add(t)}));return n}(t),i=function(e){const t=new Set,n=/(?:var|let|const)\s+([a-zA-Z_$][a-zA-Z0-9_$]*)/g;let o;for(;null!==(o=n.exec(e));)t.add(o[1]);return t}(t),c=function(){const e={};return"undefined"!=typeof window&&Object.getOwnPropertyNames(window).forEach((t=>{try{if(!g(t)){const n=Object.getOwnPropertyDescriptor(window,t);if(n&&n.configurable){const n=window[t];void 0!==n&&(e[t]=n)}}}catch(e){}})),"undefined"!=typeof globalThis&&Object.getOwnPropertyNames(globalThis).forEach((t=>{try{g(t)||t in e||(e[t]=globalThis[t])}catch(e){}})),e}();return console.log("추출된 식별자들:",r),console.log("매개변수들:",Array.from(s)),console.log("로컬 변수들:",Array.from(i)),console.log("호출자 스코프:",Object.keys(c)),r.forEach((e=>{if(!(d(e)||g(e)||s.has(e)||i.has(e))){if(console.log(`'${e}' 검사 중...`),e in c){const t=c[e];return console.log(`호출자 스코프에서 '${e}' 발견:`,typeof t),void(("function"==typeof t||w(t))&&(o[e]=t))}try{let t;"undefined"!=typeof window&&e in window?(t=window[e],console.log(`window에서 '${e}' 발견:`,typeof t)):"undefined"!=typeof globalThis&&e in globalThis&&(t=globalThis[e],console.log(`globalThis에서 '${e}' 발견:`,typeof t)),void 0!==t&&("function"==typeof t||w(t))&&(o[e]=t)}catch(t){console.log(`'${e}' 접근 실패:`,t)}}})),console.log("최종 컨텍스트:",o),a.setContext(t,o),o}function $(e,n){const o=void 0!==n?n:S(e);console.log("최종 사용될 컨텍스트:",o);let r=null;return function n(...s){if("undefined"==typeof window)throw new Error("[web-background] You must use background in browser");return null==r&&(r=b.fromModule(t,{module:e,context:o}),m.register(n,{worker:r,funcStr:e.toString()})),r.request.call(r,s.length>1?s:s[0])}}export{$ as background};

package/dist/modules/WorkerBuilder.d.ts

@@ -4,8 +4,9 @@ interface WorkerConstructor<Worker> {
 }
 interface Options extends WorkerOptions {
     module: (...args: any[]) => any;
+    context?: Record<string, any>;
 }
 export declare class WorkerBuilder {
-    static fromModule<W extends Worker>(Worker: WorkerConstructor<W>, { module, ...options }: Options): W;
+    static fromModule<W extends Worker>(Worker: WorkerConstructor<W>, { module, context, ...options }: Options): W;
 }
 export {};

package/dist/modules/cacheManager.d.ts

@@ -0,0 +1,16 @@
+export declare class CacheManager {
+    static getContext(funcStr: string): Record<string, any> | undefined;
+    static setContext(funcStr: string, context: Record<string, any>): void;
+    static getSerialization(cacheKey: string): string | undefined;
+    static setSerialization(cacheKey: string, result: string): void;
+    static getIdentifiers(funcStr: string): string[] | undefined;
+    static setIdentifiers(funcStr: string, identifiers: string[]): void;
+    static decrementUsage(funcStr: string): void;
+    static getCacheStats(): {
+        contextCacheSize: number;
+        serializationCacheSize: number;
+        identifierCacheSize: number;
+        activeFunctions: number;
+    };
+    static clearAllCaches(): void;
+}

package/dist/modules/captureContext.d.ts

@@ -0,0 +1 @@
+export declare function captureCallerContext(fn: Function): Record<string, any>;

package/dist/modules/functionUtils.d.ts

@@ -0,0 +1,9 @@
+export declare function extractIdentifiers(funcStr: string): string[];
+export declare function isKeyword(identifier: string): boolean;
+export declare function isGlobalBuiltIn(identifier: string): boolean;
+export declare function isParameter(identifier: string, funcStr: string): boolean;
+export declare function isLocalVariable(identifier: string, funcStr: string): boolean;
+export declare function isSerializable(value: any): boolean;
+export declare function getGlobalScope(): Record<string, any>;
+export declare function extractParametersFromFunction(funcStr: string): Set<string>;
+export declare function extractLocalVariables(funcStr: string): Set<string>;

package/dist/modules/serializeFunction.d.ts

@@ -0,0 +1,3 @@
+export declare function serializeFunction(func: Function, providedContext?: Record<string, any>): string;
+export declare function deserializeFunction(serializedFunc: string): Function;
+export declare function extractClosureContext(func: Function): Record<string, any>;

package/dist/modules/workerCleanupRegistry.d.ts

@@ -1 +1,4 @@
-export declare const workerCleanupRegistry: FinalizationRegistry<Worker>;
+export declare const workerCleanupRegistry: FinalizationRegistry<{
+    worker: Worker;
+    funcStr: string;
+}>;

package/package.json

@@ -7,7 +7,7 @@
     "Background",
     "Web Background"
   ],
-  "version": "1.0.3",
+  "version": "1.0.5",
   "main": "dist/index.js",
   "module": "dist/index.js",
   "type": "module",
@@ -24,10 +24,11 @@
     "@babel/preset-env": "^7.23.3",
     "@rollup/plugin-babel": "^6.0.4",
     "@rollup/plugin-node-resolve": "^15.2.3",
+    "@rollup/plugin-strip": "^3.0.4",
     "@rollup/plugin-terser": "^0.4.4",
     "rollup": "^4.4.0",
     "rollup-plugin-typescript2": "^0.36.0",
     "typescript": "5.2"
   },
-  "dependencies": {}
-}
+  "files": ["dist"]
+}