multivendor-order

Order domain (lifecycle, status machine, EM-threaded transactional ports, shared-config engine mode, shadow-read cutover gates) for multi-vendor marketplaces, extracted from Myownbazaar_server.

Phase 0 scaffold. Models, repositories, status machine, and HTTP controllers move in later phases (see the move-order plan). This package currently ships the plugin shape, ports, engine-mode pin helpers, deadlock-retry backoff, and shadow-reconciliation helpers so the host can start wiring against a stable contract.

Install

pnpm add multivendor-order

Host apps pin an exact version while the extract stabilizes (e.g. "multivendor-order": "0.0.1").

TypeORM version pin

Cross-package entity metadata on a shared DataSource is fragile under version drift. peerDependencies.typeorm and devDependencies.typeorm are pinned to the exact 0.2.45 (no ^/>= range) to match the host resolved version. Bumping TypeORM is a coordinated host + all-plugins change, out of scope for this package alone.

Host wiring

import {
  registerOrderPlugin,
  ORDER_PLUGIN_TOKEN,
  getOrderOrmMetadata,
} from 'multivendor-order';

const plugin = registerOrderPlugin({
  dataSource: connection,
  cart, catalog, pricing, customer, vendor, payment, shipping,
  affiliate, dropship, settings, wallet, // ports, see src/ports.ts
  flags: { defaultEngineMode: 'host', engineModeCacheTtlMs: 5000 },
});

Use getOrderOrmMetadata() when order.engine resolves to package. Keep host entity classes registered while order.engine=host so ORM metadata is not swapped before package code serves traffic (currently a no-op — see MIGRATION_CONTINUITY.md).

Engine mode (host / package / shadow)

Driven by the shared SettingService key order.engine, read through one helper across web/cron/BullMQ workers, TTL-cached ≤ 5s. See ROLLBACK.md for the full consistency/rollback model and named Cutover Owner.

Long-running writes must pin the mode once and re-assert it at TX entry — see TRANSACTION.md and src/engine/orderEngineMode.ts.

Transactional ports

Every port method that mutates same-DB state accepts an EntityManager first argument so it joins the caller's outer transaction — see src/ports.ts and TRANSACTION.md (lock order, compensation table, deadlock retry).

Deadlock retry

retryWithDeadlockBackoff (src/engine/deadlockRetry.ts) retries ER_LOCK_DEADLOCK failures with exponential backoff + full jitter (base 50ms, cap 1000ms, max 3 attempts total). See TRANSACTION.md.

Shadow-read reconciliation

computeReconciliationMs / reconcileShadowCompare (src/shadow/reconcile.ts) implement the retry-compare classification (match / transient / mismatch) described in the move-order plan's shadow-read exit gate. The reconciliation window must come from a measured commit-to-visible p99 — the helper throws if given a non-positive value rather than silently accepting a guessed constant.

Docs

• TRANSACTION.md — EM ports, compensation table, lock order, deadlock retry, engine pin + TX-entry re-assert.
• ROLLBACK.md — Cutover Owner, rollback table per phase, observability.
• MIGRATION_CONTINUITY.md — historical migrations stay host-owned; class-name continuity rule for any future package migration.

Publish tags

order-v* (e.g. order-v0.0.1).