{"_id":"@bernierllc/nevar-graph-storage","_rev":"2-a6705a271d057336201d8092e37623ae","name":"@bernierllc/nevar-graph-storage","dist-tags":{"latest":"0.1.1"},"versions":{"0.0.1":{"name":"@bernierllc/nevar-graph-storage","version":"0.0.1","license":"SEE LICENSE IN README.md","_id":"@bernierllc/nevar-graph-storage@0.0.1","maintainers":[{"name":"alikhan410","email":"mczeyo@gmail.com"},{"name":"mkbernier","email":"mkbernier@gmail.com"}],"dist":{"shasum":"bdaa0422b3f6ee78f6a464c0bd9c6e3faa480456","tarball":"https://registry.npmjs.org/@bernierllc/nevar-graph-storage/-/nevar-graph-storage-0.0.1.tgz","fileCount":2,"integrity":"sha512-fzJ2kA8V4Hqyx6Fz1tOXvp4GnBeW1rc+iPf6od10EqKSAHJnzcRlTx/ebYESq4KZj5UzS5q0OxSBUK9k5yK1qg==","signatures":[{"sig":"MEUCIBXdcJoqpWwmriqobIF2MBj8tW9adV5j1y5uqIclyIPbAiEAiZOzA3HC1gMqjRdunG9kEDmWXVzs+UGbtaveXG+BNg4=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":389},"_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-storage_0.0.1_1779119032183_0.584722533370057","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@bernierllc/nevar-graph-storage","version":"0.1.1","description":"Storage interface + in-memory adapter + conformance test suite for Nevar Graph definitions, runs, and step records","main":"dist/index.js","types":"dist/index.d.ts","keywords":["nevar","graph","storage","adapter","in-memory","conformance","bernierllc"],"author":{"name":"Bernier LLC"},"license":"SEE LICENSE IN LICENSE","dependencies":{"uuid":"^9.0.0","@bernierllc/nevar-graph-types":"0.1.2"},"devDependencies":{"@types/jest":"^29.5.0","@types/node":"^20.0.0","@types/uuid":"^9.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-storage@0.1.1","_integrity":"sha512-dK5oMsLWrszmIKxSj9S75hkhFegyBJPRrWfGJHwnr6VA8Cl/4YFx21evk3tTL/DdONDSfnpOc4Foai57KZUzCw==","_resolved":"/private/var/folders/r0/wspnzd1s18sfjy10ffyv2qxw0000gn/T/6bb48f5076cff6c3bae9c17417eaacfa/bernierllc-nevar-graph-storage-0.1.1.tgz","_from":"file:bernierllc-nevar-graph-storage-0.1.1.tgz","_nodeVersion":"25.9.0","_npmVersion":"11.12.1","dist":{"integrity":"sha512-dK5oMsLWrszmIKxSj9S75hkhFegyBJPRrWfGJHwnr6VA8Cl/4YFx21evk3tTL/DdONDSfnpOc4Foai57KZUzCw==","shasum":"32badf0bcaf61fcd52d02db93605a8e395719244","tarball":"https://registry.npmjs.org/@bernierllc/nevar-graph-storage/-/nevar-graph-storage-0.1.1.tgz","fileCount":40,"unpackedSize":252353,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDfS/572OcJQyGhIdP1f+e0bFLQl/ViJ6r5GmQokq6vfwIgWxP31KSJyPJy2GgPVlPD5PRgVhFPJqcQBamIJP9bjis="}]},"_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-storage_0.1.1_1779127304329_0.7210377448918712"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-18T15:43:52.066Z","modified":"2026-05-18T18:01:44.783Z","0.0.1":"2026-05-18T15:43:52.312Z","0.1.1":"2026-05-18T18:01:44.514Z"},"license":"SEE LICENSE IN LICENSE","description":"Storage interface + in-memory adapter + conformance test suite for Nevar Graph definitions, runs, and step records","maintainers":[{"name":"alikhan410","email":"mczeyo@gmail.com"},{"name":"mkbernier","email":"mkbernier@gmail.com"}],"readme":"# @bernierllc/nevar-graph-storage\n\nStorage interface + in-memory adapter + conformance test suite for Nevar Graph.\n\n## Overview\n\nThis package defines `GraphStorageAdapter` — the storage contract that all Nevar Graph backends implement. It ships:\n\n- `GraphStorageAdapter` — TypeScript interface for graph definitions, runs, and step records\n- `InMemoryGraphStorageAdapter` — reference implementation (suitable for tests, local development)\n- `runStorageConformance()` — Jest-based test helper that verifies any adapter meets the contract\n- `NevarGraphStorageError` — typed error for storage failures\n\n## Installation\n\n```bash\npnpm add @bernierllc/nevar-graph-storage\n```\n\n## Usage\n\n### In-memory adapter\n\n```typescript\nimport { InMemoryGraphStorageAdapter } from '@bernierllc/nevar-graph-storage';\n\nconst storage = new InMemoryGraphStorageAdapter();\n\n// Create a graph\nconst graph = await storage.createGraph({\n  name: 'Content Pipeline',\n  description: 'Processes published posts',\n  ownerType: 'organization',\n  ownerId: 'org-123',\n  triggerKey: 'event:post.published',\n  rootNodeIds: ['node-fetch'],\n  nodes: [{ id: 'node-fetch', actionType: 'action:fetch-post', config: {} }],\n  edges: [],\n  metadata: {},\n});\n\n// Start a run\nconst run = await storage.createRun({\n  graphDefinitionId: graph.id,\n  triggerKey: 'event:post.published',\n  triggerPayload: { postId: 'post-456' },\n  status: 'running',\n  startedAt: new Date(),\n  completedAt: null,\n  parentRunId: null,\n  idempotencyKey: 'sha256-of-payload',\n});\n```\n\n## API\n\n### GraphStorageAdapter Interface\n\n```typescript\ninterface GraphStorageAdapter {\n  // Graph definitions\n  createGraph(def): Promise<GraphDefinition>;\n  getGraph(id): Promise<GraphDefinition | null>;\n  updateGraph(id, patch): Promise<GraphDefinition>;\n  listGraphs(filter): Promise<GraphDefinition[]>;\n  deleteGraph(id): Promise<void>;         // soft delete\n\n  // Runs\n  createRun(run): Promise<GraphRun>;\n  findRecentRunByIdempotencyKey(key, ttlMs): Promise<GraphRun | null>;\n  updateRun(id, patch): Promise<GraphRun>;\n  getRun(id): Promise<GraphRun | null>;\n  listRunsForGraph(graphId, opts?): Promise<GraphRun[]>;\n\n  // Step records\n  appendStep(record): Promise<GraphStepRecord>;\n  listStepsForRun(runId): Promise<GraphStepRecord[]>;\n}\n```\n\n## Conformance Testing\n\nWhen implementing a new storage adapter, run the conformance suite to verify correctness:\n\n```typescript\n// In your adapter's test file:\nimport { runStorageConformance } from '@bernierllc/nevar-graph-storage';\nimport { PrismaGraphStorageAdapter } from '@bernierllc/nevar-graph-adapter-prisma';\n\ndescribe('PrismaGraphStorageAdapter conformance', () => {\n  runStorageConformance(() => new PrismaGraphStorageAdapter(prismaClient));\n});\n```\n\nThe conformance suite covers 9 scenarios:\n1. GraphDefinition CRUD (create, get, update, soft-delete, list)\n2. listGraphs filter by triggerKey\n3. listGraphs filter by ownerId\n4. Run lifecycle (create → update → get → list)\n5. findRecentRunByIdempotencyKey within TTL\n6. findRecentRunByIdempotencyKey past TTL\n7. Step records (append × 3, list ordered by startedAt)\n8. parentRunId chain\n9. listRunsForGraph with status filter + limit\n\n## Integrations\n\n### Logger integration\nLogger integration is consumer-driven. The adapter surfaces `NevarGraphStorageError` with full ES2022 `cause` chains; callers wrap storage calls and log via `@bernierllc/logger`:\n\n```ts\nimport { getErrorChain } from '@bernierllc/logger';\nimport { InMemoryGraphStorageAdapter } from '@bernierllc/nevar-graph-storage';\n\nconst storage = new InMemoryGraphStorageAdapter();\ntry {\n  await storage.createRun(runInput);\n} catch (err) {\n  logger.error('graph run creation failed', { chain: getErrorChain(err) });\n  throw err;\n}\n```\n\n### NeverHub integration\nNeverHub integration is N/A at this layer — this is a utility service (storage contract + in-memory reference adapter), not a service orchestrator. The orchestrator that consumes this adapter (`@bernierllc/nevar-graph-executor` and the `nevar` suite) owns NeverHub registration. This adapter operates as a pure data layer with no side effects beyond its storage target.\n\n### Graceful degradation\nGraceful degradation is built in: `InMemoryGraphStorageAdapter` works with zero configuration, requires no network, and never depends on optional integrations. If NeverHub or external logging is unavailable, storage operations continue to function normally — the package functions fully without any optional integration being present.\n\n## Related Packages\n\n- `@bernierllc/nevar-graph-types` — shared type definitions\n- `@bernierllc/nevar-graph-validator` — static validation for GraphDefinition\n- `@bernierllc/nevar-graph-adapter-prisma` — Prisma/PostgreSQL storage backend\n- `@bernierllc/nevar-graph-executor` — executes graphs using a storage adapter\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","storage","adapter","in-memory","conformance","bernierllc"],"author":{"name":"Bernier LLC"}}