@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

npm install @x12i/memorix-catalog

Usage

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():

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:

// 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.