promidas 2.0.0

package/dist/factory.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Factory functions for creating {@link ProtopediaInMemoryRepository} instances.
+ *
+ * This module provides convenience factory functions that simplify the setup
+ * of ProtopediaInMemoryRepository for common use cases.
+ *
+ * ## About This Implementation
+ *
+ * These factory functions serve as **sample implementations** and are intentionally
+ * verbose to demonstrate the pattern. Users are encouraged to create their own
+ * custom factory functions optimized for their specific use cases.
+ *
+ * The current implementations are simple wrappers around {@link PromidasRepositoryBuilder},
+ * but can be extended with environment-specific defaults (e.g., different TTL values,
+ * log levels, or API client configurations).
+ *
+ * @example Creating a custom factory
+ * ```typescript
+ * import { PromidasRepositoryBuilder } from 'promidas';
+ * import type { ProtopediaInMemoryRepository } from 'promidas';
+ *
+ * export function createMyCustomRepository(): ProtopediaInMemoryRepository {
+ *   return new PromidasRepositoryBuilder()
+ *     .setStoreConfig({ ttlMs: 60 * 60 * 1000, logLevel: 'warn' }) // 1 hour TTL
+ *     .build();
+ * }
+ * ```
+ *
+ * @module
+ */
+import type { LogLevel } from './logger/index.js';
+import type { ProtopediaInMemoryRepository } from './repository/types/index.js';
+/**
+ * Creates a PromidasRepository instance optimized for local execution environments.
+ *
+ * This factory function is designed for personal computers, local scripts,
+ * and development environments where the TOKEN can be safely stored.
+ *
+ * ## Pre-configured Settings
+ *
+ * This function automatically configures the following settings:
+ *
+ * **Logger:**
+ * - Log Level: `'info'` (records normal operations for development monitoring)
+ *
+ * **Store:**
+ * - TTL: 30 minutes (1,800,000 ms)
+ * - Max Data Size: 30 MiB (hard limit)
+ *
+ * **API Client:**
+ * - Timeout: 90 seconds (accommodates 1-2 Mbps connections)
+ * - User-Agent: `PromidasForLocal/{version}`
+ *
+ * ## Use Cases
+ *
+ * - Local development and testing
+ * - Command-line scripts
+ * - Personal automation tools
+ * - Data analysis scripts
+ *
+ * @param config - Configuration options
+ * @param config.protopediaApiToken - ProtoPedia API v2 token
+ * @param config.logLevel - Log level for all components (optional, default: 'info')
+ * @returns A configured PromidasRepository instance
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { createPromidasForLocal } from "promidas";
+ *
+ * const repository = createPromidasForLocal({
+ *   protopediaApiToken: 'your-api-token',
+ * });
+ *
+ * // Setup snapshot with 100 prototypes
+ * await repository.setupSnapshot({ limit: 100 });
+ *
+ * // Get random prototype
+ * const prototype = await repository.getRandomPrototypeFromSnapshot();
+ * console.log(prototype?.prototypeNm);
+ * ```
+ *
+ * @example With custom log level
+ * ```typescript
+ * const repository = createPromidasForLocal({
+ *   protopediaApiToken: process.env.PROTOPEDIA_API_V2_TOKEN!,
+ *   logLevel: 'warn', // Only show warnings and errors
+ * });
+ * ```
+ */
+export declare function createPromidasForLocal(config: {
+    protopediaApiToken: string;
+    logLevel?: LogLevel;
+}): ProtopediaInMemoryRepository;
+/**
+ * Creates a PromidasRepository instance optimized for server backend environments.
+ *
+ * This factory function is designed for Node.js server applications
+ * where the TOKEN is managed securely via environment variables.
+ *
+ * ## Pre-configured Settings
+ *
+ * This function automatically configures the following settings:
+ *
+ * **Environment Variable:**
+ * - Token Source: `PROTOPEDIA_API_V2_TOKEN` (required)
+ *
+ * **Logger:**
+ * - Log Level: `'warn'` (production-ready, warnings and errors only)
+ *
+ * **Store:**
+ * - TTL: 10 minutes (600,000 ms)
+ * - Max Data Size: 30 MiB (hard limit)
+ *
+ * **API Client:**
+ * - Timeout: 30 seconds (server-grade connection)
+ * - User-Agent: `PromidasForServer/{version}`
+ *
+ * ## Use Cases
+ *
+ * - REST API servers
+ * - Background job processors
+ * - Serverless functions (AWS Lambda, Cloud Functions)
+ * - Microservices
+ *
+ * @param config - Configuration options
+ * @param config.logLevel - Log level for all components (optional, default: 'warn')
+ * @returns A configured PromidasRepository instance
+ * @throws {Error} If PROTOPEDIA_API_V2_TOKEN environment variable is not set
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { createPromidasForServer } from "promidas";
+ *
+ * // TOKEN is read from PROTOPEDIA_API_V2_TOKEN environment variable
+ * const repository = createPromidasForServer();
+ *
+ * // Setup snapshot with 1000 prototypes
+ * await repository.setupSnapshot({ limit: 1000 });
+ *
+ * // Get prototype by ID
+ * const prototype = await repository.getPrototypeFromSnapshotByPrototypeId(123);
+ * ```
+ *
+ * @example With custom log level
+ * ```typescript
+ * const repository = createPromidasForServer({
+ *   logLevel: 'error', // Only show errors in production
+ * });
+ * ```
+ */
+export declare function createPromidasForServer(config?: {
+    logLevel?: LogLevel;
+}): ProtopediaInMemoryRepository;
+//# sourceMappingURL=factory.d.ts.map

package/dist/factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../lib/factory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAKH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,KAAK,EACV,4BAA4B,EAE7B,MAAM,6BAA6B,CAAC;AAKrC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE;IAC7C,kBAAkB,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,EAAE,QAAQ,CAAC;CACrB,GAAG,4BAA4B,CAqD/B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,CAAC,EAAE;IAC/C,QAAQ,CAAC,EAAE,QAAQ,CAAC;CACrB,GAAG,4BAA4B,CAsD/B"}

package/dist/factory.js

@@ -0,0 +1,243 @@
+/**
+ * Factory functions for creating {@link ProtopediaInMemoryRepository} instances.
+ *
+ * This module provides convenience factory functions that simplify the setup
+ * of ProtopediaInMemoryRepository for common use cases.
+ *
+ * ## About This Implementation
+ *
+ * These factory functions serve as **sample implementations** and are intentionally
+ * verbose to demonstrate the pattern. Users are encouraged to create their own
+ * custom factory functions optimized for their specific use cases.
+ *
+ * The current implementations are simple wrappers around {@link PromidasRepositoryBuilder},
+ * but can be extended with environment-specific defaults (e.g., different TTL values,
+ * log levels, or API client configurations).
+ *
+ * @example Creating a custom factory
+ * ```typescript
+ * import { PromidasRepositoryBuilder } from 'promidas';
+ * import type { ProtopediaInMemoryRepository } from 'promidas';
+ *
+ * export function createMyCustomRepository(): ProtopediaInMemoryRepository {
+ *   return new PromidasRepositoryBuilder()
+ *     .setStoreConfig({ ttlMs: 60 * 60 * 1000, logLevel: 'warn' }) // 1 hour TTL
+ *     .build();
+ * }
+ * ```
+ *
+ * @module
+ */
+import { PromidasRepositoryBuilder } from './builder.js';
+import { ConsoleLogger } from './logger/console-logger.js';
+import { LIMIT_DATA_SIZE_BYTES as STORE_MAX_DATA_SIZE_BYTES_LIMIT } from './store/index.js';
+import { VERSION } from './version.js';
+/**
+ * Creates a PromidasRepository instance optimized for local execution environments.
+ *
+ * This factory function is designed for personal computers, local scripts,
+ * and development environments where the TOKEN can be safely stored.
+ *
+ * ## Pre-configured Settings
+ *
+ * This function automatically configures the following settings:
+ *
+ * **Logger:**
+ * - Log Level: `'info'` (records normal operations for development monitoring)
+ *
+ * **Store:**
+ * - TTL: 30 minutes (1,800,000 ms)
+ * - Max Data Size: 30 MiB (hard limit)
+ *
+ * **API Client:**
+ * - Timeout: 90 seconds (accommodates 1-2 Mbps connections)
+ * - User-Agent: `PromidasForLocal/{version}`
+ *
+ * ## Use Cases
+ *
+ * - Local development and testing
+ * - Command-line scripts
+ * - Personal automation tools
+ * - Data analysis scripts
+ *
+ * @param config - Configuration options
+ * @param config.protopediaApiToken - ProtoPedia API v2 token
+ * @param config.logLevel - Log level for all components (optional, default: 'info')
+ * @returns A configured PromidasRepository instance
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { createPromidasForLocal } from "promidas";
+ *
+ * const repository = createPromidasForLocal({
+ *   protopediaApiToken: 'your-api-token',
+ * });
+ *
+ * // Setup snapshot with 100 prototypes
+ * await repository.setupSnapshot({ limit: 100 });
+ *
+ * // Get random prototype
+ * const prototype = await repository.getRandomPrototypeFromSnapshot();
+ * console.log(prototype?.prototypeNm);
+ * ```
+ *
+ * @example With custom log level
+ * ```typescript
+ * const repository = createPromidasForLocal({
+ *   protopediaApiToken: process.env.PROTOPEDIA_API_V2_TOKEN!,
+ *   logLevel: 'warn', // Only show warnings and errors
+ * });
+ * ```
+ */
+export function createPromidasForLocal(config) {
+    // Create a builder instance
+    const builder = new PromidasRepositoryBuilder();
+    // Determine log level
+    // Note: 'info' level records normal operations for development monitoring
+    const logLevel = config.logLevel ?? 'info';
+    // Create a shared logger instance for memory efficiency
+    //
+    // Design Decision: We create one ConsoleLogger and share it across all components
+    // instead of passing logLevel to each component's config. This reduces memory
+    // footprint and ensures consistent logging behavior across the repository.
+    const logger = new ConsoleLogger(logLevel);
+    // Configure store with default TTL for local development
+    const storeConfig = {
+        ttlMs: 30 * 60 * 1000, // 30 minutes
+        maxDataSizeBytes: STORE_MAX_DATA_SIZE_BYTES_LIMIT, // 30 MiB
+        logger, // Shared logger - logLevel is NOT set because logger already contains it
+    };
+    builder.setStoreConfig(storeConfig);
+    // Configure API client wrapper
+    const apiClientConfig = {
+        protoPediaApiClientOptions: {
+            token: config.protopediaApiToken,
+            // Timeout for API requests (SDK default: 15000ms = 15s)
+            // Reference: 20MB download time by connection speed:
+            //   - 10 Mbps: ~16s
+            //   - 5 Mbps: ~32s
+            //   - 1 Mbps: ~160s (2m40s)
+            //   - 0.5 Mbps: ~320s (5m20s)
+            timeoutMs: 90 * 1_000, // 90 seconds (accommodates 1-2 Mbps)
+            userAgent: `PromidasForLocal/${VERSION}`,
+            // Ensure SDK-level network logs are controlled consistently.
+            // Note: The SDK logger interface is compatible with promidas logger.
+            logger,
+            logLevel,
+        },
+        logger, // Shared logger - logLevel is NOT set because logger already contains it
+        progressLog: true,
+    };
+    builder.setApiClientConfig(apiClientConfig);
+    // Configure repository
+    const repositoryConfig = {
+        logger, // Shared logger - logLevel is NOT set because logger already contains it
+    };
+    builder.setRepositoryConfig(repositoryConfig);
+    // Build and return the repository instance
+    return builder.build();
+}
+/**
+ * Creates a PromidasRepository instance optimized for server backend environments.
+ *
+ * This factory function is designed for Node.js server applications
+ * where the TOKEN is managed securely via environment variables.
+ *
+ * ## Pre-configured Settings
+ *
+ * This function automatically configures the following settings:
+ *
+ * **Environment Variable:**
+ * - Token Source: `PROTOPEDIA_API_V2_TOKEN` (required)
+ *
+ * **Logger:**
+ * - Log Level: `'warn'` (production-ready, warnings and errors only)
+ *
+ * **Store:**
+ * - TTL: 10 minutes (600,000 ms)
+ * - Max Data Size: 30 MiB (hard limit)
+ *
+ * **API Client:**
+ * - Timeout: 30 seconds (server-grade connection)
+ * - User-Agent: `PromidasForServer/{version}`
+ *
+ * ## Use Cases
+ *
+ * - REST API servers
+ * - Background job processors
+ * - Serverless functions (AWS Lambda, Cloud Functions)
+ * - Microservices
+ *
+ * @param config - Configuration options
+ * @param config.logLevel - Log level for all components (optional, default: 'warn')
+ * @returns A configured PromidasRepository instance
+ * @throws {Error} If PROTOPEDIA_API_V2_TOKEN environment variable is not set
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { createPromidasForServer } from "promidas";
+ *
+ * // TOKEN is read from PROTOPEDIA_API_V2_TOKEN environment variable
+ * const repository = createPromidasForServer();
+ *
+ * // Setup snapshot with 1000 prototypes
+ * await repository.setupSnapshot({ limit: 1000 });
+ *
+ * // Get prototype by ID
+ * const prototype = await repository.getPrototypeFromSnapshotByPrototypeId(123);
+ * ```
+ *
+ * @example With custom log level
+ * ```typescript
+ * const repository = createPromidasForServer({
+ *   logLevel: 'error', // Only show errors in production
+ * });
+ * ```
+ */
+export function createPromidasForServer(config) {
+    // Read TOKEN from environment variable
+    const protopediaApiToken = process.env.PROTOPEDIA_API_V2_TOKEN;
+    if (!protopediaApiToken) {
+        throw new Error('PROTOPEDIA_API_V2_TOKEN environment variable is required for server environments');
+    }
+    // Create a builder instance
+    const builder = new PromidasRepositoryBuilder();
+    // Determine log level for server environment
+    // Note: 'warn' level is recommended for server environments to reduce log volume
+    const logLevel = config?.logLevel ?? 'warn';
+    // Create a shared logger instance for memory efficiency
+    //
+    // Design Decision: We create one ConsoleLogger and share it across all components
+    // instead of passing logLevel to each component's config. This reduces memory
+    // footprint and ensures consistent logging behavior across the repository.
+    const logger = new ConsoleLogger(logLevel);
+    // Configure store for server environments (shorter TTL for memory efficiency)
+    const storeConfig = {
+        ttlMs: 10 * 60 * 1000, // 10 minutes
+        maxDataSizeBytes: STORE_MAX_DATA_SIZE_BYTES_LIMIT, // 30 MiB
+        logger, // Shared logger - logLevel is NOT set because logger already contains it
+    };
+    builder.setStoreConfig(storeConfig);
+    // Configure API client for server environments (stable, high-speed connections)
+    const apiClientConfig = {
+        protoPediaApiClientOptions: {
+            token: protopediaApiToken,
+            timeoutMs: 30 * 1_000, // 30 seconds
+            userAgent: `PromidasForServer/${VERSION}`,
+            // Ensure SDK-level network logs are controlled consistently.
+            logger,
+            logLevel,
+        },
+        logger, // Shared logger - logLevel is NOT set because logger already contains it
+        progressLog: true,
+    };
+    builder.setApiClientConfig(apiClientConfig);
+    // Configure repository
+    const repositoryConfig = {
+        logger, // Shared logger - logLevel is NOT set because logger already contains it
+    };
+    builder.setRepositoryConfig(repositoryConfig);
+    // Build and return the repository instance
+    return builder.build();
+}
+//# sourceMappingURL=factory.js.map

package/dist/factory.js.map

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

package/dist/fetcher/client/config.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Configuration types for ProtopediaApiCustomClient.
+ *
+ * @module
+ */
+import type { ProtoPediaApiClientOptions } from 'protopedia-api-v2-client';
+import type { Logger, LogLevel } from '../../logger/index.js';
+import type { FetchProgressEvent } from '../types/progress-event.types.js';
+/**
+ * Configuration options for ProtopediaApiCustomClient.
+ *
+ * @example
+ * ```typescript
+ * // Pattern 1: logLevel only (creates ConsoleLogger internally)
+ * const config1: ProtopediaApiCustomClientConfig = {
+ *   protoPediaApiClientOptions: {
+ *     token: process.env.PROTOPEDIA_API_TOKEN,
+ *   },
+ *   logLevel: 'debug',
+ * };
+ *
+ * // Pattern 2: Custom logger with logLevel
+ * import { createConsoleLogger } from 'promidas/logger';
+ * const config2: ProtopediaApiCustomClientConfig = {
+ *   protoPediaApiClientOptions: {
+ *     token: process.env.PROTOPEDIA_API_TOKEN,
+ *   },
+ *   logger: createConsoleLogger(),
+ *   logLevel: 'warn', // Updates logger's level if mutable
+ * };
+ *
+ * // Pattern 3: Custom logger only
+ * const config3: ProtopediaApiCustomClientConfig = {
+ *   protoPediaApiClientOptions: {
+ *     token: process.env.PROTOPEDIA_API_TOKEN,
+ *   },
+ *   logger: createConsoleLogger(), // Uses logger's existing level
+ * };
+ * ```
+ */
+export type ProtopediaApiCustomClientConfig = {
+    /**
+     * Options passed to the underlying protopedia-api-v2-client.
+     *
+     * @remarks
+     * This allows full control over the official client's configuration,
+     * including token, baseUrl, fetch implementation, and timeout settings.
+     */
+    protoPediaApiClientOptions?: ProtoPediaApiClientOptions;
+    /**
+     * Custom logger instance.
+     *
+     * @remarks
+     * - If provided, the logger will be used as-is
+     * - If provided with logLevel, the level will be updated if logger is mutable
+     * - If not provided, creates a ConsoleLogger with the specified logLevel
+     *
+     * @default undefined (creates ConsoleLogger with 'info' level)
+     */
+    logger?: Logger;
+    /**
+     * Log level for creating a default ConsoleLogger.
+     *
+     * @remarks
+     * - Only used when `logger` is NOT provided
+     * - Creates a new ConsoleLogger with this level
+     * - If logger is provided and mutable, updates its level property
+     *
+     * @default 'info'
+     */
+    logLevel?: LogLevel;
+    /**
+     * Enable download progress logging.
+     *
+     * @remarks
+     * - When enabled, logs download progress to logger
+     * - Requires logger to be configured to show info level logs
+     * - Useful for monitoring large data downloads on slow connections
+     * - Works independently of progressCallback
+     *
+     * @default true
+     */
+    progressLog?: boolean;
+    /**
+     * Download progress callback.
+     *
+     * Receives events for all phases of the fetch request lifecycle:
+     * - `request-start`: Fired when fetch() is called
+     * - `response-received`: Fired when response headers are received
+     * - `download-progress`: Fired periodically during body download (throttled to 500ms)
+     * - `complete`: Fired when download completes successfully
+     *
+     * @remarks
+     * - All events are fired regardless of progressLog setting
+     * - Use TypeScript's discriminated union for type-safe event handling
+     * - Events are fired in order: request-start → response-received → download-progress (0+) → complete
+     *
+     * @example Complete lifecycle handling
+     * ```typescript
+     * const client = new ProtopediaApiCustomClient({
+     *   progressCallback: (event) => {
+     *     switch (event.type) {
+     *       case 'request-start':
+     *         console.log('🚀 Request initiated...');
+     *         break;
+     *       case 'response-received':
+     *         console.log(`✓ Headers received (${event.prepareTimeMs}ms)`);
+     *         console.log(`  Estimated: ${event.estimatedTotal} bytes`);
+     *         break;
+     *       case 'download-progress':
+     *         console.log(`📥 ${event.percentage.toFixed(1)}%`);
+     *         break;
+     *       case 'complete':
+     *         console.log(`✅ Complete (${event.totalTimeMs}ms total)`);
+     *         break;
+     *     }
+     *   },
+     * });
+     * ```
+     *
+     * @example Progress bar integration
+     * ```typescript
+     * let progressBar: ProgressBar | null = null;
+     *
+     * const client = new ProtopediaApiCustomClient({
+     *   progressCallback: (event) => {
+     *     if (event.type === 'response-received') {
+     *       progressBar = new ProgressBar({ total: event.estimatedTotal });
+     *     } else if (event.type === 'download-progress' && progressBar) {
+     *       progressBar.update(event.percentage);
+     *     } else if (event.type === 'complete' && progressBar) {
+     *       progressBar.finish();
+     *     }
+     *   },
+     * });
+     * ```
+     */
+    progressCallback?: (event: FetchProgressEvent) => void;
+};
+//# sourceMappingURL=config.d.ts.map

package/dist/fetcher/client/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../lib/fetcher/client/config.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,0BAA0B,CAAC;AAE3E,OAAO,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AAE3E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,MAAM,+BAA+B,GAAG;IAC5C;;;;;;OAMG;IACH,0BAA0B,CAAC,EAAE,0BAA0B,CAAC;IAExD;;;;;;;;;OASG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;;;;;;;OASG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAC;IAEpB;;;;;;;;;;OAUG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IAEtB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAqDG;IACH,gBAAgB,CAAC,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,IAAI,CAAC;CACxD,CAAC"}

package/dist/fetcher/client/config.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=config.js.map

package/dist/fetcher/client/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../../lib/fetcher/client/config.ts"],"names":[],"mappings":""}