docs: add inline documentation

packages/lyra/src/lyra.ts

@@ -18,7 +18,13 @@ export type PropertiesSchema = {
 };
 
 export type Configuration<S extends PropertiesSchema> = {
+  /**
+   * The structure of the document to be inserted into the database.
+   */
   schema: S;
+  /**
+   * The default language analyzer to use.
+   */
   defaultLanguage?: Language;
   edge?: boolean;
 };
@@ -30,31 +36,71 @@ export type Data<S extends PropertiesSchema> = {
 };
 
 export interface Lyra<S extends PropertiesSchema> extends Data<S> {
+  /**
+   * The default language analyzer in use.
+   */
   defaultLanguage: Language;
+  /**
+   * The structure of documents stored in the database.
+   */
   schema: S;
   edge: boolean;
 }
 
 export type InsertConfig = {
+  /**
+   * The language analyzer to use.
+   */
   language: Language;
 };
 
 export type SearchParams<S extends PropertiesSchema> = {
+  /**
+   * The word to search.
+   */
   term: string;
+  /**
+   * The properties of the document to search in.
+   */
   properties?: "*" | SearchProperties<S>[];
+  /**
+   * The number of matched documents to return.
+   */
   limit?: number;
+  /**
+   * The number of matched documents to skip.
+   */
   offset?: number;
+  /**
+   * Whether to match the term exactly.
+   */
   exact?: boolean;
+  /**
+   * The maximum [levenshtein distance](https://en.wikipedia.org/wiki/Levenshtein_distance)
+   * between the term and the searchable property.
+   */
   tolerance?: number;
 };
 
 export type SearchResult<S extends PropertiesSchema> = {
+  /**
+   * The number of all the matched documents.
+   */
   count: number;
+  /**
+   * An array of matched documents taking `limit` and `offset` into account.
+   */
   hits: RetrievedDoc<S>[];
+  /**
+   * The time taken to search.
+   */
   elapsed: bigint;
 };
 
 export type RetrievedDoc<S extends PropertiesSchema> = ResolveSchema<S> & {
+  /**
+   * The id of the document.
+   */
   id: string;
 };
 
@@ -174,6 +220,18 @@ function getDocumentIDsFromSearch<S extends PropertiesSchema>(
   return Array.from(ids);
 }
 
+/**
+ * Creates a new database.
+ * @param properties Options to initialize the database with.
+ * @example
+ * // Create a database that stores documents containing 'author' and 'quote' fields.
+ * const db = create({
+ *   schema: {
+ *     author: 'string',
+ *     quote: 'string'
+ *   }
+ * });
+ */
 export function create<S extends PropertiesSchema>(properties: Configuration<S>): Lyra<S> {
   const defaultLanguage = (properties?.defaultLanguage?.toLowerCase() as Language) ?? "english";
 
@@ -194,6 +252,18 @@ export function create<S extends PropertiesSchema>(properties: Configuration<S>)
   return instance;
 }
 
+/**
+ * Inserts a document into a database.
+ * @param lyra The database to insert document into.
+ * @param doc The document to insert.
+ * @param config Optional parameter for overriding default configuration.
+ * @returns An object containing id of the inserted document.
+ * @example
+ * const { id } = insert(db, {
+ *   quote: 'You miss 100% of the shots you don\'t take',
+ *   author: 'Wayne Gretzky - Michael Scott'
+ * });
+ */
 export function insert<S extends PropertiesSchema>(
   lyra: Lyra<S>,
   doc: ResolveSchema<S>,
@@ -217,6 +287,13 @@ export function insert<S extends PropertiesSchema>(
   return { id };
 }
 
+/**
+ * Removes a document from a database.
+ * @param lyra The database to remove the document from.
+ * @param docID The id of the document to remove.
+ * @example
+ * const isDeleted = remove(db, 'L1tpqQxc0c2djrSN2a6TJ');
+ */
 export function remove<S extends PropertiesSchema>(lyra: Lyra<S>, docID: string): boolean {
   if (!(docID in lyra.docs)) {
     throw new Error(ERRORS.DOC_ID_DOES_NOT_EXISTS(docID));
@@ -244,6 +321,18 @@ export function remove<S extends PropertiesSchema>(lyra: Lyra<S>, docID: string)
   return true;
 }
 
+/**
+ * Searches for documents in a database.
+ * @param lyra The database to search.
+ * @param params The search query.
+ * @param language Optional parameter to override the default language analyzer.
+ * @example
+ * // Search for documents that contain 'Michael' in the 'author' field.
+ * const result = search(db, {
+ *   term: 'Michael',
+ *   properties: ['author']
+ * });
+ */
 export function search<S extends PropertiesSchema>(
   lyra: Lyra<S>,
   params: SearchParams<S>,