feat(mongodb): distinguish missing fields from BSON null in grid

This commit is contained in:
二丫讲梵 authored and GitHub committed 2026-09-10 11:59:28 +08:00
1 parent 464f2f33c5
commit 0f07d337c3
16 files changed
+542 -69

No files matched your search

@@ -1,5 +1,7 @@
import { MONGO_DOCUMENT_GRID_NULL, mongoDocumentGridDisplayText, mongoDocumentGridExternalValue, mongoDocumentGridValue } from "@/lib/mongo/mongoDocumentValues";
import { displayCellValue, type CellValue } from "@/lib/dataGrid/cellValue";
import { describe, expect, it } from "vitest";
import { buildDeleteRowConfirmDetails, dataGridColumnDetailTsv, dataGridRowDetailTsv, type DataGridColumnDetail, type DataGridRowDetail } from "../dataGridDetail";
import { buildDataGridCellDetail, buildDataGridColumnDetail, buildDataGridRowDetail, buildDeleteRowConfirmDetails, dataGridColumnDetailJson, dataGridColumnDetailTsv, dataGridRowDetailJson, dataGridRowDetailTsv, type DataGridColumnDetail, type DataGridRowDetail } from "../dataGridDetail";
type TestRow = string[];
@@ -142,3 +144,79 @@ describe("data grid detail TSV", () => {
expect(dataGridColumnDetailTsv(columnDetail)).toBe("\nNULL");
});
});
describe("Mongo collection cell detail presentation", () => {
it.each([null, "NULL", MONGO_DOCUMENT_GRID_NULL])("presents BSON value %j without leaking grid encoding", (bsonValue) => {
const value = mongoDocumentGridValue(bsonValue) as string;
const text = mongoDocumentGridDisplayText(value) ?? displayCellValue(value);
const detail = buildDataGridCellDetail({
rowIndex: 0,
rowId: 0,
row: [value],
columns: ["value"],
columnIndex: 0,
displayValue: () => text,
rawValue: () => text,
isNullValue: (cell) => cell === MONGO_DOCUMENT_GRID_NULL,
isEditable: true,
});
expect(detail).toMatchObject({ value, rawValue: text, rawValuePreview: text, isNull: bsonValue === null, length: bsonValue === null ? 0 : text.length });
expect(detail!.rawValue).not.toContain("\u0000");
});
it("presents the BSON null marker as NULL text in row and column detail fields", () => {
const value = mongoDocumentGridValue(null) as string;
const rawValue = (cell: CellValue) => mongoDocumentGridDisplayText(cell) ?? displayCellValue(cell);
const isNullValue = (cell: CellValue) => cell === MONGO_DOCUMENT_GRID_NULL;
const rowDetail = buildDataGridRowDetail({
rowIndex: 0,
rowId: 1,
row: [value],
columns: ["value"],
columnIndexes: [0],
displayValue: rawValue,
rawValue,
isNullValue,
});
const columnDetail = buildDataGridColumnDetail({
rows: [{ rowIndex: 0, rowId: 1, row: [value] }],
columns: ["value"],
columnIndex: 0,
displayValue: rawValue,
rawValue,
isNullValue,
});
for (const field of [...rowDetail.fields, ...columnDetail!.fields]) {
expect(field).toMatchObject({ value, rawValue: "NULL", rawValuePreview: "NULL", isNull: true, length: 0 });
expect(field.rawValuePreview).not.toContain("\u0000");
}
});
it("restores external BSON null values in row and column detail copy payloads", () => {
const value = mongoDocumentGridValue(null) as string;
const rowDetail = buildDataGridRowDetail({
rowIndex: 0,
rowId: 1,
row: [value],
columns: ["value"],
columnIndexes: [0],
displayValue: (cell) => displayCellValue(cell),
});
const columnDetail = buildDataGridColumnDetail({
rows: [{ rowIndex: 0, rowId: 1, row: [value] }],
columns: ["value"],
columnIndex: 0,
displayValue: (cell) => displayCellValue(cell),
});
const rowJson = dataGridRowDetailJson(rowDetail, undefined, undefined, mongoDocumentGridExternalValue);
const columnJson = dataGridColumnDetailJson(columnDetail!, undefined, mongoDocumentGridExternalValue);
expect(rowJson).toBe('{\n "value": null\n}');
expect(columnJson).toBe('[\n {\n "row": 1,\n "value": null\n }\n]');
expect(rowJson).not.toContain("\u0000");
expect(columnJson).not.toContain("\u0000");
expect(dataGridRowDetailTsv(rowDetail, undefined, mongoDocumentGridExternalValue)).toBe("");
expect(dataGridColumnDetailTsv(columnDetail!, undefined, mongoDocumentGridExternalValue)).toBe("");
});
});
+48 -13
View File
@@ -21,6 +21,7 @@ export interface DataGridCellDetail {
isValuePreviewTruncated: boolean;
imagePreviewUrl: string | null;
length: number;
isNull?: boolean;
formattedJson: string;
isEditable: boolean;
}
@@ -50,6 +51,8 @@ export interface BuildDataGridCellDetailOptions {
commentByColumn?: ReadonlyMap<string, string>;
displayValue: (value: CellValue, columnIndex: number) => string;
isEditable: boolean;
rawValue?: (value: CellValue, columnIndex: number) => string;
isNullValue?: (value: CellValue) => boolean;
databaseType?: DatabaseType;
includeBinaryImagePreview?: boolean;
isValuePreviewTruncated?: boolean;
@@ -65,6 +68,8 @@ export interface BuildDataGridRowDetailOptions {
resultColumnTypes?: readonly string[];
commentByColumn?: ReadonlyMap<string, string>;
displayValue: (value: CellValue, columnIndex: number) => string;
rawValue?: (value: CellValue, columnIndex: number) => string;
isNullValue?: (value: CellValue) => boolean;
isEditableColumn?: (columnIndex: number) => boolean;
isValuePreviewTruncated?: (columnIndex: number) => boolean;
}
@@ -85,6 +90,8 @@ export interface BuildDataGridColumnDetailOptions {
resultColumnTypes?: readonly string[];
commentByColumn?: ReadonlyMap<string, string>;
displayValue: (value: CellValue, columnIndex: number) => string;
rawValue?: (value: CellValue, columnIndex: number) => string;
isNullValue?: (value: CellValue) => boolean;
}
export function buildDataGridCellDetail(options: BuildDataGridCellDetailOptions): DataGridCellDetail | null {
@@ -92,7 +99,8 @@ export function buildDataGridCellDetail(options: BuildDataGridCellDetailOptions)
if (column === undefined) return null;
const value = options.row[options.columnIndex] ?? null;
const rawValue = displayCellValue(value);
const rawValue = options.rawValue?.(value, options.columnIndex) ?? displayCellValue(value);
const isNull = options.isNullValue?.(value) ?? value === null;
const displayValue = options.displayValue(value, options.columnIndex);
const formattedJson = typeof value === "string" && looksLikeJsonContainer(value) ? (formatJsonText(value) ?? "") : "";
const rawValuePreview = previewText(rawValue);
@@ -116,7 +124,8 @@ export function buildDataGridCellDetail(options: BuildDataGridCellDetailOptions)
binary: options.includeBinaryImagePreview !== false,
databaseType: options.databaseType,
}),
length: value === null ? 0 : String(value).length,
length: isNull ? 0 : rawValue.length,
isNull,
formattedJson,
isEditable: options.isEditable,
};
@@ -138,6 +147,8 @@ export function buildDataGridColumnDetail(options: BuildDataGridColumnDetailOpti
resultColumnTypes: options.resultColumnTypes,
commentByColumn: options.commentByColumn,
displayValue: options.displayValue,
rawValue: options.rawValue,
isNullValue: options.isNullValue,
isEditable: row.isEditable ?? false,
includeBinaryImagePreview: false,
isValuePreviewTruncated: row.isValuePreviewTruncated,
@@ -167,6 +178,8 @@ export function buildDataGridRowDetail(options: BuildDataGridRowDetailOptions):
resultColumnTypes: options.resultColumnTypes,
commentByColumn: options.commentByColumn,
displayValue: options.displayValue,
rawValue: options.rawValue,
isNullValue: options.isNullValue,
isEditable: options.isEditableColumn?.(columnIndex) ?? false,
includeBinaryImagePreview: false,
isValuePreviewTruncated: options.isValuePreviewTruncated?.(columnIndex),
@@ -187,11 +200,20 @@ function detailColumnType(typeByColumn: ReadonlyMap<string, string> | undefined,
return resultColumnTypes?.[columnIndex]?.trim() ?? "";
}
export function dataGridRowDetailJson(detail: DataGridRowDetail, originalDocument?: unknown, databaseType?: DatabaseType): string {
/** Restores a grid-internal marker value (e.g. the Mongo BSON null sentinel) before it leaves the grid. */
export type DataGridDetailExternalValue = (value: CellValue) => CellValue;
function externalDetailFieldValue(value: CellValue, externalValue: DataGridDetailExternalValue | undefined): CellValue {
const external = externalValue?.(value);
return external === undefined ? value : external;
}
export function dataGridRowDetailJson(detail: DataGridRowDetail, originalDocument?: unknown, databaseType?: DatabaseType, externalValue?: DataGridDetailExternalValue): string {
if (originalDocument !== undefined) return JSON.stringify(jsonDetailDisplayValue(originalDocument), null, 2);
const row: Record<string, CellValue> = {};
detail.fields.forEach((field) => {
row[field.column] = binaryCellClipboardText(field.value, field.type, databaseType) ?? field.value;
const value = externalDetailFieldValue(field.value, externalValue);
row[field.column] = binaryCellClipboardText(value, field.type, databaseType) ?? value;
});
return JSON.stringify(jsonDetailDisplayValue(row), null, 2);
}
@@ -215,23 +237,36 @@ export function jsonDetailDisplayValue(value: unknown): unknown {
return value;
}
export function dataGridRowDetailTsv(detail: DataGridRowDetail, databaseType?: DatabaseType): string {
return detail.fields.map((field) => clipboardCellValue(binaryCellClipboardText(field.value, field.type, databaseType) ?? field.value)).join("\t");
export function dataGridRowDetailTsv(detail: DataGridRowDetail, databaseType?: DatabaseType, externalValue?: DataGridDetailExternalValue): string {
return detail.fields
.map((field) => {
const value = externalDetailFieldValue(field.value, externalValue);
return clipboardCellValue(binaryCellClipboardText(value, field.type, databaseType) ?? value);
})
.join("\t");
}
export function dataGridColumnDetailJson(detail: DataGridColumnDetail, databaseType?: DatabaseType): string {
export function dataGridColumnDetailJson(detail: DataGridColumnDetail, databaseType?: DatabaseType, externalValue?: DataGridDetailExternalValue): string {
return JSON.stringify(
detail.fields.map((field) => ({
row: field.rowNumber,
value: binaryCellClipboardText(field.value, field.type, databaseType) ?? field.value,
})),
detail.fields.map((field) => {
const value = externalDetailFieldValue(field.value, externalValue);
return {
row: field.rowNumber,
value: binaryCellClipboardText(value, field.type, databaseType) ?? value,
};
}),
null,
2,
);
}
export function dataGridColumnDetailTsv(detail: DataGridColumnDetail, databaseType?: DatabaseType): string {
return detail.fields.map((field) => clipboardCellValue(binaryCellClipboardText(field.value, field.type, databaseType) ?? field.value)).join("\n");
export function dataGridColumnDetailTsv(detail: DataGridColumnDetail, databaseType?: DatabaseType, externalValue?: DataGridDetailExternalValue): string {
return detail.fields
.map((field) => {
const value = externalDetailFieldValue(field.value, externalValue);
return clipboardCellValue(binaryCellClipboardText(value, field.type, databaseType) ?? value);
})
.join("\n");
}
export interface BuildDeleteRowConfirmDetailsOptions<TRow> {
@@ -1,9 +1,17 @@
import type { CellValue } from "@/lib/dataGrid/cellValue";
export type MongoInputValue = string | number | boolean | null;
const MONGO_SHELL_DATE_PATTERN = /^(?:ISODate|new Date)\(\s*(["'])(.+)\1\s*\)$/;
const MONGO_SHELL_NUMBER_LONG_PATTERN = /^NumberLong\(\s*(["'])(-?\d+)\1\s*\)$/;
const MONGO_OBJECT_ID_PATTERN = /^[a-fA-F0-9]{24}$/;
const MONGO_INTEGER_PATTERN = /^-?\d+$/;
// These values are internal to the MongoDB collection grid. BSON strings may
// contain any UTF-8 text, so strings in this reserved namespace are escaped
// before entering the grid and restored before being saved.
const MONGO_DOCUMENT_GRID_PREFIX = "\u0000dbx:mongo-document-grid:";
const MONGO_DOCUMENT_GRID_ESCAPED_STRING_PREFIX = `${MONGO_DOCUMENT_GRID_PREFIX}string:`;
export const MONGO_DOCUMENT_GRID_NULL = `${MONGO_DOCUMENT_GRID_PREFIX}null`;
const MAX_SAFE_BIGINT = BigInt(Number.MAX_SAFE_INTEGER);
const MIN_BSON_INT64 = -9223372036854775808n;
const MAX_BSON_INT64 = 9223372036854775807n;
@@ -81,7 +89,6 @@ export function parseMongoDocumentInputValue(raw: MongoInputValue): unknown {
}
export function mongoDocumentDisplayValue(value: unknown): unknown {
if (value === null) return "NULL";
if (value && typeof value === "object" && !Array.isArray(value)) {
const object = value as Record<string, unknown>;
if (Object.keys(object).length === 1 && typeof object.$numberLong === "string") return `NumberLong(${JSON.stringify(object.$numberLong)})`;
@@ -89,9 +96,59 @@ export function mongoDocumentDisplayValue(value: unknown): unknown {
return value;
}
/**
* Maps BSON values into the flat collection-grid representation. The grid
* needs an internal sentinel for an explicit BSON null because an empty cell
* represents a field that does not exist. The grid formatter renders that
* sentinel as NULL, while a literal "NULL" remains ordinary string data.
*/
export function mongoDocumentGridValue(value: unknown): unknown {
if (value === null) return MONGO_DOCUMENT_GRID_NULL;
if (typeof value === "string" && value.startsWith(MONGO_DOCUMENT_GRID_PREFIX)) return `${MONGO_DOCUMENT_GRID_ESCAPED_STRING_PREFIX}${value}`;
return mongoDocumentDisplayValue(value);
}
function mongoDocumentGridEscapedString(value: unknown): string | undefined {
return typeof value === "string" && value.startsWith(MONGO_DOCUMENT_GRID_ESCAPED_STRING_PREFIX) ? value.slice(MONGO_DOCUMENT_GRID_ESCAPED_STRING_PREFIX.length) : undefined;
}
/** Returns the text presented in a collection-grid editor, when customized. */
export function mongoDocumentGridEditorText(value: unknown): string | undefined {
if (value === MONGO_DOCUMENT_GRID_NULL) return "NULL";
return mongoDocumentGridEscapedString(value);
}
/** Returns the custom display text required by collection-grid BSON values. */
export function mongoDocumentGridDisplayText(value: unknown): string | undefined {
if (value === MONGO_DOCUMENT_GRID_NULL) return "NULL";
const escapedString = mongoDocumentGridEscapedString(value);
if (escapedString !== undefined) return JSON.stringify(escapedString);
return value === "NULL" ? JSON.stringify(value) : undefined;
}
/** Restores a collection-grid value before it leaves the grid externally. */
export function mongoDocumentGridExternalValue(value: CellValue): CellValue {
if (value === MONGO_DOCUMENT_GRID_NULL) return null;
const escapedString = mongoDocumentGridEscapedString(value);
return escapedString === undefined ? value : escapedString;
}
/** Preserves encoded grid clipboard values and escapes other reserved input. */
export function mongoDocumentGridInputValue(value: string): string {
// Internal copy/paste already carries encoded values; escaping again would
// save BSON null as a literal sentinel string.
if (value === MONGO_DOCUMENT_GRID_NULL || value.startsWith(MONGO_DOCUMENT_GRID_ESCAPED_STRING_PREFIX)) return value;
return value.startsWith(MONGO_DOCUMENT_GRID_PREFIX) ? `${MONGO_DOCUMENT_GRID_ESCAPED_STRING_PREFIX}${value}` : value;
}
function parseMongoExistingFieldInputValue(raw: Exclude<MongoInputValue, null>, originalValue: unknown): unknown {
// Objects and arrays are serialized into grid text too, so the raw document
// is the only reliable way to distinguish them from JSON-shaped BSON strings.
// The collection grid's private sentinel represents an explicit BSON null.
// A literal "NULL" remains a normal string, including in Mongo query results.
if (raw === MONGO_DOCUMENT_GRID_NULL) return null;
const escapedString = mongoDocumentGridEscapedString(raw);
if (escapedString !== undefined) return escapedString;
if (typeof originalValue === "string") {
return typeof raw === "string" ? raw : String(raw);
}
@@ -202,7 +259,7 @@ export function buildMongoInsertDocument(row: MongoInputValue[], columns: string
if (!col || col === "_id") continue;
const val = row[ci];
if (val === null) continue;
doc[col] = parseMongoDocumentInputValue(val);
doc[col] = val === MONGO_DOCUMENT_GRID_NULL ? null : (mongoDocumentGridEscapedString(val) ?? parseMongoDocumentInputValue(val));
}
return doc;
}
@@ -218,7 +275,7 @@ export function buildMongoCopyInsertDocument(row: MongoInputValue[], columns: st
doc[col] = { $oid: val };
continue;
}
doc[col] = parseMongoDocumentInputValue(val);
doc[col] = val === MONGO_DOCUMENT_GRID_NULL ? null : (mongoDocumentGridEscapedString(val) ?? parseMongoDocumentInputValue(val));
}
return doc;
}
@@ -235,7 +292,9 @@ export function buildMongoCopyDocumentFromOriginal(original: unknown, row: Mongo
// Display strings are ambiguous, so only explicitly edited cells may replace original BSON values.
if (dirtyColumns[columnIndex]) {
const value = row[columnIndex];
if (value !== null) document[column] = parseMongoDocumentInputValue(value);
if (value !== null) {
document[column] = value === MONGO_DOCUMENT_GRID_NULL ? null : (mongoDocumentGridEscapedString(value) ?? parseMongoDocumentInputValue(value));
}
continue;
}
if (Object.prototype.hasOwnProperty.call(source, column)) document[column] = source[column];