# @x12i/memorix-catalog

> Host-facing metadata facade for Memorix: descriptor catalog access with zero storage backend awareness (no Catalox, Firestore, or Mongo in host code).

Latest version **1.33.0** (published 2026-07-11) · 0 weekly downloads

## Install

```sh
npm install @x12i/memorix-catalog
pnpm add @x12i/memorix-catalog
yarn add @x12i/memorix-catalog
bun add @x12i/memorix-catalog
```

## 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.33.0 |
| Published | 2026-07-11 |
| First published | 2026-07-04 |
| Weekly downloads | 0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=18.0.0 |
| Dependencies | 3 |
| Unpacked size | 46.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | x12i |
| Keywords | memorix, catalog, metadata, descriptors |

## Links

- npm: https://www.npmjs.com/package/@x12i/memorix-catalog
- Repository: https://github.com/x12i/memorix-mono-repo
- Homepage: https://github.com/x12i/memorix-mono-repo#readme
- Issues: https://github.com/x12i/memorix-mono-repo/issues
- npm.io page: https://npm.io/package/@x12i/memorix-catalog

## Dependencies (3)

- [@x12i/catalox](https://npm.io/package/@x12i/catalox.md) ^5.10.1
- [@x12i/memorix-retrieval](https://npm.io/package/@x12i/memorix-retrieval.md) ^1.33.0
- [@x12i/memorix-descriptors](https://npm.io/package/@x12i/memorix-descriptors.md) ^1.32.0

## Recent versions

- 1.33.0 (latest) — 2026-07-11
- 1.32.0 — 2026-07-11
- 1.4.1 — 2026-07-04
- 1.4.0 — 2026-07-04
- 1.3.0 — 2026-07-04
- 1.2.0 — 2026-07-04
- 1.1.1 — 2026-07-04
- 1.1.0 — 2026-07-04

## README

# @x12i/memorix-catalog

The single host-facing surface for **Memorix descriptor metadata**. Open a catalog, read entity / list / item descriptors, done. The package owns every storage concern internally — **hosts never reference Catalox, Mongo database names, or catalog bindings.**

If you are a host app (e.g. `@exellix/jobs-api`) and you only need to know *what entities/descriptors exist*, this is the only Memorix metadata package you import.

## Why

Descriptor metadata lives in **Mongo-backed Catalox**. `@x12i/memorix-catalog` keeps that decision internal. On open it probes whether descriptors exist for the app; if the store is empty it alerts — it does **not** migrate from Firestore or any other backend. Publish descriptors via seed apply or Catalox Manager.

## Install

```bash
npm install @x12i/memorix-catalog
```

## Usage

```ts
import { openMemorixCatalog } from "@x12i/memorix-catalog";

const catalog = await openMemorixCatalog();
// appId resolves from CATALOX_APP_ID → MEMORIX_APP_ID → "memorix"

const entities = await catalog.listEntities();
// [{ entityName: "assets", target: "entity", contentTypes: ["snapshots"], ... }, ...]

const assets = await catalog.getEntity("assets");
const list = await catalog.getListDescriptor("assets-main-list");
const item = await catalog.getItemDescriptor("asset-detail-item");

await catalog.close();
```

### Guaranteeing readiness explicitly

`openMemorixCatalog()` already makes the catalog ready. If you want an explicit, idempotent check (e.g. a health probe), call `ensureReady()`:

```ts
const readiness = await catalog.ensureReady();
// { ready: true, source: "mongo-existing" | "unavailable",
//   entityCount: 10, warnings: [] }
```

`source` is informational only — hosts never branch on storage details.

### Alerts — never fail silently

The original regression this package fixes was a *silent* empty result. `openMemorixCatalog` never fails silently:

- **Database unreachable / not configured** (missing `MONGO_URI`, connection error) → throws `MemorixCatalogDbUnavailableError` with a clear message.
- **Database reachable but empty** (no descriptors) → alerts via `console.warn` by default. Configure with `onMissingDescriptors`:

```ts
// Fail hard if there are no descriptors:
await openMemorixCatalog({ onMissingDescriptors: "throw" });

// Route alerts to your own logger:
await openMemorixCatalog({ onAlert: (msg) => logger.warn(msg) });
```

| `onMissingDescriptors` | Behavior when DB is empty |
|------------------------|---------------------------|
| `"warn"` (default) | Loud `console.warn` (or `onAlert`), continues |
| `"throw"` | Throws `MemorixCatalogEmptyError` |
| `"ignore"` | Silent |

## API

| Method | Returns |
|--------|---------|
| `openMemorixCatalog(options?)` | `Promise<MemorixCatalog>` |
| `catalog.appId` | resolved app id |
| `catalog.ensureReady()` | `MemorixCatalogReadiness` |
| `catalog.getSnapshot()` | full `MemorixCatalogSnapshot` |
| `catalog.listEntities()` | `MemorixCatalogEntitySummary[]` |
| `catalog.getEntity(name)` | entity descriptor or `null` |
| `catalog.listListDescriptors()` / `getListDescriptor(id)` | list descriptors |
| `catalog.listItemDescriptors()` / `getItemDescriptor(id)` | item descriptors |
| `catalog.validate()` | integrity report |
| `catalog.close()` | releases the connection pool |

### `openMemorixCatalog(options)`

| Option | Default | Purpose |
|--------|---------|---------|
| `appId` | `CATALOX_APP_ID` → `MEMORIX_APP_ID` → `memorix` | Scope for descriptor lookups |
| `processEnv` | `process.env` | Environment source |
| `skipProvision` | `false` | Skip readiness probe side effects (tests only) |

## Environment

| Var | Required | Purpose |
|-----|----------|---------|
| `MONGO_URI` | yes | Mongo cluster the metadata lives on (same one the host already uses) |
| `MEMORIX_CATALOX_DB` | recommended | **Name of the Catalox metadata database.** If unset, the catalog uses the default `memorix-catalox` and **warns** — if your descriptors live in a different database, you must set this or lookups return nothing. (Alias: `MEMORIX_DB_CATALOX`.) |
| `CATALOX_APP_ID` | yes | Scope (unchanged from prior Memorix usage) |

> The most common misconfiguration is forgetting `MEMORIX_CATALOX_DB`. The catalog alerts on this at open time so it never fails silently.

`GOOGLE_SERVICE_ACCOUNT_BASE64` is **not** required for Memorix Catalox. Keep it only where FuncX (or optional GCS) runs.

## What this package deliberately hides

- `@x12i/catalox`, `@x12i/catalox/mongo`
- `wireCataloxFromMongoStore`, catalog bindings, god-mode scoping
- Database-name selection internals

If you find yourself importing any of the above in a host app for metadata, you don't need to — use this package instead.

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