Xmr/dev

.github/workflows/ci.yml

@@ -22,7 +22,7 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest, windows-latest]
-        node: [18, 20, 22, 24]
+        node: [20, 22, 24]
 
     steps:
       - name: Clone repository

README.md

@@ -25,8 +25,12 @@ npm install precinct
 ## Quick start
 
 ```js
+// ESM
+import fs from 'node:fs';
+import precinct from 'precinct';
+// CommonJS
 const fs = require('node:fs');
-const precinct = require('precinct');
+const { default: precinct } = require('precinct');
 
 const content = fs.readFileSync('myFile.js', 'utf8');
 
@@ -88,6 +92,9 @@ Reads the file at `filename` and returns an array of its dependencies. The modul
 #### Example
 
 ```js
+// ESM
+import { paperwork } from 'precinct';
+// CommonJS
 const { paperwork } = require('precinct');
 
 const deps = paperwork('myFile.js');

bin/cli.js

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
 
-'use strict';
+import fs from 'node:fs';
+import { program } from 'commander';
+import precinct from '../index.js';
+import pkg from '../package.json' with { type: 'json' };
 
-const fs = require('fs');
-const { program } = require('commander');
-const precinct = require('../index.js');
-const { name, description, version } = require('../package.json');
+const { name, description, version } = pkg;
 
 program
   .name(name)

index.d.ts

@@ -1,31 +1,41 @@
-export = precinct;
+export default precinct;
+export type PrecinctOptions = Partial<Record<string, Record<string, any>>> & {
+    type?: string;
+    walker?: Record<string, any>;
+};
+export type PaperworkOptions = PrecinctOptions & {
+    includeCore?: boolean;
+    fileSystem?: {
+        readFileSync: (path: string, encoding: "utf8") => string;
+    };
+};
+/**
+ * @typedef {Partial<Record<string, Record<string, any>>> & {
+ *   type?: string,
+ *   walker?: Record<string, any>
+ * }} PrecinctOptions
+ */
+/**
+ * @typedef {PrecinctOptions & {
+ *   includeCore?: boolean,
+ *   fileSystem?: { readFileSync: (path: string, encoding: 'utf8') => string }
+ * }} PaperworkOptions
+ */
 /**
  * Finds the list of dependencies for the given file
  *
- * @param {String|Object} content - File's content or AST
- * @param {Object} [options]
- * @param {String} [options.type] - The type of content being passed in. Useful if you want to use a non-JS detective
- * @param {Record<string, any>} [options.walker] - Options to pass to node-source-walk
- * @return {String[]}
+ * @param {string | Record<string, any>} content - File's content or AST
+ * @param {PrecinctOptions} [options]
+ * @return {string[]}
  */
-declare function precinct(content: string | any, options?: {
-    type?: string;
-    walker?: Record<string, any>;
-}): string[];
+declare function precinct(content: string | Record<string, any>, options?: PrecinctOptions): string[];
 declare namespace precinct {
     /**
      * Returns the dependencies for the given file path
      *
-     * @param {String} filename
-     * @param {Object} [options]
-     * @param {Boolean} [options.includeCore=true] - Whether or not to include core modules in the dependency list
-     * @param {Object} [options.fileSystem=undefined] - An alternative fs implementation to use for reading the file path.
-     * @param {Record<string, any>} [options.walker] - Options to pass to node-source-walk
-     * @return {String[]}
+     * @param {string} filename
+     * @param {PaperworkOptions} [options]
+     * @return {string[]}
      */
-    function paperwork(filename: string, options?: {
-        includeCore?: boolean;
-        fileSystem?: any;
-        walker?: Record<string, any>;
-    }): string[];
+    function paperwork(filename: string, options?: PaperworkOptions): string[];
 }

index.js

@@ -1,32 +1,42 @@
-'use strict';
-
-const fs = require('fs');
-const { builtinModules } = require('module');
-const path = require('path');
-const { debuglog } = require('util');
-const getModuleType = require('module-definition');
-const Walker = require('node-source-walk');
-const detectiveAmd = require('detective-amd');
-const detectiveCjs = require('detective-cjs');
-const detectiveEs6 = require('detective-es6');
-const detectiveLess = require('@dependents/detective-less');
-const detectivePostcss = require('detective-postcss');
-const detectiveSass = require('detective-sass');
-const detectiveScss = require('detective-scss');
-const detectiveStylus = require('detective-stylus');
-const detectiveTypeScript = require('detective-typescript');
-const detectiveVue = require('detective-vue2');
+import fs from 'node:fs';
+import { builtinModules } from 'node:module';
+import path from 'node:path';
+import { debuglog } from 'node:util';
+import getModuleType from 'module-definition';
+import Walker from 'node-source-walk';
+import detectiveAmd from 'detective-amd';
+import detectiveCjs from 'detective-cjs';
+import detectiveEs6 from 'detective-es6';
+import detectiveLess from '@dependents/detective-less';
+import detectivePostcss from 'detective-postcss';
+import detectiveSass from 'detective-sass';
+import detectiveScss from 'detective-scss';
+import detectiveStylus from 'detective-stylus';
+import detectiveTypeScript from 'detective-typescript';
+import detectiveVue from 'detective-vue2';
 
 const debug = debuglog('precinct');
 
+/**
+ * @typedef {Partial<Record<string, Record<string, any>>> & {
+ *   type?: string,
+ *   walker?: Record<string, any>
+ * }} PrecinctOptions
+ */
+
+/**
+ * @typedef {PrecinctOptions & {
+ *   includeCore?: boolean,
+ *   fileSystem?: { readFileSync: (path: string, encoding: 'utf8') => string }
+ * }} PaperworkOptions
+ */
+
 /**
  * Finds the list of dependencies for the given file
  *
- * @param {String|Object} content - File's content or AST
- * @param {Object} [options]
- * @param {String} [options.type] - The type of content being passed in. Useful if you want to use a non-JS detective
- * @param {Record<string, any>} [options.walker] - Options to pass to node-source-walk
- * @return {String[]}
+ * @param {string | Record<string, any>} content - File's content or AST
+ * @param {PrecinctOptions} [options]
+ * @return {string[]}
  */
 function precinct(content, options = {}) {
   debug('options given: %o', options);
@@ -43,7 +53,7 @@ function precinct(content, options = {}) {
       ast = walker.parse(content);
       debug('parsed the file content into an ast');
       precinct.ast = ast;
-    } catch (error) {
+    } catch(error) {
       // In case a previous call had it populated
       precinct.ast = null;
       debug('could not parse content: %s', error.message);
@@ -81,12 +91,9 @@ function precinct(content, options = {}) {
 /**
  * Returns the dependencies for the given file path
  *
- * @param {String} filename
- * @param {Object} [options]
- * @param {Boolean} [options.includeCore=true] - Whether or not to include core modules in the dependency list
- * @param {Object} [options.fileSystem=undefined] - An alternative fs implementation to use for reading the file path.
- * @param {Record<string, any>} [options.walker] - Options to pass to node-source-walk
- * @return {String[]}
+ * @param {string} filename
+ * @param {PaperworkOptions} [options]
+ * @return {string[]}
  */
 precinct.paperwork = (filename, options = {}) => {
   options = { includeCore: true, ...options };
@@ -137,6 +144,10 @@ precinct.paperwork = (filename, options = {}) => {
   return dependencies;
 };
 
+/**
+ * @param {string} type
+ * @param {PrecinctOptions} options
+ */
 function getDetective(type, options) {
   const mixedMode = options.es6?.mixedImports;
 
@@ -193,11 +204,15 @@ function getDetective(type, options) {
   }
 }
 
+/**
+ * @param {Record<string, any>} ast
+ * @param {Record<string, any>} [detectiveOptions]
+ */
 function detectiveEs6Cjs(ast, detectiveOptions) {
   return [
     ...detectiveEs6(ast, detectiveOptions),
     ...detectiveCjs(ast, detectiveOptions)
   ];
 }
 
-module.exports = precinct;
+export default precinct;