docs: use

Signed-off-by: Lexus Drumgold <[email protected]>

Author: unicornware

README.md

@@ -65,7 +65,114 @@ yarn add @flex-development/ext-regex@flex-development/ext-regex
 
 ## Use
 
-**TODO**: usage example.
+```typescript
+import { DECORATOR_REGEX } from '@flex-development/decorator-regex'
+import { EXT_DTS_REGEX, EXT_TS_REGEX } from '@flex-development/ext-regex'
+import * as mlly from '@flex-development/mlly'
+import pathe from '@flex-development/pathe'
+import * as tscu from '@flex-development/tsconfig-utils'
+import type { Nullable } from '@flex-development/tutils'
+import type {
+  OnLoadArgs,
+  OnLoadOptions,
+  OnLoadResult,
+  Plugin,
+  PluginBuild
+} from 'esbuild'
+import type { URL } from 'node:url'
+
+/**
+ * Returns a plugin that allows esbuild to handle [`emitDecoratorMetadata`][1].
+ *
+ * [1]: https://www.typescriptlang.org/tsconfig#emitDecoratorMetadata
+ *
+ * @param {tscu.LoadTsconfigOptions?} [options] - Plugin options
+ * @return {Plugin} Decorator metadata plugin
+ */
+const plugin = (options?: tscu.LoadTsconfigOptions): Plugin => ({
+  name: 'decorators',
+  setup: async ({ initialOptions, onLoad }: PluginBuild): Promise<void> => {
+    const { absWorkingDir = '.', tsconfig = 'tsconfig.json' } = initialOptions
+
+    /**
+     * User compiler options.
+     *
+     * @const {tscu.CompilerOptions} compilerOptions
+     */
+    const compilerOptions: tscu.CompilerOptions = tscu.loadCompilerOptions(
+      pathe.resolve(absWorkingDir, tsconfig),
+      options
+    )
+
+    // exit early if decorator metadata should not be emitted
+    if (!compilerOptions.emitDecoratorMetadata) return void 0
+
+    /**
+     * TypeScript module.
+     *
+     * @const {typeof import('typescript')} ts
+     */
+    const ts: typeof import('typescript') = (await import('typescript')).default
+
+    /**
+     * {@linkcode onLoad} callback options.
+     *
+     * @const {OnLoadOptions}
+     */
+    const opts: OnLoadOptions = { filter: /.*/ }
+
+    // transpile typescript modules containing decorators
+    onLoad(opts, async (args: OnLoadArgs): Promise<Nullable<OnLoadResult>> => {
+      /**
+       * Callback result.
+       *
+       * @var {Nullable<OnLoadResult>} result
+       */
+      let result: Nullable<OnLoadResult> = null
+
+      // transpile typescript modules, but skip typescript declaration modules
+      if (EXT_TS_REGEX.test(args.path) && !EXT_DTS_REGEX.test(args.path)) {
+        /**
+         * URL of module to load.
+         *
+         * @const {URL} url
+         */
+        const url: URL = mlly.toURL(args.path)
+
+        /**
+         * File content at {@linkcode args.path}.
+         *
+         * @const {string} source
+         */
+        const source: string = (await mlly.getSource(url)) as string
+
+        // do nothing if module does not use decorators
+        if (!DECORATOR_REGEX.test(source)) return null
+
+        // transpile module to emit decorator metadata
+        const { outputText: contents } = ts.transpileModule(source, {
+          compilerOptions: tscu.normalizeCompilerOptions(compilerOptions)
+        })
+
+        result = { contents }
+      }
+
+      return result
+    })
+
+    return void 0
+  }
+})
+
+export default plugin
+```
+
+<blockquote>
+  <small>
+    Looking for a plugin like this? Check out&nbsp;
+    <a href='https://github.com/flex-development/mkbuild'><code>mkbuild</code></a> 😉
+  </small>
+</blockquote>
 
 ## API
 

package.json

@@ -75,6 +75,7 @@
   "devDependencies": {
     "@commitlint/cli": "17.4.3",
     "@commitlint/config-conventional": "17.4.3",
+    "@flex-development/decorator-regex": "1.0.0",
     "@flex-development/mkbuild": "1.0.0-alpha.11",
     "@flex-development/mlly": "1.0.0-alpha.11",
     "@flex-development/tsconfig-utils": "1.1.1",

yarn.lock

@@ -1134,6 +1134,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@flex-development/decorator-regex@npm:1.0.0":
+  version: 1.0.0
+  resolution: "@flex-development/decorator-regex@npm:1.0.0::__archiveUrl=https%3A%2F%2Fnpm.pkg.github.com%2Fdownload%2F%40flex-development%2Fdecorator-regex%2F1.0.0%2Fe485b45a5c66ca688d77188039bb5efa90ca3fb8"
+  checksum: 3200659769897add6af31341c391a58a4edc7920b81042a7117a95c50ae0375da2f62c6869060ce91507a29ac9dbd06a96e440fe30b438536685f7ce36a1daca
+  languageName: node
+  linkType: hard
+
 "@flex-development/errnode@npm:1.2.0":
   version: 1.2.0
   resolution: "@flex-development/errnode@npm:1.2.0::__archiveUrl=https%3A%2F%2Fnpm.pkg.github.com%2Fdownload%2F%40flex-development%2Ferrnode%2F1.2.0%2F8e54e66e637d392299cd2d422224da9cf5d16cab"
@@ -1183,6 +1190,7 @@ __metadata:
   dependencies:
     "@commitlint/cli": "npm:17.4.3"
     "@commitlint/config-conventional": "npm:17.4.3"
+    "@flex-development/decorator-regex": "npm:1.0.0"
     "@flex-development/errnode": "npm:1.5.0"
     "@flex-development/mkbuild": "npm:1.0.0-alpha.11"
     "@flex-development/mlly": "npm:1.0.0-alpha.11"