okmodel 0.2.1 → 0.4.0

package/dist/tooling/testing/index.d.ts

@@ -0,0 +1,89 @@
+/**
+ * `okmodel/testing`: a real database, factories, query counts, and the
+ * isolation check (spec §20, D199).
+ *
+ * The database is never mocked. Pass a driver pool from `open()`.
+ */
+import type { DriverPool } from "../../contracts/driver.js";
+import type { Connected } from "../../runtime/types.js";
+import { type TableFactory } from "./factories.js";
+import { type TestingSchema } from "./facts.js";
+import { type IsolationReport } from "./isolation.js";
+/** Options for {@link testing}. */
+export type TestingOptions = {
+    /**
+     * A driver pool, or a promise of one.
+     *
+     * `open()` from `okmodel/pg/pglite` and `open({ url })` from
+     * `okmodel/pg/postgresjs` both satisfy this.
+     */
+    readonly driver: DriverPool | Promise<DriverPool>;
+    /**
+     * Seed for factory generators.
+     *
+     * The default is `1`. The same seed replays the same values.
+     */
+    readonly seed?: number;
+    /**
+     * Apply the schema's catalog before connecting.
+     *
+     * The default is true, for an empty test database. `okm seed` passes false:
+     * the target already has its schema.
+     */
+    readonly migrate?: boolean;
+};
+/**
+ * What a factory definition may call.
+ *
+ * Re-exported so a seed file can name the argument.
+ */
+export type { FactoryContext, TableFactory } from "./factories.js";
+export type { IsolationReport } from "./isolation.js";
+/** Definitions passed to {@link Testing.factories}. */
+export type FactoryDefinitions = {
+    readonly [table: string]: (context: import("./factories.js").FactoryContext) => Readonly<Record<string, unknown>>;
+};
+/**
+ * A connected test database.
+ *
+ * @typeParam S - Schema passed to {@link testing}
+ */
+export type Testing<S extends TestingSchema = TestingSchema> = {
+    /** The client. `close` on the harness closes this pool. */
+    readonly db: Connected<S>;
+    /**
+     * Builds factories for the named tables.
+     *
+     * @param definitions - One function per table
+     * @returns `create`, `createMany`, and `with` for each table
+     */
+    factories<const D extends FactoryDefinitions>(definitions: D): {
+        readonly [K in keyof D]: TableFactory;
+    };
+    /**
+     * Fails when `run` sends a different number of statements than `count`.
+     *
+     * Transaction control is not counted. The error lists the statements that were.
+     *
+     * @param count - Expected statements
+     * @param run - The work to count
+     */
+    expectQueries(count: number, run: () => Promise<unknown>): Promise<void>;
+    /**
+     * Runs the cross-tenant check.
+     *
+     * @returns Checked tenant tables and skipped global tables
+     */
+    isolation(): Promise<IsolationReport>;
+    /** Closes the client and the pool. */
+    close(): Promise<void>;
+};
+/**
+ * Opens `schema` on `driver` and returns the test harness.
+ *
+ * @typeParam S - Schema
+ * @param schema - A `schema()` value
+ * @param options - Driver, seed, and whether to apply the catalog
+ * @returns The harness
+ */
+export declare function testing<const S extends TestingSchema>(schema: S, options: TestingOptions): Promise<Testing<S>>;

package/dist/tooling/testing/index.js

@@ -0,0 +1,8 @@
+import {
+  testing2
+} from "../../shared/ygem90rn.js";
+import"../../shared/41kv2xdm.js";
+import"../../shared/8jb4ymh2.js";
+export {
+  testing2 as testing
+};

package/dist/tooling/testing/isolation.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Cross-tenant isolation check.
+ *
+ * For every tenant table, insert one row as tenant B and run the basic reads
+ * and writes as tenant A. A returned row, a count above zero, or an update or
+ * delete that touches a row is a leak. Global tables are skipped and listed.
+ * Column tenancy is the strategy this version has. A table is tenant when its
+ * predicate says so (D199).
+ */
+import { type FactoryHost } from "./factories.js";
+/** What {@link isolation} checked, and the global tables it skipped. */
+export type IsolationReport = {
+    /** Tenant tables whose queries stayed inside tenant A. */
+    readonly checked: readonly string[];
+    /** Global tables, with the reason from `global("reason")`. */
+    readonly skipped: readonly {
+        readonly table: string;
+        readonly reason: string;
+    }[];
+};
+/**
+ * Runs the check on `host`.
+ *
+ * The cache used for `x.ref` is set aside for the run, so a row the test
+ * already inserted is not reused as tenant B's row.
+ *
+ * @param host - The open harness
+ * @returns The tables that were checked and the global tables that were not
+ */
+export declare function isolation(host: FactoryHost): Promise<IsolationReport>;

package/dist/tooling/testing/random.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Seeded generators for factories.
+ *
+ * Mulberry32, a fixed word list, and a counter. No runtime dependency.
+ * The same seed replays the same sequence (D199).
+ */
+/** A seeded sequence and the values factories ask for. */
+export type Rng = {
+    /** Next unit interval, `[0, 1)`. */
+    next(): number;
+    /** Integer in `[0, bound)`. */
+    int(bound: number): number;
+    /** A version-4 UUID. The bits come from this sequence. */
+    uuid(): string;
+    /** `local@example.com`, unique for this sequence. */
+    email(): string;
+    /** A first and last name from the fixed lists. */
+    name(): string;
+    /** `count` words from the fixed list. */
+    words(count: number): string;
+    /** A boolean. */
+    boolean(): boolean;
+    /** A number in `[0, 1)`. */
+    float(): number;
+    /** An ISO date `YYYY-MM-DD` in 2020. */
+    date(): string;
+    /** One value from `list`. */
+    pick<T>(list: readonly T[]): T;
+    /** The next counter value, starting at 1. Text defaults append it. */
+    counter(): number;
+};
+/**
+ * Builds the sequence for `seed`.
+ *
+ * Seed `1` is the default. `0` is shifted so the first step is not a fixed point.
+ *
+ * @param seed - Integer seed
+ * @returns The sequence
+ */
+export declare function rng(seed: number): Rng;

package/dist/tooling/testing/record.d.ts

@@ -0,0 +1,38 @@
+/**
+ * A pool that records every statement sent to the driver.
+ *
+ * `expectQueries` counts this log. Transaction control is left out (D199).
+ * The runtime logger records errors only, and `hookm` records notices and
+ * transaction phases, not statement text, so the count wraps the pool.
+ */
+import type { DriverPool, WireValue } from "../../contracts/driver.js";
+/** One statement that reached the driver. */
+export type Recorded = {
+    readonly text: string;
+    readonly params: readonly WireValue[];
+};
+/** A recording pool and its log. */
+export type Recording = {
+    readonly pool: DriverPool;
+    /** Every statement since the pool was wrapped, in the order sent. */
+    readonly log: Recorded[];
+};
+/**
+ * Reports whether `text` only frames a transaction.
+ *
+ * Not counted: `BEGIN`, `START TRANSACTION`, `COMMIT`, `END`, `ROLLBACK`,
+ * `ROLLBACK TO`, `SAVEPOINT`, `RELEASE SAVEPOINT`, `SET TRANSACTION`,
+ * `SET LOCAL`, and `SET SESSION CHARACTERISTICS`. A data statement is counted,
+ * including one that runs inside a transaction.
+ *
+ * @param text - Statement text
+ * @returns Whether the statement is transaction control
+ */
+export declare function isTransactionControl(text: string): boolean;
+/**
+ * Wraps a pool so each statement is logged.
+ *
+ * @param pool - The real pool
+ * @returns The wrapped pool and its log
+ */
+export declare function record(pool: DriverPool): Recording;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okmodel",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "description": "okmodel is a catalog-first TypeScript ORM, PostgreSQL first.",
   "keywords": [
     "migrations",
@@ -82,13 +82,37 @@
       "types": "./dist/runtime/tenancy/index.d.ts",
       "import": "./dist/runtime/tenancy/index.js"
     },
+    "./testing": {
+      "types": "./dist/tooling/testing/index.d.ts",
+      "import": "./dist/tooling/testing/index.js"
+    },
     "./validate": {
       "types": "./dist/runtime/validate/index.d.ts",
       "import": "./dist/runtime/validate/index.js"
+    },
+    "./ext": {
+      "types": "./dist/dialects/pg/ext/index.d.ts",
+      "import": "./dist/dialects/pg/ext/index.js"
+    },
+    "./fn": {
+      "types": "./dist/dialects/pg/fn/index.d.ts",
+      "import": "./dist/dialects/pg/fn/index.js"
+    },
+    "./view": {
+      "types": "./dist/dialects/pg/view/index.d.ts",
+      "import": "./dist/dialects/pg/view/index.js"
+    },
+    "./pg/citext": {
+      "types": "./dist/dialects/pg/ext/citext.d.ts",
+      "import": "./dist/dialects/pg/ext/citext.js"
+    },
+    "./pg/pg_trgm": {
+      "types": "./dist/dialects/pg/ext/pg-trgm.d.ts",
+      "import": "./dist/dialects/pg/ext/pg-trgm.js"
     }
   },
   "scripts": {
-    "build": "rm -rf dist && bun build ./src/contracts/index.ts ./src/contracts/internal.ts ./src/dialects/pg/index.ts ./src/runtime/pg/postgresjs.ts ./src/runtime/pg/pglite.ts ./src/runtime/pg/pg.ts ./src/runtime/pg/bun.ts ./src/runtime/ids/index.ts ./src/runtime/safety/index.ts ./src/runtime/traits/index.ts ./src/runtime/tenancy/index.ts ./src/runtime/validate/index.ts ./src/tooling/migrate/index.ts ./src/tooling/cli.ts --outdir ./dist --root ./src --format esm --target node --splitting --chunk-naming=shared/[hash].js --external postgres --external @electric-sql/pglite --external pg --external bun && bunx tsc -p tsconfig.build.json && bun ./scripts/write-bin-wrappers.ts",
+    "build": "rm -rf dist && bun build ./src/contracts/index.ts ./src/contracts/internal.ts ./src/dialects/pg/index.ts ./src/runtime/pg/postgresjs.ts ./src/runtime/pg/pglite.ts ./src/runtime/pg/pg.ts ./src/runtime/pg/bun.ts ./src/runtime/ids/index.ts ./src/runtime/safety/index.ts ./src/runtime/traits/index.ts ./src/runtime/tenancy/index.ts ./src/runtime/validate/index.ts ./src/dialects/pg/ext/index.ts ./src/dialects/pg/fn/index.ts ./src/dialects/pg/view/index.ts ./src/dialects/pg/ext/citext.ts ./src/dialects/pg/ext/pg-trgm.ts ./src/tooling/migrate/index.ts ./src/tooling/testing/index.ts ./src/tooling/cli.ts --outdir ./dist --root ./src --format esm --target node --splitting --chunk-naming=shared/[hash].js --external postgres --external @electric-sql/pglite --external pg --external bun && bunx tsc -p tsconfig.build.json && bun ./scripts/write-bin-wrappers.ts",
     "driver-bench": "bun ./scripts/driver-bench.ts",
     "typecheck": "bunx tsc --noEmit -p tsconfig.json",
     "editor-check": "bun ./scripts/editor-check.ts",