@tinycloudlabs/sdk-services-test 1.0.0

package/dist/MockServiceContext.js

@@ -0,0 +1,280 @@
+/**
+ * MockServiceContext - Test implementation of IServiceContext
+ *
+ * Provides a configurable mock context for testing services
+ * without network dependencies.
+ */
+/**
+ * MockServiceContext implements IServiceContext for testing.
+ *
+ * Features:
+ * - In-memory service registry
+ * - Configurable mock invoke that returns test data
+ * - Configurable mock fetch with pattern matching
+ * - Event emission tracking for assertions
+ * - Session state management
+ *
+ * @example
+ * ```typescript
+ * const context = new MockServiceContext({
+ *   session: createMockSession(),
+ *   fetchResponses: new Map([
+ *     ['/invoke', { ok: true, status: 200, body: { data: 'test' } }],
+ *   ]),
+ * });
+ *
+ * const kv = new KVService({});
+ * kv.initialize(context);
+ * context.registerService('kv', kv);
+ *
+ * // Assert events were emitted
+ * expect(context.getEmittedEvents('service.request')).toHaveLength(1);
+ * ```
+ */
+export class MockServiceContext {
+    constructor(config = {}) {
+        this._services = new Map();
+        this._eventHandlers = new Map();
+        this._emittedEvents = [];
+        this._abortController = new AbortController();
+        this._invokeCallCount = 0;
+        this._fetchCallCount = 0;
+        this._session = config.session ?? null;
+        this.hosts = config.hosts ?? ["https://mock.tinycloud.test"];
+        this._fetchResponses = config.fetchResponses ?? new Map();
+        this._defaultFetchResponse = config.defaultFetchResponse ?? {
+            ok: true,
+            status: 200,
+            statusText: "OK",
+            body: {},
+        };
+        this._invokeFunction = config.invoke ?? this.defaultInvoke.bind(this);
+        this.retryPolicy = config.retryPolicy ?? {
+            maxAttempts: 3,
+            backoff: "exponential",
+            baseDelayMs: 1000,
+            maxDelayMs: 10000,
+            retryableErrors: ["NETWORK_ERROR", "TIMEOUT"],
+        };
+    }
+    // ============================================================
+    // Session Management
+    // ============================================================
+    get session() {
+        return this._session;
+    }
+    get isAuthenticated() {
+        return this._session !== null;
+    }
+    /**
+     * Set the session (test helper).
+     */
+    setSession(session) {
+        this._session = session;
+        this.emit("session.changed", { authenticated: session !== null });
+        for (const service of this._services.values()) {
+            service.onSessionChange(session);
+        }
+    }
+    // ============================================================
+    // Platform Dependencies
+    // ============================================================
+    /**
+     * Default invoke implementation that returns mock headers.
+     */
+    defaultInvoke(session, service, path, action) {
+        return {
+            Authorization: `Bearer mock-token-${service}-${action}`,
+            "X-Mock-Service": service,
+            "X-Mock-Path": path,
+            "X-Mock-Action": action,
+        };
+    }
+    get invoke() {
+        return (session, service, path, action) => {
+            this._invokeCallCount++;
+            return this._invokeFunction(session, service, path, action);
+        };
+    }
+    get fetch() {
+        return async (url, init) => {
+            this._fetchCallCount++;
+            // Find matching response
+            let mockResponse = this._defaultFetchResponse;
+            for (const [pattern, handler] of this._fetchResponses) {
+                const matches = typeof pattern === "string"
+                    ? url.includes(pattern)
+                    : pattern.test(url);
+                if (matches) {
+                    if (typeof handler === "function") {
+                        mockResponse = await handler(url, init);
+                    }
+                    else {
+                        mockResponse = handler;
+                    }
+                    break;
+                }
+            }
+            // Create mock response object
+            const headers = new Map(Object.entries(mockResponse.headers ?? {}).map(([k, v]) => [
+                k.toLowerCase(),
+                v,
+            ]));
+            return {
+                ok: mockResponse.ok,
+                status: mockResponse.status,
+                statusText: mockResponse.statusText,
+                headers: {
+                    get: (name) => headers.get(name.toLowerCase()) ?? null,
+                },
+                json: async () => mockResponse.body,
+                text: async () => typeof mockResponse.body === "string"
+                    ? mockResponse.body
+                    : JSON.stringify(mockResponse.body),
+            };
+        };
+    }
+    // ============================================================
+    // Service Registry
+    // ============================================================
+    registerService(name, service) {
+        this._services.set(name, service);
+    }
+    unregisterService(name) {
+        this._services.delete(name);
+    }
+    getService(name) {
+        return this._services.get(name);
+    }
+    // ============================================================
+    // Event System (Telemetry)
+    // ============================================================
+    emit(event, data) {
+        // Record the event for assertions
+        this._emittedEvents.push({
+            event,
+            data,
+            timestamp: Date.now(),
+        });
+        // Notify handlers
+        const handlers = this._eventHandlers.get(event);
+        if (handlers) {
+            for (const handler of handlers) {
+                try {
+                    handler(data);
+                }
+                catch {
+                    // Swallow errors in handlers during tests
+                }
+            }
+        }
+    }
+    on(event, handler) {
+        if (!this._eventHandlers.has(event)) {
+            this._eventHandlers.set(event, new Set());
+        }
+        this._eventHandlers.get(event).add(handler);
+        return () => {
+            const handlers = this._eventHandlers.get(event);
+            if (handlers) {
+                handlers.delete(handler);
+                if (handlers.size === 0) {
+                    this._eventHandlers.delete(event);
+                }
+            }
+        };
+    }
+    // ============================================================
+    // Lifecycle
+    // ============================================================
+    get abortSignal() {
+        return this._abortController.signal;
+    }
+    /**
+     * Abort all operations (test helper).
+     */
+    abort() {
+        this._abortController.abort();
+        this._abortController = new AbortController();
+        for (const service of this._services.values()) {
+            service.onSignOut();
+        }
+    }
+    // ============================================================
+    // Test Assertion Helpers
+    // ============================================================
+    /**
+     * Get all emitted events.
+     */
+    getEmittedEvents() {
+        return [...this._emittedEvents];
+    }
+    /**
+     * Get emitted events filtered by event name.
+     */
+    getEmittedEventsByName(eventName) {
+        return this._emittedEvents.filter((e) => e.event === eventName);
+    }
+    /**
+     * Check if a specific event was emitted.
+     */
+    wasEventEmitted(eventName) {
+        return this._emittedEvents.some((e) => e.event === eventName);
+    }
+    /**
+     * Get the count of events by name.
+     */
+    getEventCount(eventName) {
+        return this._emittedEvents.filter((e) => e.event === eventName).length;
+    }
+    /**
+     * Clear all recorded events.
+     */
+    clearEmittedEvents() {
+        this._emittedEvents = [];
+    }
+    /**
+     * Get the number of invoke calls.
+     */
+    get invokeCallCount() {
+        return this._invokeCallCount;
+    }
+    /**
+     * Get the number of fetch calls.
+     */
+    get fetchCallCount() {
+        return this._fetchCallCount;
+    }
+    /**
+     * Reset call counts.
+     */
+    resetCallCounts() {
+        this._invokeCallCount = 0;
+        this._fetchCallCount = 0;
+    }
+    /**
+     * Add a mock fetch response for a URL pattern.
+     */
+    addFetchResponse(pattern, response) {
+        this._fetchResponses.set(pattern, response);
+    }
+    /**
+     * Remove a mock fetch response.
+     */
+    removeFetchResponse(pattern) {
+        this._fetchResponses.delete(pattern);
+    }
+    /**
+     * Clear all mock fetch responses.
+     */
+    clearFetchResponses() {
+        this._fetchResponses.clear();
+    }
+    /**
+     * Set the default fetch response.
+     */
+    setDefaultFetchResponse(response) {
+        this._defaultFetchResponse = response;
+    }
+}
+//# sourceMappingURL=MockServiceContext.js.map

package/dist/MockServiceContext.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MockServiceContext.js","sourceRoot":"","sources":["../src/MockServiceContext.ts"],"names":[],"mappings":"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"}

package/dist/helpers.d.ts

@@ -0,0 +1,219 @@
+/**
+ * Test Utilities for SDK Services
+ *
+ * Factory functions and helpers for creating test fixtures.
+ */
+import type { ServiceSession } from "@tinycloudlabs/sdk-services";
+import { MockServiceContext, MockServiceContextConfig, MockFetchResponse } from "./MockServiceContext";
+import { MockKVService, MockKVServiceConfig } from "./MockKVService";
+/**
+ * Options for creating a test context.
+ */
+export interface CreateTestContextOptions extends MockServiceContextConfig {
+    /** Whether to include a default authenticated session */
+    authenticated?: boolean;
+    /** Custom session data */
+    sessionOverrides?: Partial<ServiceSession>;
+}
+/**
+ * Create a mock ServiceSession for testing.
+ *
+ * @param overrides - Optional overrides for session fields
+ * @returns A mock ServiceSession
+ *
+ * @example
+ * ```typescript
+ * const session = createMockSession();
+ * const customSession = createMockSession({
+ *   spaceId: 'space:custom-id',
+ * });
+ * ```
+ */
+export declare function createMockSession(overrides?: Partial<ServiceSession>): ServiceSession;
+/**
+ * Create a MockServiceContext with sensible defaults for testing.
+ *
+ * @param options - Configuration options
+ * @returns A configured MockServiceContext
+ *
+ * @example
+ * ```typescript
+ * // Create an authenticated context
+ * const context = createTestContext({ authenticated: true });
+ *
+ * // Create with custom fetch responses
+ * const context = createTestContext({
+ *   authenticated: true,
+ *   fetchResponses: new Map([
+ *     ['/invoke', { ok: true, status: 200, body: { data: 'test' } }],
+ *   ]),
+ * });
+ * ```
+ */
+export declare function createTestContext(options?: CreateTestContextOptions): MockServiceContext;
+/**
+ * Create a MockKVService with initial data.
+ *
+ * @param initialData - Key-value pairs to seed the store
+ * @param config - Additional configuration
+ * @returns A configured MockKVService
+ *
+ * @example
+ * ```typescript
+ * const kv = createMockKV({
+ *   'user/settings': { theme: 'dark' },
+ *   'user/profile': { name: 'Alice' },
+ * });
+ *
+ * // With latency simulation
+ * const kv = createMockKV(
+ *   { 'key': 'value' },
+ *   { latencyMs: 50 }
+ * );
+ * ```
+ */
+export declare function createMockKV(initialData?: Record<string, unknown>, config?: Omit<MockKVServiceConfig, "initialData">): MockKVService;
+/**
+ * Wait for a specific event to be emitted from a context.
+ *
+ * @param context - The MockServiceContext to listen on
+ * @param eventName - The event name to wait for
+ * @param timeoutMs - Timeout in milliseconds (default: 5000)
+ * @returns Promise that resolves with the event data
+ *
+ * @example
+ * ```typescript
+ * // Wait for session change event
+ * const eventPromise = waitForEvent(context, 'session.changed');
+ * context.setSession(createMockSession());
+ * const eventData = await eventPromise;
+ * expect(eventData.authenticated).toBe(true);
+ * ```
+ */
+export declare function waitForEvent(context: MockServiceContext, eventName: string, timeoutMs?: number): Promise<unknown>;
+/**
+ * Wait for multiple events to be emitted.
+ *
+ * @param context - The MockServiceContext to listen on
+ * @param eventName - The event name to wait for
+ * @param count - Number of events to wait for
+ * @param timeoutMs - Timeout in milliseconds (default: 5000)
+ * @returns Promise that resolves with array of event data
+ *
+ * @example
+ * ```typescript
+ * // Wait for 3 service requests
+ * const eventsPromise = waitForEvents(context, 'service.request', 3);
+ * await kv.get('key1');
+ * await kv.get('key2');
+ * await kv.get('key3');
+ * const events = await eventsPromise;
+ * expect(events).toHaveLength(3);
+ * ```
+ */
+export declare function waitForEvents(context: MockServiceContext, eventName: string, count: number, timeoutMs?: number): Promise<unknown[]>;
+/**
+ * Create a mock fetch response for success scenarios.
+ *
+ * @param body - Response body
+ * @param headers - Optional response headers
+ * @returns MockFetchResponse
+ *
+ * @example
+ * ```typescript
+ * const response = mockOkResponse({ keys: ['a', 'b'] });
+ * context.addFetchResponse('/invoke', response);
+ * ```
+ */
+export declare function mockOkResponse(body: unknown, headers?: Record<string, string>): MockFetchResponse;
+/**
+ * Create a mock fetch response for error scenarios.
+ *
+ * @param status - HTTP status code
+ * @param body - Error body
+ * @param statusText - Optional status text
+ * @returns MockFetchResponse
+ *
+ * @example
+ * ```typescript
+ * const response = mockErrorResponse(404, { error: 'Not found' });
+ * context.addFetchResponse('/invoke', response);
+ * ```
+ */
+export declare function mockErrorResponse(status: number, body?: unknown, statusText?: string): MockFetchResponse;
+/**
+ * Create a delayed mock fetch handler for testing latency.
+ *
+ * @param response - The response to return after delay
+ * @param delayMs - Delay in milliseconds
+ * @returns Mock fetch handler function
+ *
+ * @example
+ * ```typescript
+ * context.addFetchResponse(
+ *   '/invoke',
+ *   delayedResponse(mockOkResponse({ data: 'test' }), 100)
+ * );
+ * ```
+ */
+export declare function delayedResponse(response: MockFetchResponse, delayMs: number): () => Promise<MockFetchResponse>;
+/**
+ * Create a sequence of mock responses that cycle through.
+ *
+ * @param responses - Array of responses to cycle through
+ * @returns Mock fetch handler function
+ *
+ * @example
+ * ```typescript
+ * // First call returns error, subsequent calls succeed
+ * context.addFetchResponse(
+ *   '/invoke',
+ *   sequenceResponses([
+ *     mockErrorResponse(503, 'Temporarily unavailable'),
+ *     mockOkResponse({ data: 'success' }),
+ *   ])
+ * );
+ * ```
+ */
+export declare function sequenceResponses(responses: MockFetchResponse[]): () => MockFetchResponse;
+/**
+ * Assert that an operation was recorded with specific properties.
+ *
+ * @param kv - The MockKVService to check
+ * @param expected - Expected operation properties
+ * @returns Whether a matching operation was found
+ *
+ * @example
+ * ```typescript
+ * await kv.put('key', 'value');
+ * expect(wasOperationRecorded(kv, { type: 'put', key: 'key' })).toBe(true);
+ * ```
+ */
+export declare function wasOperationRecorded(kv: MockKVService, expected: Partial<{
+    type: "get" | "put" | "list" | "delete" | "head";
+    key: string;
+    value: unknown;
+}>): boolean;
+/**
+ * Setup a MockKVService with a MockServiceContext.
+ *
+ * @param kvConfig - MockKVService configuration
+ * @param contextConfig - MockServiceContext configuration
+ * @returns Object with initialized kv and context
+ *
+ * @example
+ * ```typescript
+ * const { kv, context } = setupMockKV(
+ *   { initialData: { 'key': 'value' } },
+ *   { authenticated: true }
+ * );
+ *
+ * const result = await kv.get('key');
+ * expect(result.ok).toBe(true);
+ * ```
+ */
+export declare function setupMockKV(kvConfig?: MockKVServiceConfig, contextConfig?: CreateTestContextOptions): {
+    kv: MockKVService;
+    context: MockServiceContext;
+};
+//# sourceMappingURL=helpers.d.ts.map

package/dist/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../src/helpers.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAClE,OAAO,EACL,kBAAkB,EAClB,wBAAwB,EACxB,iBAAiB,EAClB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAErE;;GAEG;AACH,MAAM,WAAW,wBAAyB,SAAQ,wBAAwB;IACxE,yDAAyD;IACzD,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,0BAA0B;IAC1B,gBAAgB,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,CAAC;CAC5C;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,GAClC,cAAc,CAgBhB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,GAAE,wBAA6B,GACrC,kBAAkB,CAapB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,YAAY,CAC1B,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACrC,MAAM,CAAC,EAAE,IAAI,CAAC,mBAAmB,EAAE,aAAa,CAAC,GAChD,aAAa,CAKf;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,kBAAkB,EAC3B,SAAS,EAAE,MAAM,EACjB,SAAS,GAAE,MAAa,GACvB,OAAO,CAAC,OAAO,CAAC,CAalB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,kBAAkB,EAC3B,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,EACb,SAAS,GAAE,MAAa,GACvB,OAAO,CAAC,OAAO,EAAE,CAAC,CAsBpB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,OAAO,EACb,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC/B,iBAAiB,CAWnB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE,OAAO,EACd,UAAU,CAAC,EAAE,MAAM,GAClB,iBAAiB,CAUnB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,iBAAiB,EAC3B,OAAO,EAAE,MAAM,GACd,MAAM,OAAO,CAAC,iBAAiB,CAAC,CAKlC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,iBAAiB,EAAE,GAC7B,MAAM,iBAAiB,CASzB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,CAClC,EAAE,EAAE,aAAa,EACjB,QAAQ,EAAE,OAAO,CAAC;IAChB,IAAI,EAAE,KAAK,GAAG,KAAK,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,CAAC;IACjD,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,OAAO,CAAC;CAChB,CAAC,GACD,OAAO,CAST;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,WAAW,CACzB,QAAQ,CAAC,EAAE,mBAAmB,EAC9B,aAAa,CAAC,EAAE,wBAAwB,GACvC;IAAE,EAAE,EAAE,aAAa,CAAC;IAAC,OAAO,EAAE,kBAAkB,CAAA;CAAE,CAMpD"}