@demokit-ai/core 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,565 @@
+/**
+ * Session state management for DemoKit
+ *
+ * Provides in-memory storage for mutable state during a demo session.
+ * State persists across requests but resets on page refresh.
+ */
+/**
+ * Session state interface for storing and retrieving demo session data
+ *
+ * @example
+ * ```typescript
+ * // In a fixture handler
+ * 'POST /api/users': ({ body, session }) => {
+ *   const users = session.get<User[]>('users') || []
+ *   const newUser = { id: crypto.randomUUID(), ...body }
+ *   session.set('users', [...users, newUser])
+ *   return newUser
+ * }
+ *
+ * 'GET /api/users': ({ session }) => {
+ *   return session.get<User[]>('users') || []
+ * }
+ * ```
+ */
+interface SessionState {
+    /**
+     * Get a value from the session state
+     * @param key - The key to retrieve
+     * @returns The value if it exists, undefined otherwise
+     */
+    get<T>(key: string): T | undefined;
+    /**
+     * Set a value in the session state
+     * @param key - The key to set
+     * @param value - The value to store
+     */
+    set<T>(key: string, value: T): void;
+    /**
+     * Delete a value from the session state
+     * @param key - The key to delete
+     */
+    delete(key: string): void;
+    /**
+     * Clear all session state
+     */
+    clear(): void;
+    /**
+     * Get all keys in the session state
+     * @returns Array of all keys
+     */
+    keys(): string[];
+    /**
+     * Check if a key exists in the session state
+     * @param key - The key to check
+     * @returns True if the key exists
+     */
+    has(key: string): boolean;
+    /**
+     * Get the number of items in the session state
+     * @returns The number of items
+     */
+    size(): number;
+}
+/**
+ * Create a new session state instance
+ *
+ * Session state is purely in-memory and resets when the page is refreshed.
+ * This is intentional - demo sessions should start fresh each time.
+ *
+ * @returns A new SessionState instance
+ *
+ * @example
+ * ```typescript
+ * const session = createSessionState()
+ *
+ * session.set('cart', [{ id: '1', quantity: 2 }])
+ * const cart = session.get<CartItem[]>('cart')
+ *
+ * session.clear() // Reset all state
+ * ```
+ */
+declare function createSessionState(): SessionState;
+
+/**
+ * Configuration for creating a demo interceptor
+ */
+interface DemoKitConfig {
+    /**
+     * Map of URL patterns to fixture handlers
+     * Patterns support :param syntax for URL parameters and * for wildcards
+     * @example
+     * {
+     *   'GET /api/users': () => [{ id: '1', name: 'Demo User' }],
+     *   'GET /api/users/:id': ({ params }) => ({ id: params.id, name: 'Demo User' }),
+     *   'POST /api/users': ({ body }) => ({ id: 'new', ...body }),
+     * }
+     */
+    fixtures: FixtureMap;
+    /**
+     * localStorage key for persisting demo mode state
+     * @default 'demokit-mode'
+     */
+    storageKey?: string;
+    /**
+     * Callback invoked when demo mode is enabled
+     */
+    onEnable?: () => void;
+    /**
+     * Callback invoked when demo mode is disabled
+     */
+    onDisable?: () => void;
+    /**
+     * Whether to start with demo mode enabled
+     * If not provided, will read from localStorage
+     * @default false
+     */
+    initialEnabled?: boolean;
+    /**
+     * Base URL to use for relative URL parsing
+     * @default 'http://localhost'
+     */
+    baseUrl?: string;
+}
+/**
+ * Map of URL patterns to fixture handlers
+ * Pattern format: "METHOD /path/:param"
+ */
+type FixtureMap = Record<string, FixtureHandler>;
+/**
+ * A fixture handler can be:
+ * - A static value (object, array, primitive)
+ * - A function that receives request context and returns a value
+ * - An async function for dynamic fixtures
+ */
+type FixtureHandler = unknown | ((context: RequestContext) => unknown) | ((context: RequestContext) => Promise<unknown>);
+/**
+ * Context provided to fixture handler functions
+ */
+interface RequestContext {
+    /**
+     * The full URL of the request
+     */
+    url: string;
+    /**
+     * HTTP method (GET, POST, PUT, PATCH, DELETE, etc.)
+     */
+    method: string;
+    /**
+     * URL parameters extracted from the pattern
+     * @example For pattern 'GET /api/users/:id' and URL '/api/users/123',
+     * params would be { id: '123' }
+     */
+    params: Record<string, string>;
+    /**
+     * Query string parameters
+     */
+    searchParams: URLSearchParams;
+    /**
+     * Parsed request body (for POST, PUT, PATCH requests)
+     */
+    body?: unknown;
+    /**
+     * Request headers
+     */
+    headers: Headers;
+    /**
+     * Session state for storing mutable data across requests
+     * Resets when the page is refreshed
+     *
+     * @example
+     * ```typescript
+     * // Store data in a POST handler
+     * 'POST /api/users': ({ body, session }) => {
+     *   const users = session.get<User[]>('users') || []
+     *   const newUser = { id: crypto.randomUUID(), ...body }
+     *   session.set('users', [...users, newUser])
+     *   return newUser
+     * }
+     *
+     * // Retrieve data in a GET handler
+     * 'GET /api/users': ({ session }) => {
+     *   return session.get<User[]>('users') || []
+     * }
+     * ```
+     */
+    session: SessionState;
+}
+/**
+ * The demo interceptor instance returned by createDemoInterceptor
+ */
+interface DemoInterceptor {
+    /**
+     * Enable demo mode - all matching fetches will return fixture data
+     */
+    enable(): void;
+    /**
+     * Disable demo mode - fetches will pass through to the real API
+     */
+    disable(): void;
+    /**
+     * Check if demo mode is currently enabled
+     */
+    isEnabled(): boolean;
+    /**
+     * Toggle demo mode state and return the new state
+     */
+    toggle(): boolean;
+    /**
+     * Replace all fixtures with a new fixture map
+     */
+    setFixtures(fixtures: FixtureMap): void;
+    /**
+     * Add or update a single fixture pattern
+     */
+    addFixture(pattern: string, handler: FixtureHandler): void;
+    /**
+     * Remove a fixture pattern
+     */
+    removeFixture(pattern: string): void;
+    /**
+     * Reset the session state, clearing all stored data
+     * Call this to manually reset the demo session without page refresh
+     */
+    resetSession(): void;
+    /**
+     * Get the current session state instance
+     * Useful for inspecting or manipulating session state directly
+     */
+    getSession(): SessionState;
+    /**
+     * Clean up the interceptor - restores original fetch
+     * Call this when unmounting or cleaning up
+     */
+    destroy(): void;
+}
+/**
+ * Result of URL pattern matching
+ */
+interface MatchResult {
+    /**
+     * Whether the pattern matched the URL
+     */
+    matched: boolean;
+    /**
+     * Extracted URL parameters
+     */
+    params: Record<string, string>;
+}
+/**
+ * Parsed URL pattern
+ */
+interface ParsedPattern {
+    /**
+     * HTTP method from the pattern
+     */
+    method: string;
+    /**
+     * Regex to match the path
+     */
+    pathPattern: RegExp;
+    /**
+     * Names of parameters in order of appearance
+     */
+    paramNames: string[];
+}
+
+/**
+ * Create a demo interceptor that patches fetch to return mock data
+ *
+ * @param config - Configuration including fixtures and options
+ * @returns Demo interceptor instance with enable/disable controls
+ *
+ * @example
+ * const demo = createDemoInterceptor({
+ *   fixtures: {
+ *     'GET /api/users': () => [{ id: '1', name: 'Demo User' }],
+ *     'GET /api/users/:id': ({ params }) => ({ id: params.id, name: 'Demo User' }),
+ *     'POST /api/users': ({ body }) => ({ id: 'new', ...body }),
+ *   }
+ * })
+ *
+ * demo.enable()   // All matching fetches return mock data
+ * demo.disable()  // Back to real API
+ */
+declare function createDemoInterceptor(config: DemoKitConfig): DemoInterceptor;
+
+/**
+ * Parse a URL pattern into its components
+ *
+ * @param pattern - Pattern in format "METHOD /path/:param"
+ * @returns Parsed pattern with method, regex, and param names
+ *
+ * @example
+ * parseUrlPattern('GET /api/users/:id')
+ * // { method: 'GET', pathPattern: /^\/api\/users\/([^/]+)$/, paramNames: ['id'] }
+ *
+ * parseUrlPattern('GET /api/projects/*')
+ * // { method: 'GET', pathPattern: /^\/api\/projects\/.*$/, paramNames: [] }
+ */
+declare function parseUrlPattern(pattern: string): ParsedPattern;
+/**
+ * Match a request against a fixture pattern
+ *
+ * @param pattern - Fixture pattern (e.g., "GET /api/users/:id")
+ * @param method - HTTP method of the request
+ * @param pathname - URL pathname of the request
+ * @returns Match result with extracted params, or null if no match
+ *
+ * @example
+ * matchUrl('GET /api/users/:id', 'GET', '/api/users/123')
+ * // { matched: true, params: { id: '123' } }
+ *
+ * matchUrl('GET /api/users/:id', 'POST', '/api/users/123')
+ * // null (method doesn't match)
+ *
+ * matchUrl('GET /api/users/:id', 'GET', '/api/projects/123')
+ * // null (path doesn't match)
+ */
+declare function matchUrl(pattern: string, method: string, pathname: string): MatchResult | null;
+/**
+ * Find the first matching pattern from a fixture map
+ *
+ * @param fixtures - Map of patterns to fixtures
+ * @param method - HTTP method of the request
+ * @param pathname - URL pathname of the request
+ * @returns Tuple of [pattern, match result] or null if no match
+ */
+declare function findMatchingPattern(fixtures: Record<string, unknown>, method: string, pathname: string): [string, MatchResult] | null;
+/**
+ * Clear the pattern cache (useful for testing)
+ */
+declare function clearPatternCache(): void;
+/**
+ * A query key element can be a string, number, or object
+ */
+type QueryKeyElement = string | number | boolean | null | undefined | Record<string, unknown>;
+/**
+ * A query key is an array of elements (like TanStack Query uses)
+ */
+type QueryKey = readonly QueryKeyElement[];
+/**
+ * Result of query key matching
+ */
+interface QueryKeyMatchResult {
+    /**
+     * Whether the pattern matched the query key
+     */
+    matched: boolean;
+    /**
+     * Extracted parameters from :param placeholders
+     */
+    params: Record<string, unknown>;
+}
+/**
+ * Match a query key against a pattern
+ *
+ * Supports:
+ * - Exact string/number matching: ['users'] matches ['users']
+ * - Parameter extraction with :param syntax: ['users', ':id'] matches ['users', '123']
+ * - Object matching with params: ['users', { id: ':id' }] matches ['users', { id: '123' }]
+ * - Wildcard matching with '*': ['users', '*'] matches ['users', 'anything']
+ *
+ * @param queryKey - The actual query key to match
+ * @param pattern - The pattern to match against
+ * @returns Match result with extracted params, or null if no match
+ *
+ * @example
+ * // Exact match
+ * matchQueryKey(['users'], ['users'])
+ * // { matched: true, params: {} }
+ *
+ * // Parameter extraction from string
+ * matchQueryKey(['users', '123'], ['users', ':id'])
+ * // { matched: true, params: { id: '123' } }
+ *
+ * // Parameter extraction from object
+ * matchQueryKey(['users', { id: '123', status: 'active' }], ['users', { id: ':userId' }])
+ * // { matched: true, params: { userId: '123' } }
+ *
+ * // Wildcard matching
+ * matchQueryKey(['users', 'anything'], ['users', '*'])
+ * // { matched: true, params: {} }
+ *
+ * // No match - different length
+ * matchQueryKey(['users'], ['users', 'list'])
+ * // null
+ */
+declare function matchQueryKey(queryKey: QueryKey, pattern: QueryKey): QueryKeyMatchResult | null;
+/**
+ * Find the first matching pattern from a map of query key patterns
+ *
+ * @param patterns - Map of serialized patterns to values
+ * @param queryKey - The query key to match
+ * @returns Tuple of [pattern, value, match result] or null if no match
+ *
+ * @example
+ * const patterns = {
+ *   'users': { data: [] },
+ *   'users/:id': (params) => ({ id: params.id }),
+ * }
+ * findMatchingQueryKeyPattern(patterns, ['users', '123'])
+ * // [['users', ':id'], { params: { id: '123' } }]
+ */
+declare function findMatchingQueryKeyPattern<T>(patterns: Map<QueryKey, T>, queryKey: QueryKey): [QueryKey, T, QueryKeyMatchResult] | null;
+
+/**
+ * Shared demo state interface that can be used across frameworks
+ * This provides a consistent API for managing demo mode state
+ */
+interface DemoState {
+    /**
+     * Whether demo mode is currently enabled
+     */
+    enabled: boolean;
+    /**
+     * The currently active scenario name, if any
+     * Scenarios allow grouping fixtures for different demo flows
+     */
+    scenario: string | null;
+    /**
+     * The active fixture map for the current scenario
+     */
+    fixtures: FixtureMap;
+    /**
+     * Timestamp when demo mode was last enabled
+     * Useful for session timeout logic
+     */
+    enabledAt: number | null;
+}
+/**
+ * Create initial demo state
+ *
+ * @param initialEnabled - Whether demo mode should start enabled
+ * @param fixtures - Initial fixture map
+ * @returns A new DemoState object
+ *
+ * @example
+ * const state = createDemoState(false, {
+ *   'GET /api/users': () => [{ id: '1', name: 'Demo User' }],
+ * })
+ */
+declare function createDemoState(initialEnabled?: boolean, fixtures?: FixtureMap): DemoState;
+/**
+ * Options for creating a demo state store
+ */
+interface DemoStateStoreOptions {
+    /**
+     * Initial enabled state
+     * @default false
+     */
+    initialEnabled?: boolean;
+    /**
+     * Initial fixtures
+     * @default {}
+     */
+    fixtures?: FixtureMap;
+    /**
+     * Available scenarios with their fixtures
+     */
+    scenarios?: Record<string, FixtureMap>;
+    /**
+     * Callback when state changes
+     */
+    onChange?: (state: DemoState) => void;
+}
+/**
+ * A minimal state store for demo mode
+ * Framework adapters can use this or integrate with their own state management
+ */
+interface DemoStateStore {
+    /**
+     * Get the current state
+     */
+    getState(): DemoState;
+    /**
+     * Enable demo mode
+     */
+    enable(): void;
+    /**
+     * Disable demo mode
+     */
+    disable(): void;
+    /**
+     * Toggle demo mode
+     */
+    toggle(): boolean;
+    /**
+     * Set the active scenario
+     * @param name - Scenario name (or null to clear)
+     */
+    setScenario(name: string | null): void;
+    /**
+     * Update fixtures (merges with existing)
+     */
+    updateFixtures(fixtures: FixtureMap): void;
+    /**
+     * Replace all fixtures
+     */
+    setFixtures(fixtures: FixtureMap): void;
+    /**
+     * Subscribe to state changes
+     * @returns Unsubscribe function
+     */
+    subscribe(listener: (state: DemoState) => void): () => void;
+}
+/**
+ * Create a demo state store
+ *
+ * This is a minimal, framework-agnostic state store that can be used
+ * directly or wrapped by framework-specific adapters (React, Vue, etc.)
+ *
+ * @param options - Store configuration options
+ * @returns A DemoStateStore instance
+ *
+ * @example
+ * const store = createDemoStateStore({
+ *   initialEnabled: false,
+ *   fixtures: {
+ *     'GET /api/users': () => [{ id: '1', name: 'Demo User' }],
+ *   },
+ *   scenarios: {
+ *     'empty-state': { 'GET /api/users': () => [] },
+ *     'error-state': { 'GET /api/users': () => { throw new Error('API Error') } },
+ *   },
+ * })
+ *
+ * // Subscribe to changes
+ * const unsubscribe = store.subscribe((state) => {
+ *   console.log('Demo mode:', state.enabled)
+ * })
+ *
+ * // Enable demo mode
+ * store.enable()
+ *
+ * // Switch scenario
+ * store.setScenario('empty-state')
+ */
+declare function createDemoStateStore(options?: DemoStateStoreOptions): DemoStateStore;
+
+/**
+ * Default localStorage key for demo mode state
+ */
+declare const DEFAULT_STORAGE_KEY = "demokit-mode";
+/**
+ * Load demo mode state from localStorage
+ *
+ * @param key - localStorage key to use
+ * @returns Current demo mode state, or false if not set or unavailable
+ */
+declare function loadDemoState(key?: string): boolean;
+/**
+ * Save demo mode state to localStorage
+ *
+ * @param key - localStorage key to use
+ * @param enabled - Whether demo mode is enabled
+ */
+declare function saveDemoState(key: string | undefined, enabled: boolean): void;
+/**
+ * Clear demo mode state from localStorage
+ *
+ * @param key - localStorage key to use
+ */
+declare function clearDemoState(key?: string): void;
+
+export { DEFAULT_STORAGE_KEY, type DemoInterceptor, type DemoKitConfig, type DemoState, type DemoStateStore, type DemoStateStoreOptions, type FixtureHandler, type FixtureMap, type MatchResult, type ParsedPattern, type QueryKey, type QueryKeyElement, type QueryKeyMatchResult, type RequestContext, type SessionState, clearDemoState, clearPatternCache, createDemoInterceptor, createDemoState, createDemoStateStore, createSessionState, findMatchingPattern, findMatchingQueryKeyPattern, loadDemoState, matchQueryKey, matchUrl, parseUrlPattern, saveDemoState };