@prisma-next/runtime-executor 0.3.0-dev.33 → 0.3.0-dev.35

package/README.md

@@ -18,7 +18,7 @@ Provide a target-agnostic execution engine that family runtimes (e.g., `@prisma-
 
 ## Responsibilities
 
-- **Plan Validation**: Verify plans against contracts (coreHash/profileHash checks)
+- **Plan Validation**: Verify plans against contracts (storageHash/profileHash checks)
 - **Marker Verification**: Read and parse contract markers from databases
 - **Plugin Orchestration**: Manage plugin lifecycle (beforeExecute, onRow, afterExecute hooks)
 - **Telemetry Recording**: Track execution metrics (lane, target, fingerprint, outcome, duration)

package/dist/index.d.mts

@@ -0,0 +1,180 @@
+import { ContractMarkerRecord, ContractMarkerRecord as ContractMarkerRecord$1, ExecutionPlan } from "@prisma-next/contract/types";
+import { OperationRegistry } from "@prisma-next/operations";
+
+//#region src/async-iterable-result.d.ts
+/**
+ * Custom async iterable result that extends AsyncIterable with a toArray() method.
+ * This provides a convenient way to collect all results from an async iterator.
+ */
+declare class AsyncIterableResult<Row> implements AsyncIterable<Row>, PromiseLike<Row[]> {
+  private readonly generator;
+  private consumed;
+  private consumedBy;
+  private bufferedArrayPromise;
+  constructor(generator: AsyncGenerator<Row, void, unknown>);
+  [Symbol.asyncIterator](): AsyncIterator<Row>;
+  /**
+   * Collects all values from the async iterator into an array.
+   * Once called, the iterator is consumed and cannot be reused.
+   */
+  toArray(): Promise<Row[]>;
+  then<TResult1 = Row[], TResult2 = never>(onfulfilled?: ((value: Row[]) => TResult1 | PromiseLike<TResult1>) | undefined | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | undefined | null): PromiseLike<TResult1 | TResult2>;
+}
+//#endregion
+//#region src/errors.d.ts
+interface RuntimeErrorEnvelope extends Error {
+  readonly code: string;
+  readonly category: 'PLAN' | 'CONTRACT' | 'LINT' | 'BUDGET' | 'RUNTIME';
+  readonly severity: 'error';
+  readonly details?: Record<string, unknown>;
+}
+declare function runtimeError(code: string, message: string, details?: Record<string, unknown>): RuntimeErrorEnvelope;
+//#endregion
+//#region src/fingerprint.d.ts
+declare function computeSqlFingerprint(sql: string): string;
+//#endregion
+//#region src/guardrails/raw.d.ts
+type LintSeverity = 'error' | 'warn';
+type BudgetSeverity = 'error' | 'warn';
+interface LintFinding {
+  readonly code: `LINT.${string}`;
+  readonly severity: LintSeverity;
+  readonly message: string;
+  readonly details?: Record<string, unknown>;
+}
+interface BudgetFinding {
+  readonly code: `BUDGET.${string}`;
+  readonly severity: BudgetSeverity;
+  readonly message: string;
+  readonly details?: Record<string, unknown>;
+}
+interface RawGuardrailConfig {
+  readonly budgets?: {
+    readonly unboundedSelectSeverity?: BudgetSeverity;
+    readonly estimatedRows?: number;
+  };
+}
+interface RawGuardrailResult {
+  readonly lints: LintFinding[];
+  readonly budgets: BudgetFinding[];
+  readonly statement: 'select' | 'mutation' | 'other';
+}
+declare function evaluateRawGuardrails(plan: ExecutionPlan, config?: RawGuardrailConfig): RawGuardrailResult;
+//#endregion
+//#region src/marker.d.ts
+declare function parseContractMarkerRow(row: unknown): ContractMarkerRecord$1;
+//#endregion
+//#region src/plugins/types.d.ts
+type Severity = 'error' | 'warn' | 'info';
+interface Log {
+  info(event: unknown): void;
+  warn(event: unknown): void;
+  error(event: unknown): void;
+}
+interface PluginContext<TContract = unknown, TAdapter = unknown, TDriver = unknown> {
+  readonly contract: TContract;
+  readonly adapter: TAdapter;
+  readonly driver: TDriver;
+  readonly mode: 'strict' | 'permissive';
+  readonly now: () => number;
+  readonly log: Log;
+}
+interface AfterExecuteResult {
+  readonly rowCount: number;
+  readonly latencyMs: number;
+  readonly completed: boolean;
+}
+interface Plugin<TContract = unknown, TAdapter = unknown, TDriver = unknown> {
+  readonly name: string;
+  beforeExecute?(plan: ExecutionPlan, ctx: PluginContext<TContract, TAdapter, TDriver>): Promise<void>;
+  onRow?(row: Record<string, unknown>, plan: ExecutionPlan, ctx: PluginContext<TContract, TAdapter, TDriver>): Promise<void>;
+  afterExecute?(plan: ExecutionPlan, result: AfterExecuteResult, ctx: PluginContext<TContract, TAdapter, TDriver>): Promise<void>;
+}
+//#endregion
+//#region src/plugins/budgets.d.ts
+interface BudgetsOptions {
+  readonly maxRows?: number;
+  readonly defaultTableRows?: number;
+  readonly tableRows?: Record<string, number>;
+  readonly maxLatencyMs?: number;
+  readonly severities?: {
+    readonly rowCount?: 'warn' | 'error';
+    readonly latency?: 'warn' | 'error';
+  };
+  readonly explain?: {
+    readonly enabled?: boolean;
+  };
+}
+declare function budgets<TContract = unknown, TAdapter = unknown, TDriver = unknown>(options?: BudgetsOptions): Plugin<TContract, TAdapter, TDriver>;
+//#endregion
+//#region src/plugins/lints.d.ts
+interface LintsOptions {
+  readonly severities?: {
+    readonly selectStar?: 'warn' | 'error';
+    readonly noLimit?: 'warn' | 'error';
+    readonly readOnlyMutation?: 'warn' | 'error';
+    readonly unindexedPredicate?: 'warn' | 'error';
+  };
+}
+declare function lints<TContract = unknown, TAdapter = unknown, TDriver = unknown>(options?: LintsOptions): Plugin<TContract, TAdapter, TDriver>;
+//#endregion
+//#region src/runtime-spi.d.ts
+interface MarkerStatement {
+  readonly sql: string;
+  readonly params: readonly unknown[];
+}
+interface MarkerReader {
+  readMarkerStatement(): MarkerStatement;
+}
+interface RuntimeFamilyAdapter<TContract = unknown> {
+  readonly contract: TContract;
+  readonly markerReader: MarkerReader;
+  validatePlan(plan: ExecutionPlan, contract: TContract): void;
+}
+//#endregion
+//#region src/runtime-core.d.ts
+interface RuntimeVerifyOptions {
+  readonly mode: 'onFirstUse' | 'startup' | 'always';
+  readonly requireMarker: boolean;
+}
+type TelemetryOutcome = 'success' | 'runtime-error';
+interface RuntimeTelemetryEvent {
+  readonly lane: string;
+  readonly target: string;
+  readonly fingerprint: string;
+  readonly outcome: TelemetryOutcome;
+  readonly durationMs?: number;
+}
+interface RuntimeCoreOptions<TContract = unknown, TAdapter = unknown, TDriver = unknown> {
+  readonly familyAdapter: RuntimeFamilyAdapter<TContract>;
+  readonly driver: TDriver;
+  readonly verify: RuntimeVerifyOptions;
+  readonly plugins?: readonly Plugin<TContract, TAdapter, TDriver>[];
+  readonly mode?: 'strict' | 'permissive';
+  readonly log?: Log;
+  readonly operationRegistry: OperationRegistry;
+}
+interface RuntimeCore<TContract = unknown, TAdapter = unknown, TDriver = unknown> extends RuntimeQueryable {
+  readonly _typeContract?: TContract;
+  readonly _typeAdapter?: TAdapter;
+  readonly _typeDriver?: TDriver;
+  connection(): Promise<RuntimeConnection>;
+  telemetry(): RuntimeTelemetryEvent | null;
+  close(): Promise<void>;
+  operations(): OperationRegistry;
+}
+interface RuntimeConnection extends RuntimeQueryable {
+  transaction(): Promise<RuntimeTransaction>;
+  release(): Promise<void>;
+}
+interface RuntimeTransaction extends RuntimeQueryable {
+  commit(): Promise<void>;
+  rollback(): Promise<void>;
+}
+interface RuntimeQueryable {
+  execute<Row = Record<string, unknown>>(plan: ExecutionPlan<Row>): AsyncIterableResult<Row>;
+}
+declare function createRuntimeCore<TContract = unknown, TAdapter = unknown, TDriver = unknown>(options: RuntimeCoreOptions<TContract, TAdapter, TDriver>): RuntimeCore<TContract, TAdapter, TDriver>;
+//#endregion
+export { AfterExecuteResult, AsyncIterableResult, BudgetFinding, BudgetsOptions, type ContractMarkerRecord, LintFinding, LintsOptions, Log, MarkerReader, MarkerStatement, Plugin, PluginContext, RawGuardrailResult, RuntimeConnection, RuntimeCore, RuntimeCoreOptions, RuntimeErrorEnvelope, RuntimeFamilyAdapter, RuntimeQueryable, RuntimeTelemetryEvent, RuntimeTransaction, RuntimeVerifyOptions, Severity, TelemetryOutcome, budgets, computeSqlFingerprint, createRuntimeCore, evaluateRawGuardrails, lints, parseContractMarkerRow, runtimeError };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/async-iterable-result.ts","../src/errors.ts","../src/fingerprint.ts","../src/guardrails/raw.ts","../src/marker.ts","../src/plugins/types.ts","../src/plugins/budgets.ts","../src/plugins/lints.ts","../src/runtime-spi.ts","../src/runtime-core.ts"],"sourcesContent":[],"mappings":"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"}