{"id":26832696,"url":"https://github.com/tabkram/execution-engine","last_synced_at":"2025-10-09T00:42:49.560Z","repository":{"id":207924653,"uuid":"720386794","full_name":"tabkram/execution-engine","owner":"tabkram","description":"A TypeScript library for tracing and visualizing code execution workflows. ","archived":false,"fork":false,"pushed_at":"2025-08-08T16:09:47.000Z","size":936,"stargazers_count":19,"open_issues_count":0,"forks_count":1,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-09-14T11:59:28.398Z","etag":null,"topics":["execution","execution-context","execution-engine","execution-workflow","graph","json","node","trace","workflow","workflow-engine"],"latest_commit_sha":null,"homepage":"https://tabkram.github.io/execution-engine/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tabkram.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"security.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":["tabkram"]}},"created_at":"2023-11-18T10:26:15.000Z","updated_at":"2025-08-08T16:08:34.000Z","dependencies_parsed_at":"2023-12-12T20:30:21.913Z","dependency_job_id":"329f695b-4fa5-4a76-aae4-170365a9b417","html_url":"https://github.com/tabkram/execution-engine","commit_stats":null,"previous_names":["tabkram/execution-engine"],"tags_count":32,"template":false,"template_full_name":null,"purl":"pkg:github/tabkram/execution-engine","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tabkram%2Fexecution-engine","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tabkram%2Fexecution-engine/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tabkram%2Fexecution-engine/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tabkram%2Fexecution-engine/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tabkram","download_url":"https://codeload.github.com/tabkram/execution-engine/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tabkram%2Fexecution-engine/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279000639,"owners_count":26082879,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-08T02:00:06.501Z","response_time":56,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["execution","execution-context","execution-engine","execution-workflow","graph","json","node","trace","workflow","workflow-engine"],"created_at":"2025-03-30T15:18:17.262Z","updated_at":"2025-10-09T00:42:49.544Z","avatar_url":"https://github.com/tabkram.png","language":"TypeScript","readme":"# Execution Engine\n\n[![execution-engine on npm](https://img.shields.io/npm/v/execution-engine.svg?logo=npm\u0026label=NPM+package\u0026color=limegreen)](https://www.npmjs.com/package/execution-engine)\n[![npm](https://img.shields.io/npm/dm/execution-engine?color=limegreen)](https://www.npmjs.com/package/execution-engine)\n[![install size](https://packagephobia.com/badge?p=execution-engine)](https://packagephobia.com/result?p=execution-engine)\n[![Bundle size](https://img.shields.io/bundlephobia/min/execution-engine)](https://bundlephobia.com/result?p=execution-engine)\n[![Coverage Status](https://coveralls.io/repos/github/tabkram/execution-engine/badge.svg?branch=main)](https://coveralls.io/github/tabkram/execution-engine?branch=main)\n[![Dependencies](https://img.shields.io/librariesio/release/npm/execution-engine.svg)](https://www.npmjs.com/package/execution-engine)\n[![Github repo](https://img.shields.io/badge/github-grey?logo=github)](https://github.com/tabkram/execution-engine)\n[![GitHub Repo stars](https://img.shields.io/github/stars/tabkram/execution-engine?style=social)](https://github.com/tabkram/execution-engine/stargazers)\n[![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n[![Documentation](https://img.shields.io/badge/documentation-grey?logo=githubpages\u0026color=blue)](https://tabkram.github.io/execution-engine)\n[![jsDocs.io](https://img.shields.io/badge/jsDocs.io-reference-blue)](https://www.jsdocs.io/package/execution-engine)\n\nExecution Engine is a TypeScript library that enables tracing, visualization, and optimization of code execution\nworkflows. It provides tools to trace execution flow, manage caching, and optimize repeated computations, offering\ninsights through structured execution traces in JSON format.\n\n## Features ✨\n\nFeatures are divided into two main parts:\n\n### 1. Execution:\n\n- **Trace:** Capture detailed execution flow for debugging and analysis.\n- **Cache:** Prevent redundant function executions by storing results temporarily.\n- **Memoize:** Optimize repeated computations within the same execution call.\n\n### 2. Engine:\n\n- **Tracing:** Trace the execution flow of code within your project.\n- **Timing:** Capture the timing of each executed function.\n- **Visualization:** Generate traces in JSON format for clear and insightful visualization.\n    - Easily parseable into graphs using tools like [json-to-graph online demo](https://tabkram.github.io/json-to-graph/).\n\n## Installation 📦\n\nUse [npm](https://www.npmjs.com/package/execution-engine) package manager:\n\n```bash\nnpm install execution-engine\n```\n\nOr use the [yarn](https://yarnpkg.com/package?name=execution-engine) package manager:\n\n```bash\nyarn add execution-engine\n```\n\n## Usage 📚\n\n---\n### 1. Execution:\n\n#### Example 1: Memoization with `@memoize`\n\n```typescript\nimport { memoize } from \"execution-engine\";\n\nclass Calculator {\n  @memoize() // Store the result of Fibonacci calculations\n  fibonacci(n: number): number {\n    if (n \u003c= 1) return n;\n    return this.fibonacci(n - 1) + this.fibonacci(n - 2);\n  }\n}\n\nconst calc = new Calculator();\nconsole.log(calc.fibonacci(10));  // Calculates and stores result\nconsole.log(calc.fibonacci(10));  // Reuses pending result, no recalculation\n```\n\nIn this example, the `fibonacci` method is decorated with `@memoize`, meaning repeated calls with the same `n` will reuse the stored result instead of recalculating it.\n\n\n#### Example 2: Caching Results with `@cache`\n\n```typescript\nimport { cache } from \"execution-engine\";\n\nclass ExampleService {\n  @cache({ ttl: 5000 })  // Store result for 5 seconds\n  async fetchData(id: number): Promise\u003cstring\u003e {\n    console.log('Fetching data...');\n    return `Data for ${id}`;\n  }\n}\n\nconst service = new ExampleService();\nconsole.log(await service.fetchData(1));  // Fetches data and stores it\nconsole.log(await service.fetchData(1));  // Reuses stored result (within ttl)\n```\n\nThe `fetchData` method is decorated with `@cache`, storing the result for 5 seconds. Subsequent calls within that time reuse the stored result.\n\n#### Example 3: Tracing with `@trace`\n\n```typescript\nimport { trace } from \"execution-engine\";\n\nclass MathOperations {\n  @trace(console.log)  // Trace the execution and log using console.log\n  add(a: number, b: number): number {\n    return a + b;\n  }\n}\n\nconst mathOps = new MathOperations();\nconsole.log(mathOps.add(2, 3));  // Traces the 'add' method execution and logs it\n```\n\nIn this example, `@trace`logs the method execution, including input parameters, output, timing, duration, start time, end time, and elapsed time.\n\n\n---\n### 2. Engine:\n\n#### Example 1: Basic Usage\n\n```typescript\nimport { ExecutionEngine } from \"execution-engine\";\n\nconst engine = new ExecutionEngine();\n\n// for sync functions:\nconst res1 = engine.run((param) =\u003e `result1 for ${param}`, ['param1']);\n\n// for async functions:\nconst res2 = await engine.run(async (param) =\u003e `result2 for ${param}`, [res1.outputs]);\n\n// Retrieve the trace\nconst trace = engine.getTrace();\nconsole.log('Trace:', trace);\n```\n\nYou can:\n\n- view the **complete code** in [examples/usage.ts](examples/usage.ts)\n- inspect the **trace output** in [examples/usage.json](examples/usage.json).\n- visualize the **trace graph** using the json-to-graph online\n  tool. [→ See the result ←](https://tabkram.github.io/json-to-graph/?data=https://raw.githubusercontent.com/tabkram/execution-engine/main/examples/usage.json)\n\n#### Example 2: Usage with Decorators\n\n```typescript\nimport { engine, run } from \"execution-engine\";\n\n@engine({ id: \"uniqueEngineId\" })\nclass MyClass extends EngineTask {\n  @run()\n  myMethod1(param: string) {\n    return `result1 for ${param}`;\n  }\n\n  @run()\n  async myMethod2(param: string) {\n    return `result2 for ${param}`;\n  }\n}\n\nconst myInstance = new MyClass();\nmyInstance.myMethod2(\"param1\");\nawait myInstance.myMethod2(\"param2\");\n\n// Retrieve the trace\nconst trace = myInstance.engine.getTrace();\nconsole.log(\"Trace:\", trace);\n```\n\nYou can:\n\n- view the **complete code** in [examples/usage2.ts](examples/usage2.ts)\n- inspect the **trace output** in [examples/usage2.json](examples/usage2.json)\n- visualize the **trace graph** using the json-to-graph online\n  tool. [→ See the result ←](https://tabkram.github.io/json-to-graph/?data=https://raw.githubusercontent.com/tabkram/execution-engine/main/examples/usage2.json)\n\n#### Understanding the Trace 🧭\n\nThe `trace` object is an array containing **nodes** and **edges**. It has the following structure:\n\n```typescript\ntrace = [\n  {\n    data: {\n      id: function_uuid1,\n      label: \"function\"\n      //... other properties of the result of the executed function as mentioned above \n    },\n    group: nodes\n  },\n  {\n    data: {\n      id: function_uuid2,\n      label: \"function\"\n      //... other properties of the result of the executed function as mentioned above\n    },\n    group: nodes\n  },\n  {\n    data: {\n      id: function_uuid1 -\u003e function_uuid2,\n      source: function_uuid1,\n      target: function_uuid2,\n      parallel: false\n    },\n    group: edges\n  }\n];\n```\n\n#### Examples 📘\n\nFor additional usage examples, please explore the __[/examples](examples)__ directory in this repository.\n\nYou'll find a variety of scenarios showcasing the capabilities of Execution Engine.\n\n## Documentation 📔\n\nExplore the comprehensive __[documentation](https://tabkram.github.io/execution-engine)__ for this project.\n\n## Changelog 📝\n\nFor a detailed list of changes, enhancements, and bug fixes, please refer to our [Changelog](CHANGELOG.md).\n\n## Contributing 🤝\n\nIf you find any issues or have suggestions for improvement, feel free to open an issue or submit a pull request.\nContributions are welcome!\n\nBefore getting started, please read our [Contribution Guidelines](CONTRIBUTING.md).\n\n## Community 👥\n\nLove `execution-engine` ? Give our repo a star ⭐ ⬆️.\n\n## License 📄\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n","funding_links":["https://github.com/sponsors/tabkram"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftabkram%2Fexecution-engine","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftabkram%2Fexecution-engine","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftabkram%2Fexecution-engine/lists"}