zon-format
Version:
ZON: The most token-efficient serialization format for LLMs - beats CSV, TOON, JSON, and all competitors
110 lines (109 loc) • 3.56 kB
TypeScript
/**
* Adaptive Encoding API
*
* Provides intelligent format selection based on data characteristics.
*/
import { type EncodeOptions } from './encoder';
import { type ComplexityMetrics } from './analyzer';
export { DataComplexityAnalyzer, type ComplexityMetrics, type AnalysisResult } from './analyzer';
export type EncodingMode = 'compact' | 'readable' | 'llm-optimized';
export interface AdaptiveEncodeOptions extends EncodeOptions {
/** Encoding mode (default: 'compact') */
mode?: EncodingMode;
/** Complexity threshold for auto mode (0.0-1.0, default: 0.6) */
complexityThreshold?: number;
/** Maximum nesting depth for table format (default: 3) */
maxNestingForTable?: number;
/** Force specific encoding for paths */
forceFormatPaths?: Record<string, 'table' | 'inline' | 'json'>;
/** Encoding hints */
hints?: {
/** Target audience for the output */
targetAudience?: 'llm' | 'human' | 'machine';
/** Optimization priority */
prioritize?: 'size' | 'readability' | 'speed';
};
/** Indentation size for readable mode (default: 2) */
indent?: number;
/** Enable detailed analysis logging */
debug?: boolean;
}
export interface AdaptiveEncodeResult {
/** Encoded ZON string */
output: string;
/** Complexity metrics */
metrics: ComplexityMetrics;
/** Mode that was used */
modeUsed: EncodingMode;
/** Reasons for encoding decisions */
decisions: string[];
}
/**
* Adaptive encoder that selects optimal encoding strategy.
*/
export declare class AdaptiveEncoder {
private analyzer;
constructor();
/**
* Encodes data using adaptive strategy selection.
*
* @param data - Data to encode
* @param options - Adaptive encoding options
* @returns Encoded string or detailed result if debug=true
*/
encode(data: any, options?: AdaptiveEncodeOptions): string | AdaptiveEncodeResult;
/**
* Selects encoding options for auto mode.
*/
private selectAutoOptions;
/**
* Gets encoding options for compact mode.
*/
private getCompactOptions;
/**
* Gets encoding options for readable mode.
* Tables are enabled for uniform data, but dictionary compression and delta encoding are disabled.
*/
private getReadableOptions;
/**
* Gets encoding options for LLM-optimized mode.
* Dictionary compression and delta encoding disabled for clarity - shows actual values not indices.
*/
private getLLMOptimizedOptions;
/**
* Determines effective mode based on analysis.
*/
private determineEffectiveMode;
}
/**
* Encodes data with adaptive strategy selection.
*
* @param data - Data to encode
* @param options - Adaptive encoding options
* @returns Encoded ZON string
*
* @example
* ```typescript
* // Auto mode - analyzes and selects best strategy
* const output = encodeAdaptive(data);
*
* // Explicit mode
* const output = encodeAdaptive(data, { mode: 'compact' });
*
* // With debugging
* const result = encodeAdaptive(data, { debug: true });
* console.log(result.decisions); // See encoding decisions
* ```
*/
export declare function encodeAdaptive(data: any, options?: AdaptiveEncodeOptions): string | AdaptiveEncodeResult;
/**
* Analyzes data and recommends optimal encoding mode.
*
* @param data - Data to analyze
* @returns Recommended mode and reasoning
*/
export declare function recommendMode(data: any): {
mode: EncodingMode;
reason: string;
confidence: number;
};