Testing API
Generated public TypeScript reference for @relkit/testing.
Common APIs
For configuration and examples, read testing, first service, first route.
For a complete workflow, follow cache product prices, build an offline agent.
Public imports
@relkit/testing— 72 exports@relkit/testing/drizzle— 3 exports@relkit/testing/better-auth— 3 exports
All exported APIs
Names link to their complete contracts. Re-exports share their original contract; legacy exports keep their separate identity. Examples link to the API’s inline sample, a maintained repository usage, or the shared module walkthrough.
application-acquisition.ts
Acquires the general runtime and explicitly selected application services in one scope.
acquireApplication
Native application work shares one scope and reverse-order cleanup policy.
Signature
declare const acquireApplication: (
app: { readonly env: object },
options: TestApplicationOptions,
) => Effect.Effect<ApplicationHarness, unknown, Scope | TestApplicationPlatform>;application-cleanup.ts
Finalizers preserve sibling release and report every application cleanup failure.
cleanup
Collects release failures and retains them in the Cause when acquisition already failed.
Signature
declare const cleanup: (
release: () => Promise<unknown> | undefined,
failures: unknown[],
failed?: boolean,
) => Effect.Effect<void>;application-drizzle-services.ts
Selected database-only test acquisition; authentication SDKs are never imported.
activateDrizzleTestServices
Acquires the sole database and releases it exactly once with the returned owner.
Signature
declare const activateDrizzleTestServices: TestServiceActivator;application-errors.ts
Normalizes foreign acquisition rejections without replacing native Error identity.
nativeServiceError
Normalizes foreign acquisition rejections without replacing native Error identity.
Signature
declare const nativeServiceError: <Failure>(cause: Failure) => Error;application-generic-services.ts
General application acquisition never imports a native database or authentication SDK.
activateGenericTestServices
Rejects an unselected native helper before returning an incomplete application.
Signature
declare const activateGenericTestServices: TestServiceActivator;application-http.ts
handleTestRequest
Dispatches a matched route through existing engine validation and error mapping.
Signature
declare const handleTestRequest: (
routes: readonly TestRoute[],
runtime: TestRuntime,
request: Request,
) => Promise<Response>;application-native-services.types.ts
Drizzle/Better Auth contracts reachable only through the selected testing helper.
ApplicationServicesPlatform (interface)
Native dependencies substituted by test Layers without replacing ownership.
Signature
export interface ApplicationServicesPlatform {
readonly load: (
root: string,
) => Effect.Effect<readonly DescriptorAny[], Error | SourceLocationError>;
readonly database: typeof activateDrizzleService;
readonly auth: typeof activateBetterAuthService;
}AuthDeclaration (type alias)
Signature
type AuthDeclaration = Parameters<typeof activateBetterAuthService>[0];DatabaseDeclaration (type alias)
Signature
type DatabaseDeclaration = Parameters<typeof activateDrizzleService>[0];NativeAuth (type alias)
Signature
type NativeAuth = Awaited<ReturnType<typeof activateBetterAuthService>>;NativeDatabase (type alias)
Signature
type NativeDatabase = Awaited<ReturnType<typeof activateDrizzleService>>;application-platform.ts
Replaceable application operations and owned harness authorities.
TestApplicationHarness (class)
Resources and release failures owned by one application Layer scope.
Signature
declare class TestApplicationHarnessTestApplicationPlatform (class)
Native application dependencies substituted before acquisition.
Signature
declare class TestApplicationPlatformTestApplicationPlatformLive
General live platform; selected native helpers enter through explicit options.
Signature
declare const TestApplicationPlatformLive: Layer.Layer<TestApplicationPlatform, never, never>;application-realtime.ts
bindTestRealtime
Binds registered realtime contracts to the acquired test provider generation.
Signature
declare const bindTestRealtime: (
runtime: TestRuntime,
artifacts: TestApplicationArtifacts | undefined,
providers: ProviderRegistry | undefined,
environment: string,
) => TestRuntime;application-registry.ts
Loads fresh generated modules with their original native import ancestry and guarded SDK resolution.
TestApplicationArtifacts
Signature
declare const TestApplicationArtifacts: TestApplicationArtifacts;loadTestApplicationArtifacts
Loads the generated graph, handlers, and selected integration modules for one test generation.
Signature
declare const loadTestApplicationArtifacts: (
root: string,
) => Promise<TestApplicationArtifacts | undefined>;application-registry.types.ts
TestApplicationArtifacts (interface)
Compiled graph, registry and native integration evidence acquired by an application.
Signature
export interface TestApplicationArtifacts {
readonly graph: FunctionRegistryOptions["graph"];
readonly publicFingerprint: string;
readonly registry: FunctionRegistry;
readonly runtimeIntegrationModules: readonly LoadedRuntimeIntegrationModule[];
}application-request.ts
Routes application test HTTP through actual runtime invocation and selected service authorities. Request-local auth and context patches are evaluated per request under the application’s owned runtime.
createApplicationRequest
Binds HTTP admission and request-local authentication to an acquired runtime.
Signature
declare const createApplicationRequest: (
routes: readonly TestRoute[],
applicationRuntime: TestRuntime,
services: TestApplicationServices,
context: Record<string, unknown>,
) => TestHttpApplication;application-routes.ts
TestFunctionRoute
Signature
declare const TestFunctionRoute: TestFunctionRoute;TestRawRoute
Signature
declare const TestRawRoute: TestRawRoute;TestRoute
Signature
declare const TestRoute: TestRoute;loadTestRoutes
Loads filesystem routes and derives native request/response contracts.
Signature
declare const loadTestRoutes: (root: string) => Promise<readonly TestRoute[]>;application-routes.types.ts
AuthoredRoute (type alias)
Native authored route descriptor accepted by application HTTP wiring.
Signature
type AuthoredRoute = Omit<TestFunctionRoute, "method" | "path" | "request" | "responses"> & {
readonly accept?: "application/json" | "multipart/form-data";
readonly request?: unknown;
readonly responses?: TestFunctionRoute["responses"];
readonly successStatus?: number;
};TestFunctionRoute (type alias)
Native function-backed HTTP route and its declared exposure/validation contract.
Signature
type TestFunctionRoute = {
readonly method: string;
readonly path: string;
readonly request: unknown;
readonly target: Parameters<TestRuntime["invoke"]>[0] & {
readonly input: StandardSchemaV1;
readonly output: StandardSchemaV1;
readonly errors?: readonly {
readonly id: string;
readonly data: StandardSchemaV1;
readonly http?: { readonly status: number };
}[];
};
readonly responses: readonly {
readonly kind?: string;
readonly id?: string;
readonly status?: number;
readonly errorId?: string;
}[];
};TestRawRoute (type alias)
Raw native HTTP route preserving its original handler and method contract.
Signature
type TestRawRoute = {
readonly method: "ALL";
readonly path: string;
readonly handler: (request: Request) => Response | Promise<Response>;
readonly auth?: { readonly protected: readonly string[] };
};TestRoute (type alias)
Supported native function or raw HTTP route declaration.
Signature
type TestRoute = TestFunctionRoute | TestRawRoute;application-service-auth.ts
Composes auth over a borrowed database without taking a second disposal authority.
acquireApplicationAuth
Acquires the optional native auth handler and its protection runtime.
Signature
declare const acquireApplicationAuth: (
platform: ApplicationServicesPlatform,
declaration: BetterAuthServiceDescriptor<BetterAuthServiceOptions> | undefined,
database: DrizzleActivation<DrizzleServiceDescriptor<any, any, any, any>> | undefined,
routes: ReadonlyArray<TestRoute>,
) => Effect.Effect<Pick<TestApplicationServices, "auth" | "authHandler">, Error, never>;nativeServiceError
Signature
declare const nativeServiceError: <Failure>(cause: Failure) => Error;application-service-discovery.ts
Finds native service declarations through the shared, syntax-only layout model.
loadApplicationServices
Loads only evidenced boundaries, in deterministic order, without activating clients.
Signature
declare const loadApplicationServices: (
root: string,
) => Effect.Effect<Array<DescriptorAny>, Error, never>;soleNativeService
Selects the sole native declaration by its capability discriminator.
Throws
Error When more than one declaration owns the capability.
Signature
declare const soleNativeService: <Kind extends "drizzle" | "better-auth">(
services: readonly DescriptorAny[],
kind: Kind,
) => DescriptorAny | undefined;application-services.ts
Owns scoped database/auth activation for a test application in either service layout.
ApplicationServicesPlatform
Signature
declare const ApplicationServicesPlatform: ApplicationServicesPlatform;TestApplicationServices
Signature
declare const TestApplicationServices: TestApplicationServices;TestServices (class)
Database and authentication authorities whose lifetime follows their Layer.
Signature
declare class TestServicesTestServicesPlatform (class)
Native activation dependencies acquired once per application owner.
Signature
declare class TestServicesPlatformTestServicesPlatformLive
Live native adapters; no database or auth client is acquired by this Layer.
Signature
declare const TestServicesPlatformLive: Layer.Layer<TestServicesPlatform, never, never>;activateTestServices
Acquires services with an idempotent native shutdown hook.
Signature
declare const activateTestServices: (
root: string,
env: ServiceEnvironment,
routes: readonly TestRoute[],
) => Promise<TestApplicationServices>;testServicesLayer
Builds an owner-scoped Layer over replaceable native dependencies.
Signature
declare const testServicesLayer: (
root: string,
env: ServiceEnvironment,
routes: readonly TestRoute[],
) => Layer.Layer<TestServices, Error, TestServicesPlatform>;application-services.types.ts
Native application service ownership and replaceable activation dependencies.
ServiceEnvironment (type alias)
Uses the existing generic runtime’s environment contract without an SDK dependency.
Signature
type ServiceEnvironment = TestRuntime["env"];TestApplicationServices (interface)
Acquired owner-specific authorities; auth borrows the sole database.
Signature
export interface TestApplicationServices {
readonly context: NonNullable<TestRuntimeOptions["context"]>;
readonly auth?: HttpAuthRuntime;
readonly authHandler?: (request: Request) => Promise<Response>;
readonly close: () => Promise<void>;
}TestServiceActivator (type alias)
Explicit capability helper selected before application acquisition.
Signature
type TestServiceActivator = (
root: string,
env: ServiceEnvironment,
routes: readonly TestRoute[],
) => Promise<TestApplicationServices>;application.ts
General test application ownership with explicitly selected capability helpers.
createTestApplication
Creates an application owner with HTTP, deterministic runtime and provider services.
Example
import { defineEnv } from "@relkit/app/config";
import { createTestApplication } from "@relkit/testing";
async function testApplication(projectRoot: string): Promise<void> {
const app = await createTestApplication({ env: defineEnv({}) }, { projectRoot });
try {
await app.http.get("/");
} finally {
await app.close();
}
}Signature
declare const createTestApplication: (
app: { readonly env: object },
options?: TestApplicationOptions,
) => Promise<TestApplication>;Since v0.1.0
TestApplication
Signature
declare const TestApplication: TestApplication;TestApplicationHarness
Signature
declare const TestApplicationHarness: typeof TestApplicationHarness;TestApplicationOptions
Signature
declare const TestApplicationOptions: TestApplicationOptions;TestApplicationPlatform
Signature
declare const TestApplicationPlatform: typeof TestApplicationPlatform;TestApplicationPlatformLive
Signature
declare const TestApplicationPlatformLive: Layer.Layer<TestApplicationPlatform, never, never>;testApplicationLayer
Acquires the application scope using replaceable platform operations.
Signature
declare const testApplicationLayer: (
app: { readonly env: object },
options?: TestApplicationOptions,
) => Layer.Layer<TestApplicationHarness, unknown, TestApplicationPlatform>;application.types.ts
Describes the owned test application and replaceable acquisition platform. Generic contracts retain existing runtime environment/context semantics without a native auth or database SDK edge.
ApplicationHarness (interface)
Effect-owned application request workflow and native application state.
Signature
export interface ApplicationHarness {
readonly value: Omit<TestApplication, "close">;
readonly cleanupFailures: unknown[];
}ApplicationPlatform (interface)
Replaceable application acquisition operations used by the owning service Layer.
Signature
export interface ApplicationPlatform {
readonly artifacts: typeof loadTestApplicationArtifacts;
readonly routes: typeof loadTestRoutes;
readonly providers: typeof activateTestProviders;
readonly services: TestServiceActivator;
}TestApplication (interface)
Owned compiled test application, direct HTTP facade and complete release boundary.
Signature
export interface TestApplication {
readonly runtime: TestRuntime;
readonly http: TestHttpClient;
readonly clock: TestClock;
readonly fakes: TestFakes;
readonly observability: TestObservability;
readonly close: () => Promise<void>;
}TestApplicationOptions (type alias)
Explicit test application project, environment and native platform inputs.
Signature
type TestApplicationOptions = Omit<TestRuntimeOptions, "app"> & {
readonly projectRoot?: string;
readonly bindingValues?: Readonly<Record<string, JsonValue>>;
readonly resourceProviders?: "configured" | "fake";
readonly services?: TestServiceActivator;
};better-auth.ts
Explicit database-backed authentication test application facade.
TestApplication
Signature
declare const TestApplication: TestApplication;TestApplicationOptions
Signature
declare const TestApplicationOptions: TestApplicationOptions;createTestApplication
Acquires auth over a borrowed database while preserving general harness ownership.
Signature
declare const createTestApplication: (
app: { readonly env: object },
options?: TestApplicationOptions,
) => Promise<TestApplication>;bucket-storage.schemas.ts
BucketStorageSnapshot
Schema authority for detached native fake bucket transfers.
Signature
declare const BucketStorageSnapshot: Schema.Struct<{
readonly bucketId: Schema.String;
readonly records: Schema.$Array<
Schema.Struct<{
readonly key: Schema.String;
readonly bytes: Schema.Uint8Array;
readonly metadata: Schema.Struct<{
readonly etag: Schema.String;
readonly contentHash: Schema.optionalKey<Schema.String>;
readonly size: Schema.optionalKey<Schema.Finite>;
readonly contentType: Schema.optionalKey<Schema.String>;
readonly metadata: Schema.optionalKey<Schema.$Record<Schema.String, Schema.String>>;
}>;
}>
>;
}>;bucket-storage.ts
TestBucketStorage (class)
Authoritative writable bucket state; every public read returns detached bytes/metadata.
Signature
declare class TestBucketStoragebucketStorageLayer
Owns one isolated bucket, validating options before allocating its temporary root.
Signature
declare const bucketStorageLayer: (
options?: TestBucketFakeOptions,
) => Layer.Layer<TestBucketStorage, never, never>;bucket-storage.types.ts
BucketStorageService (interface)
Effect decisions over authoritative writable bucket bytes and native metadata.
Signature
export interface BucketStorageService {
readonly stateRoot: string;
readonly put: (
...args: Parameters<NonNullable<BucketProvider["put"]>>
) => Effect.Effect<void, unknown>;
readonly get: (
...args: Parameters<NonNullable<BucketProvider["get"]>>
) => Effect.Effect<Uint8Array | undefined, unknown>;
readonly head: (
...args: Parameters<NonNullable<BucketProvider["head"]>>
) => Effect.Effect<BucketObjectMetadata | undefined, unknown>;
readonly delete: (
...args: Parameters<NonNullable<BucketProvider["delete"]>>
) => Effect.Effect<void, unknown>;
readonly exists: (
...args: Parameters<NonNullable<BucketProvider["exists"]>>
) => Effect.Effect<boolean, unknown>;
readonly list: (
...args: Parameters<NonNullable<BucketProvider["list"]>>
) => Effect.Effect<readonly string[], unknown>;
readonly inspect: Effect.Effect<readonly TestBucketObject[]>;
readonly snapshot: Effect.Effect<BucketStorageSnapshot>;
readonly restore: (snapshot: unknown) => Effect.Effect<void, unknown>;
readonly clear: Effect.Effect<void>;
readonly close: Effect.Effect<void>;
}BucketStorageSnapshot (type alias)
Detached native bucket transfer derived from its decoding schema authority.
Signature
type BucketStorageSnapshot = typeof SnapshotSchema.Type;bucket-validation.ts
assertBucketKey
Rejects unsafe or empty native bucket keys.
Signature
declare const assertBucketKey: (value: string) => void;assertBucketPrefix
Validates the existing optional bucket listing prefix.
Signature
declare const assertBucketPrefix: (value: string) => string;copyBucketMetadata
Detaches nested native bucket metadata.
Signature
declare const copyBucketMetadata: (
value: BucketObjectMetadata | undefined,
) => BucketObjectMetadata | undefined;copyBucketObject
Detaches stored bytes and nested native metadata.
Signature
declare const copyBucketObject: (value: TestBucketObject) => TestBucketObject;buckets-types.ts
Preserved compatibility entrypoint for the canonical domain type companion.
“./buckets.types.js” (namespace export)
Re-exports all named exports from the “./buckets.types.js” module.
Signature
export * from "./buckets.types.js";buckets.ts
TestBucketFake
Signature
declare const TestBucketFake: TestBucketFake;TestBucketFakeOptions
Signature
declare const TestBucketFakeOptions: TestBucketFakeOptions;TestBucketObject
Signature
declare const TestBucketObject: TestBucketObject;createTestBucket
Signature
declare const createTestBucket: (options?: TestBucketFakeOptions) => TestBucketFake;createTestBucketFake
Creates an authoritative in-memory provider behind the production Promise client.
See
- tests/fixtures/checked-examples.ts ownedHelpersExample for checked resource ownership.
Signature
declare const createTestBucketFake: (options?: TestBucketFakeOptions) => TestBucketFake;buckets.types.ts
TestBucketFake (interface)
Owned native bucket client with deterministic transfer and inspection controls.
Signature
export interface TestBucketFake extends BucketClient {
readonly capabilities: { readonly signedReadUrl: false; readonly signedWriteUrl: false };
readonly provider: BucketProvider;
readonly client: BucketClient;
readonly stateRoot: string;
readonly seed: (key: string, bytes: Uint8Array, options?: BucketPutOptions) => Promise<void>;
readonly read: (key: string) => Promise<Uint8Array | undefined>;
readonly inspect: () => readonly TestBucketObject[];
readonly snapshot: () => import("./bucket-storage.types.js").BucketStorageSnapshot;
readonly restore: (snapshot: unknown) => void;
readonly clear: () => void;
readonly close: () => Promise<void>;
}TestBucketFakeOptions (interface)
Bucket write policy and explicit clock, root and failure dependencies.
Signature
export interface TestBucketFakeOptions {
readonly bucketId?: string;
readonly ownerId?: string;
readonly stateRoot?: string;
readonly clock?: () => number;
readonly failures?: TestFailureControls;
readonly logger?: import("@relkit/runtime-effect").LoggerOptions;
readonly maxObjectBytes?: number;
readonly allowedContentTypes?: readonly string[];
}TestBucketObject (interface)
Detached native bucket bytes and metadata selected by a stable key.
Signature
export interface TestBucketObject {
readonly key: string;
readonly bytes: Uint8Array;
readonly metadata: BucketObjectMetadata;
}cache-storage-state.ts
cacheStorageOperations
Binds native cache validation and committed mutations to one authoritative Ref.
Signature
declare const cacheStorageOperations: (
state: Ref.Ref<CacheStorageState>,
policy: CacheStoragePolicy,
) => {
open: () => CacheStorageState;
keyOf: (key: unknown) => string;
active: (context: CacheOperationContext | undefined) => number;
readEntry: (key: unknown, context: CacheOperationContext | undefined) => CacheEntry | undefined;
writeEntry: (
key: unknown,
value: unknown,
write: CacheOperationOptions | undefined,
context: CacheOperationContext | undefined,
) => void;
};cache-storage.schemas.ts
CacheStorageKey
Restored keys retain the canonical identity produced by the native fake.
Signature
declare const CacheStorageKey: Schema.Struct<{
readonly cacheId: Schema.String;
readonly schemaVersion: Schema.Union<readonly [Schema.String, Schema.Number]>;
readonly key: Schema.Unknown;
}>;CacheStorageSnapshot
Detached storage transfer; restoring requires matching cache identity/version.
Signature
declare const CacheStorageSnapshot: Schema.Struct<{
readonly cacheId: Schema.String;
readonly schemaVersion: Schema.Union<readonly [Schema.String, Schema.Number]>;
readonly records: Schema.$Array<
Schema.Struct<{
readonly key: Schema.String;
readonly value: Schema.Unknown;
readonly expiresAt: Schema.optionalKey<Schema.Finite>;
}>
>;
}>;cache-storage.ts
TestCacheStorage (class)
Authoritative writable cache state, never subject to memoization eviction.
Signature
declare class TestCacheStoragecacheStorageLayer
Acquires one isolated fake root with scoped release and native cache semantics.
Signature
declare const cacheStorageLayer: (
options: TestCacheFakeOptions,
) => Layer.Layer<TestCacheStorage, never, never>;cache-storage.types.ts
CacheEntry (interface)
Detached authoritative cache value with an optional deterministic expiration timestamp.
Signature
export interface CacheEntry {
readonly value: unknown;
readonly expiresAt?: number;
}CacheStoragePolicy (interface)
Validated native write policy captured once before storage acquisition.
Signature
export interface CacheStoragePolicy {
readonly cacheId: string;
readonly schemaVersion: string | number;
readonly clock: () => number;
readonly failures: TestFailureControls;
readonly defaultTtlMs: number | undefined;
readonly maxTtlMs: number | undefined;
}CacheStorageService (interface)
Effect decisions over authoritative writable cache state and transfer boundaries.
Signature
export interface CacheStorageService {
readonly stateRoot: string;
readonly get: (
...args: Parameters<NonNullable<CacheProvider["get"]>>
) => Effect.Effect<unknown, unknown>;
readonly set: (
...args: Parameters<NonNullable<CacheProvider["set"]>>
) => Effect.Effect<void, unknown>;
readonly delete: (
...args: Parameters<NonNullable<CacheProvider["delete"]>>
) => Effect.Effect<void, unknown>;
readonly has: (
...args: Parameters<NonNullable<CacheProvider["has"]>>
) => Effect.Effect<boolean, unknown>;
readonly getOrSet: (
...args: Parameters<NonNullable<CacheProvider["getOrSet"]>>
) => Effect.Effect<unknown, unknown>;
readonly increment: (
...args: Parameters<NonNullable<CacheProvider["increment"]>>
) => Effect.Effect<number, unknown>;
readonly inspect: Effect.Effect<TestCacheSnapshot>;
readonly snapshot: Effect.Effect<CacheStorageSnapshot>;
readonly restore: (snapshot: unknown) => Effect.Effect<void, unknown>;
readonly clear: Effect.Effect<void>;
readonly close: Effect.Effect<void>;
}CacheStorageSnapshot (type alias)
Detached native cache transfer derived from its decoding schema authority.
Signature
type CacheStorageSnapshot = typeof SnapshotSchema.Type;CacheStorageState (interface)
Authoritative state survives until explicit owner release, without eviction.
Signature
export interface CacheStorageState {
closed: boolean;
readonly entries: Map<string, CacheEntry>;
readonly flights: Map<string, Promise<unknown>>;
}cache-types.ts
Preserved compatibility entrypoint for the canonical domain type companion.
“./cache.types.js” (namespace export)
Re-exports all named exports from the “./cache.types.js” module.
Signature
export * from "./cache.types.js";cache.ts
TestCacheFake
Signature
declare const TestCacheFake: TestCacheFake<Key, Value>;TestCacheFakeOptions
Signature
declare const TestCacheFakeOptions: TestCacheFakeOptions<KeySchema, ValueSchema>;TestCacheSnapshot
Signature
declare const TestCacheSnapshot: TestCacheSnapshot;createTestCache
Signature
declare const createTestCache: <
const KeySchema extends StandardSchemaV1 = StandardSchemaV1<unknown, unknown>,
const ValueSchema extends StandardSchemaV1 = StandardSchemaV1<unknown, unknown>,
>(
options?: TestCacheFakeOptions<KeySchema, ValueSchema>,
) => TestCacheFake<InferInput<KeySchema>, InferOutput<ValueSchema>>;createTestCacheFake
Creates authoritative cache storage behind the production Promise client.
See
- tests/fixtures/checked-examples.ts ownedHelpersExample for checked schema inference.
Signature
declare const createTestCacheFake: <
const KeySchema extends StandardSchemaV1 = StandardSchemaV1<unknown, unknown>,
const ValueSchema extends StandardSchemaV1 = StandardSchemaV1<unknown, unknown>,
>(
options?: TestCacheFakeOptions<KeySchema, ValueSchema>,
) => TestCacheFake<InferInput<KeySchema>, InferOutput<ValueSchema>>;cache.types.ts
TestCacheFake (type alias)
Authoritative writable native cache facade with detached transfer and release controls.
Signature
type TestCacheFake<Key, Value> = CacheClient<Key, Value> & {
readonly provider: CacheProvider;
readonly client: CacheClient<Key, Value>;
readonly capabilities: { readonly increment: true };
readonly stateRoot: string;
readonly seed: (key: Key, value: Value, options?: CacheOperationOptions) => Promise<void>;
readonly read: (key: Key) => Promise<Value | undefined>;
readonly increment: (
key: Key,
delta?: number,
options?: CacheOperationOptions,
) => Promise<number>;
readonly inspect: () => TestCacheSnapshot;
readonly snapshot: () => import("./cache-storage.types.js").CacheStorageSnapshot;
readonly restore: (snapshot: unknown) => void;
readonly clear: () => void;
readonly close: () => Promise<void>;
};TestCacheFakeOptions (interface)
Native key/value schemas, TTL policy and explicit fake-owner dependencies.
Signature
export interface TestCacheFakeOptions<
KeySchema extends StandardSchemaV1 = StandardSchemaV1,
ValueSchema extends StandardSchemaV1 = StandardSchemaV1,
> {
readonly cacheId?: string;
readonly ownerId?: string;
readonly stateRoot?: string;
readonly clock?: () => number;
readonly failures?: TestFailureControls;
readonly logger?: import("@relkit/runtime-effect").LoggerOptions;
readonly keySchema?: KeySchema;
readonly valueSchema?: ValueSchema;
readonly defaultTtlMs?: number;
readonly maxTtlMs?: number;
readonly schemaVersion?: string | number;
}TestCacheSnapshot (interface)
Native cache occupancy and identity evidence without memoization eviction.
Signature
export interface TestCacheSnapshot {
readonly cacheId: string;
readonly schemaVersion: string | number;
readonly entries: number;
readonly inFlight: number;
}drizzle.ts
Selected database application harness; database ownership remains scoped to each test.
TestApplication
Signature
declare const TestApplication: TestApplication;TestApplicationOptions
Signature
declare const TestApplicationOptions: TestApplicationOptions;createTestApplication
Acquires the general harness with the explicit native database service installer.
Signature
declare const createTestApplication: (
app: { readonly env: object },
options?: TestApplicationOptions,
) => Promise<TestApplication>;event-controls.types.ts
EventControlsService (interface)
Effect publication, delivery, inspection and lifecycle operations over native authorities.
Signature
export interface EventControlsService {
readonly publish: (
...args: Parameters<EventProvider["publish"]>
) => Effect.Effect<Awaited<ReturnType<EventProvider["publish"]>>, unknown>;
readonly pending: (triggerId?: string) => Effect.Effect<number, unknown>;
readonly completed: (triggerId?: string) => Effect.Effect<number, unknown>;
readonly runNext: (triggerId?: string) => Effect.Effect<EventDeliveryResult | undefined, unknown>;
readonly drain: Effect.Effect<readonly EventDeliveryResult[], unknown>;
readonly restart: Effect.Effect<void, unknown>;
readonly close: (options?: TestEventCloseOptions) => Effect.Effect<void, unknown>;
}events-inspection.ts
completedEventDeliveries
Counts acknowledged durable and ephemeral deliveries.
Signature
declare const completedEventDeliveries: (
state: TestEventControlState,
triggerId?: string,
) => number;pendingEventDeliveries
Counts eligible durable deliveries and persisted publications still awaiting fanout.
Signature
declare const pendingEventDeliveries: (state: TestEventControlState, triggerId?: string) => number;events-lifecycle.ts
eventLifecycle
Composes restart and final release under the event service’s scoped ownership.
Signature
declare const eventLifecycle: (
state: TestEventControlState,
scope: Scope.Scope,
context: Context.Context<never>,
) => {
restart: Effect.Effect<void, unknown, never>;
close: (failed?: boolean) => Effect.Effect<void, unknown, never>;
};events-runtime-controls.ts
TestEventControlState
Signature
declare const TestEventControlState: TestEventControlState;TestEventControls
Signature
declare const TestEventControls: TestEventControls;TestEventExecution (class)
Delivery admission, retry/fanout and release belong to one event owner.
Signature
declare class TestEventExecutioncreateTestEventControls
Exposes synchronous inspection and Promise work through one owned runtime.
Signature
declare const createTestEventControls: (state: TestEventControlState) => Promise<TestEventControls>;eventControlsLayer
Owns the native delivery lifecycle; alternate Layers retain this service contract.
Signature
declare const eventControlsLayer: (
state: TestEventControlState,
) => Layer.Layer<TestEventExecution, unknown, never>;events-runtime-controls.types.ts
TestEventControlState (interface)
Native authorities and Effect workflows owned by one event service Layer.
Signature
export interface TestEventControlState {
readonly logger?: import("@relkit/runtime-effect").LoggerOptions;
readonly router: () => EventRouter;
readonly log: () => { readonly close: () => Promise<void> };
readonly open: Effect.Effect<void, unknown>;
readonly release: Effect.Effect<void, unknown>;
readonly work: WorkOwnershipState;
readonly openFanout: (envelope: UnknownEventEnvelope) => Effect.Effect<void, unknown>;
readonly owner: TestStateRoot;
readonly failures: TestFailureControls;
readonly triggers: readonly {
readonly id: string;
readonly eventId: string;
readonly eventVersion: number;
}[];
readonly envelopes: readonly UnknownEventEnvelope[];
readonly unfanned: Map<string, UnknownEventEnvelope>;
readonly remember: (result: EventDeliveryResult, envelope: UnknownEventEnvelope) => void;
readonly publish: (
...args: Parameters<EventProvider["publish"]>
) => Effect.Effect<Awaited<ReturnType<EventProvider["publish"]>>, unknown>;
}TestEventControls (interface)
Native Promise facade preserving publication, inspection and delivery signatures.
Signature
export interface TestEventControls {
readonly publishNative: EventProvider["publish"];
readonly pending: (triggerId?: string) => number;
readonly runNext: (triggerId?: string) => Promise<EventDeliveryResult | undefined>;
readonly drain: () => Promise<readonly EventDeliveryResult[]>;
readonly completed: (triggerId?: string) => number;
readonly restart: () => Promise<void>;
readonly close: (options?: TestEventCloseOptions) => Promise<void>;
}events-runtime-open.ts
OpenTestEventRuntimeOptions
Signature
declare const OpenTestEventRuntimeOptions: OpenTestEventRuntimeOptions;openTestEventRuntime
Acquires log/router resources and materializes the declared event plan.
Signature
declare const openTestEventRuntime: (
input: OpenTestEventRuntimeOptions,
) => Effect.Effect<
{ log: EventLog; router: EventRouter; generation: number; storedCount: number },
unknown,
never
>;events-runtime-open.types.ts
OpenTestEventRuntimeOptions (interface)
Native log/router acquisition inputs and deterministic generation identity.
Signature
export interface OpenTestEventRuntimeOptions {
readonly profile: string;
readonly plan: Parameters<typeof materializeEvents>[0]["plan"];
readonly owner: TestStateRoot;
readonly options: TestEventOptions<unknown, unknown>;
readonly now: () => number;
readonly random: () => number;
readonly failures: TestFailureControls;
readonly runner: InvocationRunner;
readonly idSource: Parameters<typeof createEventInvoker>[4];
readonly targets: ReadonlyMap<string, InvocationTarget<unknown, unknown>>;
readonly generation: number;
readonly ownerSignal?: () => AbortSignal;
}events-runtime-utils.ts
createEventInvoker
Binds native event invocation to deterministic dependencies and cancellation.
Signature
declare const createEventInvoker: (
targets: ReadonlyMap<string, InvocationTarget<unknown, unknown>>,
options: TestEventOptions<unknown, unknown>,
now: () => number,
runner: InvocationRunner,
idSource: InvocationIdSource,
ownerSignal?: () => AbortSignal,
) => (request: EventInvocationOptions) => Promise<unknown>;createEventTraceBridge
Binds event producer spans to deterministic native invocation identities.
Signature
declare const createEventTraceBridge: (
eventId: string,
options: Pick<TestEventOptions<unknown, unknown>, "correlationId" | "causationInvocationId">,
clock: DeterministicClockService,
ids: InvocationIdSource,
) => {
run: <A>(
operation: () => MaybePromise<A>,
bridgeOptions?: { readonly name?: string },
) => Promise<A>;
};fanoutEvent
Routes a persisted publication before removing its acknowledgement-gap marker.
Signature
declare const fanoutEvent: (
router: EventRouter,
envelope: UnknownEventEnvelope,
unfanned: Map<string, UnknownEventEnvelope>,
failures: TestFailureControls,
) => Effect.Effect<void, unknown>;toEnvelope
Detaches an event envelope through the existing canonical JSON authority.
Signature
declare const toEnvelope: (value: Record<string, unknown>) => UnknownEventEnvelope;events-runtime.ts
TestEventRuntimeOptions
Signature
declare const TestEventRuntimeOptions: TestEventRuntimeOptions<Payload, Output>;createTestEventRuntime
Builds the native event publication and delivery owner.
Signature
declare const createTestEventRuntime: <Payload, Output>(
input: TestEventRuntimeOptions<Payload, Output>,
) => Promise<TestEventFake<Payload, Output>>;events-runtime.types.ts
EventRuntimeState (interface)
All publication, fanout and admission state belongs to one event owner.
Signature
export interface EventRuntimeState extends WorkOwnershipState {
readonly envelopes: UnknownEventEnvelope[];
readonly attempts: TestEventDeliveryAttempt[];
readonly unfanned: Map<string, UnknownEventEnvelope>;
generation: number;
sequence: number;
}OpenedEventRuntime (type alias)
Native generation acquired by the event owner’s ordered Effect workflow.
Signature
type OpenedEventRuntime = Effect.Success<ReturnType<typeof openTestEventRuntime>>;TestEventRuntimeOptions (interface)
Dependencies required to acquire one event log/router generation.
Signature
export interface TestEventRuntimeOptions<Payload, Output> {
readonly eventId: string;
readonly version: number;
readonly profile: string;
readonly triggers: readonly TestTrigger<Output>[];
readonly plan: Parameters<typeof materializeEvents>[0]["plan"];
readonly owner: TestStateRoot;
readonly deterministic: ReturnType<typeof createDeterministicClock>;
readonly failures: TestFailureControls;
readonly random: () => number;
readonly runner: InvocationRunner;
readonly idSource: InvocationIdSource;
readonly options: TestEventOptions<Payload, Output>;
}TestTrigger (type alias)
Normalized event trigger identity, delivery policy and native target.
Signature
type TestTrigger<Output> = TestEventTriggerOptions<Output> & {
readonly delivery: "ephemeral" | "durable";
readonly profile: string;
readonly eventId: string;
readonly eventVersion: number;
};events-types.ts
Preserved compatibility entrypoint for the canonical domain type companion.
“./events.types.js” (namespace export)
Re-exports all named exports from the “./events.types.js” module.
Signature
export * from "./events.types.js";events.ts
createTestEvent
Creates a deterministic event publication and delivery harness.
Signature
declare const createTestEvent: <Payload = unknown, Output = unknown>(
options: TestEventOptions<Payload, Output>,
) => Promise<TestEventFake<Payload, Output>>;createTestEventFake
Signature
declare const createTestEventFake: <Payload = unknown, Output = unknown>(
options: TestEventOptions<Payload, Output>,
) => Promise<TestEventFake<Payload, Output>>;events.types.ts
NormalizedTrigger (type alias)
Validated event trigger identity and policy used by native materialization.
Signature
type NormalizedTrigger<Output> = TestEventTriggerOptions<Output> & {
readonly delivery: "ephemeral" | "durable";
readonly profile: string;
readonly eventId: string;
readonly eventVersion: number;
};TestEventCloseOptions (interface)
Explicit failed-test state retention policy for event shutdown.
Signature
export interface TestEventCloseOptions {
readonly failed?: boolean;
}TestEventDeliveryAttempt (interface)
Native delivery outcome paired with its canonical persisted event envelope.
Signature
export interface TestEventDeliveryAttempt extends EventDeliveryResult {
readonly envelope: UnknownEventEnvelope;
}TestEventFake (interface)
Owned native publication/delivery facade with truthful deterministic ledgers.
Signature
export interface TestEventFake<Payload = unknown, Output = unknown> extends EventClient<
Payload,
string,
number,
Payload
> {
readonly id: string;
readonly eventId: string;
readonly version: number;
readonly client: EventClient<Payload, string, number, Payload>;
readonly provider: EventProvider;
readonly stateRoot: string;
readonly clock: TestClock;
readonly failures: TestFailureControls;
readonly pending: (triggerId?: string) => number;
readonly runNext: (triggerId?: string) => Promise<EventDeliveryResult | undefined>;
readonly drain: () => Promise<readonly EventDeliveryResult[]>;
readonly completed: (triggerId?: string) => number;
readonly restart: () => Promise<void>;
readonly envelopes: readonly UnknownEventEnvelope[];
readonly attempts: readonly TestEventDeliveryAttempt[];
readonly deliveries: readonly EventDeliveryLedgerRecord[];
readonly close: (options?: TestEventCloseOptions) => Promise<void>;
}TestEventInvocation (type alias)
Native invocation request consumed by an event target fixture.
Signature
type TestEventInvocation = EventInvocationOptions;TestEventOptions (interface)
Event publication contract, native consumers and deterministic fixture dependencies.
Signature
export interface TestEventOptions<Payload = unknown, Output = unknown> {
readonly logger?: import("@relkit/runtime-effect").LoggerOptions;
readonly event?: EventDescriptorAny;
readonly events?: readonly EventDescriptorAny[];
readonly eventId?: string;
readonly version?: number;
readonly payloadSchema?: StandardSchemaV1;
readonly target?: EventFunctionDescriptorAny;
readonly triggers?: readonly TestEventTriggerOptions<Output>[];
readonly triggerId?: string;
readonly delivery?: "ephemeral" | "durable";
readonly profile?: string;
readonly ownerId?: string;
readonly correlationId?: string;
readonly causationInvocationId?: string;
readonly retry?: RetryPolicy;
readonly concurrency?: number;
readonly stateRoot?: string;
readonly startTimeMs?: number;
readonly leaseDurationMs?: number;
readonly ephemeralCapacity?: number;
readonly random?: () => number;
readonly randomValues?: readonly number[];
readonly failures?: TestFailureControls;
readonly env?: Readonly<Record<string, unknown>>;
readonly clients?: DependencyClientSources;
readonly hooks?: InvocationHooks;
}TestEventPublishResult (type alias)
Native accepted publication receipt retained by the public event fixture.
Signature
type TestEventPublishResult = EventPublishResult<string, number, unknown>;TestEventTriggerOptions (interface)
Native target and per-trigger delivery, retry and worker concurrency policy.
Signature
export interface TestEventTriggerOptions<Output = unknown> {
readonly id: string;
readonly target: EventFunctionDescriptorAny;
readonly delivery?: "ephemeral" | "durable";
readonly profile?: string;
readonly retry?: RetryPolicy;
readonly concurrency?: number;
readonly timeoutMs?: number;
}fake-utils.ts
TestFakeRoot
Signature
declare const TestFakeRoot: TestFakeRoot;assertFailurePoint
Validates the existing dependency-fake failure boundary name.
Signature
declare const assertFailurePoint: (point: string) => void;assertName
Rejects empty dependency client names.
Signature
declare const assertName: (name: string) => void;clone
Detaches native fixture data using structured cloning.
Signature
declare const clone: (value: unknown) => unknown;createFakeRoot
Acquires a category-specific persistence path beneath an owned state root.
Signature
declare const createFakeRoot: (
requestedPath: string | undefined,
category: string,
id: string,
) => TestFakeRoot;lazyRecords
Creates owner-local dependency instances only on first named access.
Signature
declare const lazyRecords: <T>(
records: Record<string, T>,
create: (id: string) => T,
) => Record<string, T>;noFailures
Signature
declare const noFailures: TestFailureControls;positive
Validates the existing optional positive TTL policy.
Signature
declare const positive: (value: number | undefined, name: string) => number | undefined;text
Validates and trims a required fake storage identity.
Signature
declare const text: (value: string, name: string) => string;fake-utils.types.ts
Owned native storage subdirectory and idempotent temporary-parent cleanup.
TestFakeRoot (interface)
Owned native storage subdirectory and idempotent temporary-parent cleanup.
Signature
export interface TestFakeRoot {
readonly stateRoot: string;
readonly cleanup: (failed: boolean) => void;
}fakes.ts
TestFailureControls
Signature
declare const TestFailureControls: TestFailureControls;TestFakeProviders (class)
Native dependency sources and their storage release share a single test owner.
Signature
declare class TestFakeProvidersTestFakes
Signature
declare const TestFakes: TestFakes;TestFakesOptions
Signature
declare const TestFakesOptions: TestFakesOptions;createTestFakes
Creates fresh native dependency sources with an owned Effect lifetime.
Signature
declare const createTestFakes: (stateRoot: string, options?: TestFakesOptions) => TestFakes;fakeProvidersLayer
Acquires synchronous fake dependencies and scopes all storage created lazily later.
Signature
declare const fakeProvidersLayer: (
stateRoot: string,
options?: TestFakesOptions,
) => Layer.Layer<TestFakeProviders, never, never>;fakes.types.ts
TestFailureControls (interface)
Owner-local native failure injection with explicit one-shot and persistent boundaries.
Signature
export interface TestFailureControls {
readonly failAt: (point: string, cause?: unknown) => void;
readonly once?: (point: string, cause?: unknown) => void;
readonly clear: (point?: string) => void;
readonly check: (point: string) => void;
}TestFakes (interface)
Owned native dependency sources and authoritative writable storage fixtures.
Signature
export interface TestFakes {
readonly stateRoot: string;
readonly clients: DependencyClientSources;
readonly buckets: Readonly<Record<string, TestBucketFake>>;
readonly cache: Readonly<Record<string, TestCacheFake<unknown, unknown>>>;
readonly providers: TestProviderReplacements;
readonly createBucket: (
id: string,
options?: Omit<TestBucketFakeOptions, "bucketId" | "stateRoot" | "failures" | "clock">,
) => TestBucketFake;
readonly createCache: (
id: string,
options?: Omit<TestCacheFakeOptions, "cacheId" | "stateRoot" | "failures" | "clock">,
) => TestCacheFake<unknown, unknown>;
readonly setClient: (category: DependencyCategory, name: string, client: unknown) => void;
readonly removeClient: (category: DependencyCategory, name: string) => void;
readonly failures: TestFailureControls;
readonly close: () => Promise<void>;
}TestFakesOptions (interface)
Explicit clock, logger and provider replacement policy for one fake owner.
Signature
export interface TestFakesOptions {
readonly logger?: import("@relkit/runtime-effect").LoggerOptions;
readonly clock?: () => number;
readonly providers?: TestProviderReplacements;
}http-listener.ts
RealListenerPurpose
Signature
declare const RealListenerPurpose: RealListenerPurpose;TestHttpListener
Signature
declare const TestHttpListener: TestHttpListener;TestHttpListenerOptions
Signature
declare const TestHttpListenerOptions: TestHttpListenerOptions;createBunHttpListener
Signature
declare const createBunHttpListener: (
app: TestHttpApplication,
options?: TestHttpListenerOptions,
) => Promise<TestHttpListener>;createTestHttpListener
Starts the real-socket path reserved for disconnect, streaming, and proxy tests.
Signature
declare const createTestHttpListener: (
app: TestHttpApplication,
options?: TestHttpListenerOptions,
) => Promise<TestHttpListener>;http-listener.types.ts
RealListenerPurpose (type alias)
Native behavior requiring a real Bun listener in compatibility acceptance.
Signature
type RealListenerPurpose = "disconnect" | "stream" | "proxy";TestHttpListener (interface)
Owned real Bun server handle and native request/release boundary.
Signature
export interface TestHttpListener {
readonly purpose: RealListenerPurpose;
readonly url: URL;
readonly server: Bun.Server<undefined>;
readonly request: TestHttpRequest;
readonly close: () => Promise<void>;
}TestHttpListenerOptions (interface)
Explicit native socket identity, timeout and disconnect test policy.
Signature
export interface TestHttpListenerOptions {
readonly purpose?: RealListenerPurpose;
readonly hostname?: string;
readonly port?: number;
readonly idleTimeout?: number;
readonly closeTimeoutMs?: number;
}http-owner.ts
TestHttpOwner (class)
Listener admission, startup races and complete shutdown belong to one client owner.
Signature
declare class TestHttpOwnerTestHttpPlatform (class)
Native listener acquisition; tests substitute failures without opening real sockets.
Signature
declare class TestHttpPlatformTestHttpPlatformLive
Signature
declare const TestHttpPlatformLive: Layer.Layer<TestHttpPlatform, never, never>;httpOwnerLayer
Owns listener admission, late startup adoption and complete release as Effect decisions.
Signature
declare const httpOwnerLayer: (
app: TestHttpApplication,
options: TestHttpClientOptions,
) => Layer.Layer<TestHttpOwner, never, TestHttpPlatform>;http-owner.types.ts
HttpOwnerService (interface)
Effect listener admission and complete shutdown over native listener handles.
Signature
export interface HttpOwnerService {
readonly listen: (options?: TestHttpListenerOptions) => Effect.Effect<TestHttpListener, unknown>;
readonly close: Effect.Effect<void, unknown>;
}HttpOwnerState (interface)
Listener handles and real startup completion retained by one scoped HTTP owner.
Signature
export interface HttpOwnerState {
closed: boolean;
readonly listeners: Set<TestHttpListener>;
readonly pending: Set<Promise<unknown>>;
readonly startupReleaseFailures: unknown[];
closing: Promise<void> | undefined;
}HttpPlatformService (interface)
Replaceable native listener acquisition authority for one HTTP owner.
Signature
export interface HttpPlatformService {
readonly listen: typeof createTestHttpListener;
}http.ts
RealListenerPurpose
Signature
declare const RealListenerPurpose: RealListenerPurpose;TestHttpApplication
Signature
declare const TestHttpApplication: TestHttpApplication;TestHttpClient
Signature
declare const TestHttpClient: TestHttpClient;TestHttpClientOptions
Signature
declare const TestHttpClientOptions: TestHttpClientOptions;TestHttpInput
Signature
declare const TestHttpInput: TestHttpInput;TestHttpListener
Signature
declare const TestHttpListener: TestHttpListener;TestHttpListenerOptions
Signature
declare const TestHttpListenerOptions: TestHttpListenerOptions;TestHttpRequest
Signature
declare const TestHttpRequest: TestHttpRequest;TestObservability
Signature
declare const TestObservability: TestObservability;assertObservabilityHookTypes
Asserts event order and the existing observability protocol/version.
Signature
declare const assertObservabilityHookTypes: (
hooks: Pick<InspectableObservabilityHooks, "read">,
expected: readonly ObservabilityHookEvent["type"][],
) => readonly ObservabilityHookEvent[];assertResponseStatus
Asserts the existing native HTTP response status.
Signature
declare const assertResponseStatus: (response: Response, expected: number) => Response;createBunHttpListener
Signature
declare const createBunHttpListener: (
app: TestHttpApplication,
options?: TestHttpListenerOptions,
) => Promise<TestHttpListener>;createHttpTestClient
Signature
declare const createHttpTestClient: (
app: TestHttpApplication,
options?: TestHttpClientOptions,
) => TestHttpClient;createObservabilityAssertions
Signature
declare const createObservabilityAssertions: () => TestObservability;createTestHttpClient
Sends ordinary route tests through the app’s in-memory request entry point.
Signature
declare const createTestHttpClient: (
app: TestHttpApplication,
options?: TestHttpClientOptions,
) => TestHttpClient;createTestHttpListener
Signature
declare const createTestHttpListener: (
app: TestHttpApplication,
options?: TestHttpListenerOptions,
) => Promise<TestHttpListener>;createTestObservability
Creates a protocol/version-checked capture for engine-backed HTTP tests.
Signature
declare const createTestObservability: () => TestObservability;responseJson
Reads JSON after the optional native status assertion.
Signature
declare const responseJson: <T = unknown>(
response: Response,
expectedStatus?: number,
) => Promise<T>;responseText
Reads text after the optional native status assertion.
Signature
declare const responseText: (response: Response, expectedStatus?: number) => Promise<string>;http.types.ts
TestHttpApplication (interface)
The app request/fetch methods satisfy this boundary without leaking framework types.
Signature
export interface TestHttpApplication {
readonly request?: (input: TestHttpInput, init?: RequestInit) => Response | Promise<Response>;
readonly fetch?: (request: Request) => Response | Promise<Response>;
}TestHttpClient (interface)
Owned HTTP test facade exposing direct requests and optional real listeners.
Signature
export interface TestHttpClient {
readonly request: TestHttpRequest;
readonly get: TestHttpRequest;
readonly post: TestHttpRequest;
readonly put: TestHttpRequest;
readonly patch: TestHttpRequest;
readonly delete: TestHttpRequest;
readonly listen: (options?: TestHttpListenerOptions) => Promise<TestHttpListener>;
readonly close: () => Promise<void>;
}TestHttpClientOptions (interface)
Explicit test origin, listener close policy and ownership callbacks.
Signature
export interface TestHttpClientOptions {
readonly logger?: import("@relkit/runtime-effect").LoggerOptions;
readonly baseUrl?: string | URL;
/** Registers client shutdown with the owning test runtime/application. */
readonly registerClose?: (close: () => Promise<void>) => void;
readonly onClose?: () => MaybePromise<void>;
readonly closeTimeoutMs?: number;
}TestHttpInput (type alias)
Native Request, URL or relative path accepted by direct HTTP fixtures.
Signature
type TestHttpInput = Request | string | URL;TestHttpRequest (type alias)
Native in-memory request operation preserving RequestInit and Response contracts.
Signature
type TestHttpRequest = (input: TestHttpInput, init?: RequestInit) => Promise<Response>;TestObservability (interface)
Native engine event capture with ordered protocol/version assertions.
Signature
export interface TestObservability {
readonly hooks: InspectableObservabilityHooks;
readonly read: () => readonly ObservabilityHookEvent[];
readonly types: () => readonly ObservabilityHookEvent["type"][];
readonly assertTypes: (
expected: readonly ObservabilityHookEvent["type"][],
) => readonly ObservabilityHookEvent[];
readonly clear: () => void;
}identity.ts
TestIdentity (class)
Native trace/span/invocation identity sequence belongs to one deterministic owner.
Signature
declare class TestIdentitycreateTestIdentitySource
Exposes native synchronous identity generation over the same service contract.
Signature
declare const createTestIdentitySource: () => InvocationIdSource;identityLayer
Builds the identity service once per provisioned owner.
Signature
declare const identityLayer: () => Layer.Layer<TestIdentity, never, never>;identity.types.ts
TestIdentityService (interface)
Deterministic identity allocation authority shared by one test owner.
Signature
export interface TestIdentityService {
readonly next: (kind: Parameters<InvocationIdSource["next"]>[0]) => Effect.Effect<ProtocolId>;
}index.ts
Exposes generic application test owners and fakes; native helpers have feature entrypoints.
FunctionContextOf
Signature
declare const FunctionContextOf: FunctionContextOf<Target>;FunctionInput
Signature
declare const FunctionInput: FunctionInput<Target>;FunctionOutput
Signature
declare const FunctionOutput: FunctionOutput<Target>;InvokeFunctionOptions
Signature
declare const InvokeFunctionOptions: InvokeFunctionOptions<Context>;JOBS_CONFORMANCE_FIXTURES
Signature
declare const JOBS_CONFORMANCE_FIXTURES: ReadonlyArray<JobsConformanceFixture>;JobsConformanceFixture
Signature
declare const JobsConformanceFixture: JobsConformanceFixture;JobsConformanceHarness
Signature
declare const JobsConformanceHarness: JobsConformanceHarness;RealListenerPurpose
Signature
declare const RealListenerPurpose: RealListenerPurpose;StandaloneFunctionTarget
Signature
declare const StandaloneFunctionTarget: StandaloneFunctionTarget;TestApplication
Signature
declare const TestApplication: TestApplication;TestApplicationOptions
Signature
declare const TestApplicationOptions: TestApplicationOptions;TestBucketFake
Signature
declare const TestBucketFake: TestBucketFake;TestBucketFakeOptions
Signature
declare const TestBucketFakeOptions: TestBucketFakeOptions;TestBucketObject
Signature
declare const TestBucketObject: TestBucketObject;TestCacheFake
Signature
declare const TestCacheFake: TestCacheFake<Key, Value>;TestCacheFakeOptions
Signature
declare const TestCacheFakeOptions: TestCacheFakeOptions<KeySchema, ValueSchema>;TestCacheSnapshot
Signature
declare const TestCacheSnapshot: TestCacheSnapshot;TestClock
Signature
declare const TestClock: TestClock;TestEventCloseOptions
Signature
declare const TestEventCloseOptions: TestEventCloseOptions;TestEventDeliveryAttempt
Signature
declare const TestEventDeliveryAttempt: TestEventDeliveryAttempt;TestEventFake
Signature
declare const TestEventFake: TestEventFake<Payload, Output>;TestEventOptions
Signature
declare const TestEventOptions: TestEventOptions<Payload, Output>;TestEventPublishResult
Signature
declare const TestEventPublishResult: TestEventPublishResult;TestEventTriggerOptions
Signature
declare const TestEventTriggerOptions: TestEventTriggerOptions<Output>;TestFailureControls
Signature
declare const TestFailureControls: TestFailureControls;TestFakes
Signature
declare const TestFakes: TestFakes;TestFakesOptions
Signature
declare const TestFakesOptions: TestFakesOptions;TestHttpApplication
Signature
declare const TestHttpApplication: TestHttpApplication;TestHttpClient
Signature
declare const TestHttpClient: TestHttpClient;TestHttpClientOptions
Signature
declare const TestHttpClientOptions: TestHttpClientOptions;TestHttpInput
Signature
declare const TestHttpInput: TestHttpInput;TestHttpListener
Signature
declare const TestHttpListener: TestHttpListener;TestHttpListenerOptions
Signature
declare const TestHttpListenerOptions: TestHttpListenerOptions;TestHttpRequest
Signature
declare const TestHttpRequest: TestHttpRequest;TestJobCloseOptions
Signature
declare const TestJobCloseOptions: TestJobCloseOptions;TestJobFake
Signature
declare const TestJobFake: TestJobFake<Input, Output>;TestJobOptions
Signature
declare const TestJobOptions: TestJobOptions<Input, Output>;TestJobsAdapter
Signature
declare const TestJobsAdapter: TestJobsAdapter;TestJobsAdapterOptions
Signature
declare const TestJobsAdapterOptions: TestJobsAdapterOptions;TestObservability
Signature
declare const TestObservability: TestObservability;TestProviderReplacements
Signature
declare const TestProviderReplacements: Readonly<
Partial<
Record<
"bucket" | "cache" | "job" | "event" | "model" | "realtime" | "agent-state",
Readonly<Record<string, unknown>>
>
>
>;TestRuntime
Signature
declare const TestRuntime: TestRuntime;TestRuntimeCloseOptions
Signature
declare const TestRuntimeCloseOptions: TestRuntimeCloseOptions;TestRuntimeOptions
Signature
declare const TestRuntimeOptions: TestRuntimeOptions<S>;assertObservabilityHookTypes
Signature
declare const assertObservabilityHookTypes: (
hooks: Pick<InspectableObservabilityHooks, "read">,
expected: readonly ObservabilityHookEvent["type"][],
) => readonly ObservabilityHookEvent[];assertResponseStatus
Signature
declare const assertResponseStatus: (response: Response, expected: number) => Response;createBunHttpListener
Signature
declare const createBunHttpListener: (
app: TestHttpApplication,
options?: TestHttpListenerOptions,
) => Promise<TestHttpListener>;createDeterministicJobsAdapter
Signature
declare const createDeterministicJobsAdapter: (options?: TestJobsAdapterOptions) => TestJobsAdapter;createHttpTestClient
Signature
declare const createHttpTestClient: (
app: TestHttpApplication,
options?: TestHttpClientOptions,
) => TestHttpClient;createJobsConformanceHarness
Signature
declare const createJobsConformanceHarness: (
options?: TestJobsAdapterOptions,
) => JobsConformanceHarness;createObservabilityAssertions
Signature
declare const createObservabilityAssertions: () => TestObservability;createTestAgentStateProvider
Signature
declare const createTestAgentStateProvider: (root: string) => AgentStateProvider;createTestApplication
Signature
declare const createTestApplication: (
app: { readonly env: object },
options?: TestApplicationOptions,
) => Promise<TestApplication>;createTestBucket
Signature
declare const createTestBucket: (options?: TestBucketFakeOptions) => TestBucketFake;createTestBucketFake
Signature
declare const createTestBucketFake: (options?: TestBucketFakeOptions) => TestBucketFake;createTestCache
Signature
declare const createTestCache: <
const KeySchema extends StandardSchemaV1 = StandardSchemaV1<unknown, unknown>,
const ValueSchema extends StandardSchemaV1 = StandardSchemaV1<unknown, unknown>,
>(
options?: TestCacheFakeOptions<KeySchema, ValueSchema>,
) => TestCacheFake<InferInput<KeySchema>, InferOutput<ValueSchema>>;createTestCacheFake
Signature
declare const createTestCacheFake: <
const KeySchema extends StandardSchemaV1 = StandardSchemaV1<unknown, unknown>,
const ValueSchema extends StandardSchemaV1 = StandardSchemaV1<unknown, unknown>,
>(
options?: TestCacheFakeOptions<KeySchema, ValueSchema>,
) => TestCacheFake<InferInput<KeySchema>, InferOutput<ValueSchema>>;createTestEvent
Signature
declare const createTestEvent: <Payload = unknown, Output = unknown>(
options: TestEventOptions<Payload, Output>,
) => Promise<TestEventFake<Payload, Output>>;createTestEventFake
Signature
declare const createTestEventFake: <Payload = unknown, Output = unknown>(
options: TestEventOptions<Payload, Output>,
) => Promise<TestEventFake<Payload, Output>>;createTestFakes
Signature
declare const createTestFakes: (stateRoot: string, options?: TestFakesOptions) => TestFakes;createTestHttpClient
Signature
declare const createTestHttpClient: (
app: TestHttpApplication,
options?: TestHttpClientOptions,
) => TestHttpClient;createTestHttpListener
Signature
declare const createTestHttpListener: (
app: TestHttpApplication,
options?: TestHttpListenerOptions,
) => Promise<TestHttpListener>;createTestJob
Signature
declare const createTestJob: <Input = JsonValue, Output = unknown>(
options: TestJobOptions<Input, Output>,
) => Promise<TestJobFake<Input, Output>>;createTestJobFake
Signature
declare const createTestJobFake: <Input = JsonValue, Output = unknown>(
options: TestJobOptions<Input, Output>,
) => Promise<TestJobFake<Input, Output>>;createTestJobsAdapter
Signature
declare const createTestJobsAdapter: (options?: TestJobsAdapterOptions) => TestJobsAdapter;createTestObservability
Signature
declare const createTestObservability: () => TestObservability;createTestRealtimeProvider
Signature
declare const createTestRealtimeProvider: (root: string) => RealtimeProvider;createTestRuntime
Signature
declare const createTestRuntime: <S extends EnvShape = EnvShape>(
options?: TestRuntimeOptions<S>,
) => TestRuntime;invokeFunction
Signature
declare const invokeFunction: <
const Target extends StandaloneFunctionTarget,
Context extends { readonly signal: AbortSignal } = FunctionContextOf<Target>,
>(
target: Target,
input: FunctionInput<Target>,
options?: InvokeFunctionOptions<Context>,
) => Promise<FunctionOutput<Target>>;responseJson
Signature
declare const responseJson: <T = unknown>(
response: Response,
expectedStatus?: number,
) => Promise<T>;responseText
Signature
declare const responseText: (response: Response, expectedStatus?: number) => Promise<string>;runJobsConformance
Signature
declare const runJobsConformance: (
adapter: JobsAdapterRuntime,
fixtureIds?: readonly string[],
) => Promise<readonly string[]>;invoke-function.ts
invokeFunction
Invokes a function descriptor through the engine’s direct, transport-free path.
Example
import { defineFunction } from "@relkit/app/functions";
import { z } from "@relkit/app/schema";
import { invokeFunction } from "@relkit/testing";
export async function greetingExample(): Promise<string> {
const greet = defineFunction({
id: "greet",
input: z.string(),
output: z.string(),
handler: async (name) => `Hello ${name}`,
});
return invokeFunction(greet, "Ada");
}Signature
declare const invokeFunction: <
const Target extends StandaloneFunctionTarget,
Context extends { readonly signal: AbortSignal } = FunctionContextOf<Target>,
>(
target: Target,
input: FunctionInput<Target>,
options?: InvokeFunctionOptions<Context>,
) => Promise<FunctionOutput<Target>>;Since v0.1.0
FunctionContextOf
Signature
declare const FunctionContextOf: FunctionContextOf<Target>;FunctionInput
Signature
declare const FunctionInput: FunctionInput<Target>;FunctionOutput
Signature
declare const FunctionOutput: FunctionOutput<Target>;InvokeFunctionOptions
Signature
declare const InvokeFunctionOptions: InvokeFunctionOptions<Context>;StandaloneFunctionTarget
Signature
declare const StandaloneFunctionTarget: StandaloneFunctionTarget;invokeFunctionWithRunner
Invokes the existing engine validation path with an explicit Effect runner.
Signature
declare const invokeFunctionWithRunner: <
const Target extends StandaloneFunctionTarget,
Context extends { readonly signal: AbortSignal } = FunctionContextOf<Target>,
>(
target: Target,
input: FunctionInput<Target>,
options: InvokeFunctionOptions<Context> | undefined,
runner?: InvocationRunner,
) => Promise<FunctionOutput<Target>>;invoke-function.types.ts
FunctionContextOf (type alias)
Context inferred from the native handler, preserving required cancellation.
Signature
type FunctionContextOf<Target> =
Target extends Record<"handler", (input: infer _Input, context: infer Context) => unknown>
? Context extends { readonly signal: AbortSignal }
? Context
: InvocationContext
: InvocationContext;FunctionInput (type alias)
Input inferred from the target’s native schema authority.
Signature
type FunctionInput<Target extends { readonly input: StandardSchemaV1 }> = InferInput<
Target["input"]
>;FunctionOutput (type alias)
Output inferred from the target’s native schema authority.
Signature
type FunctionOutput<Target extends { readonly output: StandardSchemaV1 }> = InferOutput<
Target["output"]
>;InvokeFunctionOptions (interface)
Direct invocation dependencies and native hooks without process environment reads.
Signature
export interface InvokeFunctionOptions<Context extends { readonly signal: AbortSignal }> {
readonly registry?: FunctionRegistry;
readonly env?: Readonly<Record<string, unknown>>;
readonly clients?: DependencyClientSources;
readonly signal?: AbortSignal;
readonly now?: () => number;
readonly idSource?: InvocationIdSource;
readonly context?: InvocationHooks<Context>["context"];
readonly hooks?: InvocationHooks<Context>;
}StandaloneFunctionTarget (interface)
Native function descriptor retaining input, output and dependency validation.
Signature
export interface StandaloneFunctionTarget {
readonly id: string;
readonly input: StandardSchemaV1;
readonly output: StandardSchemaV1;
readonly errors?: readonly { readonly id: string; readonly data: StandardSchemaV1 }[];
readonly dependencies?: import("@relkit/engine").DependencyDeclarations;
readonly publishes?: readonly string[];
readonly publications?: Readonly<Record<string, import("@relkit/engine").DependencyRefLike>>;
readonly timeoutMs?: number;
readonly concurrency?: number;
readonly handler: (...arguments_: readonly never[]) => MaybePromise<unknown>;
}job-harness.types.ts
JobHarnessService (interface)
Native inspection and Effect workflows over one durable job generation.
Signature
export interface JobHarnessService {
readonly value: TestJobFake<never, unknown>;
readonly runNext: (
id?: string,
) => Effect.Effect<Awaited<ReturnType<TestJobFake["runNext"]>>, unknown>;
readonly drain: Effect.Effect<Awaited<ReturnType<TestJobFake["drain"]>>, unknown>;
readonly restart: Effect.Effect<void, unknown>;
readonly close: (options?: TestJobCloseOptions) => Effect.Effect<void, unknown>;
}job-runtime-controls.ts
enqueueJob
Persists one submission before making a new durable instance available.
Signature
declare const enqueueJob: (
queue: JobQueue,
input: JobQueueEnqueue,
signal: AbortSignal,
) => Effect.Effect<JobQueueAcceptance, unknown, never>;jobWorkerControls
Composes native worker selection and retry promotion against the current generation.
Signature
declare const jobWorkerControls: (state: JobWorkerState) => {
runNext: (
instanceId?: string | undefined,
) => Effect.Effect<JobRunResult | undefined, unknown, never>;
drain: Effect.Effect<ReadonlyArray<JobRunResult>, unknown, never>;
};promoteDueJobs
Promotes due entries in native snapshot order before worker admission.
Signature
declare const promoteDueJobs: (
queue: JobQueue,
currentTimeMs: () => number,
) => Effect.Effect<void, unknown, never>;job-runtime.ts
createTestJobRuntime
Acquires and composes the durable job owner’s actual workflows.
Signature
declare const createTestJobRuntime: <Input = JsonValue, Output = unknown>(
options: TestJobOptions<Input, Output>,
) => Effect.Effect<
{
value: JobHarnessService["value"];
runNext: (instanceId?: string) => Effect.Effect<JobRunResult | undefined, unknown, never>;
drain: Effect.Effect<ReadonlyArray<JobRunResult>, unknown, never>;
restart: Effect.Effect<void, unknown, never>;
close: (closeOptions: TestJobCloseOptions | undefined) => Effect.Effect<void, unknown, never>;
},
unknown,
Scope.Scope
>;job-runtime.types.ts
JobRuntimeState (interface)
Admission, native cancellation and actual completion receipts for one durable job owner.
Signature
export interface JobRuntimeState extends WorkOwnershipState {}JobWorkerState (interface)
Current-generation native authorities read lazily by ordered worker workflows.
Signature
export interface JobWorkerState {
readonly queue: () => JobQueue;
readonly worker: () => Awaited<ReturnType<typeof materializeJobs>>;
readonly jobId: string;
readonly now: () => number;
readonly isClosed: () => boolean;
}jobs-conformance.ts
JOBS_CONFORMANCE_FIXTURES
Signature
declare const JOBS_CONFORMANCE_FIXTURES: ReadonlyArray<JobsConformanceFixture>;JobsConformanceFixture
Signature
declare const JobsConformanceFixture: JobsConformanceFixture;JobsConformanceHarness
Signature
declare const JobsConformanceHarness: JobsConformanceHarness;createJobsConformanceHarness
Creates the deterministic adapter used by native contract fixtures.
Signature
declare const createJobsConformanceHarness: (
options?: TestJobsAdapterOptions,
) => JobsConformanceHarness;runJobsConformance
Executes selected existing native adapter contract fixtures sequentially.
Signature
declare const runJobsConformance: (
adapter: JobsAdapterRuntime,
fixtureIds?: readonly string[],
) => Promise<readonly string[]>;jobs-conformance.types.ts
JobsConformanceFixture (interface)
Native adapter fixture inputs for reusable jobs contract assertions.
Signature
export interface JobsConformanceFixture {
readonly id: string;
readonly description: string;
}JobsConformanceHarness (interface)
Owned native jobs conformance operations and completion controls.
Signature
export interface JobsConformanceHarness {
readonly adapter: TestJobsAdapter;
readonly context: OperationContext;
readonly fixtures: typeof JOBS_CONFORMANCE_FIXTURES;
readonly run: (fixtureId: string) => Promise<RunHandle | undefined>;
}jobs-types.ts
Preserved compatibility entrypoint for the canonical domain type companion.
“./jobs.types.js” (namespace export)
Re-exports all named exports from the “./jobs.types.js” module.
Signature
export * from "./jobs.types.js";jobs-utils.ts
createFailures
Creates isolated named failure injection controls.
Signature
declare const createFailures: () => TestFailureControls;createIdSource
Creates an isolated monotonically sequenced invocation identity source.
Signature
declare const createIdSource: () => InvocationIdSource;createJobInvoker
Binds job invocation to deterministic IDs, time and owner cancellation.
Signature
declare const createJobInvoker: <Input, Output>(
target: InvocationTarget<Input, Output>,
failures: TestFailureControls,
runner: InvocationRunner,
idSource: InvocationIdSource,
now: () => number,
env: Readonly<Record<string, unknown>> | undefined,
clients: DependencyClientSources | undefined,
hooks: InvocationHooks | undefined,
ownerSignal?: () => AbortSignal,
) => (request: JobInvocationOptions) => Promise<unknown>;createPlan
Builds the minimal registration plan consumed by native materialization.
Signature
declare const createPlan: <Input, Output>(
jobId: string,
target: InvocationTarget<Input, Output>,
retry: RetryPolicy,
profile: string,
options: TestJobOptions<Input, Output>,
) => Parameters<typeof materializeJobs>[0]["plan"];createRandom
Creates deterministic retry randomness with upfront fixture validation.
Signature
declare const createRandom: (
source: (() => number) | undefined,
values: readonly number[] | undefined,
) => () => number;defaultRetry
Signature
declare const defaultRetry: RetryPolicy;jobs.ts
TestJobHarness (class)
Durable native job generation owned by one test scope.
Signature
declare class TestJobHarnesscreateTestJob
Signature
declare const createTestJob: <Input = JsonValue, Output = unknown>(
options: TestJobOptions<Input, Output>,
) => Promise<TestJobFake<Input, Output>>;createTestJobFake
Creates a durable one-job harness with an owned Effect runtime.
Signature
declare const createTestJobFake: <Input = JsonValue, Output = unknown>(
options: TestJobOptions<Input, Output>,
) => Promise<TestJobFake<Input, Output>>;testJobLayer
Acquires native store/queue/worker resources with deterministic retry inputs.
Signature
declare const testJobLayer: <Input, Output>(
options: TestJobOptions<Input, Output>,
) => Layer.Layer<TestJobHarness, unknown, never>;jobs.types.ts
TestJobCloseOptions (interface)
Explicit failed-test state retention policy for durable job shutdown.
Signature
export interface TestJobCloseOptions {
readonly failed?: boolean;
}TestJobFake (interface)
Owned durable native job facade with deterministic admission and lifecycle controls.
Signature
export interface TestJobFake<Input = JsonValue, Output = unknown> extends JobClient<Input> {
readonly id: string;
readonly client: JobClient<Input>;
readonly provider: JobProvider;
readonly stateRoot: string;
readonly clock: TestClock;
readonly random: () => number;
readonly failures: TestFailureControls;
readonly admin: JobAdmin;
readonly status: () => JobQueueCounts;
readonly get: (instanceId: string) => JobQueueEntry | undefined;
readonly runNext: (instanceId?: string) => Promise<JobRunResult | undefined>;
readonly drain: () => Promise<readonly JobRunResult[]>;
readonly restart: () => Promise<void>;
readonly close: (options?: TestJobCloseOptions) => Promise<void>;
}TestJobOptions (interface)
Durable native target, retry bounds and deterministic persistence dependencies.
Signature
export interface TestJobOptions<Input = JsonValue, Output = unknown> {
readonly logger?: import("@relkit/runtime-effect").LoggerOptions;
readonly jobId?: string;
readonly target: InvocationTarget<Input, Output>;
readonly retry?: RetryPolicy;
readonly profile?: string;
readonly timeoutMs?: number;
readonly concurrency?: number;
readonly consumerConcurrency?: number;
readonly idempotency?: JobIdempotencyDefinition;
readonly leaseDurationMs?: number;
readonly ownerId?: string;
readonly stateRoot?: string;
readonly startTimeMs?: number;
readonly random?: () => number;
readonly randomValues?: readonly number[];
readonly failures?: TestFailureControls;
readonly env?: Readonly<Record<string, unknown>>;
readonly clients?: DependencyClientSources;
readonly hooks?: InvocationHooks;
}native-jobs-observe.ts
nativeJobObservation
Publishes owner state availability without polling or sharing observer cursors.
Signature
declare const nativeJobObservation: (
state: Ref.Ref<NativeJobsState>,
clock: TestClock,
service: string,
request: NativeWatchRequest,
context: OperationContext,
) => Stream.Stream<
| {
readonly kind: "snapshot";
readonly run: RunSnapshot;
readonly observedAt: string;
readonly epoch: string;
readonly sequence: number;
readonly cursor?: string;
readonly continuity: "state" | "history";
}
| {
readonly kind: "update";
readonly run: RunSnapshot;
readonly observedAt: string;
readonly epoch: string;
readonly sequence: number;
readonly cursor?: string;
},
unknown,
never
>;native-jobs-service.ts
TestNativeJobs (class)
Owns authoritative native run state, deterministic time and observation synchronization.
Signature
declare class TestNativeJobsnativeJobsLayer
Builds one native jobs service, substitutable by providing TestNativeJobs.of in tests.
Signature
declare const nativeJobsLayer: (
options?: TestJobsAdapterOptions,
) => Layer.Layer<TestNativeJobs, never, never>;native-jobs-state.ts
notifyNativeJobs
Publishes state availability without buffers or wall-clock polling.
Signature
declare const notifyNativeJobs: (value: NativeJobsState) => void;native-jobs.types.ts
NativeJobsService (interface)
Effect native jobs adapter decisions with owned worker and observation lifetimes.
Signature
export interface NativeJobsService {
readonly state: Ref.Ref<NativeJobsState>;
readonly clock: TestClock;
readonly submit: (
...args: Parameters<JobsAdapterRuntime["submit"]>
) => Effect.Effect<Awaited<ReturnType<JobsAdapterRuntime["submit"]>>, unknown>;
readonly get: (
...args: Parameters<JobsAdapterRuntime["get"]>
) => Effect.Effect<RunSnapshot, unknown>;
readonly list: (
...args: Parameters<JobsAdapterRuntime["list"]>
) => Effect.Effect<Awaited<ReturnType<JobsAdapterRuntime["list"]>>, unknown>;
readonly cancel: (
...args: Parameters<JobsAdapterRuntime["cancel"]>
) => Effect.Effect<Awaited<ReturnType<JobsAdapterRuntime["cancel"]>>, unknown>;
readonly retry: (
...args: Parameters<NonNullable<JobsAdapterRuntime["retry"]>>
) => Effect.Effect<Awaited<ReturnType<NonNullable<JobsAdapterRuntime["retry"]>>>, unknown>;
readonly worker: {
readonly next: (
...args: Parameters<NonNullable<JobsAdapterRuntime["worker"]>["next"]>
) => Effect.Effect<
Awaited<ReturnType<NonNullable<JobsAdapterRuntime["worker"]>["next"]>>,
unknown
>;
readonly complete: (
...args: Parameters<NonNullable<JobsAdapterRuntime["worker"]>["complete"]>
) => Effect.Effect<void, unknown>;
readonly fail: (
...args: Parameters<NonNullable<JobsAdapterRuntime["worker"]>["fail"]>
) => Effect.Effect<void, unknown>;
};
readonly observe: (
...args: Parameters<NonNullable<JobsAdapterRuntime["observe"]>>
) => Stream.Stream<RunWatchFrame<RunSnapshot>, unknown>;
readonly snapshot: (runId: string) => Effect.Effect<RunSnapshot, unknown>;
readonly close: Effect.Effect<void>;
}NativeJobsState (interface)
Owner-local deterministic run, worker, cursor and observation admission state.
Signature
export interface NativeJobsState {
readonly runs: Map<string, TestNativeRun>;
readonly keys: Map<string, string>;
readonly cancelReceipts: Map<string, Awaited<ReturnType<JobsAdapterRuntime["cancel"]>>>;
readonly retryReceipts: Map<
string,
Awaited<ReturnType<NonNullable<JobsAdapterRuntime["retry"]>>>
>;
sequence: number;
closed: boolean;
changed: Deferred.Deferred<void>;
}provider-replacements.ts
TestProviderReplacements
Signature
declare const TestProviderReplacements: Readonly<
Partial<
Record<
"bucket" | "cache" | "job" | "event" | "model" | "realtime" | "agent-state",
Readonly<Record<string, unknown>>
>
>
>;activateTestProviders
Acquires native providers and wires dependency clients with partial-failure release.
Signature
declare const activateTestProviders: (
artifacts: TestApplicationArtifacts | undefined,
replacements: TestProviderReplacements,
bindingValues: Readonly<Record<string, JsonValue>> | undefined,
fakes: TestFakes,
fakeResources?: boolean,
) => Promise<ProviderRegistry | undefined>;copyTestProviderReplacements
Copies explicit capability/profile replacements before resource acquisition.
Signature
declare const copyTestProviderReplacements: (
input: TestProviderReplacements | undefined,
) => TestProviderReplacements;provider-replacements.types.ts
TestProviderReplacements (type alias)
Explicit capability/profile replacements; absent profiles remain native authority decisions.
Signature
type TestProviderReplacements = Readonly<
Partial<Record<ProviderCapability, Readonly<Record<string, unknown>>>>
>;runtime-clock.ts
TestDeterministicClock (class)
Manual time and native clock scheduling belong to one deterministic owner.
Signature
declare class TestDeterministicClockcombineSignals
Combines cancellation sources without retaining their listeners after work.
Signature
declare const combineSignals: (...signals: (AbortSignal | undefined)[]) => CombinedSignals;createDeterministicClock
Creates a manually controlled native Effect clock without wall-time polling.
Signature
declare const createDeterministicClock: (startTime: number) => DeterministicClockService;deterministicClockLayer
Provides a replaceable clock service from the native manual-time implementation.
Signature
declare const deterministicClockLayer: (
startTime?: number,
) => Layer.Layer<TestDeterministicClock, never, never>;runtime-clock.types.ts
ClockWaiter (interface)
Owned deterministic deadline and its native completion callback.
Signature
export interface ClockWaiter {
readonly at: number;
readonly resume: (effect: Effect.Effect<void>) => void;
done: boolean;
}CombinedSignals (interface)
Native cancellation signal and the explicit lifetime of its source listeners.
Signature
export interface CombinedSignals {
readonly signal: AbortSignal;
readonly dispose: () => void;
}DeterministicClockService (interface)
Manually controlled native clock with an Effect invocation runner.
Signature
export interface DeterministicClockService {
readonly service: Clock.Clock;
readonly clock: TestClock;
readonly run: InvocationRunner["run"];
}runtime-close.ts
closeRuntime
Waits for bounded admitted work before cleaning temporary ownership.
Signature
declare const closeRuntime: (
pending: Set<Promise<unknown>>,
timeoutMs: number,
cleanup: (failed: boolean) => Effect.Effect<void, unknown>,
failed: () => boolean,
) => Effect.Effect<void, unknown, never>;runtime-context.ts
createTestContextFactory
Creates the validated runtime context defaults with an explicit caller patch.
Signature
declare const createTestContextFactory: (patch: Readonly<Record<string, unknown>>) => ({
invocation,
signal,
env,
time,
}: InvocationContextOptions) => Readonly<{
invocation: InvocationRecord;
signal: AbortSignal;
env: Readonly<Record<string, unknown>>;
time: PublicClock;
log: Readonly<{
trace: () => void;
debug: () => void;
info: () => void;
warn: () => void;
error: () => void;
}>;
jobs: Readonly<{}>;
events: Readonly<{}>;
buckets: Readonly<{}>;
cache: Readonly<{}>;
agents: Readonly<{}>;
database: Readonly<{}>;
auth: Readonly<{ getSession: () => Promise<null> }>;
constants: Readonly<{}>;
prompts: Readonly<{}>;
}>;runtime-execution.ts
TestRuntimeExecution (class)
Owns invocation admission, cancellation, deterministic dependencies and shutdown.
Signature
declare class TestRuntimeExecutiontestRuntimeLayer
Allocates a synchronously ready runtime domain service after validating all options.
Signature
declare const testRuntimeLayer: <S extends EnvShape = EnvShape>(
options?: TestRuntimeOptions<S>,
) => Layer.Layer<TestRuntimeExecution, never, never>;runtime-execution.types.ts
RuntimeExecutionService (interface)
Effect invocation admission and shutdown with deterministic native runtime state.
Signature
export interface RuntimeExecutionService {
readonly value: Omit<TestRuntime, "invoke" | "close">;
readonly invoke: <Target extends StandaloneFunctionTarget>(
target: Target,
input: FunctionInput<Target>,
options?: Omit<InvokeFunctionOptions<FunctionContextOf<Target>>, "env" | "now" | "idSource">,
) => Effect.Effect<FunctionOutput<Target>, unknown>;
readonly close: (options?: TestRuntimeCloseOptions) => Effect.Effect<void, unknown>;
}runtime-options.ts
resolveRuntimeEnv
Resolves explicit values through the application’s existing environment authority.
Signature
declare const resolveRuntimeEnv: <S extends EnvShape>(
options: TestRuntimeOptions<S>,
) => Readonly<Record<string, unknown>>;validateRuntimeTimeout
Rejects invalid close deadlines before allocating native resources.
Signature
declare const validateRuntimeTimeout: (value: number) => void;runtime.ts
TestClock
Signature
declare const TestClock: TestClock;TestRuntime
Signature
declare const TestRuntime: TestRuntime;TestRuntimeCloseOptions
Signature
declare const TestRuntimeCloseOptions: TestRuntimeCloseOptions;TestRuntimeOptions
Signature
declare const TestRuntimeOptions: TestRuntimeOptions<S>;createTestRuntime
Creates a small deterministic runtime for direct function tests.
Example
import { defineEnv } from "@relkit/app/config";
import { createTestRuntime } from "@relkit/testing";
export async function runtimeExample(): Promise<void> {
const runtime = createTestRuntime({ app: { env: defineEnv({}) } });
try {
await runtime.clock.advance(10);
} finally {
await runtime.close();
}
}See
- tests/fixtures/checked-examples.ts ownedHelpersExample for checked inference and release.
Signature
declare const createTestRuntime: <S extends EnvShape = EnvShape>(
options?: TestRuntimeOptions<S>,
) => TestRuntime;runtime.types.ts
TestClock (interface)
Deterministic native time facade advanced only by explicit test commands.
Signature
export interface TestClock {
readonly now: () => Date;
readonly currentTimeMs: () => number;
readonly advance: (milliseconds: number) => Promise<void>;
readonly setTime: (timestamp: number) => Promise<void>;
}TestRuntime (interface)
Owned direct invocation runtime with native dependency fakes and complete shutdown.
Signature
export interface TestRuntime {
readonly stateRoot: string;
readonly fakes: TestFakes;
readonly providers: TestProviderReplacements;
readonly env: Readonly<Record<string, unknown>>;
readonly clock: TestClock;
readonly invoke: <Target extends StandaloneFunctionTarget>(
target: Target,
input: FunctionInput<Target>,
options?: Omit<InvokeFunctionOptions<FunctionContextOf<Target>>, "env" | "now" | "idSource">,
) => Promise<FunctionOutput<Target>>;
readonly close: (options?: TestRuntimeCloseOptions) => Promise<void>;
}TestRuntimeCloseOptions (interface)
Explicit failed-test state retention policy for runtime shutdown.
Signature
export interface TestRuntimeCloseOptions {
readonly failed?: boolean;
}TestRuntimeOptions (interface)
Runtime options retaining the concrete application’s environment shape.
Signature
export interface TestRuntimeOptions<S extends EnvShape = EnvShape> {
readonly registry?: FunctionRegistry;
readonly logger?: LoggerOptions;
readonly app?: { readonly env: EnvDefinition<S> };
readonly environment?: string;
readonly env?: Readonly<Record<string, unknown>>;
readonly startTimeMs?: number;
readonly closeTimeoutMs?: number;
readonly context?: Readonly<Record<string, unknown>>;
readonly providers?: TestProviderReplacements;
/** Caller-owned roots enable explicit restart tests; omitted roots are temporary. */
readonly stateRoot?: string;
}state-providers.ts
Supplies local realtime and agent-state providers without selecting a native agent engine.
createTestAgentStateProvider
Constructs the native local agent state provider at an explicit test root.
Signature
declare const createTestAgentStateProvider: (root: string) => AgentStateProvider;createTestRealtimeProvider
Constructs the native local realtime provider at an explicit test root.
Signature
declare const createTestRealtimeProvider: (root: string) => RealtimeProvider;state-root.ts
TestStateRoot
Signature
declare const TestStateRoot: TestStateRoot;createTestStateRoot
Creates an owned temporary state root, or opens a caller-owned restart root.
Signature
declare const createTestStateRoot: (requestedPath?: string) => TestStateRoot;state-root.types.ts
Native temporary or caller-owned persistence path with idempotent cleanup.
TestStateRoot (interface)
Native temporary or caller-owned persistence path with idempotent cleanup.
Signature
export interface TestStateRoot {
readonly path: string;
readonly cleanup: (failed: boolean) => void;
}storage-failure.ts
InvalidTestSnapshot (class)
Typed invalid transfer boundary translated to the existing public TypeError family.
Signature
declare class InvalidTestSnapshottest-jobs-adapter-controls.ts
cancel
Applies the first native cancellation transition and acknowledgement receipt.
Signature
declare const cancel: (
runs: Map<string, TestNativeRun>,
receipts: Map<string, NativeControlReceipt>,
request: NativeCancelRequest,
unknownOutcome: boolean,
service: string,
clock: TestClock,
) => Promise<NativeControlReceipt>;retry
Creates a deduplicated native retry with a fresh canonical run identity.
Signature
declare const retry: (
runs: Map<string, TestNativeRun>,
receipts: Map<string, NativeControlReceipt>,
request: NativeRetryRequest,
unknownOutcome: boolean,
service: string,
clock: TestClock,
) => Promise<NativeControlReceipt>;unknown
Builds an explicit ambiguous native write result.
Signature
declare const unknown: (
code: JobUnknownOutcome["code"],
operationId: string,
idempotencyKey?: string,
) => JobUnknownOutcome;test-jobs-adapter-support.ts
TestNativeRun
Signature
declare const TestNativeRun: TestNativeRun;detachedNativeSnapshot
Reads a detached native snapshot, including retained state after owner close.
Signature
declare const detachedNativeSnapshot: (
state: NativeJobsState,
runId: string,
service: string,
clock: TestClock,
) => RunSnapshot;failureOf
Projects an unknown worker failure into the existing public envelope.
Signature
declare const failureOf: (value: unknown) => JobErrorEnvelope;isTerminal
Classifies native job terminal lifecycle states.
Signature
declare const isTerminal: (status: RunSnapshot["status"]) => boolean;requestKey
Builds the existing canonical submission deduplication identity.
Signature
declare const requestKey: (request: NativeSubmission) => string | undefined;snapshotOf
Projects a native run using the injected observation clock.
Signature
declare const snapshotOf: (run: TestNativeRun, service: string, clock: TestClock) => RunSnapshot;test-jobs-adapter-support.types.ts
TestNativeRun (interface)
Mutable deterministic native run state with owned worker cancellation.
Signature
export interface TestNativeRun {
readonly request: NativeSubmission;
readonly runId: string;
readonly acceptedAt: string;
status: RunSnapshot["status"];
attempt: number;
startedAt?: string;
completedAt?: string;
output?: unknown;
error?: JobErrorEnvelope;
retryOfRunId?: string;
readonly canonicalInput: JobWireEnvelope;
controller?: AbortController;
disposeSignal?: () => void;
}test-jobs-adapter-work.ts
complete
Commits a nonterminal worker’s successful native outcome.
Signature
declare const complete: (
run: TestNativeRun | undefined,
output: unknown,
clock: TestClock,
) => Promise<void>;createRun
Creates one queued native run using an injected acceptance clock.
Signature
declare const createRun: (
request: NativeSubmission,
runId: string,
retryOfRunId: string | undefined,
clock: TestClock,
) => TestNativeRun;fail
Commits a nonterminal worker’s bounded native failure envelope.
Signature
declare const fail: (
run: TestNativeRun | undefined,
error: unknown,
clock: TestClock,
) => Promise<void>;handle
Projects the accepted native run identity.
Signature
declare const handle: (run: TestNativeRun) => RunHandle;list
Filters native runs and returns detached deterministic snapshots.
Signature
declare const list: (
runs: Map<string, TestNativeRun>,
query: NativeRunQuery,
service: string,
clock: TestClock,
) => RunPage<RunSnapshot>;next
Admits one queued native task and binds native cancellation.
Signature
declare const next: (
runs: Map<string, TestNativeRun>,
context: OperationContext,
service: string,
clock: TestClock,
) => Promise<NativeTaskWork | undefined>;test-jobs-adapter.ts
TestJobsAdapter
Signature
declare const TestJobsAdapter: TestJobsAdapter;TestJobsAdapterOptions
Signature
declare const TestJobsAdapterOptions: TestJobsAdapterOptions;createDeterministicJobsAdapter
Creates a synchronous compatibility adapter over one deterministic jobs owner.
Signature
declare const createDeterministicJobsAdapter: (options?: TestJobsAdapterOptions) => TestJobsAdapter;createTestJobsAdapter
Signature
declare const createTestJobsAdapter: (options?: TestJobsAdapterOptions) => TestJobsAdapter;test-jobs-adapter.types.ts
TestJobsAdapter (interface)
Owned native jobs adapter with deterministic worker and snapshot test controls.
Signature
export interface TestJobsAdapter extends JobsAdapterRuntime {
readonly clock: TestClock;
readonly runNext: () => Promise<import("@relkit/jobs/adapter").NativeTaskWork | undefined>;
readonly snapshot: (runId: string) => RunSnapshot;
}TestJobsAdapterOptions (interface)
Deterministic native adapter time, failure injection and unknown-outcome policy.
Signature
export interface TestJobsAdapterOptions {
readonly logger?: import("@relkit/runtime-effect").LoggerOptions;
readonly clock?: TestClock;
readonly startTimeMs?: number;
readonly service?: string;
readonly unknown?: Partial<Record<"submit" | "cancel" | "retry", boolean>>;
}testing-owner.ts
disposeTestingOwner
Releases an existing owner while retaining native failure identity.
See
- tests/fixtures/checked-examples.ts deterministicServicesExample for checked ownership.
Signature
declare const disposeTestingOwner: <R, E>(
owner: ManagedRuntime.ManagedRuntime<R, E>,
) => Promise<void>;runRetainedTestingQuery
Reads retained, resource-free state using the owner’s captured observation context.
Signature
declare const runRetainedTestingQuery: <A>(
context: Context.Context<never>,
query: Effect.Effect<A, unknown>,
) => Promise<A>;testingLoggerLayer
Provisions redacting server logging once at a test helper’s ownership boundary.
See
- tests/fixtures/checked-examples.ts deterministicServicesExample for checked provisioning.
Signature
declare const testingLoggerLayer: (options?: LoggerOptions) => Layer.Layer<never>;work-ownership.ts
admitOwnedWork
Registers scoped work before restoring caller interruption at its join boundary.
Signature
declare const admitOwnedWork: <A>(
state: WorkOwnershipState,
scope: Scope.Scope,
context: Context.Context<never>,
work: Effect.Effect<A, unknown>,
) => Effect.Effect<A, unknown>;joinOwnedWork
Joins every actual completion while retaining failed operations as settled work.
Signature
declare const joinOwnedWork: (
pending: Iterable<Promise<unknown>>,
) => Effect.Effect<void, never, never>;ownedLifecycle
Owns restart and close ordering without replacing native persistence authorities.
Signature
declare const ownedLifecycle: (
state: WorkOwnershipState,
scope: Scope.Scope,
context: Context.Context<never>,
release: Effect.Effect<void, unknown>,
acquire: Effect.Effect<void, unknown>,
cleanup: (failed: boolean) => Effect.Effect<void>,
closeOperation: OwnedCloseOperation,
) => {
restart: Effect.Effect<void, unknown, never>;
close: (failed?: boolean) => Effect.Effect<void, unknown, never>;
};runOwnedContext
Runs a native facade callback in its already acquired observation context.
Signature
declare const runOwnedContext: <A>(
context: Context.Context<never>,
effect: Effect.Effect<A, unknown>,
) => Promise<A>;work-ownership.types.ts
Native completion receipts and admission state shared by one scoped harness.
OwnedCloseOperation (type alias)
Fixed release labels supplied only by the two declaration-owned durable harnesses.
Signature
type OwnedCloseOperation = "job.close" | "event.close";WorkOwnershipState (interface)
Native completion receipts and admission state shared by one scoped harness.
Signature
export interface WorkOwnershipState {
readonly kind?: string;
closed: boolean;
controller: AbortController;
pending: Set<Promise<unknown>>;
restarting?: Promise<void>;
closing?: Promise<void>;
}