@x12i/memorix-catalog

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