docs: add usage docs

Signed-off-by: Lexus Drumgold <unicornware@flexdevelopment.llc>

.dictionary.txt

@@ -1,6 +1,7 @@
 ardatan
 bdougie
 cefc
+colorette
 commitlintrc
 dawidd
 dedupe

README.md

@@ -32,7 +32,7 @@ Use this package when you need to match dynamic or static `import` statements.
 **Note**:
 
 - Statements in docblock (`/** */`), multiline (`/* */`), and single-line (`//`) comments are ignored
-- Regular expressions are ECMAScript-compatible. They have **not** been tested with other flavors (PCRE, PCRE2, etc)
+- Expressions are ECMAScript-compatible. They have **not** been tested with other flavors (PCRE, PCRE2, etc)
 
 ## Install
 
@@ -57,15 +57,184 @@ yarn add @flex-development/import-regex@flex-development/import-regex
 
 ## Use
 
-**TODO**: Update documentation.
+Suppose we have the following module:
+
+```typescript
+import * as regexp from '@flex-development/import-regex'
+import { omit } from 'radash'
+import dedent from 'ts-dedent'
+
+const code: string = dedent`
+  import { defineBuildConfig, type Config } from '@flex-development/mkbuild'
+  import type {
+    Join,
+    Nullable,
+    Opaque,
+    Simplify
+  } from '@flex-development/tutils'
+  import * as color from 'colorette'
+  import consola from 'consola'
+  import tsconfig from './tsconfig.json' assert { type: 'json' }
+
+  const { readPackage } = await import('read-pkg')
+
+  const se2 = 'side-effect-2.mjs'
+
+  await import('./side-effect.mjs')
+  await import(se2)
+`
+
+const print = (matches: IterableIterator<RegExpMatchArray>): void => {
+  console.debug([...matches].map(match => omit(match, ['input'])))
+}
+
+print(code.matchAll(regexp.STATIC_IMPORT_REGEX))
+print(code.matchAll(regexp.DYNAMIC_IMPORT_REGEX))
+```
+
+...running that yields:
+
+```sh
+[
+  {
+    '0': "import { defineBuildConfig, type Config } from '@flex-development/mkbuild'",
+    '1': undefined,
+    '2': '{ defineBuildConfig, type Config }',
+    '3': '@flex-development/mkbuild',
+    '4': undefined,
+    index: 0,
+    groups: [Object: null prototype] {
+      type: undefined,
+      imports: '{ defineBuildConfig, type Config }',
+      specifier: '@flex-development/mkbuild',
+      assertion: undefined
+    }
+  },
+  {
+    '0': 'import type {\n' +
+      '  Join,\n' +
+      '  Nullable,\n' +
+      '  Opaque,\n' +
+      '  Simplify\n' +
+      "} from '@flex-development/tutils'",
+    '1': 'type',
+    '2': '{\n  Join,\n  Nullable,\n  Opaque,\n  Simplify\n}',
+    '3': '@flex-development/tutils',
+    '4': undefined,
+    index: 75,
+    groups: [Object: null prototype] {
+      type: 'type',
+      imports: '{\n  Join,\n  Nullable,\n  Opaque,\n  Simplify\n}',
+      specifier: '@flex-development/tutils',
+      assertion: undefined
+    }
+  },
+  {
+    '0': "import * as color from 'colorette'",
+    '1': undefined,
+    '2': '* as color',
+    '3': 'colorette',
+    '4': undefined,
+    index: 164,
+    groups: [Object: null prototype] {
+      type: undefined,
+      imports: '* as color',
+      specifier: 'colorette',
+      assertion: undefined
+    }
+  },
+  {
+    '0': "import consola from 'consola'",
+    '1': undefined,
+    '2': 'consola',
+    '3': 'consola',
+    '4': undefined,
+    index: 199,
+    groups: [Object: null prototype] {
+      type: undefined,
+      imports: 'consola',
+      specifier: 'consola',
+      assertion: undefined
+    }
+  },
+  {
+    '0': "import tsconfig from './tsconfig.json' assert { type: 'json' }",
+    '1': undefined,
+    '2': 'tsconfig',
+    '3': './tsconfig.json',
+    '4': "{ type: 'json' }",
+    index: 229,
+    groups: [Object: null prototype] {
+      type: undefined,
+      imports: 'tsconfig',
+      specifier: './tsconfig.json',
+      assertion: "{ type: 'json' }"
+    }
+  }
+]
+[
+  {
+    '0': "const { readPackage } = await import('read-pkg')",
+    '1': '{ readPackage }',
+    '2': "import('read-pkg')",
+    '3': "'read-pkg'",
+    '4': undefined,
+    index: 293,
+    groups: [Object: null prototype] {
+      imports: '{ readPackage }',
+      expression: "import('read-pkg')",
+      specifier: "'read-pkg'",
+      assertion: undefined
+    }
+  },
+  {
+    '0': "await import('./side-effect.mjs')",
+    '1': undefined,
+    '2': "import('./side-effect.mjs')",
+    '3': "'./side-effect.mjs'",
+    '4': undefined,
+    index: 376,
+    groups: [Object: null prototype] {
+      imports: undefined,
+      expression: "import('./side-effect.mjs')",
+      specifier: "'./side-effect.mjs'",
+      assertion: undefined
+    }
+  },
+  {
+    '0': 'await import(se2)',
+    '1': undefined,
+    '2': 'import(se2)',
+    '3': 'se2',
+    '4': undefined,
+    index: 410,
+    groups: [Object: null prototype] {
+      imports: undefined,
+      expression: 'import(se2)',
+      specifier: 'se2',
+      assertion: undefined
+    }
+  }
+]
+```
 
 ## API
 
-**TODO**: Update documentation.
+This package exports the identifiers `DYNAMIC_IMPORT_REGEX` and `STATIC_IMPORT_REGEX`. There is no default export.
+
+### `DYNAMIC_IMPORT_REGEX`
+
+Dynamic `import` statement regex.
+
+**Requires unicode support ([flag `u`][4])**.
+
+### `STATIC_IMPORT_REGEX`
+
+Static `import` statement regex.
 
 ## Types
 
-This package is fully typed with [TypeScript][4].
+This package is fully typed with [TypeScript][5].
 
 ## Contribute
 
@@ -74,4 +243,5 @@ See [`CONTRIBUTING.md`](CONTRIBUTING.md).
 [1]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/import
 [2]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Operators/import
 [3]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
-[4]: https://www.typescriptlang.org
+[4]: https://javascript.info/regexp-unicode
+[5]: https://www.typescriptlang.org

src/import-dynamic.ts

@@ -6,7 +6,9 @@
 /**
  * Dynamic `import` statement regex. Ignores matches in comments.
  *
- * **Note**: Requires unicode support.
+ * **Note**: Requires unicode support ([flag `u`][1]).
+ *
+ * [1]: https://javascript.info/regexp-unicode
  *
  * @see https://regex101.com/r/PTPAvU
  *