@medusajs/workflow-engine-inmemory 2.22.0-snapshot-20261020204851 → 2.22.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/AGENTS.md +64 -0
  2. package/README.md +58 -1
  3. package/package.json +8 -4
package/AGENTS.md ADDED
@@ -0,0 +1,64 @@
1
+ # @medusajs/workflow-engine-inmemory
2
+
3
+ Default Workflow Engine Module: orchestrates workflow executions, keeping in-flight checkpoints in a process-local object and persisting executions to the `workflow_execution` table when needed. Registered as `Modules.WORKFLOW_ENGINE` (`"workflows"`). For production or multiple instances use `@medusajs/workflow-engine-redis`.
4
+
5
+ ## Using this package
6
+
7
+ - Loaded by default through `defineConfig` (`@medusajs/medusa/workflow-engine-inmemory`). No module options.
8
+ - Workflows run through `workflow(container).run()` from `@medusajs/framework/workflows-sdk` use the registered engine. Resolve the engine directly to drive long-running workflows:
9
+
10
+ ```ts
11
+ import { Modules, TransactionHandlerType } from "@medusajs/framework/utils"
12
+ import { StepResponse } from "@medusajs/framework/workflows-sdk"
13
+
14
+ const workflowEngineService = container.resolve(Modules.WORKFLOW_ENGINE)
15
+
16
+ await workflowEngineService.setStepSuccess({
17
+ idempotencyKey: {
18
+ action: TransactionHandlerType.INVOKE,
19
+ transactionId,
20
+ stepId: "step-2",
21
+ workflowId: "hello-world",
22
+ },
23
+ stepResponse: new StepResponse("Done!"),
24
+ })
25
+ ```
26
+
27
+ ### Service methods (`src/services/workflows-module.ts`)
28
+
29
+ Generated CRUD for `WorkflowExecution`, plus `run`, `getRunningTransaction`, `setStepSuccess`, `setStepFailure`, `retryStep`, `cancel`, `subscribe`, `unsubscribe`. `listWorkflowExecutions` / `listAndCountWorkflowExecutions` accept a `q` filter (ILIKE on `transaction_id`, `workflow_id`, `state`, `execution.runId`).
30
+
31
+ ### Data model (`src/models/workflow-execution.ts`)
32
+
33
+ - `WorkflowExecution` (`wf_exec_`): composite primary key `(workflow_id, transaction_id, run_id)`, `execution` and `context` JSON, `state` (`TransactionState`), `retention_time` (seconds). Kept identical to the Redis engine's model.
34
+ - No module links and no module events.
35
+
36
+ Docs: https://docs.medusajs.com/resources/infrastructure-modules/workflow-engine.md, https://docs.medusajs.com/resources/infrastructure-modules/workflow-engine/in-memory.md, https://docs.medusajs.com/learn/fundamentals/workflows/long-running-workflow.md, https://docs.medusajs.com/learn/fundamentals/workflows/store-executions.md
37
+
38
+ ## Architecture
39
+
40
+ - `src/services/workflow-orchestrator.ts` (`WorkflowOrchestratorService`): runs exported workflows, notifies subscribers (static, process-wide map), and resumes parent workflows of async sub-workflows.
41
+ - `src/utils/workflow-orchestrator-storage.ts` (`InMemoryDistributedTransactionStorage`, registered by `src/loaders/utils.ts`): checkpoints, retries, step/transaction timeouts, and scheduled jobs (`cron` via `cron-parser` or `interval`) all use in-process `setTimeout` timers.
42
+ - DB writes happen only when the flow is not started, finished, waiting to compensate, async (`_v`), or a step at the current depth has `store: true`. Finished flows without `retentionTime` are deleted from the DB unless they are sub-workflows (`parentStepIdempotencyKey`).
43
+ - Every 30 minutes, finished executions (`done`, `failed`, `reverted`) older than their `retention_time` are deleted.
44
+ - This package and `workflow-engine-redis` share most of their service and orchestrator code; port behavior changes to both.
45
+
46
+ ## Development
47
+
48
+ ```bash
49
+ cd packages/modules/workflow-engine-inmemory
50
+ yarn build
51
+ yarn test
52
+ yarn test:integration # integration-tests/__tests__ (needs Postgres, DB_* env vars)
53
+ yarn test:integration integration-tests/__tests__/race.spec.ts
54
+ yarn migration:create # after any change in src/models
55
+ ```
56
+
57
+ - Integration tests: `index.spec.ts`, `race.spec.ts`, `retry-interval.spec.ts`, `subscribe.spec.ts`; workflow fixtures in `integration-tests/__fixtures__/`.
58
+
59
+ ## Gotchas
60
+
61
+ - State, timers, and subscribers live in one process: retries, timeouts, and scheduled jobs are lost on restart and are not shared across instances.
62
+ - `save` throws `Transaction storage is locked` on concurrent saves for the same key, and `SkipExecutionError` when a manual (non `auto-`) `transactionId` is already running.
63
+ - `run` JSON-clones its options, so non-serializable values in `options` are dropped.
64
+ - Unlike the Redis engine, `run` copies `options.runId` into the workflow context.
package/README.md CHANGED
@@ -1 +1,58 @@
1
- # Workflow Orchestrator
1
+ <p align="center">
2
+ <a href="https://www.medusajs.com">
3
+ <picture>
4
+ <source media="(prefers-color-scheme: dark)" srcset="https://user-images.githubusercontent.com/59018053/229103275-b5e482bb-4601-46e6-8142-244f531cebdb.svg">
5
+ <source media="(prefers-color-scheme: light)" srcset="https://user-images.githubusercontent.com/59018053/229103726-e5b529a3-9b3f-4970-8a1f-c6af37f087bf.svg">
6
+ <img alt="Medusa logo" src="https://user-images.githubusercontent.com/59018053/229103726-e5b529a3-9b3f-4970-8a1f-c6af37f087bf.svg">
7
+ </picture>
8
+ </a>
9
+ </p>
10
+ <h1 align="center">
11
+ @medusajs/workflow-engine-inmemory
12
+ </h1>
13
+
14
+ <h4 align="center">
15
+ <a href="https://docs.medusajs.com">Documentation</a> |
16
+ <a href="https://www.medusajs.com">Website</a>
17
+ </h4>
18
+
19
+ <p align="center">
20
+ Building blocks for digital commerce
21
+ </p>
22
+ <p align="center">
23
+ <a href="https://github.com/medusajs/medusa/blob/develop/LICENSE">
24
+ <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="Medusa is released under the MIT license." />
25
+ </a>
26
+ <a href="https://github.com/medusajs/medusa/blob/develop/CONTRIBUTING.md">
27
+ <img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat" alt="PRs welcome!" />
28
+ </a>
29
+ <a href="https://discord.gg/xpCwq3Kfn8">
30
+ <img src="https://img.shields.io/badge/chat-on%20discord-7289DA.svg" alt="Discord Chat" />
31
+ </a>
32
+ <a href="https://twitter.com/intent/follow?screen_name=medusajs">
33
+ <img src="https://img.shields.io/twitter/follow/medusajs.svg?label=Follow%20@medusajs" alt="Follow @medusajs" />
34
+ </a>
35
+ </p>
36
+
37
+ In-Memory Workflow Engine Module for Medusa: runs workflows and tracks their executions and subscribers in memory. It's the default Workflow Engine Module, installed and registered with `@medusajs/medusa`, and is meant for development and testing. For production, use the [Redis Workflow Engine Module](https://docs.medusajs.com/resources/infrastructure-modules/workflow-engine/redis) (`@medusajs/workflow-engine-redis`) instead.
38
+
39
+ ## At a glance
40
+
41
+ | | |
42
+ | --- | --- |
43
+ | Package | `@medusajs/workflow-engine-inmemory` |
44
+ | Type | Infrastructure Module |
45
+ | Module key | `Modules.WORKFLOW_ENGINE` (`"workflows"`) |
46
+ | Registered by default | Yes |
47
+ | Import from | `@medusajs/medusa/workflow-engine-inmemory` |
48
+
49
+ ## Installation
50
+
51
+ No installation needed. The module ships with `@medusajs/medusa` and is registered by `defineConfig`. It has no options.
52
+
53
+ ## Resources
54
+
55
+ - [Workflow Engine Module](https://docs.medusajs.com/resources/infrastructure-modules/workflow-engine)
56
+ - [In-Memory Workflow Engine Module](https://docs.medusajs.com/resources/infrastructure-modules/workflow-engine/in-memory)
57
+ - [How to Use the Workflow Engine Module](https://docs.medusajs.com/resources/infrastructure-modules/workflow-engine/how-to-use)
58
+ - [Workflows](https://docs.medusajs.com/learn/fundamentals/workflows)
package/package.json CHANGED
@@ -1,15 +1,19 @@
1
1
  {
2
2
  "name": "@medusajs/workflow-engine-inmemory",
3
- "version": "2.22.0-snapshot-20261020204851",
3
+ "version": "2.22.0",
4
4
  "description": "Medusa Workflow Orchestrator module",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",
7
7
  "files": [
8
8
  "dist",
9
+ "AGENTS.md",
9
10
  "!dist/**/__tests__",
10
11
  "!dist/**/__mocks__",
11
12
  "!dist/**/__fixtures__"
12
13
  ],
14
+ "llms": "https://docs.medusajs.com/llms.txt",
15
+ "llmsFull": "https://docs.medusajs.com/llms-full.txt",
16
+ "mcpServer": "https://docs.medusajs.com/mcp",
13
17
  "engines": {
14
18
  "node": ">=22.22.0"
15
19
  },
@@ -39,14 +43,14 @@
39
43
  "orm:cache:clear": "MIKRO_ORM_CLI_CONFIG=./mikro-orm.config.dev.ts MIKRO_ORM_ALLOW_GLOBAL_CLI=true medusa-mikro-orm cache:clear"
40
44
  },
41
45
  "devDependencies": {
42
- "@medusajs/framework": "2.22.0-snapshot-20261020204851",
43
- "@medusajs/test-utils": "2.22.0-snapshot-20261020204851"
46
+ "@medusajs/framework": "2.22.0",
47
+ "@medusajs/test-utils": "2.22.0"
44
48
  },
45
49
  "dependencies": {
46
50
  "cron-parser": "^4.9.0",
47
51
  "ulid": "^2.3.0"
48
52
  },
49
53
  "peerDependencies": {
50
- "@medusajs/framework": "2.22.0-snapshot-20261020204851"
54
+ "@medusajs/framework": "2.22.0"
51
55
  }
52
56
  }