users get unfixable (and inaccurate) type errors when using go-to-source for openai library code

[aroman]

Confirm this is a library issue and not an underlying OpenAI API issue

• This is an issue with the library

Describe the bug

simply adding the new openai package to my project causes all sorts of type errors when I cmd+click on into the OpenAI source code from my project

To Reproduce

See above.

OS

macOS

Node version

n/a

Library version

4.2.0

[RobertCraigie]

Can you share your tsconfig?

Here's the tsconfig we use for testing cloudflare workers, which extends this one.

[aroman]

@RobertCraigie sure:

tsconfig.server.ts

{
  "extends": "../tsconfig.base.json",
  "compilerOptions": {
    "target": "es2022",
    "lib": ["es2022"],
    "types": ["@cloudflare/workers-types"],
    "noUncheckedIndexedAccess": true
  },
  "include": ["src", "../common"]
}

tsconfig.base.json

{
  "compilerOptions": {
    "target": "es2022",
    "module": "ESNext",
    "moduleResolution": "Node",
    "strict": true,
    "allowSyntheticDefaultImports": true,
    "noEmit": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "sourceMap": true,
    "baseUrl": ".",
    "paths": {
      "@common/*": ["./common/*"]
    }
  }
}

[aroman]

odd... although VSCode complains about these type errors, when i actually run tsc it seems like they just... don't really exist?

very strange behavior. i'm using the latest version of VSCode and typescript 5.1. i should also mention that we do use other npm packages that use fetch in our server without issue.

i wonder what is going on here... i've restarted VSCode a dozen times but keep getting the errors. if i remove the openai package, though, poof - no more type errors.

[rattrayalex]

Does it help to add "skipLibCheck": true to your tsconfig?

[rattrayalex]

Is there a relevant issue in VS Code for this? if not, perhaps worth opening one?

[aroman]

Does it help to add "skipLibCheck": true to your tsconfig?

Unfortunately not.

Taking a step back... I can reproduce this issue in a blank project using version 4.3.0 of this library.

Here's what I did:

1. mkdir -p test-openai/src
2. cd test-openai
3. npm i openai
4. echo "import openai from 'openai'" > src/test.ts
5. use this tsconfig:

{
  "compilerOptions": {
    "noEmit": true,
    "target": "es2022",
    "strict": true,
    "moduleResolution": "Bundler"
  },
  "include": ["src"]
}

EDIT: this is a red herring; see my comment below

Observe:

tsc src/test.ts

node_modules/openai/core.d.ts:179:3 - error TS18028: Private identifiers are only available when targeting ECMAScript 2015 and higher.

179 #private;

Found 1 error in node_modules/openai/core.d.ts:179

Also observe:

tsc --skipLibCheck src/test.ts

<no output, since no errors>

what am I missing here...?

[aroman]

ohhhh, i think the issue is that you're including the actual source .ts files in your npm package. I'm pretty sure you're not supposed to do that, since they're distributed without a tsconfig.json, and how would typescript know how to compile them...? @rattrayalex

[rattrayalex]

Thanks @aroman , this is very helpful!

I don't think the src folder is the problem, because the error you're getting is in a .d.ts file outside of the directory. (The src folder is there for a better sourcemap experience).

The tldr is that you need "skipLibCheck": true with this library, as with many others (which is why it's on by default).

Is there a reason you want it off?

[aroman]

Thanks @rattrayalex for the quick reply! I've done some more digging, and summarized my learnings below. Would love your thoughts when you get a chance!

tl;dr

• the root issue here is this library's inclusion of .ts files in the npm package and is unrelated to Cloudflare Workers types
• skipLibCheck will not help here, and is not recommended because it disables typechecking in end-user .d.ts files; it's meant as a performance optimization.
• Going forward, I would suggest not shipping .ts files in the openai npm package, which is consistent with the behavior of the most popular typescript-native projects, such as stripe, twilio, aws-sdk, axios, etc.

More detailed thoughts below to elaborate on the above. I've also re-titled the bug thread to better reflect what's going on here.

Thanks @aroman , this is very helpful!

I don't think the src folder is the problem, because the error you're getting is in a .d.ts file outside of the directory. (The src folder is there for a better sourcemap experience).

Ah, actually, that's my mistake — my tsc invocation wasn't using the tsconfig.json (I should have used --project). (What I get for looking at code too close to dinner 😅) In fact, the errors are coming from the .ts files in the openai package. --skipLibCheck is not actually relevant here (and its usage is problematic, as I'll explain below)

To clarify what's actually happening here:

1. All that's needed for a project to use openai is to specify a target of >es2015 in its tsconfig.json, so the #private syntax in its .d.ts file works. You could instead use --skipLibCheck, but this is generally a really bad idea™ for reasons explained below.

2. The reason the library is not typechecking when I cmd+click to open its source is simply because VSCode (understandably) has no idea how to interpret openai's src .ts files without an accompanying tsconfig.json. This is probably why most packages don't include .ts source files, besides saving space. What VSCode is doing here is expected behavior — if you click the little typescript icon in the status bar, it makes it clear what's going on — it is essentially compiling those .ts files as if there were no tsconfig.json (since there isn't one!)

The tldr is that you need "skipLibCheck": true with this library, as with many others (which is why it's on by default).

Is there a reason you want it off?

Fortunately, skipLibCheck isn't actually needed to use the library, but in general, I'd strongly recommend against advising users of the library to add skipLibCheck to their projects, for three reasons:

1. It isn't necessary as long as users target es2015+
2. It will not fix the errors I surfaced in my original report, which are not in fact related to an incompatibility with cloudflare workers types, but actually due to this library's inclusion of its source .ts files without an accompanying tsconfig.json.
3. Despite its name, skipLibCheck will actually disable typechecking for ALL .d.ts files — even the ones defined internally in end-user, non-package code. Have a look at this blogpost for some more context on why turning off skipLibCheck is generally not recommended. As best I can tell, it's intended as a performance optimization, or as a quick hack for working around broken libraries. So, definitely not worth losing typesafety over!

[rattrayalex]

Ah, terrific, thanks @aroman !

We'll look into whether there's a way to remove these errors - perhaps including a stub tsconfig could help.

We'd like to keep the .ts files if possible because I believe it provides a much better go-to-definition experience, thanks to the declarationMap flag (which I wasn't aware of when I shipped the Stripe library's TypeScript support - I think it may not have been documented at the time).

[aroman]

Ah, terrific, thanks @aroman !

We'll look into whether there's a way to remove these errors - perhaps including a stub tsconfig could help.

We'd like to keep the .ts files if possible because I believe it provides a much better go-to-definition experience, thanks to the declarationMap flag (which I wasn't aware of when I shipped the Stripe library's TypeScript support - I think it may not have been documented at the time).

@rattrayalex yes, the go-to-definition is great! That's how I stumbled upon this in the first place 😄

And indeed, looks like a stub tsconfig does seem to do the trick. Dropping the below minimal tsconfig into node_modules/openai does seem to fix all the issues I was seeing (though I didn't think too hard about the config specifics, e.g. what version to actually target). Tbh, I haven't really seen other libraries do this (not to say it's a bad idea per se, just unfamiliar to me), but intuitively it makes sense to me that something like this would be needed if you're shipping typescript source files.

{
  "compilerOptions": {
    "noEmit": true,
    "target": "es2021",
    "strict": true,
    "moduleResolution": "Bundler"
  },
  "include": [ "src" ],
  "exclude": [ "src/_shims" ]
}

[aroman]

oh, also, just noticed that stub tsconfig seems to have fixed auto-import suggestions (see screenshot) -- those weren't working for me with this library before, though I wasn't sure why