deepline 0.0.1 → 0.1.1

package/dist/repo/shared_libs/play-runtime/batch-runtime.ts

@@ -0,0 +1,182 @@
+import type { AnyBatchOperationStrategy } from './batching-types';
+
+export interface ChunkExecutionResult<TRequest, TResult> {
+  request: TRequest;
+  result: TResult | null;
+}
+
+function formatChunkExecutionError(error: unknown): string {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  return String(error);
+}
+
+export interface CompiledRequestBatch<TRequest> {
+  batchOperation: string;
+  memberRequests: TRequest[];
+  batchPayload: Record<string, unknown>;
+  splitResults: (value: unknown) => Array<unknown | null>;
+}
+
+export async function executeChunkedRequests<TRequest, TResult>(input: {
+  requests: TRequest[];
+  batchSize: number;
+  execute: (request: TRequest) => Promise<TResult>;
+  onChunkComplete?: (
+    results: Array<ChunkExecutionResult<TRequest, TResult>>,
+  ) => void | Promise<void>;
+}): Promise<Array<ChunkExecutionResult<TRequest, TResult>>> {
+  const results: Array<ChunkExecutionResult<TRequest, TResult>> = [];
+
+  for (let start = 0; start < input.requests.length; start += input.batchSize) {
+    const chunk = input.requests.slice(start, start + input.batchSize);
+    const settled = await Promise.allSettled(
+      chunk.map((request) => input.execute(request)),
+    );
+
+    const rejected = settled.find(
+      (outcome): outcome is PromiseRejectedResult =>
+        outcome.status === 'rejected',
+    );
+    if (rejected) {
+      throw new Error(
+        `Play batch request failed: ${formatChunkExecutionError(rejected.reason)}`,
+        { cause: rejected.reason },
+      );
+    }
+
+    for (let index = 0; index < chunk.length; index += 1) {
+      const outcome = settled[index] as PromiseFulfilledResult<TResult>;
+      results.push({
+        request: chunk[index]!,
+        result: outcome.value,
+      });
+    }
+
+    const completedChunk = results.slice(results.length - chunk.length);
+    await input.onChunkComplete?.(completedChunk);
+  }
+
+  return results;
+}
+
+export function compileRequestsWithStrategy<TRequest>(input: {
+  requests: TRequest[];
+  strategy: AnyBatchOperationStrategy;
+  getPayload: (request: TRequest) => Record<string, unknown>;
+}): Array<CompiledRequestBatch<TRequest>> {
+  const compiledBatches: Array<CompiledRequestBatch<TRequest>> = [];
+  const bucketedRequests = new Map<string, TRequest[]>();
+
+  for (const request of input.requests) {
+    const payload = input.getPayload(request);
+    const bucketKey = String(input.strategy.toBucketKey(payload));
+    if (!bucketedRequests.has(bucketKey)) {
+      bucketedRequests.set(bucketKey, []);
+    }
+    bucketedRequests.get(bucketKey)!.push(request);
+  }
+
+  for (const bucketRequests of bucketedRequests.values()) {
+    let currentBatch: TRequest[] = [];
+
+    const flushBatch = () => {
+      if (currentBatch.length === 0) {
+        return;
+      }
+
+      const memberRequests = [...currentBatch];
+      const compiled = input.strategy.compile(
+        memberRequests.map((request) => input.getPayload(request)),
+      );
+      compiledBatches.push({
+        batchOperation: compiled.batchOperation,
+        memberRequests,
+        batchPayload: compiled.batchPayload as Record<string, unknown>,
+        splitResults: (value: unknown) => {
+          const splitResults = input.strategy.splitResult(
+            value as never,
+            compiled as never,
+          );
+          return memberRequests.map(
+            (_, index) => splitResults[index]?.result ?? null,
+          );
+        },
+      });
+      currentBatch = [];
+    };
+
+    for (const request of bucketRequests) {
+      const payload = input.getPayload(request);
+      const canAppend =
+        currentBatch.length > 0 &&
+        currentBatch.length < input.strategy.maxBatchSize &&
+        currentBatch.every((existing) =>
+          input.strategy.canBatchWith(input.getPayload(existing), payload),
+        );
+
+      if (!canAppend && currentBatch.length > 0) {
+        flushBatch();
+      }
+
+      currentBatch.push(request);
+    }
+
+    flushBatch();
+  }
+
+  return compiledBatches;
+}
+
+export async function executeWaterfallProviders<TRequest, TResult>(input: {
+  providers: string[];
+  getPendingRequests: () => TRequest[];
+  getCachedResults: (provider: string) => Array<ChunkExecutionResult<TRequest, TResult>> | null;
+  storeCachedResults: (
+    provider: string,
+    results: Array<ChunkExecutionResult<TRequest, TResult>>,
+  ) => void;
+  executeProviderRequests: (
+    provider: string,
+    requests: TRequest[],
+  ) => Promise<Array<ChunkExecutionResult<TRequest, TResult>>>;
+  onHit: (provider: string, request: TRequest, result: TResult) => void;
+  onMiss: (provider: string, request: TRequest) => void;
+  onProviderComplete?: (provider: string) => void;
+}): Promise<void> {
+  for (const provider of input.providers) {
+    const cached = input.getCachedResults(provider);
+    if (cached) {
+      for (const entry of cached) {
+        if (entry.result != null) {
+          input.onHit(provider, entry.request, entry.result);
+        }
+      }
+      input.onProviderComplete?.(provider);
+      continue;
+    }
+
+    const pending = input.getPendingRequests();
+    if (pending.length === 0) {
+      return;
+    }
+
+    const results = await input.executeProviderRequests(provider, pending);
+    input.storeCachedResults(provider, results);
+
+    for (const entry of results) {
+      if (entry.result != null) {
+        input.onHit(provider, entry.request, entry.result);
+      } else {
+        input.onMiss(provider, entry.request);
+      }
+    }
+
+    input.onProviderComplete?.(provider);
+  }
+}
+
+export function resolveWaterfallToolId(provider: string, toolName: string): string {
+  return toolName.startsWith(`${provider}_`) ? toolName : `${provider}_${toolName}`;
+}

package/dist/repo/shared_libs/play-runtime/batching-types.ts

@@ -0,0 +1,91 @@
+export type BatchStrategyKind =
+  | 'identifier_batch'
+  | 'query_share'
+  | 'async_dataset_job';
+
+export type BatchCompileItem<TSingle extends object> = {
+  // Preserved for diagnostics and job bookkeeping only.
+  // Batch fanout is positional: compiled.items[index] maps to splitResult[index].
+  itemKey: string;
+  payload: TSingle;
+};
+
+export type BatchCompileResult<TBatch extends object, TSingle extends object> = {
+  batchOperation: string;
+  batchPayload: TBatch;
+  items: Array<BatchCompileItem<TSingle>>;
+};
+
+export type BatchExecutionDataEnvelope<TBatchResult> = {
+  data: TBatchResult;
+};
+
+export type BatchExecutionResultPayload<TBatchResult> =
+  | TBatchResult
+  | BatchExecutionDataEnvelope<TBatchResult>;
+
+export type BatchSplitItemResult<TResult = unknown, TRawResult = unknown> = {
+  // Preserved as metadata only. The runtime does not use itemKey to match rows.
+  itemKey: string;
+  result: TResult;
+  rawResult?: TRawResult;
+};
+
+export type BatchOperationStrategy<
+  TSingle extends Record<string, unknown> = Record<string, unknown>,
+  TBatch extends Record<string, unknown> = Record<string, unknown>,
+  TBatchResult extends object = Record<string, unknown>,
+  TResult = unknown,
+  TRawResult = unknown,
+> = {
+  sourceOperation: string;
+  batchOperation: string;
+  kind: BatchStrategyKind;
+  maxBatchSize: number;
+  canBatchWith(left: TSingle, right: TSingle): boolean;
+  toBucketKey(payload: TSingle): string;
+  toItemKey(payload: TSingle): string;
+  compile(payloads: TSingle[]): BatchCompileResult<TBatch, TSingle>;
+  splitResult(
+    fullResult: TBatchResult,
+    compiled: BatchCompileResult<TBatch, TSingle>,
+    // Implementations must return results in the same order as compiled.items.
+  ): BatchSplitItemResult<TResult, TRawResult>[];
+};
+
+export type AnyBatchOperationStrategy = {
+  sourceOperation: string;
+  batchOperation: string;
+  kind: BatchStrategyKind;
+  maxBatchSize: number;
+  canBatchWith(left: Record<string, unknown>, right: Record<string, unknown>): boolean;
+  toBucketKey(payload: Record<string, unknown>): string;
+  toItemKey(payload: Record<string, unknown>): string;
+  compile(payloads: Record<string, unknown>[]): {
+    batchOperation: string;
+    batchPayload: Record<string, unknown>;
+    items: Array<{
+      itemKey: string;
+      payload: Record<string, unknown>;
+    }>;
+  };
+  splitResult(
+    fullResult: unknown,
+    compiled: {
+      batchOperation: string;
+      batchPayload: Record<string, unknown>;
+      items: Array<{ itemKey: string; payload: Record<string, unknown> }>;
+    },
+  ): BatchSplitItemResult<unknown, unknown>[];
+};
+
+export type BatchStrategyMap = Record<string, AnyBatchOperationStrategy>;
+
+type StrictBatchOperationStrategy =
+  BatchOperationStrategy<Record<string, unknown>, Record<string, unknown>, object, unknown, unknown>;
+
+export function defineBatchStrategyMap<
+  TStrategies extends Record<string, StrictBatchOperationStrategy>,
+>(strategies: TStrategies): BatchStrategyMap {
+  return strategies as BatchStrategyMap;
+}