Strengthening Documentation for Core Libraries

packages/core/src/backup.ts

@@ -3,8 +3,14 @@ import { DocInfo } from './server'
 
 /**
  * @public
- * Define a st of document + hashcode for chunk
- * So backup client could decide to download or not any of documents.
+
+ * Defines a 'chunk' of documents for backup. Each chunk, identified by an index, contains an 
+ * array of `DocInfo` objects. Each `DocInfo` includes a unique ID and a hash code, used by
+ * the backup client if a document needs to be downloaded. 
+ * 
+ * @property {number} idx - The index of the chunk.
+ * @property {DocInfo[]} docs - The array of document information.
+ * @property {boolean} finished - A flag indicating whether the chunk is finished and all documents have been processed.
  */
 export interface DocChunk {
   idx: number

packages/core/src/clone.ts

@@ -1,6 +1,16 @@
+// Check if Symbol is defined
 const se = typeof Symbol !== 'undefined'
+// Check if Symbol.toStringTag is defined
 const ste = se && typeof Symbol.toStringTag !== 'undefined'
 
+/**
+ * @function getTypeOf
+ * 
+ * Returns the type of the given object.
+ * 
+ * @param {any} obj - The object to check.
+ * @returns {string} The type of the object.
+ */
 export function getTypeOf (obj: any): string {
   const typeofObj = typeof obj
   if (typeofObj !== 'object') {
@@ -34,6 +44,16 @@ export function getTypeOf (obj: any): string {
   return {}.toString.call(obj).slice(8, -1)
 }
 
+/**
+ * @function clone
+ * 
+ * Clones the given object.
+ * 
+ * @param {any} obj - The object to clone.
+ * @param {(doc: any, m: any) => any} as - A function to transform the cloned object.
+ * @param {(value: any) => any | undefined} needAs - A function to check if the transformation is needed.
+ * @returns {any} The cloned object.
+ */
 export function clone (obj: any, as?: (doc: any, m: any) => any, needAs?: (value: any) => any | undefined): any {
   if (typeof obj === 'undefined') {
     return undefined

packages/core/src/common.ts

@@ -1,3 +1,14 @@
+/**
+ * @function groupByArray
+ * 
+ * Groups the elements of an array into a Map based on a provided key.
+ * 
+ * @template T - Type of elements in the array.
+ * @template K - Type of key.
+ * @param {T[]} array - The array to group.
+ * @param {(item: T) => K} keyProvider - A function that provides the key for each element.
+ * @returns {Map<K, T[]>} The Map of grouped elements.
+ */
 export function groupByArray<T, K> (array: T[], keyProvider: (item: T) => K): Map<K, T[]> {
   const result = new Map<K, T[]>()
 
@@ -14,6 +25,17 @@ export function groupByArray<T, K> (array: T[], keyProvider: (item: T) => K): Ma
   return result
 }
 
+/**
+ * @function flipSet
+ * 
+ * Flips the presence of an item in a Set. If the item is in the Set, it is removed. 
+ * If it is not in the Set, it is added.
+ * 
+ * @template T - Type of item.
+ * @param {Set<T>} set - The Set to flip.
+ * @param {T} item - The item to flip.
+ * @returns {Set<T>} The flipped Set.
+ */
 export function flipSet<T> (set: Set<T>, item: T): Set<T> {
   if (set.has(item)) {
     set.delete(item)
@@ -22,4 +44,4 @@ export function flipSet<T> (set: Set<T>, item: T): Set<T> {
   }
 
   return set
-}
+}

packages/core/src/objvalue.ts

@@ -5,6 +5,13 @@ import core from './component'
 
 /**
  * @public
+ * @function getObjectValue
+ * 
+ * Retrieves the value of a property from a document using dot notation.
+ * 
+ * @param {string} key - The key of the property to retrieve, in dot notation.
+ * @param {Doc} doc - The document to retrieve the property value from.
+ * @returns {any} The value of the property.
  */
 export function getObjectValue (key: string, doc: Doc): any {
   // Check dot notation
@@ -32,6 +39,14 @@ export function getObjectValue (key: string, doc: Doc): any {
 
 /**
  * @public
+ * @function setObjectValue
+ * 
+ * Sets the value of a property in a document using dot notation.
+ * 
+ * @param {string} key - The key of the property to set, in dot notation.
+ * @param {Doc} doc - The document to set the property value in.
+ * @param {any} newValue - The new value to set.
+ * @returns {void}
  */
 export function setObjectValue (key: string, doc: Doc, newValue: any): void {
   // Check dot notation
@@ -64,10 +79,28 @@ export function setObjectValue (key: string, doc: Doc, newValue: any): void {
   return value
 }
 
+/**
+ * @function isNestedArrayQuery
+ * 
+ * Checks if a value is a nested array query.
+ * 
+ * @param {any} value - The value to check.
+ * @param {string} d - The key to check.
+ * @returns {boolean} True if the value is a nested array query, false otherwise.
+ */
 function isNestedArrayQuery (value: any, d: string): boolean {
   return Number.isNaN(Number.parseInt(d)) && value?.[d as any] === undefined
 }
 
+/**
+ * @function getNestedArrayValue
+ * 
+ * Retrieves the nested array value of a property from a document using dot notation.
+ * 
+ * @param {any[]} value - The array to retrieve the nested value from.
+ * @param {string} name - The name of the property to retrieve, in dot notation.
+ * @returns {any[]} The nested array value of the property.
+ */
 function getNestedArrayValue (value: any[], name: string): any[] {
   const result = []
   for (const v of value) {
@@ -76,6 +109,14 @@ function getNestedArrayValue (value: any[], name: string): any[] {
   return result
 }
 
+/**
+ * @function arrayOrValue
+ * 
+ * Checks if a value is an array, and if not, wraps it in an array.
+ * 
+ * @param {any} vv - The value to check.
+ * @returns {any[]} The value, either as it was if it was an array, or wrapped in an array if it was not.
+ */
 function arrayOrValue (vv: any): any[] {
   return Array.isArray(vv) ? vv : [vv]
 }

packages/core/src/predicate.ts

@@ -25,6 +25,16 @@ type PredicateFactory = (pred: any, propertyKey: string) => Predicate
 
 type ExecPredicate = (value: any) => boolean
 
+/**
+ * @function execPredicate
+ * 
+ * Executes a predicate on each document in an array of documents.
+ * 
+ * @param {Doc[]} docs - The array of documents.
+ * @param {string} propertyKey - The property key.
+ * @param {ExecPredicate} pred - The predicate to execute.
+ * @returns {Doc[]} The array of documents that satisfy the predicate.
+ */
 function execPredicate (docs: Doc[], propertyKey: string, pred: ExecPredicate): Doc[] {
   const result: Doc[] = []
   for (const doc of docs) {
@@ -36,6 +46,7 @@ function execPredicate (docs: Doc[], propertyKey: string, pred: ExecPredicate):
   return result
 }
 
+// Maps predicate names to their corresponding PredicateFactory.
 const predicates: Record<string, PredicateFactory> = {
   $in: (o, propertyKey) => {
     if (!Array.isArray(o)) {
@@ -106,6 +117,14 @@ const predicates: Record<string, PredicateFactory> = {
   }
 }
 
+/**
+ * @function isPredicate
+ * 
+ * Checks if an object is a predicate.
+ * 
+ * @param {Record<string, any>} o - The object to check.
+ * @returns {boolean} True if the object is a predicate, false otherwise.
+ */
 export function isPredicate (o: Record<string, any>): boolean {
   if (o === null || typeof o !== 'object') {
     return false
@@ -114,6 +133,15 @@ export function isPredicate (o: Record<string, any>): boolean {
   return keys.length > 0 && keys.every((key) => key.startsWith('$'))
 }
 
+/**
+ * @function createPredicates
+ * 
+ * Creates an array of Predicates from an object and a property key.
+ * 
+ * @param {Record<string, any>} o - The object.
+ * @param {string} propertyKey - The property key.
+ * @returns {Predicate[]} The array of Predicates.
+ */
 export function createPredicates (o: Record<string, any>, propertyKey: string): Predicate[] {
   const keys = Object.keys(o)
   const result: Predicate[] = []

packages/core/src/proxy.ts

@@ -6,6 +6,13 @@ const PROXY_MIXIN_CLASS_KEY = '$__mixin'
 
 /**
  * @internal
+ * @function _createMixinProxy
+ * 
+ * This function creates a proxy for a mixin.
+ * 
+ * @param {Mixin<Doc>} mixin - The mixin to create a proxy for.
+ * @param {ProxyHandler<Doc> | null} ancestorProxy - The ancestor proxy.
+ * @returns {ProxyHandler<Doc>} The created proxy.
  */
 export function _createMixinProxy (mixin: Mixin<Doc>, ancestorProxy: ProxyHandler<Doc> | null): ProxyHandler<Doc> {
   return {
@@ -28,6 +35,13 @@ export function _createMixinProxy (mixin: Mixin<Doc>, ancestorProxy: ProxyHandle
 
 /**
  * @internal
+ * @function _toDoc
+ * 
+ * This function converts a document to its target document if it is a proxy.
+ * 
+ * @template D extends Doc - The type of the document.
+ * @param {D} doc - The document to convert.
+ * @returns {D} The target document if the document is a proxy, otherwise the original document.
  */
 export function _toDoc<D extends Doc> (doc: D): D {
   const targetDoc = (doc as any)[PROXY_TARGET_KEY]
@@ -39,6 +53,14 @@ export function _toDoc<D extends Doc> (doc: D): D {
 
 /**
  * @internal
+ * @function _mixinClass
+ * 
+ * This function gets the mixin class of a document.
+ * 
+ * @template D extends Doc - The type of the document.
+ * @template M extends D - The type of the mixin.
+ * @param {D} doc - The document to get the mixin class from.
+ * @returns {Ref<Mixin<M>> | undefined} The mixin class if it exists, otherwise undefined.
  */
 export function _mixinClass<D extends Doc, M extends D> (doc: D): Ref<Mixin<M>> | undefined {
   return (doc as any)[PROXY_MIXIN_CLASS_KEY]