@zenoaihq/tson 1.0.1 → 1.1.0

package/dist/index.d.ts

@@ -21,17 +21,27 @@ type TSONObject = {
  * Any valid TSON value
  */
 type TSONValue = TSONPrimitive | TSONArray | TSONObject;
+/**
+ * Schema info for nested object/array structures
+ * - schema: nested schema keys (or null if no schema)
+ * - count: array count (or null if single object)
+ */
+interface SchemaInfo {
+    schema: string[] | null;
+    count: number | null;
+}
 /**
  * Schema map for nested object structures
- * Maps field names to their nested schemas (or null if no schema)
+ * Maps field names to their schema info
  */
-type SchemaMap = Record<string, string[] | null>;
+type SchemaMap = Record<string, SchemaInfo>;
 /**
  * Result of parsing a key with optional schema notation
  */
 interface KeySchema {
     keyName: string;
     schema: string[] | null;
+    count: number | null;
 }
 /**
  * Result of parsing keys with optional row count
@@ -93,6 +103,154 @@ declare function loads(s: string): TSONValue;
  */
 declare function load(filePath: string): Promise<TSONValue>;
 
+/**
+ * TSON Prettify
+ *
+ * Format TSON strings for human readability.
+ * CSV-like format: schema on top, one row/value per line.
+ */
+/**
+ * Format a compact TSON string for human readability.
+ *
+ * Uses CSV-like formatting:
+ * - Schema declaration on first line
+ * - Each row/value on its own line with leading delimiter
+ *
+ * @example
+ * prettify('{@id,name#2|1,Alice|2,Bob}')
+ * // Returns: '{@id,name#2\n|1,Alice\n|2,Bob}'
+ *
+ * @param tsonStr - Compact TSON string
+ * @param indent - Indentation string (default: 2 spaces)
+ * @returns Pretty-formatted TSON string
+ */
+declare function prettify(tsonStr: string, indent?: string): string;
+/**
+ * Remove all formatting from a TSON string.
+ *
+ * @param tsonStr - Pretty-formatted TSON string
+ * @returns Compact single-line TSON string
+ */
+declare function minify(tsonStr: string): string;
+
+/**
+ * TSON File Utilities
+ *
+ * Convenience functions for working with TSON and JSON files.
+ * Includes support for:
+ * - Loading JSON/TSON files
+ * - Saving to TSON with formatting options
+ *
+ * Note: These functions are Node.js only (use dynamic imports for fs).
+ */
+type FormatOption = 'compact' | 'pretty';
+/**
+ * Load a JSON file and return JavaScript data structure.
+ *
+ * @example
+ * const data = await loadJson('data.json');
+ *
+ * @param filepath - Path to JSON file
+ * @returns Parsed JavaScript object
+ */
+declare function loadJson(filepath: string): Promise<unknown>;
+/**
+ * Load a TSON file and return JavaScript data structure.
+ *
+ * @example
+ * const data = await loadTson('data.tson');
+ *
+ * @param filepath - Path to TSON file
+ * @returns Parsed JavaScript object
+ */
+declare function loadTson(filepath: string): Promise<unknown>;
+/**
+ * Save JavaScript data to a TSON file.
+ *
+ * @example
+ * await saveTson(data, 'output.tson');
+ * await saveTson(data, 'output.tson', { format: 'pretty' });
+ *
+ * @param data - JavaScript object to serialize
+ * @param filepath - Output file path
+ * @param options - Formatting options
+ */
+declare function saveTson(data: unknown, filepath: string, options?: {
+    format?: FormatOption;
+    indent?: string;
+}): Promise<void>;
+/**
+ * Save a TSON string directly to file.
+ *
+ * @example
+ * await saveTsonString(tsonData, 'output.tson');
+ * await saveTsonString(tsonData, 'output.tson', { format: 'pretty' });
+ *
+ * @param tsonStr - TSON formatted string
+ * @param filepath - Output file path
+ * @param options - Formatting options
+ */
+declare function saveTsonString(tsonStr: string, filepath: string, options?: {
+    format?: FormatOption | null;
+    indent?: string;
+}): Promise<void>;
+/**
+ * Convert a JSON file to TSON format.
+ *
+ * @example
+ * const tsonStr = await jsonToTson('data.json');
+ * await jsonToTson('data.json', 'data.tson');
+ *
+ * @param inputPath - Path to input JSON file
+ * @param outputPath - Path to output TSON file (optional)
+ * @param options - Formatting options
+ * @returns TSON string representation
+ */
+declare function jsonToTson(inputPath: string, outputPath?: string, options?: {
+    format?: FormatOption;
+}): Promise<string>;
+/**
+ * Convert a TSON file to JSON format.
+ *
+ * @example
+ * const jsonStr = await tsonToJson('data.tson');
+ * await tsonToJson('data.tson', 'data.json');
+ *
+ * @param inputPath - Path to input TSON file
+ * @param outputPath - Path to output JSON file (optional)
+ * @param options - Formatting options
+ * @returns JSON string representation
+ */
+declare function tsonToJson(inputPath: string, outputPath?: string, options?: {
+    indent?: number;
+}): Promise<string>;
+/**
+ * Read a TSON file as raw string (without parsing).
+ *
+ * Useful when you want to prettify/minify without deserializing.
+ *
+ * @param filepath - Path to TSON file
+ * @returns Raw TSON string
+ */
+declare function readTsonString(filepath: string): Promise<string>;
+/**
+ * Prettify a TSON file in place or to a new file.
+ *
+ * @param inputPath - Path to input TSON file
+ * @param outputPath - Path to output file (default: overwrite input)
+ * @param indent - Indentation string (default: 2 spaces)
+ * @returns Prettified TSON string
+ */
+declare function prettifyFile(inputPath: string, outputPath?: string, indent?: string): Promise<string>;
+/**
+ * Minify a TSON file in place or to a new file.
+ *
+ * @param inputPath - Path to input TSON file
+ * @param outputPath - Path to output file (default: overwrite input)
+ * @returns Minified TSON string
+ */
+declare function minifyFile(inputPath: string, outputPath?: string): Promise<string>;
+
 /**
  * TSON Utility Functions
  *
@@ -127,6 +285,7 @@ declare function escapeString(value: string): string;
  * Unescape a quoted string back to its original form.
  *
  * Reverses the escaping done by escapeString().
+ * Must process character by character to handle sequences like \\n correctly.
  */
 declare function unescapeString(value: string): string;
 /**
@@ -153,20 +312,28 @@ declare function isUniformObjectArray(data: unknown): data is TSONObject[];
  */
 declare function splitByDelimiter(text: string, delimiter: string): string[];
 /**
- * Parse a key which may include nested schema notation.
+ * Parse a key which may include nested schema notation and optional array count.
+ *
+ * The array count can be specified INSIDE the parentheses to avoid ambiguity:
+ * - `key(@schema#N)` means key is an array of N objects with the given schema
+ * - `key(@schema)` means key is a single object with the given schema
  *
  * Examples:
- *   "name" -> { keyName: "name", schema: null }
- *   "address(@city,zip)" -> { keyName: "address", schema: ["city", "zip"] }
- *   "location(@coords(@lat,lng))" -> { keyName: "location", schema: ["coords(@lat,lng)"] }
+ *   "name" -> { keyName: "name", schema: null, count: null }
+ *   "address(@city,zip)" -> { keyName: "address", schema: ["city", "zip"], count: null }
+ *   "characters(@name,role#2)" -> { keyName: "characters", schema: ["name", "role"], count: 2 }
  */
 declare function parseKeySchema(keyString: string): KeySchema;
 /**
- * Build a mapping of field names to their nested schemas.
+ * Build a mapping of field names to their nested schemas and array counts.
  *
  * Example:
- *   ["id", "address(@city,zip)"]
- *   -> { id: null, address: ["city", "zip"] }
+ *   ["id", "address(@city,zip)", "items(@x,y#2)"]
+ *   -> {
+ *     id: { schema: null, count: null },
+ *     address: { schema: ["city", "zip"], count: null },
+ *     items: { schema: ["x", "y"], count: 2 }
+ *   }
  */
 declare function buildSchemaMap(keys: string[]): SchemaMap;
 /**
@@ -176,4 +343,4 @@ declare function buildSchemaMap(keys: string[]): SchemaMap;
  */
 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 };
+export { type KeySchema, type ParsedKeys, type SchemaInfo, type SchemaMap, type TSONArray, type TSONObject, type TSONPrimitive, type TSONValue, buildSchemaMap, dump, dumps, escapeString, formatPrimitive, isUniformObjectArray, jsonToTson, load, loadJson, loadTson, loads, looksLikeNumber, minify, minifyFile, needsQuoting, parseKeySchema, parseKeys, parsePrimitive, prettify, prettifyFile, readTsonString, saveTson, saveTsonString, splitByDelimiter, tsonToJson, unescapeString };