@open-captable-protocol/canton 0.2.230 → 0.2.232

package/dist/utils/deprecatedFieldNormalization.d.ts

@@ -1,881 +0,0 @@
-/**
- * Utilities for normalizing deprecated OCF fields to their current equivalents.
- *
- * OCF schema evolves over time, and some fields are deprecated in favor of new ones.
- * These utilities provide type-safe normalization and verification helpers.
- *
- * @example
- *   ```typescript
- *   import { normalizeSingularToArray, normalizeDeprecatedStockPlanFields } from './deprecatedFieldNormalization';
- *
- *   // Generic singular → array normalization
- *   const stockClassIds = normalizeSingularToArray({
- *     singularValue: data.stock_class_id,
- *     arrayValue: data.stock_class_ids,
- *   });
- *
- *   // Stock plan specific helper
- *   const normalized = normalizeDeprecatedStockPlanFields(inputData);
- *   ```
- */
-import { DEFAULT_DEPRECATED_FIELDS, DEFAULT_INTERNAL_FIELDS, type OcfComparisonOptions } from './ocfComparison';
-/**
- * Configuration for deprecation warnings.
- * Can be customized for testing or production environments.
- */
-export interface DeprecationWarningConfig {
-    /** Whether to emit console warnings for deprecated field usage (default: true in development) */
-    enabled: boolean;
-    /** Custom warning handler (default: console.warn) */
-    handler?: (message: string, details: DeprecationDetails) => void;
-}
-/**
- * Details about a deprecated field usage.
- */
-export interface DeprecationDetails {
-    /** Name of the deprecated field */
-    deprecatedField: string;
-    /** Name of the replacement field */
-    replacementField: string;
-    /** The deprecated value that was provided */
-    deprecatedValue: unknown;
-    /** Context about where the deprecation occurred */
-    context?: string;
-}
-/**
- * Global deprecation warning configuration.
- * Can be modified for testing or to customize warning behavior.
- */
-export declare const deprecationWarningConfig: DeprecationWarningConfig;
-/**
- * Emit a deprecation warning.
- *
- * @param details - Details about the deprecated field usage
- */
-export declare function emitDeprecationWarning(details: DeprecationDetails): void;
-/**
- * Parameters for normalizing a singular deprecated field to an array field.
- */
-export interface SingularToArrayParams<T> {
-    /** The deprecated singular value (may be undefined) */
-    singularValue: T | undefined;
-    /** The current array value (may be undefined or empty) */
-    arrayValue: T[] | undefined;
-    /** Name of the deprecated field (for warnings) */
-    deprecatedFieldName?: string;
-    /** Name of the replacement field (for warnings) */
-    replacementFieldName?: string;
-    /** Context for the warning message */
-    context?: string;
-}
-/**
- * Normalize a deprecated singular field to an array field.
- *
- * When both singular and array values are provided, the array takes precedence.
- * If the array is empty/undefined but singular has a value, wraps it in an array.
- *
- * @param params - Parameters for the normalization
- * @returns The normalized array value (empty array if both inputs are empty/undefined)
- *
- * @example
- *   ```typescript
- *   // Only deprecated field provided
- *   normalizeSingularToArray({
- *     singularValue: 'class-1',
- *     arrayValue: undefined,
- *   }); // Returns ['class-1']
- *
- *   // Both provided - array takes precedence
- *   normalizeSingularToArray({
- *     singularValue: 'class-1',
- *     arrayValue: ['class-2', 'class-3'],
- *   }); // Returns ['class-2', 'class-3']
- *
- *   // Neither provided
- *   normalizeSingularToArray({
- *     singularValue: undefined,
- *     arrayValue: undefined,
- *   }); // Returns []
- *   ```
- */
-export declare function normalizeSingularToArray<T>(params: SingularToArrayParams<T>): T[];
-/**
- * Input type that may contain deprecated stock_class_id field.
- * This matches OCF data that may come from older schemas.
- *
- * Note: Fields can be null (not just undefined) when parsing JSON data from external sources.
- */
-export interface StockPlanDataWithDeprecatedField {
-    /** The current array field for stock class associations */
-    stock_class_ids?: string[] | null;
-    /** @deprecated Use stock_class_ids instead. Deprecated field from older OCF versions. */
-    stock_class_id?: string | null;
-}
-/**
- * Result of normalizing deprecated stock plan fields.
- */
-export interface NormalizedStockPlanFields {
-    /** Normalized array of stock class IDs */
-    stock_class_ids: string[];
-    /** Whether a deprecated field was used */
-    usedDeprecatedField: boolean;
-}
-/**
- * Normalize deprecated stock plan fields.
- *
- * Handles the OCF deprecation of `stock_class_id` (singular) → `stock_class_ids` (array).
- *
- * @param data - Stock plan data that may contain deprecated fields
- * @param context - Optional context for deprecation warnings (e.g., "stockPlan.create")
- * @returns Object containing normalized stock_class_ids and deprecation usage flag
- *
- * @example
- *   ```typescript
- *   // Old format (deprecated)
- *   const result = normalizeDeprecatedStockPlanFields({
- *     stock_class_id: 'sc-1',
- *   });
- *   // Returns { stock_class_ids: ['sc-1'], usedDeprecatedField: true }
- *
- *   // New format
- *   const result = normalizeDeprecatedStockPlanFields({
- *     stock_class_ids: ['sc-1', 'sc-2'],
- *   });
- *   // Returns { stock_class_ids: ['sc-1', 'sc-2'], usedDeprecatedField: false }
- *   ```
- */
-export declare function normalizeDeprecatedStockPlanFields(data: StockPlanDataWithDeprecatedField, context?: string): NormalizedStockPlanFields;
-/**
- * Input type that may contain deprecated current_relationship field.
- */
-export interface StakeholderDataWithDeprecatedField {
-    /** The current array field for stakeholder relationships */
-    current_relationships?: string[] | null;
-    /** @deprecated Use current_relationships instead. */
-    current_relationship?: string | null;
-}
-/**
- * Result of normalizing deprecated stakeholder fields.
- */
-export interface NormalizedStakeholderFields {
-    /** Normalized array of stakeholder relationships */
-    current_relationships: string[];
-    /** Whether a deprecated field was used */
-    usedDeprecatedField: boolean;
-}
-/**
- * Normalize deprecated stakeholder relationship fields to their canonical form.
- *
- * This helper accepts stakeholder data that may use the legacy singular
- * `current_relationship` field or the newer array-based `current_relationships`
- * field and returns a normalized representation plus metadata about deprecation use.
- *
- * Behavior:
- * - If only `current_relationship` is provided, it is converted to a single-element
- *   `current_relationships` array and `usedDeprecatedField` is set to `true`.
- * - If `current_relationships` is provided and non-empty, it is used as-is and
- *   `usedDeprecatedField` is set to `false`, even if `current_relationship` is
- *   also present.
- * - If neither field is provided, `current_relationships` will be an empty array
- *   and `usedDeprecatedField` will be `false`.
- *
- * The input object is not mutated.
- *
- * @param data - Stakeholder data that may contain either the deprecated
- *   `current_relationship` field, the newer `current_relationships` field, or both.
- * @param context - Optional human-readable context used when emitting deprecation
- *   warnings. Defaults to `"Stakeholder"` when not provided.
- * @returns Normalized stakeholder relationship fields, including
- *   `current_relationships` (always an array) and a `usedDeprecatedField` flag
- *   indicating whether only the deprecated field was relied upon.
- *
- * @example
- * ```typescript
- * const normalized = normalizeDeprecatedStakeholderFields({
- *   current_relationship: 'EMPLOYEE',
- * });
- * normalized.current_relationships; // ['EMPLOYEE']
- * normalized.usedDeprecatedField;   // true
- * ```
- *
- * @example
- * ```typescript
- * const normalized = normalizeDeprecatedStakeholderFields({
- *   current_relationship: 'ADVISOR',
- *   current_relationships: ['FOUNDER', 'DIRECTOR'],
- * });
- * // The array field takes precedence when both are present.
- * normalized.current_relationships; // ['FOUNDER', 'DIRECTOR']
- * normalized.usedDeprecatedField;   // false
- * ```
- */
-export declare function normalizeDeprecatedStakeholderFields(data: StakeholderDataWithDeprecatedField, context?: string): NormalizedStakeholderFields;
-/**
- * Check stakeholder data for deprecated field usage without modifying the data.
- */
-export declare function checkStakeholderDeprecatedFieldUsage(data: StakeholderDataWithDeprecatedField): DeprecatedFieldUsageResult;
-/**
- * Migrate deprecated stakeholder fields to their current equivalents.
- */
-export declare function migrateStakeholderFields<T extends StakeholderDataWithDeprecatedField>(data: T): MigrationResult<Omit<T, 'current_relationship'> & {
-    current_relationships: string[];
-}>;
-/**
- * Migrate deprecated fields in multiple stakeholder objects.
- */
-export declare function migrateStakeholderFieldsBatch<T extends StakeholderDataWithDeprecatedField>(items: T[]): BatchMigrationResult<Omit<T, 'current_relationship'> & {
-    current_relationships: string[];
-}>;
-/**
- * Input type that may contain deprecated option_grant_type field.
- */
-export interface EquityCompensationIssuanceDataWithDeprecatedField {
-    /** The current compensation type field */
-    compensation_type?: string | null;
-    /** @deprecated Use compensation_type instead. */
-    option_grant_type?: string | null;
-}
-/**
- * Result of normalizing deprecated equity compensation issuance fields.
- */
-export interface NormalizedEquityCompensationIssuanceFields {
-    /** Normalized compensation type */
-    compensation_type: string | null;
-    /** Whether a deprecated field was used */
-    usedDeprecatedField: boolean;
-    /** The original deprecated value (if any) */
-    originalDeprecatedValue?: string;
-}
-/**
- * Convert deprecated option_grant_type value to current compensation_type value.
- */
-export declare function convertOptionGrantTypeToCompensationType(optionGrantType: string): string;
-/**
- * Normalize deprecated equity compensation issuance fields to their canonical form.
- *
- * This helper converts the legacy `option_grant_type` field to the current
- * `compensation_type` field, applying value mappings as needed:
- * - `NSO` → `OPTION_NSO`
- * - `ISO` → `OPTION_ISO`
- * - `INTL` → `OPTION`
- * - Unknown values are passed through unchanged
- *
- * Behavior:
- * - If only `option_grant_type` is provided, it is converted to `compensation_type`
- *   with the appropriate value mapping and `usedDeprecatedField` is set to `true`.
- * - If `compensation_type` is provided and non-empty, it is used as-is and
- *   `usedDeprecatedField` is set to `false`, even if `option_grant_type` is
- *   also present.
- * - If neither field is provided, `compensation_type` will be `null`.
- *
- * The input object is not mutated.
- *
- * @param data - Equity compensation issuance data that may contain either the deprecated
- *   `option_grant_type` field, the newer `compensation_type` field, or both.
- * @param context - Optional human-readable context used when emitting deprecation
- *   warnings. Defaults to `"EquityCompensationIssuance"` when not provided.
- * @returns Normalized fields including `compensation_type`, a `usedDeprecatedField` flag,
- *   and optionally the `originalDeprecatedValue` if conversion occurred.
- *
- * @example
- * ```typescript
- * const normalized = normalizeDeprecatedEquityCompensationIssuanceFields({
- *   option_grant_type: 'NSO',
- * });
- * normalized.compensation_type;      // 'OPTION_NSO'
- * normalized.usedDeprecatedField;    // true
- * normalized.originalDeprecatedValue; // 'NSO'
- * ```
- *
- * @example
- * ```typescript
- * const normalized = normalizeDeprecatedEquityCompensationIssuanceFields({
- *   option_grant_type: 'ISO',
- *   compensation_type: 'RSU',
- * });
- * // The current field takes precedence when both are present.
- * normalized.compensation_type;   // 'RSU'
- * normalized.usedDeprecatedField; // false
- * ```
- */
-export declare function normalizeDeprecatedEquityCompensationIssuanceFields(data: EquityCompensationIssuanceDataWithDeprecatedField, context?: string): NormalizedEquityCompensationIssuanceFields;
-/**
- * Check equity compensation issuance data for deprecated field usage.
- */
-export declare function checkEquityCompensationIssuanceDeprecatedFieldUsage(data: EquityCompensationIssuanceDataWithDeprecatedField): DeprecatedFieldUsageResult;
-/**
- * Migrate deprecated equity compensation issuance fields.
- */
-export declare function migrateEquityCompensationIssuanceFields<T extends EquityCompensationIssuanceDataWithDeprecatedField>(data: T): MigrationResult<Omit<T, 'option_grant_type'> & {
-    compensation_type: string | null;
-}>;
-/**
- * Migrate deprecated fields in multiple equity compensation issuance objects.
- */
-export declare function migrateEquityCompensationIssuanceFieldsBatch<T extends EquityCompensationIssuanceDataWithDeprecatedField>(items: T[]): BatchMigrationResult<Omit<T, 'option_grant_type'> & {
-    compensation_type: string | null;
-}>;
-/**
- * Result of checking for deprecated field usage.
- */
-export interface DeprecatedFieldUsageResult {
-    /** Whether any deprecated fields were detected */
-    hasDeprecatedFields: boolean;
-    /** List of deprecated fields that were used */
-    deprecatedFieldsUsed: string[];
-}
-/**
- * Check stock plan data for deprecated field usage without modifying the data.
- *
- * @param data - Stock plan data to check
- * @returns Result indicating whether deprecated fields were used
- *
- * @example
- *   ```typescript
- *   const result = checkStockPlanDeprecatedFieldUsage({
- *     stock_class_id: 'sc-1', // deprecated
- *   });
- *   // Returns { hasDeprecatedFields: true, deprecatedFieldsUsed: ['stock_class_id'] }
- *   ```
- */
-export declare function checkStockPlanDeprecatedFieldUsage(data: StockPlanDataWithDeprecatedField): DeprecatedFieldUsageResult;
-/**
- * Configuration for a deprecated field mapping.
- */
-export interface DeprecatedFieldMapping {
-    /** The deprecated field name */
-    deprecatedField: string;
-    /** The replacement field name */
-    replacementField: string;
-    /** The type of deprecation (singular_to_array, renamed, value_mapped, removed) */
-    deprecationType: 'singular_to_array' | 'renamed' | 'value_mapped' | 'removed';
-    /** Value mapping for 'value_mapped' deprecation type */
-    valueMap?: Record<string, string>;
-}
-/**
- * Value mapping for option_grant_type -> compensation_type conversion.
- */
-export declare const OPTION_GRANT_TYPE_TO_COMPENSATION_TYPE: Record<string, string>;
-/**
- * Known OCF deprecated field mappings.
- * Add new deprecations here as they are discovered.
- */
-export declare const OCF_DEPRECATED_FIELDS: Record<string, DeprecatedFieldMapping[]>;
-/**
- * Get the list of deprecated field mappings for an OCF object type.
- *
- * @param objectType - The OCF object type name (e.g., 'StockPlan')
- * @returns Array of deprecated field mappings for the object type
- */
-export declare function getDeprecatedFieldMappings(objectType: string): DeprecatedFieldMapping[];
-/**
- * Check if a specific field is deprecated for an OCF object type.
- *
- * @param objectType - The OCF object type name
- * @param fieldName - The field name to check
- * @returns The deprecation mapping if the field is deprecated, undefined otherwise
- */
-export declare function getFieldDeprecation(objectType: string, fieldName: string): DeprecatedFieldMapping | undefined;
-/**
- * Check an object for any deprecated field usage based on known deprecations.
- *
- * @param objectType - The OCF object type name
- * @param data - The object data to check
- * @returns Result indicating which deprecated fields were used
- *
- * @example
- *   ```typescript
- *   const result = checkDeprecatedFields('StockPlan', {
- *     stock_class_id: 'sc-1', // deprecated
- *     plan_name: 'Equity Plan',
- *   });
- *   // Returns { hasDeprecatedFields: true, deprecatedFieldsUsed: ['stock_class_id'] }
- *   ```
- */
-export declare function checkDeprecatedFields(objectType: string, data: Record<string, unknown>): DeprecatedFieldUsageResult;
-/**
- * Item with an identifier for tracking in batch operations.
- */
-export interface IdentifiableItem {
-    /** Unique identifier for the item */
-    id?: string;
-    /** Index in the original array (for items without id) */
-    index?: number;
-}
-/**
- * Result of checking a single object in a batch operation.
- */
-export interface BatchItemResult extends DeprecatedFieldUsageResult {
-    /** Identifier for the item (id or index-based) */
-    itemId: string;
-    /** The object type that was checked */
-    objectType: string;
-}
-/**
- * Aggregated result of checking multiple objects for deprecated field usage.
- */
-export interface BatchDeprecatedFieldsResult {
-    /** Total number of objects checked */
-    totalChecked: number;
-    /** Number of objects with deprecated fields */
-    objectsWithDeprecatedFields: number;
-    /** Number of objects without deprecated fields */
-    objectsWithoutDeprecatedFields: number;
-    /** Whether any deprecated fields were found */
-    hasDeprecatedFields: boolean;
-    /** Per-item results for objects that have deprecated fields */
-    itemsWithDeprecatedFields: BatchItemResult[];
-    /** Summary of deprecated field usage by field name */
-    deprecatedFieldSummary: Record<string, number>;
-    /** Summary of deprecated field usage by object type */
-    objectTypeSummary: Record<string, {
-        total: number;
-        withDeprecated: number;
-    }>;
-}
-/**
- * Input item for batch verification.
- */
-export interface BatchVerificationItem {
-    /** The OCF object type (e.g., 'StockPlan') */
-    objectType: string;
-    /** The data to check */
-    data: Record<string, unknown>;
-    /** Optional identifier for the item */
-    id?: string;
-}
-/**
- * Check multiple objects for deprecated field usage in a single batch operation.
- *
- * @param items - Array of items to check, each with objectType and data
- * @returns Aggregated result with summary statistics and per-item details
- *
- * @example
- *   ```typescript
- *   const result = checkDeprecatedFieldsBatch([
- *     { objectType: 'StockPlan', data: { stock_class_id: 'sc-1', plan_name: 'Plan A' }, id: 'plan-1' },
- *     { objectType: 'StockPlan', data: { stock_class_ids: ['sc-2'], plan_name: 'Plan B' }, id: 'plan-2' },
- *   ]);
- *   // result.objectsWithDeprecatedFields === 1
- *   // result.deprecatedFieldSummary === { stock_class_id: 1 }
- *   ```
- */
-export declare function checkDeprecatedFieldsBatch(items: BatchVerificationItem[]): BatchDeprecatedFieldsResult;
-/**
- * Check an array of objects of the same type for deprecated field usage.
- *
- * @param objectType - The OCF object type for all items
- * @param items - Array of data objects to check
- * @returns Aggregated result with summary statistics
- *
- * @example
- *   ```typescript
- *   const stockPlans = [
- *     { id: 'plan-1', stock_class_id: 'sc-1', plan_name: 'Plan A' },
- *     { id: 'plan-2', stock_class_ids: ['sc-2'], plan_name: 'Plan B' },
- *   ];
- *   const result = checkDeprecatedFieldsForType('StockPlan', stockPlans);
- *   ```
- */
-export declare function checkDeprecatedFieldsForType(objectType: string, items: Array<Record<string, unknown>>): BatchDeprecatedFieldsResult;
-/**
- * Result of migrating deprecated fields in an object.
- */
-export interface MigrationResult<T> {
-    /** The migrated data with deprecated fields converted to current format */
-    data: T;
-    /** Whether any migrations were performed */
-    migrated: boolean;
-    /** List of fields that were migrated */
-    migratedFields: string[];
-    /** List of warnings (e.g., both deprecated and current fields present) */
-    warnings: string[];
-}
-/**
- * Migrate deprecated stock plan fields to their current equivalents.
- *
- * This function creates a new object with deprecated fields converted to current format.
- * The original object is not modified.
- *
- * @param data - Stock plan data that may contain deprecated fields
- * @returns Migration result with normalized data and migration details
- *
- * @example
- *   ```typescript
- *   const result = migrateStockPlanFields({
- *     id: 'plan-1',
- *     stock_class_id: 'sc-1', // deprecated
- *     plan_name: 'Equity Plan',
- *   });
- *   // result.data.stock_class_ids === ['sc-1']
- *   // result.migrated === true
- *   // result.migratedFields === ['stock_class_id']
- *   ```
- */
-export declare function migrateStockPlanFields<T extends StockPlanDataWithDeprecatedField>(data: T): MigrationResult<Omit<T, 'stock_class_id'> & {
-    stock_class_ids: string[];
-}>;
-/**
- * Batch result for migrating multiple objects.
- */
-export interface BatchMigrationResult<T> {
-    /** Migrated items */
-    items: Array<MigrationResult<T>>;
-    /** Total number of items processed */
-    totalProcessed: number;
-    /** Number of items that required migration */
-    itemsMigrated: number;
-    /** Number of items with warnings */
-    itemsWithWarnings: number;
-    /** Summary of migrated fields */
-    migratedFieldsSummary: Record<string, number>;
-}
-/**
- * Migrate deprecated fields in multiple stock plan objects.
- *
- * @param items - Array of stock plan data objects
- * @returns Batch migration result with all migrated items
- *
- * @example
- *   ```typescript
- *   const plans = [
- *     { id: 'plan-1', stock_class_id: 'sc-1' },
- *     { id: 'plan-2', stock_class_ids: ['sc-2'] },
- *   ];
- *   const result = migrateStockPlanFieldsBatch(plans);
- *   // result.itemsMigrated === 1
- *   ```
- */
-export declare function migrateStockPlanFieldsBatch<T extends StockPlanDataWithDeprecatedField>(items: T[]): BatchMigrationResult<Omit<T, 'stock_class_id'> & {
-    stock_class_ids: string[];
-}>;
-/**
- * Detailed deprecation report for analysis and documentation.
- */
-export interface DeprecationReport {
-    /** Timestamp when the report was generated */
-    generatedAt: string;
-    /** Summary statistics */
-    summary: {
-        /** Total objects analyzed */
-        totalObjects: number;
-        /** Objects with deprecated fields */
-        objectsWithDeprecatedFields: number;
-        /** Percentage of objects with deprecated fields */
-        deprecationPercentage: number;
-        /** Total deprecated field usages */
-        totalDeprecatedFieldUsages: number;
-    };
-    /** Breakdown by object type */
-    byObjectType: Record<string, {
-        total: number;
-        withDeprecatedFields: number;
-        deprecationPercentage: number;
-        fieldsUsed: Record<string, number>;
-    }>;
-    /** Breakdown by deprecated field */
-    byField: Record<string, {
-        totalUsages: number;
-        objectTypesAffected: string[];
-        replacementField: string;
-        deprecationType: string;
-    }>;
-    /** List of all affected items (optional, for detailed reports) */
-    affectedItems?: Array<{
-        itemId: string;
-        objectType: string;
-        deprecatedFieldsUsed: string[];
-    }>;
-}
-/**
- * Options for generating a deprecation report.
- */
-export interface DeprecationReportOptions {
-    /** Whether to include detailed list of affected items (default: false for large datasets) */
-    includeAffectedItems?: boolean;
-    /** Maximum number of affected items to include (default: 100) */
-    maxAffectedItems?: number;
-}
-/**
- * Generate a detailed deprecation report from batch verification results.
- *
- * @param batchResult - Result from checkDeprecatedFieldsBatch or checkDeprecatedFieldsForType
- * @param options - Options for report generation
- * @returns Detailed deprecation report
- *
- * @example
- *   ```typescript
- *   const items = [
- *     { objectType: 'StockPlan', data: { stock_class_id: 'sc-1' }, id: 'plan-1' },
- *   ];
- *   const batchResult = checkDeprecatedFieldsBatch(items);
- *   const report = generateDeprecationReport(batchResult);
- *   console.log(`${report.summary.deprecationPercentage}% of objects use deprecated fields`);
- *   ```
- */
-export declare function generateDeprecationReport(batchResult: BatchDeprecatedFieldsResult, options?: DeprecationReportOptions): DeprecationReport;
-/**
- * Result of validating deprecated field usage.
- */
-export interface DeprecationValidationResult {
-    /** Whether validation passed (no deprecated fields, or within acceptable limits) */
-    valid: boolean;
-    /** Validation errors (if any) */
-    errors: string[];
-    /** Validation warnings (if any) */
-    warnings: string[];
-    /** The underlying check result */
-    checkResult: DeprecatedFieldUsageResult;
-}
-/**
- * Options for deprecation validation.
- */
-export interface DeprecationValidationOptions {
-    /** Whether to treat deprecated field usage as an error (default: false, treated as warning) */
-    treatAsError?: boolean;
-    /** Specific deprecated fields to ignore in validation */
-    ignoreFields?: string[];
-    /** Custom error message prefix */
-    errorMessagePrefix?: string;
-}
-/**
- * Validate an object for deprecated field usage.
- *
- * This is useful for validation pipelines where you want to:
- * - Warn users about deprecated field usage
- * - Optionally fail validation on deprecated fields
- * - Generate clear validation messages
- *
- * @param objectType - The OCF object type
- * @param data - The data to validate
- * @param options - Validation options
- * @returns Validation result
- *
- * @example
- *   ```typescript
- *   const result = validateDeprecatedFields('StockPlan', {
- *     stock_class_id: 'sc-1',
- *   }, { treatAsError: false });
- *
- *   if (!result.valid) {
- *     console.error(result.errors.join('\n'));
- *   } else if (result.warnings.length > 0) {
- *     console.warn(result.warnings.join('\n'));
- *   }
- *   ```
- */
-export declare function validateDeprecatedFields(objectType: string, data: Record<string, unknown>, options?: DeprecationValidationOptions): DeprecationValidationResult;
-/**
- * Create a validator function for use in validation pipelines.
- *
- * @param objectType - The OCF object type to validate
- * @param options - Validation options
- * @returns A validator function that returns DeprecationValidationResult
- *
- * @example
- *   ```typescript
- *   const validateStockPlan = createDeprecatedFieldsValidator('StockPlan', {
- *     treatAsError: false,
- *   });
- *
- *   // Use in a validation pipeline
- *   const result = validateStockPlan(stockPlanData);
- *   ```
- */
-export declare function createDeprecatedFieldsValidator(objectType: string, options?: DeprecationValidationOptions): (data: Record<string, unknown>) => DeprecationValidationResult;
-/**
- * Assert that an object does not use deprecated fields.
- * Throws an error if deprecated fields are detected.
- *
- * @param objectType - The OCF object type
- * @param data - The data to check
- * @param options - Validation options (ignoreFields only)
- * @throws Error if deprecated fields are detected
- *
- * @example
- *   ```typescript
- *   try {
- *     assertNoDeprecatedFields('StockPlan', stockPlanData);
- *     // Proceed with operation
- *   } catch (error) {
- *     // Handle deprecated field usage
- *   }
- *   ```
- */
-export declare function assertNoDeprecatedFields(objectType: string, data: Record<string, unknown>, options?: Pick<DeprecationValidationOptions, 'ignoreFields'>): void;
-/**
- * Register a new deprecated field mapping.
- *
- * This is useful for extending the built-in deprecation registry with
- * custom or newly discovered deprecations.
- *
- * @param objectType - The OCF object type
- * @param mapping - The deprecation mapping to register
- *
- * @example
- *   ```typescript
- *   // Register a new deprecation
- *   registerDeprecatedFieldMapping('SomeOcfType', {
- *     deprecatedField: 'old_field',
- *     replacementField: 'new_fields',
- *     deprecationType: 'singular_to_array',
- *   });
- *   ```
- */
-export declare function registerDeprecatedFieldMapping(objectType: string, mapping: DeprecatedFieldMapping): void;
-/**
- * Get all registered object types that have deprecated field mappings.
- *
- * @returns Array of object type names
- */
-export declare function getRegisteredObjectTypes(): string[];
-/**
- * Get all registered deprecated field mappings.
- *
- * @returns Copy of the deprecated fields registry
- */
-export declare function getAllDeprecatedFieldMappings(): Record<string, DeprecatedFieldMapping[]>;
-/**
- * Result of automatic OCF data normalization.
- */
-export interface NormalizedOcfDataResult<T> {
-    /** The normalized data with deprecated fields converted */
-    data: T;
-    /** Whether any normalization was performed */
-    normalized: boolean;
-    /** List of deprecated fields that were normalized */
-    normalizedFields: string[];
-    /** Warnings generated during normalization */
-    warnings: string[];
-}
-/**
- * Automatically normalize deprecated fields in OCF data based on entity type.
- *
- * This function is designed to be called by the SDK internally when processing
- * OCF data, making deprecated field handling transparent to end-users.
- *
- * @param entityType - The OCF entity type (e.g., 'stockPlan')
- * @param data - The OCF data that may contain deprecated fields
- * @param options - Optional configuration
- * @returns The normalized data with deprecated fields converted to current format
- *
- * @example
- *   ```typescript
- *   // SDK automatically normalizes deprecated fields
- *   const result = normalizeDeprecatedOcfFields('stockPlan', {
- *     id: 'plan-1',
- *     stock_class_id: 'sc-1', // deprecated, automatically converted
- *     plan_name: 'Equity Plan',
- *   });
- *   // result.data.stock_class_ids === ['sc-1']
- *   ```
- */
-export declare function normalizeDeprecatedOcfFields<T extends Record<string, unknown>>(entityType: string, data: T, options?: {
-    emitWarnings?: boolean;
-    context?: string;
-}): NormalizedOcfDataResult<T>;
-/**
- * Check if an entity type has registered deprecations.
- *
- * @param entityType - The OCF entity type (e.g., 'stockPlan')
- * @returns true if the entity type has deprecation mappings
- */
-export declare function hasDeprecationsForEntityType(entityType: string): boolean;
-/**
- * Register a mapping from entity type to object type for automatic normalization.
- *
- * @param entityType - The OcfEntityType used in batch API (e.g., 'stockPlan')
- * @param objectType - The object type name used in deprecation registry (e.g., 'StockPlan')
- */
-export declare function registerEntityTypeMapping(entityType: string, objectType: string): void;
-/**
- * Options for normalizeOcfObject.
- */
-export interface NormalizeOcfObjectOptions {
-    /** Whether to emit deprecation warnings (default: true) */
-    emitWarnings?: boolean;
-    /** Context for deprecation warnings */
-    context?: string;
-}
-/**
- * Normalize an OCF object by applying all deprecation normalizations.
- *
- * This function auto-detects the object type from the `object_type` field and applies:
- * 1. PlanSecurity -> EquityCompensation object_type normalization
- * 2. Deprecated field normalizations (singular->array, value mappings, etc.)
- * 3. Semantic normalizations (e.g., quantity_source: 'UNSPECIFIED' when quantity is absent)
- */
-export declare function normalizeOcfObject<T extends Record<string, unknown>>(data: T, options?: NormalizeOcfObjectOptions): NormalizedOcfDataResult<T>;
-/**
- * Options for areOcfObjectsEquivalent comparison.
- */
-export interface OcfEquivalenceOptions extends OcfComparisonOptions {
-    /** Whether to normalize objects before comparison (default: true) */
-    normalizeBeforeCompare?: boolean;
-    /** Whether to emit deprecation warnings during normalization (default: false) */
-    emitNormalizationWarnings?: boolean;
-}
-/**
- * Result of OCF equivalence comparison.
- */
-export interface OcfEquivalenceResult {
-    /** Whether the objects are equivalent after normalization */
-    equivalent: boolean;
-    /** Normalization details for the first object */
-    normalizationA: {
-        wasNormalized: boolean;
-        normalizedFields: string[];
-        warnings: string[];
-    };
-    /** Normalization details for the second object */
-    normalizationB: {
-        wasNormalized: boolean;
-        normalizedFields: string[];
-        warnings: string[];
-    };
-}
-/**
- * Compare two OCF objects for semantic equivalence after normalizing deprecated fields.
- */
-export declare function areOcfObjectsEquivalent(dbObject: Record<string, unknown>, chainObject: Record<string, unknown>, options?: OcfEquivalenceOptions): boolean;
-/**
- * Compare two OCF objects with detailed results.
- */
-export declare function compareOcfObjects(dbObject: Record<string, unknown>, chainObject: Record<string, unknown>, options?: OcfEquivalenceOptions): OcfEquivalenceResult;
-export { DEFAULT_DEPRECATED_FIELDS, DEFAULT_INTERNAL_FIELDS };
-/**
- * Configuration for required array fields by entity type.
- * These fields must be arrays (empty or populated), but raw data might have them as null/undefined.
- * The SDK normalizes these to empty arrays automatically.
- */
-export declare const REQUIRED_ARRAY_FIELDS: Partial<Record<string, string[]>>;
-/**
- * Normalize required array fields in OCF data.
- * This ensures array fields that are null/undefined become empty arrays.
- *
- * Uses lazy cloning - only creates a copy when modification is actually needed,
- * and clones once then mutates the clone for efficiency.
- *
- * @param entityType - The OCF entity type
- * @param data - The OCF data that may have null/undefined array fields
- * @returns The normalized data with array fields as arrays
- */
-export declare function normalizeRequiredArrayFields<T extends Record<string, unknown>>(entityType: string, data: T): {
-    data: T;
-    normalizedFields: string[];
-};
-/**
- * Register required array fields for an entity type.
- *
- * @param entityType - The OCF entity type (e.g., 'stockPlan')
- * @param fields - Array of field names that must be arrays
- */
-export declare function registerRequiredArrayFields(entityType: string, fields: string[]): void;
-/**
- * Get required array fields for an entity type.
- *
- * @param entityType - The OCF entity type
- * @returns Array of field names that must be arrays
- */
-export declare function getRequiredArrayFields(entityType: string): string[];
-//# sourceMappingURL=deprecatedFieldNormalization.d.ts.map