mongo-alias

library1.0.13jsnpmunverified

A lightweight aliasing layer on top of the MongoDB Node.js driver that translates long field names to short keys for storage optimization. Current stable version is 1.0.13, released sporadically as a single-developer project. Unlike Mongoose, mongo-alias does not override native driver commands, keeping full control of the DB object and enabling direct logging. It focuses solely on field aliasing and automatic createdAt/updatedAt timestamps, deliberately omitting schema validation, middleware, virtuals, and population. This package is suitable for developers who want minimal overhead (42KB) and fine-grained control over MongoDB queries.

database

npm install mongo-alias

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · MONGO-ALIAS

mongo-alias

databasejavascriptv1.0.13

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

MongoAlias

✓ import MongoAlias from 'mongo-alias'

✗ const { MongoAlias } = require('mongo-alias')

Default export is a class. ESM-only; CJS require will fail as package is type:module.

AliasManager

✓ import { AliasManager } from 'mongo-alias'

✗ import AliasManager from 'mongo-alias'

Named export for advanced use. Types are bundled; no separate @types package needed.

type MongoAliasConfig

✓ import type { MongoAliasConfig } from 'mongo-alias'

✗ import { MongoAliasConfig } from 'mongo-alias'

Type-only import in TypeScript. Avoid runtime import of types.

Demonstrates connecting to MongoDB, creating an alias manager, inserting, and querying with automatic field translation and timestamps.

import { MongoClient } from 'mongodb'; import MongoAlias from 'mongo-alias'; const client = new MongoClient('mongodb://localhost:27017'); await client.connect(); const db = client.db('test'); const alias = new MongoAlias(db, { // Define aliases: long -> short users: { name: 'n', email: 'e', createdAt: 'c', updatedAt: 'u' } }); const coll = alias.collection('users'); // Insert with long field names; stored as short await coll.insertOne({ name: 'Alice', email: 'alice@example.com' }); // Find returns long field names const doc = await coll.findOne({ email: 'alice@example.com' }); console.log(doc); // { _id: ..., name: 'Alice', email: 'alice@example.com', createdAt: ..., updatedAt: ... } // Query with long names translates to short const results = await coll.find({ name: 'Alice' }).toArray(); // Automatic timestamps are added if not provided // Native methods (e.g., findOneAndUpdate) work on aliased collection too

Debug

Known issues

breakingVersion 1.0.0 dropped support for Node.js <18. Engines field is >=18.0.0.

fix

Upgrade Node.js to 18+ or stay on older mongo-alias versions if needed (none exist, so upgrade Node).

affects: >=1.0.0

breakingOnly commonly used collection methods are aliased (insertOne, find, findOne, updateOne, deleteOne, etc.). Calling non-aliased methods bypasses translation.

fix

Use the native collection for unsupported methods, or submit a PR. Check the docs for the list of aliased methods.

affects: >=1.0.0

deprecatedIn version 1.0.10, the `writeConcern` option for insertOne was deprecated and may be removed in a future release.

fix

Set write concern on the MongoClient or DB level instead of per-operation.

affects: >=1.0.10

gotchaAlias definitions are shallow; nested fields are not translated.

fix

Manually handle nested object field translation if needed, or use schema-level mapping.

affects: >=1.0.0

breakingVersion 1.0.7 changed the default `autoTimestamps` option from `true` to `false`.

fix

Explicitly set `autoTimestamps: true` in the constructor if you rely on automatic createdAt/updatedAt.

affects: >=1.0.7

gotchaThe `find` method returns a cursor, but alias translation only applies to the initial query; subsequent calls like `project`, `sort`, etc. require manual alias awareness.

fix

Apply aliases in the initial query; additional cursor methods bypass translation. For complex aggregations, use the native aggregate method without aliasing.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: MongoAlias is not a constructor

Used CommonJS require on an ESM-only package.

fix

Switch to ESM import: `import MongoAlias from 'mongo-alias'` and ensure project type is 'module' or use .mjs extension.

AliasManager is not defined

Tried to import named export via default import.

fix

Use named import: `import { AliasManager } from 'mongo-alias'`.

MongoServerError: unknown top level operator: $n

Tried to use an aliased field name in an aggregation pipeline stage that wasn't translated (aggregate method not aliased).

fix

Use the native collection for aggregation or manually map fields. The `aggregate` method is not aliased in this package.

Cannot find module 'mongo-alias' or its corresponding type declarations.

TypeScript cannot find types because the package may not be installed or tsconfig misses declaration resolution.

fix

Ensure the package is installed (`npm install mongo-alias`). If using TypeScript <5, add `esModuleInterop: true` and `moduleResolution: node16` or `bundler`.

ValidationError: `createdAt` is not allowed in schema

Using with a validation library that expects only the aliased short keys but the code sends long names.

fix

Either apply validation after alias translation (on returned documents) or configure your validation to accept both long and short keys.

Upgrade

Version history

1.0.13latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

7 hits · last 30 days

node

Amazon

Resources

githubssh://git@github.com/CodeAwareness/mongo-alias ↗

packagemongo-alias ↗

homepagehttps://github.com/CodeAwareness/mongo-alias#readme ↗