promidas 2.0.0

package/dist/repository/protopedia-in-memory-repository.js

@@ -0,0 +1,929 @@
+/**
+ * In-memory repository implementation for ProtoPedia prototypes.
+ *
+ * This module contains the concrete implementation of the repository pattern
+ * for managing ProtoPedia prototype data in memory with snapshot-based access.
+ *
+ * ## Architecture
+ *
+ * The {@link ProtopediaInMemoryRepositoryImpl} class orchestrates:
+ *
+ * - **API Client**: ProtoPedia API v2 client for fetching prototype data
+ * - **Memory Store**: {@link PrototypeInMemoryStore} for snapshot management
+ * - **Repository Interface**: {@link ProtopediaInMemoryRepository} for high-level operations
+ *
+ * ## Design Patterns
+ *
+ * ### Repository Pattern
+ * Abstracts data access behind a clean interface, isolating business logic
+ * from data fetching and storage mechanisms.
+ *
+ * ### Snapshot Isolation
+ * All read operations work against an immutable in-memory snapshot.
+ * Network I/O only occurs during explicit setup/refresh operations.
+ *
+ * ### Private Fields
+ * Uses ECMAScript private fields (#) for proper encapsulation:
+ * - `#store` - Internal memory store instance
+ * - `#apiClient` - HTTP client for ProtoPedia API
+ * - `#lastFetchParams` - Cache of last fetch parameters
+ *
+ * ## Performance Optimizations
+ *
+ * 1. **O(1) Lookups**: Direct Map access by prototype ID
+ * 2. **Hybrid Sampling**: Adaptive algorithm based on sample size ratio
+ *    - Small samples (< 50%): Set-based random selection
+ *    - Large samples (≥ 50%): Fisher-Yates shuffle
+ * 3. **Efficient Checks**: Use `store.size` instead of array operations
+ * 4. **Parameter Validation**: Zod schemas for runtime type safety
+ *
+ * ## Usage Recommendation
+ *
+ * For normal usage, import from `promidas` instead of direct instantiation:
+ * - `createPromidasForLocal()` for local development
+ * - `createPromidasForServer()` for server environments
+ * - `PromidasRepositoryBuilder` for advanced customization
+ *
+ * Direct instantiation is only recommended for:
+ * - Testing scenarios
+ * - Advanced customization needs
+ * - Framework integration
+ *
+ * @module
+ * @see {@link ProtopediaInMemoryRepository} for the public interface
+ */
+import { EventEmitter } from 'events';
+import { ProtopediaApiCustomClient } from '../fetcher/index.js';
+import { ConsoleLogger } from '../logger/index.js';
+import { DataSizeExceededError, PrototypeInMemoryStore, SizeEstimationError, } from '../store/index.js';
+import { sanitizeDataForLogging } from '../utils/index.js';
+import { ValidationError } from './errors/validation-error.js';
+import { emitRepositoryEventSafely } from './utils/emit-repository-event-safely.js';
+import { convertFetchResult, convertStoreResult } from './utils/index.js';
+import { RepositoryParamsValidator, validateSerializableSnapshot, } from './validation/index.js';
+const DEFAULT_FETCH_PARAMS = {
+    offset: 0,
+    limit: 10,
+};
+/**
+ * Version identifier for snapshot serialization format.
+ * Increment when making incompatible changes to SerializableSnapshot schema.
+ */
+const SNAPSHOT_SERIALIZATION_VERSION = '1.0.0';
+/**
+ * Threshold ratio for choosing sampling strategy in getRandomSampleFromSnapshot.
+ *
+ * When requested sample size exceeds this ratio of total items,
+ * use "Fisher-Yates shuffle" instead of "Set-based random selection" for better performance.
+ *
+ * @example
+ * // With 100 items total:
+ * // - size=40 (40%) → Set-based random selection (O(size))
+ * // - size=60 (60%) → Fisher-Yates shuffle (O(n))
+ */
+const SAMPLE_SIZE_THRESHOLD_RATIO = 0.5;
+/**
+ * Implementation class for the ProtoPedia in-memory repository.
+ *
+ * This class provides the concrete implementation of {@link ProtopediaInMemoryRepository}
+ * with full encapsulation using ECMAScript private fields.
+ *
+ * ## Responsibilities
+ *
+ * 1. **Dependency Management**
+ *    - Receives {@link PrototypeInMemoryStore} and {@link ProtopediaApiCustomClient} via DI
+ *    - Maintains internal state for fetch parameters
+ *
+ * 2. **Snapshot Operations**
+ *    - {@link setupSnapshot} - Initial data fetch and population
+ *    - {@link refreshSnapshot} - Update snapshot with fresh API data
+ *
+ * 3. **Data Access**
+ *    - {@link getAllFromSnapshot} - Retrieve all prototypes
+ *    - {@link getPrototypeFromSnapshotByPrototypeId} - Fast ID lookup
+ *    - {@link getRandomPrototypeFromSnapshot} - Single random sample
+ *    - {@link getRandomSampleFromSnapshot} - Multiple random samples
+ *    - {@link getPrototypeIdsFromSnapshot} - Get all IDs efficiently
+ *
+ * 4. **Analysis & Metadata**
+ *    - {@link analyzePrototypes} - Statistical analysis (min/max)
+ *    - {@link getStats} - Snapshot statistics and TTL info
+ *    - {@link getConfig} - Store configuration details
+ *
+ * ## Implementation Details
+ *
+ * ### Validation
+ * All public methods validate their parameters using {@link RepositoryParamsValidator}:
+ * - {@link RepositoryParamsValidator.validatePrototypeId} - Ensures valid prototype IDs
+ * - {@link RepositoryParamsValidator.validateSampleSize} - Ensures valid sample sizes
+ *
+ * ### Error Handling
+ * Network operations return {@link SnapshotOperationResult}:
+ * - `{ ok: true, ... }` - Success with metadata
+ * - `{ ok: false, error: string }` - Failure with error message
+ *
+ * ### Performance
+ * - Uses `store.size` for O(1) empty checks
+ * - Implements hybrid sampling algorithm (see {@link SAMPLE_SIZE_THRESHOLD_RATIO})
+ * - Returns read-only data to prevent accidental mutations
+ *
+ * ## Usage
+ *
+ * **Recommended**: Import from `promidas` instead of direct instantiation
+ *
+ * **Direct instantiation** (advanced):
+ * ```typescript
+ * // Dependencies must be created manually
+ * const store = new PrototypeInMemoryStore({ ... });
+ * const client = new ProtopediaApiCustomClient({ ... });
+ *
+ * const repo = new ProtopediaInMemoryRepositoryImpl({
+ *   store,
+ *   apiClient: client
+ * });
+ * ```
+ *
+ * @see {@link ProtopediaInMemoryRepository} for the public interface contract
+ */
+export class ProtopediaInMemoryRepositoryImpl {
+    /**
+     * Event emitter for snapshot operation notifications.
+     *
+     * Only defined when enableEvents: true is set in repository configuration.
+     */
+    events;
+    /**
+     * Internal logger instance.
+     */
+    #logger;
+    /**
+     * Log level for the repository.
+     */
+    #logLevel;
+    /**
+     * Underlying in-memory store instance.
+     */
+    #store;
+    /**
+     * Underlying API client instance.
+     */
+    #apiClient;
+    /**
+     * Cache of the last successful fetch parameters.
+     *
+     * - `undefined`: No API fetch has been performed, or reset after loading serialized data
+     * - `ListPrototypesParams`: Parameters from the last successful setupSnapshot() call
+     */
+    #lastFetchParams = undefined;
+    /**
+     * Ongoing fetch promise for concurrency control.
+     */
+    #ongoingFetch = null;
+    /**
+     * Creates a new ProtoPedia in-memory repository instance.
+     *
+     * @param dependencies - Dependency injection object
+     * @param dependencies.store - Pre-configured in-memory store instance
+     * @param dependencies.apiClient - Pre-configured API client instance
+     * @param dependencies.repositoryConfig - Repository-level configuration (optional)
+     */
+    constructor({ store, apiClient, repositoryConfig = {}, }) {
+        // Fastify-style logger configuration for repository
+        const { logger, logLevel, enableEvents } = repositoryConfig;
+        if (logger) {
+            this.#logger = logger;
+            this.#logLevel = logLevel ?? 'info';
+            // If logLevel is specified, update logger's level property (if mutable)
+            if (logLevel !== undefined && 'level' in logger) {
+                logger.level = logLevel;
+            }
+        }
+        else {
+            const resolvedLogLevel = logLevel ?? 'info';
+            this.#logger = new ConsoleLogger(resolvedLogLevel);
+            this.#logLevel = resolvedLogLevel;
+        }
+        // Initialize event emitter if events are enabled
+        if (enableEvents === true) {
+            this.events = new EventEmitter();
+            this.events.setMaxListeners(0); // Allow unlimited listeners
+        }
+        this.#logger.info('ProtopediaInMemoryRepository constructor called', {
+            repositoryConfig: sanitizeDataForLogging(repositoryConfig),
+            storeConfig: store.getConfig(),
+            eventsEnabled: enableEvents === true,
+        });
+        this.#store = store;
+        this.#apiClient = apiClient;
+    }
+    /**
+     * Fetch and normalize prototypes from the ProtoPedia API.
+     *
+     * @param params - Fetch parameters to merge with {@link DEFAULT_FETCH_PARAMS}
+     * @returns {@link FetchPrototypesResult} from the API client
+     *
+     * @remarks
+     * This method delegates directly to the API client's `fetchPrototypes()` method,
+     * which handles all error cases and returns them as {@link FetchPrototypesFailure}
+     * instead of throwing exceptions.
+     *
+     * **Responsibility Separation**:
+     * - This method only fetches and normalizes data
+     * - The caller is responsible for storing the data via {@link storeSnapshot}
+     * - The caller must update lastFetchParams on successful storage
+     *
+     * **Error Handling**:
+     * - The API client never throws exceptions under normal operation
+     * - The try-catch block is defensive programming for unexpected cases
+     * - All expected errors are returned as part of {@link FetchPrototypesResult}
+     *
+     * **Logging**:
+     * - Success: `debug` level with fetch count and parameters
+     * - Failure: No logging (API client layer already logs failures)
+     * - Unexpected exceptions: `error` level (defensive fallback)
+     *
+     * @see {@link ProtopediaApiCustomClient.fetchPrototypes} for API client implementation
+     * @internal
+     */
+    async fetchAndNormalize(params) {
+        const mergedParams = {
+            ...DEFAULT_FETCH_PARAMS,
+            ...params,
+        };
+        try {
+            const result = await this.#apiClient.fetchPrototypes(mergedParams);
+            // Log success for diagnostics
+            if (result.ok) {
+                this.#logger.debug('Fetch operation completed', {
+                    count: result.data.length,
+                    params: mergedParams,
+                });
+            }
+            return result;
+        }
+        catch (error) {
+            // This should never happen as the API client catches all errors,
+            // but we handle it defensively in case of unexpected exceptions.
+            this.#logger.error('Unexpected exception from API client', {
+                error: sanitizeDataForLogging(error),
+                params: mergedParams,
+            });
+            return {
+                ok: false,
+                origin: 'fetcher',
+                kind: 'unknown',
+                code: 'UNKNOWN',
+                error: error instanceof Error ? error.message : String(error),
+                details: {
+                    req: {
+                        method: 'GET',
+                    },
+                },
+            };
+        }
+    }
+    /**
+     * Store normalized prototypes in the in-memory snapshot.
+     *
+     * This private method handles:
+     * - Storing data via the memory store
+     * - Converting store errors to {@link SetFailure}
+     * - Logging detailed operation information with sanitized data
+     *
+     * @param data - Array of normalized prototypes to store
+     * @returns {@link SetResult} - Success with stats or failure details
+     *
+     * @remarks
+     * **Error Handling**:
+     * - {@link DataSizeExceededError} → {@link SetFailure} with kind='storage_limit'
+     * - {@link SizeEstimationError} → {@link SetFailure} with kind='serialization'
+     * - Unexpected errors → {@link SetFailure} with kind='unknown'
+     *
+     * All store errors include `dataState` to indicate whether existing data was preserved.
+     *
+     * **Logging**:
+     * - Success: `debug` level with store size and data size
+     * - DataSizeExceededError: `warn` level (configuration issue)
+     * - SizeEstimationError: `error` level (serialization failure)
+     * - Unexpected errors: `error` level (unknown failures)
+     *
+     * @internal
+     */
+    storeSnapshot(data) {
+        try {
+            this.#store.setAll(data);
+            const stats = this.#store.getStats();
+            this.#logger.debug('Store operation completed', {
+                size: stats.size,
+                dataSizeBytes: stats.dataSizeBytes,
+            });
+            return {
+                ok: true,
+                stats,
+            };
+        }
+        catch (error) {
+            // Log detailed Store error information
+            if (error instanceof DataSizeExceededError) {
+                this.#logger.warn('Snapshot storage failed: data size exceeded', {
+                    dataSizeBytes: error.dataSizeBytes,
+                    maxDataSizeBytes: error.maxDataSizeBytes,
+                    dataState: error.dataState,
+                });
+                return {
+                    ok: false,
+                    origin: 'store',
+                    kind: 'storage_limit',
+                    code: 'STORE_CAPACITY_EXCEEDED',
+                    message: `Data size ${error.dataSizeBytes} bytes exceeds maximum ${error.maxDataSizeBytes} bytes`,
+                    dataState: error.dataState,
+                };
+            }
+            else if (error instanceof SizeEstimationError) {
+                this.#logger.error('Snapshot storage failed: size estimation error', {
+                    dataState: error.dataState,
+                    cause: sanitizeDataForLogging(error.cause),
+                });
+                return {
+                    ok: false,
+                    origin: 'store',
+                    kind: 'serialization',
+                    code: 'STORE_SERIALIZATION_FAILED',
+                    message: 'Failed to estimate data size during serialization',
+                    dataState: error.dataState,
+                    cause: sanitizeDataForLogging(error.cause),
+                };
+            }
+            else {
+                // Unexpected store error - map to unknown store error
+                this.#logger.error('Snapshot storage failed: unexpected error', {
+                    error: sanitizeDataForLogging(error),
+                });
+                return {
+                    ok: false,
+                    origin: 'store',
+                    kind: 'unknown',
+                    code: 'STORE_UNKNOWN',
+                    message: error instanceof Error ? error.message : String(error),
+                    dataState: 'UNKNOWN',
+                    cause: sanitizeDataForLogging(error),
+                };
+            }
+        }
+    }
+    /**
+     * Return the configuration used to initialize the underlying store.
+     */
+    getConfig() {
+        return this.#store.getConfig();
+    }
+    /**
+     * Return stats for the current snapshot from the underlying store.
+     */
+    getStats() {
+        return this.#store.getStats();
+    }
+    /**
+     * Fetch prototypes from the API and store them in memory.
+     *
+     * This is the core implementation shared by {@link setupSnapshot} and {@link refreshSnapshot}.
+     * It encapsulates the complete fetch-and-store workflow with proper error handling and
+     * optional parameter caching.
+     *
+     * @param params - Fetch parameters to merge with {@link DEFAULT_FETCH_PARAMS}
+     * @param updateLastFetchParams - Whether to update {@link #lastFetchParams} on successful storage.
+     *   Set to `true` for {@link setupSnapshot} to cache parameters for future {@link refreshSnapshot} calls.
+     *   Set to `false` for {@link refreshSnapshot} to avoid overwriting cached parameters.
+     * @returns {@link SnapshotOperationResult} indicating success or failure
+     *
+     * @remarks
+     * **Operation Flow**:
+     * 1. Fetch and normalize prototypes via {@link fetchAndNormalize}
+     * 2. Convert fetch result (both success and failure) via {@link convertFetchResult}
+     * 3. Return early if fetch failed
+     * 4. Store the fetched data in memory via {@link storeSnapshot}
+     * 5. Convert store result via {@link convertStoreResult}
+     * 6. Update {@link #lastFetchParams} only if `updateLastFetchParams` is `true` AND storage succeeds
+     *
+     * **Parameter Handling**:
+     * - Input `params` are merged with {@link DEFAULT_FETCH_PARAMS} by {@link fetchAndNormalize}
+     * - Merged parameters are cached in {@link #lastFetchParams} only when:
+     *   - `updateLastFetchParams` is `true` (typically {@link setupSnapshot})
+     *   - Storage operation succeeds
+     * - Failed operations never update {@link #lastFetchParams}
+     *
+     * **Concurrency Control**:
+     * - Uses {@link #executeWithCoalescing} to prevent concurrent API calls
+     * - Multiple concurrent calls are coalesced into a single API request
+     * - All callers receive the same result
+     * - The first caller's operation (fetch + store) is executed
+     * - Subsequent concurrent callers wait for the same result
+     * - This is necessary because async operations can run concurrently (await allows other calls to start)
+     *
+     * **Error Handling**:
+     * - Returns error result if API fetch fails (network, timeout, API errors)
+     * - Returns error result if storage fails (e.g., {@link DataSizeExceededError})
+     * - Previous snapshot remains intact on failure
+     * - Never throws exceptions - all errors are returned as {@link SnapshotOperationResult}
+     *
+     * @internal This method is private and used only by {@link setupSnapshot} and {@link refreshSnapshot}.
+     * It can be accessed in tests via `(repo as any).fetchAndStore(...)` for unit testing.
+     *
+     * @see {@link setupSnapshot} for initial snapshot setup with parameter caching
+     * @see {@link refreshSnapshot} for refreshing with cached parameters
+     */
+    async fetchAndStore(params, updateLastFetchParams) {
+        return this.#executeWithCoalescing(async () => {
+            // Fetch and normalize prototypes
+            const fetchResult = await this.fetchAndNormalize(params);
+            // Convert fetch result (handles both success and failure)
+            const convertedFetchResult = convertFetchResult(fetchResult);
+            // Return early on fetch failure
+            if (!convertedFetchResult.ok) {
+                return convertedFetchResult;
+            }
+            // Type guard: convertedFetchResult is FetchPrototypesSuccess here
+            /* istanbul ignore next */
+            if (!('data' in convertedFetchResult)) {
+                // This should never happen, but TypeScript needs the check
+                throw new Error('Unexpected: success result missing data field');
+            }
+            // Store the fetched data
+            const storeResult = this.storeSnapshot(convertedFetchResult.data);
+            // Return early on store failure, converting to SnapshotOperationFailure
+            if (!storeResult.ok) {
+                return convertStoreResult(storeResult);
+            }
+            // Update lastFetchParams only on successful storage if requested
+            if (updateLastFetchParams) {
+                this.#lastFetchParams = { ...DEFAULT_FETCH_PARAMS, ...params };
+            }
+            return convertStoreResult(storeResult);
+        });
+    }
+    /**
+     * Initialize the in-memory snapshot using the provided fetch parameters.
+     *
+     * Typically called once at startup. Fetches data from the API, stores it in memory,
+     * and caches the parameters for future {@link refreshSnapshot} calls.
+     *
+     * @param params - Fetch parameters to merge with {@link DEFAULT_FETCH_PARAMS}
+     * @returns {@link SnapshotOperationResult} indicating success or failure
+     *
+     * @remarks
+     * Delegates to {@link fetchAndStore} with `updateLastFetchParams: true`.
+     * Emits `snapshotStarted('setup')` event before operation (if events enabled).
+     *
+     * See {@link fetchAndStore} for operation flow, concurrency control, and error handling details.
+     *
+     * @see {@link fetchAndStore}
+     * @see {@link refreshSnapshot}
+     */
+    async setupSnapshot(params) {
+        emitRepositoryEventSafely(this.events, this.#logger, 'snapshotStarted', 'setup');
+        return this.fetchAndStore(params, true);
+    }
+    /**
+     * Refresh the in-memory snapshot using cached fetch parameters.
+     *
+     * Typically called periodically to refresh expired data. Uses parameters
+     * cached by the last successful {@link setupSnapshot} call.
+     *
+     * **Prerequisite**: {@link setupSnapshot} must have been called successfully at least once.
+     * If called before {@link setupSnapshot}, returns an error with code `REPOSITORY_INVALID_STATE`.
+     *
+     * @returns Promise resolving to {@link SnapshotOperationResult}:
+     * - **Success** (`ok: true`): Contains {@link PrototypeInMemoryStats} with snapshot metadata
+     * - **Failure** (`ok: false`): One of:
+     *   - {@link RepositorySnapshotFailure} - Invalid state (setupSnapshot not called)
+     *   - {@link FetcherSnapshotFailure} - Network/HTTP errors from API
+     *   - {@link StoreSnapshotFailure} - Storage errors (size limits, serialization)
+     *   - {@link UnknownSnapshotFailure} - Unexpected errors
+     *
+     * @remarks
+     * **Operation Flow**:
+     * 1. Validate that {@link setupSnapshot} has been called (check `#lastFetchParams`)
+     * 2. Return error immediately if validation fails (before coalescing)
+     * 3. Emit `snapshotStarted('refresh')` event (if events enabled)
+     * 4. Delegate to {@link fetchAndStore} with `updateLastFetchParams: false`
+     * 5. Preserve existing snapshot on failure (atomic operation)
+     *
+     * **Concurrency Control**:
+     * - Multiple concurrent calls are coalesced into a single API request
+     * - All callers receive the same result
+     * - Validation check executes before coalescing, ensuring deterministic failure
+     *
+     * **Error Handling**:
+     * - Never throws exceptions
+     * - All errors returned as Result type with `ok: false`
+     * - Use `result.origin` to discriminate error types
+     *
+     * @example
+     * ```typescript
+     * // Typical usage: periodic refresh
+     * const result = await repo.refreshSnapshot();
+     * if (result.ok) {
+     *   console.log(`Refreshed ${result.stats.size} prototypes`);
+     * } else {
+     *   console.error(`Refresh failed: ${result.message}`);
+     * }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Error handling by origin
+     * const result = await repo.refreshSnapshot();
+     * if (!result.ok) {
+     *   if (result.origin === 'repository') {
+     *     console.error('Call setupSnapshot first');
+     *   } else if (result.origin === 'fetcher') {
+     *     console.error(`HTTP ${result.status}: ${result.message}`);
+     *   }
+     * }
+     * ```
+     *
+     * @see {@link fetchAndStore} - Core implementation
+     * @see {@link setupSnapshot} - Initial snapshot setup
+     * @see {@link SnapshotOperationResult} - Return type details
+     */
+    async refreshSnapshot() {
+        // Check lastFetchParams before coalescing to ensure refresh is not called
+        // before setupSnapshot has established parameters, even during concurrent calls
+        if (this.#lastFetchParams === undefined) {
+            const error = {
+                ok: false,
+                origin: 'repository',
+                kind: 'invalid_state',
+                code: 'REPOSITORY_INVALID_STATE',
+                message: 'Cannot refresh snapshot: No previous API fetch parameters available. ' +
+                    'Call setupSnapshot() first to establish fetch parameters.',
+            };
+            emitRepositoryEventSafely(this.events, this.#logger, 'snapshotFailed', error);
+            return error;
+        }
+        // Capture lastFetchParams before entering fetchAndStore to prevent race conditions
+        // where setupSnapshot might update it during concurrent execution
+        const paramsToUse = this.#lastFetchParams;
+        emitRepositoryEventSafely(this.events, this.#logger, 'snapshotStarted', 'refresh');
+        return this.fetchAndStore(paramsToUse, false);
+    }
+    /**
+     * Load and validate snapshot data, then store it in memory.
+     *
+     * This is the core implementation for {@link setupSnapshotFromSerializedData}.
+     * It encapsulates the complete validation-and-store workflow with proper error handling.
+     *
+     * @param data - Serializable snapshot object to validate and store
+     * @returns {@link SnapshotOperationResult} indicating success or failure
+     *
+     * @remarks
+     * **Operation Flow**:
+     * 1. Validate data structure via {@link validateSerializableSnapshot}
+     * 2. Return early if validation failed (origin: 'repository')
+     * 3. Store the validated prototypes via {@link storeSnapshot}
+     * 4. Return success or store failure result
+     *
+     * **Concurrency Control**:
+     * Unlike {@link fetchAndStore}, this method does NOT use concurrency control because:
+     * - This is a synchronous method (no await points)
+     * - JavaScript's single-threaded nature prevents concurrent execution
+     * - Multiple calls will execute sequentially, not simultaneously
+     * - Each call will update the store in order
+     *
+     * **Error Handling**:
+     * - Returns {@link RepositorySnapshotFailure} if validation fails
+     * - Returns {@link StoreSnapshotFailure} if storage fails (e.g., {@link DataSizeExceededError})
+     * - Previous snapshot remains intact on failure
+     * - Never throws exceptions - all errors are returned as {@link SnapshotOperationResult}
+     *
+     * **Logging**:
+     * - Validation: Handled by {@link validateSerializableSnapshot}
+     * - Storage success: Handled by {@link storeSnapshot} at `debug` level
+     * - Storage failure: Handled by {@link storeSnapshot}
+     *
+     * @internal
+     * This method is private and used only by {@link setupSnapshotFromSerializedData}.
+     *
+     * @see {@link setupSnapshotFromSerializedData} - Public API
+     * @see {@link validateSerializableSnapshot} - Validation logic
+     * @see {@link storeSnapshot} - Storage implementation
+     * @see {@link fetchAndStore} - Async equivalent with concurrency control
+     */
+    loadAndStore(data) {
+        // Validate data structure
+        const validationResult = validateSerializableSnapshot(data, this.#logger);
+        if (!validationResult.ok) {
+            return {
+                ok: false,
+                origin: 'repository',
+                kind: 'validation',
+                // validationResult.code -> "REPOSITORY_VALIDATION_ERROR"
+                code: 'REPOSITORY_VALIDATION_ERROR',
+                message: validationResult.message,
+            };
+        }
+        // Store the validated data
+        const storeResult = this.storeSnapshot(data.prototypes);
+        // Return early on store failure, converting to SnapshotOperationFailure
+        if (!storeResult.ok) {
+            return convertStoreResult(storeResult);
+        }
+        return convertStoreResult(storeResult);
+    }
+    /**
+     * Setup snapshot from previously serialized data.
+     *
+     * Alternative to {@link setupSnapshot} for offline/cached initialization.
+     * Validates the data structure and populates the in-memory store.
+     *
+     * **Important**: This method resets `#lastFetchParams` to `undefined`, preventing
+     * {@link refreshSnapshot} from working until {@link setupSnapshot} is called.
+     * This ensures that API parameters don't become mismatched with serialized data.
+     *
+     * @param data - Serializable snapshot object (previously exported via {@link getSerializableSnapshot})
+     * @returns {@link SnapshotOperationResult} indicating success or failure
+     *
+     * @remarks
+     * **Caller Responsibilities**:
+     * - Load snapshot file (e.g., `fs.readFile()`)
+     * - Parse JSON to JavaScript object (e.g., `JSON.parse()`)
+     * - Pass the parsed object to this method
+     *
+     * **Operation Flow**:
+     * 1. Reset `#lastFetchParams` to `undefined`
+     * 2. Emit `snapshotStarted('setupFromSerializedData')` event (if enabled)
+     * 3. Validate data structure via {@link loadAndStore}
+     * 4. Store validated prototypes if validation succeeds
+     * 5. Return operation result
+     *
+     * **Side Effects**:
+     * - Resets cached API fetch parameters
+     * - Subsequent {@link refreshSnapshot} calls will fail with `REPOSITORY_INVALID_STATE`
+     * - Use {@link setupSnapshot} after this method to re-enable {@link refreshSnapshot}
+     *
+     * **This method does NOT**:
+     * - Perform file I/O operations
+     * - Parse JSON strings
+     * - Make network requests
+     *
+     * @example
+     * ```typescript
+     * // Import from file
+     * const json = await fs.readFile('snapshot.json', 'utf-8');
+     * const data = JSON.parse(json);
+     * const result = repo.setupSnapshotFromSerializedData(data);
+     *
+     * if (result.ok) {
+     *   console.log(`Loaded ${result.stats.size} prototypes`);
+     * } else {
+     *   console.error(`Import failed: ${result.message}`);
+     * }
+     * ```
+     *
+     * @see {@link loadAndStore} for the core implementation
+     * @see {@link getSerializableSnapshot} for exporting snapshots
+     * @see {@link setupSnapshot} for API-based initialization
+     */
+    setupSnapshotFromSerializedData(data) {
+        // Reset fetch parameters immediately when attempting to load from serialized data.
+        // This ensures that any subsequent refreshSnapshot() calls will fail explicitly,
+        // rather than using potentially mismatched API parameters from a previous setupSnapshot().
+        this.#lastFetchParams = undefined;
+        emitRepositoryEventSafely(this.events, this.#logger, 'snapshotStarted', 'setupFromSerializedData');
+        const result = this.loadAndStore(data);
+        // Emit events based on result
+        if (result.ok) {
+            emitRepositoryEventSafely(this.events, this.#logger, 'snapshotCompleted', result.stats);
+        }
+        else {
+            emitRepositoryEventSafely(this.events, this.#logger, 'snapshotFailed', result);
+        }
+        return result;
+    }
+    /**
+     * Get current snapshot as a serializable object.
+     *
+     * Returns a plain JavaScript object containing all prototypes from the current
+     * snapshot along with metadata. The returned object can be passed to
+     * JSON.stringify() for persistence.
+     *
+     * This method does NOT perform file I/O or JSON.stringify().
+     * The caller is responsible for serialization and storage.
+     *
+     * @returns Serializable snapshot object with version, timestamp, and prototypes
+     *
+     * @example
+     * ```typescript
+     * // Export to file
+     * const snapshot = repo.getSerializableSnapshot();
+     * const json = JSON.stringify(snapshot, null, 2);
+     * await fs.writeFile('snapshot.json', json, 'utf-8');
+     * ```
+     */
+    getSerializableSnapshot() {
+        const prototypes = this.#store.getAll();
+        // Create deep mutable copies for serialization
+        // This removes readonly constraints while preserving all data
+        const serializablePrototypes = prototypes.map((p) => ({
+            ...p,
+            users: [...p.users],
+            tags: [...p.tags],
+            materials: [...p.materials],
+            events: [...p.events],
+            awards: [...p.awards],
+        }));
+        return {
+            version: SNAPSHOT_SERIALIZATION_VERSION,
+            serializedAt: new Date().toISOString(),
+            prototypes: serializablePrototypes,
+        };
+    }
+    /**
+     * Execute a fetch operation with promise coalescing to prevent concurrent API calls.
+     *
+     * If a fetch is already in progress, returns the existing promise instead of
+     * starting a new fetch. This ensures that multiple concurrent calls result in
+     * only one API request.
+     *
+     * @param fetchFn - Function that performs the actual fetch operation
+     * @returns Promise that resolves to the fetch result
+     */
+    async #executeWithCoalescing(fetchFn) {
+        // If a fetch is already in progress, return the existing promise
+        if (this.#ongoingFetch) {
+            return this.#ongoingFetch;
+        }
+        // Start new fetch and store the promise
+        this.#ongoingFetch = fetchFn();
+        try {
+            const result = await this.#ongoingFetch;
+            // Emit events based on result
+            if (result.ok) {
+                emitRepositoryEventSafely(this.events, this.#logger, 'snapshotCompleted', result.stats);
+            }
+            else {
+                emitRepositoryEventSafely(this.events, this.#logger, 'snapshotFailed', result);
+            }
+            return result;
+        }
+        finally {
+            // Clear the ongoing fetch regardless of success or failure
+            this.#ongoingFetch = null;
+        }
+    }
+    /**
+     * Look up a prototype by id in the current snapshot.
+     * Never performs HTTP requests.
+     *
+     * @param prototypeId - The prototype ID to look up. Must be a positive integer.
+     * @returns The prototype if found, null otherwise
+     * @throws {ValidationError} If prototypeId is not a positive integer
+     */
+    async getPrototypeFromSnapshotByPrototypeId(prototypeId) {
+        RepositoryParamsValidator.validatePrototypeId(prototypeId);
+        return this.#store.getByPrototypeId(prototypeId);
+    }
+    /**
+     * Return a random prototype from the current snapshot, or null
+     * when the snapshot is empty. Never performs HTTP requests.
+     *
+     * @remarks
+     * **Implementation Note**: This method uses `store.size` for O(1) empty check,
+     * then `store.getAll()` to select a random element. While it might seem wasteful
+     * to copy all objects just to select one, the alternative would require:
+     *
+     * 1. Call `getPrototypeIds()` - O(n) to iterate Map keys
+     * 2. Select random ID - O(1)
+     * 3. Call `getByPrototypeId(id)` - O(1)
+     *
+     * This approach still costs O(n) for step 1, making it no better than
+     * `getAll()` in terms of time complexity, but with additional function
+     * call overhead. The current implementation is simpler and equally
+     * efficient.
+     */
+    async getRandomPrototypeFromSnapshot() {
+        if (this.#store.size === 0) {
+            return null;
+        }
+        const all = this.#store.getAll();
+        const index = Math.floor(Math.random() * all.length);
+        return all[index] ?? null;
+    }
+    /**
+     * Return random samples from the current snapshot.
+     *
+     * Returns up to `size` random prototypes without duplicates.
+     * If `size` exceeds the available data, returns all prototypes in random order.
+     * Never performs HTTP requests.
+     *
+     * @param size - Maximum number of samples to return. Must be an integer.
+     * @returns Array of random prototypes (empty array if size <= 0 or snapshot is empty)
+     * @throws {ValidationError} If size is not an integer
+     *
+     * @remarks
+     * **Implementation Note**: Uses a hybrid approach for optimal performance:
+     *
+     * - `store.size` provides O(1) empty check
+     * - `store.getAll()` is O(1) (returns reference to internal array)
+     * - For small samples (< 50% of total): Set-based random selection, O(size)
+     * - For large samples (≥ 50% of total): Fisher-Yates shuffle, O(n)
+     *
+     * This hybrid approach optimizes for the common case where sample size is
+     * much smaller than the total population, while avoiding performance
+     * degradation when the sample size approaches the total size.
+     */
+    async getRandomSampleFromSnapshot(size) {
+        RepositoryParamsValidator.validateSampleSize(size);
+        if (size <= 0 || this.#store.size === 0) {
+            return [];
+        }
+        const all = this.#store.getAll();
+        const actualSize = Math.min(size, all.length);
+        // For large samples (≥50% of total), use Fisher-Yates shuffle
+        if (actualSize > all.length * SAMPLE_SIZE_THRESHOLD_RATIO) {
+            const shuffled = [...all];
+            for (let i = shuffled.length - 1; i > 0; i--) {
+                const j = Math.floor(Math.random() * (i + 1));
+                [shuffled[i], shuffled[j]] = [shuffled[j], shuffled[i]];
+            }
+            return shuffled.slice(0, actualSize);
+        }
+        // For small samples, use Set-based collision avoidance
+        const result = [];
+        const indices = new Set();
+        while (result.length < actualSize) {
+            const index = Math.floor(Math.random() * all.length);
+            if (!indices.has(index)) {
+                indices.add(index);
+                result.push(all[index]);
+            }
+        }
+        return result;
+    }
+    /**
+     * Return all prototype IDs from the current snapshot.
+     * Never performs HTTP requests.
+     */
+    async getPrototypeIdsFromSnapshot() {
+        return this.#store.getPrototypeIds();
+    }
+    /**
+     * Return all prototypes from the current snapshot.
+     * Never performs HTTP requests.
+     */
+    async getAllFromSnapshot() {
+        return this.#store.getAll();
+    }
+    /**
+     * Analyze prototypes to extract ID range (minimum and maximum).
+     *
+     * Uses a for-loop implementation for better performance with large datasets (5,000+ items).
+     * Single-pass algorithm with minimal memory allocations.
+     *
+     * @param prototypes - Array of prototypes to analyze
+     * @returns Object containing min and max IDs, or null values if array is empty
+     */
+    analyzePrototypesWithForLoop(prototypes) {
+        if (prototypes.length === 0) {
+            return { min: null, max: null };
+        }
+        let min = prototypes[0].id;
+        let max = prototypes[0].id;
+        for (let i = 1; i < prototypes.length; i++) {
+            const id = prototypes[i].id;
+            if (id < min)
+                min = id;
+            if (id > max)
+                max = id;
+        }
+        return { min, max };
+    }
+    /**
+     * Analyze prototypes from the current snapshot to extract ID range.
+     *
+     * Currently uses the for-loop implementation for optimal performance with typical dataset sizes.
+     * Never performs HTTP requests.
+     *
+     * @returns Object containing min and max IDs, or null values if snapshot is empty
+     */
+    async analyzePrototypes() {
+        const all = this.#store.getAll();
+        return this.analyzePrototypesWithForLoop(all);
+    }
+    /**
+     * Clean up event listeners and release resources.
+     *
+     * Removes all event listeners from the internal EventEmitter to prevent memory leaks.
+     * Safe to call even when events are disabled.
+     *
+     * @remarks
+     * Always call this method in cleanup paths:
+     * - Test cleanup (afterEach)
+     * - Component unmounting (React useEffect cleanup)
+     * - Before creating a new repository instance
+     */
+    dispose() {
+        this.events?.removeAllListeners();
+    }
+}
+//# sourceMappingURL=protopedia-in-memory-repository.js.map