Merge pull request #8 from serpapi/more-lenient-types

More lenient TypeScript types

Author: sebastianquek

CHANGELOG.md

@@ -10,9 +10,13 @@ and this project adheres to
 
 ### Added
 
+- Expose `EngineName`, `EngineParameters` and `AllowArbitraryParams` types.
+
 ### Changed
 
 - Remove `settings.json`, update CONTRIBUTING.md.
+- Make types more lenient so newly supported engines/parameters whose types have
+  not yet been updated do not throw warnings.
 
 ### Fixed
 

examples/deno/basic_ts/README.md

@@ -20,6 +20,7 @@ deno run example.ts
   following:
   ```ts
   import {
+    AllowArbitraryParams,
     config,
     getJson,
     GoogleParameters,

examples/deno/basic_ts/example.ts

@@ -1,11 +1,16 @@
 import { loadSync } from "https://deno.land/std@0.173.0/dotenv/mod.ts";
-import { config, getJson, GoogleParameters } from "../../../mod.ts";
+import {
+  AllowArbitraryParams,
+  config,
+  getJson,
+  GoogleParameters,
+} from "../../../mod.ts";
 
 const { API_KEY: apiKey } = loadSync();
 const params = {
   q: "Coffee",
   api_key: apiKey,
-} satisfies GoogleParameters;
+} satisfies AllowArbitraryParams<GoogleParameters>;
 
 // Show result as JSON (async/await)
 const response1 = await getJson("google", params);

examples/deno/pagination_ts/README.md

@@ -20,6 +20,7 @@ deno run example.ts
   following:
   ```ts
   import {
+    AllowArbitraryParams,
     config,
     getJson,
     GoogleParameters,

examples/deno/pagination_ts/example.ts

@@ -1,5 +1,10 @@
 import { loadSync } from "https://deno.land/std@0.173.0/dotenv/mod.ts";
-import { config, getJson, GoogleParameters } from "../../../mod.ts";
+import {
+  AllowArbitraryParams,
+  config,
+  getJson,
+  GoogleParameters,
+} from "../../../mod.ts";
 
 const { API_KEY: apiKey } = loadSync();
 
@@ -9,7 +14,7 @@ const extractLinks = (results: { link: string }[]) =>
 const params = {
   q: "Coffee",
   api_key: apiKey,
-} satisfies GoogleParameters;
+} satisfies AllowArbitraryParams<GoogleParameters>;
 
 // Pagination (async/await)
 let page1 = await getJson("google", params);

examples/node/basic_ts_esm/example.ts

@@ -1,13 +1,13 @@
 import * as Dotenv from "dotenv";
-import { config, getJson, GoogleParameters } from "serpapi";
+import { AllowArbitraryParams, config, getJson, GoogleParameters } from "serpapi";
 
 Dotenv.config();
 const apiKey = process.env.API_KEY;
 
 const params = {
   q: "Coffee",
   api_key: apiKey,
-} satisfies GoogleParameters;
+} satisfies AllowArbitraryParams<GoogleParameters>;
 
 // Show result as JSON (async/await)
 const response1 = await getJson("google", params);

examples/node/pagination_ts_esm/example.ts

@@ -1,5 +1,5 @@
 import * as Dotenv from "dotenv";
-import { config, getJson, GoogleParameters } from "serpapi";
+import { AllowArbitraryParams, config, getJson, GoogleParameters } from "serpapi";
 
 Dotenv.config();
 const apiKey = process.env.API_KEY;
@@ -10,7 +10,7 @@ const extractLinks = (results: { link: string }[]) =>
 const params = {
   q: "Coffee",
   api_key: apiKey,
-} satisfies GoogleParameters;
+} satisfies AllowArbitraryParams<GoogleParameters>;
 
 // Pagination (async/await)
 let page1 = await getJson("google", params);

mod.ts

@@ -6,8 +6,11 @@ export { InvalidTimeoutError, MissingApiKeyError } from "./src/errors.ts";
 export type {
   AccountApiParameters,
   AccountInformation,
+  AllowArbitraryParams,
   BaseParameters,
   BaseResponse,
+  EngineName,
+  EngineParameters,
   GetBySearchIdParameters,
   Location,
   Locations,

src/serpapi.ts

@@ -1,12 +1,14 @@
 import {
   AccountApiParameters,
   AccountInformation,
+  AllowArbitraryParams,
   BaseResponse,
+  EngineName,
+  EngineParameters,
   GetBySearchIdParameters,
   Locations,
   LocationsApiParameters,
 } from "./types.ts";
-import { EngineMap } from "./engines/engine_map.ts";
 import {
   _internals,
   execute,
@@ -69,11 +71,12 @@ const SEARCH_ARCHIVE_PATH = `/searches`;
  * });
  */
 export async function getJson<
-  E extends keyof EngineMap,
+  E extends EngineName = EngineName,
+  P extends AllowArbitraryParams<EngineParameters<E>> = EngineParameters<E>,
 >(
   engine: E,
-  parameters: EngineMap[E]["parameters"],
-  callback?: (json: BaseResponse<EngineMap[E]["parameters"]>) => void,
+  parameters: P,
+  callback?: (json: BaseResponse<E>) => void,
 ) {
   const key = validateApiKey(parameters.api_key, true);
   const timeout = validateTimeout(parameters.timeout);
@@ -87,9 +90,7 @@ export async function getJson<
     },
     timeout,
   );
-  const json = await response.json() as BaseResponse<
-    EngineMap[E]["parameters"]
-  >;
+  const json = await response.json() as BaseResponse<E>;
   const nextParametersFromResponse = extractNextParameters<E>(json);
   if (
     // https://github.com/serpapi/public-roadmap/issues/562
@@ -126,9 +127,12 @@ export async function getJson<
  * // callback
  * getHtml("google", { api_key: API_KEY, q: "coffee" }, console.log);
  */
-export async function getHtml<E extends keyof EngineMap>(
+export async function getHtml<
+  E extends EngineName = EngineName,
+  P extends AllowArbitraryParams<EngineParameters<E>> = EngineParameters<E>,
+>(
   engine: E,
-  parameters: EngineMap[E]["parameters"],
+  parameters: P,
   callback?: (html: string) => void,
 ) {
   const key = validateApiKey(parameters.api_key, true);

src/types.ts

@@ -1,3 +1,10 @@
+import { EngineMap } from "./engines/engine_map.ts";
+
+/**
+ * Allow arbitrary parameters in addition to parameters in T.
+ */
+export type AllowArbitraryParams<T> = T & Record<string, unknown>;
+
 export type BaseParameters = {
   /**
    * Parameter defines the device to use to get the results. It can be set to
@@ -39,7 +46,19 @@ export type BaseParameters = {
    */
   timeout?: number;
 };
-export type BaseResponse<P = Record<string | number | symbol, never>> = {
+
+// https://github.com/microsoft/TypeScript/issues/29729
+// deno-lint-ignore ban-types
+type AnyEngineName = string & {};
+export type EngineName = (keyof EngineMap) | AnyEngineName;
+export type EngineParameters<
+  E extends EngineName = EngineName,
+> = {
+  [K in E]: K extends keyof EngineMap ? EngineMap[K]["parameters"]
+    : BaseParameters & Record<string, unknown>;
+}[E];
+
+export type BaseResponse<E extends EngineName = EngineName> = {
   search_metadata: {
     id: string;
     status: "Queued" | "Processing" | "Success";
@@ -49,14 +68,15 @@ export type BaseResponse<P = Record<string | number | symbol, never>> = {
     raw_html_file: string;
     total_time_taken: number;
   };
-  search_parameters:
-    & { engine: string }
-    & Omit<BaseParameters & P, "api_key" | "no_cache" | "async" | "timeout">;
+  search_parameters: Omit<
+    EngineParameters<E>,
+    "api_key" | "no_cache" | "async" | "timeout"
+  >;
   serpapi_pagination?: { next: string };
   pagination?: { next: string };
   next?: (
-    callback?: (json: BaseResponse<P>) => void,
-  ) => Promise<BaseResponse<P>>;
+    callback?: (json: BaseResponse<E>) => void,
+  ) => Promise<BaseResponse<E>>;
   // deno-lint-ignore no-explicit-any
   [key: string]: any; // TODO(seb): use recursive type
 };