export interface StructuredOutputSpec<T = unknown> {
  name: string;
  description?: string;
  parse?: (value: unknown) => T;
}

export interface StructuredOutputResult<T = unknown> {
  spec: StructuredOutputSpec<T>;
  value: T;
}

export function defineStructuredOutput<T = unknown>(
  spec: StructuredOutputSpec<T>
): StructuredOutputSpec<T> {
  if (!spec.name.trim()) {
    throw new Error("Structured output specs require a name.");
  }
  return Object.freeze({ ...spec });
}

export function parseStructuredJson<T = unknown>(
  text: string,
  spec: StructuredOutputSpec<T> = { name: "json" }
): StructuredOutputResult<T> {
  const rawValue = JSON.parse(text) as unknown;
  const value = spec.parse ? spec.parse(rawValue) : (rawValue as T);
  return { spec, value };
}