#ObjectId Conversion Diagnostics

#Current Behavior

In the current runtime, ObjectId conversion is value-based by default. Valid 24-character hex strings can be converted in query filters, write payloads, and aggregation pipelines when traversal reaches them.

Use autoConvertObjectId as an instance-level conversion switch:

const msq = new MonSQLize({
  type: 'mongodb',
  config: { uri: 'mongodb://localhost:27017' },
  autoConvertObjectId: true
});

Set it to false, or use { enabled: false }, when a code path must preserve arbitrary 24-character hexadecimal strings. When only selected fields must remain strings, use excludeFields, { fieldName: false }, or maxDepth.

#How to Verify Conversion

Because the converter does not emit conversion logs, verify behavior through one of these routes:

1. Add an integration test that writes or queries a known value and inspects the stored or matched value.
2. Use MongoDB command monitoring in the application test harness to inspect the command sent to the driver.
3. Call the converter in a focused unit test when validating adapter behavior.

Example focused check:

import { ObjectId } from 'mongodb';
import { convertObjectIdStrings } from '../src/adapters/mongodb/utils/objectid-converter';

const converted = convertObjectIdStrings({
  _id: '507f1f77bcf86cd799439011',
  code: '1234567890abcdef12345678'
});

console.log(converted._id instanceof ObjectId);  // true
console.log(converted.code instanceof ObjectId); // true

#Configuration Reference

#FAQ

#Can I enable ObjectId conversion logs?

No. The current converter does not provide conversion log output or silent / verbose controls.

#Can I exclude specific fields from conversion?

Yes. If a workload contains values such as transaction hashes, idempotency keys, signatures, or external payment numbers that can look like ObjectIds, use excludeFields or { fieldName: false }. Use autoConvertObjectId: false only when the whole instance should preserve every string exactly.

#Is conversion field-whitelist based?

No. Current stable behavior is value-based. A valid ObjectId-looking string can be converted regardless of the field name when traversal reaches it.