Refactor types

.gitignore

@@ -9,3 +9,5 @@ script/grammars.yml
 *.log
 .DS_Store
 yarn.lock
+!/lib/types.d.ts
+!/index.d.ts

index.d.ts

@@ -0,0 +1,4 @@
+export type {GetOnigurumaUrl, Grammar, Options} from './lib/types.js'
+export {grammars as all} from './lib/all.js'
+export {grammars as common} from './lib/common.js'
+export {createStarryNight} from './lib/index.js'

index.js

@@ -1,9 +1,4 @@
-/**
- * @typedef {import('./lib/index.js').GetOnigurumaUrl} GetOnigurumaUrl
- * @typedef {import('./lib/index.js').Grammar} Grammar
- * @typedef {import('./lib/index.js').Options} Options
- */
-
+// Note: types exposed from `index.d.ts`.
 export {grammars as all} from './lib/all.js'
 export {grammars as common} from './lib/common.js'
 export {createStarryNight} from './lib/index.js'

lib/get-oniguruma.default.js

@@ -2,7 +2,7 @@
 /* eslint-env browser */
 
 /**
- * @import {Options} from '@wooorm/starry-night'
+ * @import {Options} from './types.js'
  */
 
 /**

lib/get-oniguruma.fs.js

@@ -1,5 +1,5 @@
 /**
- * @import {Options} from '@wooorm/starry-night'
+ * @import {Options} from './types.js'
  */
 
 import fs from 'node:fs/promises'

lib/index.js

@@ -1,97 +1,7 @@
 /**
  * @import {Root} from 'hast'
  * @import {IGrammar, IRawGrammar} from 'vscode-textmate'
- */
-
-/**
- * @typedef {Record<string, Rule>} Captures
- *   Rule `captures` field.
- *
- * @callback GetOnigurumaUrl
- *   Get a URL to the oniguruma WASM.
- *
- *   > 👉 **Note**: this must currently result in a version 1 URL of
- *   > `onig.wasm` from `vscode-oniguruma`.
- *
- *   > ⚠️ **Danger**: when you use this functionality, your project might break at
- *   > any time (when reinstalling dependencies), except when you make sure that
- *   > the WASM binary you load manually is what our internally used
- *   > `vscode-oniguruma` dependency expects.
- *   > To solve this, you could for example use an npm script called `dependencies`
- *   > (which runs everytime `node_modules` is changed) which copies
- *   > `vscode-oniguruma/release/onig.wasm` to the place you want to host it.
- * @returns {Promise<Readonly<URL>> | Readonly<URL>}
- *   URL object to a WASM binary.
- * @example
- *   ```js
- *   import {common, createStarryNight} from '@wooorm/starry-night'
- *
- *   const starryNight = await createStarryNight(common, {
- *     getOnigurumaUrlFetch() {
- *       return new URL('/onig.wasm', window.location.href);
- *     }
- *   })
- *   ```
- *
- * @typedef Grammar
- *   TextMate grammar with some extra info.
- * @property {Array<string>} [dependencies]
- *   List of scopes that are needed for this grammar to work (optional,
- *   example: `['source.tsx']`).
- * @property {Array<string>} extensions
- *   List of extensions (example: `['.mdx']`).
- * @property {Array<string>} [extensionsWithDot]
- *   List of extensions that only match if used w/ a dot (optional, example:
- *   `['.php']`).
- * @property {Record<string, Rule>} [injections]
- *   TextMate injections (optional).
- * @property {Array<string>} names
- *   List of names (example: `['mdx']`).
- * @property {Array<Rule>} patterns
- *   TextMate patterns.
- * @property {Record<string, Rule>} [repository]
- *   TextMate repository (optional).
- * @property {string} scopeName
- *   Scope (example: `source.mdx`).
- *
- * @typedef Options
- *   Configuration (optional).
- * @property {GetOnigurumaUrl | null | undefined} [getOnigurumaUrlFetch]
- *   Get a URL to the oniguruma WASM, typically used in browsers (optional).
- * @property {GetOnigurumaUrl | null | undefined} [getOnigurumaUrlFs]
- *   Get a URL to the oniguruma WASM, typically used in Node.js (optional).
- *
- * @typedef {RuleDefinition | RuleInclude | RuleName} Rule
- *   TextMate rule.
- *
- * @typedef RuleDefinition
- * @property {boolean} [applyEndPatternLast]
- * @property {string} [begin]
- * @property {Captures} [beginCaptures]
- * @property {Captures} [captures]
- * @property {string} [contentName]
- * @property {string} [end]
- * @property {Captures} [endCaptures]
- * @property {Record<string, Rule>} [injections]
- * @property {string} [match]
- * @property {string} [name]
- * @property {Array<Rule>} [patterns]
- * @property {Record<string, Rule>} [repository]
- * @property {string} [while]
- * @property {Captures} [whileCaptures]
- *
- * @typedef RuleInclude
- * @property {string} [begin]
- * @property {string} [end]
- * @property {string} include
- * @property {string} [match]
- * @property {string} [name]
- *
- * @typedef RuleName
- * @property {never} [begin]
- * @property {never} [include]
- * @property {never} [match]
- * @property {string} name
+ * @import {Grammar, Options} from './types.js'
  */
 
 import vscodeOniguruma from 'vscode-oniguruma'

lib/types.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Get a URL to the oniguruma WASM.
+ *
+ * > **Note**: this must currently result in a version 1 URL of
+ * > `onig.wasm` from `vscode-oniguruma`.
+ *
+ * > **Danger**: when you use this functionality, your project might break at
+ * > any time (when reinstalling dependencies), except when you make sure that
+ * > the WASM binary you load manually is what our internally used
+ * > `vscode-oniguruma` dependency expects.
+ * > To solve this, you could for example use an npm script called `dependencies`
+ * > (which runs everytime `node_modules` is changed) which copies
+ * > `vscode-oniguruma/release/onig.wasm` to the place you want to host it.
+ *
+ * @returns
+ *   URL object to a WASM binary.
+ * @example
+ *   ```js
+ *   import {common, createStarryNight} from '@wooorm/starry-night'
+ *
+ *   const starryNight = await createStarryNight(common, {
+ *     getOnigurumaUrlFetch() {
+ *       return new URL('/onig.wasm', window.location.href);
+ *     }
+ *   })
+ *   ```
+ */
+export type GetOnigurumaUrl = () => Promise<Readonly<URL>> | Readonly<URL>
+
+/**
+ * TextMate grammar with some extra info.
+ */
+export interface Grammar {
+  /**
+   * List of scopes that are needed for this grammar to work (optional,
+   * example: `['source.tsx']`).
+   */
+  dependencies?: Array<string>
+  /**
+   *   List of extensions (example: `['.mdx']`).
+   */
+  extensions: Array<string>
+  /**
+   * List of extensions that only match if used w/ a dot (optional, example:
+   * `['.php']`).
+   */
+  extensionsWithDot?: Array<string>
+  /**
+   * TextMate injections (optional).
+   */
+  injections?: Record<string, Rule>
+  /**
+   *   List of names (example: `['mdx']`).
+   */
+  names: Array<string>
+  /**
+   *   TextMate patterns.
+   */
+  patterns: Array<Rule>
+  /**
+   * TextMate repository (optional).
+   */
+  repository?: Record<string, Rule>
+  /**
+   *   Scope (example: `source.mdx`).
+   */
+  scopeName: string
+}
+
+/**
+ * Configuration (optional).
+ */
+export interface Options {
+  /**
+   * Get a URL to the oniguruma WASM, typically used in browsers (optional).
+   */
+  getOnigurumaUrlFetch?: GetOnigurumaUrl | null | undefined
+
+  /**
+   * Get a URL to the oniguruma WASM, typically used in Node.js (optional).
+   */
+  getOnigurumaUrlFs?: GetOnigurumaUrl | null | undefined
+}
+
+/**
+ * TextMate rule.
+ */
+export type Rule = RuleDefinition | RuleInclude | RuleName
+
+export interface RuleDefinition {
+  applyEndPatternLast?: boolean
+  begin?: string
+  beginCaptures?: Record<string, Rule>
+  captures?: Record<string, Rule>
+  contentName?: string
+  end?: string
+  endCaptures?: Record<string, Rule>
+  injections?: Record<string, Rule>
+  match?: string
+  name?: string
+  patterns?: Array<Rule>
+  repository?: Record<string, Rule>
+  while?: string
+  whileCaptures?: Record<string, Rule>
+}
+
+export interface RuleInclude {
+  begin?: string
+  end?: string
+  include: string
+  match?: string
+  name?: string
+}
+
+export interface RuleName {
+  begin?: never
+  include?: never
+  match?: never
+  name: string
+}

lib/types.js

@@ -0,0 +1,2 @@
+// Note: types exposed from `types.d.ts`.
+export {}

package.json

@@ -47,7 +47,6 @@
     "lang/",
     "lib/",
     "style/",
-    "index.d.ts.map",
     "index.d.ts",
     "index.js",
     "notice"
@@ -138,6 +137,29 @@
       "lang/"
     ],
     "overrides": [
+      {
+        "files": [
+          "**/*.d.ts"
+        ],
+        "rules": {
+          "@typescript-eslint/array-type": [
+            "error",
+            {
+              "default": "generic"
+            }
+          ],
+          "@typescript-eslint/ban-types": [
+            "error",
+            {
+              "extendDefaults": true
+            }
+          ],
+          "@typescript-eslint/consistent-type-definitions": [
+            "error",
+            "interface"
+          ]
+        }
+      },
       {
         "files": [
           "script/**/*.js"

script/build.js

@@ -1,5 +1,5 @@
 /**
- * @import {Grammar, Rule} from '../lib/index.js'
+ * @import {Grammar, Rule} from '../lib/types.js'
  */
 
 /**

tsconfig.json

@@ -12,5 +12,5 @@
     "target": "es2022"
   },
   "exclude": ["coverage/", "node_modules/"],
-  "include": ["**/*.js"]
+  "include": ["**/*.js", "lib/types.d.ts", "index.d.ts"]
 }