@fedify/testing 2.4.0-pr.936.41 → 2.5.0-dev.2271

package/dist/mod.d.cts

@@ -1,7 +1,8 @@
 /// <reference lib="esnext.temporal" />
-import { Context, Federation, InboxContext, OutboxContext, RequestContext } from "@fedify/fedify/federation";
+import { Context, Federation, InboxContext, OutboxContext, PortableRequest, RequestContext } from "@fedify/fedify/federation";
 import { Activity } from "@fedify/vocab";
-import { MessageQueue } from "@fedify/fedify";
+import { DocumentLoader, PortableObjectVerifier } from "@fedify/vocab-runtime";
+import { KvStore, MessageQueue } from "@fedify/fedify";
 
 //#region src/context.d.ts
 declare function createContext<TContextData>(values: Partial<Context<TContextData>> & {
@@ -22,6 +23,10 @@ declare function createRequestContext<TContextData>(args: Partial<RequestContext
   federation: Federation<TContextData>;
 }): RequestContext<TContextData>;
 /**
+* The default implementation of `RequestContext.isSignedByAudience()` for
+* testing, which checks the audience against `getSignedKeyOwner()`.
+*/
+/**
 * Test-specific InboxContext type alias.
 * This indirection helps avoid JSR type analyzer issues.
 * @since 1.9.1
@@ -82,7 +87,7 @@ interface SentActivity {
 * Extends the standard Context interface with additional testing utilities.
 * @since 1.9.1
 */
-interface TestContext<TContextData> extends Omit<Context<TContextData>, "clone">, Pick<RequestContext<TContextData>, "request" | "url" | "getActor" | "getObject" | "getSignedKey" | "getSignedKeyOwner" | "sendActivity" | "routeActivity"> {
+interface TestContext<TContextData> extends Omit<Context<TContextData>, "clone">, Pick<RequestContext<TContextData>, "request" | "url" | "portableRequest" | "getActor" | "getObject" | "getSignedKey" | "getSignedKeyOwner" | "isSignedByAudience" | "sendActivity" | "routeActivity"> {
   clone(data: TContextData): TestContext<TContextData>;
   getSentActivities(): Array<{
     sender: any;
@@ -104,7 +109,13 @@ interface TestFederation<TContextData> extends Omit<Federation<TContextData>, "c
   receiveActivity(activity: Activity): Promise<void>;
   postOutboxActivity(identifier: string, activity: Activity): Promise<void>;
   reset(): void;
-  createContext(baseUrlOrRequest: URL | Request, contextData: TContextData): TestContext<TContextData>;
+  createContext(baseUrl: URL, contextData: TContextData): TestContext<TContextData>;
+  createContext(request: Request, contextData: TContextData, options?: {
+    portableRequest?: PortableRequest;
+  }): TestContext<TContextData>;
+  createContext(baseUrlOrRequest: URL | Request, contextData: TContextData, options?: {
+    portableRequest?: PortableRequest;
+  }): TestContext<TContextData>;
 }
 /**
 * Creates a mock Federation instance for testing purposes.
@@ -150,9 +161,64 @@ declare function createFederation<TContextData>(options?: {
   * @since 2.3.0
   */
   meterProvider?: any;
-  tracerProvider?: any;
+  tracerProvider?: any; /** The document loader used by mock context lookups. @since 2.4.0 */
+  documentLoader?: DocumentLoader; /** The JSON-LD context loader used by mock context lookups. @since 2.4.0 */
+  contextLoader?: DocumentLoader;
+  /**
+  * The portable object verifier used by mock context lookups when a
+  * document loader is provided.  Mock collection traversal remains empty.
+  * @since 2.4.0
+  */
+  verifyPortableObject?: PortableObjectVerifier;
 }): TestFederation<TContextData>;
 //#endregion
+//#region src/kv-tester.d.ts
+/**
+* Options for {@link testKvStore}.
+*/
+interface TestKvStoreOptions {
+  /**
+  * Whether to test compare-and-swap support.  By default, these tests run
+  * when the store implements {@link KvStore.cas}.
+  */
+  readonly testCas?: boolean;
+  /**
+  * Whether to test time-to-live support.  `true` by default.
+  * @default true
+  */
+  readonly testTtl?: boolean;
+}
+/**
+* Tests a {@link KvStore} implementation with a standard set of tests.
+*
+* The suite covers reads and writes, deletion, structured keys and values,
+* prefix listing, TTL expiration, and optional compare-and-swap behavior.
+* Every key is isolated below a random prefix and is deleted after the suite.
+*
+* @example
+* ```typescript ignore
+* import { test } from "@fedify/fixture";
+* import { testKvStore } from "@fedify/testing";
+* import { MyKvStore } from "./my-kv.ts";
+*
+* test("MyKvStore", () =>
+*   testKvStore(
+*     () => new MyKvStore(),
+*     async ({ store }) => await store.close(),
+*   )
+* );
+* ```
+*
+* @param getKvStore A factory that creates the store to test.
+* @param onFinally A cleanup function called after the suite completes.
+* @param options Optional configuration for the suite.
+*/
+declare function testKvStore<KV extends KvStore>(getKvStore: () => KV | Promise<KV>, onFinally: ({
+  store
+}: {
+  store: KV;
+}) => Promise<void> | void, options?: TestKvStoreOptions): Promise<void>;
+//#endregion
 //#region src/mq-tester.d.ts
 /**
 * Options for {@link testMessageQueue}.
@@ -223,4 +289,4 @@ declare function testMessageQueue<MQ extends MessageQueue>(getMessageQueue: () =
 declare function waitFor(predicate: () => boolean, timeoutMs: number): Promise<void>;
 declare const getRandomKey: (prefix: string) => string;
 //#endregion
-export { type TestMessageQueueOptions, createContext, createFederation, createInboxContext, createOutboxContext, createRequestContext, getRandomKey, testMessageQueue, waitFor };
+export { type TestKvStoreOptions, type TestMessageQueueOptions, createContext, createFederation, createInboxContext, createOutboxContext, createRequestContext, getRandomKey, testKvStore, testMessageQueue, waitFor };

package/dist/mod.d.ts

@@ -1,7 +1,8 @@
 /// <reference lib="esnext.temporal" />
 import { Activity } from "@fedify/vocab";
-import { Context, Federation, InboxContext, OutboxContext, RequestContext } from "@fedify/fedify/federation";
-import { MessageQueue } from "@fedify/fedify";
+import { DocumentLoader, PortableObjectVerifier } from "@fedify/vocab-runtime";
+import { Context, Federation, InboxContext, OutboxContext, PortableRequest, RequestContext } from "@fedify/fedify/federation";
+import { KvStore, MessageQueue } from "@fedify/fedify";
 
 //#region src/context.d.ts
 declare function createContext<TContextData>(values: Partial<Context<TContextData>> & {
@@ -22,6 +23,10 @@ declare function createRequestContext<TContextData>(args: Partial<RequestContext
   federation: Federation<TContextData>;
 }): RequestContext<TContextData>;
 /**
+* The default implementation of `RequestContext.isSignedByAudience()` for
+* testing, which checks the audience against `getSignedKeyOwner()`.
+*/
+/**
 * Test-specific InboxContext type alias.
 * This indirection helps avoid JSR type analyzer issues.
 * @since 1.9.1
@@ -82,7 +87,7 @@ interface SentActivity {
 * Extends the standard Context interface with additional testing utilities.
 * @since 1.9.1
 */
-interface TestContext<TContextData> extends Omit<Context<TContextData>, "clone">, Pick<RequestContext<TContextData>, "request" | "url" | "getActor" | "getObject" | "getSignedKey" | "getSignedKeyOwner" | "sendActivity" | "routeActivity"> {
+interface TestContext<TContextData> extends Omit<Context<TContextData>, "clone">, Pick<RequestContext<TContextData>, "request" | "url" | "portableRequest" | "getActor" | "getObject" | "getSignedKey" | "getSignedKeyOwner" | "isSignedByAudience" | "sendActivity" | "routeActivity"> {
   clone(data: TContextData): TestContext<TContextData>;
   getSentActivities(): Array<{
     sender: any;
@@ -104,7 +109,13 @@ interface TestFederation<TContextData> extends Omit<Federation<TContextData>, "c
   receiveActivity(activity: Activity): Promise<void>;
   postOutboxActivity(identifier: string, activity: Activity): Promise<void>;
   reset(): void;
-  createContext(baseUrlOrRequest: URL | Request, contextData: TContextData): TestContext<TContextData>;
+  createContext(baseUrl: URL, contextData: TContextData): TestContext<TContextData>;
+  createContext(request: Request, contextData: TContextData, options?: {
+    portableRequest?: PortableRequest;
+  }): TestContext<TContextData>;
+  createContext(baseUrlOrRequest: URL | Request, contextData: TContextData, options?: {
+    portableRequest?: PortableRequest;
+  }): TestContext<TContextData>;
 }
 /**
 * Creates a mock Federation instance for testing purposes.
@@ -150,9 +161,64 @@ declare function createFederation<TContextData>(options?: {
   * @since 2.3.0
   */
   meterProvider?: any;
-  tracerProvider?: any;
+  tracerProvider?: any; /** The document loader used by mock context lookups. @since 2.4.0 */
+  documentLoader?: DocumentLoader; /** The JSON-LD context loader used by mock context lookups. @since 2.4.0 */
+  contextLoader?: DocumentLoader;
+  /**
+  * The portable object verifier used by mock context lookups when a
+  * document loader is provided.  Mock collection traversal remains empty.
+  * @since 2.4.0
+  */
+  verifyPortableObject?: PortableObjectVerifier;
 }): TestFederation<TContextData>;
 //#endregion
+//#region src/kv-tester.d.ts
+/**
+* Options for {@link testKvStore}.
+*/
+interface TestKvStoreOptions {
+  /**
+  * Whether to test compare-and-swap support.  By default, these tests run
+  * when the store implements {@link KvStore.cas}.
+  */
+  readonly testCas?: boolean;
+  /**
+  * Whether to test time-to-live support.  `true` by default.
+  * @default true
+  */
+  readonly testTtl?: boolean;
+}
+/**
+* Tests a {@link KvStore} implementation with a standard set of tests.
+*
+* The suite covers reads and writes, deletion, structured keys and values,
+* prefix listing, TTL expiration, and optional compare-and-swap behavior.
+* Every key is isolated below a random prefix and is deleted after the suite.
+*
+* @example
+* ```typescript ignore
+* import { test } from "@fedify/fixture";
+* import { testKvStore } from "@fedify/testing";
+* import { MyKvStore } from "./my-kv.ts";
+*
+* test("MyKvStore", () =>
+*   testKvStore(
+*     () => new MyKvStore(),
+*     async ({ store }) => await store.close(),
+*   )
+* );
+* ```
+*
+* @param getKvStore A factory that creates the store to test.
+* @param onFinally A cleanup function called after the suite completes.
+* @param options Optional configuration for the suite.
+*/
+declare function testKvStore<KV extends KvStore>(getKvStore: () => KV | Promise<KV>, onFinally: ({
+  store
+}: {
+  store: KV;
+}) => Promise<void> | void, options?: TestKvStoreOptions): Promise<void>;
+//#endregion
 //#region src/mq-tester.d.ts
 /**
 * Options for {@link testMessageQueue}.
@@ -223,4 +289,4 @@ declare function testMessageQueue<MQ extends MessageQueue>(getMessageQueue: () =
 declare function waitFor(predicate: () => boolean, timeoutMs: number): Promise<void>;
 declare const getRandomKey: (prefix: string) => string;
 //#endregion
-export { type TestMessageQueueOptions, createContext, createFederation, createInboxContext, createOutboxContext, createRequestContext, getRandomKey, testMessageQueue, waitFor };
+export { type TestKvStoreOptions, type TestMessageQueueOptions, createContext, createFederation, createInboxContext, createOutboxContext, createRequestContext, getRandomKey, testKvStore, testMessageQueue, waitFor };