fix: resolve #414 — transform module in typescript?

package.json

@@ -8,6 +8,7 @@
   },
   "bugs": "https://github.com/facebook/jscodeshift/issues",
   "main": "index.js",
+  "types": "index.d.ts",
   "scripts": {
     "clean": "rm -rf dist/",
     "prepare": "yarn clean && cp -R src/ dist/",

src/Collection.js

@@ -14,7 +14,7 @@ const recast = require('recast');
 const union = require('./utils/union');
 
 const astTypes = recast.types;
-var types = astTypes.namedTypes;
+const types = astTypes.namedTypes;
 const NodePath = astTypes.NodePath;
 const Node = types.Node;
 

src/core.js

@@ -18,6 +18,22 @@ const template = require('./template');
 const Node = recast.types.namedTypes.Node;
 const NodePath = recast.types.NodePath;
 
+/**
+ * @namespace JSCodeshift
+ * @description
+ * The jscodeshift API available in transform functions. This object is passed
+ * as the first argument to transform functions and provides methods for
+ * working with the AST.
+ * @property {Object} types - The ast-types library (recast.types)
+ * @property {Function} registerMethods - Register collection methods
+ * @property {Function} match - Utility function to match a node against a pattern
+ * @property {Function} template - Template literal compiler for generating AST nodes
+ * @property {Object} filters - Filters for collection types
+ * @property {Object} mappings - Mappings for collection types
+ * @property {Function} use - Register a plugin
+ * @property {Function} withParser - Create a jscodeshift instance bound to a specific parser
+ */
+
 // Register all built-in collections
 for (var name in collections) {
   collections[name].register();

src/matchNode.js

@@ -16,7 +16,7 @@ const hasOwn =
  *
  * @param {*} haystack Value to test.
  * @param {*} needle Test function or value to look for in `haystack`.
- * @return {bool}
+ * @return {boolean}
  */
 function matchNode(haystack, needle) {
   if (typeof needle === 'function') {
@@ -33,6 +33,10 @@ function matchNode(haystack, needle) {
   return haystack === needle;
 }
 
+/**
+ * @param {*} value
+ * @return {boolean}
+ */
 function isNode(value) {
   return typeof value === 'object' && value;
 }

types.d.ts

@@ -0,0 +1,150 @@
+import { Node, File } from '@babel/types';
+
+/**
+ * Transform function signature
+ */
+export type JSTransformSource = (
+  source: string | undefined,
+  api: JSCodeshift,
+  options: TransformOptions
+) => string | undefined | null;
+
+/**
+ * Options passed to the transform function
+ */
+export interface TransformOptions {
+  [key: string]: any;
+}
+
+/**
+ * Core jscodeshift API
+ */
+export interface JSCodeshift {
+  (source: string | undefined, options?: object): Collection;
+  withParser(parserName: string): JSCodeshift;
+  withTemplates(templatePaths: string[], options?: object): JSCodeshift;
+  defineTemplateCodeLocations(templateCode: string[], filePath: string): void;
+}
+
+/**
+ * jscodeshift Collection interface
+ */
+export interface Collection {
+  nodes<T = any>(): Collection;
+  size(): number;
+  length: number;
+  forEach(
+    callback: (node: Node | File, index: number, collection: Collection) => void
+  ): Collection;
+  map<T>(callback: (node: Node | File, index: number) => T): T[];
+  filter(
+    predicate: (node: Node | File, index: number) => boolean
+  ): Collection;
+  find<T = any>(predicate: T | ((node: Node) => boolean)): Collection;
+  at(index: number | number[]): Collection;
+  first(): Collection;
+  last(): Collection;
+  get(): Node | File | undefined;
+  get(index: number): Node | File | undefined;
+  toArray(): (Node | File)[];
+  prune(): Collection;
+  replaceWith(
+    node: Node | File | ((node: Node | File) => Node | File)
+  ): Collection;
+  remove(): Collection;
+  insertAfter(node: Node | File): Collection;
+  insertBefore(node: Node | File): Collection;
+  appendToMemberExpression(memberObject: Node): Collection;
+  getSiblingCollection(): Collection;
+  getMostImmediateParent(): Collection;
+}
+
+/**
+ * Parser interface for AST parsing
+ */
+export interface Parser {
+  parse(source: string, options?: object): File;
+}
+
+/**
+ * Options for building/compiling code
+ */
+export interface BuildOptions {
+  source?: string;
+  path?: string;
+  sourceFileName?: string;
+  printOptions?: object;
+}
+
+/**
+ * Options for printing/formatting code
+ */
+export interface PrintOptions {
+  source: string;
+  sourceFileName?: string;
+  parser?: string;
+  printOptions?: object;
+}
+
+/**
+ * API object passed to transform functions
+ */
+export interface JSCodeshiftAPI {
+  jscodeshift: JSCodeshift;
+  jscodeshift: JSCodeshift;
+  stats: (message?: string) => void;
+  report: (msg: string) => void;
+}
+
+/**
+ * Execute options
+ */
+export interface ExecuteOptions extends TransformOptions {
+  extensions?: string[];
+  jscodeshift?: object;
+  babelOptions?: object;
+  parser?: string;
+  dry?: boolean;
+  print?: boolean;
+}
+
+/**
+ * Execute result type
+ */
+export type ExecuteResult = Promise<{ [key: string]: string }>;
+
+/**
+ * Wrapper function type for async transforms
+ */
+export interface JSCodeshiftWrapper {
+  (
+    transform:
+      | ((source: string, api: JSCodeshiftAPI, options: TransformOptions) => any)
+      | { default: (source: string, api: JSCodeshiftAPI, options: TransformOptions) => any },
+    options?: TransformOptions
+  ): ExecuteResult;
+}
+
+declare module 'jscodeshift' {
+  export const transformer: (
+    transformArg: string | JSTransformSource | object,
+    options: object
+  ) => any;
+  export const parse: Parser;
+  export const execute: (
+    transformArg: string | Function | object,
+    options?: object
+  ) => ExecuteResult;
+
+  export default {
+    transformer: (
+      transformArg: string | JSTransformSource | object,
+      options: object
+    ) => any,
+    parse: Parser,
+    execute: (
+      transformArg: string | Function | object,
+      options?: object
+    ) => ExecuteResult,
+  };
+}