promidas 2.0.0

package/dist/repository/types/repository.types.d.ts

@@ -0,0 +1,330 @@
+/**
+ * Type definitions for the ProtoPedia in-memory repository interface.
+ *
+ * @module
+ */
+import type { EventEmitter } from 'events';
+import type { ListPrototypesParams } from 'protopedia-api-v2-client';
+import type { DeepReadonly } from 'ts-essentials';
+import type { Logger, LogLevel } from '../../logger/index.js';
+import type { PrototypeInMemoryStats, PrototypeInMemoryStoreConfig } from '../../store/index.js';
+import type { NormalizedPrototype } from '../../types/index.js';
+import type { PrototypeAnalysisResult } from './analysis.types.js';
+import type { SerializableSnapshot } from './serialization.types.js';
+import type { SnapshotOperationResult } from './snapshot-operation.types.js';
+/**
+ * Configuration options for the ProtoPedia in-memory repository.
+ */
+export type ProtopediaInMemoryRepositoryConfig = {
+    /**
+     * Custom logger instance for repository operations.
+     *
+     * @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 event notifications for snapshot operations.
+     *
+     * When enabled, the repository will create an EventEmitter instance and
+     * emit events during snapshot operations (snapshotStarted, snapshotCompleted, snapshotFailed).
+     *
+     * @remarks
+     * - Events are disabled by default to minimize overhead for CLI/script users
+     * - When enabled, access events via the `events` property
+     * - Always call `dispose()` to clean up event listeners when done
+     * - Designed primarily for WebApp/SPA scenarios
+     *
+     * @default false
+     *
+     * @see {@link RepositoryEvents} for available event types
+     * @see {@link https://github.com/F88/promidas/issues/19 | Issue #19: Event Notification System}
+     */
+    enableEvents?: boolean;
+};
+/**
+ * In-memory, snapshot-based repository for ProtoPedia prototypes.
+ *
+ * This repository hides HTTP and caching details behind a simple
+ * snapshot API:
+ *
+ * - `setupSnapshot` / `refreshSnapshot` populate or update the snapshot
+ *   by calling the ProtoPedia API under the hood.
+ * - Read methods (`getPrototypeFromSnapshotById`,
+ *   `getRandomPrototypeFromSnapshot`) access only the current in-memory
+ *   snapshot and never perform HTTP calls.
+ * - `getStats` exposes enough information (size, cachedAt, isExpired) to
+ *   implement TTL-based refresh strategies in the calling code.
+ */
+export interface ProtopediaInMemoryRepository {
+    /**
+     * Event emitter for snapshot operation notifications.
+     *
+     * This property is only defined when `enableEvents: true` is set in the repository configuration.
+     * Use optional chaining (`events?.on(...)`) to safely access event methods.
+     *
+     * @remarks
+     * **Available Events:**
+     * - `snapshotStarted` - Emitted when setupSnapshot or refreshSnapshot begins
+     * - `snapshotCompleted` - Emitted when snapshot operation succeeds (includes stats)
+     * - `snapshotFailed` - Emitted when snapshot operation fails (includes error details)
+     *
+     * **Cleanup:**
+     * Always call `dispose()` to remove all event listeners and prevent memory leaks.
+     *
+     * @example
+     * ```typescript
+     * const repo = new PromidasRepositoryBuilder()
+     *   .setRepositoryConfig({ enableEvents: true })
+     *   .build();
+     *
+     * repo.events?.on('snapshotCompleted', (stats) => {
+     *   console.log(`Updated: ${stats.size} prototypes`);
+     * });
+     *
+     * // Cleanup
+     * repo.dispose();
+     * ```
+     *
+     * @see {@link RepositoryEvents} for event type definitions
+     * @see {@link dispose} for cleanup method
+     */
+    readonly events?: EventEmitter;
+    /**
+     * Retrieve the configuration used to initialize the underlying store.
+     *
+     * Returns the TTL and maximum data size settings (logger is excluded).
+     */
+    getConfig(): Omit<Required<PrototypeInMemoryStoreConfig>, 'logger'>;
+    /**
+     * Stats for the current snapshot, including TTL-related information.
+     *
+     * Callers can use this to implement strategies such as:
+     * - refreshing when `isExpired` is true, or
+     * - refreshing when `cachedAt` is older than a given threshold.
+     *
+     * This method never throws due to ProtoPedia API failures; it only
+     * reports the current in-memory state.
+     */
+    getStats(): PrototypeInMemoryStats;
+    /**
+     * Fetch prototypes from ProtoPedia and populate the in-memory snapshot.
+     *
+     * Typical usage: call once on startup, or before the first read. The
+     * concrete fetch strategy (all vs partial, page size, filters, etc.) is
+     * an implementation detail of this repository.
+     *
+     * Returns a Result type indicating success with stats or failure with error details.
+     * In case of failure, any existing in-memory snapshot remains unchanged.
+     *
+     * @returns SnapshotOperationResult with ok: true and stats on success,
+     *          or ok: false with error details on failure
+     */
+    setupSnapshot(params: ListPrototypesParams): Promise<SnapshotOperationResult>;
+    /**
+     * Refresh the snapshot using the same parameters as the last successful
+     * {@link ProtopediaInMemoryRepository.setupSnapshot | setupSnapshot} call.
+     *
+     * **Prerequisite**: `setupSnapshot()` must have been called successfully at least once.
+     * If called before `setupSnapshot()`, returns an error with code `REPOSITORY_INVALID_STATE`.
+     *
+     * Returns a Result type indicating success with stats or failure with error details.
+     * In case of failure, the current in-memory snapshot is preserved.
+     *
+     * @returns SnapshotOperationResult with ok: true and stats on success,
+     *          or ok: false with error details on failure
+     */
+    refreshSnapshot(): Promise<SnapshotOperationResult>;
+    /**
+     * Analyze prototypes from the current snapshot to extract ID range.
+     *
+     * Returns the minimum and maximum prototype IDs from the current snapshot.
+     * This method does NOT perform HTTP calls.
+     *
+     * @returns {@link PrototypeAnalysisResult} containing min and max IDs, or null values if snapshot is empty
+     */
+    analyzePrototypes(): Promise<PrototypeAnalysisResult>;
+    /**
+     * Get all prototypes from the current in-memory snapshot.
+     *
+     * Returns all prototypes currently cached in the snapshot.
+     * The returned data is read-only and reflects the state at the time of the call.
+     *
+     * This method does NOT perform HTTP calls.
+     * It does not throw due to ProtoPedia API failures; it only reflects
+     * the current in-memory state of the snapshot.
+     *
+     * @returns Read-only array of all prototypes
+     */
+    getAllFromSnapshot(): Promise<readonly DeepReadonly<NormalizedPrototype>[]>;
+    /**
+     * Get all prototype IDs from the current in-memory snapshot.
+     *
+     * Returns an array of all prototype IDs currently cached in the snapshot.
+     * Useful for operations that only need IDs, such as:
+     * - Exporting available prototype IDs to clients
+     * - ID-based filtering or statistics
+     * - Checking if specific IDs exist without loading full objects
+     *
+     * This method does NOT perform HTTP calls.
+     * It does not throw due to ProtoPedia API failures; it only reflects
+     * the current in-memory state of the snapshot.
+     *
+     * @returns Read-only array of prototype IDs
+     */
+    getPrototypeIdsFromSnapshot(): Promise<readonly number[]>;
+    /**
+     * Get a prototype from the current in-memory snapshot by id.
+     *
+     * Returns the prototype when it exists in the snapshot, or null when
+     * the id is not present in the current snapshot.
+     *
+     * This method does NOT perform HTTP calls.
+     * It does not throw due to ProtoPedia API failures; it only reflects
+     * the current in-memory state of the snapshot.
+     */
+    getPrototypeFromSnapshotByPrototypeId(prototypeId: number): Promise<DeepReadonly<NormalizedPrototype> | null>;
+    /**
+     * Get a random prototype from the current in-memory snapshot.
+     *
+     * Returns a random prototype when the snapshot is not empty, or null
+     * when the snapshot is empty.
+     *
+     * This method does NOT perform HTTP calls.
+     * It does not throw due to ProtoPedia API failures; it only reflects
+     * the current in-memory state of the snapshot.
+     */
+    getRandomPrototypeFromSnapshot(): Promise<DeepReadonly<NormalizedPrototype> | null>;
+    /**
+     * Get random samples from the current in-memory snapshot.
+     *
+     * Returns up to `size` random prototypes without duplicates.
+     * If `size` exceeds the available data, returns all prototypes in random order.
+     * Returns an empty array when `size <= 0` or when the snapshot is empty.
+     *
+     * This method does NOT perform HTTP calls.
+     * It does not throw due to ProtoPedia API failures; it only reflects
+     * the current in-memory state of the snapshot.
+     *
+     * @param size - Maximum number of random samples to return
+     */
+    getRandomSampleFromSnapshot(size: number): Promise<readonly DeepReadonly<NormalizedPrototype>[]>;
+    /**
+     * 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.
+     *
+     * This method does NOT perform HTTP calls.
+     * It only reflects the current in-memory state of the snapshot.
+     *
+     * @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');
+     *
+     * // Check content
+     * console.log(`Version: ${snapshot.version}`);
+     * console.log(`Serialized: ${snapshot.serializedAt}`);
+     * console.log(`Count: ${snapshot.prototypes.length}`);
+     * ```
+     *
+     * @see {@link setupSnapshotFromSerializedData} for importing serialized snapshots
+     * @see {@link SerializableSnapshot} for the data structure
+     */
+    getSerializableSnapshot(): SerializableSnapshot;
+    /**
+     * Setup snapshot from previously serialized data.
+     *
+     * Alternative to setupSnapshot(params) for offline/cached initialization.
+     * Validates the data structure and populates the in-memory store.
+     *
+     * This method does NOT perform file I/O or JSON.parse().
+     * The caller is responsible for loading and parsing the data.
+     *
+     * Returns a Result type indicating success with stats or failure with error details.
+     * Validation errors are returned as VALIDATION_ERROR type.
+     *
+     * @param data - Serializable snapshot object (previously exported)
+     * @returns SnapshotOperationResult with ok: true and stats on success,
+     *          or ok: false with error details on validation/import failure
+     *
+     * @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 getSerializableSnapshot} for exporting snapshots
+     * @see {@link setupSnapshot} for API-based initialization
+     * @see {@link SerializableSnapshot} for the expected data structure
+     */
+    setupSnapshotFromSerializedData(data: SerializableSnapshot): SnapshotOperationResult;
+    /**
+     * Clean up event listeners and release resources.
+     *
+     * This method removes all event listeners from the internal EventEmitter.
+     * Always call this method in cleanup paths to prevent memory leaks.
+     *
+     * @remarks
+     * **When to call:**
+     * - Test cleanup (`afterEach` in test suites)
+     * - Component unmounting (React `useEffect` cleanup)
+     * - Before creating a new repository instance
+     * - When the repository is no longer needed
+     *
+     * **Safety:**
+     * - Safe to call even when events are disabled (`enableEvents: false`)
+     * - Safe to call multiple times
+     * - Does nothing if no event listeners exist
+     *
+     * @example
+     * ```typescript
+     * // In tests
+     * afterEach(() => {
+     *   repo.dispose();
+     * });
+     *
+     * // In React components
+     * useEffect(() => {
+     *   repo.events?.on('snapshotCompleted', handleComplete);
+     *   return () => repo.dispose();
+     * }, []);
+     * ```
+     *
+     * @see {@link events} for event emitter property
+     */
+    dispose(): void;
+}
+//# sourceMappingURL=repository.types.d.ts.map

package/dist/repository/types/repository.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repository.types.d.ts","sourceRoot":"","sources":["../../../lib/repository/types/repository.types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AAE3C,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AACrE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAElD,OAAO,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,KAAK,EACV,sBAAsB,EACtB,4BAA4B,EAC7B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAEhE,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAEnE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AACrE,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,+BAA+B,CAAC;AAE7E;;GAEG;AACH,MAAM,MAAM,kCAAkC,GAAG;IAC/C;;;;;;;;;OASG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;;;;;;;OASG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAC;IAEpB;;;;;;;;;;;;;;;;OAgBG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,4BAA4B;IAC3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,YAAY,CAAC;IAE/B;;;;OAIG;IACH,SAAS,IAAI,IAAI,CAAC,QAAQ,CAAC,4BAA4B,CAAC,EAAE,QAAQ,CAAC,CAAC;IAEpE;;;;;;;;;OASG;IACH,QAAQ,IAAI,sBAAsB,CAAC;IAEnC;;;;;;;;;;;;OAYG;IACH,aAAa,CAAC,MAAM,EAAE,oBAAoB,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAAC;IAE9E;;;;;;;;;;;;OAYG;IACH,eAAe,IAAI,OAAO,CAAC,uBAAuB,CAAC,CAAC;IAEpD;;;;;;;OAOG;IACH,iBAAiB,IAAI,OAAO,CAAC,uBAAuB,CAAC,CAAC;IAEtD;;;;;;;;;;;OAWG;IACH,kBAAkB,IAAI,OAAO,CAAC,SAAS,YAAY,CAAC,mBAAmB,CAAC,EAAE,CAAC,CAAC;IAE5E;;;;;;;;;;;;;;OAcG;IACH,2BAA2B,IAAI,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC,CAAC;IAE1D;;;;;;;;;OASG;IACH,qCAAqC,CACnC,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,YAAY,CAAC,mBAAmB,CAAC,GAAG,IAAI,CAAC,CAAC;IAErD;;;;;;;;;OASG;IACH,8BAA8B,IAAI,OAAO,CAAC,YAAY,CAAC,mBAAmB,CAAC,GAAG,IAAI,CAAC,CAAC;IAEpF;;;;;;;;;;;;OAYG;IACH,2BAA2B,CACzB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,SAAS,YAAY,CAAC,mBAAmB,CAAC,EAAE,CAAC,CAAC;IAEzD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACH,uBAAuB,IAAI,oBAAoB,CAAC;IAEhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACH,+BAA+B,CAC7B,IAAI,EAAE,oBAAoB,GACzB,uBAAuB,CAAC;IAE3B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACH,OAAO,IAAI,IAAI,CAAC;CACjB"}

package/dist/repository/types/repository.types.js

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

package/dist/repository/types/repository.types.js.map

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

package/dist/repository/types/result.types.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Failure kinds specific to repository operations.
+ *
+ * - `validation`: Snapshot validation failed (Zod schema mismatch)
+ * - `invalid_state`: Operation cannot proceed due to invalid repository state
+ * - `size_estimation`: Size estimation for snapshot failed
+ * - `unknown`: Classification failed or unexpected error
+ */
+export type RepositoryFailureKind = 'validation' | 'invalid_state' | 'size_estimation' | 'unknown';
+/**
+ * Error codes for repository-originated failures.
+ *
+ * - `REPOSITORY_VALIDATION_ERROR`: Zod validation failed
+ * - `REPOSITORY_INVALID_STATE`: Operation cannot proceed (e.g., refresh without setup)
+ * - `REPOSITORY_SIZE_ESTIMATION_ERROR`: Size calculation failed
+ * - `REPOSITORY_UNKNOWN`: Unclassified error
+ */
+export type RepositoryErrorCode = 'REPOSITORY_VALIDATION_ERROR' | 'REPOSITORY_INVALID_STATE' | 'REPOSITORY_SIZE_ESTIMATION_ERROR' | 'REPOSITORY_UNKNOWN';
+/**
+ * Successful result from repository operations.
+ */
+export type RepositorySuccess = {
+    /** Indicates successful operation. */
+    ok: true;
+};
+/**
+ * Failed result from repository operations.
+ *
+ * Contains repository-specific error information.
+ *
+ * @remarks
+ * This type represents failures that occur at the repository layer,
+ * distinct from failures originating in the fetcher or store layers.
+ */
+export type RepositoryFailure = {
+    /** Indicates failed operation. */
+    ok: false;
+    /** Always repository-originated. */
+    origin: 'repository';
+    /** Coarse-grained classification of the failure cause. */
+    kind: RepositoryFailureKind;
+    /** Canonical error code from the repository. */
+    code: RepositoryErrorCode;
+    /** Human-readable error message. */
+    message: string;
+    /** Underlying cause of the error (optional). */
+    cause?: unknown;
+};
+/**
+ * Result from repository operations.
+ *
+ * Returns either success or failure with repository-specific error details.
+ */
+export type RepositoryResult = RepositorySuccess | RepositoryFailure;
+//# sourceMappingURL=result.types.d.ts.map

package/dist/repository/types/result.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"result.types.d.ts","sourceRoot":"","sources":["../../../lib/repository/types/result.types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,MAAM,qBAAqB,GAC7B,YAAY,GACZ,eAAe,GACf,iBAAiB,GACjB,SAAS,CAAC;AAEd;;;;;;;GAOG;AACH,MAAM,MAAM,mBAAmB,GAC3B,6BAA6B,GAC7B,0BAA0B,GAC1B,kCAAkC,GAClC,oBAAoB,CAAC;AAEzB;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,sCAAsC;IACtC,EAAE,EAAE,IAAI,CAAC;CACV,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,kCAAkC;IAClC,EAAE,EAAE,KAAK,CAAC;IACV,oCAAoC;IACpC,MAAM,EAAE,YAAY,CAAC;IACrB,0DAA0D;IAC1D,IAAI,EAAE,qBAAqB,CAAC;IAC5B,gDAAgD;IAChD,IAAI,EAAE,mBAAmB,CAAC;IAC1B,oCAAoC;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,gDAAgD;IAChD,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,iBAAiB,GAAG,iBAAiB,CAAC"}

package/dist/repository/types/result.types.js

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

package/dist/repository/types/result.types.js.map

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

package/dist/repository/types/serialization.types.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Type definitions for snapshot serialization and deserialization.
+ *
+ * This module defines types related to exporting and importing snapshots
+ * in serializable formats.
+ *
+ * @module
+ */
+import type { NormalizedPrototype } from '../../types/index.js';
+/**
+ * Serializable snapshot data structure for export/import.
+ *
+ * This type represents a snapshot that can be serialized to JSON and later
+ * restored. It contains all necessary data to reconstruct an in-memory snapshot
+ * without requiring API calls.
+ *
+ * @remarks
+ * **Use Cases:**
+ * - Offline usage - Load snapshot without network access
+ * - Faster startup - Skip API calls by loading cached snapshots
+ * - Test fixtures - Create consistent test data
+ * - Development - Work without hitting API rate limits
+ *
+ * **Format:**
+ * The structure is designed to be JSON-serializable. The caller is responsible
+ * for actual JSON.stringify() and file I/O operations.
+ *
+ * @example
+ * ```typescript
+ * // Export
+ * const snapshot = await repo.getSerializableSnapshot();
+ * await fs.writeFile('snapshot.json', JSON.stringify(snapshot, null, 2));
+ *
+ * // Import
+ * const data = JSON.parse(await fs.readFile('snapshot.json', 'utf-8'));
+ * const result = repo.setupSnapshotFromSerializedData(data);
+ * ```
+ */
+export type SerializableSnapshot = {
+    /**
+     * Snapshot format version for compatibility checks.
+     *
+     * Format: Semantic versioning (e.g., "1.0.0")
+     * Used to validate compatibility when deserializing.
+     */
+    version: string;
+    /**
+     * ISO-8601 UTC timestamp when the snapshot was serialized.
+     *
+     * Format: "YYYY-MM-DDTHH:mm:ss.sssZ"
+     * Useful for tracking snapshot age and debugging.
+     */
+    serializedAt: string;
+    /**
+     * Array of normalized prototypes.
+     *
+     * Contains all prototypes from the snapshot at the time of export.
+     */
+    prototypes: NormalizedPrototype[];
+};
+//# sourceMappingURL=serialization.types.d.ts.map

package/dist/repository/types/serialization.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serialization.types.d.ts","sourceRoot":"","sources":["../../../lib/repository/types/serialization.types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAEhE;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC;;;;;OAKG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;;;;OAKG;IACH,YAAY,EAAE,MAAM,CAAC;IAErB;;;;OAIG;IACH,UAAU,EAAE,mBAAmB,EAAE,CAAC;CACnC,CAAC"}

package/dist/repository/types/serialization.types.js

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

package/dist/repository/types/serialization.types.js.map

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

package/dist/repository/types/snapshot-operation.types.d.ts

@@ -0,0 +1,140 @@
+import type { FetcherErrorCode, FetchFailureKind, FetchPrototypesFailure } from '../../fetcher/types/index.js';
+import type { PrototypeInMemoryStats } from '../../store/index.js';
+import type { SetFailure } from '../../store/types/index.js';
+import type { RepositoryErrorCode, RepositoryFailureKind } from './result.types.js';
+/**
+ * Successful response from setupSnapshot or refreshSnapshot operations.
+ *
+ * Contains statistics about the newly created or refreshed snapshot.
+ *
+ * @example
+ * ```typescript
+ * const result = await repo.setupSnapshot({ limit: 100 });
+ * if (result.ok) {
+ *   console.log('Cached prototypes:', result.stats.size);
+ *   console.log('Cached at:', result.stats.cachedAt);
+ * }
+ * ```
+ */
+export type SnapshotOperationSuccess = {
+    /** Indicates successful operation. */
+    ok: true;
+    /** Statistics about the current snapshot after the operation. */
+    stats: PrototypeInMemoryStats;
+};
+/**
+ * Base type for all snapshot operation failures.
+ *
+ * Contains common fields shared by all failure types in the discriminated union.
+ */
+export type SnapshotOperationFailureBase = {
+    /** Indicates failed operation. */
+    ok: false;
+    /** Origin layer where the failure occurred. */
+    origin: 'fetcher' | 'store' | 'repository' | 'unknown';
+    /** Human-readable error message. */
+    message: string;
+};
+/**
+ * Unknown/unexpected failure during snapshot operations.
+ *
+ * Fallback for errors that cannot be classified into fetcher or store failures.
+ */
+export type UnknownSnapshotFailure = SnapshotOperationFailureBase & {
+    /** Indicates failure with unknown origin. */
+    origin: 'unknown';
+};
+/**
+ * Failure from the fetcher layer during snapshot operations.
+ *
+ * Includes detailed error information from network/HTTP operations.
+ */
+export type FetcherSnapshotFailure = SnapshotOperationFailureBase & {
+    /** Indicates failure originated from fetcher layer. */
+    origin: 'fetcher';
+    /** Coarse-grained classification of the failure cause. */
+    kind: FetchFailureKind;
+    /** Canonical error code from the fetcher. */
+    code: FetcherErrorCode;
+    /** HTTP status code if applicable. */
+    status?: number;
+    /** Additional error details from request and response. */
+    details: FetchPrototypesFailure['details'];
+};
+/**
+ * Failure from the store layer during snapshot operations.
+ *
+ * Type alias for SetFailure when used in snapshot operation context.
+ * Occurs when snapshot data cannot be stored in memory due to size limits
+ * or serialization issues.
+ */
+export type StoreSnapshotFailure = SetFailure;
+/**
+ * Failure from the repository layer during snapshot operations.
+ *
+ * Occurs when input data validation fails during setupSnapshotFromSerializedData
+ * or when size estimation fails for snapshots.
+ * This indicates that the provided snapshot data does not conform to the
+ * expected schema (e.g., invalid version format, missing fields, incorrect types)
+ * or that size calculation encountered an error.
+ */
+export type RepositorySnapshotFailure = SnapshotOperationFailureBase & {
+    /** Indicates failure originated from repository layer. */
+    origin: 'repository';
+    /** Coarse-grained classification of the failure cause. */
+    kind: RepositoryFailureKind;
+    /** Canonical error code from the repository. */
+    code: RepositoryErrorCode;
+};
+/**
+ * Failed response from setupSnapshot or refreshSnapshot operations.
+ *
+ * Discriminated union of all possible snapshot failure types.
+ * Use the 'origin' field to determine which specific failure type it is.
+ *
+ * @example
+ * ```typescript
+ * const result = await repo.setupSnapshot({ limit: 100 });
+ * if (!result.ok) {
+ *   switch (result.origin) {
+ *     case 'fetcher':
+ *       console.error('Fetch failed:', result.kind, result.code);
+ *       if (result.status === 401) {
+ *         console.error('Authentication error');
+ *       }
+ *       break;
+ *     case 'store':
+ *       console.error('Store failed:', result.kind, result.code);
+ *       break;
+ *     case 'repository':
+ *       console.error('Validation failed:', result.message);
+ *       break;
+ *     case 'unknown':
+ *       console.error('Unknown error:', result.message);
+ *       break;
+ *   }
+ * }
+ * ```
+ */
+export type SnapshotOperationFailure = FetcherSnapshotFailure | StoreSnapshotFailure | RepositorySnapshotFailure | UnknownSnapshotFailure;
+/**
+ * Result type for setupSnapshot and refreshSnapshot operations.
+ *
+ * Discriminated union that allows type-safe error handling without exceptions.
+ * Follows the same pattern as the fetcher module's Result types.
+ *
+ * @example
+ * ```typescript
+ * const result = await repo.setupSnapshot({ limit: 100 });
+ *
+ * if (result.ok) {
+ *   // TypeScript knows result has 'stats' property
+ *   console.log('Success:', result.stats.size);
+ * } else {
+ *   // TypeScript knows result has 'error', 'status', 'code' properties
+ *   console.error('Failed:', result.error, result.status);
+ * }
+ * ```
+ */
+export type SnapshotOperationResult = SnapshotOperationSuccess | SnapshotOperationFailure;
+//# sourceMappingURL=snapshot-operation.types.d.ts.map

package/dist/repository/types/snapshot-operation.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot-operation.types.d.ts","sourceRoot":"","sources":["../../../lib/repository/types/snapshot-operation.types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,gBAAgB,EAChB,gBAAgB,EAChB,sBAAsB,EACvB,MAAM,8BAA8B,CAAC;AACtC,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AACnE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAE7D,OAAO,KAAK,EACV,mBAAmB,EACnB,qBAAqB,EACtB,MAAM,mBAAmB,CAAC;AAE3B;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,wBAAwB,GAAG;IACrC,sCAAsC;IACtC,EAAE,EAAE,IAAI,CAAC;IACT,iEAAiE;IACjE,KAAK,EAAE,sBAAsB,CAAC;CAC/B,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,4BAA4B,GAAG;IACzC,kCAAkC;IAClC,EAAE,EAAE,KAAK,CAAC;IACV,+CAA+C;IAC/C,MAAM,EAAE,SAAS,GAAG,OAAO,GAAG,YAAY,GAAG,SAAS,CAAC;IACvD,oCAAoC;IACpC,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,sBAAsB,GAAG,4BAA4B,GAAG;IAClE,6CAA6C;IAC7C,MAAM,EAAE,SAAS,CAAC;CACnB,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,sBAAsB,GAAG,4BAA4B,GAAG;IAClE,uDAAuD;IACvD,MAAM,EAAE,SAAS,CAAC;IAClB,0DAA0D;IAC1D,IAAI,EAAE,gBAAgB,CAAC;IACvB,6CAA6C;IAC7C,IAAI,EAAE,gBAAgB,CAAC;IACvB,sCAAsC;IACtC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0DAA0D;IAC1D,OAAO,EAAE,sBAAsB,CAAC,SAAS,CAAC,CAAC;CAC5C,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,MAAM,oBAAoB,GAAG,UAAU,CAAC;AAE9C;;;;;;;;GAQG;AACH,MAAM,MAAM,yBAAyB,GAAG,4BAA4B,GAAG;IACrE,0DAA0D;IAC1D,MAAM,EAAE,YAAY,CAAC;IACrB,0DAA0D;IAC1D,IAAI,EAAE,qBAAqB,CAAC;IAC5B,gDAAgD;IAChD,IAAI,EAAE,mBAAmB,CAAC;CAC3B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,MAAM,wBAAwB,GAChC,sBAAsB,GACtB,oBAAoB,GACpB,yBAAyB,GACzB,sBAAsB,CAAC;AAE3B;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,MAAM,uBAAuB,GAC/B,wBAAwB,GACxB,wBAAwB,CAAC"}

package/dist/repository/types/snapshot-operation.types.js

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

package/dist/repository/types/snapshot-operation.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot-operation.types.js","sourceRoot":"","sources":["../../../lib/repository/types/snapshot-operation.types.ts"],"names":[],"mappings":""}