types.ts

/**
 * @fileoverview JSON type definitions and interfaces.
 */

/**
 * JSON primitive types: `null`, `boolean`, `number`, or `string`.
 *
 * @example
 * ```ts
 * const primitives: JsonPrimitive[] = [null, true, 42, 'hello']
 * ```
 */
export type JsonPrimitive = null | boolean | number | string

/**
 * A JSON array containing JSON values.
 *
 * @example
 * ```ts
 * const arr: JsonArray = [1, 'two', { three: 3 }, [4, 5]]
 * ```
 */
export interface JsonArray extends Array<JsonValue> {}

/**
 * A JSON object with string keys and JSON values.
 *
 * @example
 * ```ts
 * const obj: JsonObject = {
 *   name: 'example',
 *   count: 42,
 *   active: true,
 *   nested: { key: 'value' }
 * }
 * ```
 */
export interface JsonObject {
  [key: string]: JsonValue
}

/**
 * Any valid JSON value: primitive, object, or array.
 *
 * @example
 * ```ts
 * const values: JsonValue[] = [
 *   null,
 *   true,
 *   42,
 *   'hello',
 *   { key: 'value' },
 *   [1, 2, 3]
 * ]
 * ```
 */
export type JsonValue = JsonPrimitive | JsonObject | JsonArray

/**
 * Reviver function for transforming parsed JSON values.
 * Called for each key-value pair during parsing.
 *
 * @param key - The object key or array index being parsed
 * @param value - The parsed value
 * @returns The transformed value (or original if no transform needed)
 *
 * @example
 * ```ts
 * // Convert date strings to Date objects
 * const reviver: JsonReviver = (key, value) => {
 *   if (typeof value === 'string' && /^\d{4}-\d{2}-\d{2}/.test(value)) {
 *     return new Date(value)
 *   }
 *   return value
 * }
 * ```
 */
export type JsonReviver = (key: string, value: unknown) => unknown

/**
 * Options for JSON parsing operations.
 */
export interface JsonParseOptions {
  /**
   * Optional filepath for improved error messages.
   * When provided, errors will be prefixed with the filepath.
   *
   * @example
   * ```ts
   * // Error message will be: "config.json: Unexpected token } in JSON"
   * jsonParse('invalid', { filepath: 'config.json' })
   * ```
   */
  filepath?: string | undefined
  /**
   * Optional reviver function to transform parsed values.
   * Called for each key-value pair during parsing.
   *
   * @example
   * ```ts
   * // Convert ISO date strings to Date objects
   * const options = {
   *   reviver: (key, value) => {
   *     if (typeof value === 'string' && /^\d{4}-\d{2}-\d{2}/.test(value)) {
   *       return new Date(value)
   *     }
   *     return value
   *   }
   * }
   * ```
   */
  reviver?: JsonReviver | undefined
  /**
   * Whether to throw on parse errors.
   * When `false`, returns `undefined` instead of throwing.
   *
   * @default true
   *
   * @example
   * ```ts
   * // Throws error
   * jsonParse('invalid', { throws: true })
   *
   * // Returns undefined
   * const result = jsonParse('invalid', { throws: false })
   * ```
   */
  throws?: boolean | undefined
}

/**
 * Options for saving editable JSON files.
 */
export interface EditableJsonSaveOptions {
  /**
   * Whether to ignore whitespace-only changes when determining if save is needed.
   * @default false
   */
  ignoreWhitespace?: boolean | undefined
  /**
   * Whether to sort object keys alphabetically before saving.
   * @default false
   */
  sort?: boolean | undefined
}

/**
 * Options for creating or loading editable JSON instances.
 */
export interface EditableJsonOptions<T = Record<string, unknown>> {
  /**
   * File path for the JSON file (optional for in-memory instances).
   */
  path?: string | undefined
  /**
   * Whether to create the file if it doesn't exist during load.
   * @default false
   */
  create?: boolean | undefined
  /**
   * Initial data to populate the instance with.
   */
  data?: T | undefined
}

/**
 * EditableJson instance interface for JSON file manipulation.
 * Provides core functionality for loading, editing, and saving JSON files
 * while preserving formatting (indentation and line endings).
 */
export interface EditableJsonInstance<T = Record<string, unknown>> {
  /**
   * The parsed JSON content as a readonly object.
   * @readonly
   */
  content: Readonly<T>

  /**
   * Create a new JSON file at the specified path.
   * @param path - The file path where JSON will be created
   */
  create(path: string): this

  /**
   * Initialize the instance from a content object.
   * Note: Disables saving when used (no file path associated).
   * @param content - The JSON content object
   */
  fromContent(content: unknown): this

  /**
   * Initialize the instance from a JSON string.
   * @param json - The JSON content as a string
   */
  fromJSON(json: string): this

  /**
   * Load a JSON file from the specified path.
   * @param path - The file path to load
   * @param create - Whether to create the file if it doesn't exist
   */
  load(path: string, create?: boolean): Promise<this>

  /**
   * Update the JSON content with new values.
   * @param content - Partial object with fields to update
   */
  update(content: Partial<T>): this

  /**
   * Save the JSON file to disk.
   * @param options - Save options for formatting and sorting
   */
  save(options?: EditableJsonSaveOptions): Promise<boolean>

  /**
   * Synchronously save the JSON file to disk.
   * @param options - Save options for formatting and sorting
   */
  saveSync(options?: EditableJsonSaveOptions): boolean

  /**
   * Check if the JSON will be saved based on current changes.
   * @param options - Save options to evaluate
   */
  willSave(options?: EditableJsonSaveOptions): boolean

  /**
   * The full path to the JSON file.
   * @readonly
   */
  readonly filename: string

  /**
   * The directory path containing the JSON file.
   * @readonly
   */
  readonly path: string | undefined
}

/**
 * EditableJson constructor interface.
 */
export interface EditableJsonConstructor<T = Record<string, unknown>> {
  new (): EditableJsonInstance<T>
  create(
    path: string,
    opts?: EditableJsonOptions<T>,
  ): Promise<EditableJsonInstance<T>>
  load(
    path: string,
    opts?: EditableJsonOptions<T>,
  ): Promise<EditableJsonInstance<T>>
}