Generate types from JSDoc

package.json

@@ -12,6 +12,7 @@
     "traverse": "^0.6.6"
   },
   "devDependencies": {
+    "abstract-level": "^1.0.3",
     "assert": "^2.0.0",
     "buffer": "^6.0.3",
     "diacritic": "^0.0.2",
@@ -24,14 +25,16 @@
     "stream-browserify": "^3.0.0",
     "tape": "^5.3.1",
     "tape-run": "^9.0.0",
+    "typescript": "^4.7.4",
     "webpack": "^5.62.2",
     "webpack-cli": "^4.9.1",
     "world-bank-dataset": "^1.0.0"
   },
   "scripts": {
     "build": "npm run empty-sandbox && webpack",
+    "types": "tsc",
     "empty-sandbox": "rm -rf test/sandbox && mkdir test/sandbox",
-    "lint": "standard --fix test/src/*.js src/*",
+    "lint": "standard --fix test/src/*.js src/*.js",
     "test": "npm run test-node && npm run test-browser && npm run lint",
     "test-browser": "npm run build && cat test/sandbox/browser-tests.js | tape-run",
     "test-node": "npm run empty-sandbox && tape test/src/*.js",

src/browser.d.ts

@@ -0,0 +1,7 @@
+export = browser;
+/**
+ * Creates an inverted index using [`BrowserLevel`](https://github.com/Level/browser-level)
+ * @param {import("./main.js").FiiOptions} [ops] Options
+ * @returns {Promise<import("./main").Fii>}
+ */
+declare function browser(ops?: import("./main.js").FiiOptions): Promise<import("./main").Fii>;

src/browser.js

@@ -1,7 +1,12 @@
 const fii = require('./main.js')
 const { BrowserLevel } = require('browser-level')
 
-module.exports = ops =>
+/**
+ * Creates an inverted index using [`BrowserLevel`](https://github.com/Level/browser-level)
+ * @param {import("./main.js").FiiOptions} [ops] Options
+ * @returns {Promise<import("./main").Fii>}
+ */
+const browser = ops =>
   fii(
     Object.assign(
       {
@@ -10,3 +15,5 @@ module.exports = ops =>
       ops
     )
   )
+
+module.exports = browser

src/main.d.ts

@@ -0,0 +1,80 @@
+export = main;
+/**
+ * Creates and intializes index
+ * @param {FiiOptions} [ops] Options
+ */
+declare function main(ops?: FiiOptions): Promise<Fii>;
+declare namespace main {
+    export { AbstractLevelConstructor, FiiOptions, InitializedOptions, OR, Fii };
+}
+/**
+ * Fii options
+ */
+type FiiOptions = {
+    /**
+     * Name of database
+     */
+    name?: string;
+    /**
+     * Constructor of `class` extending [`abstract-level`](https://github.com/Level/abstract-level)
+     */
+    db?: AbstractLevelConstructor;
+    /**
+     * Creates 'comment' spaces in tokens.
+     * For example using `#` allows tokens like `boom#1.00` to be retrieved by using `boom`.
+     * If `tokenAppend` wasnt used, then `{gte: 'boom', lte: 'boom'}` would also return stuff like `boomness#1.00` etc
+     */
+    tokenAppend?: string;
+    /**
+     * Sets case sensitivity of the index
+     */
+    caseSensitive?: boolean;
+    /**
+     * Array of stop words to be stripped using [`stopword`](https://github.com/fergiemcdowall/stopword)
+     */
+    stopwords?: string[];
+    /**
+     * Array of fields not to index
+     */
+    doNotIndexField?: string[];
+    storeVectors?: boolean;
+    /**
+     * Field used to verify that doc exists
+     */
+    docExistsSpace?: string;
+};
+type Fii = {
+    AGGREGATION_FILTER: import("./read.js").AGGREGATION_FILTER;
+    AGGREGATE: import("./read.js").AGGREGATE;
+    AND: import("./read.js").AND;
+    BUCKET: import("./read.js").BUCKET;
+    BUCKETS: import("./read.js").BUCKETS;
+    CREATED: import("./read.js").CREATED;
+    DELETE: import("./write.js").DELETE;
+    DISTINCT: import("./read.js").DISTINCT;
+    EXIST: import("./read.js").EXIST;
+    EXPORT: import("./read.js").EXPORT;
+    FACETS: import("./read.js").FACETS;
+    FIELDS: import("./read.js").FIELDS;
+    GET: import("./read.js").GET;
+    IMPORT: import("./write.js").IMPORT;
+    LAST_UPDATED: import("./read.js").LAST_UPDATED;
+    MAX: import("./read.js").MAX;
+    MIN: import("./read.js").MIN;
+    NOT: import("./read.js").NOT;
+    OBJECT: import("./read.js").OBJECT;
+    OR: OR;
+    PUT: import("./write.js").PUT;
+    SORT: import("./read.js").SORT;
+    STORE: import("abstract-level/types/abstract-level.js").AbstractLevel<any, string, string>;
+    TIMESTAMP_LAST_UPDATED: import("./write.js").TIMESTAMP_LAST_UPDATED;
+    parseToken: import("./parseToken.js").PARSE;
+};
+type AbstractLevelConstructor = new <K, V>(name: string, options?: import("abstract-level").AbstractDatabaseOptions<K, V>) => import("abstract-level/types/abstract-level.js").AbstractLevel<any, K, V>;
+type InitializedOptions = {
+    _db: import("abstract-level/types/abstract-level.js").AbstractLevel<any, string, string>;
+};
+/**
+ * Returns objects that match one or more of the query clauses
+ */
+type OR = (tokens: import("./parseToken.js").Token[], pipeline?: import("./read.js").AlterToken) => Promise<import("./read.js").QueryObject[]>;

src/main.js

@@ -1,10 +1,75 @@
 const charwise = require('charwise')
-// const level = require('level')
+
+/**
+ * @typedef {{new<K, V>(name: string, options?: import("abstract-level").AbstractDatabaseOptions<K, V>): import("abstract-level").AbstractLevel<any, K, V>}} AbstractLevelConstructor
+ */
+
+/**
+ * Fii options
+ * @typedef {Object} FiiOptions
+ * @property {string} [name="fii"] Name of database
+ * @property {AbstractLevelConstructor} [db] Constructor of `class` extending [`abstract-level`](https://github.com/Level/abstract-level)
+ * @property {string} [tokenAppend=""] Creates 'comment' spaces in tokens.
+ * For example using `#` allows tokens like `boom#1.00` to be retrieved by using `boom`.
+ * If `tokenAppend` wasnt used, then `{gte: 'boom', lte: 'boom'}` would also return stuff like `boomness#1.00` etc
+ * @property {boolean} [caseSensitive=true] Sets case sensitivity of the index
+ * @property {string[]} [stopwords=[]] Array of stop words to be stripped using [`stopword`](https://github.com/fergiemcdowall/stopword)
+ * @property {string[]} [doNotIndexField=[]] Array of fields not to index
+ * @property {boolean} [storeVectors=true]
+ * @property {string} [docExistsSpace="DOC"] Field used to verify that doc exists
+ */
+
+/**
+ * @typedef {{_db: import("abstract-level").AbstractLevel}} InitializedOptions
+ */
+
+/**
+ * Returns objects that match one or more of the query clauses
+ * @callback OR
+ * @param {import("./parseToken.js").Token[]} tokens
+ * @param {import("./read.js").AlterToken} [pipeline]
+ * @returns {Promise<import("./read.js").QueryObject[]>}
+ */
+
+/**
+ * @typedef {Object} Fii
+ * @property {import("./read.js").AGGREGATION_FILTER} AGGREGATION_FILTER
+ * @property {import("./read.js").AGGREGATE} AGGREGATE
+ * @property {import("./read.js").AND} AND
+ * @property {import("./read.js").BUCKET} BUCKET
+ * @property {import("./read.js").BUCKETS} BUCKETS
+ * @property {import("./read.js").CREATED} CREATED
+ * @property {import("./write.js").DELETE} DELETE
+ * @property {import("./read.js").DISTINCT} DISTINCT
+ * @property {import("./read.js").EXIST} EXIST
+ * @property {import("./read.js").EXPORT} EXPORT
+ * @property {import("./read.js").FACETS} FACETS
+ * @property {import("./read.js").FIELDS} FIELDS
+ * @property {import("./read.js").GET} GET
+ * @property {import("./write.js").IMPORT} IMPORT
+ * @property {import("./read.js").LAST_UPDATED} LAST_UPDATED
+ * @property {import("./read.js").MAX} MAX
+ * @property {import("./read.js").MIN} MIN
+ * @property {import("./read.js").NOT} NOT
+ * @property {import("./read.js").OBJECT} OBJECT
+ * @property {OR} OR
+ * @property {import("./write.js").PUT} PUT
+ * @property {import("./read.js").SORT} SORT
+ * @property {import("abstract-level").AbstractLevel} STORE
+ * @property {import("./write.js").TIMESTAMP_LAST_UPDATED} TIMESTAMP_LAST_UPDATED
+ * @property {import("./parseToken.js").PARSE} parseToken
+ */
+
 const read = require('./read.js')
 const write = require('./write.js')
 
 // _match is nested by default so that AND and OR work correctly under
 // the bonnet. Flatten array before presenting to consumer
+/**
+ * 
+ * @param {import("./read.js").QueryObject[]} [results] 
+ * @returns {import("./read.js").QueryObject[]} Flattened and sorted results
+ */
 const flattenMatchArrayInResults = results =>
   typeof results === 'undefined'
     ? undefined
@@ -25,23 +90,23 @@ const flattenMatchArrayInResults = results =>
       return result
     })
 
+/**
+ * Initializes store
+ * @template {FiiOptions} O FiiOptions
+ * @param {O} [ops={}] Options
+ * @returns {Promise<O & InitializedOptions}>
+ */
 const initStore = (ops = {}) =>
   new Promise((resolve, reject) => {
     ops = Object.assign(
       {
         name: 'fii',
-        // TODO: is tokenAppens still needed?
-        // tokenAppend can be used to create 'comment' spaces in
-        // tokens. For example using '#' allows tokens like boom#1.00 to
-        // be retrieved by using "boom". If tokenAppend wasnt used, then
-        // {gte: 'boom', lte: 'boom'} would also return stuff like
-        // boomness#1.00 etc
         tokenAppend: '',
         caseSensitive: true,
         stopwords: [],
         doNotIndexField: [],
         storeVectors: true,
-        docExistsSpace: 'DOC' // field used to verify that doc exists
+        docExistsSpace: 'DOC'
       },
       ops
     )
@@ -56,7 +121,12 @@ const initStore = (ops = {}) =>
     )
   })
 
-const makeAFii = ops => {
+/**
+ * Creates an inverted index
+ * @param {FiiOptions & InitializedOptions} [ops={}] Options
+ * @returns {Promise<Fii>}
+ */
+const makeAFii = async (ops) => {
   const r = read(ops)
   const w = write(ops)
 
@@ -73,14 +143,14 @@ const makeAFii = ops => {
     EXPORT: r.EXPORT,
     FACETS: r.FACETS,
     FIELDS: r.FIELDS,
-    GET: (tokens, pipeline) =>
-      r.GET(tokens, pipeline).then(flattenMatchArrayInResults),
+    GET: (token, pipeline) =>
+      r.GET(token, pipeline).then(flattenMatchArrayInResults),
     IMPORT: w.IMPORT,
     LAST_UPDATED: r.LAST_UPDATED,
     MAX: r.MAX,
     MIN: r.MIN,
-    NOT: (...keys) =>
-      r.SET_SUBTRACTION(...keys).then(flattenMatchArrayInResults),
+    NOT: (a, b) =>
+      r.SET_SUBTRACTION(a, b).then(flattenMatchArrayInResults),
     OBJECT: r.OBJECT,
     OR: (tokens, pipeline) =>
       r
@@ -95,4 +165,10 @@ const makeAFii = ops => {
   }))
 }
 
-module.exports = ops => initStore(ops).then(makeAFii)
+/**
+ * Creates and intializes index
+ * @param {FiiOptions} [ops] Options
+ */
+const main = ops => initStore(ops).then(makeAFii)
+
+module.exports = main

src/node.d.ts

@@ -0,0 +1,7 @@
+export = node;
+/**
+ * Creates an inverted index using [`ClassicLevel`](https://github.com/Level/classic-level)
+ * @param {import("./main.js").FiiOptions} [ops] Options
+ * @returns {Promise<import("./main").Fii>}
+ */
+declare function node(ops?: import("./main.js").FiiOptions): Promise<import("./main").Fii>;

src/node.js

@@ -1,7 +1,12 @@
 const fii = require('./main.js')
 const { ClassicLevel } = require('classic-level')
 
-module.exports = ops =>
+/**
+ * Creates an inverted index using [`ClassicLevel`](https://github.com/Level/classic-level)
+ * @param {import("./main.js").FiiOptions} [ops] Options
+ * @returns {Promise<import("./main").Fii>}
+ */
+const node = ops =>
   fii(
     Object.assign(
       {
@@ -10,3 +15,5 @@ module.exports = ops =>
       ops
     )
   )
+
+module.exports = node