@jterrazz/test 15.3.0 → 16.1.0

package/docs/reference/type-aliases/HonoApp.md

@@ -0,0 +1,31 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Type Alias: HonoApp
+
+```ts
+type HonoApp = object;
+```
+
+Defined in: [src/facets/api/api.specification.ts:20](https://github.com/jterrazz/package-test/blob/main/src/facets/api/api.specification.ts#L20)
+
+Any object with a request method compatible with Hono's app.request().
+
+## Properties
+
+### request
+
+```ts
+request: (path, init?) => Promise<Response> | Response;
+```
+
+Defined in: [src/facets/api/api.specification.ts:21](https://github.com/jterrazz/package-test/blob/main/src/facets/api/api.specification.ts#L21)
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `path` | `string` |
+| `init?` | `RequestInit` |
+
+#### Returns
+
+`Promise`\<`Response`\> \| `Response`

package/docs/reference/type-aliases/HttpContractFilter.md

@@ -0,0 +1,49 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Type Alias: HttpContractFilter
+
+```ts
+type HttpContractFilter = object;
+```
+
+Defined in: [src/model/contracts/http.ts:18](https://github.com/jterrazz/package-test/blob/main/src/model/contracts/http.ts#L18)
+
+Request filters for the generic HTTP provider. Every field is a subset
+constraint — a request matches when all provided fields match.
+
+## Properties
+
+### body?
+
+```ts
+optional body?: object | RegExp | string;
+```
+
+Defined in: [src/model/contracts/http.ts:24](https://github.com/jterrazz/package-test/blob/main/src/model/contracts/http.ts#L24)
+
+Body constraint. An object is a deep SUBSET match (toMatchObject-style)
+whose leaf values may be `match.*` matchers; a string is a containment
+test and a RegExp a `test()` over the raw text body.
+
+***
+
+### headers?
+
+```ts
+optional headers?: Record<string, RegExp | string>;
+```
+
+Defined in: [src/model/contracts/http.ts:26](https://github.com/jterrazz/package-test/blob/main/src/model/contracts/http.ts#L26)
+
+Header subset. Names are case-insensitive; string = exact value, RegExp = `test()`.
+
+***
+
+### query?
+
+```ts
+optional query?: Record<string, RegExp | string>;
+```
+
+Defined in: [src/model/contracts/http.ts:28](https://github.com/jterrazz/package-test/blob/main/src/model/contracts/http.ts#L28)
+
+Query-param subset. string = exact value, RegExp = `test()`.

package/docs/reference/type-aliases/HttpResponseInit.md

@@ -0,0 +1,46 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Type Alias: HttpResponseInit
+
+```ts
+type HttpResponseInit = object;
+```
+
+Defined in: [src/model/contracts/http.ts:77](https://github.com/jterrazz/package-test/blob/main/src/model/contracts/http.ts#L77)
+
+Init options shared by the response builders.
+
+## Properties
+
+### delay?
+
+```ts
+optional delay?: number;
+```
+
+Defined in: [src/model/contracts/http.ts:79](https://github.com/jterrazz/package-test/blob/main/src/model/contracts/http.ts#L79)
+
+Delay in ms before responding (for timeout testing).
+
+***
+
+### headers?
+
+```ts
+optional headers?: Record<string, string>;
+```
+
+Defined in: [src/model/contracts/http.ts:81](https://github.com/jterrazz/package-test/blob/main/src/model/contracts/http.ts#L81)
+
+Response headers, merged over the builder's own.
+
+***
+
+### status?
+
+```ts
+optional status?: number;
+```
+
+Defined in: [src/model/contracts/http.ts:83](https://github.com/jterrazz/package-test/blob/main/src/model/contracts/http.ts#L83)
+
+HTTP status code.

package/docs/reference/type-aliases/HttpStreamInit.md

@@ -0,0 +1,58 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Type Alias: HttpStreamInit
+
+```ts
+type HttpStreamInit = object;
+```
+
+Defined in: [src/model/contracts/http.ts:32](https://github.com/jterrazz/package-test/blob/main/src/model/contracts/http.ts#L32)
+
+Init options for a streamed reply.
+
+## Properties
+
+### contentType?
+
+```ts
+optional contentType?: string;
+```
+
+Defined in: [src/model/contracts/http.ts:34](https://github.com/jterrazz/package-test/blob/main/src/model/contracts/http.ts#L34)
+
+The `content-type` the stream is served under. Default `application/octet-stream`.
+
+***
+
+### delay?
+
+```ts
+optional delay?: number;
+```
+
+Defined in: [src/model/contracts/http.ts:36](https://github.com/jterrazz/package-test/blob/main/src/model/contracts/http.ts#L36)
+
+Milliseconds between two chunks. Default 0 — every chunk at once.
+
+***
+
+### headers?
+
+```ts
+optional headers?: Record<string, string>;
+```
+
+Defined in: [src/model/contracts/http.ts:38](https://github.com/jterrazz/package-test/blob/main/src/model/contracts/http.ts#L38)
+
+Response headers, merged over the builder's own.
+
+***
+
+### status?
+
+```ts
+optional status?: number;
+```
+
+Defined in: [src/model/contracts/http.ts:40](https://github.com/jterrazz/package-test/blob/main/src/model/contracts/http.ts#L40)
+
+HTTP status code. Default 200.

package/docs/reference/type-aliases/IntegrationHandle.md

@@ -0,0 +1,46 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Type Alias: IntegrationHandle\<Services, DatabaseKey\>
+
+```ts
+type IntegrationHandle<Services, DatabaseKey> = object;
+```
+
+Defined in: [src/facets/integration/integration.specification.ts:34](https://github.com/jterrazz/package-test/blob/main/src/facets/integration/integration.specification.ts#L34)
+
+The record returned by startIntegration \| specification.integration.
+Destructure with the canonical names (CONVENTIONS A3):
+
+    const { integration, cleanup } = await specification.integration(…);
+
+## Type Parameters
+
+| Type Parameter | Default type |
+| ------ | ------ |
+| `Services` *extends* [`ServiceRecord`](ServiceRecord.md) | [`ServiceRecord`](ServiceRecord.md) |
+| `DatabaseKey` *extends* `string` | `string` |
+
+## Properties
+
+### cleanup
+
+```ts
+cleanup: () => Promise<void>;
+```
+
+Defined in: [src/facets/integration/integration.specification.ts:39](https://github.com/jterrazz/package-test/blob/main/src/facets/integration/integration.specification.ts#L39)
+
+Stop all infrastructure started by this specification.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+***
+
+### integration
+
+```ts
+integration: IntegrationSpecification<Services, DatabaseKey>;
+```
+
+Defined in: [src/facets/integration/integration.specification.ts:40](https://github.com/jterrazz/package-test/blob/main/src/facets/integration/integration.specification.ts#L40)

package/docs/reference/type-aliases/IntegrationSpecification.md

@@ -0,0 +1,111 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Type Alias: IntegrationSpecification\<Services, DatabaseKey\>
+
+```ts
+type IntegrationSpecification<Services, DatabaseKey> = object;
+```
+
+Defined in: [src/model/chain/builder.ts:237](https://github.com/jterrazz/package-test/blob/main/src/model/chain/builder.ts#L237)
+
+The `integration` facet — the in-process chain handed out by
+`specification.integration()`.
+
+The subject is a MODULE, not an entry: no HTTP, no binary, no page. What
+makes it a spec rather than a module test is what it stands on — real
+services, declared contracts, a golden — so it takes the same setups as
+every other facet and ends on the one action a module has: being called.
+
+## Type Parameters
+
+| Type Parameter | Default type |
+| ------ | ------ |
+| `Services` *extends* `Record`\<`string`, `unknown`\> | `Record`\<`string`, `unknown`\> |
+| `DatabaseKey` *extends* `string` | `string` |
+
+## Properties
+
+### call
+
+```ts
+call: <T>(subject) => Promise<CallResult<T>>;
+```
+
+Defined in: [src/model/chain/builder.ts:256](https://github.com/jterrazz/package-test/blob/main/src/model/chain/builder.ts#L256)
+
+Call the module and resolve with what it produced. The started services
+record is handed in, so the subject is constructed with the real
+connection strings rather than with a double.
+
+#### Type Parameters
+
+| Type Parameter |
+| ------ |
+| `T` |
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `subject` | (`services`) => `Promise`\<`T`\> \| `T` |
+
+#### Returns
+
+`Promise`\<[`CallResult`](../interfaces/CallResult.md)\<`T`\>\>
+
+***
+
+### clock
+
+```ts
+clock: (iso) => IntegrationSpecification<Services, DatabaseKey>;
+```
+
+Defined in: [src/model/chain/builder.ts:242](https://github.com/jterrazz/package-test/blob/main/src/model/chain/builder.ts#L242)
+
+Pin the module's `Date` at `iso` for this chain.
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `iso` | `string` |
+
+#### Returns
+
+`IntegrationSpecification`\<`Services`, `DatabaseKey`\>
+
+***
+
+### intercept
+
+```ts
+intercept: InterceptMethod<IntegrationSpecification<Services, DatabaseKey>>;
+```
+
+Defined in: [src/model/chain/builder.ts:244](https://github.com/jterrazz/package-test/blob/main/src/model/chain/builder.ts#L244)
+
+Declare outgoing calls — a contract, a list, a composite, or an inline request + response pair.
+
+***
+
+### seed
+
+```ts
+seed: (file, options?) => IntegrationSpecification<Services, DatabaseKey>;
+```
+
+Defined in: [src/model/chain/builder.ts:246](https://github.com/jterrazz/package-test/blob/main/src/model/chain/builder.ts#L246)
+
+Queue a SQL seed file from `_seeds/` to run before the call.
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `file` | `string` |
+| `options?` | \{ `database?`: `DatabaseKey`; \} |
+| `options.database?` | `DatabaseKey` |
+
+#### Returns
+
+`IntegrationSpecification`\<`Services`, `DatabaseKey`\>

package/docs/reference/type-aliases/IntegrationSpecificationOptions.md

@@ -0,0 +1,42 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Type Alias: IntegrationSpecificationOptions\<Services\>
+
+```ts
+type IntegrationSpecificationOptions<Services> = object;
+```
+
+Defined in: [src/facets/integration/integration.specification.ts:17](https://github.com/jterrazz/package-test/blob/main/src/facets/integration/integration.specification.ts#L17)
+
+Options for startIntegration \| specification.integration.
+
+## Type Parameters
+
+| Type Parameter | Default type |
+| ------ | ------ |
+| `Services` *extends* [`ServiceRecord`](ServiceRecord.md) | [`ServiceRecord`](ServiceRecord.md) |
+
+## Properties
+
+### root?
+
+```ts
+optional root?: string;
+```
+
+Defined in: [src/facets/integration/integration.specification.ts:19](https://github.com/jterrazz/package-test/blob/main/src/facets/integration/integration.specification.ts#L19)
+
+Project-root override — see the `root` option of `specification.api()`.
+
+***
+
+### services?
+
+```ts
+optional services?: Services;
+```
+
+Defined in: [src/facets/integration/integration.specification.ts:25](https://github.com/jterrazz/package-test/blob/main/src/facets/integration/integration.specification.ts#L25)
+
+Named infrastructure the module is specified AGAINST — a real database,
+a real cache, a `process()` it talks to. Omit it for the other half of
+the facet: a pure module whose oracle is a golden.

package/docs/reference/type-aliases/Intercept.md

@@ -0,0 +1,19 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Type Alias: Intercept
+
+```ts
+type Intercept = (contracts, options?) => Promise<InterceptScope> & (request, response, options?) => Promise<InterceptScope>;
+```
+
+Defined in: [src/model/contracts/intercept.ts:54](https://github.com/jterrazz/package-test/blob/main/src/model/contracts/intercept.ts#L54)
+
+The module-scope network double. Resolves once the engine is listening —
+which is why it is a promise, and why the canonical form awaits it:
+
+```typescript
+await using _ = await intercept(http.get(url), http.json({ ok: true }));
+```
+
+Without that `await` the subject could reach the real network before the
+first handler is in place, so the shape refuses the racy spelling: a promise
+is not an `AsyncDisposable`, and the compiler says so.

package/docs/reference/type-aliases/InterceptOptions.md

@@ -0,0 +1,28 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Type Alias: InterceptOptions
+
+```ts
+type InterceptOptions = object;
+```
+
+Defined in: [src/model/contracts/intercept.ts:29](https://github.com/jterrazz/package-test/blob/main/src/model/contracts/intercept.ts#L29)
+
+What a scope may state about the network it declares.
+
+## Properties
+
+### origin?
+
+```ts
+optional origin?: string;
+```
+
+Defined in: [src/model/contracts/intercept.ts:39](https://github.com/jterrazz/package-test/blob/main/src/model/contracts/intercept.ts#L39)
+
+The base a RELATIVE request resolves against, for the life of the scope.
+
+A module that calls `fetch('/api/posts')` is browser code: under node the
+URL cannot be parsed at all, so the request fails before any contract can
+answer it and the test's only way out was to replace `fetch` itself. With
+an origin stated, the relative call resolves here and the declared
+contracts — path form or absolute — match it as they would any other.

package/docs/reference/type-aliases/InterceptScope.md

@@ -0,0 +1,11 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Type Alias: InterceptScope
+
+```ts
+type InterceptScope = AsyncDisposable;
+```
+
+Defined in: [src/model/contracts/intercept.ts:26](https://github.com/jterrazz/package-test/blob/main/src/model/contracts/intercept.ts#L26)
+
+One block's worth of declared network. Disposed at the end of the scope that
+declared it: the handlers are dropped, and an unmatched request is thrown.

package/docs/reference/type-aliases/IsolationStrategy.md

@@ -0,0 +1,75 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Type Alias: IsolationStrategy
+
+```ts
+type IsolationStrategy = object;
+```
+
+Defined in: [src/model/ports/isolation.port.ts:11](https://github.com/jterrazz/package-test/blob/main/src/model/ports/isolation.port.ts#L11)
+
+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).
+
+## Properties
+
+### acquire
+
+```ts
+acquire: (workerId) => Promise<void>;
+```
+
+Defined in: [src/model/ports/isolation.port.ts:19](https://github.com/jterrazz/package-test/blob/main/src/model/ports/isolation.port.ts#L19)
+
+Create an isolated namespace for this worker.
+Called once when the worker starts — e.g. clone a template database,
+set a Redis key prefix.
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `workerId` | `string` | Unique identifier for this vitest worker. |
+
+#### Returns
+
+`Promise`\<`void`\>
+
+***
+
+### release
+
+```ts
+release: () => Promise<void>;
+```
+
+Defined in: [src/model/ports/isolation.port.ts:31](https://github.com/jterrazz/package-test/blob/main/src/model/ports/isolation.port.ts#L31)
+
+Tear down the isolated namespace.
+Called once when the worker shuts down — e.g. drop the cloned database.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+***
+
+### reset
+
+```ts
+reset: () => Promise<void>;
+```
+
+Defined in: [src/model/ports/isolation.port.ts:25](https://github.com/jterrazz/package-test/blob/main/src/model/ports/isolation.port.ts#L25)
+
+Fast reset within the namespace between `spec.run()` calls.
+E.g. truncate tables (without dropping the database).
+
+#### Returns
+
+`Promise`\<`void`\>

package/docs/reference/type-aliases/JobHandle.md

@@ -0,0 +1,34 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Type Alias: JobHandle
+
+```ts
+type JobHandle = object;
+```
+
+Defined in: [src/model/chain/builder.ts:36](https://github.com/jterrazz/package-test/blob/main/src/model/chain/builder.ts#L36)
+
+A named job that can be triggered via jobs.trigger().
+
+## Properties
+
+### execute
+
+```ts
+execute: () => Promise<void>;
+```
+
+Defined in: [src/model/chain/builder.ts:38](https://github.com/jterrazz/package-test/blob/main/src/model/chain/builder.ts#L38)
+
+#### Returns
+
+`Promise`\<`void`\>
+
+***
+
+### name
+
+```ts
+name: string;
+```
+
+Defined in: [src/model/chain/builder.ts:37](https://github.com/jterrazz/package-test/blob/main/src/model/chain/builder.ts#L37)

package/docs/reference/type-aliases/JobsHandle.md

@@ -0,0 +1,57 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Type Alias: JobsHandle\<DatabaseKey\>
+
+```ts
+type JobsHandle<DatabaseKey> = object;
+```
+
+Defined in: [src/facets/jobs/jobs.specification.ts:37](https://github.com/jterrazz/package-test/blob/main/src/facets/jobs/jobs.specification.ts#L37)
+
+The record returned by startJobs \| specification.jobs. Destructure
+with the canonical names (CONVENTIONS A3):
+
+    const { jobs, cleanup } = await specification.jobs(…);
+
+## Type Parameters
+
+| Type Parameter | Default type |
+| ------ | ------ |
+| `DatabaseKey` *extends* `string` | `string` |
+
+## Properties
+
+### cleanup
+
+```ts
+cleanup: () => Promise<void>;
+```
+
+Defined in: [src/facets/jobs/jobs.specification.ts:39](https://github.com/jterrazz/package-test/blob/main/src/facets/jobs/jobs.specification.ts#L39)
+
+Stop all infrastructure started by this specification.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+***
+
+### jobs
+
+```ts
+jobs: JobsSpecification<DatabaseKey>;
+```
+
+Defined in: [src/facets/jobs/jobs.specification.ts:40](https://github.com/jterrazz/package-test/blob/main/src/facets/jobs/jobs.specification.ts#L40)
+
+***
+
+### orchestrator
+
+```ts
+orchestrator: null | Orchestrator;
+```
+
+Defined in: [src/facets/jobs/jobs.specification.ts:42](https://github.com/jterrazz/package-test/blob/main/src/facets/jobs/jobs.specification.ts#L42)
+
+The orchestrator managing the test infrastructure lifecycle.

package/docs/reference/type-aliases/JobsResult.md

@@ -0,0 +1,16 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Type Alias: JobsResult
+
+```ts
+type JobsResult = Omit<BaseResult, "directory" | "file">;
+```
+
+Defined in: [src/model/chain/builder.ts:214](https://github.com/jterrazz/package-test/blob/main/src/model/chain/builder.ts#L214)
+
+What a triggered job HANDS BACK.
+
+A job writes to a database, a cache, a queue — never to a working directory
+the spec then walks, because a job has none: it runs in this process, where
+the only filesystem is the repository's. So the two accessors that read one
+(`file()`, `directory()`) are not on this result. A pipeline that really
+produces files is a binary, and `specification.cli()` is its facet.