@jterrazz/test 5.3.2 → 6.1.0

package/dist/sqlite.adapter.d.cts

@@ -0,0 +1,209 @@
+//#region src/ports/database.port.d.ts
+/**
+ * Abstract database interface for specification runners.
+ * Implement this to plug in your database stack (e.g. Postgres, SQLite).
+ */
+interface DatabasePort {
+  /** Execute raw SQL (for seeding test data). */
+  seed(sql: string): Promise<void>;
+  /** Query a table and return rows as arrays of values. */
+  query(table: string, columns: string[]): Promise<unknown[][]>;
+  /** Reset database to clean state between tests. */
+  reset(): Promise<void>;
+}
+//#endregion
+//#region src/ports/isolation.port.d.ts
+/**
+ * Strategy for isolating service state across parallel test workers.
+ *
+ * Each service handle provides an isolation strategy. The framework
+ * calls `acquire()` once per vitest worker, `reset()` before each
+ * `spec.run()`, and `release()` when the worker shuts down.
+ *
+ * Implement this interface to support new service types (e.g. MongoDB,
+ * Elasticsearch, S3).
+ */
+interface IsolationStrategy {
+  /**
+   * Create an isolated namespace for this worker.
+   * Called once when the worker starts — e.g. clone a template database,
+   * set a Redis key prefix.
+   *
+   * @param workerId - Unique identifier for this vitest worker.
+   */
+  acquire(workerId: string): Promise<void>;
+  /**
+   * Fast reset within the namespace between `spec.run()` calls.
+   * E.g. truncate tables (without dropping the database).
+   */
+  reset(): Promise<void>;
+  /**
+   * Tear down the isolated namespace.
+   * Called once when the worker shuts down — e.g. drop the cloned database.
+   */
+  release(): Promise<void>;
+}
+//#endregion
+//#region src/ports/service.port.d.ts
+/**
+ * A service handle — returned by factory functions like postgres(), redis().
+ * Mutable: connectionString is populated after the orchestrator starts containers.
+ */
+interface ServiceHandle {
+  /** Service type identifier. */
+  readonly type: string;
+  /** Compose service name (if linked). */
+  readonly composeName: null | string;
+  /** Default container port for this service type. */
+  readonly defaultPort: number;
+  /** Default Docker image for this service type. */
+  readonly defaultImage: string;
+  /** Environment variables to pass to the container. */
+  readonly environment: Record<string, string>;
+  /** Connection string — populated after start. */
+  connectionString: string;
+  /** Whether this service has been started. */
+  started: boolean;
+  /** Build the connection string from host and port. */
+  buildConnectionString(host: string, port: number): string;
+  /** Create a DatabasePort adapter (if this is a database). Returns null otherwise. */
+  createDatabaseAdapter(): DatabasePort | null;
+  /** Verify the service is ready and accepting connections. Throws with context if not. */
+  healthcheck(): Promise<void>;
+  /** Run initialization scripts (e.g., init.sql). Throws with SQL error context if it fails. */
+  initialize(composeDir: string): Promise<void>;
+  /** Reset state between tests (truncate tables, flush cache, etc.) */
+  reset(): Promise<void>;
+  /** Get the isolation strategy for parallel test execution. */
+  isolation(): IsolationStrategy;
+}
+//#endregion
+//#region src/adapters/postgres.adapter.d.ts
+interface PostgresOptions {
+  /** Map to a service in docker-compose.test.yaml. */
+  compose?: string;
+  /** Override image. */
+  image?: string;
+  /** Override environment variables. */
+  env?: Record<string, string>;
+}
+declare class PostgresHandle implements DatabasePort, ServiceHandle {
+  readonly type = "postgres";
+  readonly composeName: null | string;
+  readonly defaultPort = 5432;
+  readonly defaultImage: string;
+  readonly environment: Record<string, string>;
+  connectionString: string;
+  started: boolean;
+  private client;
+  private originalConnectionString;
+  private schema;
+  constructor(options?: PostgresOptions);
+  buildConnectionString(host: string, port: number): string;
+  createDatabaseAdapter(): DatabasePort;
+  healthcheck(): Promise<void>;
+  initialize(composeDir: string): Promise<void>;
+  private getClient;
+  seed(sql: string): Promise<void>;
+  reset(): Promise<void>;
+  query(table: string, columns: string[]): Promise<unknown[][]>;
+  isolation(): IsolationStrategy;
+}
+/**
+ * Create a PostgreSQL service handle.
+ *
+ * @example
+ * const db = postgres({ compose: "db" });
+ * // After start: db.connectionString is populated
+ */
+declare function postgres(options?: PostgresOptions): PostgresHandle;
+//#endregion
+//#region src/adapters/redis.adapter.d.ts
+interface RedisOptions {
+  /** Map to a service in docker-compose.test.yaml. */
+  compose?: string;
+  /** Override image. */
+  image?: string;
+}
+declare class RedisHandle implements ServiceHandle {
+  readonly type = "redis";
+  readonly composeName: null | string;
+  readonly defaultPort = 6379;
+  readonly defaultImage: string;
+  readonly environment: Record<string, string>;
+  connectionString: string;
+  started: boolean;
+  private dbIndex;
+  constructor(options?: RedisOptions);
+  buildConnectionString(host: string, port: number): string;
+  createDatabaseAdapter(): DatabasePort | null;
+  healthcheck(): Promise<void>;
+  initialize(): Promise<void>;
+  reset(): Promise<void>;
+  isolation(): IsolationStrategy;
+}
+/**
+ * Create a Redis service handle.
+ *
+ * @example
+ * const cache = redis({ compose: "cache" });
+ * // After start: cache.connectionString is populated
+ */
+declare function redis(options?: RedisOptions): RedisHandle;
+//#endregion
+//#region src/adapters/sqlite.adapter.d.ts
+interface SqliteOptions {
+  /**
+   * Path to a SQL file used to initialize the database schema.
+   * Mutually exclusive with `prismaSchema`.
+   */
+  init?: string;
+  /**
+   * Path to a Prisma schema directory or file.
+   * The adapter runs `prisma db push` to create the template.
+   * Mutually exclusive with `init`.
+   */
+  prismaSchema?: string;
+}
+declare class SqliteHandle implements DatabasePort, ServiceHandle {
+  readonly type = "sqlite";
+  readonly composeName: null;
+  readonly defaultPort = 0;
+  readonly defaultImage = "";
+  readonly environment: Record<string, string>;
+  connectionString: string;
+  started: boolean;
+  private db;
+  private templatePath;
+  private workerDbPath;
+  private initSql;
+  private prismaSchema;
+  constructor(options?: SqliteOptions);
+  buildConnectionString(): string;
+  createDatabaseAdapter(): DatabasePort;
+  healthcheck(): Promise<void>;
+  initialize(): Promise<void>;
+  private getDb;
+  private closeDb;
+  seed(sql: string): Promise<void>;
+  query(table: string, columns: string[]): Promise<unknown[][]>;
+  reset(): Promise<void>;
+  isolation(): IsolationStrategy;
+}
+/**
+ * Create a SQLite service handle. Uses file-copy isolation for parallel tests.
+ *
+ * @example
+ *   // With Prisma schema
+ *   const db = sqlite({ prismaSchema: './prisma/schema' });
+ *
+ *   // With raw SQL init
+ *   const db = sqlite({ init: './schema.sql' });
+ *
+ *   // Empty database
+ *   const db = sqlite();
+ */
+declare function sqlite(options?: SqliteOptions): SqliteHandle;
+//#endregion
+export { PostgresOptions as a, IsolationStrategy as c, redis as i, DatabasePort as l, sqlite as n, postgres as o, RedisOptions as r, ServiceHandle as s, SqliteOptions as t };
+//# sourceMappingURL=sqlite.adapter.d.cts.map

package/dist/sqlite.adapter.d.ts

@@ -0,0 +1,209 @@
+//#region src/ports/database.port.d.ts
+/**
+ * Abstract database interface for specification runners.
+ * Implement this to plug in your database stack (e.g. Postgres, SQLite).
+ */
+interface DatabasePort {
+  /** Execute raw SQL (for seeding test data). */
+  seed(sql: string): Promise<void>;
+  /** Query a table and return rows as arrays of values. */
+  query(table: string, columns: string[]): Promise<unknown[][]>;
+  /** Reset database to clean state between tests. */
+  reset(): Promise<void>;
+}
+//#endregion
+//#region src/ports/isolation.port.d.ts
+/**
+ * Strategy for isolating service state across parallel test workers.
+ *
+ * Each service handle provides an isolation strategy. The framework
+ * calls `acquire()` once per vitest worker, `reset()` before each
+ * `spec.run()`, and `release()` when the worker shuts down.
+ *
+ * Implement this interface to support new service types (e.g. MongoDB,
+ * Elasticsearch, S3).
+ */
+interface IsolationStrategy {
+  /**
+   * Create an isolated namespace for this worker.
+   * Called once when the worker starts — e.g. clone a template database,
+   * set a Redis key prefix.
+   *
+   * @param workerId - Unique identifier for this vitest worker.
+   */
+  acquire(workerId: string): Promise<void>;
+  /**
+   * Fast reset within the namespace between `spec.run()` calls.
+   * E.g. truncate tables (without dropping the database).
+   */
+  reset(): Promise<void>;
+  /**
+   * Tear down the isolated namespace.
+   * Called once when the worker shuts down — e.g. drop the cloned database.
+   */
+  release(): Promise<void>;
+}
+//#endregion
+//#region src/ports/service.port.d.ts
+/**
+ * A service handle — returned by factory functions like postgres(), redis().
+ * Mutable: connectionString is populated after the orchestrator starts containers.
+ */
+interface ServiceHandle {
+  /** Service type identifier. */
+  readonly type: string;
+  /** Compose service name (if linked). */
+  readonly composeName: null | string;
+  /** Default container port for this service type. */
+  readonly defaultPort: number;
+  /** Default Docker image for this service type. */
+  readonly defaultImage: string;
+  /** Environment variables to pass to the container. */
+  readonly environment: Record<string, string>;
+  /** Connection string — populated after start. */
+  connectionString: string;
+  /** Whether this service has been started. */
+  started: boolean;
+  /** Build the connection string from host and port. */
+  buildConnectionString(host: string, port: number): string;
+  /** Create a DatabasePort adapter (if this is a database). Returns null otherwise. */
+  createDatabaseAdapter(): DatabasePort | null;
+  /** Verify the service is ready and accepting connections. Throws with context if not. */
+  healthcheck(): Promise<void>;
+  /** Run initialization scripts (e.g., init.sql). Throws with SQL error context if it fails. */
+  initialize(composeDir: string): Promise<void>;
+  /** Reset state between tests (truncate tables, flush cache, etc.) */
+  reset(): Promise<void>;
+  /** Get the isolation strategy for parallel test execution. */
+  isolation(): IsolationStrategy;
+}
+//#endregion
+//#region src/adapters/postgres.adapter.d.ts
+interface PostgresOptions {
+  /** Map to a service in docker-compose.test.yaml. */
+  compose?: string;
+  /** Override image. */
+  image?: string;
+  /** Override environment variables. */
+  env?: Record<string, string>;
+}
+declare class PostgresHandle implements DatabasePort, ServiceHandle {
+  readonly type = "postgres";
+  readonly composeName: null | string;
+  readonly defaultPort = 5432;
+  readonly defaultImage: string;
+  readonly environment: Record<string, string>;
+  connectionString: string;
+  started: boolean;
+  private client;
+  private originalConnectionString;
+  private schema;
+  constructor(options?: PostgresOptions);
+  buildConnectionString(host: string, port: number): string;
+  createDatabaseAdapter(): DatabasePort;
+  healthcheck(): Promise<void>;
+  initialize(composeDir: string): Promise<void>;
+  private getClient;
+  seed(sql: string): Promise<void>;
+  reset(): Promise<void>;
+  query(table: string, columns: string[]): Promise<unknown[][]>;
+  isolation(): IsolationStrategy;
+}
+/**
+ * Create a PostgreSQL service handle.
+ *
+ * @example
+ * const db = postgres({ compose: "db" });
+ * // After start: db.connectionString is populated
+ */
+declare function postgres(options?: PostgresOptions): PostgresHandle;
+//#endregion
+//#region src/adapters/redis.adapter.d.ts
+interface RedisOptions {
+  /** Map to a service in docker-compose.test.yaml. */
+  compose?: string;
+  /** Override image. */
+  image?: string;
+}
+declare class RedisHandle implements ServiceHandle {
+  readonly type = "redis";
+  readonly composeName: null | string;
+  readonly defaultPort = 6379;
+  readonly defaultImage: string;
+  readonly environment: Record<string, string>;
+  connectionString: string;
+  started: boolean;
+  private dbIndex;
+  constructor(options?: RedisOptions);
+  buildConnectionString(host: string, port: number): string;
+  createDatabaseAdapter(): DatabasePort | null;
+  healthcheck(): Promise<void>;
+  initialize(): Promise<void>;
+  reset(): Promise<void>;
+  isolation(): IsolationStrategy;
+}
+/**
+ * Create a Redis service handle.
+ *
+ * @example
+ * const cache = redis({ compose: "cache" });
+ * // After start: cache.connectionString is populated
+ */
+declare function redis(options?: RedisOptions): RedisHandle;
+//#endregion
+//#region src/adapters/sqlite.adapter.d.ts
+interface SqliteOptions {
+  /**
+   * Path to a SQL file used to initialize the database schema.
+   * Mutually exclusive with `prismaSchema`.
+   */
+  init?: string;
+  /**
+   * Path to a Prisma schema directory or file.
+   * The adapter runs `prisma db push` to create the template.
+   * Mutually exclusive with `init`.
+   */
+  prismaSchema?: string;
+}
+declare class SqliteHandle implements DatabasePort, ServiceHandle {
+  readonly type = "sqlite";
+  readonly composeName: null;
+  readonly defaultPort = 0;
+  readonly defaultImage = "";
+  readonly environment: Record<string, string>;
+  connectionString: string;
+  started: boolean;
+  private db;
+  private templatePath;
+  private workerDbPath;
+  private initSql;
+  private prismaSchema;
+  constructor(options?: SqliteOptions);
+  buildConnectionString(): string;
+  createDatabaseAdapter(): DatabasePort;
+  healthcheck(): Promise<void>;
+  initialize(): Promise<void>;
+  private getDb;
+  private closeDb;
+  seed(sql: string): Promise<void>;
+  query(table: string, columns: string[]): Promise<unknown[][]>;
+  reset(): Promise<void>;
+  isolation(): IsolationStrategy;
+}
+/**
+ * Create a SQLite service handle. Uses file-copy isolation for parallel tests.
+ *
+ * @example
+ *   // With Prisma schema
+ *   const db = sqlite({ prismaSchema: './prisma/schema' });
+ *
+ *   // With raw SQL init
+ *   const db = sqlite({ init: './schema.sql' });
+ *
+ *   // Empty database
+ *   const db = sqlite();
+ */
+declare function sqlite(options?: SqliteOptions): SqliteHandle;
+//#endregion
+export { PostgresOptions as a, IsolationStrategy as c, redis as i, DatabasePort as l, sqlite as n, postgres as o, RedisOptions as r, ServiceHandle as s, SqliteOptions as t };
+//# sourceMappingURL=sqlite.adapter.d.ts.map