@minnowdb/core 0.10.1 → 0.10.2

package/dist/testing/interaction-simulator.d.ts

@@ -0,0 +1,319 @@
+/**
+ * Interaction-plan simulator: a seeded, replayable workload over the whole SQL surface an
+ * application uses, checked against a shadow model and a set of properties.
+ *
+ * `simulator.ts` is the storage-completion simulator: one table, keyed upserts and deletes, a
+ * seeded completion order for every block-store call. This one sits above it, in the spirit of
+ * Turso's simulator. A plan is a sequence of *interactions* -- DDL, inserts, predicate updates
+ * and deletes, selects, indexes, SQL transactions, concurrent rounds across several connections,
+ * faults, reopens, maintenance -- generated from a seed and serialized as JSON, so a failing CI
+ * seed replays exactly and can be checked in. Every interaction is executed through the real
+ * SQL entry points and judged against an in-memory shadow model that applies three-valued
+ * predicate logic, plus the properties a database must honour whatever its internals do:
+ *
+ *   - insert-select: a row just inserted comes back exactly, and a rejected insert leaves none
+ *     of its rows behind (statement atomicity)
+ *   - update-count and delete-count: the reported row count is the model's matched count
+ *   - delete-select: nothing matching a delete's predicate survives it
+ *   - drop-select and double-create-failure: dropped tables are gone, duplicates are refused
+ *   - select-limit: LIMIT returns exactly min(limit, matching) rows in ORDER BY order
+ *   - where-true-false-null: COUNT(p) + COUNT(NOT p) + COUNT(p IS NULL) = COUNT(*)
+ *   - union-all-cardinality: a UNION ALL has the sum of its members' cardinalities
+ *   - transaction-isolation: uncommitted rows are visible on their own connection and invisible
+ *     to another; ROLLBACK discards them and COMMIT keeps them
+ *   - concurrent-explicability: a read taken while a round of commuting writes is in flight
+ *     shows every untouched key exactly and every touched key at either its old or new value
+ *   - fault-atomicity: a mutation interrupted by a storage fault or a crash lands entirely or
+ *     not at all, and a reported success is durable
+ *   - agreement: at every checkpoint every connection reads the same database as the model
+ *
+ * The runner is driver-agnostic. `SimulationDriver` opens connections over one shared database;
+ * the Node driver wraps `MinnowDatabase` over any block store, and the Playwright driver wraps
+ * one real browser tab per connection over IndexedDB or OPFS, so the same plan runs in both.
+ */
+import { type MinnowDatabaseOptions } from "../engine/database.js";
+import type { BlockStore } from "../storage/index.js";
+export type ColumnType = "integer" | "real" | "text" | "boolean";
+export interface PlanColumn {
+    readonly name: string;
+    readonly type: ColumnType;
+    readonly nullable: boolean;
+}
+export interface PlanTable {
+    readonly name: string;
+    /** Every table has `id INTEGER PRIMARY KEY`; these are the other columns. */
+    readonly columns: readonly PlanColumn[];
+}
+export type PlanValue = number | string | boolean | null;
+export type PlanRow = Readonly<Record<string, PlanValue>>;
+export type CompareOperator = "=" | "<>" | "<" | "<=" | ">" | ">=";
+export type Predicate = {
+    readonly kind: "compare";
+    readonly column: string;
+    readonly op: CompareOperator;
+    readonly value: PlanValue;
+} | {
+    readonly kind: "isNull";
+    readonly column: string;
+    readonly negated: boolean;
+} | {
+    readonly kind: "and";
+    readonly left: Predicate;
+    readonly right: Predicate;
+} | {
+    readonly kind: "or";
+    readonly left: Predicate;
+    readonly right: Predicate;
+} | {
+    readonly kind: "not";
+    readonly inner: Predicate;
+} | {
+    readonly kind: "literal";
+    readonly value: boolean;
+};
+export type Assignment = {
+    readonly kind: "set";
+    readonly column: string;
+    readonly value: PlanValue;
+} | {
+    readonly kind: "increment";
+    readonly column: string;
+    readonly by: number;
+};
+export type KeyedMutation = {
+    readonly kind: "insert";
+    readonly row: PlanRow;
+} | {
+    readonly kind: "upsert";
+    readonly row: PlanRow;
+} | {
+    readonly kind: "updateKey";
+    readonly id: number;
+    readonly assignments: readonly Assignment[];
+} | {
+    readonly kind: "deleteKey";
+    readonly id: number;
+};
+export type TransactionStatement = {
+    readonly kind: "insert";
+    readonly rows: readonly PlanRow[];
+} | {
+    readonly kind: "update";
+    readonly predicate: Predicate;
+    readonly assignments: readonly Assignment[];
+} | {
+    readonly kind: "delete";
+    readonly predicate: Predicate;
+};
+export type Interaction = {
+    readonly kind: "createTable";
+    readonly connection: number;
+    readonly table: PlanTable;
+    readonly expectExisting: boolean;
+} | {
+    readonly kind: "insert";
+    readonly connection: number;
+    readonly table: string;
+    readonly rows: readonly PlanRow[];
+    readonly viaParameters: boolean;
+} | {
+    readonly kind: "update";
+    readonly connection: number;
+    readonly table: string;
+    readonly predicate: Predicate;
+    readonly assignments: readonly Assignment[];
+} | {
+    readonly kind: "delete";
+    readonly connection: number;
+    readonly table: string;
+    readonly predicate: Predicate;
+} | {
+    readonly kind: "select";
+    readonly connection: number;
+    readonly table: string;
+    readonly predicate: Predicate;
+    readonly limit: number | null;
+    readonly descending: boolean;
+} | {
+    readonly kind: "partition";
+    readonly connection: number;
+    readonly table: string;
+    readonly predicate: Predicate;
+} | {
+    readonly kind: "unionAll";
+    readonly connection: number;
+    readonly table: string;
+    readonly left: Predicate;
+    readonly right: Predicate;
+} | {
+    readonly kind: "createIndex";
+    readonly connection: number;
+    readonly table: string;
+    readonly name: string;
+    readonly columns: readonly string[];
+} | {
+    readonly kind: "dropTable";
+    readonly connection: number;
+    readonly table: string;
+    readonly expectMissing: boolean;
+} | {
+    readonly kind: "transaction";
+    readonly connection: number;
+    readonly observer: number;
+    readonly table: string;
+    readonly statements: readonly TransactionStatement[];
+    readonly outcome: "commit" | "rollback";
+} | {
+    readonly kind: "concurrent";
+    readonly table: string;
+    readonly operations: ReadonlyArray<{
+        readonly connection: number;
+        readonly mutation: KeyedMutation;
+    }>;
+    readonly readers: readonly number[];
+} | {
+    readonly kind: "fault";
+    readonly connection: number;
+    readonly table: string;
+    readonly mutation: KeyedMutation;
+    readonly point: FaultPointName;
+} | {
+    readonly kind: "reopen";
+    readonly connection: number;
+} | {
+    readonly kind: "maintenance";
+    readonly connection: number;
+    readonly table: string;
+} | {
+    readonly kind: "checkpoint";
+};
+export type FaultPointName = "beforeBlockWrite" | "afterBlockWrite" | "beforeTransactionCommit" | "afterTransactionCommit" | "crash";
+export interface InteractionPlan {
+    readonly version: 1;
+    readonly seed: number;
+    readonly connections: number;
+    readonly interactions: readonly Interaction[];
+}
+export interface InteractionPlanOptions {
+    /** Interactions to generate, checkpoints and DDL included. */
+    readonly length?: number;
+    readonly connections?: number;
+    /** Tables the plan may create at once. */
+    readonly tables?: number;
+    /** Primary-key space per table; small enough that inserts collide and updates hit. */
+    readonly keySpace?: number;
+    /**
+     * Fault points the plan may draw from. A driver without storage fault injection (a real
+     * browser) generates crash faults only, so every fault step is one it can exercise.
+     */
+    readonly faultPoints?: readonly FaultPointName[];
+}
+export interface SimulatedExecuteResult {
+    readonly kind: string;
+    readonly rowCount?: number;
+}
+export interface SimulatedQueryResult {
+    readonly columns: readonly string[];
+    readonly rows: ReadonlyArray<Readonly<Record<string, unknown>>>;
+}
+export interface SimulatedConnection {
+    execute(sql: string, params?: readonly PlanValue[]): Promise<SimulatedExecuteResult>;
+    query(sql: string, params?: readonly PlanValue[]): Promise<SimulatedQueryResult>;
+    /** Closes and reopens this connection over the same database. */
+    reopen(): Promise<void>;
+    /** Runs the store's maintenance (compaction and collection) for one table. */
+    maintain?(table: string): Promise<void>;
+    /**
+     * Kills the connection's process while a call may be in flight; the pending call must fail
+     * with an unknown-outcome or lost-connection error, and `reopen` must bring the connection
+     * back. A driver without a process boundary omits it and the plan's crash faults are skipped.
+     */
+    crash?(): Promise<void>;
+}
+export interface SimulatedFaults {
+    /** Fails the next `occurrence`-th storage call at `point` on any connection. */
+    arm(point: Exclude<FaultPointName, "crash">, occurrence: number): void;
+    disarm(): void;
+    fired(): boolean;
+}
+export interface SimulationDriver {
+    open(connection: number): Promise<SimulatedConnection>;
+    readonly faults?: SimulatedFaults;
+    /** Whether errors the driver reports carry `name`; a driver over a text channel may not. */
+    close?(): Promise<void>;
+}
+export interface InteractionRunOptions {
+    /** Bounded trace of executed SQL kept for the failure report. */
+    readonly traceLength?: number;
+}
+export interface InteractionRunResult {
+    readonly seed: number;
+    /** Interactions judged. Short of the plan's length only when `transientsAccepted` is not zero. */
+    readonly interactions: number;
+    readonly statements: number;
+    readonly queries: number;
+    readonly acceptedWrites: number;
+    /**
+     * Refusals the engine documents and the runner models rather than reports: a write that lost a
+     * conflict, and a transaction whose COMMIT lost the race to another connection's data commit.
+     * The run continues from the state they leave behind.
+     */
+    readonly rejectedConflicts: number;
+    /**
+     * Refusals the plan expected: a duplicate insert, a double create, and a transaction the engine
+     * rolled back on its own idle deadline, which the runner acknowledges with a `ROLLBACK`. These
+     * do not stop the run either.
+     */
+    readonly expectedFailures: number;
+    readonly faultsInjected: number;
+    readonly faultsSkipped: number;
+    readonly reopens: number;
+    readonly checkpoints: number;
+    readonly tablesAtEnd: number;
+    readonly rowsAtEnd: number;
+    /**
+     * The one transient that ends a run instead of being modelled: a store that stopped answering.
+     * A browser can wedge a whole database beyond any engine's reach (a worker terminated with a
+     * write in flight leaves WebKit's IndexedDB connection registered until its document goes away),
+     * and the engine then bounds the wait and reports `StorageUnresponsiveError` rather than hanging.
+     * Nothing further can be driven through that store, so the run stops at that interaction and
+     * `interactions` counts only the steps it judged.
+     */
+    readonly transientsAccepted: number;
+    /** What ended the run early, when `transientsAccepted` is not zero. */
+    readonly stoppedBy: string | undefined;
+}
+export declare class InteractionFailure extends Error {
+    readonly index: number;
+    readonly interaction: Interaction;
+    readonly trace: readonly string[];
+    constructor(message: string, index: number, interaction: Interaction, trace: readonly string[], options?: ErrorOptions);
+}
+/** Generates a bounded, replayable plan; the same seed and options always produce the same plan. */
+export declare function generateInteractionPlan(seed: number, options?: InteractionPlanOptions): InteractionPlan;
+export declare function parseInteractionPlan(source: string): InteractionPlan;
+type Truth = true | false | null;
+/** SQL three-valued logic over one row. */
+export declare function evaluate(predicate: Predicate, row: PlanRow): Truth;
+export declare function renderLiteral(value: PlanValue): string;
+export declare function renderPredicate(predicate: Predicate): string;
+export declare function runInteractionPlan(plan: InteractionPlan, driver: SimulationDriver, options?: InteractionRunOptions): Promise<InteractionRunResult>;
+export declare function describeError(error: unknown): string;
+export interface DatabaseDriverOptions {
+    /** Options for every `MinnowDatabase` the driver opens; `now` and `createId` stay the engine's. */
+    readonly databaseOptions?: MinnowDatabaseOptions;
+}
+/**
+ * Where a connection's block store comes from: one shared instance, as several engines in one
+ * process share it, or a factory that opens a separate instance over the same durable database
+ * for every connection and every reopen -- the shape of separate tabs, each with its own
+ * adapter caches, which is where a cross-tab cache that goes stale shows up.
+ */
+export type DriverStoreSource = BlockStore | (() => Promise<BlockStore>);
+/**
+ * A driver whose connections are `MinnowDatabase` instances over one database, with the storage
+ * fault points armed through `FaultInjectingBlockStore`. Crash faults are skipped: there is no
+ * process to kill.
+ */
+export declare function createDatabaseDriver(source: DriverStoreSource, options?: DatabaseDriverOptions): SimulationDriver;
+export {};