promidas 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 F88
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,179 @@
+# PROMIDAS
+
+[![CI](https://github.com/F88/promidas/actions/workflows/ci.yml/badge.svg)](https://github.com/F88/promidas/actions/workflows/ci.yml)
+[![CodeQL](https://github.com/F88/promidas/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/F88/promidas/actions/workflows/github-code-scanning/codeql)
+[![Publish package to npmjs.com](https://github.com/F88/promidas/actions/workflows/publish-package-to-npmjs.yml/badge.svg)](https://github.com/F88/promidas/actions/workflows/publish-package-to-npmjs.yml)
+[![codecov](https://codecov.io/github/F88/promidas/graph/badge.svg)](https://codecov.io/github/F88/promidas)
+
+![Release](https://img.shields.io/github/v/release/F88/promidas?label=release)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+![Issues](https://img.shields.io/github/issues/F88/promidas?label=issues)
+
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/F88/promidas)
+[![View Code Wiki](https://www.gstatic.com/_/boq-sdlc-agents-ui/_/r/YUi5dj2UWvE.svg)](https://codewiki.google/github.com/f88/promidas)
+
+ProtoPedia Resource Organized Management In-memory Data Access Store
+
+A toolset library for ProtoPedia providing independent store and fetcher components, and a high-level repository for easy data management.
+
+## クイックスタート
+
+**[📖 ドキュメントサイト](https://f88.github.io/promidas/)** - 使い方とサンプルコード
+
+**[🛝 PROMIDAS Playground](https://f88.github.io/PROMIDAS-demo/)** - デモ
+
+**初めての方へ:**
+
+1. [スタートガイド](https://f88.github.io/promidas/getting-started.html) - インストールと最初の一歩
+2. [ユースケース](https://f88.github.io/promidas/use-case/) - あなたの利用シーンを選ぶ
+
+**今すぐ試す:**
+
+```bash
+npm install promidas
+export PROTOPEDIA_API_V2_TOKEN="your-token-here"
+npx tsx scripts/try-protopedia-repository.ts
+```
+
+---
+
+## Project Overview
+
+This repository provides a modular toolset for managing ProtoPedia data, consisting of independent components and a high-level repository:
+
+1. **`lib/types`** - Compile-time Type Definitions (`NormalizedPrototype`, `StatusCode`, etc.)
+    - Type-safe TypeScript definitions for ProtoPedia data structures
+    - Normalized representation with consistent handling of dates, arrays, and optional fields
+    - Shared across all layers: fetcher, store, repository, and validation utilities
+    - Foundation for compile-time type safety (complements runtime validation in lib/schemas)
+    - [📘 README](lib/types/README.md) | [Usage Guide](lib/types/docs/USAGE.md) | [Design Document](lib/types/docs/DESIGN.md)
+
+2. **`lib/schemas`** - Runtime Validation Schemas (`normalizedPrototypeSchema`)
+    - Zod-based runtime validation for external data (API responses, snapshots, files)
+    - Complements compile-time types for complete type safety (TypeScript + runtime)
+    - Shared across fetcher, repository, and validation utilities
+    - Strict code value validation (e.g., status: 1|2|3|4, not just any number)
+    - [📘 README](lib/schemas/README.md) | [Usage Guide](lib/schemas/docs/USAGE.md) | [Design Document](lib/schemas/docs/DESIGN.md)
+
+3. **`lib/utils`** - Utility Functions and Converters
+    - Type-safe converters for ProtoPedia data (status, license, flags)
+    - Timestamp parsers (ProtoPedia JST format and W3C-DTF)
+    - Shared type definitions and constants
+    - Independent utilities usable across all modules
+    - [📘 README](lib/utils/README.md) | [Usage Guide](lib/utils/docs/USAGE.md) | [Design Document](lib/utils/docs/DESIGN.md)
+
+4. **`lib/store`** - Standalone In-memory Store (`PrototypeInMemoryStore`)
+    - Generic snapshot management with TTL support
+    - O(1) lookups by ID via internal index
+    - Independent of any specific API client
+    - [📘 README](lib/store/README.md) | [Usage Guide](lib/store/docs/USAGE.md) | [Design Document](lib/store/docs/DESIGN.md)
+
+5. **`lib/fetcher`** - API Client Utilities (`ProtopediaApiCustomClient`)
+    - Utilities to fetch and normalize ProtoPedia prototypes
+    - Error handling and network helpers for `protopedia-api-v2-client`
+    - Supports custom logger configuration for unified diagnostic output
+    - Can be used independently to build custom data pipelines
+    - [📘 README](lib/fetcher/README.md) | [Usage Guide](lib/fetcher/docs/USAGE.md) | [Design Document](lib/fetcher/docs/DESIGN.md)
+
+6. **`lib/logger`** - Logger Interface (`Logger`)
+    - Type-safe logging interface compatible with `protopedia-api-v2-client`
+    - Used internally by Store, Fetcher, and Repository
+    - Can be replaced with custom logger (e.g., Winston, Pino)
+    - No `level` property for SDK compatibility (level managed by factory functions)
+    - [📘 README](lib/logger/README.md) | [Usage Guide](lib/logger/docs/USAGE.md) | [Design Document](lib/logger/docs/DESIGN.md)
+
+7. **`lib/repository`** - Ready-to-use Repository (`ProtopediaInMemoryRepository`)
+    - Integrates `lib/store` and `lib/fetcher` into a single easy-to-use package
+    - Best for most use cases requiring caching and automatic refreshing
+    - [📘 README](lib/repository/README.md) | [Usage Guide](lib/repository/docs/USAGE.md) | [Design Document](lib/repository/docs/DESIGN.md)
+
+8. **High-Level APIs** - Factory Functions and Builder
+    - **Factory Functions** (`lib/factory.ts`): Pre-configured for common scenarios
+        - `createPromidasForLocal()` - Optimized for local/development (30min TTL, 90s timeout, verbose logging)
+        - `createPromidasForServer()` - Optimized for server/production (10min TTL, 30s timeout, minimal logging)
+    - **Builder Pattern** (`lib/builder.ts`): Step-by-step configuration for advanced use cases
+        - `PromidasRepositoryBuilder` - Fluent API for complex configurations
+    - Exported from main module: `import { createPromidasForLocal, PromidasRepositoryBuilder } from 'promidas'`
+
+This project extracts and generalizes the data-fetching and in-memory data management capabilities originally implemented in [F88/mugen-protopedia](https://github.com/F88/mugen-protopedia/), providing them as a standalone, reusable library for various applications.
+
+## ProtoPedia API Ver 2.0
+
+This library uses ProtoPedia API Ver 2.0.
+To use the API, you need an Access Token (Bearer Token).
+
+Please refer to the API documentation for details:
+[ProtoPedia API Ver 2.0 · Apiary](https://protopediav2.docs.apiary.io/)
+
+## Fully Supported API Client
+
+This library fully supports [protopedia-api-v2-client](https://www.npmjs.com/package/protopedia-api-v2-client) v3.0.0 and later.
+
+For details on how to integrate with `protopedia-api-v2-client` and use custom fetchers (e.g. for Next.js), please refer to [`lib/fetcher/docs/USAGE.md`](lib/fetcher/docs/USAGE.md).
+
+## Subpath Exports
+
+Each module can be imported independently using subpath exports:
+
+```typescript
+// Type definitions
+import type { NormalizedPrototype, StatusCode } from 'promidas/types';
+
+// Runtime validation schemas
+import { normalizedPrototypeSchema } from 'promidas/schemas';
+
+// Utility functions
+import {
+    parseProtoPediaTimestamp,
+    getPrototypeStatusLabel,
+} from 'promidas/utils';
+
+// Logger
+import { createConsoleLogger, type Logger } from 'promidas/logger';
+
+// API client and fetcher
+import {
+    ProtopediaApiCustomClient,
+    normalizePrototype,
+} from 'promidas/fetcher';
+
+// In-memory store
+import {
+    PrototypeInMemoryStore,
+    type NormalizedPrototype,
+} from 'promidas/store';
+
+// Repository implementation
+import { ProtopediaInMemoryRepositoryImpl } from 'promidas/repository';
+
+// Factory functions and Builder (main module)
+import {
+    createPromidasForLocal,
+    createPromidasForServer,
+    PromidasRepositoryBuilder,
+} from 'promidas';
+```
+
+**Available subpath exports:**
+
+- `promidas` — High-level APIs: Factory functions and Builder (recommended)
+- `promidas/types` — Type definitions
+- `promidas/schemas` — Runtime validation schemas (Zod)
+- `promidas/utils` — Utility functions and converters
+- `promidas/logger` — Logger interface and implementations
+- `promidas/fetcher` — API client and data fetching
+- `promidas/store` — In-memory store
+- `promidas/repository` — Repository implementation
+
+## For Contributors
+
+**Development:**
+
+- [DEVELOPMENT.md](DEVELOPMENT.md) - Setup development environment and workflows
+- [CONTRIBUTING.md](CONTRIBUTING.md) - Contribution guidelines
+- [DOCUMENTATION.md](DOCUMENTATION.md) - Documentation standards and guidelines
+- [RELEASE.md](RELEASE.md) - Release process and versioning
+
+**Project History:**
+
+- [CHANGELOG.md](CHANGELOG.md) - Version history and release notes

package/dist/builder.d.ts

@@ -0,0 +1,158 @@
+/**
+ * Builder for creating Promidas repository instances.
+ *
+ * This module provides a fluent builder interface for constructing
+ * {@link ProtopediaInMemoryRepository} instances.
+ *
+ * @module
+ */
+import type { ProtoPediaApiClientOptions } from 'protopedia-api-v2-client';
+import { ProtopediaApiCustomClient, type ProtopediaApiCustomClientConfig } from './fetcher/index.js';
+import type { ProtopediaInMemoryRepository, ProtopediaInMemoryRepositoryConfig, PrototypeAnalysisResult } from './repository/types/index.js';
+import { type PrototypeInMemoryStats, type PrototypeInMemoryStoreConfig } from './store/index.js';
+export type { PrototypeInMemoryStoreConfig, PrototypeInMemoryStats, ProtopediaApiCustomClient, ProtopediaApiCustomClientConfig, ProtoPediaApiClientOptions, ProtopediaInMemoryRepository, ProtopediaInMemoryRepositoryConfig, PrototypeAnalysisResult, };
+/**
+ * A builder class for constructing {@link ProtopediaInMemoryRepository} instances.
+ *
+ * It allows for step-by-step configuration of Store, API Client, and Repository settings
+ * through a fluent interface.
+ *
+ * @remarks
+ * **Logger Configuration:**
+ * Each component (Store, API Client, Repository) receives an independent logger instance.
+ * - If you provide a custom logger, it will be used as-is
+ * - If you don't provide a logger, a new ConsoleLogger is created with the specified logLevel (default: 'info')
+ * - Each component can have different loggers and log levels for maximum flexibility
+ *
+ * @example
+ * ```typescript
+ * // Basic usage with default settings (each component gets independent logger)
+ * const repo = new PromidasRepositoryBuilder().build();
+ *
+ * // Configure store settings
+ * const repo = new PromidasRepositoryBuilder()
+ *   .setStoreConfig({ ttlMs: 60000 })
+ *   .setApiClientConfig({
+ *     protoPediaApiClientOptions: { token: 'my-token' }
+ *   })
+ *   .build();
+ *
+ * // Different log levels for each component
+ * const repo = new PromidasRepositoryBuilder()
+ *   .setStoreConfig({ logLevel: 'error' })
+ *   .setApiClientConfig({ logLevel: 'warn' })
+ *   .setRepositoryConfig({ logLevel: 'debug' })
+ *   .build();
+ * ```
+ */
+export declare class PromidasRepositoryBuilder {
+    #private;
+    /**
+     * Set configuration for the in-memory store.
+     *
+     * Multiple calls will merge configurations (later values override earlier ones).
+     * Configuration is deeply merged to prevent external mutations while preserving
+     * function references (e.g., logger methods).
+     *
+     * @param config - Store configuration (TTL, max size, logger, etc.)
+     */
+    setStoreConfig(config: PrototypeInMemoryStoreConfig): this;
+    /**
+     * Set configuration for the ProtopediaApiCustomClient wrapper.
+     * Allows configuring the logger used by the client wrapper itself.
+     *
+     * Multiple calls will merge configurations (later values override earlier ones).
+     * Configuration is deeply merged to prevent external mutations while preserving
+     * function references (e.g., logger methods).
+     *
+     * @param config - Wrapper configuration (logger, logLevel)
+     */
+    setApiClientConfig(config: ProtopediaApiCustomClientConfig): this;
+    /**
+     * Set configuration for the Repository itself.
+     *
+     * Multiple calls will merge configurations (later values override earlier ones).
+     * Configuration is deeply merged to prevent external mutations while preserving
+     * function references (e.g., logger methods).
+     *
+     * @param config - Repository configuration (logger, etc.)
+     */
+    setRepositoryConfig(config: ProtopediaInMemoryRepositoryConfig): this;
+    /**
+     * Build and return a fully configured ProtopediaInMemoryRepository instance.
+     *
+     * This method creates new instances of dependencies (Store, API Client)
+     * based on the accumulated configuration.
+     *
+     * @remarks
+     * **Logger Creation:**
+     * When no explicit logger is provided in a component's configuration, Builder
+     * creates a new ConsoleLogger instance with the specified logLevel (default: 'info').
+     * Each component receives an independent logger instance unless you explicitly
+     * share a logger by passing the same logger instance to multiple configs.
+     *
+     * **Configuration Immutability:**
+     * Configurations are deep-merged to prevent external mutations from affecting
+     * the builder's internal state.
+     *
+     * **Failure Logging:**
+     * When construction fails, this method logs the failure via the repository
+     * logger (if `logger.error` is a function) and rethrows the original error.
+     *
+     * @returns A fully configured ProtopediaInMemoryRepository instance
+     * @throws {ConfigurationError} When store configuration is invalid
+     * @throws {DataSizeExceededError} When snapshot data exceeds size limit
+     * @throws {SizeEstimationError} When snapshot size estimation fails
+     * @throws {StoreError} When store initialization fails
+     * @throws {unknown} When API client or repository construction fails
+     *
+     * @example
+     * ```typescript
+     * // Build with default settings (each component gets independent logger with 'info' level)
+     * const repo = new PromidasRepositoryBuilder().build();
+     *
+     * // Build with different log levels
+     * const repo = new PromidasRepositoryBuilder()
+     *   .setStoreConfig({ ttlMs: 60000, logLevel: 'warn' })
+     *   .setRepositoryConfig({ logLevel: 'debug' })
+     *   .build();
+     * // Result: Store gets ConsoleLogger('warn'), Repository gets ConsoleLogger('debug')
+     * ```
+     */
+    build(): ProtopediaInMemoryRepository;
+    /**
+     * Creates a PrototypeInMemoryStore instance with detailed error handling.
+     *
+     * @param config - Store configuration
+     * @param repositoryLogger - Logger instance for error reporting
+     * @returns Initialized store instance
+     * @throws {ConfigurationError} When store configuration is invalid
+     * @throws {DataSizeExceededError} When snapshot data exceeds size limit
+     * @throws {SizeEstimationError} When snapshot size estimation fails
+     * @throws {StoreError} When other store-related errors occur
+     * @throws {unknown} When the store constructor throws an unexpected error
+     *
+     * @remarks
+     * On failure, this method logs via the repository logger (if `logger.error`
+     * is a function) and rethrows the original error.
+     *
+     * @internal This method is private and intended for internal use and testing only
+     */
+    private buildStore;
+    /**
+     * Creates a ProtopediaApiCustomClient instance with detailed error handling.
+     *
+     * @param config - API client configuration
+     * @param repositoryLogger - Logger instance for error reporting
+     * @returns Initialized API client instance
+     * @throws {unknown} When API client construction fails
+     *
+     * @remarks
+     * On failure, this method logs via the repository logger (if `logger.error`
+     * is a function) and rethrows the original error.
+     *
+     * @internal This method is private and intended for internal use and testing only
+     */
+    private buildApiClient;
+}
+//# sourceMappingURL=builder.d.ts.map

package/dist/builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builder.d.ts","sourceRoot":"","sources":["../lib/builder.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,0BAA0B,CAAC;AAG3E,OAAO,EACL,yBAAyB,EACzB,KAAK,+BAA+B,EACrC,MAAM,oBAAoB,CAAC;AAI5B,OAAO,KAAK,EACV,4BAA4B,EAC5B,kCAAkC,EAClC,uBAAuB,EACxB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAML,KAAK,sBAAsB,EAC3B,KAAK,4BAA4B,EAClC,MAAM,kBAAkB,CAAC;AAI1B,YAAY,EAEV,4BAA4B,EAC5B,sBAAsB,EAGtB,yBAAyB,EACzB,+BAA+B,EAE/B,0BAA0B,EAG1B,4BAA4B,EAC5B,kCAAkC,EAClC,uBAAuB,GACxB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,qBAAa,yBAAyB;;IAMpC;;;;;;;;OAQG;IACH,cAAc,CAAC,MAAM,EAAE,4BAA4B,GAAG,IAAI;IAK1D;;;;;;;;;OASG;IACH,kBAAkB,CAAC,MAAM,EAAE,+BAA+B,GAAG,IAAI;IAKjE;;;;;;;;OAQG;IACH,mBAAmB,CAAC,MAAM,EAAE,kCAAkC,GAAG,IAAI;IAKrE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAwCG;IACH,KAAK,IAAI,4BAA4B;IA2DrC;;;;;;;;;;;;;;;;;OAiBG;IACH,OAAO,CAAC,UAAU;IAiClB;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,cAAc;CAiBvB"}

package/dist/builder.js

@@ -0,0 +1,255 @@
+/**
+ * Builder for creating Promidas repository instances.
+ *
+ * This module provides a fluent builder interface for constructing
+ * {@link ProtopediaInMemoryRepository} instances.
+ *
+ * @module
+ */
+// Logger types
+import { ProtopediaApiCustomClient, } from './fetcher/index.js';
+import { ConsoleLogger } from './logger/console-logger.js';
+import { ProtopediaInMemoryRepositoryImpl } from './repository/protopedia-in-memory-repository.js';
+import { ConfigurationError, DataSizeExceededError, PrototypeInMemoryStore, SizeEstimationError, StoreError, } from './store/index.js';
+import { deepMerge, sanitizeDataForLogging } from './utils/index.js';
+/**
+ * A builder class for constructing {@link ProtopediaInMemoryRepository} instances.
+ *
+ * It allows for step-by-step configuration of Store, API Client, and Repository settings
+ * through a fluent interface.
+ *
+ * @remarks
+ * **Logger Configuration:**
+ * Each component (Store, API Client, Repository) receives an independent logger instance.
+ * - If you provide a custom logger, it will be used as-is
+ * - If you don't provide a logger, a new ConsoleLogger is created with the specified logLevel (default: 'info')
+ * - Each component can have different loggers and log levels for maximum flexibility
+ *
+ * @example
+ * ```typescript
+ * // Basic usage with default settings (each component gets independent logger)
+ * const repo = new PromidasRepositoryBuilder().build();
+ *
+ * // Configure store settings
+ * const repo = new PromidasRepositoryBuilder()
+ *   .setStoreConfig({ ttlMs: 60000 })
+ *   .setApiClientConfig({
+ *     protoPediaApiClientOptions: { token: 'my-token' }
+ *   })
+ *   .build();
+ *
+ * // Different log levels for each component
+ * const repo = new PromidasRepositoryBuilder()
+ *   .setStoreConfig({ logLevel: 'error' })
+ *   .setApiClientConfig({ logLevel: 'warn' })
+ *   .setRepositoryConfig({ logLevel: 'debug' })
+ *   .build();
+ * ```
+ */
+export class PromidasRepositoryBuilder {
+    // Configs
+    #storeConfig = {};
+    #apiClientConfig = {};
+    #repositoryConfig = {};
+    /**
+     * Set configuration for the in-memory store.
+     *
+     * Multiple calls will merge configurations (later values override earlier ones).
+     * Configuration is deeply merged to prevent external mutations while preserving
+     * function references (e.g., logger methods).
+     *
+     * @param config - Store configuration (TTL, max size, logger, etc.)
+     */
+    setStoreConfig(config) {
+        this.#storeConfig = deepMerge(this.#storeConfig, config);
+        return this;
+    }
+    /**
+     * Set configuration for the ProtopediaApiCustomClient wrapper.
+     * Allows configuring the logger used by the client wrapper itself.
+     *
+     * Multiple calls will merge configurations (later values override earlier ones).
+     * Configuration is deeply merged to prevent external mutations while preserving
+     * function references (e.g., logger methods).
+     *
+     * @param config - Wrapper configuration (logger, logLevel)
+     */
+    setApiClientConfig(config) {
+        this.#apiClientConfig = deepMerge(this.#apiClientConfig, config);
+        return this;
+    }
+    /**
+     * Set configuration for the Repository itself.
+     *
+     * Multiple calls will merge configurations (later values override earlier ones).
+     * Configuration is deeply merged to prevent external mutations while preserving
+     * function references (e.g., logger methods).
+     *
+     * @param config - Repository configuration (logger, etc.)
+     */
+    setRepositoryConfig(config) {
+        this.#repositoryConfig = deepMerge(this.#repositoryConfig, config);
+        return this;
+    }
+    /**
+     * Build and return a fully configured ProtopediaInMemoryRepository instance.
+     *
+     * This method creates new instances of dependencies (Store, API Client)
+     * based on the accumulated configuration.
+     *
+     * @remarks
+     * **Logger Creation:**
+     * When no explicit logger is provided in a component's configuration, Builder
+     * creates a new ConsoleLogger instance with the specified logLevel (default: 'info').
+     * Each component receives an independent logger instance unless you explicitly
+     * share a logger by passing the same logger instance to multiple configs.
+     *
+     * **Configuration Immutability:**
+     * Configurations are deep-merged to prevent external mutations from affecting
+     * the builder's internal state.
+     *
+     * **Failure Logging:**
+     * When construction fails, this method logs the failure via the repository
+     * logger (if `logger.error` is a function) and rethrows the original error.
+     *
+     * @returns A fully configured ProtopediaInMemoryRepository instance
+     * @throws {ConfigurationError} When store configuration is invalid
+     * @throws {DataSizeExceededError} When snapshot data exceeds size limit
+     * @throws {SizeEstimationError} When snapshot size estimation fails
+     * @throws {StoreError} When store initialization fails
+     * @throws {unknown} When API client or repository construction fails
+     *
+     * @example
+     * ```typescript
+     * // Build with default settings (each component gets independent logger with 'info' level)
+     * const repo = new PromidasRepositoryBuilder().build();
+     *
+     * // Build with different log levels
+     * const repo = new PromidasRepositoryBuilder()
+     *   .setStoreConfig({ ttlMs: 60000, logLevel: 'warn' })
+     *   .setRepositoryConfig({ logLevel: 'debug' })
+     *   .build();
+     * // Result: Store gets ConsoleLogger('warn'), Repository gets ConsoleLogger('debug')
+     * ```
+     */
+    build() {
+        // Design Decision: Builder ensures logger instance exists
+        //
+        // Why Builder creates loggers instead of delegating to modules:
+        // 1. Responsibility clarity: Builder guarantees logger presence
+        // 2. Loose coupling: Reduces dependency on module's logger creation logic
+        // 3. Consistency: Uniform logger creation strategy across all components
+        //
+        // Alternative (simpler but more coupled):
+        //   Just pass config as-is: new PrototypeInMemoryStore(this.#storeConfig)
+        //   Modules would handle logger creation internally
+        //   Trade-off: Tighter coupling to module implementation details
+        const storeConfig = {
+            ...this.#storeConfig,
+            logger: this.#storeConfig.logger ??
+                new ConsoleLogger(this.#storeConfig.logLevel ?? 'info'),
+        };
+        const apiClientConfig = {
+            ...this.#apiClientConfig,
+            logger: this.#apiClientConfig.logger ??
+                new ConsoleLogger(this.#apiClientConfig.logLevel ?? 'info'),
+        };
+        // Ensure logger exists before constructing repository config
+        const repositoryLogger = this.#repositoryConfig.logger ??
+            new ConsoleLogger(this.#repositoryConfig.logLevel ?? 'info');
+        const repositoryConfig = {
+            ...this.#repositoryConfig,
+            logger: repositoryLogger,
+        };
+        // Build Store and API Client
+        const store = this.buildStore(storeConfig, repositoryLogger);
+        const apiClient = this.buildApiClient(apiClientConfig, repositoryLogger);
+        // Build Repository
+        try {
+            return new ProtopediaInMemoryRepositoryImpl({
+                store,
+                apiClient,
+                repositoryConfig,
+            });
+        }
+        catch (error) {
+            // Handle Repository construction errors
+            if (typeof repositoryLogger.error === 'function') {
+                repositoryLogger.error('Failed to create ProtopediaInMemoryRepositoryImpl', sanitizeDataForLogging({ error }));
+            }
+            throw error;
+        }
+    }
+    /**
+     * Creates a PrototypeInMemoryStore instance with detailed error handling.
+     *
+     * @param config - Store configuration
+     * @param repositoryLogger - Logger instance for error reporting
+     * @returns Initialized store instance
+     * @throws {ConfigurationError} When store configuration is invalid
+     * @throws {DataSizeExceededError} When snapshot data exceeds size limit
+     * @throws {SizeEstimationError} When snapshot size estimation fails
+     * @throws {StoreError} When other store-related errors occur
+     * @throws {unknown} When the store constructor throws an unexpected error
+     *
+     * @remarks
+     * On failure, this method logs via the repository logger (if `logger.error`
+     * is a function) and rethrows the original error.
+     *
+     * @internal This method is private and intended for internal use and testing only
+     */
+    buildStore(config, repositoryLogger) {
+        try {
+            return new PrototypeInMemoryStore(config);
+        }
+        catch (error) {
+            // Handle Store construction errors (e.g., ConfigurationError)
+            if (typeof repositoryLogger.error === 'function') {
+                // Build detailed error information based on error type
+                let errorDetails;
+                if (error instanceof StoreError) {
+                    errorDetails = { error, dataState: error.dataState };
+                    if (error instanceof DataSizeExceededError) {
+                        errorDetails.dataSizeBytes = error.dataSizeBytes;
+                        errorDetails.maxDataSizeBytes = error.maxDataSizeBytes;
+                    }
+                    else if (error instanceof SizeEstimationError) {
+                        errorDetails.cause = error.cause;
+                    }
+                }
+                else {
+                    errorDetails = { error };
+                }
+                repositoryLogger.error('Failed to create PrototypeInMemoryStore', sanitizeDataForLogging(errorDetails));
+            }
+            throw error;
+        }
+    }
+    /**
+     * Creates a ProtopediaApiCustomClient instance with detailed error handling.
+     *
+     * @param config - API client configuration
+     * @param repositoryLogger - Logger instance for error reporting
+     * @returns Initialized API client instance
+     * @throws {unknown} When API client construction fails
+     *
+     * @remarks
+     * On failure, this method logs via the repository logger (if `logger.error`
+     * is a function) and rethrows the original error.
+     *
+     * @internal This method is private and intended for internal use and testing only
+     */
+    buildApiClient(config, repositoryLogger) {
+        try {
+            return new ProtopediaApiCustomClient(config);
+        }
+        catch (error) {
+            // Handle API client construction errors
+            if (typeof repositoryLogger.error === 'function') {
+                repositoryLogger.error('Failed to create ProtopediaApiCustomClient', sanitizeDataForLogging({ error }));
+            }
+            throw error;
+        }
+    }
+}
+//# sourceMappingURL=builder.js.map

package/dist/builder.js.map

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