promidas 2.0.0

package/dist/utils/time/parser.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Timestamp parsing utilities for ProtoPedia and W3C-DTF formats.
+ *
+ * @module utils/time/parse
+ */
+/**
+ * Parse ProtoPedia timestamp (JST without explicit timezone offset).
+ *
+ * ProtoPedia timestamps are JST-based timestamps without explicit timezone offset.
+ * Current format: `YYYY-MM-DD HH:MM:SS.0` (space separator, `.0` for zero milliseconds)
+ * Example: `2025-11-14 12:03:07.0`
+ *
+ * ## Fractional Seconds Support
+ *
+ * Currently, ProtoPedia API outputs `.0` (single digit, no sub-second precision).
+ * However, this parser accepts any number of fractional digits to accommodate
+ * future API changes:
+ *
+ * - Current: `2025-10-08 18:03:48.0` (1 digit)
+ * - Future possibilities:
+ *   - Milliseconds: `2025-10-08 18:03:48.123` (3 digits)
+ *   - Microseconds: `2025-10-08 18:03:48.123456` (6 digits)
+ *   - Nanoseconds: `2025-10-08 18:03:48.123456789` (9 digits)
+ *
+ * The regex pattern `\.(\d+)` accepts 1 or more digits to support all these cases,
+ * as the underlying Java implementation may begin storing sub-second precision
+ * in the database.
+ *
+ * @param value - String to parse
+ * @returns UTC ISO string if valid ProtoPedia timestamp, undefined otherwise
+ */
+export declare function parseProtoPediaTimestamp(value: string): string | undefined;
+/**
+ * Parse W3C Date and Time Formats (W3C-DTF) timestamps.
+ *
+ * Implements W3C-DTF Level 4-6, which are datetime formats with mandatory
+ * timezone designator (TZD). This is a strict profile of ISO 8601 designed
+ * for web standards.
+ *
+ * **Specification:** https://www.w3.org/TR/NOTE-datetime
+ *
+ * ## Supported Formats
+ *
+ * **Level 4: Complete date plus hours and minutes**
+ * - Format: `YYYY-MM-DDThh:mmTZD`
+ * - Examples: `2025-11-14T12:03Z`, `2025-11-14T12:03+09:00`
+ *
+ * **Level 5: Complete date plus hours, minutes and seconds**
+ * - Format: `YYYY-MM-DDThh:mm:ssTZD`
+ * - Examples: `2025-11-14T12:03:07Z`, `2025-11-14T12:03:07-05:00`
+ *
+ * **Level 6: Complete date plus hours, minutes, seconds and fractional seconds**
+ * - Format: `YYYY-MM-DDThh:mm:ss.sTZD`
+ * - Examples: `2025-11-14T12:03:07.123Z`, `2025-11-14T12:03:07.45+09:00`
+ * - Fractional seconds: 1 or more digits (no maximum)
+ *
+ * ## Timezone Designator (TZD)
+ *
+ * - `Z` or `z`: UTC (Coordinated Universal Time)
+ * - `+HH:MM` or `-HH:MM`: Offset from UTC (colon required per W3C-DTF)
+ *
+ * ## NOT Supported (returns undefined)
+ *
+ * - W3C-DTF Level 1-3 (year-only, year-month, date-only): `2025`, `2025-11`, `2025-11-14`
+ * - Timestamps without TZD: `2025-11-14T12:03:07` (timezone-dependent)
+ * - Offset without colon: `2025-11-14T12:03:07+0900` (not W3C-DTF compliant)
+ * - Other ISO 8601 variants (week dates, ordinal dates, basic format)
+ *
+ * @param value - String to parse
+ * @returns UTC ISO string if valid W3C-DTF Level 4-6, undefined otherwise
+ *
+ * @example
+ * ```typescript
+ * parseW3cDtfTimestamp('2025-11-14T12:03Z')
+ * // => '2025-11-14T12:03:00.000Z'
+ *
+ * parseW3cDtfTimestamp('2025-11-14T12:03:07+09:00')
+ * // => '2025-11-14T03:03:07.000Z'
+ *
+ * parseW3cDtfTimestamp('2025-11-14T12:03:07.123Z')
+ * // => '2025-11-14T12:03:07.123Z'
+ *
+ * parseW3cDtfTimestamp('2025-11-14T12:03:07')
+ * // => undefined (no TZD)
+ *
+ * parseW3cDtfTimestamp('2025-11-14')
+ * // => undefined (date-only, Level 3)
+ * ```
+ */
+export declare function parseW3cDtfTimestamp(value: string): string | undefined;
+//# sourceMappingURL=parser.d.ts.map

package/dist/utils/time/parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../../../lib/utils/time/parser.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CA6C1E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAuBtE"}

package/dist/utils/time/parser.js

@@ -0,0 +1,143 @@
+/**
+ * Timestamp parsing utilities for ProtoPedia and W3C-DTF formats.
+ *
+ * @module utils/time/parse
+ */
+import { JST_OFFSET_MS } from './constants.js';
+/**
+ * Parse ProtoPedia timestamp (JST without explicit timezone offset).
+ *
+ * ProtoPedia timestamps are JST-based timestamps without explicit timezone offset.
+ * Current format: `YYYY-MM-DD HH:MM:SS.0` (space separator, `.0` for zero milliseconds)
+ * Example: `2025-11-14 12:03:07.0`
+ *
+ * ## Fractional Seconds Support
+ *
+ * Currently, ProtoPedia API outputs `.0` (single digit, no sub-second precision).
+ * However, this parser accepts any number of fractional digits to accommodate
+ * future API changes:
+ *
+ * - Current: `2025-10-08 18:03:48.0` (1 digit)
+ * - Future possibilities:
+ *   - Milliseconds: `2025-10-08 18:03:48.123` (3 digits)
+ *   - Microseconds: `2025-10-08 18:03:48.123456` (6 digits)
+ *   - Nanoseconds: `2025-10-08 18:03:48.123456789` (9 digits)
+ *
+ * The regex pattern `\.(\d+)` accepts 1 or more digits to support all these cases,
+ * as the underlying Java implementation may begin storing sub-second precision
+ * in the database.
+ *
+ * @param value - String to parse
+ * @returns UTC ISO string if valid ProtoPedia timestamp, undefined otherwise
+ */
+export function parseProtoPediaTimestamp(value) {
+    if (typeof value !== 'string' || value.length === 0) {
+        return undefined;
+    }
+    // Pattern matches current format and future sub-second precision:
+    // - Current: .0 (1 digit)
+    // - Future: .123 (milliseconds), .123456 (microseconds), .123456789 (nanoseconds)
+    // The `\.(\d+)` pattern accepts 1 or more digits to accommodate potential
+    // database schema changes in the underlying Java implementation.
+    const match = value.match(/^(\d{4})-(\d{2})-(\d{2}) (\d{2}):(\d{2}):(\d{2})\.(\d+)$/);
+    if (!match) {
+        return undefined;
+    }
+    const [, y, m, d, hh, mm, ss, fractional] = match;
+    const year = Number(y);
+    const month = Number(m);
+    const day = Number(d);
+    const hour = Number(hh);
+    const minute = Number(mm);
+    const second = Number(ss);
+    // Fractional seconds are required in the format
+    const padded = fractional.padEnd(3, '0').slice(0, 3);
+    const milli = Number(padded);
+    if ([year, month, day, hour, minute, second, milli].some((part) => Number.isNaN(part))) {
+        return undefined;
+    }
+    // ProtoPedia の既存レスポンスは JST 起点でなので、UTC へ換算するために固定オフセットを引く
+    const utcMs = Date.UTC(year, month - 1, day, hour, minute, second, milli) - JST_OFFSET_MS;
+    if (!Number.isFinite(utcMs)) {
+        return undefined;
+    }
+    const iso = new Date(utcMs).toISOString();
+    return iso;
+}
+/**
+ * Parse W3C Date and Time Formats (W3C-DTF) timestamps.
+ *
+ * Implements W3C-DTF Level 4-6, which are datetime formats with mandatory
+ * timezone designator (TZD). This is a strict profile of ISO 8601 designed
+ * for web standards.
+ *
+ * **Specification:** https://www.w3.org/TR/NOTE-datetime
+ *
+ * ## Supported Formats
+ *
+ * **Level 4: Complete date plus hours and minutes**
+ * - Format: `YYYY-MM-DDThh:mmTZD`
+ * - Examples: `2025-11-14T12:03Z`, `2025-11-14T12:03+09:00`
+ *
+ * **Level 5: Complete date plus hours, minutes and seconds**
+ * - Format: `YYYY-MM-DDThh:mm:ssTZD`
+ * - Examples: `2025-11-14T12:03:07Z`, `2025-11-14T12:03:07-05:00`
+ *
+ * **Level 6: Complete date plus hours, minutes, seconds and fractional seconds**
+ * - Format: `YYYY-MM-DDThh:mm:ss.sTZD`
+ * - Examples: `2025-11-14T12:03:07.123Z`, `2025-11-14T12:03:07.45+09:00`
+ * - Fractional seconds: 1 or more digits (no maximum)
+ *
+ * ## Timezone Designator (TZD)
+ *
+ * - `Z` or `z`: UTC (Coordinated Universal Time)
+ * - `+HH:MM` or `-HH:MM`: Offset from UTC (colon required per W3C-DTF)
+ *
+ * ## NOT Supported (returns undefined)
+ *
+ * - W3C-DTF Level 1-3 (year-only, year-month, date-only): `2025`, `2025-11`, `2025-11-14`
+ * - Timestamps without TZD: `2025-11-14T12:03:07` (timezone-dependent)
+ * - Offset without colon: `2025-11-14T12:03:07+0900` (not W3C-DTF compliant)
+ * - Other ISO 8601 variants (week dates, ordinal dates, basic format)
+ *
+ * @param value - String to parse
+ * @returns UTC ISO string if valid W3C-DTF Level 4-6, undefined otherwise
+ *
+ * @example
+ * ```typescript
+ * parseW3cDtfTimestamp('2025-11-14T12:03Z')
+ * // => '2025-11-14T12:03:00.000Z'
+ *
+ * parseW3cDtfTimestamp('2025-11-14T12:03:07+09:00')
+ * // => '2025-11-14T03:03:07.000Z'
+ *
+ * parseW3cDtfTimestamp('2025-11-14T12:03:07.123Z')
+ * // => '2025-11-14T12:03:07.123Z'
+ *
+ * parseW3cDtfTimestamp('2025-11-14T12:03:07')
+ * // => undefined (no TZD)
+ *
+ * parseW3cDtfTimestamp('2025-11-14')
+ * // => undefined (date-only, Level 3)
+ * ```
+ */
+export function parseW3cDtfTimestamp(value) {
+    if (typeof value !== 'string' || value.length === 0) {
+        return undefined;
+    }
+    // W3C-DTF Level 4-6: datetime with mandatory TZD
+    // Level 4: hh:mm + TZD (seconds optional)
+    // Level 5: hh:mm:ss + TZD
+    // Level 6: hh:mm:ss.s + TZD (fractional seconds: 1+ digits)
+    // TZD: Z/z or ±HH:MM (colon required per W3C-DTF)
+    const w3cDtfPattern = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2})?(\.\d+)?([Zz]|[+-]\d{2}:\d{2})$/;
+    if (!w3cDtfPattern.test(value)) {
+        return undefined;
+    }
+    const parsed = new Date(value);
+    if (Number.isNaN(parsed.getTime())) {
+        return undefined;
+    }
+    return parsed.toISOString();
+}
+//# sourceMappingURL=parser.js.map

package/dist/utils/time/parser.js.map

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

package/dist/utils/validation/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Data validation utilities.
+ *
+ * This module provides validation functions for common data structures.
+ */
+export { validateNormalizedPrototype, validateNormalizedPrototypeArray, } from './normalized-prototype.js';
+export type { ValidationErrorCode, ValidationFailure, ValidationResult, ValidationSuccess, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/utils/validation/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../lib/utils/validation/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,2BAA2B,EAC3B,gCAAgC,GACjC,MAAM,2BAA2B,CAAC;AACnC,YAAY,EACV,mBAAmB,EACnB,iBAAiB,EACjB,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,YAAY,CAAC"}

package/dist/utils/validation/index.js

@@ -0,0 +1,7 @@
+/**
+ * Data validation utilities.
+ *
+ * This module provides validation functions for common data structures.
+ */
+export { validateNormalizedPrototype, validateNormalizedPrototypeArray, } from './normalized-prototype.js';
+//# sourceMappingURL=index.js.map

package/dist/utils/validation/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../lib/utils/validation/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,2BAA2B,EAC3B,gCAAgC,GACjC,MAAM,2BAA2B,CAAC"}

package/dist/utils/validation/normalized-prototype.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Common data validators.
+ *
+ * This module provides validation utilities for common data structures
+ * used across multiple modules (fetcher, repository, store).
+ *
+ * These validators return Result types (ValidationResult) instead of throwing errors.
+ * For parameter validation at API boundaries, modules should throw appropriate errors.
+ */
+import type { Logger } from '../../logger/logger.types.js';
+import type { NormalizedPrototype } from '../../types/index.js';
+import type { ValidationErrorCode, ValidationResult } from './types.js';
+/**
+ * Validate a NormalizedPrototype object.
+ *
+ * Validates that the data conforms to the NormalizedPrototype schema,
+ * including field types, required properties, and ID constraints.
+ *
+ * @param data - Data to validate
+ * @param logger - Optional logger for validation events
+ * @returns Validation result with typed data or error details
+ *
+ * @example
+ * ```ts
+ * const result = validateNormalizedPrototype(data);
+ * if (result.ok) {
+ *   // data is NormalizedPrototype
+ *   console.log(`Prototype ID: ${result.data.id}`);
+ * } else {
+ *   console.error(result.message);
+ * }
+ * ```
+ */
+export declare function validateNormalizedPrototype(data: unknown, logger?: Logger): ValidationResult<NormalizedPrototype, ValidationErrorCode>;
+/**
+ * Validate an array of NormalizedPrototype objects.
+ *
+ * Validates that the data is an array and each element conforms to
+ * the NormalizedPrototype schema. Uses Zod's fail-fast behavior,
+ * stopping at the first validation error.
+ *
+ * @param data - Data to validate (should be an array)
+ * @param logger - Optional logger for validation events
+ * @returns Validation result with typed data array or error details
+ *
+ * @example
+ * ```ts
+ * const result = validateNormalizedPrototypeArray(data);
+ * if (result.ok) {
+ *   // data is NormalizedPrototype[]
+ *   console.log(`Validated ${result.data.length} prototypes`);
+ * } else {
+ *   console.error(result.message);
+ * }
+ * ```
+ *
+ * @remarks
+ * - Uses Zod's default fail-fast behavior (stops at first error)
+ * - For large datasets (5000+ items), this is more efficient than
+ *   validating each item individually
+ * - Memory usage: ~2x input size at peak due to Zod's immutable design
+ */
+export declare function validateNormalizedPrototypeArray(data: unknown, logger?: Logger): ValidationResult<NormalizedPrototype[], ValidationErrorCode>;
+//# sourceMappingURL=normalized-prototype.d.ts.map

package/dist/utils/validation/normalized-prototype.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalized-prototype.d.ts","sourceRoot":"","sources":["../../../lib/utils/validation/normalized-prototype.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,8BAA8B,CAAC;AAE3D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAEhE,OAAO,KAAK,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAExE;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,2BAA2B,CACzC,IAAI,EAAE,OAAO,EACb,MAAM,CAAC,EAAE,MAAM,GACd,gBAAgB,CAAC,mBAAmB,EAAE,mBAAmB,CAAC,CA0B5D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,gCAAgC,CAC9C,IAAI,EAAE,OAAO,EACb,MAAM,CAAC,EAAE,MAAM,GACd,gBAAgB,CAAC,mBAAmB,EAAE,EAAE,mBAAmB,CAAC,CA0B9D"}

package/dist/utils/validation/normalized-prototype.js

@@ -0,0 +1,97 @@
+import { normalizedPrototypeSchema } from '../../schemas/index.js';
+/**
+ * Validate a NormalizedPrototype object.
+ *
+ * Validates that the data conforms to the NormalizedPrototype schema,
+ * including field types, required properties, and ID constraints.
+ *
+ * @param data - Data to validate
+ * @param logger - Optional logger for validation events
+ * @returns Validation result with typed data or error details
+ *
+ * @example
+ * ```ts
+ * const result = validateNormalizedPrototype(data);
+ * if (result.ok) {
+ *   // data is NormalizedPrototype
+ *   console.log(`Prototype ID: ${result.data.id}`);
+ * } else {
+ *   console.error(result.message);
+ * }
+ * ```
+ */
+export function validateNormalizedPrototype(data, logger) {
+    const validationResult = normalizedPrototypeSchema.safeParse(data);
+    if (!validationResult.success) {
+        logger?.warn('Prototype data validation failed', {
+            errors: validationResult.error.issues,
+        });
+        return {
+            ok: false,
+            code: 'VALIDATION_ERROR',
+            message: validationResult.error.issues
+                .map((issue) => `${issue.path.join('.')}: ${issue.message}`)
+                .join('; '),
+        };
+    }
+    logger?.info('Prototype data validated successfully', {
+        id: validationResult.data.id,
+        prototypeNm: validationResult.data.prototypeNm,
+    });
+    return {
+        ok: true,
+        data: validationResult.data,
+    };
+}
+/**
+ * Validate an array of NormalizedPrototype objects.
+ *
+ * Validates that the data is an array and each element conforms to
+ * the NormalizedPrototype schema. Uses Zod's fail-fast behavior,
+ * stopping at the first validation error.
+ *
+ * @param data - Data to validate (should be an array)
+ * @param logger - Optional logger for validation events
+ * @returns Validation result with typed data array or error details
+ *
+ * @example
+ * ```ts
+ * const result = validateNormalizedPrototypeArray(data);
+ * if (result.ok) {
+ *   // data is NormalizedPrototype[]
+ *   console.log(`Validated ${result.data.length} prototypes`);
+ * } else {
+ *   console.error(result.message);
+ * }
+ * ```
+ *
+ * @remarks
+ * - Uses Zod's default fail-fast behavior (stops at first error)
+ * - For large datasets (5000+ items), this is more efficient than
+ *   validating each item individually
+ * - Memory usage: ~2x input size at peak due to Zod's immutable design
+ */
+export function validateNormalizedPrototypeArray(data, logger) {
+    const arraySchema = normalizedPrototypeSchema.array();
+    const validationResult = arraySchema.safeParse(data);
+    if (!validationResult.success) {
+        logger?.warn('Prototype array validation failed', {
+            errors: validationResult.error.issues,
+        });
+        return {
+            ok: false,
+            code: 'VALIDATION_ERROR',
+            message: validationResult.error.issues
+                .map((issue) => `${issue.path.join('.')}: ${issue.message}`)
+                .join('; '),
+        };
+    }
+    logger?.info('Prototype array validated successfully', {
+        count: validationResult.data.length,
+    });
+    return {
+        ok: true,
+        data: validationResult.data,
+    };
+}
+//# sourceMappingURL=normalized-prototype.js.map

package/dist/utils/validation/normalized-prototype.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalized-prototype.js","sourceRoot":"","sources":["../../../lib/utils/validation/normalized-prototype.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,yBAAyB,EAAE,MAAM,wBAAwB,CAAC;AAKnE;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,2BAA2B,CACzC,IAAa,EACb,MAAe;IAEf,MAAM,gBAAgB,GAAG,yBAAyB,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;IAEnE,IAAI,CAAC,gBAAgB,CAAC,OAAO,EAAE,CAAC;QAC9B,MAAM,EAAE,IAAI,CAAC,kCAAkC,EAAE;YAC/C,MAAM,EAAE,gBAAgB,CAAC,KAAK,CAAC,MAAM;SACtC,CAAC,CAAC;QAEH,OAAO;YACL,EAAE,EAAE,KAAK;YACT,IAAI,EAAE,kBAAkB;YACxB,OAAO,EAAE,gBAAgB,CAAC,KAAK,CAAC,MAAM;iBACnC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC;iBAC3D,IAAI,CAAC,IAAI,CAAC;SACd,CAAC;IACJ,CAAC;IAED,MAAM,EAAE,IAAI,CAAC,uCAAuC,EAAE;QACpD,EAAE,EAAE,gBAAgB,CAAC,IAAI,CAAC,EAAE;QAC5B,WAAW,EAAE,gBAAgB,CAAC,IAAI,CAAC,WAAW;KAC/C,CAAC,CAAC;IAEH,OAAO;QACL,EAAE,EAAE,IAAI;QACR,IAAI,EAAE,gBAAgB,CAAC,IAAI;KAC5B,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,UAAU,gCAAgC,CAC9C,IAAa,EACb,MAAe;IAEf,MAAM,WAAW,GAAG,yBAAyB,CAAC,KAAK,EAAE,CAAC;IACtD,MAAM,gBAAgB,GAAG,WAAW,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;IAErD,IAAI,CAAC,gBAAgB,CAAC,OAAO,EAAE,CAAC;QAC9B,MAAM,EAAE,IAAI,CAAC,mCAAmC,EAAE;YAChD,MAAM,EAAE,gBAAgB,CAAC,KAAK,CAAC,MAAM;SACtC,CAAC,CAAC;QAEH,OAAO;YACL,EAAE,EAAE,KAAK;YACT,IAAI,EAAE,kBAAkB;YACxB,OAAO,EAAE,gBAAgB,CAAC,KAAK,CAAC,MAAM;iBACnC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC;iBAC3D,IAAI,CAAC,IAAI,CAAC;SACd,CAAC;IACJ,CAAC;IAED,MAAM,EAAE,IAAI,CAAC,wCAAwC,EAAE;QACrD,KAAK,EAAE,gBAAgB,CAAC,IAAI,CAAC,MAAM;KACpC,CAAC,CAAC;IAEH,OAAO;QACL,EAAE,EAAE,IAAI;QACR,IAAI,EAAE,gBAAgB,CAAC,IAAI;KAC5B,CAAC;AACJ,CAAC"}

package/dist/utils/validation/types.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Validation result types.
+ *
+ * This module provides common type definitions for validation operations
+ * that return Result types instead of throwing exceptions.
+ */
+/**
+ * Validation success result.
+ *
+ * @template T - The type of the validated data
+ */
+export type ValidationSuccess<T> = {
+    ok: true;
+    data: T;
+};
+/**
+ * Validation failure result.
+ *
+ * @template TErrorCode - The type of the error code (defaults to string)
+ */
+export type ValidationFailure<TErrorCode extends string = string> = {
+    ok: false;
+    code: TErrorCode;
+    message: string;
+};
+/**
+ * Validation error code for common data validation.
+ */
+export type ValidationErrorCode = 'VALIDATION_ERROR';
+/**
+ * Validation result type.
+ *
+ * A discriminated union type representing the result of a validation operation.
+ * Returns either success with typed data or failure with error details.
+ *
+ * @template T - The type of the validated data on success
+ * @template TErrorCode - The type of the error code (defaults to string)
+ *
+ * @example
+ * ```ts
+ * // With specific error code
+ * type MyErrorCode = 'VALIDATION_ERROR' | 'PARSE_ERROR';
+ * function validate(data: unknown): ValidationResult<MyType, MyErrorCode> {
+ *   if (isValid(data)) {
+ *     return { ok: true, data };
+ *   } else {
+ *     return { ok: false, code: 'VALIDATION_ERROR', message: 'Invalid data' };
+ *   }
+ * }
+ *
+ * // With default error code (string)
+ * function simpleValidate(data: unknown): ValidationResult<MyType> {
+ *   if (isValid(data)) {
+ *     return { ok: true, data };
+ *   } else {
+ *     return { ok: false, code: 'ERROR', message: 'Invalid' };
+ *   }
+ * }
+ * ```
+ */
+export type ValidationResult<T, TErrorCode extends string = string> = ValidationSuccess<T> | ValidationFailure<TErrorCode>;
+//# sourceMappingURL=types.d.ts.map

package/dist/utils/validation/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../lib/utils/validation/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,CAAC,CAAC,IAAI;IACjC,EAAE,EAAE,IAAI,CAAC;IACT,IAAI,EAAE,CAAC,CAAC;CACT,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,CAAC,UAAU,SAAS,MAAM,GAAG,MAAM,IAAI;IAClE,EAAE,EAAE,KAAK,CAAC;IACV,IAAI,EAAE,UAAU,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG,kBAAkB,CAAC;AAErD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,MAAM,gBAAgB,CAAC,CAAC,EAAE,UAAU,SAAS,MAAM,GAAG,MAAM,IAC9D,iBAAiB,CAAC,CAAC,CAAC,GACpB,iBAAiB,CAAC,UAAU,CAAC,CAAC"}

package/dist/utils/validation/types.js

@@ -0,0 +1,8 @@
+/**
+ * Validation result types.
+ *
+ * This module provides common type definitions for validation operations
+ * that return Result types instead of throwing exceptions.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/utils/validation/types.js.map

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

package/dist/version.d.ts

@@ -0,0 +1,6 @@
+/**
+ * This file is auto-generated by scripts/generate-version.mjs
+ * Do not edit manually.
+ */
+export declare const VERSION = "2.0.0";
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../lib/version.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,eAAO,MAAM,OAAO,UAAU,CAAC"}

package/dist/version.js

@@ -0,0 +1,6 @@
+/**
+ * This file is auto-generated by scripts/generate-version.mjs
+ * Do not edit manually.
+ */
+export const VERSION = '2.0.0';
+//# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../lib/version.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC"}