Move to TypeScript #78

vernak2539 · 2024-12-19T16:52:08Z

This PR moves this plugin to use TypeScript. It aims to fix #72 and make the upkeep of types (now jsdoc style + custom declaration files) easier.

TODO:

Context in #72

vernak2539 · 2024-12-19T17:16:26Z

@techfg I think this is most of the way done. Last thing is to sort out the docs, which seem to not be generating correctly. Unsure if it's the differences between tsconfig settings or something else. I've optimised the tsconfig settings for the tsup build

techfg · 2024-12-20T05:42:53Z

@techfg I think this is most of the way done. Last thing is to sort out the docs, which seem to not be generating correctly. Unsure if it's the differences between tsconfig settings or something else. I've optimised the tsconfig settings for the tsup build

Thanks for putting this together. Added some comments that should get you to where you want to be code & doc wise. Note that there are still some issues with typedoc/typedoc-plugin-markdown/typedoc-plugin-zod so I included a workaround (using @interface) for now. That means that the docs will generate as interfaces instead of types which isn't ideal. However, it allows us to make all the code changes to solve both hover & intellisense leaving only the docs to be "fixed" once the typedoc* plugin issues are fully resolved.

vernak2539 · 2024-12-20T16:34:54Z

Thanks @techfg! I'm not sure I'm seeing comments anywhere though 😢

vernak2539 · 2024-12-20T17:13:13Z

@techfg I've gotten a bunch further, but ran out of time for today. I'm not sure the docs are generating right (Options seems to be problematic) unfortunately.

techfg · 2024-12-20T05:18:53Z

src/index.ts

+  type Options,
+  validateOptions,
+  mergeCollectionOptions,
+} from "./options";


Need to export the types to ensure they are generated in the docs along with their properties and the property comments

import { type Options, type CollectionConfig, validateOptions, mergeCollectionOptions, } from "./options"; export type { Options, CollectionConfig };

techfg · 2024-12-20T05:20:06Z

src/index.ts


 // This package makes a lot of assumptions based on it being used with Astro

 const debug = debugFn("astro-rehype-relative-markdown-links");

 /**
- * @type {import('unified').Plugin<[(import('./options.d.ts').Options | null | undefined)?], import('hast').Root>}
+ * Rehype plugin for Astro to add support for transforming relative links in MD and MDX files into their final page paths.


In doc generation, once moving to type from interface, the type will be inlined in the docs instead of referenced so want to include an @see to Options here:

/** * Rehype plugin for Astro to add support for transforming relative links in MD and MDX files into their final page paths. * @see {@link Options} */

techfg · 2024-12-20T05:25:37Z

src/options.ts

+
+/** General options */
+export type Options = z.infer<typeof OptionsSchema>;
+interface EffectiveOptions extends Options {}


Couple of things here:

Options should use z.input while EffectiveOptions should use z.infer (which is the same as z.output)

There are still some remaining issues with typedoc/typedoc-plugin-markdown/etc. when using types instead of interfaces. If you change Options and CollectionsSchema to interface and make all the other changes that I recommend, the docs should generate identical to current. However, we want Options to be a type to solve for the hover issue. So, we use the @interface typedoc tag as a workaround for now. This is not ideal as the docs will have Options as an interface and we're going to lose the TOC, etc. but the code itself will be correct. I'm going to update the isuses I have filed with typedoc, etc. to cover a few additional situations that I found just now. Once all those issues are addressed, we can eliminate the @interface workaround.

type OptionsSchemaType = typeof OptionsSchema; type CollectionConfigSchemaType = typeof CollectionConfigSchema; /** * Collection specific options * @interface */ export type CollectionConfig = z.input<CollectionConfigSchemaType>; /** * General options * @interface */ export type Options = z.input<OptionsSchemaType>; interface EffectiveOptions extends z.infer<OptionsSchemaType> {};

EDIT: Per my recent comment, the @interface workaround should no longer be required and its inclusion can be ignored. The docs should generate correctly with Options and CollectionConfig as types assuming all the changes in other comments are implemented.

techfg · 2024-12-20T05:40:41Z

tsconfig.json

+    "noEmit": true,
+    "allowImportingTsExtensions": true,
+    "lib": ["esnext"],
+    "types": ["node"],


A couple config options to consider:

"strict": true, "noUncheckedIndexedAccess": true,

Also, it may make sense to configure around es2022 instead of ESNext to avoid any potential stability issues, however unlikely they may be, since we don't need to be on bleeding edge.

EDIT: strict is required for the docs to generate correctly when using types instead of interfaces so it must be included.

techfg · 2024-12-20T17:38:00Z

Thanks @techfg! I'm not sure I'm seeing comments anywhere though 😢

Sorry, forgot to hit the "submit" review button - still a weird nuance of github in IMHO that you have to do that instead of it just posting the comment. Either way, you should see the comments now, let me know if you don't.

I'll take a look at the commits you added today and see if anything pops out but the comments you hopefully see now should get you to where you need to be doc wise.

techfg · 2024-12-21T04:13:19Z

src/plugin.test.ts

@@ -418,10 +418,10 @@ describe("astroRehypeRelativeMarkdownLinks", () => {
  });

  describe("config option validation", () => {
-    const runValidationTest = async (context, options) => {
+    const runValidationTest = async (context, options?) => {


This comment actually refers to line 34 above (https://github.com/vernak2539/astro-rehype-relative-markdown-links/pull/78/files#diff-15ddc1bcd6ddf3b9483b554a2e56cad27ca25a7924fcd2e1db0bf2d7a849ccadR34) - GH doesn't allow commenting on unchanged lines :(

The old jsdoc type can be removed. It was wrong to begin with so line 35 should actually be:

function testSetupRehype(options: { currentFilePath?: string } = {}) {

techfg · 2024-12-21T06:04:45Z

src/index.ts

@@ -0,0 +1,4 @@
+import astroRehypeRelativeMarkdownLinks from "./plugin";


Change to the following to ensure docs generate correctly when using types

// NOTE - The order of exports is very important see https://github.com/Gerrit0/typedoc-plugin-zod/issues/8 export type { CollectionConfig, Options } from "./options"; export { default } from "./plugin";

techfg · 2024-12-21T06:12:06Z

@vernak2539 -

Great news! Based on input from Gerrit0/typedoc-plugin-zod#8, I was able to successfully generate the docs using types (instead of interfaces)! I did find another issue typedoc2md/typedoc-plugin-markdown#743, but its resolution shouldn't hold up getting this finished and merged. Once that issue is addressed, we can always update deps and push new docs with a TOC.

I added a few comments to the PR and edit a couple that should hopefully get you to where we want to be docs wise.

Lemme know if you have any issues/questions. Getting close, thank you!

feat(ts): initial move to typescript (no tests)

97a71de

vernak2539 mentioned this pull request Dec 19, 2024

bug: hover & intellisense do not work for Options #72

Open

vernak2539 added 11 commits December 19, 2024 16:55

feat(ts): update type of default export

458c5aa

feat(ts): add tsx as dep to run node test runner with typescript support

418bf34

feat(ts): covert test files to ts

ddf05dc

feat(ts): udpate test files and get runner working

681519b

feat(ts): build package before publish

86d51f8

feat(ts): upgrade typedoc and deps

4581855

feat(ts): add build command to tests

4a2fb49

feat(ts): move build to own job

95a9491

feat(ts): update name of test+build gh action

6df53c4

fix(docs): point typedoc at index.ts + export option type again

bcea29a

fix(docs): add back description

bdb8f1a

vernak2539 added 6 commits December 20, 2024 16:38

fix(tsconfig): update tsconfig.json

3ba0bec

fix(structure): move index to plugin + use index for exports

1c56336

fix(types): export CollectionConfig

ee1835d

chore: install and use typedoc-plugin-zod

8789e23

chore: allow back ts extensions

c050656

fix(tests): fix tests

007a526

techfg suggested changes Dec 20, 2024

View reviewed changes

techfg suggested changes Dec 21, 2024

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Move to TypeScript #78

Move to TypeScript #78

vernak2539 commented Dec 19, 2024 •

edited

Loading

vernak2539 commented Dec 19, 2024

techfg commented Dec 20, 2024

vernak2539 commented Dec 20, 2024

vernak2539 commented Dec 20, 2024

techfg Dec 20, 2024

techfg Dec 20, 2024

techfg Dec 20, 2024 •

edited

Loading

techfg Dec 20, 2024 •

edited

Loading

techfg commented Dec 20, 2024

techfg Dec 21, 2024

techfg Dec 21, 2024

techfg commented Dec 21, 2024

		@@ -0,0 +1,4 @@
		import astroRehypeRelativeMarkdownLinks from "./plugin";

Move to TypeScript #78

Are you sure you want to change the base?

Move to TypeScript #78

Conversation

vernak2539 commented Dec 19, 2024 • edited Loading

vernak2539 commented Dec 19, 2024

techfg commented Dec 20, 2024

vernak2539 commented Dec 20, 2024

vernak2539 commented Dec 20, 2024

techfg Dec 20, 2024

Choose a reason for hiding this comment

techfg Dec 20, 2024

Choose a reason for hiding this comment

techfg Dec 20, 2024 • edited Loading

Choose a reason for hiding this comment

techfg Dec 20, 2024 • edited Loading

Choose a reason for hiding this comment

techfg commented Dec 20, 2024

techfg Dec 21, 2024

Choose a reason for hiding this comment

techfg Dec 21, 2024

Choose a reason for hiding this comment

techfg commented Dec 21, 2024

vernak2539 commented Dec 19, 2024 •

edited

Loading

techfg Dec 20, 2024 •

edited

Loading

techfg Dec 20, 2024 •

edited

Loading