Transform Function and Type Clarity

[philbegg]

Description

_I'm encountering an issue when I try to use the transform function as mentioned in the V6 Docs I'm unsure if there is a problem with the type definition for the "schema" variable or the way I am using it.

When use my openAPI schema as a JSON string it does not complete successfully, I can convert to a JSON object and it completes successfully.

Is it that maybe the docs should be updated to be more clear?

Usage Docs show:

import fs from "node:fs";
import openapiTS from "openapi-typescript";

// example 1: load [object] as schema (JSON only)
const schema = await fs.promises.readFile("spec.json", "utf8"); // must be OpenAPI JSON
const output = await openapiTS(JSON.parse(schema));

Transform Docs show:

const types = openapiTS(mySchema, {
  transform(schemaObject, metadata): string {
    if ("format" in schemaObject && schemaObject.format === "date-time") {
      return schemaObject.nullable ? "Date | null" : "Date";
    }
  },
});

For clarity it would be good to show a full example of how to use the transform function - specifying how to import the schema variable. It might be just me but I got stuck on this for a while as there was no error reported in the terminal.

Name	Version
openapi-typescript	6.7.5
Node.js	20.11.0
OS + version	Windows 10

Reproduction

import fs from "node:fs";
import openapiTS from "openapi-typescript";

// example 1: load [object] as schema (JSON only)
const schema = await fs.promises.readFile("spec.json", "utf8")

const types = openapiTS(schema , {
  transform(schemaObject, metadata): string {
    if ("format" in schemaObject && schemaObject.format === "date-time") {
      return schemaObject.nullable ? "Date | null" : "Date";
    }
  },
});

should actually be

import fs from "node:fs";
import openapiTS from "openapi-typescript";

// example 1: load [object] as schema (JSON only)
const schema = JSON.parse(await fs.promises.readFile("spec.json", "utf8"))

const types = openapiTS(schema , {
  transform(schemaObject, metadata): string {
    if ("format" in schemaObject && schemaObject.format === "date-time") {
      return schemaObject.nullable ? "Date | null" : "Date";
    }
  },
});

[drwpow]

Yes I’d be fine with this docs change if you wanted to submit a PR! If it was tripping you up, it’s probably tripping up others.

A little extra context on why a clear error isn’t thrown: in 6.x, between the CLI and Node API it allows URLs/filepaths as strings, and YAML as strings, but it doesn’t throw an error on an invalid schema so it may just interpret it as an empty schema. In 7.x it does validate it. And the errors are all clear if you’re holding it wrong in the Node API. Fixing that involved rewriting the library. That confused a lot of people. And improving docs is the best solution for 6.x I think.