### Copy Environment Variables Example (Bash)

Source: https://github.com/f88/promidas/blob/main/DEVELOPMENT.md

Copies the example environment variables file to a new file for local configuration. This is the first step in setting up the development environment.

```bash
cp .env.example .env

```

--------------------------------

### Install Project Dependencies (Bash)

Source: https://github.com/f88/promidas/blob/main/DEVELOPMENT.md

Installs project dependencies using npm. `npm ci` is recommended for clean and consistent installations, especially in CI/CD environments, as it uses the `package-lock.json` file.

```bash
npm ci

```

--------------------------------

### Copy Test Environment Variables Example (Bash)

Source: https://github.com/f88/promidas/blob/main/DEVELOPMENT.md

Copies the example environment variables file to a new file specifically for the test environment. This allows for separate configuration for testing purposes.

```bash
cp .env.example .env.test

```

--------------------------------

### Run Demo Script (Bash)

Source: https://github.com/f88/promidas/blob/main/DEVELOPMENT.md

Executes a demo script using `tsx` to experiment with the repository API. This is a practical way to verify the setup and explore functionality.

```bash
npx tsx scripts/try-protopedia-repository.ts

```

--------------------------------

### Build Project (Bash)

Source: https://github.com/f88/promidas/blob/main/DEVELOPMENT.md

Compiles the project, generating production-ready artifacts.

```bash
npm run build
```

--------------------------------

### Initialize Fetcher Client with Logger (TypeScript)

Source: https://github.com/f88/promidas/blob/main/lib/logger/docs/USAGE.md

This example shows how to initialize the `ProtopediaApiCustomClient` from 'promidas/fetcher' with a console logger. It demonstrates passing logger options and a log level during client instantiation.

```typescript
import { ProtopediaApiCustomClient } from 'promidas/fetcher';
import { createConsoleLogger } from 'promidas/logger';

const logger = createConsoleLogger();

const client = new ProtopediaApiCustomClient({
    protoPediaApiClientOptions: {
        token: process.env.PROTOPEDIA_API_V2_TOKEN ?? 'no-token',
    },
    logger,
    logLevel: 'info',
});
```

--------------------------------

### Run Test Suite (Bash)

Source: https://github.com/f88/promidas/blob/main/DEVELOPMENT.md

Executes the project's test suite using npm. This command verifies the installation and configuration of the development environment. API calls are typically mocked during tests.

```bash
npm test

```

--------------------------------

### Run All Tests (Bash)

Source: https://github.com/f88/promidas/blob/main/DEVELOPMENT.md

Executes the entire test suite for the project.

```bash
npm test
```

--------------------------------

### Protopedia API Custom Client Event Handler Examples (TypeScript)

Source: https://github.com/f88/promidas/blob/main/lib/fetcher/docs/DESIGN_PROGRESS.md

Provides examples of how to use the `progressCallback` in the Protopedia API custom client to handle different progress events. Examples include simple logging, custom UI updates, and combining logging with analytics tracking.

```typescript
// Example 1: Simple progress logging
const client = new ProtopediaApiCustomClient({
    progressLog: true, // Uses default logger output
});

// Example 2: Custom event handler
const client = new ProtopediaApiCustomClient({
    progressLog: false,
    progressCallback: (event) => {
        switch (event.type) {
            case 'request-start':
                console.log('Request initiated');
                break;
            case 'response-received':
                console.log(`Headers received in ${event.prepareTimeMs}ms`);
                break;
            case 'download-progress':
                updateProgressBar(event.percentage);
                break;
            case 'complete':
                console.log(`Download complete in ${event.totalTimeMs}ms`);
                break;
            case 'error':
                console.error(`Download failed: ${event.error}`);
                break;
        }
    },
});

// Example 3: Combined logging and custom handler
const client = new ProtopediaApiCustomClient({
    progressLog: true, // Logs to stderr
    progressCallback: (event) => {
        // Also send to analytics
        if (event.type === 'complete') {
            analytics.track('download-complete', {
                bytes: event.received,
                duration: event.totalTimeMs,
            });
        }
    },
});
```

--------------------------------

### Cross-Reference Example (DESIGN to USAGE)

Source: https://github.com/f88/promidas/blob/main/DOCUMENTATION.md

Illustrates linking from DESIGN.md to USAGE.md to provide practical examples for concepts discussed in the design document, such as common patterns.

```markdown
For practical examples, see [USAGE.md](USAGE.md#common-patterns).
```

--------------------------------

### Conventional Commits Format Example

Source: https://github.com/f88/promidas/blob/main/CONTRIBUTING.md

Illustrates the structure of a commit message following the Conventional Commits specification. Includes type, scope, subject, body, and footer for breaking changes.

```text
<type>(<scope>): <subject>

<body>

<footer>

feat(api)!: remove deprecated endpoints

BREAKING CHANGE: All v1 API endpoints have been removed.
```

--------------------------------

### Project Structure Overview

Source: https://github.com/f88/promidas/blob/main/DEVELOPMENT.md

Provides a hierarchical view of the project's directories and their purposes, including source code, documentation, scripts, tests, and CI/CD configurations.

```text
lib/                      # Source code
  ├── types/             # Shared type definitions and prototypes
  ├── utils/             # Utility functions (converters, time, deep-merge)
  ├── logger/            # Logger interface and console implementation
  ├── fetcher/           # API client and data fetching logic
  ├── store/             # In-memory data store
  ├── repository/        # Repository pattern implementation
  ├── builder.ts         # Builder pattern API for constructing stores
  └── factory.ts         # Factory functions for common use cases
docs/                     # VitePress documentation site
  ├── index.md           # Documentation home
  ├── features/          # Feature documentation
  └── use-cases/          # Usage examples by scenario
scripts/                  # Utility scripts
  ├── generate-version.mjs  # Version generation for builds
  └── try-*.ts           # Demo/trial scripts
__tests__/               # Integration and cross-module tests
.github/workflows/       # CI/CD GitHub Actions workflows

```

--------------------------------

### Check Formatting (Bash)

Source: https://github.com/f88/promidas/blob/main/DEVELOPMENT.md

Verifies that the code adheres to the project's formatting standards.

```bash
npm run format:check
```

--------------------------------

### Cross-Reference Example (README to DESIGN)

Source: https://github.com/f88/promidas/blob/main/DOCUMENTATION.md

Demonstrates how to link from a README.md file to a DESIGN.md file for detailed design specifications, using Markdown syntax.

```markdown
詳細な設計仕様については [DESIGN.md](docs/DESIGN.md) を参照してください。
```

--------------------------------

### Integrate Winston Logger with Promidas (TypeScript)

Source: https://github.com/f88/promidas/blob/main/lib/logger/docs/USAGE.md

This example shows how to integrate the Winston logging library with Promidas by creating a Promidas-compatible logger object. It configures Winston to log to a file and maps Winston's methods to the Promidas Logger interface.

```typescript
import type { Logger } from 'promidas/logger';
import winston from 'winston';

const winstonLogger = winston.createLogger({
    level: 'info',
    format: winston.format.json(),
    transports: [new winston.transports.File({ filename: 'app.log' })],
});

const logger: Logger = {
    debug: (msg, meta) => winstonLogger.debug(msg, meta),
    info: (msg, meta) => winstonLogger.info(msg, meta),
    warn: (msg, meta) => winstonLogger.warn(msg, meta),
    error: (msg, meta) => winstonLogger.error(msg, meta),
};
```

--------------------------------

### Install PROMIDAS Package

Source: https://context7.com/f88/promidas/llms.txt

Installs the PROMIDAS library using npm. This command requires Node.js version 22 or higher to be installed on your system.

```bash
npm install promidas
```

--------------------------------

### Error Handling Example (GOOD - Linked Design)

Source: https://github.com/f88/promidas/blob/main/DOCUMENTATION.md

Presents a recommended approach for documenting error handling in USAGE.md by linking to the design rationale in DESIGN.md and providing only practical usage examples.

```markdown
## Error Handling

For error handling design rationale, see [DESIGN.md](DESIGN.md#error-handling-design).

try {
// practical usage example only
const result = api.fetch();
} catch (error) {
// handle error
}
```

--------------------------------

### Clean Project Before Build (Bash)

Source: https://github.com/f88/promidas/blob/main/DEVELOPMENT.md

Removes build artifacts and temporary files to ensure a clean build environment.

```bash
npm run clean
```

--------------------------------

### Cross-Reference Example (USAGE to DESIGN)

Source: https://github.com/f88/promidas/blob/main/DOCUMENTATION.md

Shows how to reference specific sections within DESIGN.md from USAGE.md, particularly for design rationale like error handling.

```markdown
For design rationale, see [DESIGN.md](DESIGN.md#error-handling-design).
```

--------------------------------

### Run Tests in UI Mode (Bash)

Source: https://github.com/f88/promidas/blob/main/DEVELOPMENT.md

Launches tests in an interactive user interface, allowing for more dynamic test exploration and debugging.

```bash
npm run test:ui
```

--------------------------------

### Run Tests with Coverage (Bash)

Source: https://github.com/f88/promidas/blob/main/DEVELOPMENT.md

Executes all tests and generates a code coverage report, indicating which parts of the codebase are tested.

```bash
npm run test:coverage
```

--------------------------------

### Handle Snapshot Started Event

Source: https://github.com/f88/promidas/blob/main/lib/repository/docs/USAGE.md

Subscribes to the `snapshotStarted` event, which is emitted when a snapshot operation begins. This handler logs the operation type and sets a loading state.

```typescript
repo.events?.on('snapshotStarted', (operation: 'setup' | 'refresh') => {
    console.log(`${operation} operation started`);
    setLoading(true);
});
```

--------------------------------

### Pre-Pull Request Checklist

Source: https://github.com/f88/promidas/blob/main/CONTRIBUTING.md

A checklist of commands and checks to ensure code quality, test coverage, linting, formatting, type checking, and successful build before submitting a pull request.

```text
- [ ] All tests pass (`npm test`)
- [ ] Exports tests pass (`npm run test:exports`)
- [ ] Performance tests pass (`npm run test:perf`)
- [ ] Linter passes (`npm run lint`)
- [ ] Formatting passes (`npm run format:check`)
- [ ] Type checking passes (`npm run typecheck`)
- [ ] Build succeeds (`npm run build`)
- [ ] Commit messages follow Conventional Commits format
```

--------------------------------

### Populate Initial Snapshot (TypeScript)

Source: https://github.com/f88/promidas/blob/main/lib/repository/docs/USAGE.md

Shows how to call `setupSnapshot` to populate the in-memory repository with prototypes. It includes error handling for the asynchronous operation, logging success or failure details.

```typescript
const result = await repo.setupSnapshot({ offset: 0, limit: 10 });

if (result.ok) {
    console.log('Setup successful, cached:', result.stats.size);
} else {
    console.error('Setup failed:', result.message);
    if (result.origin === 'fetcher' && result.status) {
        console.error('HTTP status:', result.status);
    }
    // Handle error appropriately
}
```

--------------------------------

### Pull Request Title Examples

Source: https://github.com/f88/promidas/blob/main/CONTRIBUTING.md

Examples of pull request titles following the Conventional Commits format, indicating the type of change and scope.

```text
feat(store): add new caching strategy
fix(fetcher): handle network timeout correctly
docs: update installation guide
```

--------------------------------

### Basic Fetch Example with ProtopediaApiCustomClient

Source: https://github.com/f88/promidas/blob/main/lib/fetcher/docs/USAGE.md

Demonstrates how to initialize ProtopediaApiCustomClient and fetch prototypes. It shows how to handle successful responses and errors, logging the number of fetched prototypes and their names/tags.

```typescript
import { ProtopediaApiCustomClient } from 'promidas/fetcher';

const client = new ProtopediaApiCustomClient({
    protoPediaApiClientOptions: {
        token: process.env.PROTOPEDIA_API_V2_TOKEN ?? 'no-token',
    },
});

const result = await client.fetchPrototypes({ limit: 10 });

if (result.ok) {
    console.log(`Fetched ${result.data.length} prototypes`);
    result.data.forEach((prototype) => {
        console.log(prototype.name, prototype.tags);
    });
} else {
    console.error('Fetch failed:', result.error, result.status);
}
```

--------------------------------

### Initialize Data Cache with setupSnapshot()

Source: https://context7.com/f88/promidas/llms.txt

Demonstrates the `setupSnapshot()` method for fetching and caching data from the ProtoPedia API. It handles success cases by logging statistics and provides detailed error handling for fetcher, store, or unknown errors, including specific checks for API token validity.

```typescript
import { createPromidasForLocal } from 'promidas';

const repo = createPromidasForLocal({
    protopediaApiToken: process.env.PROTOPEDIA_API_V2_TOKEN ?? 'no-token',
});

// Fetch and cache up to 1000 prototypes
const result = await repo.setupSnapshot({ limit: 1000 });

if (result.ok) {
    console.log(`Success: ${result.stats.size} prototypes loaded`);
    console.log(`Data size: ${result.stats.dataSizeBytes} bytes`);
    console.log(`Cached at: ${result.stats.cachedAt}`);
} else {
    // Handle different error types
    switch (result.origin) {
        case 'fetcher':
            console.error(`API Error: ${result.message}`);
            console.error(`Kind: ${result.kind}, Code: ${result.code}`);
            if (result.status === 401) {
                console.error('Invalid API token');
            }
            break;
        case 'store':
            console.error(`Store Error: ${result.message}`);
            console.error(`Data state: ${result.dataState}`);
            break;
        case 'unknown':
            console.error(`Unknown Error: ${result.message}`);
            break;
    }
}
```

--------------------------------

### Use Object Metadata for Structured Logging (TypeScript)

Source: https://github.com/f88/promidas/blob/main/lib/logger/docs/USAGE.md

This example demonstrates the best practice of using structured metadata objects for logging instead of string interpolation. It contrasts a 'bad' example using template literals with a 'good' example passing an object with relevant properties.

```typescript
// ❌ Bad:
logger.info(`User ${userId} performed ${action}`); // String interpolation

// ✅ Good:
logger.info('User action', { userId, action }); // Structured metadata
```

--------------------------------

### Quick Repository Setup with Factory Functions

Source: https://context7.com/f88/promidas/llms.txt

Demonstrates setting up PROMIDAS repositories for local development and server environments using factory functions. `createPromidasForLocal` is for development with verbose logging and longer timeouts, while `createPromidasForServer` is for production with minimal logging. Both require a ProtoPedia API token, typically provided via environment variables.

```typescript
import { createPromidasForLocal, createPromidasForServer } from 'promidas';

// For local development: 30min TTL, 90s timeout, verbose logging
const localRepo = createPromidasForLocal({
    protopediaApiToken: process.env.PROTOPEDIA_API_V2_TOKEN ?? 'no-token',
    logLevel: 'info', // optional, default: 'info'
});

// For server/production: 10min TTL, 30s timeout, minimal logging
// Requires PROTOPEDIA_API_V2_TOKEN environment variable
const serverRepo = createPromidasForServer({
    logLevel: 'warn', // optional, default: 'warn'
});

// Setup snapshot and use
const result = await localRepo.setupSnapshot({ limit: 1000 });
if (result.ok) {
    console.log(`Loaded ${result.stats.size} prototypes`);
    const allData = await localRepo.getAllFromSnapshot();
    console.log(`First prototype: ${allData[0].prototypeNm}`);
}
```

--------------------------------

### Configure Logger Based on Environment (TypeScript)

Source: https://github.com/f88/promidas/blob/main/lib/logger/docs/USAGE.md

This code illustrates how to configure logger settings dynamically based on environment variables. It shows a 'bad' example with hardcoded settings and a 'good' example that determines the log level based on NODE_ENV and a DEBUG flag.

```typescript
// ❌ Bad:
const logger = createConsoleLogger(); // No environment consideration
logger.level = 'debug'; // Hardcoded

// ✅ Good:
const logger = createConsoleLogger();
const level =
    process.env.NODE_ENV === 'production'
        ? 'error'
        : process.env.DEBUG
          ? 'debug'
          : 'info';
logger.level = level;
```

--------------------------------

### Fork Repository using GitHub CLI

Source: https://github.com/f88/promidas/blob/main/CONTRIBUTING.md

This command forks the specified repository and clones it locally. It requires the GitHub CLI to be installed and authenticated.

```bash
gh repo fork F88/promidas --clone
```

--------------------------------

### Include Contextual Metadata in Logs (TypeScript)

Source: https://github.com/f88/promidas/blob/main/lib/logger/docs/USAGE.md

This snippet highlights the importance of including contextual metadata in log messages. It shows a 'bad' example with a generic error message and a 'good' example that includes relevant details like URL, method, status code, and duration.

```typescript
// ❌ Bad:
logger.error('Request failed');

// ✅ Good:
logger.error('Request failed', {
    url: request.url,
    method: request.method,
    statusCode: response.status,
    duration: Date.now() - startTime,
});
```

--------------------------------

### Initialize Protopedia API Custom Client with Progress Tracking (TypeScript)

Source: https://github.com/f88/promidas/blob/main/lib/fetcher/docs/DESIGN_PROGRESS.md

Initializes the Protopedia API custom client, creating a customized fetch instance with progress tracking capabilities. It accepts an optional configuration object for customizing logging, callbacks, and other fetch options. The clientFetch is then passed to the SDK client.

```typescript
constructor(config?: ProtopediaApiCustomClientConfig | null) {
    const {
        progressLog = true,
        progressCallback,
        // ... other config
    } = config ?? {};

    // Create customized fetch with progress tracking
    const clientFetch = createClientFetch({
        logger: this.#logger,
        enableProgressLog: progressLog,
        progressCallback, // Single event handler function
        timeoutMs,
        providedFetch,
        stripHeaders, // Browser compatibility
    });

    // Pass to SDK client
    this.#client = createProtoPediaClient({
        ...sdkOptions,
        fetch: clientFetch,
    });
}
```

--------------------------------

### Basic Download Progress Tracking with Automatic Logging (TypeScript)

Source: https://github.com/f88/promidas/blob/main/lib/fetcher/docs/USAGE.md

This example shows how to use the ProtopediaApiCustomClient for fetching prototypes with automatic download progress logging. Progress information is sent to stderr when the logger level permits, and the `progressLog` option is enabled.

```typescript
import { ProtopediaApiCustomClient } from 'promidas/fetcher';

const client = new ProtopediaApiCustomClient({
    protoPediaApiClientOptions: {
        token: process.env.PROTOPEDIA_API_V2_TOKEN ?? 'no-token',
    },
    logLevel: 'info', // Progress logs appear at 'info' level
    progressLog: true, // Default: enabled
});

const result = await client.fetchPrototypes({ limit: 10000 });
// stderr output:
// [INFO] Request starting...
// [INFO] Response received (50ms) - 2670000 bytes (estimated), limit=10000
// Download complete: 2670000 bytes received (estimated 2670000 bytes) in 1230ms (total: 1280ms)
```

--------------------------------

### Use Appropriate Log Levels (TypeScript)

Source: https://github.com/f88/promidas/blob/main/lib/logger/docs/USAGE.md

This example illustrates the best practice of using appropriate log levels. It contrasts incorrect usage (e.g., using 'error' for non-failures) with correct usage, emphasizing the distinction between diagnostic messages and actual errors.

```typescript
// ❌ Bad:
logger.error('Cache hit'); // error is for failures
logger.debug('Database connection failed'); // critical errors should be error level

// ✅ Good:
logger.debug('Cache hit'); // diagnostic info
logger.error('Database connection failed', { error: err }); // actual error
```

--------------------------------

### Creating and Using Console Logger Instances in TypeScript

Source: https://github.com/f88/promidas/blob/main/lib/logger/docs/USAGE.md

Demonstrates how to create instances of the console logger, including setting the initial log level. It also shows how to log messages with different types of metadata, such as objects, primitives, or no metadata.

```typescript
import { createConsoleLogger } from 'promidas/logger';

// Default level is 'info'
const logger1 = createConsoleLogger();

// Set level after creation
const logger2 = createConsoleLogger();
logger2.level = 'debug';

const logger3 = createConsoleLogger();
logger3.level = 'error';

// Object Metadata (recommended):
logger.info('User action', {
    userId: 123,
    action: 'login',
    timestamp: new Date().toISOString(),
});
// Console: "[INFO] User action" { userId: 123, action: 'login', timestamp: '...' }

// Primitive Metadata:
logger.error('Request failed', 500);
// Console: "[ERROR] Request failed" 500

// No Metadata:
logger.warn('Cache miss');
// Console: "[WARN] Cache miss"
```

--------------------------------

### Type Guard Example for API Results (TypeScript)

Source: https://github.com/f88/promidas/blob/main/lib/fetcher/docs/DESIGN.md

An example demonstrating the use of type guards in TypeScript to handle discriminated unions returned by an API client. This allows TypeScript to infer the type of the data or error, eliminating the need for manual runtime type checking.

```typescript
const result = await client.fetchPrototypes(params);

if (result.ok) {
    // TypeScript knows: result.data is NormalizedPrototype[]
    result.data.forEach((prototype) => {
        console.log(prototype.name);
    });
} else {
    // TypeScript knows: result.error is string, result.status may exist
    console.error(result.error, result.status);
}
```

--------------------------------

### Configure Promidas Client Logger with Fastify-Style Options (TypeScript)

Source: https://github.com/f88/promidas/blob/main/lib/fetcher/docs/USAGE.md

Demonstrates three patterns for configuring the logger for ProtopediaApiCustomClient, adhering to Fastify-style logger configurations. It shows how to initialize the client with only a log level, with a pre-created console logger and a log level, or with a custom logger instance that dictates the log level.

```typescript
import { createConsoleLogger } from 'promidas/logger';
import { ProtopediaApiCustomClient } from 'promidas/fetcher';

// Pattern 1: logLevel only (creates ConsoleLogger internally)
const client1 = new ProtopediaApiCustomClient({
    protoPediaApiClientOptions: {
        token: process.env.PROTOPEDIA_API_V2_TOKEN ?? 'no-token',
    },
    logLevel: 'debug',
});

// Pattern 2: Custom logger with logLevel
const logger = createConsoleLogger();
const client2 = new ProtopediaApiCustomClient({
    protoPediaApiClientOptions: {
        token: process.env.PROTOPEDIA_API_V2_TOKEN ?? 'no-token',
    },
    logger,
    logLevel: 'debug', // Updates logger's level if mutable
});

// Pattern 3: Custom logger only
const client3 = new ProtopediaApiCustomClient({
    protoPediaApiClientOptions: {
        token: process.env.PROTOPEDIA_API_V2_TOKEN ?? 'no-token',
    },
    logger, // Uses logger's existing level
});
```

--------------------------------

### Configure Logger Levels with Promidas

Source: https://github.com/f88/promidas/blob/main/lib/fetcher/docs/USAGE.md

Demonstrates how to set different logger levels for the Protopedia API client. It shows examples for verbose logging ('debug'), minimal logging ('error'), and silent logging using a no-operation logger.

```typescript
import { createConsoleLogger, createNoopLogger } from 'promidas/logger';

// Development - verbose logging
const client = new ProtopediaApiCustomClient({
    protoPediaApiClientOptions: {
        token: process.env.PROTOPEDIA_API_V2_TOKEN ?? 'no-token',
    },
    logLevel: 'debug',
});

// Production - minimal logging
const prodClient = new ProtopediaApiCustomClient({
    protoPediaApiClientOptions: {
        token: process.env.PROTOPEDIA_API_V2_TOKEN ?? 'no-token',
    },
    logLevel: 'error',
});

// Testing - silent logger
const testClient = new ProtopediaApiCustomClient({
    protoPediaApiClientOptions: {
        token: process.env.PROTOPEDIA_API_V2_TOKEN ?? 'no-token',
    },
    logger: createNoopLogger(),
});
```

--------------------------------

### Auto-fix Formatting (Bash)

Source: https://github.com/f88/promidas/blob/main/DEVELOPMENT.md

Automatically formats the code according to the project's standards.

```bash
npm run format
```

--------------------------------

### Protopedia API Custom Client Initialization (TypeScript)

Source: https://github.com/f88/promidas/blob/main/lib/fetcher/docs/DESIGN.md

This TypeScript code snippet shows how to instantiate the `ProtopediaApiCustomClient` with custom configurations, including API client options and logging level. It demonstrates providing a token, base URL, and setting a specific log level for the client.

```typescript
// Create client with custom configuration
const client = new ProtopediaApiCustomClient({
    protoPediaApiClientOptions: {
        token: process.env.TOKEN,
        baseUrl: 'https://api.protopedia.net',
    },
    logLevel: 'error',
});

// Use client's methods
const result = await client.fetchPrototypes(params);
```

--------------------------------

### Create Mock Store for Integration Tests (TypeScript)

Source: https://github.com/f88/promidas/blob/main/lib/repository/__tests__/protopedia-in-memory-repository/README.md

This snippet demonstrates how to create a mock store instance for integration tests using `createMockStore`. It configures the store with a Time-To-Live (TTL) and sets up a mock API client to simulate fetching prototypes. This is useful for testing end-to-end flows and real store behavior.

```typescript
import { createMockStore, setupMocks } from './test-helpers.js';

describe('Integration tests', () => {
    const { fetchPrototypesMock, resetMocks } = setupMocks();

    beforeEach(() => {
        resetMocks();
    });

    it('should handle full flow', async () => {
        const store = createMockStore({ ttlMs: 30_000 });
        const apiClient = { fetchPrototypes: fetchPrototypesMock };

        const repo = new ProtopediaInMemoryRepositoryImpl({
            store,
            apiClient,
        });

        fetchPrototypesMock.mockResolvedValueOnce({
            ok: true,
            data: [makePrototype({ id: 1 })],
        });

        await repo.setupSnapshot({});
        const result = repo.getById(1);
        expect(result).toBeDefined();
    });
});
```

--------------------------------

### Set Up `.env.test` for Test Environment

Source: https://github.com/f88/promidas/blob/main/DEVELOPMENT.md

Resolve 'PROTOPEDIA_API_V2_TOKEN not found' errors during testing by creating a `.env.test` file. This file is used to configure environment variables for the test suite, even though actual API tokens are not required due to mocking.

```bash
cp .env.example .env.test
# No need to set PROTOPEDIA_API_V2_TOKEN for tests
```

--------------------------------

### Auto-fix Linter Issues (Bash)

Source: https://github.com/f88/promidas/blob/main/DEVELOPMENT.md

Automatically fixes common linter issues, improving code quality and consistency.

```bash
npm run lint:fix
```

--------------------------------

### Run Linter (Bash)

Source: https://github.com/f88/promidas/blob/main/DEVELOPMENT.md

Executes the linter to enforce code quality rules and identify potential issues in the codebase.

```bash
npm run lint
```

--------------------------------

### Setup Test Context for Unit Tests (TypeScript)

Source: https://github.com/f88/promidas/blob/main/lib/repository/__tests__/protopedia-in-memory-repository/README.md

This snippet shows how to use `createTestContext` and `setupMocks` to reduce boilerplate in unit tests. It initializes mocks and a test context, allowing for specific mock behavior overrides within individual tests. This is beneficial for isolating and testing individual units of code.

```typescript
import { createTestContext, setupMocks } from './test-helpers.js';

describe('My unit tests', () => {
    const { fetchPrototypesMock, resetMocks } = setupMocks();
    let testContext;

    beforeEach(() => {
        resetMocks();
        testContext = createTestContext();
    });

    it('should work', async () => {
        const { mockStoreInstance, mockApiClientInstance } = testContext;

        // Override specific behavior for this test
        vi.mocked(mockStoreInstance.getStats).mockReturnValueOnce({
            size: 10,
            cachedAt: new Date(),
            isExpired: false,
            // ...
        });

        const repo = new ProtopediaInMemoryRepositoryImpl({
            store: mockStoreInstance,
            apiClient: mockApiClientInstance,
        });

        // ... test assertions
    });
});
```

--------------------------------

### Debug Tests Matching Pattern (Bash)

Source: https://github.com/f88/promidas/blob/main/DEVELOPMENT.md

Runs tests that match a given pattern, useful for focusing on a subset of tests.

```bash
npm test -- --grep="should handle"
```

--------------------------------

### Check Node.js Version and Upgrade

Source: https://github.com/f88/promidas/blob/main/DEVELOPMENT.md

Ensure the project is running on a compatible Node.js version (20 or later) to avoid runtime errors. This includes checking the current version and upgrading if necessary, particularly when using Node Version Manager (nvm).

```bash
# Check current version
node --version

# Using nvm (Node Version Manager)
nvm install 20
nvm use 20
```

--------------------------------

### Debug Specific Test File (Bash)

Source: https://github.com/f88/promidas/blob/main/DEVELOPMENT.md

Runs a single test file to quickly debug specific test cases.

```bash
npm test -- lib/store/__tests__/store.test.ts
```

--------------------------------

### Run Type Checking (Bash)

Source: https://github.com/f88/promidas/blob/main/DEVELOPMENT.md

Performs static type checking using TypeScript to catch type-related errors before runtime.

```bash
npm run typecheck
```

--------------------------------

### Create Promidas Repository Instance (TypeScript)

Source: https://github.com/f88/promidas/blob/main/lib/repository/docs/USAGE.md

Demonstrates how to create an instance of the Promidas repository using the `createPromidasForLocal` factory function. This is the recommended approach for most use cases, requiring a Protopedia API token.

```typescript
import { createPromidasForLocal } from 'promidas';

const repo = createPromidasForLocal({
    protopediaApiToken: process.env.PROTOPEDIA_API_V2_TOKEN ?? 'no-token',
});
```