@exellix/exellix-matrix-persister

Mongo-backed factory for Exellix execution-matrix persistence: operational collections (rows, failures, snapshots) plus matrix and graph config collections. Host apps import createExellixMatrixDataTier instead of wiring mongodb or @x12i/xronox-store themselves.

Domain behavior (claims, materialization, filters) stays in @exellix/exellix-runtime. This package is the supported wiring surface for workers and read tiers.

Install

npm install @exellix/exellix-matrix-persister @exellix/exellix-runtime

@exellix/exellix-runtime is a peer dependency (install it next to this package).

Private registry (GitHub Packages)

If @exellix/* is published to GitHub npm, set a token and .npmrc (do not commit tokens):

@exellix:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}

Export NODE_AUTH_TOKEN (PAT with read:packages) before npm install.

Usage

import { createExellixMatrixDataTier } from '@exellix/exellix-matrix-persister';

const tier = await createExellixMatrixDataTier({
  mongoUri: process.env.MONGO_URI,
  executionDb: 'exellix-runtime',
  configDb: 'exellix',
});

await tier.init?.();

// Pass into createMatrixWorker / openMatrixReadTier / createExecutionMatrixRuntime
const { rows, failures, snapshots, matrices, graphs } = tier;

await tier.close();

Returned shape

| Field | Role | |-------------|------| | rows | Execution matrix rows | | failures | Failure records | | snapshots | Snapshot side-channel | | matrices | Matrix configs (exellix_matrix_configs) | | graphs | Graph configs (exellix_graph_configs) | | init? | Optional warm-up (no-op after factory; safe to call) | | close | Closes stores and any Mongo driver pass-through | | probe? | { executionStore, configStore, executionMongoUri, configMongoUri } for dependency health checks |

Collection names and indexes follow @exellix/exellix-runtime (src/execution-matrix/collections.ts).

Environment

| Variable | Default | Used by | |----------------|-------------------|---------| | MONGO_URI | (required) | Connection string | | execution_db | exellix-runtime | Rows, failures, snapshots | | config_db | exellix | Matrix + graph configs |

Options passed to createExellixMatrixDataTier({ ... }) override env for that call.

Consumers

@exellix/exellix-jobs and @exellix/exellix-matrix-read try this package first for createExellixMatrixDataTier, then @x12i/xmemory-store if the factory is re-exported there later. Installing @exellix/exellix-matrix-persister is enough for openExellixMatrixPersistenceFromXmemoryStore / openMatrixPersistenceFromXmemoryStore to succeed without host glue.

API surface

• createExellixMatrixDataTier(options?) — main factory
• resolveExellixMatrixDataTierOptions(overrides?, env?) — merge options + process.env (throws if mongoUri missing)
• loadMatrixDataTierFactory() — resolves the factory from this package or @x12i/xmemory-store (for advanced dynamic wiring)

Types are exported from the package entry (CreateExellixMatrixDataTierOptions, ExellixMatrixDataTier, etc.).

Development

npm install
npm run build
npm test

Live tests (real Mongo)

1. Copy .env.example → .env and set MONGO_URI (and optional execution_db / config_db).
2. Run:

npm run test:live

The default npm test suite skips live tests when MONGO_URI is unset. Vitest is configured with MODE=debug so importing @exellix/exellix-runtime in tests does not fail on @x12i/funcx mode checks.

More detail: docs/integration.md. For a minimal env template, see .env.example.

Specification

Normative persistence contract: createExellixMatrixDataTier in @exellix/exellix-runtime — see client-integration.md.

License

UNLICENSED (internal Exellix package unless published otherwise).