feat(types): add typescript jsdoc to core

Author: posva

packages/@posva/vuefire-core/declarations.d.ts

@@ -0,0 +1,12 @@
+// import { firestore } from '../../../node_modules/firebase/index'
+
+type TODO = any
+type EmptyObject = {}
+
+type DocumentData = Record<string, any>
+
+interface OperationsType<T> {
+  set: (target: Record<string, any>, key: string, value: T) => T
+  add: (array: TODO[], index: number, data: firebase.firestore.DocumentData) => T
+  remove: (array: TODO[], index: number) => any
+}

packages/@posva/vuefire-core/package.json

@@ -27,6 +27,7 @@
     "url": "https://github.com/vuejs/vuefire/issues"
   },
   "devDependencies": {
+    "firebase": "^5.3.1",
     "typescript": "^3.0.1"
   }
 }

packages/@posva/vuefire-core/src/index.js

@@ -221,6 +221,16 @@ function subscribeToDocument({ ref, target, path, depth, resolve, ops }, options
   }
 }
 
+/* TODO do not use an object
+ *
+ * @param {*} vm
+ * @param {string} key
+ * @param {firebase.firestore.DocumentReference} document
+ * @param {*} resolve
+ * @param {*} reject
+ * @param {OperationsType<any>} ops
+ * @param {*} options
+ */
 export function bindDocument({ vm, key, document, resolve, reject, ops }, options) {
   // TODO warning check if key exists?
   // const boundRefs = Object.create(null)

packages/@posva/vuefire-core/src/utils.js

@@ -1,23 +1,55 @@
+/**
+ * @typedef {firebase.firestore.DocumentReference | firebase.firestore.CollectionReference} Reference
+ */
+/**
+ *
+ * @param {firebase.firestore.DocumentSnapshot} doc
+ * @return {DocumentData}
+ */
 export function createSnapshot(doc) {
   // defaults everything to false, so no need to set
   return Object.defineProperty(doc.data(), 'id', {
     value: doc.id,
   })
 }
 
+/**
+ *
+ * @param {any} o
+ * @returns {boolean}
+ */
 function isObject(o) {
   return o && typeof o === 'object'
 }
 
+/**
+ *
+ * @param {any} o
+ * should be o is Date https://github.com/Microsoft/TypeScript/issues/26297
+ * @returns {boolean}
+ */
 function isTimestamp(o) {
   return o.toDate
 }
 
+/**
+ *
+ * @param {*} o
+ * @returns {boolean}
+ */
 function isRef(o) {
   return o && o.onSnapshot
 }
 
-export function extractRefs(doc, oldDoc, path = '', result = [{}, {}]) {
+/**
+ *
+ * @param {firebase.firestore.DocumentData} doc
+ * @param {firebase.firestore.DocumentData} [oldDoc]
+ * @param {string} [path]
+ * @param {[firebase.firestore.DocumentData, Record<string, Reference>]} result
+ * @returns {[firebase.firestore.DocumentData, Record<string, Reference>]}
+ */
+export function extractRefs(doc, oldDoc = {}, path = '', result = [{}, {}]) {
   // must be set here because walkGet can return null or undefined
   oldDoc = oldDoc || {}
   const idDescriptor = Object.getOwnPropertyDescriptor(doc, 'id')
@@ -53,7 +85,15 @@ export function extractRefs(doc, oldDoc, path = '', result = [{}, {}]) {
   }, result)
 }
 
+/**
+ * @template T any
+ * @template K any
+ * @param {(arg: T) => K} fn
+ * @param {() => T} argFn
+ * @returns {() => K | undefined}
+ */
 export function callOnceWithArg(fn, argFn) {
+  /** @type {boolean | undefined} */
   let called
   return () => {
     if (!called) {
@@ -63,10 +103,23 @@ export function callOnceWithArg(fn, argFn) {
   }
 }
 
+/**
+ *
+ * @param {Record<string, any>} obj
+ * @param {string} path
+ * @returns {any}
+ */
 export function walkGet(obj, path) {
   return path.split('.').reduce((target, key) => target[key], obj)
 }
 
+/**
+ *
+ * @param {Record<string, any>} obj
+ * @param {string} path
+ * @param {any} value
+ * @returns
+ */
 export function walkSet(obj, path, value) {
   // path can be a number
   const keys = ('' + path).split('.')

packages/@posva/vuefire-core/tsconfig.json

@@ -1,5 +1,10 @@
 {
-  "include": ["src/**/*.js", "src/*.js"],
+  "include": [
+    "../../../node_modules/firebase/index.d.ts",
+    "declarations.d.ts",
+    "src/index.js",
+    "src/utils.js"
+  ],
   "compilerOptions": {
     /* Basic Options */
     "target": "esnext" /* Specify ECMAScript target version: 'ES3' (default), 'ES5', 'ES2015', 'ES2016', 'ES2017','ES2018' or 'ESNEXT'. */,
@@ -22,7 +27,7 @@
     // "isolatedModules": true,               /* Transpile each file as a separate module (similar to 'ts.transpileModule'). */
 
     /* Strict Type-Checking Options */
-    // "strict": true /* Enable all strict type-checking options. */,
+    "strict": true /* Enable all strict type-checking options. */,
     // "noImplicitAny": true,                 /* Raise error on expressions and declarations with an implied 'any' type. */
     // "strictNullChecks": true,              /* Enable strict null checks. */
     // "strictFunctionTypes": true,           /* Enable strict checking of function types. */

yarn.lock

@@ -2901,7 +2901,7 @@ find-up@^3.0.0:
   dependencies:
     locate-path "^3.0.0"
 
-firebase@^5.2.0:
+firebase@^5.2.0, firebase@^5.3.1:
   version "5.3.1"
   resolved "https://registry.yarnpkg.com/firebase/-/firebase-5.3.1.tgz#99df1a9b101d12cd765ef010bb015fdb0b76850b"
   dependencies: