promidas 2.0.0

package/dist/store/store.js

@@ -0,0 +1,411 @@
+import { ConsoleLogger, createConsoleLogger, } from '../logger/index.js';
+import { sanitizeDataForLogging } from '../utils/index.js';
+import { ConfigurationError, DataSizeExceededError, SizeEstimationError, } from './errors/store-error.js';
+const DEFAULT_TTL_MS = 30 * 60 * 1_000; // 30 minutes
+const DEFAULT_DATA_SIZE_BYTES = 10 * 1024 * 1024; // 10 MiB
+/**
+ * Hard limit for data size in bytes for storing snapshots.
+ * Attempting to configure a store with a size larger than this will throw an error.
+ */
+export const LIMIT_DATA_SIZE_BYTES = 30 * 1024 * 1024; // 30 MiB
+/**
+ * In-memory store that keeps the full set of normalized prototypes with an ID-based index.
+ *
+ * The store accepts full snapshots (`setAll`) and exposes O(1) lookups by prototype id
+ * via an internal index. When TTL expires, data remains readable while callers kick off
+ * background refresh tasks using {@link runExclusive} to avoid redundant upstream calls.
+ */
+export class PrototypeInMemoryStore {
+    logger;
+    logLevel;
+    ttlMs;
+    maxDataSizeBytes;
+    prototypeIdIndex = new Map();
+    prototypes = [];
+    cachedAt = null;
+    dataSizeBytes = 0;
+    refreshPromise = null;
+    /**
+     * Create a new PrototypeInMemoryStore instance.
+     *
+     * Initializes an in-memory cache for normalized prototypes with configurable
+     * TTL and size limits. The store manages snapshot expiration, refresh state,
+     * and provides type-safe read-only access to cached data.
+     *
+     * @param config - Configuration options for the store
+     * @param config.ttlMs - Time-to-live in milliseconds for cached snapshots.
+     *   Defaults to 30 minutes (1,800,000ms). After this duration, the snapshot
+     *   is considered expired and should be refreshed.
+     * @param config.maxDataSizeBytes - Maximum allowed size for cached data in bytes.
+     *   Defaults to 10 MiB (10,485,760 bytes). Must not exceed 30 MiB.
+     *   If a snapshot exceeds this limit, setAll() will reject it.
+     * @param config.logger - Optional custom logger instance. If not provided,
+     *   a default ConsoleLogger is created.
+     * @param config.logLevel - Log level for the logger. When `logger` is not provided,
+     *   creates a ConsoleLogger with this level. When `logger` is provided and mutable,
+     *   updates the logger's level property.
+     *
+     * @throws {ConfigurationError} When maxDataSizeBytes exceeds LIMIT_DATA_SIZE_BYTES (30 MiB)
+     */
+    constructor({ ttlMs = DEFAULT_TTL_MS, maxDataSizeBytes = DEFAULT_DATA_SIZE_BYTES, logger, logLevel, } = {}) {
+        this.ttlMs = ttlMs;
+        this.maxDataSizeBytes = maxDataSizeBytes;
+        // Fastify-style logger configuration
+        if (logger) {
+            // Custom logger provided
+            this.logger = logger;
+            this.logLevel = logLevel ?? 'info';
+            // If logLevel is specified, update logger's level property (if mutable)
+            if (logLevel !== undefined && 'level' in logger) {
+                logger.level = logLevel;
+            }
+        }
+        else {
+            // No custom logger → create ConsoleLogger with logLevel
+            const resolvedLogLevel = logLevel ?? 'info';
+            this.logger = new ConsoleLogger(resolvedLogLevel);
+            this.logLevel = resolvedLogLevel;
+        }
+        this.logger.info('PrototypeInMemoryStore constructor called', {
+            ttlMs,
+            maxDataSizeBytes,
+            logger: logger ? 'custom' : undefined,
+            logLevel,
+        });
+        // Throw if maxDataSizeBytes exceeds the hard limit
+        if (maxDataSizeBytes > LIMIT_DATA_SIZE_BYTES) {
+            const maxMiB = (LIMIT_DATA_SIZE_BYTES / (1024 * 1024)).toFixed(0);
+            throw new ConfigurationError(`PrototypeInMemoryStore maxDataSizeBytes must be <= ${LIMIT_DATA_SIZE_BYTES} bytes (${maxMiB} MiB) to prevent oversized data`);
+        }
+    }
+    /**
+     * Retrieve the configuration used to initialize this store.
+     *
+     * Returns the resolved configuration values (TTL and max payload size) that were
+     * set during instantiation. These values are immutable after construction.
+     */
+    getConfig() {
+        return {
+            ttlMs: this.ttlMs,
+            maxDataSizeBytes: this.maxDataSizeBytes,
+            logLevel: this.logLevel,
+        };
+    }
+    /** Count of prototypes currently kept in the in-memory store. */
+    get size() {
+        return this.prototypeIdIndex.size;
+    }
+    /** Timestamp representing when the snapshot was last refreshed. */
+    getCachedAt() {
+        return this.cachedAt;
+    }
+    /**
+     * Calculate elapsed time in milliseconds since the snapshot was cached.
+     * Returns 0 if no data is cached.
+     */
+    getElapsedTime() {
+        if (!this.cachedAt) {
+            return 0;
+        }
+        return Date.now() - this.cachedAt.getTime();
+    }
+    /**
+     * Calculate remaining time in milliseconds until expiration.
+     * Returns 0 if already expired or no data is cached.
+     */
+    getRemainingTtl() {
+        if (!this.cachedAt) {
+            return 0;
+        }
+        const elapsed = this.getElapsedTime();
+        const remaining = this.ttlMs - elapsed;
+        return Math.max(0, remaining);
+    }
+    /** Determine whether the snapshot is stale based on the configured TTL. */
+    isExpired() {
+        if (!this.cachedAt) {
+            return true;
+        }
+        return this.getElapsedTime() > this.ttlMs;
+    }
+    /** Report whether a background refresh is currently in flight. */
+    isRefreshInFlight() {
+        return this.refreshPromise !== null;
+    }
+    /**
+     * Provide statistics describing cache health and runtime state.
+     *
+     * Returns metadata about the current snapshot including size, expiration status,
+     * and refresh state. For configuration values like TTL, use {@link getConfig}.
+     */
+    getStats() {
+        return {
+            size: this.prototypeIdIndex.size,
+            cachedAt: this.cachedAt,
+            isExpired: this.isExpired(),
+            remainingTtlMs: this.getRemainingTtl(),
+            dataSizeBytes: this.dataSizeBytes,
+            refreshInFlight: this.isRefreshInFlight(),
+        };
+    }
+    /**
+     * Estimates the JSON payload size of an array of NormalizedPrototypes in bytes.
+     *
+     * This method calculates the size by iteratively serializing each item and summing their byte lengths,
+     * along with the overhead for array brackets and commas. This approach minimizes memory usage
+     * by avoiding the creation of a single large JSON string for the entire array, thus reducing
+     * the risk of out-of-memory errors, especially with large datasets.
+     *
+     * @param data - The array of NormalizedPrototypes to estimate the size for.
+     * @returns The estimated size in bytes of the JSON-serialized data.
+     * @throws {SizeEstimationError} When JSON serialization fails (e.g., circular references).
+     */
+    estimateSize(data) {
+        try {
+            if (data.length === 0) {
+                return 2; // "[]"
+            }
+            // Start with 2 bytes for "[]" and 1 byte for each comma (N-1 commas)
+            let totalBytes = 2 + (data.length - 1);
+            if (typeof Buffer !== 'undefined') {
+                for (const item of data) {
+                    totalBytes += Buffer.byteLength(JSON.stringify(item), 'utf8');
+                }
+            }
+            else if (typeof TextEncoder !== 'undefined') {
+                const encoder = new TextEncoder();
+                for (const item of data) {
+                    totalBytes += encoder.encode(JSON.stringify(item)).length;
+                }
+            }
+            else {
+                // Fallback for environments without Buffer/TextEncoder (should not happen in Node.js)
+                this.logger.warn('Neither Buffer nor TextEncoder found for size estimation. Returning 0.', {});
+                return 0;
+            }
+            return totalBytes;
+        }
+        catch (error) {
+            this.logger.error('Failed to estimate payload size', {
+                error: sanitizeDataForLogging(error),
+            });
+            throw new SizeEstimationError('UNKNOWN', error instanceof Error ? error : undefined);
+        }
+    }
+    /**
+     * Execute a refresh task while preventing concurrent execution.
+     *
+     * @returns Promise resolved when the task completes; callers may ignore it for background refreshes.
+     */
+    runExclusive(task) {
+        if (this.refreshPromise) {
+            return this.refreshPromise;
+        }
+        this.refreshPromise = (async () => {
+            try {
+                await task();
+            }
+            catch (error) {
+                this.logger.error('PrototypeInMemoryStore refresh task failed', {
+                    error: sanitizeDataForLogging(error),
+                });
+                throw error;
+            }
+            finally {
+                this.refreshPromise = null;
+            }
+        })();
+        return this.refreshPromise;
+    }
+    /** Reset the store to an empty state and clear all metadata. */
+    clear() {
+        const previousSize = this.prototypeIdIndex.size;
+        this.prototypeIdIndex.clear();
+        this.prototypes = [];
+        this.cachedAt = null;
+        this.dataSizeBytes = 0;
+        this.logger.info('PrototypeInMemoryStore cleared', { previousSize });
+    }
+    /**
+     * Store the provided snapshot if it fits within the configured payload limit.
+     * Creates a shallow copy of the input array to prevent external mutations.
+     *
+     * @param prototypes - Array of normalized prototypes to store (array will be copied)
+     * @returns Metadata about the stored snapshot including the exact data size in bytes
+     * @throws {SizeEstimationError} When data size estimation fails
+     * @throws {DataSizeExceededError} When the payload exceeds the configured maximum size limit
+     *
+     * @remarks
+     * **Error Handling**: When an error is thrown, the store is NOT modified.
+     * Any previously stored snapshot remains intact and accessible. This ensures
+     * that applications can continue serving data from the last successful snapshot
+     * even when new data cannot be stored.
+     *
+     * The method creates a shallow copy of the input array to ensure the store's
+     * internal state cannot be corrupted by external mutations of the array.
+     * However, the prototype objects themselves are not cloned. Callers must not
+     * mutate the prototype objects after passing them to this method.
+     *
+     * Size calculation is performed AFTER deduplication to ensure accurate size checking.
+     * If duplicate IDs are present in the input array, only the last occurrence is kept.
+     */
+    setAll(prototypes) {
+        // Build O(1) lookup index by prototype ID first to deduplicate
+        // Note: If duplicate IDs are present in the input array, the last one wins.
+        const uniqueMap = new Map(prototypes.map((prototype) => [prototype.id, prototype]));
+        // Warn if duplicate IDs were detected in the input array
+        if (uniqueMap.size !== prototypes.length) {
+            this.logger.warn('Duplicate prototype IDs detected in snapshot', {
+                inputCount: prototypes.length,
+                storedCount: uniqueMap.size,
+            });
+        }
+        // Reconstruct prototypes array from the map to ensure consistency and uniqueness by ID.
+        // This will also ensure that `getAll().length` matches `this.size`.
+        const uniquePrototypes = Array.from(uniqueMap.values());
+        // Validate payload size AFTER deduplication
+        const dataSizeBytes = (() => {
+            try {
+                return this.estimateSize(uniquePrototypes);
+            }
+            catch (error) {
+                // At this point, store data is unchanged (estimation failed before any store updates)
+                if (error instanceof SizeEstimationError) {
+                    throw new SizeEstimationError('UNCHANGED', error.cause);
+                }
+                // Re-throw unexpected errors
+                throw error;
+            }
+        })();
+        if (dataSizeBytes > this.maxDataSizeBytes) {
+            this.logger.warn('Snapshot rejected: data exceeds maximum size', {
+                dataSizeBytes,
+                maxDataSizeBytes: this.maxDataSizeBytes,
+                inputCount: prototypes.length,
+                uniqueCount: uniqueMap.size,
+            });
+            throw new DataSizeExceededError('UNCHANGED', dataSizeBytes, this.maxDataSizeBytes);
+        }
+        // Store the deduplicated data
+        this.prototypeIdIndex = uniqueMap;
+        this.prototypes = uniquePrototypes;
+        // Update cache metadata
+        this.cachedAt = new Date();
+        this.dataSizeBytes = dataSizeBytes;
+        this.logger.info('PrototypeInMemoryStore snapshot updated', {
+            count: this.prototypeIdIndex.size,
+            dataSizeBytes,
+        });
+        return { dataSizeBytes };
+    }
+    /**
+     * Retrieve the latest fetched prototypes in their original order.
+     *
+     * Returns type-level readonly reference to the internal prototypes array.
+     * The readonly type provides compile-time safety but not runtime protection.
+     *
+     * @returns Type-level readonly array of prototypes
+     *
+     * @remarks
+     * **Type Safety**: This method returns a readonly-typed reference without
+     * runtime immutability enforcement (no Object.freeze or defensive copying).
+     * Callers must honor the readonly contract and not cast it away.
+     *
+     * **Performance**: Direct reference with zero overhead - suitable for
+     * high-frequency reads of large datasets.
+     */
+    getAll() {
+        return this.prototypes;
+    }
+    /**
+     * Return a lightweight structure containing the cached data and metadata.
+     *
+     * Useful for callers that want to inspect expiry state without mutating the store.
+     */
+    getSnapshot() {
+        return {
+            data: this.getAll(),
+            cachedAt: this.cachedAt,
+            isExpired: this.isExpired(),
+        };
+    }
+    /**
+     * Retrieve a single prototype by its numeric identifier.
+     *
+     * Uses the internal prototypeIdIndex for O(1) constant-time lookup, providing
+     * exceptional performance even with thousands of cached prototypes. This is
+     * significantly faster than linear search alternatives (approximately 12,500x
+     * faster for 5,000 items).
+     *
+     * The index-based implementation adds minimal memory overhead (~230KB for 5,000
+     * items, or ~0.8% of total cache size) while delivering constant-time access
+     * regardless of cache size.
+     *
+     * @param prototypeId - The numeric ID of the prototype to retrieve
+     * @returns The prototype with type-level immutability, or null if not found
+     *
+     * @example
+     * ```typescript
+     * const proto = store.getByPrototypeId(123);
+     * if (proto) {
+     *   console.log(proto.prototypeNm);
+     * }
+     * ```
+     *
+     * @performance
+     * - Time complexity: O(1) - constant time regardless of cache size
+     * - Measured: ~0.0002ms per lookup (10,000 items)
+     * - Memory overhead: ~40 bytes per entry (including index metadata and hash table)
+     */
+    getByPrototypeId(prototypeId) {
+        const prototype = this.prototypeIdIndex.get(prototypeId) ?? null;
+        return prototype;
+    }
+    /**
+     * Return an array of all cached prototype IDs.
+     *
+     * This method provides efficient access to prototype IDs without copying the
+     * entire prototype objects. Useful for operations that only need IDs, such as
+     * ID-based filtering, statistics, or exporting ID lists.
+     *
+     * @returns Read-only array of prototype IDs in insertion order
+     *
+     * @performance
+     * - Time complexity: O(n) - must iterate through all Map keys
+     * - Memory: Creates a new array of numbers (~40 bytes per ID)
+     * - Lighter than getAll() which copies full objects (~300+ bytes each)
+     *
+     * @example
+     * ```typescript
+     * // ✅ Good: Call once and reuse
+     * const ids = store.getPrototypeIds();
+     * const count = ids.length;
+     * const maxId = Math.max(...ids);
+     *
+     * // ✅ Good: Single-use cases
+     * return { availableIds: store.getPrototypeIds() };
+     *
+     * // ❌ Bad: Repeated calls in loops
+     * for (let i = 0; i < 1000; i++) {
+     *   const ids = store.getPrototypeIds();  // O(n) × 1000 = very slow!
+     *   const id = ids[Math.floor(Math.random() * ids.length)];
+     * }
+     *
+     * // ✅ Better: Use getAll() once for repeated access
+     * const all = store.getAll();
+     * for (let i = 0; i < 1000; i++) {
+     *   const item = all[Math.floor(Math.random() * all.length)];
+     * }
+     * ```
+     *
+     * @remarks
+     * **Performance Warning**: This method creates a new array on every call.
+     * For high-frequency operations (loops, repeated random access), prefer
+     * calling {@link getAll} once and reusing the result. The O(n) cost per
+     * call makes this unsuitable for tight loops.
+     */
+    getPrototypeIds() {
+        return Array.from(this.prototypeIdIndex.keys());
+    }
+}
+//# sourceMappingURL=store.js.map

package/dist/store/store.js.map

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

package/dist/store/types/index.d.ts

@@ -0,0 +1,2 @@
+export type { SetFailure, SetResult, SetSuccess, StoreErrorCode, StoreFailureKind, } from './result.types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/store/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../lib/store/types/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,UAAU,EACV,SAAS,EACT,UAAU,EACV,cAAc,EACd,gBAAgB,GACjB,MAAM,mBAAmB,CAAC"}

package/dist/store/types/index.js

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

package/dist/store/types/index.js.map

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

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

@@ -0,0 +1,67 @@
+import type { StoreDataState } from '../errors/store-error.js';
+import type { PrototypeInMemoryStats } from '../store.js';
+/**
+ * Failure kinds specific to store operations.
+ *
+ * - `storage_limit`: Store capacity exceeded
+ * - `serialization`: JSON serialization failed during size estimation
+ * - `unknown`: Unexpected store error
+ */
+export type StoreFailureKind = 'storage_limit' | 'serialization' | 'unknown';
+/**
+ * Error codes for store-originated failures.
+ *
+ * - `STORE_CAPACITY_EXCEEDED`: Data size exceeds configured limit
+ * - `STORE_SERIALIZATION_FAILED`: Failed to serialize data for size estimation
+ * - `STORE_UNKNOWN`: Unexpected error from store
+ */
+export type StoreErrorCode = 'STORE_CAPACITY_EXCEEDED' | 'STORE_SERIALIZATION_FAILED' | 'STORE_UNKNOWN';
+/**
+ * Successful result from setAll operation.
+ */
+export type SetSuccess = {
+    /** Indicates successful operation. */
+    ok: true;
+    /** Statistics about the current snapshot after storing. */
+    stats: PrototypeInMemoryStats;
+};
+/**
+ * Failed result from setAll operation.
+ *
+ * Contains store-specific error information.
+ */
+export type SetFailure = {
+    /** Indicates failed operation. */
+    ok: false;
+    /** Always store-originated. */
+    origin: 'store';
+    /** Coarse-grained classification of the failure cause. */
+    kind: StoreFailureKind;
+    /** Canonical error code from the store. */
+    code: StoreErrorCode;
+    /** Human-readable error message. */
+    message: string;
+    /** State of the store's data when the error occurred. */
+    dataState: StoreDataState;
+    /** Underlying cause of the error (for serialization failures). */
+    cause?: unknown;
+};
+/**
+ * Result from setAll operation.
+ *
+ * Returns either success with stats or failure with store-specific error details.
+ * This type maintains symmetry with FetchPrototypesResult at the operation boundary,
+ * allowing fetchAndStore to handle both fetch and store operations uniformly.
+ *
+ * @example
+ * ```typescript
+ * const result = storeSnapshot(data);
+ * if (result.ok) {
+ *   console.log('Stored:', result.stats.size);
+ * } else {
+ *   console.error('Store failed:', result.kind, result.code);
+ * }
+ * ```
+ */
+export type SetResult = SetSuccess | SetFailure;
+//# sourceMappingURL=result.types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"result.types.d.ts","sourceRoot":"","sources":["../../../lib/store/types/result.types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAE1D;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GAAG,eAAe,GAAG,eAAe,GAAG,SAAS,CAAC;AAE7E;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,GACtB,yBAAyB,GACzB,4BAA4B,GAC5B,eAAe,CAAC;AAEpB;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,sCAAsC;IACtC,EAAE,EAAE,IAAI,CAAC;IACT,2DAA2D;IAC3D,KAAK,EAAE,sBAAsB,CAAC;CAC/B,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,kCAAkC;IAClC,EAAE,EAAE,KAAK,CAAC;IACV,+BAA+B;IAC/B,MAAM,EAAE,OAAO,CAAC;IAChB,0DAA0D;IAC1D,IAAI,EAAE,gBAAgB,CAAC;IACvB,2CAA2C;IAC3C,IAAI,EAAE,cAAc,CAAC;IACrB,oCAAoC;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,yDAAyD;IACzD,SAAS,EAAE,cAAc,CAAC;IAC1B,kEAAkE;IAClE,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,SAAS,GAAG,UAAU,GAAG,UAAU,CAAC"}

package/dist/store/types/result.types.js

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

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

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

package/dist/types/codes.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Type definitions for ProtoPedia field value codes.
+ *
+ * These types define the valid numeric values for various ProtoPedia fields.
+ *
+ * @module types
+ */
+/**
+ * Valid status code values.
+ *
+ * - 1: 'アイデア' (Idea)
+ * - 2: '開発中' (In Development)
+ * - 3: '完成' (Completed)
+ * - 4: '供養' (Retired/Memorial)
+ *
+ * All four status values appear in public API responses.
+ */
+export type StatusCode = 1 | 2 | 3 | 4;
+/**
+ * Valid release flag code values.
+ *
+ * - 1: '下書き保存' (Draft) - Not accessible via public API
+ * - 2: '一般公開' (Public) - Only this value appears in API responses
+ * - 3: '限定共有' (Limited Sharing) - Not accessible via public API
+ */
+export type ReleaseFlagCode = 1 | 2 | 3;
+/**
+ * Valid license type code values.
+ *
+ * - 0: 'なし' (None) - Not observed in API responses
+ * - 1: '表示(CC:BY)' (Display with CC BY license) - All API responses have this value
+ */
+export type LicenseTypeCode = 0 | 1;
+/**
+ * Valid thanks flag code values.
+ *
+ * - 0: (Implicit) Message not yet shown - Rarely or never seen in API responses
+ * - 1: '初回表示済' ("Thank you for posting" message shown) - Most common value
+ * - undefined: Field not present in older prototypes (pre-thanksFlg era, ~3.26% of data)
+ *
+ * Note: Historical data may not include this field. Always handle undefined case.
+ */
+export type ThanksFlagCode = 0 | 1 | undefined;
+//# sourceMappingURL=codes.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"codes.d.ts","sourceRoot":"","sources":["../../lib/types/codes.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;GASG;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AAEvC;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AAExC;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,GAAG,CAAC,CAAC;AAEpC;;;;;;;;GAQG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,GAAG,CAAC,GAAG,SAAS,CAAC"}

package/dist/types/codes.js

@@ -0,0 +1,9 @@
+/**
+ * Type definitions for ProtoPedia field value codes.
+ *
+ * These types define the valid numeric values for various ProtoPedia fields.
+ *
+ * @module types
+ */
+export {};
+//# sourceMappingURL=codes.js.map

package/dist/types/codes.js.map

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

package/dist/types/index.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Shared type definitions for the library.
+ *
+ * This module provides the core data structures used throughout the library.
+ * It serves as the single source of truth for type definitions, ensuring
+ * consistency across all layers (Fetcher, Store, Repository).
+ *
+ * ## Main Exports
+ *
+ * - {@link NormalizedPrototype} — The standardized shape of a prototype
+ *   after normalization from ProtoPedia API responses.
+ * - {@link StatusCode} — Type for prototype status codes (1-4)
+ * - {@link ReleaseFlagCode} — Type for release flag codes (1-3)
+ * - {@link LicenseTypeCode} — Type for license type codes (0-1)
+ * - {@link ThanksFlagCode} — Type for thanks flag codes (0, 1, or undefined)
+ *
+ * ## Type Characteristics
+ *
+ * - **Type Safety**: Strongly typed with clear required/optional field distinction
+ * - **Normalization**: Pipe-separated strings converted to arrays, timestamps to UTC ISO 8601
+ * - **Strict Typing**: Compatible with TypeScript's `exactOptionalPropertyTypes: true`
+ * - **Cross-Layer Consistency**: Used uniformly across Fetcher, Store, and Repository
+ *
+ * ## Usage
+ *
+ * @example
+ * ```typescript
+ * import type { NormalizedPrototype, StatusCode } from 'promidas/types';
+ *
+ * function processPrototype(prototype: NormalizedPrototype) {
+ *   // Required fields are always accessible
+ *   console.log(prototype.id, prototype.prototypeNm);
+ *
+ *   // Array fields are type-safe
+ *   prototype.tags.forEach(tag => console.log(tag)); // tag is string
+ *
+ *   // Optional fields require undefined checks
+ *   if (prototype.releaseDate !== undefined) {
+ *     console.log(new Date(prototype.releaseDate));
+ *   }
+ *
+ *   // Code types are available
+ *   const status: StatusCode = prototype.status as StatusCode;
+ * }
+ * ```
+ *
+ * ## Data Transformation
+ *
+ * This type represents data after normalization:
+ *
+ * - **Raw API data** (`UpstreamPrototype`) → `normalizePrototype()` → **Normalized data** (`NormalizedPrototype`)
+ * - Pipe-separated strings (`"tag1|tag2"`) → Arrays (`["tag1", "tag2"]`)
+ * - JST timestamps (`"2025-12-12 09:00:00.0"`) → UTC ISO 8601 (`"2025-12-12T00:00:00.000Z"`)
+ *
+ * @module
+ * @see {@link NormalizedPrototype} for detailed field documentation
+ * @see {@link ../fetcher/index.js} for normalization utilities
+ */
+export type { NormalizedPrototype } from './normalized-prototype.js';
+export type { StatusCode, ReleaseFlagCode, LicenseTypeCode, ThanksFlagCode, } from './codes.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../lib/types/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AAEH,YAAY,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AACrE,YAAY,EACV,UAAU,EACV,eAAe,EACf,eAAe,EACf,cAAc,GACf,MAAM,YAAY,CAAC"}