feat(modules): build (true) esm, (interop) cjs modules; tests/readme

.circleci/config.yml

@@ -9,7 +9,9 @@ jobs:
   build:
     docker:
       # https://circleci.com/developer/images/image/cimg/node
-      - image: cimg/node:12.22.1
+      #- image: cimg/node:12.22.1
+      #- currently we need this for dynamic import in module tests, ONLY.
+      - image: cimg/node:14.16.1
 
       # Specify service dependencies here if necessary
       # CircleCI maintains a library of pre-built images
@@ -52,4 +54,7 @@ jobs:
       - codecov/upload:
           file: './coverage/coverage-final.json'
 
+      - run: yarn build
+      - run: yarn test:build
+
       - run: yarn semantic-release

.gitignore

@@ -1,3 +1,4 @@
 /node_modules
 /coverage
 /dist
+/api

README.md

@@ -43,8 +43,12 @@ $ yahoo-finance search AAPL '{ "someOption": true }'
 **Importing**
 
 ```js
+// import syntax (recommended)
 import yahooFinance from 'yahoo-finance2';
 
+// require syntax (if your code base does not support imports)
+const yahooFinance = require('yahoo-finance2').default; // NOTE the .default
+
 const results = await yahooFinance.search('AAPL');
 const results = await yahooFInance.search('AAPL', { someOption: true, etc });
 ```
@@ -81,6 +85,39 @@ const quote = await yahooFinance.quote('AAPL');
 const { regularMarketPrice as price, currency } = quote;
 ```
 
+## NB: CommonJS / ES modules
+
+This package is shipped as **both an ES Module and a CommonJS module**.  Node will
+*automatically* load the ES module if:
+
+* *Your* `package.json` contains a `{ type: module }` entry
+* You're running at least Node 12.
+* You `import` the module (`require` function does not exist in ES modules)
+
+otherwise the traditional CommonJS module will be loaded.  Note, for ES modules,
+and depending on your node version, you may need some extra flags:
+
+```bash
+# As environment variables
+NODE_OPTIONS="--experimental-vm-modules --experimental-json-modules"
+
+# Or as command line options
+node --experimental-vm-modules --experimental-json-modules [...]
+```
+
+ES Modules are "relatively" new.  They got a big boost in April 2021 when
+Node 10, which did not support them, reached end-of-life.  However, support
+varies by build tool and configuration, and there are some edge cases which
+can be tricky.  Please open an issue if you run into any trouble.
+
+**require (CommonJS)**
+
+If you use load the library with `require`, make sure to add `.default`:
+
+```js
+const yahooFinance = require('yahoo-finance2').default; // NOTE the .default
+```
+
 ## (Optional) TypeScript Love
 
 Working with `yahoo-finance2` is a joy if you're using TypeScript (but you

bin/schema-tweak.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
-const fs = require("fs");
-const schemaWalker = require("oas-schema-walker");
+import fs from "fs";
+import schemaWalker from "oas-schema-walker";
 
 const chunks = [];
 process.stdin.on("readable", () => {

bin/yahoo-finance.js

@@ -1,6 +1,6 @@
-#!/usr/bin/env node
+#!/usr/bin/env -S node --experimental-json-modules --experimental-vm-modules
 
-const yahooFinance = require("../api/index-node.js").default;
+import yahooFinance from "../dist/esm/src/index-node.js";
 const moduleNames = Object.keys(yahooFinance).filter((n) => !n.startsWith("_"));
 
 const node = process.argv[0];

jest.config.ts

@@ -0,0 +1,30 @@
+import type { Config } from "@jest/types";
+
+const config: Config.InitialOptions = {
+  preset: "ts-jest/presets/default-esm",
+  setupFilesAfterEnv: ["<rootDir>/tests/setupTests.js"],
+  testEnvironment: "node",
+  testPathIgnorePatterns: [
+    "/node_modules/",
+    "/dist/",
+    "/api/",
+    "/tests-modules/",
+  ],
+  extensionsToTreatAsEsm: [".ts"],
+  globals: {
+    "ts-jest": {
+      useESM: true,
+    },
+  },
+  moduleNameMapper: {
+    "(.*)\\.js$": "$1",
+  },
+  /*
+  reporters: [
+    '<rootDir>/tests/reporter.js',
+    '<rootDir>/tests/summary-reporter.js',
+  ],
+  */
+};
+
+export default config;

package.json

@@ -2,9 +2,15 @@
   "name": "yahoo-finance2",
   "version": "0.0.1",
   "description": "JS API for Yahoo Finance",
-  "main": "api/index-node.js",
-  "types": "api/index-node.d.ts",
-  "browser": "api/index-browser.js",
+  "type": "module",
+  "module": "./dist/esm/src/index-node.js",
+  "main": "./dist/cjs/src/index-node.js",
+  "exports": {
+    "import": "./dist/esm/src/index-node.js",
+    "default": "./dist/cjs/src/index-node.js"
+  },
+  "types": "./dist/esm/src/index-node.d.ts",
+  "browser": "./dist/esm/src/index-browser.js",
   "repository": "https://github.com/gadicc/node-yahoo-finance2",
   "author": "Gadi Cohen <[email protected]>",
   "license": "MIT",
@@ -22,20 +28,32 @@
     "client",
     "library"
   ],
+  "//engines//UNCOMMENT_WHEN_WE_DROP_CJS_SUPPORT": {
+    "node": ">=12.17.0",
+    "//node2": "we need 14.x for dynamic imports -- JUST FOR FETCH_DEVEL()!  think about this.",
+    "node2": ">=14.0.0"
+  },
   "bin": {
     "yahoo-finance": "bin/yahoo-finance.js"
   },
   "scripts": {
     "coverage": "jest --coverage",
     "lint": "eslint . --ext .js,.ts",
     "schema": "ts-json-schema-generator -f tsconfig.json -p 'src/{modules,typings}/**/*.ts' -t '*' | node bin/schema-tweak.js > schema.json",
+    "build": "yarn run build:esm && yarn run build:cjs",
+    "build:esm": "tsc --module es2020 --outDir dist/esm",
+    "build:cjs": "tsc --module commonjs --outDir dist/cjs && sed -i 's/\"type\": \"module\",/\"type:\": \"commonjs\",/' dist/cjs/package.json",
     "generateSchema": "yarn schema",
-    "prepublishOnly": "tsc && yarn generateSchema",
-    "test": "jest",
-    "test:ts": "tsc --noEmit"
+    "prepublishOnly": "yarn build && yarn generateSchema",
+    "test": "node --experimental-vm-modules node_modules/.bin/jest",
+    "test:ts": "tsc --noEmit",
+    "test:esm": "node --experimental-vm-modules node_modules/.bin/jest -c tests-modules/esm/jest.config.js tests-modules/esm/tests/*",
+    "test:cjs": "node node_modules/.bin/jest -c tests-modules/cjs/jest.config.js tests-modules/cjs/tests/*",
+    "test:modules": "yarn test:esm && yarn test:cjs",
+    "test:build": "yarn test:modules"
   },
   "files": [
-    "api",
+    "dist",
     "schema.json"
   ],
   "dependencies": {
@@ -52,18 +70,20 @@
     "@semantic-release/release-notes-generator": "9.0.2",
     "@tsconfig/node12": "1.0.7",
     "@types/jest": "26.0.23",
+    "@types/node-fetch": "^2.5.10",
     "@typescript-eslint/eslint-plugin": "4.22.1",
     "@typescript-eslint/parser": "4.22.1",
     "eslint": "7.26.0",
     "eslint-config-prettier": "8.3.0",
     "globby": "11.0.3",
-    "jest": "26.6.3",
+    "jest": "v27.0.0-next.8",
     "jest-tobetype": "1.2.3",
     "oas-schema-walker": "1.1.5",
     "prettier": "2.2.1",
     "semantic-release": "17.4.2",
-    "ts-jest": "26.5.6",
+    "ts-jest": "27.0.0-next.11",
     "ts-json-schema-generator": "0.92.0",
+    "ts-node": "^9.1.1",
     "typescript": "4.2.4"
   }
 }

schema.json

@@ -2,6 +2,28 @@
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$comment": "DO NOT EDIT THIS FILE.  It is generated automatically from typescript interfaces in the project.  To update, run `yarn schema`.",
   "definitions": {
+    "*": {
+      "additionalProperties": false,
+      "properties": {
+        "moduleOptions": {
+          "$ref": "#/definitions/ModuleOptions"
+        },
+        "query": {
+          "type": "string"
+        },
+        "queryOptionsOverrides": {
+          "$ref": "#/definitions/AutocOptions"
+        },
+        "this": {
+          "$ref": "#/definitions/ModuleThis"
+        }
+      },
+      "required": [
+        "this",
+        "query"
+      ],
+      "type": "object"
+    },
     "Action": {
       "enum": [
         "down",
@@ -1992,6 +2014,52 @@
       ],
       "type": "object"
     },
+    "ModuleOptions": {
+      "additionalProperties": false,
+      "properties": {
+        "devel": {
+          "type": [
+            "boolean",
+            "string"
+          ]
+        },
+        "fetchOptions": {
+          "type": "object"
+        },
+        "validateResult": {
+          "type": "boolean"
+        }
+      },
+      "type": "object"
+    },
+    "ModuleThis": {
+      "properties": {
+        "_moduleExec": {
+          "additionalProperties": false,
+          "properties": {
+            "arguments": {},
+            "caller": {
+              "$ref": "#/definitions/interface-731470504-9814-11278-731470504-0-212312"
+            },
+            "length": {
+              "yahooFinanceType": "number"
+            },
+            "prototype": {}
+          },
+          "required": [
+            "prototype",
+            "length",
+            "arguments",
+            "caller"
+          ],
+          "type": "object"
+        }
+      },
+      "required": [
+        "_moduleExec"
+      ],
+      "type": "object"
+    },
     "NetSharePurchaseActivity": {
       "additionalProperties": false,
       "properties": {
@@ -2416,7 +2484,7 @@
                 "properties": {
                   "arguments": {},
                   "caller": {
-                    "$ref": "#/definitions/interface-2073358172-9814-11278-2073358172-0-212312"
+                    "$ref": "#/definitions/interface-731470504-9814-11278-731470504-0-212312"
                   },
                   "length": {
                     "yahooFinanceType": "number"
@@ -2436,7 +2504,7 @@
                 "properties": {
                   "arguments": {},
                   "caller": {
-                    "$ref": "#/definitions/interface-2073358172-9814-11278-2073358172-0-212312"
+                    "$ref": "#/definitions/interface-731470504-9814-11278-731470504-0-212312"
                   },
                   "length": {
                     "yahooFinanceType": "number"
@@ -2456,7 +2524,7 @@
                 "properties": {
                   "arguments": {},
                   "caller": {
-                    "$ref": "#/definitions/interface-2073358172-9814-11278-2073358172-0-212312"
+                    "$ref": "#/definitions/interface-731470504-9814-11278-731470504-0-212312"
                   },
                   "length": {
                     "yahooFinanceType": "number"
@@ -6224,12 +6292,12 @@
       ],
       "type": "object"
     },
-    "interface-2073358172-9814-11278-2073358172-0-212312": {
+    "interface-731470504-9814-11278-731470504-0-212312": {
       "additionalProperties": false,
       "properties": {
         "arguments": {},
         "caller": {
-          "$ref": "#/definitions/interface-2073358172-9814-11278-2073358172-0-212312"
+          "$ref": "#/definitions/interface-731470504-9814-11278-731470504-0-212312"
         },
         "length": {
           "yahooFinanceType": "number"

src/env-node.ts

@@ -1,9 +1,10 @@
-const { URLSearchParams } = require("url");
-const fetch = require("node-fetch");
+import { URLSearchParams } from "url";
+import fetch from "node-fetch";
 
-function fetchDevel() {
-  // This let's us still only require the file if we need it, at runtime.
-  return require("./lib/fetchDevel");
+// This let's us still only require the file if we need it, at runtime.
+async function fetchDevel() {
+  const module = await import("./lib/fetchDevel.js");
+  return module.default;
 }
 
 export default {

src/index-browser.ts

@@ -1,5 +1,5 @@
-import yahooFinance from "./index-common";
-import browserEnvironment from "./env-browser";
+import yahooFinance from "./index-common.js";
+import browserEnvironment from "./env-browser.js";
 
 yahooFinance._env = browserEnvironment;
 

src/index-common.ts

@@ -1,20 +1,20 @@
 // libs
-import yahooFinanceFetch from "./lib/yahooFinanceFetch";
-import moduleExec from "./lib/moduleExec";
-import options from "./lib/options";
+import yahooFinanceFetch from "./lib/yahooFinanceFetch.js";
+import moduleExec from "./lib/moduleExec.js";
+import options from "./lib/options.js";
 
 // modules
-import autoc from "./modules/autoc";
-import historical from "./modules/historical";
-import quote from "./modules/quote";
-import quoteSummary from "./modules/quoteSummary";
-import search from "./modules/search";
-import recommendationsBySymbol from "./modules/recommendationsBySymbol";
-import trendingSymbols from "./modules/trendingSymbols";
-import optionsModule from "./modules/options";
+import autoc from "./modules/autoc.js";
+import historical from "./modules/historical.js";
+import quote from "./modules/quote.js";
+import quoteSummary from "./modules/quoteSummary.js";
+import search from "./modules/search.js";
+import recommendationsBySymbol from "./modules/recommendationsBySymbol.js";
+import trendingSymbols from "./modules/trendingSymbols.js";
+import optionsModule from "./modules/options.js";
 
 // other
-import quoteCombine from "./other/quoteCombine";
+import quoteCombine from "./other/quoteCombine.js";
 
 export default {
   // internal