toonfile 1.0.0

package/src/index.ts

@@ -0,0 +1,222 @@
+import * as fs from 'fs'
+import * as universalify from 'universalify'
+import { parse, stringify, stripBom } from './utils'
+import type { ReadOptions, WriteOptions, Callback } from './types'
+
+let _fs: typeof fs
+try {
+  _fs = require('graceful-fs') as typeof fs
+} catch (_) {
+  _fs = fs
+}
+
+// ============ READ FILE ============
+
+async function _readFile (file: string, options: ReadOptions | string = {}): Promise<any> {
+  if (typeof options === 'string') {
+    options = { encoding: options as BufferEncoding }
+  }
+
+  const fsModule = options.fs || _fs
+
+  const shouldThrow = 'throws' in options ? options.throws : true
+
+  let data: string
+  try {
+    const result = await new Promise<Buffer | string>((resolve, reject) => {
+      fsModule.readFile(file, options.encoding || 'utf8', (err: any, data: any) => {
+        if (err) reject(err)
+        else resolve(data)
+      })
+    })
+    data = typeof result === 'string' ? result : result.toString('utf8')
+  } catch (err) {
+    if (shouldThrow) {
+      const error = err as NodeJS.ErrnoException
+      error.message = `${file}: ${error.message}`
+      throw error
+    } else {
+      return null
+    }
+  }
+
+  data = stripBom(data)
+
+  let obj: any
+  try {
+    obj = parse(data, options)
+  } catch (err) {
+    if (shouldThrow) {
+      const error = err as Error
+      error.message = `${file}: ${error.message}`
+      throw error
+    } else {
+      return null
+    }
+  }
+
+  return obj
+}
+
+/**
+ * Read and parse a TOON file asynchronously
+ *
+ * @param file - Path to the TOON file
+ * @param options - Read options or encoding string
+ * @param callback - Optional callback function
+ * @returns Promise that resolves to parsed object (if no callback provided)
+ *
+ * @example
+ * // With promise
+ * const data = await readFile('config.toon')
+ *
+ * @example
+ * // With callback
+ * readFile('config.toon', (err, data) => {
+ *   if (err) console.error(err)
+ *   console.log(data)
+ * })
+ *
+ * @example
+ * // With options
+ * const data = await readFile('config.toon', { throws: false })
+ */
+export const readFile: {
+  (file: string, options?: ReadOptions | string): Promise<any>
+  (file: string, callback: Callback<any>): void
+  (file: string, options: ReadOptions | string, callback: Callback<any>): void
+} = universalify.fromPromise(_readFile) as any
+
+/**
+ * Read and parse a TOON file synchronously
+ *
+ * @param file - Path to the TOON file
+ * @param options - Read options or encoding string
+ * @returns Parsed object
+ *
+ * @example
+ * const data = readFileSync('config.toon')
+ *
+ * @example
+ * const data = readFileSync('config.toon', { throws: false })
+ */
+export function readFileSync (file: string, options: ReadOptions | string = {}): any {
+  if (typeof options === 'string') {
+    options = { encoding: options as BufferEncoding }
+  }
+
+  const fsModule = options.fs || _fs
+
+  const shouldThrow = 'throws' in options ? options.throws : true
+
+  try {
+    const buffer = fsModule.readFileSync(file, options as any)
+    let content = typeof buffer === 'string' ? buffer : buffer.toString('utf8')
+    content = stripBom(content)
+    return parse(content, options)
+  } catch (err) {
+    if (shouldThrow) {
+      const error = err as NodeJS.ErrnoException
+      error.message = `${file}: ${error.message}`
+      throw error
+    } else {
+      return null
+    }
+  }
+}
+
+// ============ WRITE FILE ============
+
+async function _writeFile (file: string, obj: any, options: WriteOptions = {}): Promise<void> {
+  const fsModule = options.fs || _fs
+
+  const str = stringify(obj, options)
+
+  const writeOptions: any = { encoding: options.encoding || 'utf8' }
+  if (options.mode) writeOptions.mode = options.mode
+  if (options.flag) writeOptions.flag = options.flag
+
+  await new Promise<void>((resolve, reject) => {
+    fsModule.writeFile(file, str, writeOptions, (err: any) => {
+      if (err) reject(err)
+      else resolve()
+    })
+  })
+}
+
+/**
+ * Stringify object and write to TOON file asynchronously
+ *
+ * @param file - Path to the TOON file
+ * @param obj - Object to stringify and write
+ * @param options - Write options
+ * @param callback - Optional callback function
+ * @returns Promise that resolves when file is written (if no callback provided)
+ *
+ * @example
+ * // With promise
+ * await writeFile('data.toon', { name: 'Alice', age: 30 })
+ *
+ * @example
+ * // With callback
+ * writeFile('data.toon', obj, (err) => {
+ *   if (err) console.error(err)
+ * })
+ *
+ * @example
+ * // With options
+ * await writeFile('data.toon', obj, { indentSize: 4, delimiter: '|' })
+ */
+export const writeFile: {
+  (file: string, obj: any, options?: WriteOptions): Promise<void>
+  (file: string, obj: any, callback: Callback<void>): void
+  (file: string, obj: any, options: WriteOptions, callback: Callback<void>): void
+} = universalify.fromPromise(_writeFile) as any
+
+/**
+ * Stringify object and write to TOON file synchronously
+ *
+ * @param file - Path to the TOON file
+ * @param obj - Object to stringify and write
+ * @param options - Write options
+ *
+ * @example
+ * writeFileSync('data.toon', { name: 'Bob', age: 25 })
+ *
+ * @example
+ * writeFileSync('data.toon', obj, { indentSize: 4 })
+ */
+export function writeFileSync (file: string, obj: any, options: WriteOptions = {}): void {
+  const fsModule = options.fs || _fs
+
+  const str = stringify(obj, options)
+  fsModule.writeFileSync(file, str, options as any)
+}
+
+// ============ EXPORTS ============
+
+// Re-export utility functions
+export { parse, stringify } from './utils'
+
+// Re-export types
+export type {
+  ReadOptions,
+  WriteOptions,
+  ParseOptions,
+  StringifyOptions,
+  Callback,
+  ToonValue,
+  ToonObject,
+  ToonArray
+} from './types'
+
+// NOTE: do not change this export format; required for ESM compat
+// Default export for CommonJS compatibility
+export default {
+  readFile,
+  readFileSync,
+  writeFile,
+  writeFileSync,
+  parse,
+  stringify
+}

package/src/types.ts

@@ -0,0 +1,198 @@
+/**
+ * TOON File Types and Interfaces
+ */
+
+import type * as fs from 'fs'
+
+/**
+ * Options for reading TOON files
+ */
+export interface ReadOptions {
+  /**
+   * File encoding (default: 'utf8')
+   */
+  encoding?: BufferEncoding
+
+  /**
+   * Throw error on parse failure. If false, returns null instead.
+   * @default true
+   */
+  throws?: boolean
+
+  /**
+   * Custom fs module for testing or alternative file systems
+   */
+  fs?: typeof fs
+
+  /**
+   * Transform function applied to parsed values (similar to JSON.parse reviver)
+   */
+  reviver?: (key: string, value: any) => any
+
+  /**
+   * Indent size for parsing (default: 2)
+   */
+  indentSize?: number
+
+  /**
+   * Strict mode for parsing
+   * @default true
+   */
+  strict?: boolean
+}
+
+/**
+ * Options for writing TOON files
+ */
+export interface WriteOptions {
+  /**
+   * File encoding (default: 'utf8')
+   */
+  encoding?: BufferEncoding
+
+  /**
+   * Custom fs module for testing or alternative file systems
+   */
+  fs?: typeof fs
+
+  /**
+   * Spaces per indent level
+   * @default 2
+   */
+  indentSize?: number
+
+  /**
+   * Delimiter for arrays: comma, tab, or pipe
+   * @default ','
+   */
+  delimiter?: ',' | '\t' | '|'
+
+  /**
+   * End-of-line character(s)
+   * @default '\n'
+   */
+  EOL?: '\n' | '\r\n' | string
+
+  /**
+   * Include EOL at end of file
+   * @default true
+   */
+  finalEOL?: boolean
+
+  /**
+   * Use tabular format for uniform arrays of objects
+   * @default true
+   */
+  tabularArrays?: boolean
+
+  /**
+   * Minimum array length to use tabular format
+   * @default 2
+   */
+  minArrayLengthForTabular?: number
+
+  /**
+   * Transform function applied before stringifying (similar to JSON.stringify replacer)
+   */
+  replacer?: (key: string, value: any) => any
+
+  /**
+   * File system flags (e.g., 'w', 'a')
+   * @default 'w'
+   */
+  flag?: string
+
+  /**
+   * File mode (permissions)
+   */
+  mode?: number
+}
+
+/**
+ * Options for parsing TOON strings
+ */
+export interface ParseOptions {
+  /**
+   * Transform function applied to parsed values
+   */
+  reviver?: (key: string, value: any) => any
+
+  /**
+   * Indent size (default: 2)
+   */
+  indentSize?: number
+
+  /**
+   * Strict mode
+   * @default true
+   */
+  strict?: boolean
+}
+
+/**
+ * Options for stringifying objects to TOON
+ */
+export interface StringifyOptions {
+  /**
+   * Spaces per indent level
+   * @default 2
+   */
+  indentSize?: number
+
+  /**
+   * Delimiter for arrays
+   * @default ','
+   */
+  delimiter?: ',' | '\t' | '|' | string
+
+  /**
+   * End-of-line character(s)
+   * @default '\n'
+   */
+  EOL?: '\n' | '\r\n' | string
+
+  /**
+   * Include EOL at end of file
+   * @default true
+   */
+  finalEOL?: boolean
+
+  /**
+   * Use tabular format for uniform arrays
+   * @default true
+   */
+  tabularArrays?: boolean
+
+  /**
+   * Minimum array length for tabular format
+   * @default 2
+   */
+  minArrayLengthForTabular?: number
+
+  /**
+   * Transform function applied before stringifying
+   */
+  replacer?: (key: string, value: any) => any
+}
+
+/**
+ * Callback function for async operations
+ */
+export type Callback<T> = (err: Error | null, data?: T) => void
+
+/**
+ * TOON value types
+ */
+export type ToonValue =
+  | string
+  | number
+  | boolean
+  | null
+  | ToonArray
+  | ToonObject
+
+export interface ToonObject {
+  [key: string]: ToonValue
+}
+
+export type ToonArray = ToonValue[]

package/src/universalify.d.ts

@@ -0,0 +1,6 @@
+declare module 'universalify' {
+  export function fromCallback<T extends (...args: any[]) => any>(fn: T): T
+  export function fromPromise<T extends (...args: any[]) => Promise<any>>(fn: T): T & {
+    (...args: [...Parameters<T>, (err: Error | null, result?: any) => void]): void
+  }
+}

package/src/utils.ts

@@ -0,0 +1,222 @@
+/**
+ * TOON Format Parser and Serializer
+ *
+ * Custom implementation supporting basic TOON features.
+ */
+
+import type {
+  ParseOptions,
+  StringifyOptions,
+  ToonValue
+} from './types'
+
+/**
+ * Parse TOON string to JavaScript object
+ */
+export function parse(content: string | Buffer, options: ParseOptions = {}): any {
+  if (Buffer.isBuffer(content)) {
+    content = content.toString('utf8')
+  }
+
+  content = stripBom(content)
+
+  const lines = content.split(/\r?\n/)
+  const indentSize = options.indentSize || 2
+
+  interface StackItem {
+    obj: any
+    indent: number
+  }
+
+  const stack: StackItem[] = [{ obj: {}, indent: -indentSize }]
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+
+    // Skip empty lines and comments
+    if (!line.trim() || line.trim().startsWith('#')) continue
+
+    const indent = getIndentLevel(line)
+    const trimmedLine = line.trim()
+
+    // Pop stack until we find the right parent
+    while (stack.length > 1 && indent <= stack[stack.length - 1].indent) {
+      stack.pop()
+    }
+
+    const parent = stack[stack.length - 1].obj
+
+    // Parse key-value
+    if (trimmedLine.includes(':')) {
+      const colonIndex = trimmedLine.indexOf(':')
+      const key = trimmedLine.substring(0, colonIndex).trim()
+      const valueStr = trimmedLine.substring(colonIndex + 1).trim()
+
+      // Check for array declaration: key[length]
+      const arrayMatch = key.match(/^(.+)\[(\d+)\]$/)
+
+      if (arrayMatch) {
+        // Inline array: scores[3]: 95,87,92
+        const arrayName = arrayMatch[1]
+        const arrayLength = parseInt(arrayMatch[2], 10)
+
+        if (valueStr) {
+          parent[arrayName] = parseInlineArray(valueStr, arrayLength)
+        } else {
+          parent[arrayName] = []
+        }
+      } else if (valueStr) {
+        // Simple key-value
+        parent[key] = parseValue(valueStr)
+      } else {
+        // Nested object
+        const newObj: any = {}
+        parent[key] = newObj
+        stack.push({ obj: newObj, indent })
+      }
+    }
+  }
+
+  const result = stack[0].obj
+
+  if (options.reviver) {
+    return applyReviver(result, options.reviver)
+  }
+
+  return result
+}
+
+/**
+ * Stringify JavaScript object to TOON format
+ */
+export function stringify(obj: any, options: StringifyOptions = {}): string {
+  const indentSize = options.indentSize || 2
+  const delimiter = options.delimiter || ','
+  const lines: string[] = []
+
+  function serializeObject(o: any, depth: number = 0): void {
+    const indent = ' '.repeat(depth * indentSize)
+
+    for (const [key, value] of Object.entries(o)) {
+      if (Array.isArray(value)) {
+        const arrayStr = value.map(v => serializeValue(v)).join(delimiter)
+        lines.push(`${indent}${key}[${value.length}]: ${arrayStr}`)
+      } else if (value !== null && typeof value === 'object') {
+        lines.push(`${indent}${key}:`)
+        serializeObject(value, depth + 1)
+      } else {
+        lines.push(`${indent}${key}: ${serializeValue(value)}`)
+      }
+    }
+  }
+
+  function serializeValue(value: any): string {
+    if (value === null) return 'null'
+    if (typeof value === 'boolean') return value.toString()
+    if (typeof value === 'number') return value.toString()
+    if (typeof value === 'string') {
+      if (needsQuotes(value, delimiter)) {
+        return `"${escapeString(value)}"`
+      }
+      return value
+    }
+    return String(value)
+  }
+
+  serializeObject(obj)
+
+  let result = lines.join('\n')
+
+  // Handle finalEOL (default: true)
+  const finalEOL = options.finalEOL !== undefined ? options.finalEOL : true
+  if (finalEOL && !result.endsWith('\n')) {
+    result += '\n'
+  } else if (!finalEOL && result.endsWith('\n')) {
+    result = result.slice(0, -1)
+  }
+
+  // Handle EOL customization
+  const EOL = options.EOL || '\n'
+  if (EOL !== '\n') {
+    result = result.replace(/\n/g, EOL)
+  }
+
+  return result
+}
+
+export function stripBom(content: string | Buffer): string {
+  if (Buffer.isBuffer(content)) content = content.toString('utf8')
+  return content.replace(/^\uFEFF/, '')
+}
+
+function applyReviver(obj: any, reviver: (key: string, value: any) => any): any {
+  return reviver('', obj)
+}
+
+function parseInlineArray(valueStr: string, expectedLength?: number): any[] {
+  const delimiter = detectDelimiter(valueStr)
+  const values = valueStr.split(delimiter).map(v => parseValue(v.trim()))
+
+  if (expectedLength !== undefined && values.length !== expectedLength) {
+    console.warn(`[toonfile] Array length mismatch: expected ${expectedLength}, got ${values.length}`)
+  }
+
+  return values
+}
+
+function detectDelimiter(str: string): string | RegExp {
+  if (str.includes('\t')) return '\t'
+  if (str.includes('|')) return '|'
+  return ','
+}
+
+function parseValue(str: string): ToonValue {
+  if (str === 'null') return null
+  if (str === 'true') return true
+  if (str === 'false') return false
+
+  if (/^-?\d+(\.\d+)?$/.test(str)) {
+    return parseFloat(str)
+  }
+
+  if ((str.startsWith('"') && str.endsWith('"')) ||
+      (str.startsWith("'") && str.endsWith("'"))) {
+    return unescapeString(str.slice(1, -1))
+  }
+
+  return str
+}
+
+function getIndentLevel(line: string): number {
+  const match = line.match(/^( *)/)
+  return match ? match[1].length : 0
+}
+
+function needsQuotes(str: string, delimiter: string): boolean {
+  const reservedWords = ['true', 'false', 'null']
+  if (reservedWords.includes(str)) return true
+  if (str.includes(delimiter)) return true
+  if (str.includes(':')) return true
+  if (str.includes('\n') || str.includes('\r') || str.includes('\t')) return true
+  if (/^-?\d+(\.\d+)?$/.test(str)) return true
+  return false
+}
+
+function escapeString(str: string): string {
+  return str
+    .replace(/\\/g, '\\\\')
+    .replace(/"/g, '\\"')
+    .replace(/\n/g, '\\n')
+    .replace(/\r/g, '\\r')
+    .replace(/\t/g, '\\t')
+}
+
+function unescapeString(str: string): string {
+  return str
+    .replace(/\\n/g, '\n')
+    .replace(/\\r/g, '\r')
+    .replace(/\\t/g, '\t')
+    .replace(/\\"/g, '"')
+    .replace(/\\'/g, "'")
+    .replace(/\\\\/g, '\\')
+}