feat: add type annotations, new solr functions

BREAKING CHANGE: From now on,  the `core` parameter needs
to be passed through the `config` parameter. This simplifies
the API by removing special cases.
The provided typings provide better user experience when developing
in an IDE such as vscode.

Author: vsimko

.eslintrc

@@ -1,12 +1,10 @@
 {
-  "extends": [
-    "standard"
-  ],
+  "extends": ["standard"],
   "env": {
     "mocha": true
   },
   "rules": {
     "indent": "off",
     "quotes": ["error", "double"]
   }
-}
+}

src/index.js

@@ -1,46 +1,64 @@
+// @ts-check
+/**
+ * @typedef {typeof defaultConfig} SolrConfig
+ * @typedef {import(".").SolrDocument} SolrDocument
+ * @typedef {import(".").SolrData} SolrData
+ * @typedef {import(".").SolrResponse} SolrResponse
+ * @typedef {import("axios").AxiosError} AxiosError
+ * @typedef {import(".").SolrException} SolrException
+ */
+
 const url = require("url")
-const axios = require("axios")
+const { default: axios } = require("axios")
 
 const defaultConfig = {
   hostname: "localhost",
   port: 8983,
-  protocol: "http"
+  protocol: "http",
+  debug: false,
+  core: "",
+  apiPrefix: "api/cores"
 }
 
-const ensureArray = x => (x instanceof Array ? x : [x])
-
-const solrPost = config => path => (data, coreOpt = "") => {
-  const core = coreOpt || config.core
-  if (!core) {
-    throw new Error("core not specified")
-  }
+/** @type {(x:object) => object|object[]} */
+const ensureArray = x => (Object(x) instanceof Array ? x : [x])
 
+/**
+ * @type {(config:SolrConfig) => (path:string) => (data:SolrData) => Promise<SolrResponse>}
+ */
+const solrPost = config => path => async data => {
+  const { core, apiPrefix } = config
   const solrUrl = url.format({
     ...defaultConfig,
     ...config, // overrides defalt config
-    pathname: `solr/${core}/${path}`,
+    pathname: `${apiPrefix}/${core}/${path}`,
     query: {
       wt: "json",
       overwrite: true,
       commitWithin: 1000
     }
   })
 
-  return axios
-    .post(solrUrl, ensureArray(data), {
-      headers: {
-        "content-type": "application/json; charset=utf-8",
-        accept: "application/json; charset=utf-8"
-      }
-    })
-    .then(r => r.data)
+  if (config.debug) {
+    console.debug(`\n$ curl '${solrUrl}' -d '${JSON.stringify(data)}'\n`)
+  }
+
+  const response = await axios.post(solrUrl, data, {
+    headers: {
+      "content-type": "application/json; charset=utf-8",
+      accept: "application/json; charset=utf-8"
+    }
+  })
+
+  return response.data
 }
 
-const solrGet = config => path => (query = {}, coreOpt = "") => {
-  const core = coreOpt || query.core || config.core
-  if (!core) {
-    throw new Error("core not specified")
-  }
+/**
+ * @type {(config:SolrConfig) => (path:string) => (query:any) => Promise<SolrResponse>}
+ */
+const solrGet = config => path => async query => {
+  const core = query.core || config.core
+  const { apiPrefix } = config
 
   // we don't want to alter the query structure
   const queryWithoutCore = { ...query }
@@ -49,38 +67,73 @@ const solrGet = config => path => (query = {}, coreOpt = "") => {
   const solrUrl = url.format({
     ...defaultConfig,
     ...config, // overrides defalt config
-    pathname: `solr/${core}/${path}`,
-    query: queryWithoutCore // DO NOT rename the query parameter!
+    pathname: `${apiPrefix}/${core}/${path}`,
+    query: queryWithoutCore // DO NOT rename the "query" parameter!
   })
 
   if (config.debug) {
-    console.debug("SOLR QUERY:")
-    console.debug(query)
-    console.debug("SOLR HTTP GET: " + solrUrl)
+    console.debug(`\n$ curl '${solrUrl}'\n`)
   }
 
-  return axios(solrUrl).then(r => r.data)
+  const response = await axios(solrUrl)
+  return response.data
 }
 
+/**
+ * Perform an operation on solr schema.
+ * @see https://lucene.apache.org/solr/guide/7_5/schema-api.html#modify-the-schema
+ * @param {SolrConfig} config
+ */
+const solrSchema = config => op => data =>
+  solrPost(config)("schema")({ [op]: data })
+
+/** @param {SolrConfig} config */
 const prepareSolrClient = config => ({
+  ping: () =>
+    solrGet({ ...config, apiPrefix: "solr" })("admin/ping")({})
+      .then(value => {
+        return value.status === "OK"
+      })
+      .catch(() => false),
+
+  /**
+   * @param {SolrDocument} data */
+  add: data => solrPost(config)("update")(ensureArray(data)),
+
+  /**
+   * @type {(data: import(".").FieldProperties) => Promise<SolrResponse>}
+   * @see https://lucene.apache.org/solr/guide/7_5/schema-api.html#add-a-new-field
+   */
+  addField: solrSchema(config)("add-field"),
+
+  /**
+   * @type {(data:import(".").FieldTypeProperties) => Promise<SolrResponse>}
+   * @see https://lucene.apache.org/solr/guide/7_5/schema-api.html#add-a-new-field-type
+   */
+  addFieldType: solrSchema(config)("add-field-type"),
+
+  /**
+   * @type {({name:string}) => Promise<SolrResponse>}
+   */
+  deleteField: solrSchema(config)("delete-field"),
+
+  /**
+   * @type {({name:string}) => Promise<SolrResponse>}
+   */
+  deleteFieldType: solrSchema(config)("delete-field-type"),
+
+  /**
+   * @type {(query:import(".").SolrSelect) => Promise<SolrResponse>}
+   */
   select: solrGet(config)("select"),
-  ping: core => solrGet(config)("admin/ping")({ core }),
-  add: solrPost(config)("update"),
-  delete: () => Error("not implemented yet"),
-  commit: () => Error("not implemented yet"),
-  rollback: () => Error("not implemented yet"),
-  spell: () => Error("not implemented yet"),
-  optimize: () => Error("not implemented yet"),
-  realTimeGet: () => Error("not implemented yet"),
-  facet: (jsonFacet, coreOpt = "") =>
-    solrGet(config)("query")(
-      {
-        q: "*:*", // filtering will be implemented later
-        rows: 0,
-        "json.facet": JSON.stringify(jsonFacet)
-      },
-      coreOpt
-    )
+
+  facet: (facetMap, filterArr = []) =>
+    solrPost(config)("query")({
+      query: "*:*",
+      limit: "0",
+      filter: filterArr,
+      facet: facetMap
+    })
 })
 
 module.exports = {