@x12i/catalox-engine

The Catalox catalog engine: runtime API, Firestore/Mongo persistence, operator helpers, mapping module, and the catalox CLI binary.

Part of the Catalox monorepo. Published on npm as a workspace package; consumers often install the root @x12i/catalox meta package instead.

Role

| Responsibility | Details | |----------------|---------| | Runtime | createCatalox, Catalox, CataloxBound — list/get/write catalogs and items | | Persistence | Firestore stores (default), Mongo primary/mapped adapters | | Authorization | Bindings, scope lenses, structured outcomes | | Operator | Seed presets, backup/GCS, record history, validation, markdown/diagrams | | CLI | catalox — firestore, seed, items, toolbox, history, catalog |

Install

npm install @x12i/catalox-engine @x12i/catalox-contracts

Requires Node >=20.

Import surfaces

| Subpath | Export | |---------|--------| | @x12i/catalox-engine | Full index (embedder + operator re-exports) | | @x12i/catalox-engine/embedder | createCatalox, Catalox, adapters, errors | | @x12i/catalox-engine/operator | Backup, GCS, bindings, ContextResolver, etc. | | @x12i/catalox-engine/firebase | createCataloxFromEnv, testFirestoreConnectionFromEnv | | @x12i/catalox-engine/mongo | createCataloxFromMongoEnv, MongoStore | | @x12i/catalox-engine/mapping | validateMappingSpec, executeMapping |

Equivalent paths on root package: @x12i/catalox/embedder, /firebase, etc.

Quick start

import { createCataloxFromEnv } from "@x12i/catalox-engine/firebase";

const { catalox } = createCataloxFromEnv();
const scoped = catalox.withContext({ appId: "myApp" });
const { listOutcome, items } = await scoped.listCatalogItems("signals", { limit: 50 });

# CLI (after build)
node dist/cli/index.js firestore probe
# or: npx catalox (via @x12i/catalox / @x12i/catalox-cli)

Build & test

npm run build -w @x12i/catalox-engine
npm test -w @x12i/catalox-engine
npm run test:integration -w @x12i/catalox-engine  # live Firestore

Package layout

| Path | Purpose | |------|---------| | src/catalox/ | Core Catalox class, bound context, seed presets | | src/firebase/ | Firestore stores, bootstrap | | src/mongo/ | Mongo persistence | | src/cli/ | Commander CLI entry | | src/mapping/ | Mapped catalog field mapping | | presets/ | Built-in seed manifest presets | | schemas/ | JSON schemas for manifests | | test/ | Unit + integration tests |

Dependencies

• @x12i/catalox-contracts — shared types
• firebase-admin, mongodb, @google-cloud/storage
• @x12i/helpers, @x12i/logxer
• Optional: react, react-dom (renderer snippet HTML path)

Documentation

• Root README — overview and doc index
• Onboarding
• Environment
• Native storage
• CLI items
• Deployment

Related packages

| Package | Relationship | |---------|--------------| | @x12i/catalox-contracts | Types consumed by engine | | @x12i/catalox-api | HTTP wrapper over this engine | | @x12i/catalox-cli | Bin re-export of this package's CLI |