promptspeak-mcp-server 0.1.0

package/dist/core/result/builders.d.ts

@@ -0,0 +1,310 @@
+/**
+ * ===============================================================================
+ * RESULT BUILDERS AND UTILITIES
+ * ===============================================================================
+ *
+ * Fluent builders for creating Result types, type guards, and utility functions
+ * for working with Result values.
+ *
+ * ===============================================================================
+ */
+import type { Result, Success, Failure, ResultMetadata, ResultError, LegacyResult } from './types.js';
+/**
+ * Creates a Success result with the given data.
+ *
+ * @param data - The successful result data
+ * @param metadata - Optional metadata about the operation
+ * @returns A Success result
+ *
+ * @example
+ * ```typescript
+ * const result = success({ id: 1, name: 'Alice' });
+ * // result.success === true
+ * // result.data === { id: 1, name: 'Alice' }
+ * ```
+ */
+export declare function success<T>(data: T, metadata?: ResultMetadata): Success<T>;
+/**
+ * Creates a Failure result with the given error information.
+ *
+ * @param code - Machine-readable error code
+ * @param message - Human-readable error message
+ * @param options - Additional error options
+ * @returns A Failure result
+ *
+ * @example
+ * ```typescript
+ * const result = failure('NOT_FOUND', 'User not found', { details: { userId: 123 } });
+ * // result.success === false
+ * // result.error.code === 'NOT_FOUND'
+ * ```
+ */
+export declare function failure(code: string, message: string, options?: {
+    details?: Record<string, unknown>;
+    retryable?: boolean;
+    retryAfterMs?: number;
+    cause?: ResultError;
+    metadata?: ResultMetadata;
+}): Failure;
+/**
+ * Interface for errors that have a code property.
+ * Used by fromError to extract structured error information.
+ */
+interface CodedError extends Error {
+    code?: string;
+    details?: Record<string, unknown>;
+    retryable?: boolean;
+}
+/**
+ * Creates a Failure result from an Error object.
+ * Extracts code and details if available (e.g., from PromptSpeakError).
+ *
+ * @param error - The error to convert
+ * @param defaultCode - Default error code if none is present on the error
+ * @returns A Failure result
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await riskyOperation();
+ * } catch (err) {
+ *   return fromError(err);
+ * }
+ * ```
+ */
+export declare function fromError(error: Error | CodedError | unknown, defaultCode?: string): Failure;
+/**
+ * Wraps a Promise to return a Result instead of throwing.
+ *
+ * @param promise - The promise to wrap
+ * @param errorCode - Error code to use if the promise rejects
+ * @returns A Promise that resolves to a Result
+ *
+ * @example
+ * ```typescript
+ * const result = await fromPromise(fetchUser(id), 'FETCH_USER_FAILED');
+ * if (isSuccess(result)) {
+ *   console.log(result.data);
+ * }
+ * ```
+ */
+export declare function fromPromise<T>(promise: Promise<T>, errorCode?: string): Promise<Result<T>>;
+/**
+ * Wraps a synchronous function to return a Result instead of throwing.
+ *
+ * @param fn - The function to wrap
+ * @param errorCode - Error code to use if the function throws
+ * @returns A Result
+ *
+ * @example
+ * ```typescript
+ * const result = fromThrowable(() => JSON.parse(jsonString), 'PARSE_FAILED');
+ * ```
+ */
+export declare function fromThrowable<T>(fn: () => T, errorCode?: string): Result<T>;
+/**
+ * Type guard to check if a Result is a Success.
+ *
+ * @param result - The result to check
+ * @returns True if the result is a Success
+ *
+ * @example
+ * ```typescript
+ * if (isSuccess(result)) {
+ *   // TypeScript knows result.data exists
+ *   console.log(result.data);
+ * }
+ * ```
+ */
+export declare function isSuccess<T>(result: Result<T>): result is Success<T>;
+/**
+ * Type guard to check if a Result is a Failure.
+ *
+ * @param result - The result to check
+ * @returns True if the result is a Failure
+ *
+ * @example
+ * ```typescript
+ * if (isFailure(result)) {
+ *   // TypeScript knows result.error exists
+ *   console.error(result.error.message);
+ * }
+ * ```
+ */
+export declare function isFailure<T>(result: Result<T>): result is Failure;
+/**
+ * Type guard to check if an error is retryable.
+ *
+ * @param result - The failure result to check
+ * @returns True if the operation can be retried
+ */
+export declare function isRetryable(result: Failure): boolean;
+/**
+ * Error thrown when unwrapping a Failure result.
+ */
+export declare class UnwrapError extends Error {
+    readonly error: ResultError;
+    constructor(error: ResultError);
+}
+/**
+ * Extracts the data from a Success result.
+ * Throws UnwrapError if the result is a Failure.
+ *
+ * @param result - The result to unwrap
+ * @returns The success data
+ * @throws UnwrapError if the result is a Failure
+ *
+ * @example
+ * ```typescript
+ * const user = unwrap(result);  // Throws if result is Failure
+ * ```
+ */
+export declare function unwrap<T>(result: Result<T>): T;
+/**
+ * Extracts the data from a Success result, or returns a default value.
+ *
+ * @param result - The result to unwrap
+ * @param defaultValue - Value to return if result is Failure
+ * @returns The success data or the default value
+ *
+ * @example
+ * ```typescript
+ * const user = unwrapOr(result, defaultUser);
+ * ```
+ */
+export declare function unwrapOr<T>(result: Result<T>, defaultValue: T): T;
+/**
+ * Extracts the data from a Success result, or computes a default lazily.
+ *
+ * @param result - The result to unwrap
+ * @param defaultFn - Function that returns the default value
+ * @returns The success data or the computed default value
+ *
+ * @example
+ * ```typescript
+ * const user = unwrapOrElse(result, () => createDefaultUser());
+ * ```
+ */
+export declare function unwrapOrElse<T>(result: Result<T>, defaultFn: () => T): T;
+/**
+ * Extracts the error from a Failure result.
+ * Throws if the result is a Success.
+ *
+ * @param result - The result to unwrap
+ * @returns The error
+ * @throws Error if the result is a Success
+ */
+export declare function unwrapError<T>(result: Result<T>): ResultError;
+/**
+ * Maps a Success value to a new value using the provided function.
+ * If the result is a Failure, returns the Failure unchanged.
+ *
+ * @param result - The result to map
+ * @param fn - Function to transform the success data
+ * @returns A new Result with the transformed data
+ *
+ * @example
+ * ```typescript
+ * const nameResult = map(userResult, user => user.name);
+ * ```
+ */
+export declare function map<T, U>(result: Result<T>, fn: (data: T) => U): Result<U>;
+/**
+ * Maps a Failure error to a new error using the provided function.
+ * If the result is a Success, returns the Success unchanged.
+ *
+ * @param result - The result to map
+ * @param fn - Function to transform the error
+ * @returns A new Result with the transformed error
+ */
+export declare function mapError<T>(result: Result<T>, fn: (error: ResultError) => ResultError): Result<T>;
+/**
+ * Chains a Result with a function that returns another Result.
+ * Also known as flatMap or bind.
+ *
+ * @param result - The result to chain
+ * @param fn - Function that takes the success data and returns a new Result
+ * @returns The chained Result
+ *
+ * @example
+ * ```typescript
+ * const result = flatMap(userResult, user => fetchPosts(user.id));
+ * ```
+ */
+export declare function flatMap<T, U>(result: Result<T>, fn: (data: T) => Result<U>): Result<U>;
+/**
+ * Async version of flatMap for chaining async operations.
+ *
+ * @param result - The result to chain
+ * @param fn - Async function that takes the success data and returns a new Result
+ * @returns A Promise that resolves to the chained Result
+ */
+export declare function flatMapAsync<T, U>(result: Result<T>, fn: (data: T) => Promise<Result<U>>): Promise<Result<U>>;
+/**
+ * Applies one of two functions depending on success/failure.
+ *
+ * @param result - The result to match
+ * @param onSuccess - Function to call with success data
+ * @param onFailure - Function to call with error
+ * @returns The return value of the matched function
+ *
+ * @example
+ * ```typescript
+ * const message = match(
+ *   result,
+ *   user => `Hello, ${user.name}!`,
+ *   error => `Error: ${error.message}`
+ * );
+ * ```
+ */
+export declare function match<T, U>(result: Result<T>, onSuccess: (data: T) => U, onFailure: (error: ResultError) => U): U;
+/**
+ * Combines multiple Results into a single Result containing an array.
+ * If any Result is a Failure, returns the first Failure.
+ *
+ * @param results - Array of Results to combine
+ * @returns A Result containing an array of all success values
+ *
+ * @example
+ * ```typescript
+ * const combined = all([result1, result2, result3]);
+ * if (isSuccess(combined)) {
+ *   const [a, b, c] = combined.data;
+ * }
+ * ```
+ */
+export declare function all<T>(results: Array<Result<T>>): Result<T[]>;
+/**
+ * Combines multiple Results, collecting all successes and failures.
+ * Unlike `all`, this processes all results even if some fail.
+ *
+ * @param results - Array of Results to partition
+ * @returns Object containing arrays of successes and failures
+ */
+export declare function partition<T>(results: Array<Result<T>>): {
+    successes: T[];
+    failures: Failure[];
+};
+/**
+ * Converts a legacy result format to the new Result type.
+ *
+ * @param legacy - Legacy result object
+ * @param dataKey - Key to extract data from (default: 'data')
+ * @returns A proper Result type
+ *
+ * @example
+ * ```typescript
+ * const legacyResult = { success: true, user: { id: 1 } };
+ * const result = fromLegacy(legacyResult, 'user');
+ * ```
+ */
+export declare function fromLegacy<T>(legacy: LegacyResult<T>, dataKey?: string): Result<T>;
+/**
+ * Converts a Result to the legacy format for backward compatibility.
+ *
+ * @param result - The Result to convert
+ * @returns A legacy result object
+ */
+export declare function toLegacy<T>(result: Result<T>): LegacyResult<T>;
+export {};
+//# sourceMappingURL=builders.d.ts.map

package/dist/core/result/builders.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builders.d.ts","sourceRoot":"","sources":["../../../src/core/result/builders.ts"],"names":[],"mappings":"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"}