@withstudiocms/effect/dist/clack.d.ts

Effect-TS Utilities for Astro

import type { ClackSettings, ConfirmOptions, GroupMultiSelectOptions, LogMessageOptions, MultiSelectOptions, PasswordOptions, PromptGroup, PromptGroupOptions, SelectOptions, SpinnerOptions, Task, TextOptions } from '@clack/prompts';
import * as ClackPrompts from '@clack/prompts';
import { Effect } from './effect.js';
export type { ClackSettings, ConfirmOptions, GroupMultiSelectOptions, LogMessageOptions, MultiSelectOptions, Option, PasswordOptions, PromptGroup, PromptGroupAwaitedReturn, PromptGroupOptions, SelectOptions, SpinnerOptions, Task, TextOptions, } from '@clack/prompts';
declare const ClackError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => import("effect/Cause").YieldableError & {
    readonly _tag: "ClackError";
} & Readonly<A>;
/**
 * Represents a custom error type for Clack-related operations.
 * Extends a tagged error with the tag 'ClackError' and includes an optional cause.
 *
 * @extends Data.TaggedError
 * @template { cause: unknown } - The shape of the error details.
 *
 * @example
 * throw new ClackError({ cause: someError });
 */
export declare class ClackError extends ClackError_base<{
    cause: unknown;
}> {
}
/**
 * Executes a function within an Effect, capturing any thrown errors and wrapping them in a `ClackError`.
 *
 * @template A - The type of the value returned by the function.
 * @param _try - A function to execute that may throw an error.
 * @returns An `Effect` that yields the result of the function or a `ClackError` if an error is thrown.
 */
export declare const useClackError: <A>(_try: () => A) => Effect.Effect<A, ClackError>;
/**
 * Wraps a promise-returning function in an Effect, mapping any thrown error to a `ClackError`.
 *
 * @template A The type of the resolved value of the promise.
 * @param _try A function that returns a promise of type `A`.
 * @returns An `Effect` that resolves with the value of type `A` or fails with a `ClackError`.
 */
export declare const useClackErrorPromise: <A>(_try: () => Promise<A>) => Effect.Effect<A, ClackError>;
/**
 * Cancels the current Clack operation and optionally displays an error message.
 *
 * This function wraps the `clackCancel` operation with error handling using `useClackError`.
 *
 * @param message - Optional error message to display when cancelling the operation.
 * @returns An Effect representing the cancellation operation.
 */
export declare const cancel: (message?: string | undefined) => Effect.Effect<void, ClackError, never>;
/**
 * Prompts the user for confirmation using the Clack UI and handles errors with `useClackError`.
 *
 * @param options - The configuration options for the confirmation prompt.
 * @returns An Effect that resolves to the user's confirmation response.
 */
export declare const confirm: (options: ConfirmOptions) => Effect.Effect<boolean | symbol, ClackError, never>;
/**
 * Groups multiple prompts together and executes them as a single operation.
 * Utilizes error handling via `useClackError` to wrap the `clackGroup` execution.
 *
 * @typeParam T - The type of the data returned by the prompt group.
 * @param prompts - The group of prompts to be executed.
 * @param opts - Optional configuration options for the prompt group.
 * @returns The result of the grouped prompts, with error handling applied.
 */
export declare const group: <T>(prompts: PromptGroup<T>, opts?: PromptGroupOptions<T>) => Effect.Effect<{ [P in keyof ClackPrompts.PromptGroupAwaitedReturn<T>]: ClackPrompts.PromptGroupAwaitedReturn<T>[P]; }, ClackError, never>;
/**
 * Wraps the `clackGroupMultiselect` function with error handling using `useClackError`.
 *
 * @template T - The type of the selectable items.
 * @param options - The configuration options for the group multi-select prompt.
 * @returns The result of the group multi-select operation, with error handling applied.
 */
export declare const groupMultiselect: <T>(options: GroupMultiSelectOptions<T>) => Effect.Effect<symbol | T[], ClackError, never>;
/**
 * Displays an introductory message using the Clack library within an Effect context.
 *
 * @param message - The message to display as an introduction.
 * @returns An Effect that, when executed, shows the intro message and handles any Clack-related errors.
 */
export declare const intro: (message: string) => Effect.Effect<void, ClackError, never>;
/**
 * Determines if the provided value represents a cancellation event.
 *
 * This function wraps the `clackIsCancel` utility with error handling via `useClackError`.
 * It is useful for checking if a value indicates a user-initiated cancellation in Clack-based workflows.
 *
 * @param value - The value to check for cancellation.
 * @returns `true` if the value represents a cancellation, otherwise `false`.
 */
export declare const isCancel: (value: unknown) => Effect.Effect<boolean, ClackError, never>;
/**
 * Presents a multi-select prompt to the user with error handling.
 *
 * @typeParam T - The type of the selectable options.
 * @param options - The configuration options for the multi-select prompt.
 * @returns The result of the multi-select prompt, wrapped with error handling.
 */
export declare const multiselect: <T>(options: MultiSelectOptions<T>) => Effect.Effect<symbol | T[], ClackError, never>;
/**
 * Displays a note message using the Clack notification system.
 *
 * @param message - Optional message to display in the note.
 * @param title - Optional title for the note.
 * @returns An Effect that triggers the note display, handling any Clack errors.
 */
export declare const note: (message?: string | undefined, title?: string | undefined) => Effect.Effect<void, ClackError, never>;
/**
 * Displays an outro message using the Clack library, handling any errors that may occur.
 *
 * @param message - Optional message to display as the outro.
 * @returns An Effect that executes the outro logic with error handling.
 */
export declare const outro: (message?: string | undefined) => Effect.Effect<void, ClackError, never>;
/**
 * Prompts the user for a password input using the Clack library, with error handling.
 *
 * @param options - Configuration options for the password prompt.
 * @returns The result of the password prompt, potentially wrapped with error handling.
 *
 * @remarks
 * This function wraps the `clackPassword` prompt with `useClackError` to provide consistent error handling.
 */
export declare const password: (options: PasswordOptions) => Effect.Effect<string | symbol, ClackError, never>;
/**
 * Presents a selection prompt to the user using Clack, handling errors gracefully.
 *
 * @typeParam T - The type of the selectable options.
 * @param options - The configuration options for the selection prompt.
 * @returns The selected option of type `T`.
 */
export declare const select: <T>(options: SelectOptions<T>) => Effect.Effect<symbol | T, ClackError, never>;
/**
 * Prompts the user to select a key from the provided options and handles errors using `useClackError`.
 *
 * @template T - The type of the selectable keys, constrained to `string`.
 * @param options - The selection options to present to the user.
 * @returns The selected key of type `T`.
 */
export declare const selectKey: <T extends string>(options: SelectOptions<T>) => Effect.Effect<symbol | T, ClackError, never>;
/**
 * Executes a list of tasks using the `clackTasks` function and wraps the execution with error handling provided by `useClackError`.
 *
 * @param tasks - An array of `Task` objects to be executed.
 * @returns The result of the `clackTasks` execution, potentially wrapped or modified by `useClackError`.
 */
export declare const tasks: (tasks: Task[]) => Effect.Effect<void, ClackError, never>;
/**
 * Displays a text prompt using Clack, handling any errors that may occur.
 *
 * @param options - The options to configure the text prompt.
 * @returns The result of the text prompt, or an error if one occurs.
 */
export declare const text: (options: TextOptions) => Effect.Effect<string | symbol, ClackError, never>;
/**
 * Updates the Clack settings by applying the provided updates.
 * Utilizes `useClackError` to handle any errors that may occur during the update process.
 *
 * @param updates - An object containing the new settings to apply.
 * @returns The result of the `clackUpdateSettings` function, wrapped with error handling.
 */
export declare const updateSettings: (updates: ClackSettings) => Effect.Effect<void, ClackError, never>;
/**
 * Creates a spinner utility with customizable indicator.
 *
 * @param {SpinnerOptions} [options] - Options for the spinner, including an optional `indicator` string.
 *
 * All methods are wrapped with `useClackError` for error handling.
 */
export declare const spinner: (options?: SpinnerOptions | undefined) => Effect.Effect<{
    start: (msg?: string) => Effect.Effect<void, ClackError, never>;
    stop: (msg?: string, code?: number) => Effect.Effect<void, ClackError, never>;
    message: (msg?: string) => Effect.Effect<void, ClackError, never>;
}, ClackError, never>;
/**
 * Prompts the user with a confirmation message and returns whether to continue.
 *
 * @param userOpts - Options for the confirmation prompt.
 * @param userOpts.message - The message to display to the user. Defaults to "Continue?".
 * @returns A boolean indicating whether the user chose to continue (`true`) or cancel (`false`).
 */
export declare const askToContinue: (userOpts?: {
    message: string;
} | undefined) => Effect.Effect<boolean, Error, never>;
/**
 * Provides a set of logging utilities wrapped with effectful error handling.
 * Each method logs a message using the underlying `clackLog` implementation,
 * and handles errors via `useClackError`.
 *
 * @property message Logs a general message. Accepts an optional message and options.
 * @property success Logs a success message.
 * @property step Logs a step message, typically used for progress indication.
 * @property warn Logs a warning message.
 * @property warning Logs a warning message (alias for `warn`).
 * @property error Logs an error message.
 * @property info Logs an informational message.
 */
export declare const log: {
    message: (message?: string | undefined, options?: LogMessageOptions | undefined) => Effect.Effect<void, ClackError, never>;
    success: (message: string) => Effect.Effect<void, ClackError, never>;
    step: (message: string) => Effect.Effect<void, ClackError, never>;
    warn: (message: string) => Effect.Effect<void, ClackError, never>;
    warning: (message: string) => Effect.Effect<void, ClackError, never>;
    error: (message: string) => Effect.Effect<void, ClackError, never>;
    info: (message: string) => Effect.Effect<void, ClackError, never>;
};
/**
 * Provides streaming logging methods wrapped in Effect functions,
 * with unified error handling via `useClackError`.
 *
 * Each method accepts an `Iterable<string>` or `AsyncIterable<string>` to stream messages,
 * and optionally accepts `LogMessageOptions` for the `message` method.
 *
 * Methods:
 * - `message`: Streams a general message, optionally with log options.
 * - `info`: Streams informational messages.
 * - `success`: Streams success messages.
 * - `step`: Streams step/progress messages.
 * - `warn`: Streams warning messages.
 * - `warning`: Alias for `warn`, streams warning messages.
 * - `error`: Streams error messages.
 */
export declare const stream: {
    message: (iterable: Iterable<string> | AsyncIterable<string>, options?: LogMessageOptions | undefined) => Effect.Effect<void, ClackError, never>;
    info: (iterable: Iterable<string> | AsyncIterable<string>) => Effect.Effect<void, ClackError, never>;
    success: (iterable: Iterable<string> | AsyncIterable<string>) => Effect.Effect<void, ClackError, never>;
    step: (iterable: Iterable<string> | AsyncIterable<string>) => Effect.Effect<void, ClackError, never>;
    warn: (iterable: Iterable<string> | AsyncIterable<string>) => Effect.Effect<void, ClackError, never>;
    warning: (iterable: Iterable<string> | AsyncIterable<string>) => Effect.Effect<void, ClackError, never>;
    error: (iterable: Iterable<string> | AsyncIterable<string>) => Effect.Effect<void, ClackError, never>;
};