# @x12i/xronox-router

> Request routing and tenant resolution for Xronox with dynamic provisioning support

Latest version **2.3.1** (published 2026-04-27) · MIT license · 0 weekly downloads

## Install

```sh
npm install @x12i/xronox-router
pnpm add @x12i/xronox-router
yarn add @x12i/xronox-router
bun add @x12i/xronox-router
```

## Health

**Score 60/100 (C)** — status: active.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 2.3.1 |
| Published | 2026-04-27 |
| First published | 2026-04-25 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 5 |
| Unpacked size | 442.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | x12i |
| Maintainers | x12i |
| Keywords | xronox, routing, multi-tenant, dynamic-provisioning |

## Links

- npm: https://www.npmjs.com/package/@x12i/xronox-router
- Repository: https://github.com/x12i/xronox-router
- Homepage: https://github.com/x12i/xronox-router#readme
- Issues: https://github.com/x12i/xronox-router/issues
- npm.io page: https://npm.io/package/@x12i/xronox-router

## Dependencies (5)

- [mongodb](https://npm.io/package/mongodb.md) ^6.3.0
- [@x12i/env](https://npm.io/package/@x12i/env.md) ^4.0.1
- [@x12i/logxer](https://npm.io/package/@x12i/logxer.md) ^4.2.1
- [@aws-sdk/client-s3](https://npm.io/package/@aws-sdk/client-s3.md) ^3.450.0
- [@azure/storage-blob](https://npm.io/package/@azure/storage-blob.md) ^12.28.0

## Alternatives

- [express-promise-router](https://npm.io/package/express-promise-router.md) — 736.1K weekly downloads
- [next-usequerystate](https://npm.io/package/next-usequerystate.md) — 29.8K weekly downloads
- [@bitkyc08/opencodex](https://npm.io/package/@bitkyc08/opencodex.md) — 4.6K weekly downloads
- [lynkr](https://npm.io/package/lynkr.md) — 575 weekly downloads
- [baremetal.js](https://npm.io/package/baremetal.js.md) — 42 weekly downloads

## Recent versions

- 2.3.1 (latest) — 2026-04-27
- 2.3.0 — 2026-04-27
- 2.2.0 — 2026-04-25

## README

# @x12i/xronox-router

Request routing and tenant resolution for Xronox with dynamic provisioning support.

## 🚀 Env-Ready Component (ERC 2.0)

This component supports **zero-config initialization** via environment variables using `@x12i/env`.

### Quick Start

```bash
# 1. Install the package
npm install @x12i/xronox-router

# 2. Copy .env.example to .env (if using zero-config mode)
cp node_modules/@x12i/xronox-router/.env.example .env

# 3. Fill in required values in .env
# MONGO_URI=mongodb://localhost:27017
# S3_ENDPOINT=http://localhost:9000
# S3_REGION=us-east-1
# S3_ACCESS_KEY=your-access-key
# S3_SECRET_KEY=your-secret-key

# 4. Use with zero config!
import { BridgeRouter } from '@x12i/xronox-router';
const router = new BridgeRouter(); // Auto-discovers from process.env
```

### Configuration Priority

The router supports **3-tier configuration priority**:

1. **Tier 1: Explicit Config (Advanced Mode)** - Pass configuration directly to constructor
   ```typescript
   const router = new BridgeRouter({
     dbConnections: { primary: { mongoUri: 'mongodb://...' } },
     spacesConnections: { s3: { /* ... */ } },
     databases: { /* ... */ }
   });
   ```

2. **Tier 2: Config File** - Place `xronox.config.json` in your project root
   ```json
   {
     "xronox": {
       "dbConnections": {
         "primary": {
           "mongoUri": "ENV.MONGO_URI"
         }
       },
       "spacesConnections": {
         "s3-primary": {
           "endpoint": "ENV.S3_ENDPOINT",
           "region": "ENV.S3_REGION",
           "accessKey": "ENV.S3_ACCESS_KEY",
           "secretKey": "ENV.S3_SECRET_KEY"
         }
       },
       "databases": { /* ... */ }
     }
   }
   ```
   **Location**: `xronox.config.json` in project root (same directory as `package.json`)

3. **Tier 3: Environment Variables (Zero-Config Mode)** - Auto-discover from `.env` file
   ```typescript
   const router = new BridgeRouter(); // Uses environment variables
   ```

### Advanced Mode (Programmatic Configuration)

```typescript
import { BridgeRouter } from '@x12i/xronox-router';

const router = new BridgeRouter({
  dbConnections: { 
    primary: { mongoUri: 'mongodb://localhost:27017' } 
  },
  spacesConnections: { 
    s3: { 
      endpoint: 'http://localhost:9000',
      region: 'us-east-1',
      accessKey: 'minioadmin',
      secretKey: 'minioadmin'
    } 
  },
  databases: {
    metadata: {
      genericDatabase: {
        dbConnRef: 'primary',
        spaceConnRef: 's3',
        dbName: 'athenix_metadata',
        recordsBucket: 'metadata-records'
      },
      domainsDatabases: [],
      tenantDatabases: []
    }
  },
  hashAlgo: 'rendezvous'
});

const backend = router.route(ctx);
console.log(`Routed to: ${backend.mongoUri}`);
```

## Features

- Consistent hashing (Rendezvous/Jump Hash)
- Multi-tier architecture support
- Dynamic tenant provisioning
- Template-based naming
- Multi-bucket support
- Storage adapter abstraction
- **ERC 2.0 compliant** - Zero-config initialization

## Logging

By default, `@x12i/xronox-router` emits **error-only** logs (quiet by default).

To enable richer local logs (debug/info/warn), set:

```dotenv
ENABLE_XRONOX_ROUTER_LOGXER=true
XRONOX_ROUTER_LOGS_LEVEL=debug
```

- If `ENABLE_XRONOX_ROUTER_LOGXER` is missing/empty/not `"true"` → rich logging is **disabled** and the effective level is forced to **`error`**.
- If `ENABLE_XRONOX_ROUTER_LOGXER=true` → `XRONOX_ROUTER_LOGS_LEVEL` controls the effective level:
  - `debug | info | warn | error | off`
- Legacy support: `XRONOX_ROUTER_LOG_LEVEL` is used only if `XRONOX_ROUTER_LOGS_LEVEL` is not set.

## Environment Variables

See `.env.example` for the complete list of required and optional variables with descriptions.

### Required Variables

- `MONGO_URI` - MongoDB connection URI (required by mongodb package)
- `S3_ENDPOINT` - S3-compatible storage endpoint URL (required by @aws-sdk/client-s3)
- `S3_REGION` - AWS region for S3 storage (required by @aws-sdk/client-s3)
- `S3_ACCESS_KEY` - S3 access key ID (required by @aws-sdk/client-s3)
- `S3_SECRET_KEY` - S3 secret access key (required by @aws-sdk/client-s3, sensitive)

### Optional Variables

All database names and bucket names have defaults. See `.env.example` for full list.

## ERC 2.0 Compliance

- ✅ Auto-discovers configuration from environment variables
- ✅ Type-safe with automatic coercion and validation
- ✅ All dependency requirements documented (ERC and non-ERC)
- ✅ Transitive requirements automatically merged
- ✅ Automatic manifest and `.env.example` generation

### Dependencies

- ✅ **@x12i/logxer** (ERC 2.0) - requirements auto-merged
- ℹ️ **mongodb** (non-ERC) - requirements manually documented
- ℹ️ **@aws-sdk/client-s3** (non-ERC) - requirements manually documented
- ℹ️ **@azure/storage-blob** (non-ERC) - requirements manually documented
- ✅ **@x12i/env** (Configuration engine)

### Verification

Verify ERC 2.0 compliance:

```bash
npx @x12i/env erc-verify
```

## Documentation

See `specification.md` for complete API documentation.

## License

MIT

---
_Source: https://npm.io/package/@x12i/xronox-router · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._