chore: doc and fixes after code review

Author: nytamin

meteor/server/api/ingest/ingestCache.ts

@@ -13,6 +13,10 @@ import {
 } from '@sofie-automation/corelib/dist/dataModel/NrcsIngestDataCache'
 import { groupByToMap } from '@sofie-automation/corelib/dist/lib'
 
+/**
+ * This class provides a few convenience methods for fetching IngestRundown
+ * (or its child types) from the NrcsIngestDataCache collection
+ */
 export class RundownIngestDataCache {
 	private constructor(private readonly rundownId: RundownId, private readonly documents: NrcsIngestDataCacheObj[]) {}
 

meteor/server/collections/rundown.ts

@@ -29,13 +29,19 @@ registerIndex(AdLibPieces, {
 	_rank: 1,
 })
 
+/**
+ * The NrcsIngestDataCache collection is used to store data that comes from an NRCS
+ */
 export const NrcsIngestDataCache = createAsyncOnlyReadOnlyMongoCollection<NrcsIngestDataCacheObj>(
 	CollectionName.NrcsIngestDataCache
 )
 registerIndex(NrcsIngestDataCache, {
 	rundownId: 1,
 })
 
+/**
+ * The SofieIngestDataCache collection is used to store data that comes from an NRCS and has been modified by Sofie
+ */
 export const SofieIngestDataCache = createAsyncOnlyReadOnlyMongoCollection<SofieIngestDataCacheObj>(
 	CollectionName.SofieIngestDataCache
 )

packages/blueprints-integration/src/api/studio.ts

@@ -93,6 +93,23 @@ export interface StudioBlueprintManifest<TRawConfig = IBlueprintConfig, TProcess
 		coreConfig: BlueprintConfigCoreConfig
 	) => TProcessedConfig
 
+	/**
+	 * Optional method to validate the blueprint config passed to this blueprint according to the API schema.
+	 * Returns a list of messages to the caller that are used for logging or to throw if errors have been found.
+	 */
+	validateConfigFromAPI?: (context: ICommonContext, apiConfig: object) => Array<IConfigMessage>
+
+	/**
+	 * Optional method to transform from an API blueprint config to the database blueprint config if these are required to be different.
+	 * If this method is not defined the config object will be used directly
+	 */
+	blueprintConfigFromAPI?: (context: ICommonContext, config: object) => IBlueprintConfig
+
+	/**
+	 * Optional method to transform from a database blueprint config to the API blueprint config if these are required to be different.
+	 * If this method is not defined the config object will be used directly
+	 */
+	blueprintConfigToAPI?: (context: ICommonContext, config: TRawConfig) => object
 	/**
 	 * Process an ingest operation, to apply changes to the sofie interpretation of the ingest data
 	 */

packages/blueprints-integration/src/context/processIngestDataContext.ts

@@ -5,10 +5,13 @@ import type { IngestDefaultChangesOptions, MutableIngestRundown, NrcsIngestChang
 export interface IProcessIngestDataContext extends IStudioContext {
 	/**
 	 * Perform the default syncing of changes from the ingest data to the rundown.
-	 * This may be overly agressive at removing any changes made by user operations.
-	 * If you are using user operations, you may need to perform some pre and post fixups to ensure changes aren't wiped unnecessarily.
+	 *
+	 * Please note that this may be overly aggressive at removing any changes made by user operations
+	 * If you are using user operations, you may need to perform some pre and post fixups to ensure
+	 * changes aren't wiped unnecessarily.
+	 *
 	 * @param ingestRundown NRCS version of the IngestRundown to copy from
-	 * @param ingestChanges A description of the changes that have been made to the rundown and should be propogated
+	 * @param ingestChanges A description of the changes that have been made to the rundown and should be propagated
 	 * @param options Options for how to apply the changes
 	 */
 	defaultApplyIngestChanges<TRundownPayload, TSegmentPayload, TPartPayload>(
@@ -19,9 +22,12 @@ export interface IProcessIngestDataContext extends IStudioContext {
 	): void
 
 	/**
-	 * Group Parts in a MOS Rundown and return a new changes object
+	 * Group the Parts in a MOS Rundown and return a new changes object
 	 * This will group the Parts based on the segment name, using the separator provided to extract the segment name from the part name
-	 * Note: This ignores a lot of the contents of the `ingestChanges` object, and relies more on the `previousIngestRundown` instead
+	 *
+	 * Please note that this ignores some of the granularity of the `ingestChanges` object, and relies more on the `previousIngestRundown` instead
+	 * If you are using user operations, you may need to perform some pre and post fixups to ensure changes aren't wiped unnecessarily.
+	 *
 	 * @param ingestRundown The rundown whose parts needs grouping
 	 * @param previousIngestRundown The rundown prior to the changes, if known
 	 * @param ingestChanges The changes which have been performed in `ingestRundown`, that need to translating
@@ -37,7 +43,10 @@ export interface IProcessIngestDataContext extends IStudioContext {
 
 	/**
 	 * Group Parts in a Rundown and return a new changes object
-	 * Note: This ignores a lot of the contents of the `ingestChanges` object, and relies more on the `previousIngestRundown` instead
+	 *
+	 * Please note that this ignores some of the granularity of the `ingestChanges` object, and relies more on the `previousIngestRundown` instead
+	 * If you are using user operations, you may need to perform some pre and post fixups to ensure changes aren't wiped unnecessarily.
+	 *
 	 * @param ingestRundown The rundown whose parts needs grouping
 	 * @param previousIngestRundown The rundown prior to the changes, if known
 	 * @param ingestChanges The changes which have been performed in `ingestRundown`, that need to translating

packages/blueprints-integration/src/ingest-types.ts

@@ -9,27 +9,39 @@ export interface SofieIngestRundown<TRundownPayload = unknown, TSegmentPayload =
 	/** Array of segments in this rundown */
 	segments: SofieIngestSegment<TSegmentPayload, TPartPayload>[]
 
-	/** States for UserEdits, could be lock from NRCS updates,
-	 * lock from user changes,
-	 * or removedByUser
-	 * */
+	/**
+	 * The userEditStates is a key-value store where Blueprints can store persistent data.
+	 *
+	 * Examples of use cases;
+	 * - locks from NRCS updates
+	 * - locks from user changes
+	 * - removedByUser flags
+	 */
 	userEditStates: Record<string, boolean>
 }
 export interface SofieIngestSegment<TSegmentPayload = unknown, TPartPayload = unknown>
 	extends IngestSegment<TSegmentPayload, TPartPayload> {
 	/** Array of parts in this segment */
 	parts: SofieIngestPart<TPartPayload>[]
 
-	/** States for UserEdits, could be lock from NRCS updates,
-	 * lock from user changes,
-	 * or removedByUser
-	 * */
+	/**
+	 * The userEditStates is a key-value store where Blueprints can store persistent data.
+	 *
+	 * Examples of use cases;
+	 * - locks from NRCS updates
+	 * - locks from user changes
+	 * - removedByUser flags
+	 */
 	userEditStates: Record<string, boolean>
 }
 export interface SofieIngestPart<TPayload = unknown> extends IngestPart<TPayload> {
-	/** States for UserEdits, could be lock from NRCS updates,
-	 * lock from user changes,
-	 * or removedByUser
-	 * */
+	/**
+	 * The userEditStates is a key-value store where Blueprints can store persistent data.
+	 *
+	 * Examples of use cases;
+	 * - locks from NRCS updates
+	 * - locks from user changes
+	 * - removedByUser flags
+	 */
 	userEditStates: Record<string, boolean>
 }

packages/blueprints-integration/src/ingest.ts

@@ -136,7 +136,11 @@ export interface UserOperationChange<TCustomBlueprintOperations extends { id: st
 	operationTarget: UserOperationTarget
 	operation: DefaultUserOperations | TCustomBlueprintOperations
 }
-
+/**
+ * The MutableIngestRundown is used to modify the contents of an IngestRundown during ingest.
+ * The public properties and methods are used i blueprints to selectively apply incoming
+ * or apply user operations to the SofieIngestRundown.
+ */
 export interface MutableIngestRundown<TRundownPayload = unknown, TSegmentPayload = unknown, TPartPayload = unknown> {
 	/** Id of the rundown as reported by the ingest gateway. Must be unique for each rundown owned by the gateway */
 	readonly externalId: string
@@ -172,6 +176,10 @@ export interface MutableIngestRundown<TRundownPayload = unknown, TSegmentPayload
 		  }
 		| undefined
 
+	/**
+	 * Returns a Segment with a certain externalId
+	 * @param segmentExternalId
+	 */
 	getSegment(segmentExternalId: string): MutableIngestSegment<TSegmentPayload, TPartPayload> | undefined
 
 	/**
@@ -261,6 +269,9 @@ export interface MutableIngestRundown<TRundownPayload = unknown, TSegmentPayload
 		value: ReadonlyDeep<TRundownPayload[TKey]> | TRundownPayload[TKey]
 	): void
 
+	/**
+	 * Set a value in the userEditState
+	 */
 	setUserEditState(key: string, value: boolean): void
 }
 

packages/corelib/src/dataModel/NrcsIngestDataCache.ts

@@ -2,6 +2,12 @@ import { IngestRundown, IngestSegment, IngestPart } from '@sofie-automation/blue
 import { NrcsIngestDataCacheObjId, RundownId, SegmentId, PartId } from './Ids'
 import { RundownSource } from './Rundown'
 
+/*
+	The NRCSIngestDataCache collection is used to store raw data that comes from an NRCS.
+	See also ./SofieIngestDataCache.ts
+	For where the ingested data is stored after being processed/modified by Sofie.
+*/
+
 export enum NrcsIngestCacheType {
 	RUNDOWN = 'rundown',
 	SEGMENT = 'segment',

packages/corelib/src/dataModel/SofieIngestDataCache.ts

@@ -2,6 +2,11 @@ import { SofieIngestRundown, SofieIngestSegment, SofieIngestPart } from '@sofie-
 import { SofieIngestDataCacheObjId, RundownId, SegmentId, PartId } from './Ids'
 import { RundownSource } from './Rundown'
 
+/*
+	The SofieIngestDataCache collection is used to store data that comes from an NRCS and has been modified by Sofie.
+	See also ./NrcsIngestDataCache.ts for the raw data from the NRCS.
+*/
+
 export enum SofieIngestCacheType {
 	RUNDOWN = 'rundown',
 	SEGMENT = 'segment',

packages/job-worker/src/blueprints/context/ProcessIngestDataContext.ts

@@ -11,6 +11,11 @@ import { StudioContext } from './StudioContext'
 import { defaultApplyIngestChanges } from '../ingest/defaultApplyIngestChanges'
 import { groupMosPartsIntoIngestSegments, groupPartsInRundownAndChanges } from '../ingest/groupPartsInRundownAndChanges'
 
+/**
+ * Provides a context for blueprints while running the blueprints.processIngestData() method.
+ * Note: This provides some common helpers for doing mutations of the IngestRundown.
+ * Custom updates of the IngestRundown are done by calling methods on the mutableIngestRundown itself.
+ */
 export class ProcessIngestDataContext extends StudioContext implements IProcessIngestDataContext {
 	defaultApplyIngestChanges<TRundownPayload, TSegmentPayload, TPartPayload>(
 		mutableIngestRundown: MutableIngestRundown<TRundownPayload, TSegmentPayload, TPartPayload>,

packages/job-worker/src/blueprints/context/lib.ts

@@ -562,6 +562,9 @@ export function translateUserEditsFromBlueprint(
 	)
 }
 
+/**
+ * Converts a BlueprintMutatablePart into a PlayoutMutatablePart
+ */
 export function convertPartialBlueprintMutablePartToCore(
 	updatePart: Partial<IBlueprintMutatablePart>,
 	blueprintId: BlueprintId