@mdxui/terminal 2.0.0

package/src/core/parser.ts

@@ -0,0 +1,127 @@
+/**
+ * @mdxui/terminal JSON Parser
+ *
+ * Converts JSON strings and objects into validated UINode structures.
+ * Supports both JSON string parsing and pre-parsed object validation.
+ */
+import { UINodeSchema, type UINode } from './types'
+
+/**
+ * Custom error class for parsing errors.
+ * Provides helpful error messages for JSON parsing and UINode validation failures.
+ */
+export class ParseError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'ParseError'
+    // Maintain proper prototype chain for instanceof checks
+    Object.setPrototypeOf(this, ParseError.prototype)
+  }
+}
+
+/**
+ * Parse a JSON string or JavaScript object into a validated UINode.
+ *
+ * @param input - JSON string or pre-parsed JavaScript object
+ * @returns Validated UINode
+ * @throws ParseError if the input is invalid JSON or doesn't match UINode structure
+ *
+ * @example
+ * ```tsx
+ * // Parse JSON string
+ * const node = parseUINode('{"type":"text","props":{"content":"Hello"}}')
+ *
+ * // Parse pre-parsed object
+ * const node = parseUINode({ type: 'text', props: { content: 'Hello' } })
+ * ```
+ */
+export function parseUINode(input: string | unknown): UINode {
+  let parsed: unknown
+
+  // Handle string input - parse as JSON
+  if (typeof input === 'string') {
+    // Empty string check
+    if (input.trim() === '') {
+      throw new ParseError('Invalid JSON: empty string')
+    }
+
+    try {
+      parsed = JSON.parse(input)
+    } catch (error) {
+      throw new ParseError(
+        `Invalid JSON: ${error instanceof Error ? error.message : 'parse error'}`
+      )
+    }
+  } else {
+    // Use the input directly if it's not a string
+    parsed = input
+  }
+
+  // Validate that we have an object (not null, not array, not primitive)
+  if (parsed === null) {
+    throw new ParseError('Invalid UINode: expected object, got null')
+  }
+
+  if (Array.isArray(parsed)) {
+    throw new ParseError('Invalid UINode: expected object, got array')
+  }
+
+  if (typeof parsed !== 'object') {
+    throw new ParseError(`Invalid UINode: expected object, got ${typeof parsed}`)
+  }
+
+  // Validate against UINodeSchema
+  const result = UINodeSchema.safeParse(parsed)
+
+  if (!result.success) {
+    // Extract meaningful error message from Zod error
+    const issues = result.error.issues
+    const errorMessages = issues.map((issue) => {
+      const path = issue.path.length > 0 ? ` at path "${issue.path.join('.')}"` : ''
+      return `${issue.message}${path}`
+    })
+
+    // Check for specific field errors to provide better messages
+    const hasTypeError = issues.some(
+      (issue) =>
+        issue.path.includes('type') ||
+        (issue.path.length === 0 && issue.code === 'invalid_type')
+    )
+    const hasMissingType = issues.some(
+      (issue) =>
+        issue.code === 'invalid_type' &&
+        issue.path.length === 1 &&
+        issue.path[0] === 'type'
+    )
+
+    if (hasMissingType || (!('type' in (parsed as object)))) {
+      // Check if type field is missing
+      if (!('type' in (parsed as object))) {
+        throw new ParseError('Invalid UINode: missing required field "type"')
+      }
+    }
+
+    throw new ParseError(`Invalid UINode: ${errorMessages.join('; ')}`)
+  }
+
+  return result.data
+}
+
+/**
+ * Parse a JSON string into a validated UINode.
+ *
+ * This is a convenience function that only accepts JSON strings.
+ * For parsing pre-parsed objects, use parseUINode directly.
+ *
+ * @param json - JSON string representation of a UINode
+ * @returns Validated UINode
+ * @throws ParseError if the JSON is invalid or doesn't match UINode structure
+ *
+ * @example
+ * ```tsx
+ * const node = parseUINodeFromJSON('{"type":"text","props":{"content":"Hello"}}')
+ * ```
+ */
+export function parseUINodeFromJSON(json: string): UINode {
+  return parseUINode(json)
+}