Merge pull request #11 from serpapi/widen-node-support

Support Node.js 7 and higher

Author: zyc9012

.github/workflows/build.yml

@@ -4,6 +4,7 @@ on: push
 
 jobs:
   build:
+    name: "Deno tests and build npm files"
     runs-on: ubuntu-22.04
     steps:
       - name: Checkout repo
@@ -28,8 +29,84 @@ jobs:
       - name: Setup Node
         uses: actions/setup-node@v3
         with:
-          node-version: '18.x'
+          node-version: '18.x'  # Build files using a fixed node version
           registry-url: 'https://registry.npmjs.org'
 
-      - name: Test building of npm files
+      - name: Build npm files
         run: deno task npm
+
+      - name: Zip build files
+        run: zip npm.zip ./npm -r
+
+      - name: Upload build files for smoke tests
+        uses: actions/upload-artifact@v3
+        with:
+          name: npm
+          path: npm.zip
+          retention-days: 1
+
+  smoke-tests-commonjs:
+    name: "Smoke tests (CommonJS)"
+    needs: build
+    runs-on: ubuntu-22.04
+    strategy:
+      matrix:
+        node-version: [7.x, 8.x, 9.x, 10.x, 11.x, 12.x, 13.x, 14.x, 15.x, 16.x, 17.x, 18.x, 19.x]
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v3
+
+      - name: Setup Node
+        uses: actions/setup-node@v3
+        with:
+          node-version: ${{ matrix.node-version }}
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Download build files
+        uses: actions/download-artifact@v3
+        with:
+          name: npm
+
+      - name: Unzip build files
+        run: unzip npm.zip
+
+      - name: Run smoke tests
+        env:
+          SERPAPI_TEST_KEY: ${{ secrets.SERPAPI_TEST_KEY }}
+        run: |
+          cd smoke_tests/commonjs
+          npm i
+          npm test
+
+  smoke-tests-esm:
+    name: "Smoke tests (ESM)"
+    needs: build
+    runs-on: ubuntu-22.04
+    strategy:
+      matrix:
+        node-version: [14.x, 15.x, 16.x, 17.x, 18.x, 19.x]
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v3
+
+      - name: Setup Node
+        uses: actions/setup-node@v3
+        with:
+          node-version: ${{ matrix.node-version }}
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Download build files
+        uses: actions/download-artifact@v3
+        with:
+          name: npm
+
+      - name: Unzip build files
+        run: unzip npm.zip
+
+      - name: Run smoke tests
+        env:
+          SERPAPI_TEST_KEY: ${{ secrets.SERPAPI_TEST_KEY }}
+        run: |
+          cd smoke_tests/esm
+          npm i
+          npm test

CHANGELOG.md

@@ -11,7 +11,7 @@ and this project adheres to
 ### Added
 
 - Expose `EngineParameters` type.
-- Expose `InvalidArgumentTypesError` error.
+- Expose `InvalidArgumentError` error.
 
 ### Changed
 

CONTRIBUTING.md

@@ -26,7 +26,8 @@ If you use VSCode, use the following settings (`.vscode/settings.json`):
     "mod.ts",
     "version.ts",
     "src",
-    "tests",
+    "tests/*.ts",
+    "tests/engines/",
     "scripts",
     "examples/deno"
   ],
@@ -96,6 +97,39 @@ deno task test:cov     # Get test coverage by running tests that hit "localhost"
 deno task test:ci      # Run tests that hit "https://serpapi.com"
 ```
 
+## Run examples on local source files
+
+To run [examples](./examples/) on your local source files, follow these steps.
+
+1. Run `deno task npm` to build the files.
+2. Update the respective example's `package.json` to depend on the local
+   `serpapi` module instead,
+   ```json
+   {
+     "dependencies": {
+       "dotenv": "*",
+       "serpapi": "../../../npm"
+     },
+     "scripts": {
+       "start": "node example.js"
+     }
+   }
+   ```
+
+## Run smoke tests
+
+These test key functionality on different Node.js versions. They are ran on
+GitHub Actions, see the [build workflow](.github/workflows/build.yml) for more
+details.
+
+To run these locally, follow these steps.
+
+1. Run `deno task npm` to build the files.
+2. Change directory to either the `commonjs` or `esm` folder.
+3. Setup the intended Node.js version. For example, if you're using `nvm`, you
+   can run `nvm use 14` to run Node.js 14 for the current shell.
+4. Run `npm i`, then `npm test`.
+
 ## Update documentation
 
 - Every exposed function must have associated JSDoc comments.
@@ -112,7 +146,8 @@ deno task docs:gen
 TypeScript types are generated from the backend code. Follow these steps to
 update the types.
 
-1. Run `bundle exec rails sdk:generate_ts_types` in the backend repository.
+1. Run `bundle exec rails libraries:generate_ts_types` in the backend
+   repository.
 2. Replace everything in `src/engines` with the generated files from
    `tmp/ts/engines`.
 3. Update `mod.ts` with the new engine exports from `tmp/ts/mod.ts`.

README.md

@@ -17,12 +17,40 @@ more.
 
 ### Node.js
 
-Ensure you're running at least Node.js v16.14.
+- Supports Node.js 7.10.1 and newer.
+- Refer to [this example](examples/node/basic_js_node_7_up) for help.
 
 ```bash
 npm install serpapi
 ```
 
+```js
+const { getJson } = require("serpapi");
+getJson({
+  engine: "google",
+  api_key: API_KEY, // Get your API_KEY from https://serpapi.com/manage-api-key
+  q: "coffee",
+  location: "Austin, Texas",
+}, (json) => {
+  console.log(json["organic_results"]);
+});
+```
+
+### Node.js with ES Modules (ESM) and top-level await
+
+- If you prefer using the `import` syntax and top-level `await`, you need to use
+  at least Node.js 14.8.0.
+- Refer to [this example](examples/node/basic_js_node_14_up) for help.
+
+You will need to add `"type": "module"` to your `package.json`:
+
+```js
+{
+  "type": "module",
+  // rest of package.json
+}
+```
+
 ```js
 import { getJson } from "serpapi";
 const response = await getJson({
@@ -36,7 +64,9 @@ console.log(response);
 
 ### Deno
 
-Import directly from deno.land. Usage is otherwise the same as above.
+- Import directly from deno.land.
+- Usage is otherwise the same as above.
+- Refer to [this example](examples/deno/basic_ts) for help.
 
 ```ts
 import { getJson } from "https://deno.land/x/serpapi/mod.ts";

deno.json

@@ -9,12 +9,24 @@
   },
   "fmt": {
     "files": {
-      "exclude": ["npm/", "examples/node"]
+      "exclude": ["npm/", "examples/node", "smoke_tests/"]
     }
   },
   "lint": {
     "files": {
-      "exclude": ["npm/", "examples/node"]
+      "exclude": ["npm/", "examples/node", "smoke_tests/"]
     }
+  },
+  "test": {
+    "files": {
+      "include": ["tests/"]
+    }
+  },
+  "compilerOptions": {
+    "lib": [
+      "dom",
+      "dom.iterable",
+      "deno.ns"
+    ]
   }
 }

docs/migrating_from_google_search_results_nodejs.md

@@ -51,8 +51,6 @@ migrate over to the `serpapi` npm package.
 - The `buildUrl`, `execute` and `search` methods are removed. Use `getJson` and
   `getHtml` functions instead.
 - The `SerpApiSearch` class is removed as a public class.
-- Dropped support for Node.js 16.13 and below. This module supports Node.js
-  16.14 and above.
 
 ## Fixed
 

examples/node/basic_js_commonjs/README.md

@@ -0,0 +1,15 @@
+# Basic JavaScript example for Node.js 14 and newer
+
+## Usage
+
+1. Setup environment variables
+
+- Duplicate `.env.example` and name it `.env`.
+- Replace `YOUR_API_KEY` with your SerpApi API key.
+
+2. Install dependencies and run example
+
+```bash
+npm i
+npm start
+```