@zenoaihq/tson/dist/index.d.cts

Token-efficient Structured Object Notation – a compact serialization format designed for efficient data exchange with LLMs

/**
 * TSON Type Definitions
 *
 * TypeScript type definitions for TSON serialization/deserialization.
 */
/**
 * Primitive TSON value types
 */
type TSONPrimitive = string | number | boolean | null;
/**
 * TSON array type
 */
type TSONArray = TSONValue[];
/**
 * TSON object type
 */
type TSONObject = {
    [key: string]: TSONValue;
};
/**
 * Any valid TSON value
 */
type TSONValue = TSONPrimitive | TSONArray | TSONObject;
/**
 * Schema map for nested object structures
 * Maps field names to their nested schemas (or null if no schema)
 */
type SchemaMap = Record<string, string[] | null>;
/**
 * Result of parsing a key with optional schema notation
 */
interface KeySchema {
    keyName: string;
    schema: string[] | null;
}
/**
 * Result of parsing keys with optional row count
 */
interface ParsedKeys {
    keys: string[];
    count: number | null;
}

/**
 * TSON Serializer
 *
 * Converts JavaScript data structures to TSON format.
 */

/**
 * Serialize JavaScript object to TSON formatted string.
 *
 * @example
 * dumps({ name: "Alice", age: 30 })
 * // Returns: '{@name,age|Alice,30}'
 *
 * @example
 * dumps([{ id: 1, name: "Alice" }, { id: 2, name: "Bob" }])
 * // Returns: '{@id,name#2|1,Alice|2,Bob}'
 */
declare function dumps(data: TSONValue): string;
/**
 * Serialize JavaScript object to TSON formatted file (Node.js only).
 *
 * @param data - JavaScript object to serialize
 * @param filePath - Path to file to write
 */
declare function dump(data: TSONValue, filePath: string): Promise<void>;

/**
 * TSON Deserializer
 *
 * Parses TSON format back to JavaScript data structures.
 */

/**
 * Deserialize TSON formatted string to JavaScript object.
 *
 * @example
 * loads('{@name,age|Alice,30}')
 * // Returns: { name: 'Alice', age: 30 }
 *
 * @example
 * loads('{@id,name#2|1,Alice|2,Bob}')
 * // Returns: [{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }]
 */
declare function loads(s: string): TSONValue;
/**
 * Deserialize TSON formatted file to JavaScript object (Node.js only).
 *
 * @param filePath - Path to file to read
 * @returns Parsed JavaScript object
 */
declare function load(filePath: string): Promise<TSONValue>;

/**
 * TSON Utility Functions
 *
 * Helper functions for serialization, deserialization, and validation.
 */

/**
 * Determine if a string value needs to be quoted in TSON format.
 *
 * Strings need quoting if they:
 * - Are empty
 * - Contain special delimiter characters
 * - Have leading/trailing whitespace
 * - Look like numbers (to preserve them as strings)
 * - Look like reserved words (true/false/null) when we want them as strings
 */
declare function needsQuoting(value: string): boolean;
/**
 * Check if a string looks like a numeric value.
 *
 * Used to determine if we should quote a string to preserve it as a string
 * rather than having it parsed as a number.
 */
declare function looksLikeNumber(value: string): boolean;
/**
 * Escape special characters in a string for quoted representation.
 *
 * Uses standard JSON escape sequences.
 */
declare function escapeString(value: string): string;
/**
 * Unescape a quoted string back to its original form.
 *
 * Reverses the escaping done by escapeString().
 */
declare function unescapeString(value: string): string;
/**
 * Format a primitive value as TSON string.
 */
declare function formatPrimitive(value: TSONValue): string;
/**
 * Parse a TSON primitive value string to JavaScript type.
 */
declare function parsePrimitive(value: string): TSONValue;
/**
 * Check if a value is an array of objects with identical keys.
 *
 * This determines if we can use tabular format optimization.
 */
declare function isUniformObjectArray(data: unknown): data is TSONObject[];
/**
 * Split text by delimiter, respecting quoted strings and nested structures.
 *
 * This is more sophisticated than string.split() because it handles:
 * - Quoted strings (don't split on delimiters inside quotes)
 * - Nested braces/brackets/parentheses (don't split inside nested structures)
 * - Escaped characters
 */
declare function splitByDelimiter(text: string, delimiter: string): string[];
/**
 * Parse a key which may include nested schema notation.
 *
 * Examples:
 *   "name" -> { keyName: "name", schema: null }
 *   "address(@city,zip)" -> { keyName: "address", schema: ["city", "zip"] }
 *   "location(@coords(@lat,lng))" -> { keyName: "location", schema: ["coords(@lat,lng)"] }
 */
declare function parseKeySchema(keyString: string): KeySchema;
/**
 * Build a mapping of field names to their nested schemas.
 *
 * Example:
 *   ["id", "address(@city,zip)"]
 *   -> { id: null, address: ["city", "zip"] }
 */
declare function buildSchemaMap(keys: string[]): SchemaMap;
/**
 * Parse keys string and extract row count if present.
 *
 * Format: key1,key2,key3 or key1,key2,key3#N
 */
declare function parseKeys(keysStr: string): ParsedKeys;

export { type KeySchema, type ParsedKeys, type SchemaMap, type TSONArray, type TSONObject, type TSONPrimitive, type TSONValue, buildSchemaMap, dump, dumps, escapeString, formatPrimitive, isUniformObjectArray, load, loads, looksLikeNumber, needsQuoting, parseKeySchema, parseKeys, parsePrimitive, splitByDelimiter, unescapeString };