zon-format/dist/core/versioning.d.ts

ZON: The most token-efficient serialization format for LLMs - beats CSV, TOON, JSON, and all competitors

/**
 * ZON Document Versioning Utilities
 *
 * Provides version embedding, extraction, comparison, and validation
 * for ZON documents to support schema evolution and backward compatibility.
 */
export interface ZonDocumentMetadata {
    /** Semantic version of the document format (e.g., "1.3.0") */
    version: string;
    /** Optional schema identifier (e.g., "user-profile-v2") */
    schemaId?: string;
    /** Encoding format used ("zon" | "zon-binary") */
    encoding?: string;
    /** Unix timestamp when document was created */
    timestamp?: number;
    /** Custom metadata fields */
    custom?: Record<string, any>;
}
/**
 * Embeds version metadata into a data object.
 * Adds a special __zon_meta field to the root object.
 *
 * @param data - Data object to add metadata to
 * @param version - Semantic version string (e.g., "1.0.0")
 * @param schemaId - Optional schema identifier
 * @returns Data object with embedded metadata
 *
 * @example
 * ```typescript
 * const data = { users: [{ id: 1, name: "Alice" }] };
 * const versioned = embedVersion(data, "2.0.0", "user-schema");
 * // Result: { __zon_meta: { version: "2.0.0", schemaId: "user-schema", ... }, users: [...] }
 * ```
 */
export declare function embedVersion(data: any, version: string, schemaId?: string, encoding?: string): any;
/**
 * Extracts version metadata from a decoded ZON document.
 *
 * @param data - Decoded data object
 * @returns Metadata if present, null otherwise
 *
 * @example
 * ```typescript
 * const decoded = decode(zonString);
 * const meta = extractVersion(decoded);
 * if (meta) {
 *   console.log(`Version: ${meta.version}`);
 * }
 * ```
 */
export declare function extractVersion(data: any): ZonDocumentMetadata | null;
/**
 * Removes version metadata from a data object.
 *
 * @param data - Data object with metadata
 * @returns Data object without __zon_meta field
 */
export declare function stripVersion(data: any): any;
/**
 * Compares two semantic version strings.
 *
 * @param v1 - First version (e.g., "1.2.3")
 * @param v2 - Second version (e.g., "2.0.0")
 * @returns -1 if v1 < v2, 0 if equal, 1 if v1 > v2
 *
 * @example
 * ```typescript
 * compareVersions("1.0.0", "2.0.0")  // -1
 * compareVersions("2.0.0", "1.0.0")  // 1
 * compareVersions("1.0.0", "1.0.0")  // 0
 * ```
 */
export declare function compareVersions(v1: string, v2: string): number;
/**
 * Checks if a version is compatible with a required version.
 * Considers backward compatibility: patch and minor version bumps are compatible.
 *
 * @param current - Current version
 * @param required - Required version
 * @returns True if current version is compatible with required
 *
 * @example
 * ```typescript
 * isCompatible("1.2.3", "1.0.0")  // true (same major)
 * isCompatible("2.0.0", "1.0.0")  // false (different major)
 * isCompatible("1.0.0", "1.2.0")  // false (current is older)
 * ```
 */
export declare function isCompatible(current: string, required: string): boolean;
/**
 * Validates a semantic version string.
 *
 * @param version - Version string to validate
 * @returns True if valid semantic version format
 */
export declare function isValidVersion(version: string): boolean;
/**
 * Parses a version string into components.
 *
 * @param version - Version string (e.g., "1.2.3-alpha+build")
 * @returns Object with major, minor, patch, prerelease, build
 */
export declare function parseVersion(version: string): {
    major: number;
    minor: number;
    patch: number;
    prerelease?: string;
    build?: string;
};