chore: entrypoints for plugins (#126)

* chore: entrypoints for plugins

* refactor: rename plugins and omit the plugin suffix

* refactor: use kebab case for the plugin names

* docs(changeset): refactor!: use dedicated entrypoints for the plugins

.changeset/gentle-hairs-raise.md

@@ -0,0 +1,5 @@
+---
+'@scalar/openapi-parser': minor
+---
+
+refactor!: use dedicated entrypoints for the plugins

README.md

@@ -133,23 +133,25 @@ const result = openapi()
 You can reference other files, too. To do that, the parser needs to know what files are available.
 
 ```ts
-import {
-  dereference,
-  fetchUrlsPlugin,
-  load,
-  readFilesPlugin,
-} from '@scalar/openapi-parser'
+import { dereference, load } from '@scalar/openapi-parser'
+import { fetchUrls } from '@scalar/openapi-parser/plugins/fetch-urls'
+import { readFiles } from '@scalar/openapi-parser/plugins/read-files'
 
 // Load a file and all referenced files
 const { filesystem } = await load('./openapi.yaml', {
-  plugins: [readFilesPlugin(), fetchUrlsPlugin()],
+  plugins: [
+    readFiles(),
+    fetchUrls({
+      limit: 5,
+    }),
+  ],
 })
 
 // Instead of just passing a single specification, pass the whole “filesystem”
 const result = await dereference(filesystem)
 ```
 
-As you see, `load()` supports plugin. You can write your own plugin, if you’d like to fetch API defintions from another data source, for example your database. Look at the source code of the `readFilesPlugin` to learn how this could look like.
+As you see, `load()` supports plugin. You can write your own plugin, if you’d like to fetch API defintions from another data source, for example your database. Look at the source code of the `readFiles` to learn how this could look like.
 
 ## Community
 

demo/src/App.vue

@@ -1,5 +1,6 @@
 <script setup lang="ts">
-import { dereference, fetchUrlsPlugin, load } from '@scalar/openapi-parser'
+import { dereference, load } from '@scalar/openapi-parser'
+import { fetchUrls } from '@scalar/openapi-parser/plugins/fetch-urls'
 import { watchDebounced } from '@vueuse/core'
 import { onMounted, ref, watch } from 'vue'
 // @ts-expect-error Package doesn’t come with types
@@ -50,7 +51,7 @@ watchDebounced(
   value,
   async (newValue) => {
     const { filesystem } = await load(newValue, {
-      plugins: [fetchUrlsPlugin()],
+      plugins: [fetchUrls()],
     })
 
     const { schema } = await dereference(filesystem)

demo/vite.config.ts

@@ -11,20 +11,20 @@ export default defineConfig({
   //     external: [...builtinModules, ...builtinModules.map((m) => `node:${m}`)],
   //   },
   // },
-  resolve: {
-    alias: [
-      // Resolve the uncompiled source code for all @scalar packages
-      // It’s working with the alias, too. It’s just required to enable HMR.
-      // It also does not match components since we want the built version
-      {
-        // Resolve the uncompiled source code for @scalar/openapi-parser packages
-        find: '@scalar/openapi-parser',
-        replacement: path.resolve(
-          __dirname,
-          // '../packages/openapi-parser/dist/index.js',
-          '../packages/openapi-parser/src/index.ts',
-        ),
-      },
-    ],
-  },
+  // resolve: {
+  //   alias: [
+  //     // Resolve the uncompiled source code for all @scalar packages
+  //     // It’s working with the alias, too. It’s just required to enable HMR.
+  //     // It also does not match components since we want the built version
+  //     {
+  //       // Resolve the uncompiled source code for @scalar/openapi-parser packages
+  //       find: '@scalar/openapi-parser',
+  //       replacement: path.resolve(
+  //         __dirname,
+  //         // '../packages/openapi-parser/dist/index.js',
+  //         '../packages/openapi-parser/src/index.ts',
+  //       ),
+  //     },
+  //   ],
+  // },
 })

packages/openapi-parser/package.json

@@ -24,6 +24,17 @@
   "main": "./dist/src/index.js",
   "module": "./dist/src/index.js",
   "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/src/index.js"
+    },
+    "./plugins/fetch-urls": {
+      "import": "./dist/src/utils/load/plugins/fetchUrls.js"
+    },
+    "./plugins/read-files": {
+      "import": "./dist/src/utils/load/plugins/fetchUrls.js"
+    }
+  },
   "sideEffects": false,
   "repository": {
     "type": "git",

packages/openapi-parser/rollup.config.ts

@@ -8,7 +8,11 @@ import type { Options as ESBuildOptions } from 'rollup-plugin-esbuild'
 import esbuild from 'rollup-plugin-esbuild'
 import { webpackStats } from 'rollup-plugin-webpack-stats'
 
-const input = `./src/index.ts`
+const input = [
+  './src/index.ts',
+  './src/utils/load/plugins/fetchUrls.ts',
+  './src/utils/load/plugins/readFiles.ts',
+]
 const dir = 'dist'
 
 /**

packages/openapi-parser/src/pipeline.test.ts

@@ -3,7 +3,7 @@ import { describe, expect, it } from 'vitest'
 import { stringify } from 'yaml'
 
 import { openapi } from './pipeline'
-import { readFilesPlugin } from './utils/load/plugins/readFilesPlugin'
+import { readFiles } from './utils/load/plugins/readFiles'
 
 const example = {
   openapi: '3.1.0',
@@ -37,7 +37,7 @@ describe('pipeline', () => {
   it('load file', async () => {
     const { specification } = await openapi()
       .load(EXAMPLE_FILE, {
-        plugins: [readFilesPlugin()],
+        plugins: [readFiles()],
       })
       .get()
 
@@ -47,7 +47,7 @@ describe('pipeline', () => {
   it('files', async () => {
     const filesystem = await openapi()
       .load(EXAMPLE_FILE, {
-        plugins: [readFilesPlugin()],
+        plugins: [readFiles()],
       })
       .files()
 

packages/openapi-parser/src/utils/load/index.ts

@@ -1,2 +1 @@
 export * from './load'
-export * from './plugins'

packages/openapi-parser/src/utils/load/load.test.ts

@@ -4,8 +4,8 @@ import { stringify } from 'yaml'
 
 import { getEntrypoint } from '../getEntrypoint'
 import { load } from './load'
-import { fetchUrlsPlugin } from './plugins/fetchUrlsPlugin'
-import { readFilesPlugin } from './plugins/readFilesPlugin'
+import { fetchUrls } from './plugins/fetchUrls'
+import { readFiles } from './plugins/readFiles'
 
 describe('load', async () => {
   it('loads JS object', async () => {
@@ -19,7 +19,7 @@ describe('load', async () => {
         paths: {},
       },
       {
-        plugins: [readFilesPlugin(), fetchUrlsPlugin()],
+        plugins: [readFiles(), fetchUrls()],
       },
     )
 
@@ -44,7 +44,7 @@ describe('load', async () => {
         paths: {},
       }),
       {
-        plugins: [readFilesPlugin(), fetchUrlsPlugin()],
+        plugins: [readFiles(), fetchUrls()],
       },
     )
 
@@ -69,7 +69,7 @@ describe('load', async () => {
         paths: {},
       }),
       {
-        plugins: [readFilesPlugin(), fetchUrlsPlugin()],
+        plugins: [readFiles(), fetchUrls()],
       },
     )
 
@@ -90,7 +90,7 @@ describe('load', async () => {
     )
 
     const { filesystem } = await load(EXAMPLE_FILE, {
-      plugins: [readFilesPlugin(), fetchUrlsPlugin()],
+      plugins: [readFiles(), fetchUrls()],
     })
 
     expect(getEntrypoint(filesystem).specification).toMatchObject({
@@ -110,7 +110,7 @@ describe('load', async () => {
     )
 
     const { filesystem } = await load(EXAMPLE_FILE, {
-      plugins: [readFilesPlugin()],
+      plugins: [readFiles()],
     })
 
     // filenames
@@ -151,7 +151,7 @@ describe('load', async () => {
       }) as Response
 
     const { filesystem } = await load('https://example.com/openapi.yaml', {
-      plugins: [readFilesPlugin(), fetchUrlsPlugin()],
+      plugins: [readFiles(), fetchUrls()],
     })
 
     expect(getEntrypoint(filesystem).specification).toMatchObject({
@@ -194,7 +194,7 @@ describe('load', async () => {
         },
       },
       {
-        plugins: [readFilesPlugin(), fetchUrlsPlugin()],
+        plugins: [readFiles(), fetchUrls()],
       },
     )
 
@@ -239,7 +239,7 @@ describe('load', async () => {
       },
       {
         plugins: [
-          fetchUrlsPlugin({
+          fetchUrls({
             limit: 0,
           }),
         ],
@@ -291,7 +291,7 @@ describe('load', async () => {
     }
 
     const { filesystem } = await load('https://example.com/openapi.yaml', {
-      plugins: [readFilesPlugin(), fetchUrlsPlugin()],
+      plugins: [readFiles(), fetchUrls()],
     })
 
     expect(filesystem[0].specification).toMatchObject({
@@ -358,7 +358,7 @@ describe('load', async () => {
         },
       }),
       {
-        plugins: [readFilesPlugin(), fetchUrlsPlugin()],
+        plugins: [readFiles(), fetchUrls()],
       },
     )
 

packages/openapi-parser/src/utils/load/plugins/fetchUrlsPlugin.test.ts → packages/openapi-parser/src/utils/load/plugins/fetchUrls.test.ts

@@ -1,28 +1,28 @@
 import { describe, expect, it } from 'vitest'
 
-import { fetchUrlsPlugin } from './fetchUrlsPlugin'
+import { fetchUrls } from './fetchUrls'
 
-describe('fetchUrlsPlugin', async () => {
+describe('fetchUrls', async () => {
   it('returns true for an url', async () => {
     expect(
-      fetchUrlsPlugin().check('http://example.com/specification/openapi.yaml'),
+      fetchUrls().check('http://example.com/specification/openapi.yaml'),
     ).toBe(true)
   })
 
   it('returns false for a filename', async () => {
-    expect(fetchUrlsPlugin().check('openapi.yaml')).toBe(false)
+    expect(fetchUrls().check('openapi.yaml')).toBe(false)
   })
 
   it('returns false for a path', async () => {
-    expect(fetchUrlsPlugin().check('specification/openapi.yaml')).toBe(false)
+    expect(fetchUrls().check('specification/openapi.yaml')).toBe(false)
   })
 
   it('returns false for an object', async () => {
-    expect(fetchUrlsPlugin().check({})).toBe(false)
+    expect(fetchUrls().check({})).toBe(false)
   })
 
   it('returns false for undefinded', async () => {
-    expect(fetchUrlsPlugin().check()).toBe(false)
+    expect(fetchUrls().check()).toBe(false)
   })
 
   it('fetches the URL', async () => {
@@ -38,9 +38,7 @@ describe('fetchUrlsPlugin', async () => {
       }) as Response
 
     expect(
-      await fetchUrlsPlugin().get(
-        'http://example.com/specification/openapi.yaml',
-      ),
+      await fetchUrls().get('http://example.com/specification/openapi.yaml'),
     ).toBe('OK')
   })
 
@@ -57,7 +55,7 @@ describe('fetchUrlsPlugin', async () => {
       }) as Response
 
     expect(
-      await fetchUrlsPlugin({
+      await fetchUrls({
         fetch: (url) => fetch(url.replace('example', 'foobar')),
       }).get('http://foobar.com/specification/openapi.yaml'),
     ).toBe('OK')

packages/openapi-parser/src/utils/load/plugins/fetchUrlsPlugin.ts → packages/openapi-parser/src/utils/load/plugins/fetchUrls.ts

@@ -1,10 +1,10 @@
 import { LoadPlugin } from '../load'
 
-export const fetchUrlsPluginDefaultConfiguration = {
+export const fetchUrlsDefaultConfiguration = {
   limit: 20,
 }
 
-export const fetchUrlsPlugin: (customConfiguration?: {
+export const fetchUrls: (customConfiguration?: {
   /**
    * Limit the number of requests. Set to `false` to disable the limit.
    */
@@ -19,7 +19,7 @@ export const fetchUrlsPlugin: (customConfiguration?: {
 
   // Configuration
   const configuration = {
-    ...fetchUrlsPluginDefaultConfiguration,
+    ...fetchUrlsDefaultConfiguration,
     ...customConfiguration,
   }
 
@@ -44,7 +44,7 @@ export const fetchUrlsPlugin: (customConfiguration?: {
         numberOfRequests >= configuration?.limit
       ) {
         console.warn(
-          `[fetchUrlsPlugin] Maximum number of requests reeached (${configuration?.limit}), skipping request`,
+          `[fetchUrls] Maximum number of requests reeached (${configuration?.limit}), skipping request`,
         )
         return undefined
       }
@@ -58,7 +58,7 @@ export const fetchUrlsPlugin: (customConfiguration?: {
 
         return await response.text()
       } catch (error) {
-        console.error('[fetchUrlsPlugin]', error.message, `(${value})`)
+        console.error('[fetchUrls]', error.message, `(${value})`)
       }
     },
   }

packages/openapi-parser/src/utils/load/plugins/readFiles.test.ts

@@ -0,0 +1,27 @@
+import { describe, expect, it } from 'vitest'
+
+import { readFiles } from './readFiles'
+
+describe('readFiles', async () => {
+  it('returns true for a filename', async () => {
+    expect(readFiles().check('openapi.yaml')).toBe(true)
+  })
+
+  it('returns true for a path', async () => {
+    expect(readFiles().check('../specification/openapi.yaml')).toBe(true)
+  })
+
+  it('returns false for an object', async () => {
+    expect(readFiles().check({})).toBe(false)
+  })
+
+  it('returns false for undefinded', async () => {
+    expect(readFiles().check()).toBe(false)
+  })
+
+  it('returns false for an url', async () => {
+    expect(
+      readFiles().check('http://example.com/specification/openapi.yaml'),
+    ).toBe(false)
+  })
+})