# @exellix/catalox-graphs

> Catalox graph catalog data tier (Node): CRUD stores, document loaders, and readiness probes.

Latest version **1.5.1** (published 2026-07-11) · exellix-license license · 0 weekly downloads

## Install

```sh
npm install @exellix/catalox-graphs
pnpm add @exellix/catalox-graphs
yarn add @exellix/catalox-graphs
bun add @exellix/catalox-graphs
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 1.5.1 |
| Published | 2026-07-11 |
| First published | 2026-06-22 |
| Weekly downloads | 0 |
| License | exellix-license |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=20 |
| Dependencies | 4 |
| Unpacked size | 199.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | exellix |
| Keywords | exellix, catalox, graphs, graphs-studio |

## Links

- npm: https://www.npmjs.com/package/@exellix/catalox-graphs
- Repository: https://github.com/exellix/exellix-engine-mono-repo
- Homepage: https://github.com/exellix/exellix-engine-mono-repo#readme
- Issues: https://github.com/exellix/exellix-engine-mono-repo/issues
- npm.io page: https://npm.io/package/@exellix/catalox-graphs

## Dependencies (4)

- [@x12i/catalox](https://npm.io/package/@x12i/catalox.md) ^6.0.0
- [@x12i/graphenix-core](https://npm.io/package/@x12i/graphenix-core.md) ^2.16.0
- [@x12i/graphenix-authoring-format](https://npm.io/package/@x12i/graphenix-authoring-format.md) ^2.16.0
- [@x12i/graphenix-executable-contracts](https://npm.io/package/@x12i/graphenix-executable-contracts.md) ^2.16.0

## Alternatives

- [d3-force-3d](https://npm.io/package/d3-force-3d.md) — 1.0M weekly downloads
- [ng2-charts](https://npm.io/package/ng2-charts.md) — 486.8K weekly downloads
- [@arcgis/core](https://npm.io/package/@arcgis/core.md) — 257.8K weekly downloads
- [react-sparklines](https://npm.io/package/react-sparklines.md) — 249.3K weekly downloads
- [react-native-gifted-charts](https://npm.io/package/react-native-gifted-charts.md) — 182.3K weekly downloads

## Recent versions

- 1.5.1 (latest) — 2026-07-11
- 1.5.0 — 2026-07-05
- 1.4.3 — 2026-07-05
- 1.4.2 — 2026-07-05
- 1.4.1 — 2026-06-30
- 1.4.0 — 2026-06-27
- 1.3.2 — 2026-06-26
- 1.3.1 — 2026-06-25
- 1.3.0 — 2026-06-25
- 1.2.9 — 2026-06-24
- 1.2.8 — 2026-06-23
- 1.2.7 — 2026-06-23
- 1.2.6 — 2026-06-23
- 1.2.5 — 2026-06-23
- 1.2.4 — 2026-06-23
- … 4 more at https://npm.io/package/@exellix/catalox-graphs/versions

## README

# @exellix/catalox-graphs

Node data tier for Catalox graph catalogs: CRUD stores, version checkpoints, templates, execute-time loaders, and readiness probes.

**Authoritative store:** Catalox catalog `graphs` (full `AuthoringGraphDocument`). Mongo `exellix.graphs` is matrix id-registry only.

Related packages (split by layer):

| Package | Layer |
|---------|-------|
| `@exellix/catalox-graphs` | **Data tier** — stores, loaders, Catalox runtime (this package) |
| `@exellix/catalox-graphs-http` | **HTTP BFF** — Fastify `/api/catalox/*` routes |
| `@exellix/catalox-graphs-ui` | **Browser + React** — fetch client, `CataloxGraphPicker`, `CataloxGraphLibrary` |

## Exports

| Import | Use |
|--------|-----|
| `@exellix/catalox-graphs` | `saveGraphToCatalox`, `loadGraphFromCatalox`, `createExecuteGraphLoader`, stores, types |

### Catalox runtime client

Hosts that need direct access to the bound Catalox SDK (outside the graph-store helpers) use:

| Export | Role |
|--------|------|
| `getCataloxBound()` | Lazily initialized Catalox client bound to `CATALOX_APP_ID` / credentials from env |
| `getRawCatalox()` | Same client without app binding — used when resolving skills across Catalox apps |
| `resetCataloxRuntimeCache()` | Clear cached client (tests / hot reload) |
| `seedCataloxBound(client)` | Inject a test double |

For HTTP routes use `@exellix/catalox-graphs-http`. For browser/React use `@exellix/catalox-graphs-ui`.

## Env

Catalox 6 Mongo (same as host apps):

- `MONGO_URI` (required)
- `MONGO_DB_NAME` (optional; default `catalox`)
- `CATALOX_APP_ID` (e.g. `graphs-studio`)
- `CATALOX_STORE_ID` (optional Catalox context store pin)
- `CATALOX_GOD_MODE` (optional service superAdmin)

## HTTP routes

Mount BFF from the sibling package:

```ts
import { registerCataloxGraphRoutes } from '@exellix/catalox-graphs-http';

await registerCataloxGraphRoutes(app, { prefix: '/api/catalox' });
```

Key endpoints:

- `GET /api/catalox/status`
- `GET /api/catalox/graphs?compatible=1&entityName=&contentType=`
- `GET|PUT|DELETE /api/catalox/graphs/:itemId`
- `GET|PUT|DELETE /api/catalox/graph-versions/:graphId/:versionId`
- `GET|PUT|DELETE /api/catalox/graph-templates/:templateKey`
- Generic catalog CRUD under `/api/catalox/catalogs/:catalogId/items/:itemId`

## React picker

```tsx
import { CataloxGraphPicker } from '@exellix/catalox-graphs-ui/react';

<CataloxGraphPicker
  value={graphId}
  onChange={(id) => setGraphId(id)}
  entityName="subnets"
  contentType="snapshots"
  filterCompatible
/>
```

## graphs-studio integration

See [docs/STUDIO_INTEGRATION.md](./docs/STUDIO_INTEGRATION.md). Pair with [`@x12i/memorix-mongo`](../memorix-mongo/docs/STUDIO_INTEGRATION.md) for job memory context.

## Catalogs owned

- `graphs` — working graph projects
- `graph-versions` — version checkpoints
- `graph-templates` — saved/system templates
- `graph-concepts` — legacy concept rows (dual-write optional in studio)

## Migration from 1.2.x

Subpath exports moved to dedicated packages:

| Before | After |
|--------|-------|
| `@exellix/catalox-graphs/http` | `@exellix/catalox-graphs-http` |
| `@exellix/catalox-graphs/browser` | `@exellix/catalox-graphs-ui` |
| `@exellix/catalox-graphs/react` | `@exellix/catalox-graphs-ui/react` |

## Ops — graphKind taxonomy

```bash
npm run build
npm run provision:graph-kind              # upsert descriptor 1.1.0 + verify list filters
npm run provision:graph-kind -- --backfill  # + backfill existing graph rows
npm run backfill:graph-kind -- --dry-run
```

From jobs-api: `npm run provision:catalox-graphs` / `provision:catalox-graphs:full`

## Publish

Requires root `.npmrc` with your npm token (copy from `.npmrc.example` at repo root).

```bash
# This package only
cd catalox-graphs && npm run release

# Plan without publishing
npm run release:dry

# All three catalox packages in order (graphs → http → ui)
node ../scripts/publish-all.mjs --packages catalox-graphs,catalox-graphs-http,catalox-graphs-ui --no-bump
```

From repo root: `npm run publish:all` publishes the full core chain in dependency order.

---
_Source: https://npm.io/package/@exellix/catalox-graphs · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._