Document how to make use of & debug the example type checking?

[ships]

Do you want to request a feature or report a bug?

feature

What is the current behavior?

I have a library I am trying to document using docs-ts, because it is a library of io-ts codecs. I have written examples for each of the core codecs and suddenly encounter an issue where npx docs-ts fails like that:

TypeError [ERR_UNKNOWN_FILE_EXTENSION]: Unknown file extension ".ts" for /Users/eve/docmaps/packages/ts-sdk/docs/examples/index.ts
    at new NodeError (node:internal/errors:399:5)
    at Object.getFileProtocolModuleFormat [as file:] (node:internal/modules/esm/get_format:79:11)
    at defaultGetFormat (node:internal/modules/esm/get_format:121:38)
    [ ... omitted ... ]
  code: 'ERR_UNKNOWN_FILE_EXTENSION'
}

It seems like docs-ts is doing some awesome footwork to prove that my examples actually compile or type check anyway. However I haven't found docs or other issues that reference this behavior. Could we get an explainer on this, or info in the docs? I need to write examples, auto checking is optional feature for me so I would also be happy turning it off if there is need.

Thanks very much!

Which versions of docs-ts, and which browser and OS are affected by this issue? Did this work in previous versions of docs-ts?

NodeJS 18.14.0, macos 13.3, docs-ts 0.7.2

[gcanti]

docs/examples is a temporary folder used by docs-ts to run all the examples (which are supposed to be valid, including the necessary imports). If there are no errors, it will be deleted by docs-ts, and it is not supposed to be committed.

The error you're receiving is due to the fact that type: "module" is not supported.

As a workaround, you could add the following two files to the /docs folder:

package.json

{
  "name": "examples"
}

tsconfig.json

{
  "compilerOptions": {
    "module": "CommonJS"
    // your other options
  }
}

[samhh]

@gcanti That doesn't appear to work for me with ESM imports:

// https://www.typescriptlang.org/docs/handbook/esm-node.html
import x from './y.js'

// https://nodejs.org/api/packages.html#subpath-imports
import x from '#self/y'

TSError: ⨯ Unable to compile TypeScript:
docs/examples/src-Alternative.ts-function-pureIf-0.ts(2,24): error TS1479: The current file is a CommonJS module whose imports will produce 'require' calls; however, the referenced file is an ECMAScript module and cannot be imported with 'require'. Consider writing a dynamic 'import("../../src/Alternative")' call instead.
  To convert this file to an ECMAScript module, change its file extension to '.mts', or add the field `"type": "module"` to '/path/to/repo/docs/package.json'.

Repro (slightly different files in :/docs/ but easy to adjust): https://github.com/samhh/fp-ts-std/tree/esm (Edit: out of date, but the issue can be repro'd in the repo generally)

Edit: Built a workaround script: https://github.com/samhh/fp-ts-std/commit/4d679d684b88fdae040e6ca1c205d9d9dc35cccf#diff-11acf79cfa31caef7478b768e28dffb6d7272c308c98f666c529f68bc9685871