parse-imports - npm Package Compare versions

Comparing version 1.2.0 to 2.0.0

package.json

 {
   "name": "parse-imports",
-  "version": "1.2.0",
+  "version": "2.0.0",
   "author": {
@@ -28,3 +28,3 @@ "name": "Tomer Aberbach",
   "engines": {
-    "node": ">= 12.17"
+    "node": ">= 18"
   },
@@ -36,3 +36,3 @@ "exports": "./src/index.js",
   "dependencies": {
-    "es-module-lexer": "^1.5.2",
+    "es-module-lexer": "^1.5.3",
     "slashes": "^3.0.12"
@@ -42,8 +42,8 @@ },
     "@types/jest": "^29.5.12",
-    "@types/node": "^20.12.11",
+    "@types/node": "^20.14.8",
     "eslint": "^8.57.0",
     "jest": "^29.7.0",
-    "prettier": "^3.2.5",
-    "tomer": "^3.2.1",
-    "typescript": "^5.4.5"
+    "prettier": "^3.3.2",
+    "tomer": "^3.2.4",
+    "typescript": "^5.5.2"
   },
@@ -50,0 +50,0 @@ "scripts": {

readme.md

@@ -39,3 +39,3 @@ <h1 align="center">
 ```js
-import parseImports from 'parse-imports'
+import { parseImports } from 'parse-imports'
 
@@ -173,32 +173,12 @@ const code = `
 
-### `parseImports(code[, options]) -> Promise<Iterable<Import>>`
+Use `parseImports` when you're able to await a `Promise` result and
+`parseImportsSync` otherwise.
 
-Returns a `Promise` resolving to a lazy
-[iterable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#The_iterable_protocol)/[iterator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#The_iterator_protocol)
-that iterates over the imports in `code`.
+> [!IMPORTANT]
+>
+> You can only call `parseImportsSync` once the WASM has loaded. You can be sure
+> this has happened by awaiting the exported `wasmLoadPromise`.
 
-### Parameters
+See the [type definitions](./src/index.d.ts) for details.
 
-#### `code`
-
-Type: `string`
-
-The JavaScript code to parse for imports.
-
-#### `options`
-
-Type: `object` (optional)
-
-##### Properties
-
-###### `resolveFrom`
-
-Type: `string` (optional)\
-Default: `undefined`
-
-If set to a file path, then `moduleSpecifier.resolved` of the returned `Import`
-instances will be set to the result of calling
-`require.resolve(moduleSpecifier.value)` from the given file path. Otherwise,
-will be `undefined`.
-
 ### Types
@@ -205,0 +185,0 @@

src/index.d.ts

@@ -17,6 +17,23 @@ /**
 
+/** Options for parsing imports. */
 export type Options = {
+  /**
+   * If set to a file path, then {@link Import.moduleSpecifier.resolved} of
+   * returned instances will be set to the result of calling
+   * `require.resolve(moduleSpecifier.value)` from the given file path.
+   * Otherwise, will be undefined.
+   */
   readonly resolveFrom?: string
 }
 
+/**
+ * A type representing what kind of module a specifier refers to.
+ *
+ * - 'unknown' if the module specifier is not a simple constant string literal
+ * - 'invalid' if the module specifier is the empty string
+ * - 'absolute' if the module specifier is an absolute file path
+ * - 'relative' if the module specifier is a relative file path
+ * - 'builtin' if the module specifier is the name of a builtin Node.js package
+ * - 'package' otherwise
+ */
 export type ModuleSpecifierType =
@@ -30,18 +47,91 @@ | 'invalid'
 
+/**
+ * A type representing an import in JavaScript code.
+ *
+ * `code.substring(startIndex, endIndex)` returns the full import statement or
+ * expression.
+ */
 export type Import = {
+  /** The start index of the import in the JavaScript (inclusive). */
   startIndex: number
+
+  /** The end index of the import in the JavaScript (exclusive). */
   endIndex: number
+
+  /** Whether the import is a dynamic import (e.g. `import('module')`). */
   isDynamicImport: boolean
+
+  /**
+   * A type representing the code specifiying the module being imported.
+   *
+   * `code.substring(moduleSpecifier.startIndex, moduleSpecifier.endIndex)`
+   * returns the module specifier including quotes.
+   */
   moduleSpecifier: {
+    /**
+     * What kind of module the specifier refers to.
+     *
+     * 'unknown' when `moduleSpecifier.isConstant` is false.
+     */
     type: ModuleSpecifierType
+
+    /** The start index of the specifier in the JavaScript (inclusive). */
     startIndex: number
+
+    /** The end index of the specifier in the JavaScript (exclusive). */
     endIndex: number
+
+    /**
+     * True when the import is not a dynamic import (`isDynamicImport` is
+     * false), or when the import is a dynamic import where the specifier is a
+     * simple string literal (e.g. import('fs'), import("fs"), import(`fs`)).
+     */
     isConstant: boolean
+
+    /**
+     * The module specifier as it was written in the code. For non-constant
+     * dynamic imports it could be a complex expression.
+     */
     code: string
+
+    /**
+     * `code` without string literal quotes and unescaped if `isConstant` is
+     * true. Otherwise, it is undefined.
+     */
     value?: string
+
+    /** Set if the `resolveFrom` option is set and `value` is not undefined. */
     resolved?: string
   }
+
+  /**
+   * A type representing what is being imported from the module.
+   *
+   * Undefined if `isDynamicImport` is true.
+   */
   importClause?: {
+    /**
+     * The default import identifier or undefined if the import statement does
+     * not have a default import.
+     */
     default?: string
+
+    /**
+     * An array of objects representing the named imports of the import
+     * statement. It is empty if the import statement does not have any named
+     * imports. Each object in the array has a specifier field set to the
+     * imported identifier and a binding field set to the identifier for
+     * accessing the imported value.
+     * For example, `import { a, x as y } from 'something'` would have the
+     * following array:
+     * ```
+     * [{ specifier: 'a', binding: 'a' }, { specifier: 'x', binding: 'y' }]
+     * ```
+     */
     named: { specifier: string; binding: string }[]
+
+    /**
+     * The namespace import identifier or undefined if the import statement does
+     * not have a namespace import.
+     */
     namespace?: string
@@ -51,3 +141,14 @@ }
 
-declare const parseImports: (
+/**
+ * A promise that resolves once WASM has finished loading.
+ *
+ * Await this promise to be certain calling `parseImportsSync` is safe.
+ */
+export const wasmLoadPromise: Promise<void>
+
+/**
+ * Returns a promise resolving to a lazy iterable/iterator that iterates over
+ * the imports in `code`.
+ */
+export const parseImports: (
   code: string,
@@ -57,2 +158,11 @@ options?: Options,
 
-export default parseImports
+/**
+ * Returns a lazy iterable/iterator that iterates over the imports in `code`.
+ *
+ * @throws if called before WASM has finished loading. Await `wasmLoadPromise`
+ * to be sure it has finished.
+ */
+export const parseImportsSync: (
+  code: string,
+  options?: Options,
+) => Iterable<Import>

src/index.js

@@ -17,12 +17,22 @@ /**
 
-import { parse } from 'es-module-lexer'
+import { init, parse } from 'es-module-lexer'
 import parseImportClause from './parse-import-clause/index.js'
 import parseModuleSpecifier from './parse-module-specifier/index.js'
 
-const parseImports = async (code, { resolveFrom } = {}) => {
-  const [imports] = await parse(
-    code,
-    resolveFrom == null ? undefined : resolveFrom,
-  )
+export const wasmLoadPromise = init
 
+export const parseImports = async (code, options) => {
+  await wasmLoadPromise
+  return parseImportsSync(code, options)
+}
+
+export const parseImportsSync = (code, { resolveFrom } = {}) => {
+  const result = parse(code, resolveFrom == null ? undefined : resolveFrom)
+  if (!Array.isArray(result)) {
+    throw new TypeError(
+      `Expected WASM to be loaded before calling parseImportsSync`,
+    )
+  }
+  const [imports] = result
+
   return {
@@ -93,3 +103,1 @@ *[Symbol.iterator]() {
 }
-
-export default parseImports

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

38362

increased by10.04%

Lines of code

547

increased by23.48%

Worsened metrics

Number of lines in readme file

278

decreased by-6.71%

Dependency changes

• Updatedes-module-lexer@^1.5.3