Finish documenting the source code

.clocignore

@@ -0,0 +1,3 @@
+node_modules
+secrets
+lib

src/add/index.ts

@@ -7,9 +7,9 @@ import { ref } from '../ref'
 /**
  * Adds a new document with a random id to a collection.
  *
- * @param collection - the collection to add to
- * @param data - the data to add to
- * @returns a promise to the document
+ * @param collection - The collection to add to
+ * @param data - The data to add to
+ * @returns A promise to the document
  *
  * @example
  * import { add, collection } from 'typesaurus'

src/all/index.ts

@@ -7,8 +7,8 @@ import { wrapData } from '../data'
 /**
  * Returns all documents in a collection.
  *
- * @param collection  - the collection to get all documents from
- * @returns a promise to all documents
+ * @param collection - The collection to get all documents from
+ * @returns A promise to all documents
  *
  * @example
  * import { all, collection } from 'typesaurus'

src/batch/index.ts

@@ -7,7 +7,9 @@ import { ModelUpdate } from '../update'
 import { Field } from '../field'
 
 /**
- * @returns batch API (set, update, clear, commit)
+ * Creates batch.
+ *
+ * @returns Batch API (set, update, clear, commit)
  *
  * @example
  * import { batch, collection } from 'typesaurus'
@@ -27,15 +29,15 @@ export function batch() {
   const firestoreBatch = firestore().batch()
 
   /**
-   * @param ref - the reference to the document to set
-   * @param data - the document data
+   * @param ref - The reference to the document to set
+   * @param data - The document data
    */
   function set<Model>(ref: Ref<Model>, data: Model): Doc<Model>
 
   /**
-   * @param collection - the collection to set document in
-   * @param id - the id of the document to set
-   * @param data - the document data
+   * @param collection - The collection to set document in
+   * @param id - The id of the document to set
+   * @param data - The document data
    */
   function set<Model>(
     collection: Collection<Model>,
@@ -46,7 +48,7 @@ export function batch() {
   /**
    * Sets a document to the given data.
    *
-   * @returns the document
+   * @returns The document
    *
    * @example
    * import { batch, collection } from 'typesaurus'
@@ -93,9 +95,9 @@ export function batch() {
   }
 
   /**
-   * @param collection - the collection to update document in
-   * @param id - the id of the document to update
-   * @param data - the document data to update
+   * @param collection - The collection to update document in
+   * @param id - The id of the document to update
+   * @param data - The document data to update
    */
   function update<Model>(
     collection: Collection<Model>,
@@ -104,15 +106,15 @@ export function batch() {
   ): void
 
   /**
-   * @param ref - the reference to the document to set
-   * @param data - the document data to update
+   * @param ref - The reference to the document to set
+   * @param data - The document data to update
    */
   function update<Model>(ref: Ref<Model>, data: Field<Model>[]): void
 
   /**
-   * @param collection - the collection to update document in
-   * @param id - the id of the document to update
-   * @param data - the document data to update
+   * @param collection - The collection to update document in
+   * @param id - The id of the document to update
+   * @param data - The document data to update
    */
   function update<Model>(
     collection: Collection<Model>,
@@ -121,8 +123,8 @@ export function batch() {
   ): void
 
   /**
-   * @param ref - the reference to the document to set
-   * @param data - the document data to update
+   * @param ref - The reference to the document to set
+   * @param data - The document data to update
    */
   function update<Model>(ref: Ref<Model>, data: ModelUpdate<Model>): void
 
@@ -186,13 +188,13 @@ export function batch() {
   }
 
   /**
-   * @param collection - the collection to remove document in
-   * @param id - the id of the documented to remove
+   * @param collection - The collection to remove document in
+   * @param id - The id of the documented to remove
    */
   function clear<Model>(collection: Collection<Model>, id: string): void
 
   /**
-   * @param ref - the reference to the document to remove
+   * @param ref - The reference to the document to remove
    */
   function clear<Model>(ref: Ref<Model>): void
 
@@ -240,7 +242,7 @@ export function batch() {
   /**
    * Starts the execution of the operations in the batch.
    *
-   * @returns a promise that resolves when the operations are finished
+   * @returns A promise that resolves when the operations are finished
    */
   async function commit() {
     await firestoreBatch.commit()

src/clear/index.ts

@@ -3,16 +3,16 @@ import { Collection } from '../collection'
 import { Ref } from '../ref'
 
 /**
- * @param collection - the collection to remove document in
- * @param id - the id of the documented to remove
+ * @param collection - The collection to remove document in
+ * @param id - The id of the documented to remove
  */
 async function clear<Model>(
   collection: Collection<Model>,
   id: string
 ): Promise<void>
 
 /**
- * @param ref - the reference to the document to remove
+ * @param ref - The reference to the document to remove
  */
 async function clear<Model>(ref: Ref<Model>): Promise<void>
 

src/collection/index.ts

@@ -1,20 +1,23 @@
+/**
+ * The collection type. It contains the path in Firestore.
+ */
 export interface Collection<_Model> {
   __type__: 'collection'
   path: string
 }
 
 /**
- * Creates collection object.
+ * Creates a collection object.
  *
- * @param path - the collection path
- * @returns collection object
+ * @param path - The collection path
+ * @returns The collection object
  *
  * @example
  * import { add, collection } from 'typesaurus'
  *
  * type User = { name: string }
  * const users = collection<User>('users')
- * // { __type__: 'collection', path: 'users' }
+ * //=> { __type__: 'collection', path: 'users' }
  *
  * add(users, { name: 'Sasha' })
  */

src/cursor/index.ts

@@ -14,7 +14,8 @@ export interface Cursor<Model, Key extends keyof Model> {
 /**
  * Start the query results after the given value.
  *
- * @param value - the value to end the query results after
+ * @param value - The value to end the query results after
+ * @returns The cursor object
  *
  * @example
  * import { startAfter, order, query, collection } from 'typesaurus'
@@ -40,7 +41,8 @@ export function startAfter<Model, Key extends keyof Model>(
 /**
  * Start the query results on the given value.
  *
- * @param value - the value to start the query results at
+ * @param value - The value to start the query results at
+ * @returns The cursor object
  *
  * @example
  * import { startAt, order, query, collection } from 'typesaurus'
@@ -66,7 +68,8 @@ export function startAt<Model, Key extends keyof Model>(
 /**
  * Ends the query results before the given value.
  *
- * @param value - the value to end the query results before
+ * @param value - The value to end the query results before
+ * @returns The cursor object
  *
  * @example
  * import { endBefore, order, query, collection } from 'typesaurus'
@@ -92,7 +95,8 @@ export function endBefore<Model, Key extends keyof Model>(
 /**
  * Ends the query results on the given value.
  *
- * @param value - the value to end the query results at
+ * @param value - The value to end the query results at
+ * @returns The cursor object
  *
  * @example
  * import { endAt, order, query, collection } from 'typesaurus'

src/data/index.ts

@@ -3,21 +3,23 @@ import {
   FirestoreFieldValue,
   FirestoreTimestamp
 } from '../adaptor'
-import { pathToRef, Ref, refToFirebaseDocument } from '../ref'
+import { pathToRef, Ref, refToFirestoreDocument } from '../ref'
 import { UpdateValue } from '../value'
 
 /**
+ * Converts Typesaurus data to Firestore format. It deeply traverse all the data and
+ * converts values to compatible format.
  *
- * @param value - the value to convert
+ * @param data - the data to convert
  */
-export function unwrapData(value: any) {
-  if (value instanceof Date) {
-    return FirestoreTimestamp.fromDate(value)
-  } else if (value && typeof value === 'object') {
-    if (value.__type__ === 'ref') {
-      return refToFirebaseDocument(value as Ref<any>)
-    } else if (value.__type__ === 'value') {
-      const fieldValue = value as UpdateValue<any>
+export function unwrapData(data: any) {
+  if (data instanceof Date) {
+    return FirestoreTimestamp.fromDate(data)
+  } else if (data && typeof data === 'object') {
+    if (data.__type__ === 'ref') {
+      return refToFirestoreDocument(data as Ref<any>)
+    } else if (data.__type__ === 'value') {
+      const fieldValue = data as UpdateValue<any>
       switch (fieldValue.kind) {
         case 'clear':
           return FirestoreFieldValue.delete()
@@ -33,20 +35,26 @@ export function unwrapData(value: any) {
     }
 
     const unwrappedObject: { [key: string]: any } = Object.assign(
-      Array.isArray(value) ? [] : {},
-      value
+      Array.isArray(data) ? [] : {},
+      data
     )
     Object.keys(unwrappedObject).forEach(key => {
       unwrappedObject[key] = unwrapData(unwrappedObject[key])
     })
     return unwrappedObject
-  } else if (value === undefined) {
+  } else if (data === undefined) {
     return null
   } else {
-    return value
+    return data
   }
 }
 
+/**
+ * Converts Firestore data to Typesaurus format. It deeply traverse all the
+ * data and converts values to compatible format.
+ *
+ * @param data - the data to convert
+ */
 export function wrapData(data: unknown) {
   if (data instanceof FirestoreDocumentReference) {
     return pathToRef(data.path)

src/doc/index.ts

@@ -1,11 +1,38 @@
 import { Ref } from '../ref'
 
+/**
+ * The document type. It contains the reference in the DB and the model data.
+ */
 export interface Doc<Model> {
   __type__: 'doc'
   data: Model
   ref: Ref<Model>
 }
 
+/**
+ * Creates a document object.
+ *
+ * @param ref - The document reference
+ * @param data - The model data
+ * @returns The document object
+ *
+ * @example
+ * import { doc, ref, collection } from 'typesaurus'
+ *
+ * type User = { name: string }
+ * const users = collection<User>('users')
+ *
+ * doc(ref(users, '00sHm46UWKObv2W7XK9e'), { name: 'Sasha' })
+ * //=> {
+ * //=>   __type__: 'doc',
+ * //=>   data: { name: 'Sasha' },
+ * //=>   ref: {,
+ * //=>      __type__: 'ref'
+ * //=>     collection: { __type__: 'collection', path: 'users' },
+ * //=>     id: '00sHm46UWKObv2W7XK9e'
+ * //=>   }
+ * //=> }
+ */
 export function doc<Model>(ref: Ref<Model>, data: Model): Doc<Model> {
   return { __type__: 'doc', ref, data }
 }

src/field/index.ts

@@ -1,3 +1,6 @@
+/**
+ * The field type. It contains path to the property and property value.
+ */
 export interface Field<_Model> {
   key: string | string[]
   value: any
@@ -118,6 +121,24 @@ function field<
   value: Model[Key1][Key2][Key3][Key4][Key5][Key6][Key7][Key8][Key9][Key10]
 ): Field<Model>
 
+/**
+ * Creates a field object.
+ *
+ * @param key - The field key or key path
+ * @param value - The value
+ * @returns The field object
+ *
+ * @example
+ * import { field, update, collection } from 'typesaurus'
+ *
+ * type User = { name: string }
+ * const users = collection<User>('users')
+ * update(users, '00sHm46UWKObv2W7XK9e', [
+ *   field('name', 'Sasha Koss'),
+ *   field(['address', 'city'], 'Dimitrovgrad')
+ * ])
+ * //=> Promise<void>
+ */
 function field<Model>(key: string | string[], value: any): Field<Model> {
   return { key, value }
 }