{"_id":"@bernierllc/nevar-graph-executor","_rev":"2-eff19fa80d834cba7144125ca1a5a830","name":"@bernierllc/nevar-graph-executor","dist-tags":{"latest":"0.1.1"},"versions":{"0.0.1":{"name":"@bernierllc/nevar-graph-executor","version":"0.0.1","license":"SEE LICENSE IN README.md","_id":"@bernierllc/nevar-graph-executor@0.0.1","maintainers":[{"name":"alikhan410","email":"mczeyo@gmail.com"},{"name":"mkbernier","email":"mkbernier@gmail.com"}],"dist":{"shasum":"1b97c2fb53e503e82fde56217088802852ee9414","tarball":"https://registry.npmjs.org/@bernierllc/nevar-graph-executor/-/nevar-graph-executor-0.0.1.tgz","fileCount":2,"integrity":"sha512-zSPn5P9pcdWVyX3cysr2jAO53kaFR8ge3HQsutUR+VQSoOaowLIRVJKxhCEyEYmGV+oBadhBgGNJ28iltXb2fw==","signatures":[{"sig":"MEUCIAlsX7+//2QPfnYx6580ES3Yytlao00H6qrKsEe/i1IzAiEA9unYYbqzkXLbxzLTwVmKMxewSV2+DJX4/wuonetuDxw=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":391},"_npmUser":{"name":"mkbernier","email":"mkbernier@gmail.com"},"_npmVersion":"11.12.1","description":"Placeholder for OIDC trusted-publisher bootstrap. Real release follows via GitHub Actions.","directories":{},"_nodeVersion":"25.9.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/nevar-graph-executor_0.0.1_1779119034660_0.1837836786025555","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@bernierllc/nevar-graph-executor","version":"0.1.1","description":"Topological execution engine for Nevar typed-DAG graphs — dispatches nodes, resolves edge mappings, enforces idempotency","main":"dist/index.js","types":"dist/index.d.ts","keywords":["nevar","graph","executor","dag","topological","idempotency","bernierllc"],"author":{"name":"Bernier LLC"},"license":"SEE LICENSE IN LICENSE","dependencies":{"@bernierllc/nevar-graph-types":"0.1.2","@bernierllc/nevar-types":"0.1.0","@bernierllc/nevar-action-executor":"0.1.0","@bernierllc/nevar-graph-storage":"0.1.1"},"devDependencies":{"@types/jest":"^29.5.0","@types/node":"^20.0.0","@typescript-eslint/eslint-plugin":"^6.0.0","@typescript-eslint/parser":"^6.0.0","eslint":"^8.0.0","jest":"^29.5.0","ts-jest":"^29.1.0","typescript":"^5.0.0"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"scripts":{"build":"tsc","test":"jest","test:run":"jest","test:coverage":"jest --coverage","lint":"eslint src __tests__ --ext .ts","clean":"rm -rf dist"},"_id":"@bernierllc/nevar-graph-executor@0.1.1","_integrity":"sha512-7hDZBvsuc9OkxtINHsf7383f30mOGBARTJCRpeEzyVUzx8hlsWlc6wQznTtZioFpfjmtf5gEc/gFADZcE82k6Q==","_resolved":"/private/var/folders/r0/wspnzd1s18sfjy10ffyv2qxw0000gn/T/17943e7094ab2a071ac1c19532a31bc1/bernierllc-nevar-graph-executor-0.1.1.tgz","_from":"file:bernierllc-nevar-graph-executor-0.1.1.tgz","_nodeVersion":"25.9.0","_npmVersion":"11.12.1","dist":{"integrity":"sha512-7hDZBvsuc9OkxtINHsf7383f30mOGBARTJCRpeEzyVUzx8hlsWlc6wQznTtZioFpfjmtf5gEc/gFADZcE82k6Q==","shasum":"ce9b61f1e1d1834be467c2a7b338e026b85aac72","tarball":"https://registry.npmjs.org/@bernierllc/nevar-graph-executor/-/nevar-graph-executor-0.1.1.tgz","fileCount":43,"unpackedSize":326309,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDskkUWWspf6WxQQX9PTZCfZm10QNJmZJpgsL+Ot4W3rwIgLlyUB3iVhCFrZcKw5fy0artVyXoRVK2M+Xh/poGATso="}]},"_npmUser":{"name":"mkbernier","email":"mkbernier@gmail.com"},"directories":{},"maintainers":[{"name":"alikhan410","email":"mczeyo@gmail.com"},{"name":"mkbernier","email":"mkbernier@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/nevar-graph-executor_0.1.1_1779127316346_0.9522080043697094"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-18T15:43:54.556Z","modified":"2026-05-18T18:01:56.620Z","0.0.1":"2026-05-18T15:43:54.829Z","0.1.1":"2026-05-18T18:01:56.505Z"},"license":"SEE LICENSE IN LICENSE","description":"Topological execution engine for Nevar typed-DAG graphs — dispatches nodes, resolves edge mappings, enforces idempotency","maintainers":[{"name":"alikhan410","email":"mczeyo@gmail.com"},{"name":"mkbernier","email":"mkbernier@gmail.com"}],"readme":"# @bernierllc/nevar-graph-executor\n\nTopological execution engine for Nevar typed-DAG graphs. Dispatches nodes level-by-level, resolves edge mappings between upstream outputs and downstream config, enforces idempotency, and records per-node step history.\n\n## Overview\n\n`createGraphExecutor` returns a `GraphExecutor` that runs `GraphDefinition` instances loaded from a `GraphStorageAdapter`. It does not subscribe to triggers — the calling suite (e.g. `@bernierllc/nevar`) owns that wiring and invokes `runGraph()` directly.\n\nExecution semantics:\n- Idempotency check before run creation (configurable TTL, default 60s).\n- Topological level walk with bounded concurrency (default 4).\n- Edge mappings resolved per node; root nodes receive the trigger payload merged over static config.\n- Skip propagation: nodes whose upstreams all failed/skipped or whose edge conditions evaluate false are recorded as `skipped`.\n- Failure mode: `fail-fast` (graph stops on first error) or `best-effort` (continues, final status becomes `partial` or `failed`).\n\n## Installation\n\n```bash\npnpm add @bernierllc/nevar-graph-executor\n```\n\nYou will also need the peer-style workspace packages: `@bernierllc/nevar-graph-storage`, `@bernierllc/nevar-action-executor`, and a condition evaluator from `@bernierllc/nevar-evaluator`.\n\n## Usage\n\n```typescript\nimport { createGraphExecutor } from '@bernierllc/nevar-graph-executor';\nimport { InMemoryGraphStorageAdapter } from '@bernierllc/nevar-graph-storage';\n\nconst storage = new InMemoryGraphStorageAdapter();\n\nconst executor = createGraphExecutor({\n  storage,\n  actionRegistry,        // ActionHandlerLookup\n  actionExecutor,        // ActionExecutor (single-intent dispatch)\n  conditionEvaluator,    // (tree, payload) => boolean\n});\n\nconst run = await executor.runGraph(\n  'graph-123',\n  { postId: 'post-456', authorId: 'user-789' },\n  { idempotencyTtlMs: 60_000 }\n);\n\nconsole.log(run.status); // 'succeeded' | 'failed' | 'partial'\n```\n\n### Helpers\n\n```ts\nimport {\n  computeIdempotencyKey,\n  computeTopoLevels,\n  resolveEdgeMappings,\n} from '@bernierllc/nevar-graph-executor';\n\nconst key = computeIdempotencyKey('graph-123', 'event:post.published', { postId: 'p1' });\nconst levels = computeTopoLevels(graph); // TopoLevel[]\nconst { resolvedInput, errors } = resolveEdgeMappings(node.config, incomingEdges, nodeOutputs);\n```\n\n## API\n\n### `createGraphExecutor(deps): GraphExecutor`\n\n| Dep | Type | Purpose |\n|-----|------|---------|\n| `storage` | `GraphStorageAdapter` | Persists definitions, runs, step records |\n| `actionRegistry` | `ActionHandlerLookup` | Looks up handlers by `actionType` |\n| `actionExecutor` | `ActionExecutor` | Dispatches one node as one `ActionIntent` |\n| `conditionEvaluator` | `(tree, payload) => boolean` | Evaluates edge/activation conditions |\n| `loopDetector?` | `{ check, record }` | Optional loop guard, keyed |\n| `circuitBreaker?` | `{ check, record }` | Optional circuit breaker, keyed |\n| `lifecycleEvents?` | `{ emit(event, payload) }` | Forwards deferred triggers |\n\n### `GraphExecutor.runGraph(graphId, triggerPayload, options?)`\n\n| Param | Type | Default | Description |\n|-------|------|---------|-------------|\n| `graphId` | `string` | — | Definition to execute |\n| `triggerPayload` | `Record<string, unknown>` | — | Payload that triggered this graph |\n| `options.idempotencyTtlMs` | `number` | `60_000` | Dedup window in ms |\n| `options.parentRunId` | `string` | `null` | Set when replaying a prior failed run |\n\nReturns: `Promise<GraphRun>` — either a newly created run or the existing deduplicated run.\n\n### Errors\n\n| Class | Code | When |\n|-------|------|------|\n| `NevarGraphExecutionError` | `NEVAR_GRAPH_EXECUTION_ERROR` (default), `NEVAR_GRAPH_NOT_FOUND` | Graph missing or run-time failure during execution |\n| `NevarGraphIdempotencyError` | `NEVAR_GRAPH_IDEMPOTENCY_ERROR` | Idempotency-key computation failure |\n\nAll errors carry ES2022 `cause` chains and a `context` object.\n\n## Integrations\n\n### Logger integration\nLogger integration is consumer-driven: the executor never logs directly. It surfaces `NevarGraphExecutionError` instances with `cause` chains and per-step `errorMessage` strings via the storage adapter's `appendStep`. Consumers wire `@bernierllc/logger` at the call site:\n\n```ts\nimport { formatErrorChain } from '@bernierllc/logger';\n\ntry {\n  await executor.runGraph(graphId, payload);\n} catch (err) {\n  logger.error('graph execution failed', { chain: formatErrorChain(err) });\n  throw err;\n}\n```\n\n### NeverHub integration\nNeverHub integration is optional and is owned by the suite layer (`@bernierllc/nevar`). The executor itself does not register with NeverHub — it is a pure orchestrator that operates on injected dependencies. When the consuming suite has NeverHub available it registers the executor as part of the service surface; when it is not available, the executor continues to dispatch graphs normally via the injected `actionExecutor` and `storage`.\n\n### Graceful degradation\nGraceful degradation is built into the executor's optional dependencies:\n\n- `loopDetector`, `circuitBreaker`, and `lifecycleEvents` are all optional — omit them and the corresponding feature simply no-ops.\n- When NeverHub is unavailable, the executor functions fully via its injected core dependencies.\n- Idempotency failures fall back to creating a new run; mapping errors in `best-effort` mode are recorded as step errors rather than aborting the whole run.\n\n## Related Packages\n\n- `@bernierllc/nevar-graph-types` — shared type definitions (GraphDefinition, GraphRun, etc.)\n- `@bernierllc/nevar-graph-validator` — static validation prior to execution\n- `@bernierllc/nevar-graph-storage` — storage contract (in-memory reference)\n- `@bernierllc/nevar-graph-adapter-prisma` — Prisma/PostgreSQL storage backend\n- `@bernierllc/nevar-action-executor` — single-action dispatcher used per node\n- `@bernierllc/nevar` — suite re-export (Graph namespace)\n\n## License\n\nCopyright (c) 2025 Bernier LLC. See LICENSE for details.\n","readmeFilename":"README.md","keywords":["nevar","graph","executor","dag","topological","idempotency","bernierllc"],"author":{"name":"Bernier LLC"}}