Check type declarations with JSDoc comments

[colinrotherham]

Great work on Prettier v3 🙌

Hope this PR is welcome, but I've added JSDoc + tsconfig.json to export type declarations

I followed the link in the Prettier 3.0: Hello, ECMAScript Modules! blog post after realising that the Prettier sync APIs would still be needed to avoid Nunjucks template changes for asynchronous rendering 😣

If you still need sync APIs, you can try @prettier/sync

I'd be happy to make any tweaks, and wasn't sure if committing the types would be preferred

Closes: #8

[fisker]

Thanks for working on this. Can it be done by adding a .d.ts file?

[colinrotherham]

Thanks for working on this. Can it be done by adding a .d.ts file?

Yeah course, I've pushed up a new .gitignore to show them:

1. Added index.d.cts type declarations for .cjs extension files
2. Added index.d.cts.map type declaration map to link back to source

Declaration Map
Generates a source map for .d.ts files which map back to the original .ts source file. This will allow editors such as VS Code to go to the original .ts file when using features like Go to Definition.

I've used import('prettier') in the JSDoc to make sure the existing type declarations are reused when built

[fisker]

I'm not familiar with types, but why are these needed?

[colinrotherham]

They're not publicly exported, but I've added /** @type {const} */ to these two:

PRETTIER_ASYNC_FUNCTIONS
PRETTIER_STATIC_PROPERTIES

When a function is called or property is accessed that doesn't exist (or renamed) it'll validate against:

FunctionName in typeof PRETTIER_ASYNC_FUNCTIONS[number]
PropertyName in typeof PRETTIER_STATIC_PROPERTIES[number]

Otherwise we'd have to duplicate them in quite a few places:

FunctionName extends "formatWithCursor" | "format" | "check" | "resolveConfig" | "resolveConfigFile" | "clearConfigCache" | "getFileInfo" | "getSupportInfo"
Property extends "version" | "util" | "doc"

These consts are used to populate the functions/properties available in editors:

[colinrotherham]

Appreciate they're not needed externally so tried adding @internal

But when setting tsconfig.json "stripInternal": true it didn't work due to:

• Support stripInternal for types in JSDoc microsoft/TypeScript#46407
• stripInternal should work on single-line comments microsoft/TypeScript#46515

One of the downsides to using the compiler with JSDoc 😔

[fisker]

Is it possible to do something like

import type Prettier from "prettier";

?

[colinrotherham]

Let me look into it

It's the tsc compiler automatically exporting @typedef by default

[fisker]

How about hand-writing code like this

import type {
  version,
  util,
  doc,
  formatWithCursor,
  format,
  check,
  resolveConfig,
  resolveConfigFile,
  getFileInfo,
  getSupportInfo,
} from "prettier";

type SynchronizedPrettier = {
  // Prettier static properties
  version: typeof version;
  util: typeof util;
  doc: typeof doc;

  // Prettier functions
  formatWithCursor: Awaited<ReturnType<typeof formatWithCursor>>;
  format: Awaited<ReturnType<typeof format>>;
  check: Awaited<ReturnType<typeof check>>;
  resolveConfig: Awaited<ReturnType<typeof resolveConfig>>;
  resolveConfigFile: Awaited<ReturnType<typeof resolveConfigFile>>;
  getFileInfo: Awaited<ReturnType<typeof getFileInfo>>;
  getSupportInfo: Awaited<ReturnType<typeof getSupportInfo>>;
};

[colinrotherham]

Entirely up to you 😊

With JSDoc and checkJs enabled (without switching to TypeScript) you'll be able to use code completion, see documentation in tooltips, and spot and errors and warnings as-you-type—in this repo too

Plus it lets the compiler validate that type declarations are correct when prettier "./src/index.d.ts" types change without having to keep types synchronised between repos by hand

tsconfig.json

{
  "compilerOptions": {
    "allowJs": true,
    "checkJs": true
  }
}

I'd be more than happy if you used this PR for guidance to add them manually 👍

Let me know if you'd like anything splitting out

Update: Split out manually in 7d922c2

[fisker]

I have no experience with type declarations.

@SimenB Can you help review?

[colinrotherham]

@fisker I've removed all the unnecessary autogenerated lines from index.d.cts

We're left with the good stuff like Awaited<ReturnType<Prettier[FunctionName]>>

But I've kept the tsconfig.json and JSDoc comments so you get type checking locally too

[fisker]

Thank you @colinrotherham

Released https://github.com/prettier/prettier-synchronized/releases/tag/v0.3.0

[colinrotherham]

Brilliant, thanks @fisker

Just a reminder that manually adding the types without a type declaration map means editor and IDE "Go to definition" will jump to the types rather than the original Prettier source code, should you want that in future

Glad I could help though, appreciate it