catalog-backend: Add documentation

Co-authored-by: Patrik Oldsberg <poldsberg@gmail.com>
Signed-off-by: Johan Haals <johan.haals@gmail.com>

plugins/catalog-backend/src/next/database/DefaultProcessingDatabase.ts

@@ -103,8 +103,6 @@ export class DefaultProcessingDatabase implements ProcessingDatabase {
       sourceEntityRef: stringifyEntityRef(processedEntity),
     });
 
-    // Update fragments
-
     // Delete old relations
     await tx<DbRelationsRow>('relations')
       .where({ originating_entity_id: id })
@@ -329,6 +327,10 @@ export class DefaultProcessingDatabase implements ProcessingDatabase {
     }
   }
 
+  /**
+   * Add a set of deferred entities for processing.
+   * The entities will be added at the front of the processing queue.
+   */
   async addUnprocessedEntities(
     txOpaque: Transaction,
     options: AddUnprocessedEntitiesOptions,
@@ -352,6 +354,9 @@ export class DefaultProcessingDatabase implements ProcessingDatabase {
           unprocessed_entity: serializedEntity,
           location_key: locationKey,
           last_discovery_at: tx.fn.now(),
+          // We only get to this point if a processed entity actually had any changes, or
+          // if an entity provider requested this mutation, meaning that we can safely
+          // bump the deferred entities to the front of the queue for immediate processing.
           next_update_at: tx.fn.now(),
         })
         .where('entity_ref', entityRef)

plugins/catalog-backend/src/next/database/types.ts

@@ -86,6 +86,9 @@ export type RefreshOptions = {
 export interface ProcessingDatabase {
   transaction<T>(fn: (tx: Transaction) => Promise<T>): Promise<T>;
 
+  /**
+   * Add unprocessed entities to the front of the processing queue using a mutation.
+   */
   replaceUnprocessedEntities(
     txOpaque: Transaction,
     options: ReplaceUnprocessedEntitiesOptions,
@@ -97,7 +100,10 @@ export interface ProcessingDatabase {
   ): Promise<GetProcessableEntitiesResult>;
 
   /**
-   * Updates a processed entity
+   * Updates a processed entity.
+   *
+   * Any deferred entities are added at the front of the processing queue for
+   * immediate processing, meaning this should only be called when the entity has changes.
    */
   updateProcessedEntity(
     txOpaque: Transaction,
@@ -112,5 +118,8 @@ export interface ProcessingDatabase {
     options: UpdateProcessedEntityErrorsOptions,
   ): Promise<void>;
 
+  /**
+   * Schedules a refresh of a given entityRef.
+   */
   refresh(txOpaque: Transaction, options: RefreshOptions): Promise<void>;
 }