@jumentix/external-store-proxy

Bridges native database clients into the IStore shape application code expects.

What it is

Bridges native database clients into the IStore shape application code expects.

Why it exists

Use-cases should depend on IStore, not mongoose/sequelize clients. This package is the bridge.

When to use: You have an external DB client/repository and need IStore instances for application ports.

When not to use: You are still choosing a driver (start with database-client-factory) or defining contracts (persistence-contracts).

Responsibility in context

• Stack layer: persistence / adapter
• Problem boundary it owns: ExternalStoreProxy and createExternalStores.
• Used with: persistence-contracts (IStore), external-db-repositories (drivers), database-client-factory (selection).
• Typical composition: factory selects client → repositories/proxy expose IStore → use-cases call ports.
• Journeys: REST API guide persistence steps.
• Not responsible for: SQL/Mongo query dialects themselves or HTTP transport.

Prerequisites

• Bun 1.3.13+ (monorepo pin) or the Node runtime your service already uses
• Read Getting started first
• Basic TypeScript modules/import knowledge

Glossary

• Port — TypeScript contract the application depends on (no vendor types).
• Adapter — Concrete implementation that talks to a driver, broker, or protocol.
• Composition root — Process startup code that wires env → adapters → use-cases.

Numbered steps

1. Install

bun add @jumentix/external-store-proxy

2. First success (under 30 min)

import { createExternalStores } from '@jumentix/external-store-proxy';

// `client` comes from your composed database client / repository layer.
const stores = createExternalStores(client);
// Pass stores.users (etc.) into use-cases as IStore ports.

3. Core workflows

1. Create stores from a client

Call createExternalStores once at composition root.

2. Inject into use-cases

Pass IStore ports only — not the native client.

3. Test with fakes

Swap in an in-memory IStore in unit tests.

4. Full practical surface (exports)

• ExternalStoreProxy
• createExternalStores

Use exports from application/adapters layers as described above — not from domain entities.

Common errors

Verify success: the first-success snippet runs (or typechecks against your service) and your use-case depends only on ports.

Junior checklist (“I can …”)

• I can create IStore proxies without leaking driver types
• I know where this sits between factory and use-cases

Next step

Continue with database-client-factory.