import { setup } from '@backtest-kit/mongo';
setup({
  CC_MONGO_CONNECTION_STRING: 'mongodb://mongo:27017/mydb',
  CC_REDIS_HOST: 'redis', CC_REDIS_PORT: 6379, CC_REDIS_PASSWORD: 'secret',
});

Values passed to setup() / setConfig() always take precedence over env vars. Within the CLI, put setup() in config/setup.config.ts — when present, the CLI skips its default file-adapter registration and your config owns persistence.

• Candle is immutable — first write wins; subsequent writes to the same (symbol, interval, timestamp) are silently ignored via $setOnInsert (historical OHLCV never changes).
• All others use $set — each write replaces the previous value.
• Measure / Interval / Memory soft-delete — removeMeasureData / removeIntervalData / removeMemoryData set removed: true rather than deleting; listings filter on removed: false, keeping a full audit trail.

Every domain is two layers: a DbService (MongoDB) and a CacheService (Redis). Reading state for a context key asks Redis for the Mongo _id first; a hit is two O(1) ops, a miss falls back to an indexed findOne and backfills Redis.

read signal for (BTCUSDT, my_strategy, binance)
  ├─ Redis GET → hit  → Mongo findById(_id)        ← O(1) + O(1)
  └─ Redis GET → miss → Mongo findOne(filter) → Redis SET → return

After every write the Redis entry is refreshed in the same call, so write-then-read always hits the cache.

backtest-kit requires that once write*Data() returns, the next read*Data() sees the new value. Every write is one findOneAndUpdate round-trip:

const document = await SignalModel.findOneAndUpdate(
  { symbol, strategyName, exchangeName },
  { $set: { payload } },
  { upsert: true, new: true, setDefaultsOnInsert: true },
);
await signalCacheService.setSignalId(readTransform(document.toJSON()));

The filter matches the unique compound index, so MongoDB rejects any concurrent duplicate insert at the storage engine; the returned document is written straight to Redis, making the next read O(1) on fresh data.

Adapters whose data influences decisions (Risk, Partial, Breakeven, Recent, State, Budget, Session, Memory, Interval) store when: Number — the simulation timestamp in ms — alongside the payload, so backtest-kit can verify no read returns data written at a future simulation time. Measure is exempt because it caches LLM / external-API responses, where look-ahead bias is not meaningful.

Public surface — functions/setup.ts (setup/install/setConfig/getConfig/setLogger), index.ts re-exports + getMongo/getRedis.

Adapter classes (classes/Persist*Instance.ts, 17) — each implements one backtest-kit IPersist*Instance contract and delegates to its domain DbService: PersistCandleInstance, PersistSignalInstance, PersistStrategyInstance, PersistScheduleInstance, PersistRiskInstance, PersistPartialInstance, PersistBreakevenInstance, PersistStorageInstance, PersistNotificationInstance, PersistLogInstance, PersistMeasureInstance, PersistIntervalInstance, PersistMemoryInstance, PersistRecentInstance, PersistStateInstance, PersistBudgetInstance, PersistSessionInstance.

Service layer (lib/services/):

• base/ — MongoService (lazy Mongoose connection), RedisService (lazy ioredis), LoggerService.
• db/ — one *DbService per domain: the Mongoose models, schemas, unique compound indexes, and findOneAndUpdate upsert logic.
• cache/ — one *CacheService per domain (CandleCacheService, SignalCacheService, BreakevenCacheService, IntervalCacheService, LogCacheService, MeasureCacheService, MemoryCacheService, NotificationCacheService, PartialCacheService, RecentCacheService, …): Redis _id mapping for O(1) lookups.

Shared primitives (lib/common/) — BaseCRUD (the upsert/read/remove pattern every DbService reuses) and BaseMap (the Redis key-mapping pattern every CacheService reuses).

DI & config — lib/core/{di,provide,types}.ts (IoC container wiring Db/Cache/base services), lib/index.ts (container bootstrap), config/{mongo,redis,params}.ts (connection builders + merged params), interfaces/Logger.interface.ts.