@semics-tech/mongolite 1.2.0 → 1.3.0

package/dist/cjs/cli/filter-builder.js

@@ -0,0 +1,276 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.operatorsFor = operatorsFor;
+exports.escapeRegex = escapeRegex;
+exports.parseValue = parseValue;
+exports.parseValueList = parseValueList;
+exports.compileCondition = compileCondition;
+exports.combineConditions = combineConditions;
+exports.describeCondition = describeCondition;
+const EXISTENCE = [
+    { id: 'exists', label: 'has a value', arity: 'none' },
+    { id: 'notExists', label: 'is missing or empty', arity: 'none' },
+];
+const STRING_OPERATORS = [
+    { id: 'eq', label: 'is', arity: 'one', valuePrompt: 'Value' },
+    { id: 'ne', label: 'is not', arity: 'one', valuePrompt: 'Value' },
+    { id: 'contains', label: 'contains the text', arity: 'one', valuePrompt: 'Text' },
+    { id: 'startsWith', label: 'starts with', arity: 'one', valuePrompt: 'Prefix' },
+    { id: 'endsWith', label: 'ends with', arity: 'one', valuePrompt: 'Suffix' },
+    { id: 'in', label: 'is one of', arity: 'many', valuePrompt: 'Values (comma separated)' },
+    { id: 'nin', label: 'is none of', arity: 'many', valuePrompt: 'Values (comma separated)' },
+    {
+        id: 'regex',
+        label: 'matches a regular expression',
+        arity: 'one',
+        valuePrompt: 'Pattern',
+        hint: 'advanced',
+    },
+];
+const NUMBER_OPERATORS = [
+    { id: 'eq', label: 'equals', arity: 'one', valuePrompt: 'Number' },
+    { id: 'ne', label: 'does not equal', arity: 'one', valuePrompt: 'Number' },
+    { id: 'gt', label: 'is greater than', arity: 'one', valuePrompt: 'Number' },
+    { id: 'gte', label: 'is at least', arity: 'one', valuePrompt: 'Number' },
+    { id: 'lt', label: 'is less than', arity: 'one', valuePrompt: 'Number' },
+    { id: 'lte', label: 'is at most', arity: 'one', valuePrompt: 'Number' },
+    {
+        id: 'between',
+        label: 'is between',
+        arity: 'two',
+        valuePrompt: 'From (inclusive)',
+        secondValuePrompt: 'To (inclusive)',
+    },
+    { id: 'in', label: 'is one of', arity: 'many', valuePrompt: 'Numbers (comma separated)' },
+];
+const DATE_OPERATORS = [
+    { id: 'eq', label: 'is exactly', arity: 'one', valuePrompt: 'Date (e.g. 2024-01-31)' },
+    { id: 'gt', label: 'is after', arity: 'one', valuePrompt: 'Date (e.g. 2024-01-31)' },
+    { id: 'gte', label: 'is on or after', arity: 'one', valuePrompt: 'Date' },
+    { id: 'lt', label: 'is before', arity: 'one', valuePrompt: 'Date' },
+    { id: 'lte', label: 'is on or before', arity: 'one', valuePrompt: 'Date' },
+    {
+        id: 'between',
+        label: 'is between',
+        arity: 'two',
+        valuePrompt: 'From date',
+        secondValuePrompt: 'To date',
+    },
+];
+const BOOLEAN_OPERATORS = [
+    { id: 'isTrue', label: 'is true', arity: 'none' },
+    { id: 'isFalse', label: 'is false', arity: 'none' },
+];
+const ARRAY_OPERATORS = [
+    { id: 'arrayContains', label: 'contains', arity: 'one', valuePrompt: 'Value' },
+    {
+        id: 'arrayContainsAny',
+        label: 'contains any of',
+        arity: 'many',
+        valuePrompt: 'Values (comma separated)',
+    },
+    {
+        id: 'arrayContainsAll',
+        label: 'contains all of',
+        arity: 'many',
+        valuePrompt: 'Values (comma separated)',
+    },
+    { id: 'size', label: 'has exactly N items', arity: 'one', valuePrompt: 'Number of items' },
+];
+const OBJECT_OPERATORS = [
+    { id: 'jsonEquals', label: 'equals this JSON', arity: 'one', valuePrompt: 'JSON value' },
+];
+/** The conditions worth offering for a given field. */
+function operatorsFor(field) {
+    const byType = {
+        string: STRING_OPERATORS,
+        number: NUMBER_OPERATORS,
+        date: DATE_OPERATORS,
+        boolean: BOOLEAN_OPERATORS,
+        array: ARRAY_OPERATORS,
+        object: OBJECT_OPERATORS,
+        null: STRING_OPERATORS,
+    };
+    const primary = byType[field.primaryType] ?? STRING_OPERATORS;
+    // Mixed-type fields also get the string operators, which are the most forgiving.
+    const mixed = field.types.length > 1 && field.primaryType !== 'string'
+        ? STRING_OPERATORS.filter((op) => !primary.some((existing) => existing.id === op.id))
+        : [];
+    return [...primary, ...mixed, ...EXISTENCE];
+}
+/** Escape a literal string so it can be embedded in a regular expression. */
+function escapeRegex(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * Coerce user-typed text into the type the field appears to hold.
+ * Throws a message suitable for showing straight back to the user.
+ */
+function parseValue(input, type) {
+    const trimmed = input.trim();
+    switch (type) {
+        case 'number': {
+            const parsed = Number(trimmed);
+            if (trimmed === '' || Number.isNaN(parsed)) {
+                throw new Error(`"${input}" is not a number.`);
+            }
+            return parsed;
+        }
+        case 'boolean': {
+            const lowered = trimmed.toLowerCase();
+            if (['true', 'yes', 'y', '1'].includes(lowered))
+                return true;
+            if (['false', 'no', 'n', '0'].includes(lowered))
+                return false;
+            throw new Error(`"${input}" is not true or false.`);
+        }
+        case 'date': {
+            const parsed = new Date(trimmed);
+            if (Number.isNaN(parsed.getTime())) {
+                throw new Error(`"${input}" is not a date I can read. Try 2024-01-31.`);
+            }
+            // Documents store dates as ISO strings, so compare as ISO strings.
+            return /^\d{4}-\d{2}-\d{2}$/.test(trimmed)
+                ? `${trimmed}T00:00:00.000Z`
+                : parsed.toISOString();
+        }
+        case 'object':
+        case 'array': {
+            try {
+                return JSON.parse(trimmed);
+            }
+            catch {
+                return trimmed; // Fall back to a plain scalar - useful for "array contains".
+            }
+        }
+        default: {
+            // Strings stay strings, but "true"/"42" typed against a mixed field are
+            // usually meant literally, so no coercion here.
+            return trimmed;
+        }
+    }
+}
+/** Split a comma-separated list, parsing each entry as `type`. */
+function parseValueList(input, type) {
+    const parts = input
+        .split(',')
+        .map((part) => part.trim())
+        .filter((part) => part !== '');
+    if (parts.length === 0)
+        throw new Error('Enter at least one value.');
+    return parts.map((part) => parseValue(part, type));
+}
+/** Compile one condition into the equivalent MongoLite filter fragment. */
+function compileCondition(condition) {
+    const { field, operator, values } = condition;
+    const [first, second] = values;
+    switch (operator) {
+        case 'eq':
+            return { [field]: { $eq: first } };
+        case 'ne':
+            return { [field]: { $ne: first } };
+        case 'gt':
+            return { [field]: { $gt: first } };
+        case 'gte':
+            return { [field]: { $gte: first } };
+        case 'lt':
+            return { [field]: { $lt: first } };
+        case 'lte':
+            return { [field]: { $lte: first } };
+        case 'between':
+            return { [field]: { $gte: first, $lte: second } };
+        case 'in':
+            return { [field]: { $in: values } };
+        case 'nin':
+            return { [field]: { $nin: values } };
+        case 'contains':
+            return { [field]: { $regex: escapeRegex(String(first)), $options: 'i' } };
+        case 'startsWith':
+            return { [field]: { $regex: `^${escapeRegex(String(first))}`, $options: 'i' } };
+        case 'endsWith':
+            return { [field]: { $regex: `${escapeRegex(String(first))}$`, $options: 'i' } };
+        case 'regex':
+            return { [field]: { $regex: String(first) } };
+        case 'isTrue':
+            return { [field]: { $eq: true } };
+        case 'isFalse':
+            return { [field]: { $eq: false } };
+        case 'exists':
+            return { [field]: { $exists: true } };
+        case 'notExists':
+            return { [field]: { $exists: false } };
+        // `$in` compiles to a json_each() containment check, which is what makes
+        // these work element-wise on array fields.
+        case 'arrayContains':
+            return { [field]: { $in: [first] } };
+        case 'arrayContainsAny':
+            return { [field]: { $in: values } };
+        case 'arrayContainsAll':
+            return { [field]: { $all: values } };
+        case 'size':
+            return { [field]: { $size: Number(first) } };
+        case 'jsonEquals':
+            return { [field]: first };
+        default:
+            throw new Error(`Unknown condition: ${operator}`);
+    }
+}
+/**
+ * Combine conditions into one filter.
+ * "All" merges into a flat object when the fields are distinct (the filter a
+ * person would have written by hand) and falls back to `$and` when a field is
+ * constrained more than once.
+ */
+function combineConditions(conditions, mode = 'all') {
+    if (conditions.length === 0)
+        return {};
+    const compiled = conditions.map(compileCondition);
+    if (compiled.length === 1 && mode === 'all')
+        return compiled[0];
+    if (mode === 'any')
+        return { $or: compiled };
+    const fields = conditions.map((condition) => condition.field);
+    const hasDuplicateField = new Set(fields).size !== fields.length;
+    if (hasDuplicateField)
+        return { $and: compiled };
+    return Object.assign({}, ...compiled);
+}
+/**
+ * Every operator across every type, for label lookups.
+ * A condition's `fieldType` is the type of its *values* — the element type for
+ * array fields — so looking a label up by that type alone would miss the array
+ * operators.
+ */
+const ALL_OPERATORS = [
+    ...STRING_OPERATORS,
+    ...NUMBER_OPERATORS,
+    ...DATE_OPERATORS,
+    ...BOOLEAN_OPERATORS,
+    ...ARRAY_OPERATORS,
+    ...OBJECT_OPERATORS,
+    ...EXISTENCE,
+];
+/** Render a condition the way it was phrased in the menu, for review lists. */
+function describeCondition(condition, operators = operatorsFor({
+    primaryType: condition.fieldType,
+    types: [condition.fieldType],
+})) {
+    const operator = operators.find((candidate) => candidate.id === condition.operator) ??
+        ALL_OPERATORS.find((candidate) => candidate.id === condition.operator);
+    const label = operator?.label ?? condition.operator;
+    if (condition.values.length === 0)
+        return `${condition.field} ${label}`;
+    if (condition.values.length === 2 && condition.operator === 'between') {
+        return `${condition.field} ${label} ${format(condition.values[0])} and ${format(condition.values[1])}`;
+    }
+    return `${condition.field} ${label} ${condition.values.map(format).join(', ')}`;
+}
+function format(value) {
+    if (typeof value === 'string')
+        return `"${value}"`;
+    if (value === null)
+        return 'null';
+    if (typeof value === 'object')
+        return JSON.stringify(value);
+    return String(value);
+}

package/dist/cjs/cli/format.js

@@ -0,0 +1,161 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatCell = formatCell;
+exports.renderTable = renderTable;
+exports.renderDocument = renderDocument;
+exports.renderSchema = renderSchema;
+exports.renderSql = renderSql;
+exports.describeFilter = describeFilter;
+exports.wrapText = wrapText;
+/**
+ * Rendering helpers: turning documents into something readable in a terminal.
+ */
+const schema_js_1 = require("./schema.js");
+const ui_js_1 = require("./ui.js");
+/** Render a value as a single-line cell. */
+function formatCell(value) {
+    if (value === undefined)
+        return '';
+    if (value === null)
+        return 'null';
+    if (value instanceof Date)
+        return value.toISOString();
+    if (Array.isArray(value)) {
+        if (value.length === 0)
+            return '[]';
+        const inner = value
+            .map((item) => (typeof item === 'object' && item !== null ? '{…}' : String(item)))
+            .join(', ');
+        return `[${inner}]`;
+    }
+    if (typeof value === 'object')
+        return JSON.stringify(value);
+    return String(value);
+}
+/**
+ * Render documents as an aligned table. Columns are sized to their content and
+ * then shrunk proportionally if the table would overflow the terminal.
+ */
+function renderTable(docs, options) {
+    const { columns } = options;
+    if (columns.length === 0)
+        return ui_js_1.style.grey('No columns to show.');
+    const maxColumnWidth = options.maxColumnWidth ?? 40;
+    const startIndex = options.startIndex ?? 0;
+    const showRowNumbers = options.showRowNumbers ?? true;
+    const headers = showRowNumbers ? ['#', ...columns] : [...columns];
+    const rows = docs.map((doc, index) => {
+        const cells = columns.map((column) => formatCell((0, schema_js_1.getPath)(doc, column)));
+        return showRowNumbers ? [String(startIndex + index + 1), ...cells] : cells;
+    });
+    // Natural width per column, capped.
+    const widths = headers.map((header, columnIndex) => {
+        const longestCell = rows.reduce((max, row) => Math.max(max, (row[columnIndex] ?? '').length), 0);
+        return Math.min(Math.max(header.length, longestCell), maxColumnWidth);
+    });
+    // Shrink the widest columns until the whole table fits the terminal.
+    const separatorWidth = 3;
+    const available = (0, ui_js_1.terminalWidth)() - 1;
+    let total = widths.reduce((sum, width) => sum + width, 0) + separatorWidth * (widths.length - 1);
+    while (total > available) {
+        const widest = widths.indexOf(Math.max(...widths));
+        if (widths[widest] <= 6)
+            break;
+        widths[widest] -= 1;
+        total -= 1;
+    }
+    const line = (cells, colourise) => cells
+        .map((cell, index) => {
+        const clipped = (0, ui_js_1.truncate)(cell, widths[index]);
+        const padded = clipped.padEnd(widths[index]);
+        return colourise ? colourise(padded) : padded;
+    })
+        .join(ui_js_1.style.grey(' │ '))
+        .trimEnd();
+    const output = [];
+    output.push(line(headers, ui_js_1.style.bold));
+    output.push(ui_js_1.style.grey(widths.map((width) => '─'.repeat(width)).join('─┼─')));
+    for (const row of rows)
+        output.push(line(row));
+    return output.join('\n');
+}
+/** Pretty-print one document, with the `_id` called out first. */
+function renderDocument(doc) {
+    return JSON.stringify(doc, null, 2);
+}
+/** Render an inferred schema as a table of fields. */
+function renderSchema(schema) {
+    if (schema.fields.length === 0) {
+        return ui_js_1.style.grey('No fields found - the collection looks empty.');
+    }
+    const rows = schema.fields.map((field) => {
+        const type = field.primaryType === 'array' && field.elementTypes?.length
+            ? `array<${field.elementTypes.filter((t) => t !== 'null').join('|') || 'any'}>`
+            : field.types.join('|');
+        const example = field.examples.length
+            ? formatCell(field.examples[0])
+            : field.types.includes('null')
+                ? 'null'
+                : '';
+        return {
+            field: field.path,
+            type,
+            present: `${Math.round(field.presence * 100)}%`,
+            example,
+        };
+    });
+    const widths = {
+        field: Math.min(Math.max(5, ...rows.map((r) => r.field.length)), 40),
+        type: Math.min(Math.max(4, ...rows.map((r) => r.type.length)), 24),
+        present: 7,
+    };
+    const exampleWidth = Math.max(10, (0, ui_js_1.terminalWidth)() - widths.field - widths.type - widths.present - 10);
+    const output = [];
+    output.push(ui_js_1.style.bold(`${'field'.padEnd(widths.field)}  ${'type'.padEnd(widths.type)}  ${'present'.padEnd(widths.present)}  example`));
+    for (const row of rows) {
+        output.push(`${(0, ui_js_1.truncate)(row.field, widths.field).padEnd(widths.field)}  ${ui_js_1.style.cyan((0, ui_js_1.truncate)(row.type, widths.type).padEnd(widths.type))}  ${ui_js_1.style.grey(row.present.padEnd(widths.present))}  ${ui_js_1.style.grey((0, ui_js_1.truncate)(row.example, exampleWidth))}`);
+    }
+    return output.join('\n');
+}
+/** Show a generated SQL statement with its bound parameters. */
+function renderSql(sql, params) {
+    const lines = [ui_js_1.style.bold('SQL'), sql];
+    if (params.length > 0) {
+        lines.push(ui_js_1.style.bold('Parameters'), JSON.stringify(params));
+    }
+    return lines.join('\n');
+}
+/** Describe a filter in plain English, for confirming what is about to run. */
+function describeFilter(filter) {
+    if (!filter || Object.keys(filter).length === 0)
+        return 'all documents';
+    return JSON.stringify(filter);
+}
+/** Wrap long text to the terminal width, preserving existing newlines. */
+function wrapText(text, width = (0, ui_js_1.terminalWidth)() - 2) {
+    return text
+        .split('\n')
+        .map((paragraph) => {
+        if ((0, ui_js_1.displayWidth)(paragraph) <= width)
+            return paragraph;
+        const words = paragraph.split(' ');
+        const lines = [];
+        let current = '';
+        for (const word of words) {
+            if (current === '') {
+                current = word;
+            }
+            else if ((0, ui_js_1.displayWidth)(`${current} ${word}`) <= width) {
+                current = `${current} ${word}`;
+            }
+            else {
+                lines.push(current);
+                current = word;
+            }
+        }
+        if (current)
+            lines.push(current);
+        return lines.join('\n');
+    })
+        .join('\n');
+}

package/dist/cjs/cli/schema.js

@@ -0,0 +1,211 @@
+"use strict";
+/**
+ * Schema inference for the guided CLI.
+ *
+ * MongoLite stores documents as JSON, so there is no declared schema to read.
+ * We sample documents and derive the field paths, their types, how often they
+ * appear and a handful of example values. That is enough to offer the user a
+ * list of "columns" to filter and sort on without them knowing anything about
+ * the shape of the data up front.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.valueType = valueType;
+exports.inferSchema = inferSchema;
+exports.defaultColumns = defaultColumns;
+exports.getPath = getPath;
+exports.describeField = describeField;
+const MAX_SAMPLES = 5;
+const MAX_DISTINCT = 25;
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})?)?$/;
+/** Classify a single JSON value into one of our display types. */
+function valueType(value) {
+    if (value === null || value === undefined)
+        return 'null';
+    if (value instanceof Date)
+        return 'date';
+    if (Array.isArray(value))
+        return 'array';
+    if (typeof value === 'string')
+        return ISO_DATE.test(value) ? 'date' : 'string';
+    if (typeof value === 'number')
+        return 'number';
+    if (typeof value === 'boolean')
+        return 'boolean';
+    if (typeof value === 'object')
+        return 'object';
+    return 'string';
+}
+function accumulator(path) {
+    return {
+        path,
+        typeCounts: new Map(),
+        count: 0,
+        examples: [],
+        distinct: new Map(),
+        distinctOverflow: false,
+        elementTypes: new Set(),
+        elementFields: new Set(),
+    };
+}
+function isPlainObject(value) {
+    return (typeof value === 'object' && value !== null && !Array.isArray(value) && !(value instanceof Date));
+}
+function recordValue(acc, value) {
+    const type = valueType(value);
+    acc.count += 1;
+    acc.typeCounts.set(type, (acc.typeCounts.get(type) ?? 0) + 1);
+    if (acc.examples.length < MAX_SAMPLES && value !== null && value !== undefined) {
+        const alreadySeen = acc.examples.some((existing) => stableKey(existing) === stableKey(value));
+        if (!alreadySeen)
+            acc.examples.push(value);
+    }
+    // Track distinct values for scalars only - object/array equality is not worth
+    // the noise, and a "pick a value" prompt only makes sense for scalars.
+    if (type === 'string' || type === 'number' || type === 'boolean' || type === 'date') {
+        if (!acc.distinctOverflow) {
+            const key = stableKey(value);
+            if (!acc.distinct.has(key)) {
+                if (acc.distinct.size >= MAX_DISTINCT) {
+                    acc.distinctOverflow = true;
+                    acc.distinct.clear();
+                }
+                else {
+                    acc.distinct.set(key, value);
+                }
+            }
+        }
+    }
+    if (Array.isArray(value)) {
+        for (const element of value) {
+            acc.elementTypes.add(valueType(element));
+            if (isPlainObject(element)) {
+                for (const key of Object.keys(element))
+                    acc.elementFields.add(key);
+            }
+        }
+    }
+}
+function stableKey(value) {
+    if (value instanceof Date)
+        return `date:${value.toISOString()}`;
+    if (typeof value === 'object' && value !== null)
+        return `json:${JSON.stringify(value)}`;
+    return `${typeof value}:${String(value)}`;
+}
+function walk(doc, prefix, depth, maxDepth, fields) {
+    for (const [key, value] of Object.entries(doc)) {
+        const path = prefix ? `${prefix}.${key}` : key;
+        let acc = fields.get(path);
+        if (!acc) {
+            acc = accumulator(path);
+            fields.set(path, acc);
+        }
+        recordValue(acc, value);
+        if (isPlainObject(value) && depth < maxDepth) {
+            walk(value, path, depth + 1, maxDepth, fields);
+        }
+    }
+}
+/**
+ * Infer a schema from a sample of documents.
+ * Fields are ordered by how commonly they appear, then alphabetically, with
+ * `_id` pinned first so result tables always lead with the identifier.
+ */
+function inferSchema(docs, options = {}) {
+    const maxDepth = options.maxDepth ?? 3;
+    const fields = new Map();
+    for (const doc of docs) {
+        if (!isPlainObject(doc))
+            continue;
+        walk(doc, '', 1, maxDepth, fields);
+    }
+    const total = docs.length || 1;
+    const inferred = [...fields.values()].map((acc) => {
+        const types = [...acc.typeCounts.entries()].sort((a, b) => b[1] - a[1]).map(([type]) => type);
+        // Prefer a concrete type over `null` when a field is sometimes empty.
+        const primaryType = types.find((t) => t !== 'null') ?? types[0] ?? 'null';
+        const distinctValues = acc.distinctOverflow ? undefined : [...acc.distinct.values()];
+        return {
+            path: acc.path,
+            types,
+            primaryType,
+            count: acc.count,
+            presence: acc.count / total,
+            examples: acc.examples,
+            elementTypes: acc.elementTypes.size ? [...acc.elementTypes] : undefined,
+            elementFields: acc.elementFields.size ? [...acc.elementFields].sort() : undefined,
+            lowCardinality: Boolean(distinctValues && distinctValues.length > 0 && distinctValues.length <= 12),
+            distinctValues,
+        };
+    });
+    inferred.sort((a, b) => {
+        if (a.path === '_id')
+            return -1;
+        if (b.path === '_id')
+            return 1;
+        const depthDiff = a.path.split('.').length - b.path.split('.').length;
+        if (depthDiff !== 0)
+            return depthDiff;
+        if (b.count !== a.count)
+            return b.count - a.count;
+        return a.path.localeCompare(b.path);
+    });
+    return { sampled: docs.length, fields: inferred };
+}
+/**
+ * Pick a sensible default set of columns for a results table: shallow, common,
+ * scalar-ish fields, leading with `_id`.
+ */
+function defaultColumns(schema, max = 6) {
+    const scalarish = ['string', 'number', 'boolean', 'date'];
+    const candidates = schema.fields.filter((field) => field.path !== '_id' &&
+        !field.path.includes('.') &&
+        field.presence >= 0.5 &&
+        scalarish.includes(field.primaryType));
+    const columns = candidates.slice(0, max - 1).map((field) => field.path);
+    const hasId = schema.fields.some((field) => field.path === '_id');
+    if (columns.length === 0) {
+        // Nothing scalar and shallow - fall back to whatever we do have.
+        const fallback = schema.fields
+            .filter((field) => field.path !== '_id' && !field.path.includes('.'))
+            .slice(0, max - 1)
+            .map((field) => field.path);
+        return hasId ? ['_id', ...fallback] : fallback;
+    }
+    return hasId ? ['_id', ...columns] : columns;
+}
+/** Read a dotted path out of a document, descending through objects. */
+function getPath(doc, path) {
+    return path.split('.').reduce((current, segment) => {
+        if (current === null || current === undefined)
+            return undefined;
+        if (Array.isArray(current)) {
+            const index = Number.parseInt(segment, 10);
+            return Number.isInteger(index) ? current[index] : undefined;
+        }
+        if (typeof current === 'object')
+            return current[segment];
+        return undefined;
+    }, doc);
+}
+/** Human-readable one-line summary of a field, used as a menu hint. */
+function describeField(field) {
+    const parts = [];
+    const type = field.primaryType === 'array' && field.elementTypes?.length
+        ? `array of ${field.elementTypes.filter((t) => t !== 'null').join('/') || 'values'}`
+        : field.primaryType;
+    parts.push(type);
+    if (field.presence < 0.999) {
+        parts.push(`in ${Math.round(field.presence * 100)}% of docs`);
+    }
+    if (field.examples.length > 0) {
+        const example = field.examples[0];
+        const rendered = example instanceof Date
+            ? example.toISOString()
+            : typeof example === 'object'
+                ? JSON.stringify(example)
+                : String(example);
+        parts.push(`e.g. ${rendered.length > 30 ? `${rendered.slice(0, 29)}…` : rendered}`);
+    }
+    return `— ${parts.join(', ')}`;
+}