@peernova/cuneiform-sf 1.0.2 → 1.0.4-beta.10

package/lib/utils/formatting/definition-create-display.d.ts

@@ -0,0 +1,118 @@
+import { Messages } from '@salesforce/core';
+import type { CreateResult } from '../../operations/DefinitionCreateOperation.js';
+import type { SummaryEntry } from './command-display.js';
+/**
+ * Callback result shape from the operation's onObjectComplete callback.
+ * Captures per-object status for post-execution rendering.
+ */
+export type CallbackResult = {
+    objectName: string;
+    objectLabel?: string;
+    status: 'success' | 'skip' | 'fail' | 'preview';
+    type?: 'metadata' | 'historical' | 'comparative' | 'outcome';
+    definitionKey?: string;
+    category?: string;
+    timeCategory?: string;
+    segmentCategory?: string;
+    fieldCount?: number;
+};
+/**
+ * Returns column definitions for the definition results table.
+ */
+export declare function getTableColumns(): Array<{
+    key: string;
+    name: string;
+}>;
+/**
+ * Builds table data rows from callback results for table rendering.
+ *
+ * @param results - The callback results to render
+ * @param recordCounts - Optional record counts by object name
+ * @returns Array of row data records
+ */
+export declare function buildTableData(results: Array<{
+    objectName: string;
+    objectLabel?: string;
+    type?: string;
+    category?: string;
+    timeCategory?: string;
+    segmentCategory?: string;
+}>, recordCounts?: Map<string, number>): Array<Record<string, string>>;
+/**
+ * Displays the Org Context section using the shared renderOrgContext utility.
+ *
+ * @param log - The logging function
+ * @param orgIdentity - The org identity data
+ * @param instanceUrl - The org instance URL
+ */
+export declare function displayOrgContext(log: (msg: string) => void, orgIdentity: {
+    organizationName?: string;
+    organizationId: string;
+    organizationType?: string;
+    isSandbox?: boolean;
+}, instanceUrl?: string): void;
+/**
+ * Displays separate Created and Skipped tables, plus summary footer.
+ *
+ * @param log - The logging function
+ * @param warn - The warning function
+ * @param callbackResults - The per-object callback results
+ * @param data - The operation result data
+ * @param dryRun - Whether this is a dry run
+ * @param recordCounts - Optional record counts by object name
+ */
+export declare function displayResultsTables(log: (msg: string) => void, warn: (msg: string) => void, callbackResults: CallbackResult[], data: CreateResult, dryRun: boolean, recordCounts?: Map<string, number>): void;
+/**
+ * Error code to i18n message key mapping for operation errors.
+ */
+export declare const ERROR_CODE_MAP: Record<string, string>;
+/**
+ * Handles operation failure by translating error codes to user-friendly messages.
+ *
+ * Returns a structured object indicating the action to take:
+ * - `type: 'exit'` — set process.exitCode and return a result
+ * - `type: 'error'` — throw via command's this.error()
+ *
+ * @param result - The failed operation result
+ * @param targetOrg - The target org identifier
+ * @param dryRun - Whether this is a dry run
+ * @param resolveErrorMessage - The error message resolution function from CuneiformCommand
+ * @returns An action descriptor for the command to execute
+ */
+export declare function resolveOperationFailure(result: {
+    success: boolean;
+    errorCode?: string;
+    message?: string;
+}, targetOrg: string, dryRun: boolean, resolveErrorMessage: (errorCodeMap: Record<string, string>, errorCode: string | undefined, fallbackMessage: string, msgs: Messages<string>) => string): {
+    type: 'exit' | 'error';
+    result?: {
+        success: boolean;
+        created: number;
+        failed: number;
+        skipped: number;
+        total: number;
+        dryRun: boolean;
+        failures: Array<{
+            objectName: string;
+            error: string;
+            errorCode: string;
+        }>;
+        results: Array<{
+            objectName: string;
+            status: string;
+        }>;
+    };
+    message?: string;
+    code?: string;
+    log?: string;
+};
+/**
+ * Builds the pre-confirmation summary box entries for the preview stage.
+ *
+ * @param uniqueObjects - Number of unique objects
+ * @param method - The profiling method
+ * @param toCreateCount - Number of definitions to create
+ * @param toSkipCount - Number of definitions to skip
+ * @returns Array of summary entries for renderSummaryBox
+ */
+export declare function buildPreConfirmSummary(uniqueObjects: number, method: string, toCreateCount: number, toSkipCount: number): SummaryEntry[];

package/lib/utils/formatting/definition-create-display.js

@@ -0,0 +1,230 @@
+/*
+ * Copyright (c) 2026, PeerNova, Inc. All Rights Reserved.
+ * PROPRIETARY AND CONFIDENTIAL. Unauthorized copying, modification,
+ * or distribution is strictly prohibited. Use is governed by the
+ * Master Subscription Agreement (MSA) between PeerNova, Inc. and the
+ * licensee. See LICENSE file in the repo root.
+ */
+/**
+ * Display formatting functions for the `sf cuneiform definition create` command.
+ *
+ * Extracted from the command class to keep the command as a thin orchestration
+ * shell. All functions are pure (no `this` references) and accept a `log`
+ * callback for output. Functions compose primitives from the shared formatting
+ * barrel (`utils/formatting/index.ts`).
+ *
+ * @module utils/formatting/definition-create-display
+ */
+import { printTable } from '@oclif/table';
+import { Messages } from '@salesforce/core';
+import { OrgInfoService } from '../../services/OrgInfoService.js';
+import { isOrgConnectivityError } from '../../adapters/errors.js';
+import { sectionHeader, renderOrgContext, renderSummaryBox, formatNumber } from './index.js';
+/**
+ * Lazily loads messages for the definition.create command.
+ * Using a getter to avoid module-level side effects.
+ */
+function getMessages() {
+    return Messages.loadMessages('@peernova/cuneiform-sf', 'definition.create');
+}
+/**
+ * Returns column definitions for the definition results table.
+ */
+export function getTableColumns() {
+    const messages = getMessages();
+    return [
+        { key: 'idx', name: '#' },
+        { key: 'object', name: messages.getMessage('table.header.object') },
+        { key: 'records', name: messages.getMessage('table.header.records') },
+        { key: 'type', name: messages.getMessage('table.header.type') },
+        { key: 'category', name: messages.getMessage('table.header.category') },
+        { key: 'time', name: messages.getMessage('table.header.time') },
+        { key: 'segment', name: messages.getMessage('table.header.segment') },
+    ];
+}
+/**
+ * Builds table data rows from callback results for table rendering.
+ *
+ * @param results - The callback results to render
+ * @param recordCounts - Optional record counts by object name
+ * @returns Array of row data records
+ */
+export function buildTableData(results, recordCounts) {
+    return results.map((r, i) => ({
+        idx: String(i + 1),
+        object: r.objectLabel ?? r.objectName,
+        records: recordCounts?.has(r.objectName) ? formatNumber(recordCounts.get(r.objectName)) : '—',
+        type: r.type ? r.type.charAt(0).toUpperCase() + r.type.slice(1) : '',
+        category: r.category ?? '',
+        time: r.timeCategory ?? '',
+        segment: r.segmentCategory ?? '',
+    }));
+}
+/**
+ * Displays the Org Context section using the shared renderOrgContext utility.
+ *
+ * @param log - The logging function
+ * @param orgIdentity - The org identity data
+ * @param instanceUrl - The org instance URL
+ */
+export function displayOrgContext(log, orgIdentity, instanceUrl) {
+    const messages = getMessages();
+    const orgName = orgIdentity.organizationName ?? '(unknown)';
+    const orgType = OrgInfoService.classifyOrgType(orgIdentity.isSandbox ?? false, orgIdentity.organizationType);
+    log('');
+    log(messages.getMessage('output.title', [orgName, orgType]));
+    log('');
+    log(renderOrgContext({
+        orgName: orgIdentity.organizationName,
+        orgId: orgIdentity.organizationId,
+        instanceUrl: instanceUrl ?? '',
+        isSandbox: orgIdentity.isSandbox ?? false,
+    }));
+}
+/**
+ * Displays separate Created and Skipped tables, plus summary footer.
+ *
+ * @param log - The logging function
+ * @param warn - The warning function
+ * @param callbackResults - The per-object callback results
+ * @param data - The operation result data
+ * @param dryRun - Whether this is a dry run
+ * @param recordCounts - Optional record counts by object name
+ */
+export function displayResultsTables(log, warn, callbackResults, data, dryRun, recordCounts) {
+    const messages = getMessages();
+    const created = callbackResults.filter((r) => r.status === 'success' || r.status === 'preview');
+    const skipped = callbackResults.filter((r) => r.status === 'skip');
+    const failed = callbackResults.filter((r) => r.status === 'fail');
+    const columns = getTableColumns();
+    // Created table
+    if (created.length > 0) {
+        const prefix = dryRun
+            ? messages.getMessage('output.tablePrefix.preview')
+            : messages.getMessage('output.tablePrefix.created');
+        log('');
+        log(sectionHeader(`${prefix} ${formatNumber(created.length)} ${messages.getMessage('output.definitionsTitle')}`));
+        log('');
+        printTable({
+            data: buildTableData(created, recordCounts),
+            columns,
+            borderStyle: 'headers-only',
+        });
+    }
+    // Skipped table
+    if (skipped.length > 0) {
+        log('');
+        log(sectionHeader(messages.getMessage('output.skippedExisting', [formatNumber(skipped.length)])));
+        log('');
+        printTable({
+            data: buildTableData(skipped, recordCounts),
+            columns,
+            borderStyle: 'headers-only',
+        });
+    }
+    // Failed entries
+    if (failed.length > 0 || data.failures.length > 0) {
+        log('');
+        warn(messages.getMessage('output.failedSummary', [String(data.failed)]));
+        for (const f of data.failures) {
+            log(`  ${f.objectName}: ${f.error}`);
+        }
+    }
+    // Summary footer
+    const uniqueObjects = new Set(callbackResults.map((r) => r.objectName)).size;
+    const summaryEntries = [
+        { key: messages.getMessage('output.summaryObjects'), value: formatNumber(uniqueObjects) },
+    ];
+    if (dryRun) {
+        summaryEntries.push({ key: messages.getMessage('output.summaryPreview'), value: formatNumber(created.length) });
+    }
+    else {
+        summaryEntries.push({ key: messages.getMessage('output.summaryCreated'), value: formatNumber(created.length) });
+    }
+    summaryEntries.push({ key: messages.getMessage('output.summarySkipped'), value: formatNumber(skipped.length) });
+    if (!dryRun) {
+        summaryEntries.push({ key: messages.getMessage('output.summaryFailed'), value: formatNumber(failed.length) });
+    }
+    log('');
+    log(renderSummaryBox({
+        title: messages.getMessage('output.summaryHeader'),
+        entries: summaryEntries,
+    }));
+}
+/**
+ * Error code to i18n message key mapping for operation errors.
+ */
+export const ERROR_CODE_MAP = {
+    CREATE_FILTER_FAILED: 'errors.filterFailed',
+    // CREATE_NO_OBJECTS_FOUND intentionally omitted — operation provides a specific message
+    // (e.g., "No objects with outcome fields found...") that is more helpful than the generic
+    // i18n fallback. resolveErrorMessage passes result.message through when code is not mapped.
+    CREATE_OBJECTS_NOT_FOUND: 'errors.objectsNotFound',
+    CREATE_OPERATION_FAILED: 'errors.operationFailed',
+    CREATE_NO_PROFILED_OBJECTS: 'errors.noProfiledObjects',
+};
+/**
+ * Handles operation failure by translating error codes to user-friendly messages.
+ *
+ * Returns a structured object indicating the action to take:
+ * - `type: 'exit'` — set process.exitCode and return a result
+ * - `type: 'error'` — throw via command's this.error()
+ *
+ * @param result - The failed operation result
+ * @param targetOrg - The target org identifier
+ * @param dryRun - Whether this is a dry run
+ * @param resolveErrorMessage - The error message resolution function from CuneiformCommand
+ * @returns An action descriptor for the command to execute
+ */
+export function resolveOperationFailure(result, targetOrg, dryRun, resolveErrorMessage) {
+    const messages = getMessages();
+    if (result.message && isOrgConnectivityError(result.message)) {
+        return {
+            type: 'error',
+            message: messages.getMessage('errors.orgUnreachable', [targetOrg]),
+            code: 'ORG_CONNECTION_FAILED',
+        };
+    }
+    if (result.errorCode === 'CREATE_OBJECTS_NOT_FOUND') {
+        return {
+            type: 'exit',
+            log: messages.getMessage('errors.objectsNotFoundDetail'),
+            result: { success: false, created: 0, failed: 0, skipped: 0, total: 0, dryRun, failures: [], results: [] },
+        };
+    }
+    const fallbackMessage = result.message ?? messages.getMessage('errors.operationFailed', [result.errorCode ?? 'UNKNOWN']);
+    const i18nMessage = resolveErrorMessage(ERROR_CODE_MAP, result.errorCode, fallbackMessage, messages);
+    return {
+        type: 'error',
+        message: i18nMessage,
+        code: result.errorCode,
+    };
+}
+/**
+ * Builds the pre-confirmation summary box entries for the preview stage.
+ *
+ * @param uniqueObjects - Number of unique objects
+ * @param method - The profiling method
+ * @param toCreateCount - Number of definitions to create
+ * @param toSkipCount - Number of definitions to skip
+ * @returns Array of summary entries for renderSummaryBox
+ */
+export function buildPreConfirmSummary(uniqueObjects, method, toCreateCount, toSkipCount) {
+    const messages = getMessages();
+    const entries = [
+        { key: messages.getMessage('output.summaryObjects'), value: formatNumber(uniqueObjects) },
+        { key: messages.getMessage('output.summaryMethod'), value: method },
+        {
+            key: messages.getMessage('output.summaryToCreate'),
+            value: messages.getMessage('output.summaryToCreateSuffix', [formatNumber(toCreateCount)]),
+        },
+    ];
+    if (toSkipCount > 0) {
+        entries.push({
+            key: messages.getMessage('output.summaryExisting'),
+            value: messages.getMessage('output.summaryExistingSuffix', [formatNumber(toSkipCount)]),
+        });
+    }
+    return entries;
+}
+//# sourceMappingURL=definition-create-display.js.map

package/lib/utils/formatting/definition-create-display.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"definition-create-display.js","sourceRoot":"","sources":["../../../src/utils/formatting/definition-create-display.ts"],"names":[],"mappings":"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"}

package/lib/utils/formatting/empty-states.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Options for formatting a contextual empty state message.
+ */
+export type EmptyStateOptions = {
+    /** The entity type that was searched for (e.g., "objects", "fields", "definitions") */
+    readonly entityType: string;
+    /** Summary of filters that were applied */
+    readonly appliedFilters?: readonly string[];
+    /** Suggestions to broaden the search */
+    readonly suggestions?: readonly string[];
+    /** Related commands the user might want to try */
+    readonly relatedCommands?: readonly string[];
+};
+/**
+ * Formats a contextual empty state message with suggestions.
+ *
+ * Returns an array of lines to be displayed when a query produces no results.
+ * Always starts with a "No {entityType} found" header line. Optional sections
+ * for applied filters, suggestions, and related commands are included only
+ * when their arrays are non-empty.
+ *
+ * Each section is separated by a blank line. List items within sections use
+ * a 2-space indent with a dash prefix.
+ *
+ * @param options - Configuration for the empty state message
+ * @returns An array of formatted lines for display
+ *
+ * @example
+ * formatEmptyState({ entityType: 'objects' })
+ * // ["No objects found matching the specified criteria."]
+ *
+ * @example
+ * formatEmptyState({ entityType: 'objects', appliedFilters: ['filter: custom'], suggestions: ['Try removing the filter'] })
+ */
+export declare function formatEmptyState(options: EmptyStateOptions): readonly string[];

package/lib/utils/formatting/empty-states.js

@@ -0,0 +1,70 @@
+/*
+ * Copyright (c) 2026, PeerNova, Inc. All Rights Reserved.
+ * PROPRIETARY AND CONFIDENTIAL. Unauthorized copying, modification,
+ * or distribution is strictly prohibited. Use is governed by the
+ * Master Subscription Agreement (MSA) between PeerNova, Inc. and the
+ * licensee. See LICENSE file in the repo root.
+ */
+/**
+ * Pure empty state formatting utilities for CLI display output.
+ *
+ * Provides contextual "no results" messages with applied filters,
+ * actionable suggestions, and related command references. All functions
+ * are pure (no side effects, no external state).
+ *
+ * @module utils/formatting/empty-states
+ */
+/**
+ * Indent prefix used for list items (2-space indent + dash + space).
+ */
+const BULLET_PREFIX = '  • ';
+/**
+ * Formats a contextual empty state message with suggestions.
+ *
+ * Returns an array of lines to be displayed when a query produces no results.
+ * Always starts with a "No {entityType} found" header line. Optional sections
+ * for applied filters, suggestions, and related commands are included only
+ * when their arrays are non-empty.
+ *
+ * Each section is separated by a blank line. List items within sections use
+ * a 2-space indent with a dash prefix.
+ *
+ * @param options - Configuration for the empty state message
+ * @returns An array of formatted lines for display
+ *
+ * @example
+ * formatEmptyState({ entityType: 'objects' })
+ * // ["No objects found matching the specified criteria."]
+ *
+ * @example
+ * formatEmptyState({ entityType: 'objects', appliedFilters: ['filter: custom'], suggestions: ['Try removing the filter'] })
+ */
+export function formatEmptyState(options) {
+    const { entityType, appliedFilters, suggestions, relatedCommands } = options;
+    const lines = [`• No ${entityType} found matching the specified criteria.`];
+    appendSection(lines, 'Filters applied:', appliedFilters);
+    appendSection(lines, 'Suggestions:', suggestions);
+    appendSection(lines, 'Related commands:', relatedCommands);
+    return lines;
+}
+/**
+ * Appends a labeled section with bullet items to the output lines.
+ *
+ * Only appends when the items array is defined and non-empty.
+ * A blank line is inserted before each section for visual separation.
+ *
+ * @param lines - The mutable output array to append to
+ * @param heading - The section heading text (e.g., "Filters applied:")
+ * @param items - The items to display as a bullet list
+ */
+function appendSection(lines, heading, items) {
+    if (!items || items.length === 0) {
+        return;
+    }
+    lines.push('');
+    lines.push(heading);
+    for (const item of items) {
+        lines.push(`${BULLET_PREFIX}${item}`);
+    }
+}
+//# sourceMappingURL=empty-states.js.map

package/lib/utils/formatting/empty-states.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"empty-states.js","sourceRoot":"","sources":["../../../src/utils/formatting/empty-states.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;GAQG;AAEH;;GAEG;AACH,MAAM,aAAa,GAAG,MAAM,CAAC;AAgB7B;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAA0B;IACzD,MAAM,EAAE,UAAU,EAAE,cAAc,EAAE,WAAW,EAAE,eAAe,EAAE,GAAG,OAAO,CAAC;IAE7E,MAAM,KAAK,GAAa,CAAC,QAAQ,UAAU,yCAAyC,CAAC,CAAC;IAEtF,aAAa,CAAC,KAAK,EAAE,kBAAkB,EAAE,cAAc,CAAC,CAAC;IACzD,aAAa,CAAC,KAAK,EAAE,cAAc,EAAE,WAAW,CAAC,CAAC;IAClD,aAAa,CAAC,KAAK,EAAE,mBAAmB,EAAE,eAAe,CAAC,CAAC;IAE3D,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;;GASG;AACH,SAAS,aAAa,CAAC,KAAe,EAAE,OAAe,EAAE,KAAoC;IAC3F,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACjC,OAAO;IACT,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACpB,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,KAAK,CAAC,IAAI,CAAC,GAAG,aAAa,GAAG,IAAI,EAAE,CAAC,CAAC;IACxC,CAAC;AACH,CAAC"}

package/lib/utils/formatting/errors.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Options for formatting an error with structured remediation guidance.
+ */
+export type ErrorRemediationOptions = {
+    /** What happened - the error description. */
+    readonly what: string;
+    /** Why it happened - root cause or context. */
+    readonly why?: string;
+    /** How to fix - actionable remediation steps. Can be a single string or an array of numbered steps. */
+    readonly fix?: string | readonly string[];
+    /** Error code for reference. */
+    readonly errorCode?: string;
+    /** Documentation link. */
+    readonly docsUrl?: string;
+};
+/**
+ * Formats an error with structured remediation guidance.
+ *
+ * Returns a multi-line string with what/why/fix sections following the
+ * what/why/fix pattern for CLI error display. Only sections with defined
+ * values are included; undefined fields are omitted entirely.
+ *
+ * @param options - The error remediation options
+ * @returns A formatted multi-line string with remediation guidance
+ *
+ * @example
+ * formatErrorWithRemediation({ what: 'Connection failed' })
+ * // "Error: Connection failed"
+ *
+ * @example
+ * formatErrorWithRemediation({ what: 'Could not connect.', why: 'Token expired.', fix: ['Run sf org login web'] })
+ */
+export declare function formatErrorWithRemediation(options: ErrorRemediationOptions): string;

package/lib/utils/formatting/errors.js

@@ -0,0 +1,72 @@
+/*
+ * Copyright (c) 2026, PeerNova, Inc. All Rights Reserved.
+ * PROPRIETARY AND CONFIDENTIAL. Unauthorized copying, modification,
+ * or distribution is strictly prohibited. Use is governed by the
+ * Master Subscription Agreement (MSA) between PeerNova, Inc. and the
+ * licensee. See LICENSE file in the repo root.
+ */
+/**
+ * Pure error formatting utilities for CLI display output.
+ *
+ * All functions are pure (no side effects, no external state) and return
+ * formatted strings with structured remediation guidance (what/why/fix pattern).
+ *
+ * @module utils/formatting/errors
+ */
+/**
+ * Prefix for the "what happened" line.
+ */
+const ERROR_PREFIX = 'Error: ';
+/**
+ * Prefix for numbered fix steps (indent + number + dot + space).
+ */
+const STEP_INDENT = '  ';
+/**
+ * Formats an error with structured remediation guidance.
+ *
+ * Returns a multi-line string with what/why/fix sections following the
+ * what/why/fix pattern for CLI error display. Only sections with defined
+ * values are included; undefined fields are omitted entirely.
+ *
+ * @param options - The error remediation options
+ * @returns A formatted multi-line string with remediation guidance
+ *
+ * @example
+ * formatErrorWithRemediation({ what: 'Connection failed' })
+ * // "Error: Connection failed"
+ *
+ * @example
+ * formatErrorWithRemediation({ what: 'Could not connect.', why: 'Token expired.', fix: ['Run sf org login web'] })
+ */
+export function formatErrorWithRemediation(options) {
+    const sections = [];
+    // What: always present (required field)
+    sections.push(`${ERROR_PREFIX}${options.what}`);
+    // Why: optional root cause
+    if (options.why !== undefined) {
+        sections.push(`Why: ${options.why}`);
+    }
+    // Fix: optional remediation (single string or numbered steps)
+    if (options.fix !== undefined) {
+        if (typeof options.fix === 'string') {
+            sections.push(`Fix: ${options.fix}`);
+        }
+        else if (options.fix.length > 0) {
+            const steps = options.fix.map((step, index) => `${STEP_INDENT}${index + 1}. ${step}`);
+            sections.push(`Fix:\n${steps.join('\n')}`);
+        }
+    }
+    // Reference: optional error code and/or docs URL
+    const referenceParts = [];
+    if (options.errorCode !== undefined) {
+        referenceParts.push(options.errorCode);
+    }
+    if (options.docsUrl !== undefined) {
+        referenceParts.push(options.docsUrl);
+    }
+    if (referenceParts.length > 0) {
+        sections.push(`Reference: ${referenceParts.join(' | ')}`);
+    }
+    return sections.join('\n\n');
+}
+//# sourceMappingURL=errors.js.map

package/lib/utils/formatting/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../../src/utils/formatting/errors.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;GAOG;AAEH;;GAEG;AACH,MAAM,YAAY,GAAG,SAAS,CAAC;AAE/B;;GAEG;AACH,MAAM,WAAW,GAAG,IAAI,CAAC;AAkBzB;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,0BAA0B,CAAC,OAAgC;IACzE,MAAM,QAAQ,GAAa,EAAE,CAAC;IAE9B,wCAAwC;IACxC,QAAQ,CAAC,IAAI,CAAC,GAAG,YAAY,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;IAEhD,2BAA2B;IAC3B,IAAI,OAAO,CAAC,GAAG,KAAK,SAAS,EAAE,CAAC;QAC9B,QAAQ,CAAC,IAAI,CAAC,QAAQ,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;IACvC,CAAC;IAED,8DAA8D;IAC9D,IAAI,OAAO,CAAC,GAAG,KAAK,SAAS,EAAE,CAAC;QAC9B,IAAI,OAAO,OAAO,CAAC,GAAG,KAAK,QAAQ,EAAE,CAAC;YACpC,QAAQ,CAAC,IAAI,CAAC,QAAQ,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;QACvC,CAAC;aAAM,IAAI,OAAO,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAClC,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,GAAG,WAAW,GAAG,KAAK,GAAG,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC;YACtF,QAAQ,CAAC,IAAI,CAAC,SAAS,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAC7C,CAAC;IACH,CAAC;IAED,iDAAiD;IACjD,MAAM,cAAc,GAAa,EAAE,CAAC;IACpC,IAAI,OAAO,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;QACpC,cAAc,CAAC,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IACzC,CAAC;IACD,IAAI,OAAO,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QAClC,cAAc,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IACvC,CAAC;IACD,IAAI,cAAc,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC9B,QAAQ,CAAC,IAAI,CAAC,cAAc,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IAC5D,CAAC;IAED,OAAO,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;AAC/B,CAAC"}

package/lib/utils/formatting/field-types.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Utility for converting Salesforce field API type names to user-friendly display labels.
+ *
+ * @module utils/formatting/field-types
+ */
+/**
+ * Sentinel value returned when the input field type is empty, null, or undefined.
+ */
+export declare const INVALID_DISPLAY = "--";
+/**
+ * Converts a Salesforce field API type name to a user-friendly display label.
+ *
+ * @param fieldType - The Salesforce API field type (e.g., `'string'`, `'reference'`, `'boolean'`).
+ * Matching is case-insensitive.
+ * @param referenceTo - Optional target object for reference (lookup) fields. When provided and
+ * `fieldType` is `'reference'`, the result includes the target object name
+ * (e.g., `'Lookup to Account'`).
+ * @returns A human-readable label for the field type, or {@link INVALID_DISPLAY} if the input
+ * is empty/null/undefined. Unknown types are returned in title case.
+ *
+ * @example
+ * ```typescript
+ * humanizeFieldType('string');                    // 'Text'
+ * humanizeFieldType('reference', 'Account');      // 'Lookup to Account'
+ * humanizeFieldType('reference');                  // 'Lookup'
+ * humanizeFieldType('BOOLEAN');                    // 'Checkbox' (case-insensitive)
+ * humanizeFieldType('customtype');                 // 'Customtype' (title case fallback)
+ * humanizeFieldType('');                           // '--'
+ * humanizeFieldType(null as unknown as string);    // '--'
+ * ```
+ */
+export declare function humanizeFieldType(fieldType: string, referenceTo?: string | null): string;