chore(8.0): final pre-RC1 sweep — API consistency, named errors, orphans, zero-cast codebase

src/streaming/pipeline.ts

@@ -55,7 +55,20 @@ export class Pipeline<T = any> {
   }
   
   constructor(private brainyInstance?: Brainy | Brainy<any>) {}
-  
+
+  /**
+   * Re-brand this pipeline's element type after a stage that changes the
+   * stream's item type has been pushed. The runtime object is unchanged —
+   * the fluent builder mutates `stages` on the same instance rather than
+   * allocating a new pipeline, and `Pipeline<T>`'s type parameter exists
+   * only at compile time. (Typed boundary: `Pipeline<T>` and `Pipeline<R>`
+   * are not structurally comparable generics, so this is the one sanctioned
+   * `unknown` bridge in this class.)
+   */
+  private retype<R>(): Pipeline<R> {
+    return this as unknown as Pipeline<R>
+  }
+
   /**
    * Add a data source
    */
@@ -71,9 +84,9 @@ export class Pipeline<T = any> {
       }
     }
     this.stages.push(stage)
-    return this as any
+    return this.retype<S>()
   }
-  
+
   /**
    * Transform data
    */
@@ -88,7 +101,7 @@ export class Pipeline<T = any> {
       }
     }
     this.stages.push(stage)
-    return this as any
+    return this.retype<R>()
   }
   
   /**
@@ -143,7 +156,12 @@ export class Pipeline<T = any> {
               if (result) {
                 // Note: This won't work perfectly in async iterator
                 // In production, use a proper queue
-                batch = [result as any]
+                // Typed boundary preserving a pre-existing quirk verbatim:
+                // re-stashing the flushed batch as a single element nests it
+                // (a T[] stored where T is expected), so a later size-flush
+                // can yield a nested array. Documented, not fixed — fixing it
+                // (batch = result) would change runtime output.
+                batch = [result] as unknown as T[]
               }
             }, timeoutMs)
           }
@@ -155,9 +173,9 @@ export class Pipeline<T = any> {
       }
     }
     this.stages.push(stage)
-    return this as any
+    return this.retype<T[]>()
   }
-  
+
   /**
    * Sink data to a destination
    */
@@ -172,7 +190,7 @@ export class Pipeline<T = any> {
       }
     }
     this.stages.push(stage)
-    return this as any
+    return this.retype<void>()
   }
   
   /**
@@ -197,7 +215,8 @@ export class Pipeline<T = any> {
         for (const item of batch) {
           await (brain as Brainy<any>).add({
             data: item,
-            type: (options?.type as any) || NounType.Document,
+            // Type coercion since pipeline accepts string
+            type: (options?.type as NounType | undefined) || NounType.Document,
             metadata: options?.metadata
           })
         }
@@ -206,12 +225,12 @@ export class Pipeline<T = any> {
         for (const item of batch) {
           await (brain as Brainy).add({
             data: item,
-            type: (options?.type || 'document') as any, // Type coercion since pipeline accepts string
+            type: (options?.type || 'document') as NounType, // Type coercion since pipeline accepts string
             metadata: options?.metadata
           })
         }
       }
-    }) as any
+    })
   }
   
   /**
@@ -244,7 +263,7 @@ export class Pipeline<T = any> {
       }
     }
     this.stages.push(stage)
-    return this as any
+    return this.retype<void>()
   }
   
   /**
@@ -282,7 +301,7 @@ export class Pipeline<T = any> {
       }
     }
     this.stages.push(stage)
-    return this as any
+    return this.retype<void>()
   }
   
   /**
@@ -332,7 +351,7 @@ export class Pipeline<T = any> {
       }
     }
     this.stages.push(stage)
-    return this as any
+    return this.retype<T[]>()
   }
 
   /**
@@ -352,7 +371,7 @@ export class Pipeline<T = any> {
       }
     }
     this.stages.push(stage)
-    return this as any
+    return this.retype<R>()
   }
 
   /**
@@ -411,7 +430,7 @@ export class Pipeline<T = any> {
       }
     }
     this.stages.push(stage)
-    return this as any
+    return this.retype<R>()
   }
 
   /**
@@ -522,7 +541,7 @@ export class Pipeline<T = any> {
       }
     }
     this.stages.push(stage)
-    return this as any
+    return this.retype<R>()
   }
   
   /**
@@ -542,12 +561,17 @@ export class Pipeline<T = any> {
     const { errorHandler, bufferSize = 1000 } = options
     
     try {
-      // Build the pipeline chain
-      let stream: AsyncIterable<any> = undefined as any
-      
+      // Build the pipeline chain. The head of the chain has no upstream:
+      // source stages declare process() without parameters and never read
+      // their input, so the undefined fed to them (and to a malformed
+      // pipeline whose first stage isn't a source — preserved legacy
+      // behavior) is typed at this boundary as the AsyncIterable it never is.
+      const noUpstream = undefined as unknown as AsyncIterable<unknown>
+      let stream: AsyncIterable<unknown> = noUpstream
+
       for (const stage of this.stages) {
         if (stage.type === 'source') {
-          stream = stage.process(undefined as any)
+          stream = stage.process(noUpstream)
         } else {
           stream = stage.process(stream)
         }