@reliverse/rempts-utils 2.3.1

package/README.md

@@ -0,0 +1,162 @@
+# rempts-utils
+
+Utility functions for building CLI applications with Rempts.
+
+## Installation
+
+```bash
+bun add rempts-utils
+```
+
+## Features
+
+- 🎨 **Colors** - Terminal colors and styling
+- 💬 **Prompts** - Interactive prompts and confirmations
+- ⏳ **Spinners** - Loading indicators
+- 📋 **Formatting** - Tables, lists, and text formatting
+- 🔍 **Validation** - Input validation helpers
+
+## Usage
+
+### Colors
+
+Style your terminal output:
+
+```typescript
+import { colors } from '@reliverse/rempts-utils'
+
+console.log(relico.green('✓ Success!'))
+console.log(relico.red('✗ Error!'))
+console.log(relico.blue('ℹ Info'))
+console.log(relico.yellow('⚠ Warning'))
+console.log(relico.bold('Bold text'))
+console.log(relico.dim('Dimmed text'))
+```
+
+### Prompts
+
+Interactive user input:
+
+```typescript
+import { prompt, confirm, select } from '@reliverse/rempts-utils'
+
+// Text input
+const name = await prompt({
+  message: 'What is your name?',
+  default: 'Anonymous',
+  validate: (value) => value.length > 0
+})
+
+// Confirmation
+const proceed = await confirm({
+  message: 'Do you want to continue?',
+  default: true
+})
+
+// Selection
+const choice = await select({
+  message: 'Choose your favorite framework',
+  options: [
+    { label: 'Bun', value: 'bun' },
+    { label: 'Node.js', value: 'node' },
+    { label: 'Deno', value: 'deno' }
+  ]
+})
+```
+
+### Spinners
+
+Show progress for long-running tasks:
+
+```typescript
+import { spinner } from '@reliverse/rempts-utils'
+
+const spin = spinner()
+spin.start('Loading...')
+
+// Do some work
+await someAsyncTask()
+
+spin.success('Done!')
+// or
+spin.error('Failed!')
+// or
+spin.stop()
+```
+
+### Tables
+
+Display structured data:
+
+```typescript
+import { table } from '@reliverse/rempts-utils'
+
+const data = [
+  { name: 'John', age: 30, city: 'New York' },
+  { name: 'Jane', age: 25, city: 'London' },
+  { name: 'Bob', age: 35, city: 'Paris' }
+]
+
+console.log(table(data))
+```
+
+### Lists
+
+Format lists with bullets or numbers:
+
+```typescript
+import { list } from '@reliverse/rempts-utils'
+
+// Bullet list
+console.log(list([
+  'First item',
+  'Second item',
+  'Third item'
+]))
+
+// Numbered list
+console.log(list([
+  'First step',
+  'Second step',
+  'Third step'
+], { ordered: true }))
+```
+
+## API Reference
+
+### Colors
+
+- `relico.red(text)` - Red text
+- `relico.green(text)` - Green text
+- `relico.blue(text)` - Blue text
+- `relico.yellow(text)` - Yellow text
+- `relico.cyan(text)` - Cyan text
+- `relico.magenta(text)` - Magenta text
+- `relico.bold(text)` - Bold text
+- `relico.dim(text)` - Dimmed text
+- `relico.underline(text)` - Underlined text
+
+### Prompts
+
+- `prompt(options)` - Text input prompt
+- `confirm(options)` - Yes/no confirmation
+- `select(options)` - Single selection from list
+- `multiselect(options)` - Multiple selection from list
+
+### Spinners
+
+- `spinner(options)` - Create a new spinner instance
+- `spinner.start(message)` - Start spinning with message
+- `spinner.success(message)` - Stop with success message
+- `spinner.error(message)` - Stop with error message
+- `spinner.stop()` - Stop spinning
+
+### Formatting
+
+- `table(data, options)` - Format data as table
+- `list(items, options)` - Format items as list
+- `tree(data, options)` - Format hierarchical data as tree
+
+## License
+
+MIT © blefnk

package/dist/mod.d.ts

@@ -0,0 +1,8 @@
+import type { RemptsUtils } from "./types.js";
+export * from "./types.js";
+export declare const utils: RemptsUtils;
+export { createSpinner as spinner } from "./spinner.js";
+export declare const prompt: RemptsUtils["prompt"];
+export { getDotPath, SchemaError } from "@standard-schema/utils";
+export { confirm, password, select } from "./prompt.js";
+export { validate, validateFields } from "./validation.js";

package/dist/mod.js

@@ -0,0 +1,46 @@
+import { confirm, password, prompt as promptFn, select } from "./prompt.js";
+import { createSpinner } from "./spinner.js";
+export * from "./types.js";
+export const utils = {
+  prompt: Object.assign(promptFn, {
+    confirm,
+    select,
+    password,
+    text: (message, options) => promptFn(message, options),
+    multiselect: async (message, options) => {
+      const { options: choices } = options;
+      const selected = [];
+      console.log(message);
+      for (const choice of choices) {
+        const ok = await confirm(`Select ${choice.label}?`, { default: false });
+        if (ok) {
+          selected.push(choice.value);
+        }
+      }
+      return selected;
+    }
+  }),
+  spinner: createSpinner
+};
+export { createSpinner as spinner } from "./spinner.js";
+export const prompt = Object.assign(promptFn, {
+  confirm,
+  select,
+  password,
+  text: (message, options) => promptFn(message, options),
+  multiselect: async (message, options) => {
+    const { options: choices } = options;
+    const selected = [];
+    console.log(message);
+    for (const choice of choices) {
+      const ok = await confirm(`Select ${choice.label}?`, { default: false });
+      if (ok) {
+        selected.push(choice.value);
+      }
+    }
+    return selected;
+  }
+});
+export { getDotPath, SchemaError } from "@standard-schema/utils";
+export { confirm, password, select } from "./prompt.js";
+export { validate, validateFields } from "./validation.js";

package/dist/prompt.d.ts

@@ -0,0 +1,5 @@
+import type { ConfirmOptions, PromptOptions, SelectOptions } from "./types.js";
+export declare function prompt<T = string>(message: string, options?: PromptOptions): Promise<T>;
+export declare function confirm(message: string, options?: ConfirmOptions): Promise<boolean>;
+export declare function select<T = string>(message: string, options: SelectOptions<T>): Promise<T>;
+export declare function password<T = string>(message: string, options?: PromptOptions): Promise<T>;

package/dist/prompt.js

@@ -0,0 +1,172 @@
+import { relico } from "@reliverse/relico";
+const ESC = "\x1B";
+const CSI = `${ESC}[`;
+const CLEAR_LINE = `${CSI}2K`;
+const CURSOR_START = `${CSI}G`;
+const CURSOR_HIDE = `${CSI}?25l`;
+const CURSOR_SHOW = `${CSI}?25h`;
+async function readline(prompt2) {
+  process.stdout.write(prompt2);
+  for await (const line of console) {
+    return line;
+  }
+  return "";
+}
+export async function prompt(message, options = {}) {
+  const defaultHint = options.default ? ` (${options.default})` : "";
+  const promptText = `${message}${defaultHint} `;
+  while (true) {
+    const input = await readline(promptText);
+    const value = input.trim() || options.default || "";
+    if (options.schema) {
+      const result = await options.schema["~standard"].validate(value);
+      if (result.issues) {
+        console.error(relico.red("Invalid input:"));
+        for (const issue of result.issues) {
+          console.error(relico.dim(`  \u2022 ${issue.message}`));
+        }
+        console.error();
+        continue;
+      }
+      return result.value;
+    }
+    if (options.validate) {
+      const result = options.validate(value);
+      if (result === true) {
+        return value;
+      }
+      if (typeof result === "string") {
+        console.error(`\u2717 ${result}`);
+        continue;
+      }
+      console.error("\u2717 Invalid input");
+      continue;
+    }
+    return value;
+  }
+}
+export async function confirm(message, options = {}) {
+  const defaultHint = options.default === true ? "Y/n" : options.default === false ? "y/N" : "y/n";
+  const promptText = `${message} (${defaultHint}) `;
+  while (true) {
+    const input = await readline(promptText);
+    const value = input.trim().toLowerCase();
+    if (!value && options.default !== void 0) {
+      return options.default;
+    }
+    if (value === "y" || value === "yes") {
+      return true;
+    }
+    if (value === "n" || value === "no") {
+      return false;
+    }
+    console.error("\u2717 Please answer with y/yes or n/no");
+  }
+}
+export async function select(message, options) {
+  const { options: choices, default: defaultValue } = options;
+  let selectedIndex = defaultValue ? choices.findIndex((opt) => opt.value === defaultValue) : 0;
+  if (selectedIndex === -1) {
+    selectedIndex = 0;
+  }
+  console.log(message);
+  process.stdout.write(CURSOR_HIDE);
+  drawOptions(choices, selectedIndex);
+  return new Promise((resolve) => {
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    const cleanup = () => {
+      process.stdin.setRawMode(false);
+      process.stdin.pause();
+      process.stdout.write(CURSOR_SHOW);
+    };
+    process.stdin.on("data", (data) => {
+      const key = data.toString();
+      if (key === "\x1B[A") {
+        selectedIndex = Math.max(0, selectedIndex - 1);
+        drawOptions(choices, selectedIndex);
+      } else if (key === "\x1B[B") {
+        selectedIndex = Math.min(choices.length - 1, selectedIndex + 1);
+        drawOptions(choices, selectedIndex);
+      } else if (key === "\r" || key === "\n") {
+        cleanup();
+        for (let i = 0; i < choices.length; i++) {
+          process.stdout.write(`${CSI}1A${CLEAR_LINE}`);
+        }
+        const selected = choices[selectedIndex];
+        if (selected) {
+          console.log(`\u2713 ${selected.label}`);
+          resolve(selected.value);
+        }
+      } else if (key === "" || key === "\x1B") {
+        cleanup();
+        process.exit(0);
+      }
+    });
+  });
+}
+function drawOptions(options, selectedIndex) {
+  for (let i = 0; i < options.length; i++) {
+    process.stdout.write(`${CSI}1A`);
+  }
+  options.forEach((option, index) => {
+    process.stdout.write(CLEAR_LINE + CURSOR_START);
+    const prefix = index === selectedIndex ? "\u276F " : "  ";
+    const hint = option.hint ? ` (${option.hint})` : "";
+    console.log(`${prefix}${option.label}${hint}`);
+  });
+}
+export async function password(message, options = {}) {
+  process.stdout.write(`${message} `);
+  return new Promise((resolve) => {
+    let input = "";
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    const cleanup = () => {
+      process.stdin.setRawMode(false);
+      process.stdin.pause();
+      console.log();
+    };
+    process.stdin.on("data", async (data) => {
+      const key = data.toString();
+      if (key === "\r" || key === "\n") {
+        cleanup();
+        if (options.schema) {
+          const result = await options.schema["~standard"].validate(input);
+          if (result.issues) {
+            console.error(relico.red("Invalid input:"));
+            for (const issue of result.issues) {
+              console.error(relico.dim(`  \u2022 ${issue.message}`));
+            }
+            console.error();
+            password(message, options).then(resolve);
+            return;
+          }
+          resolve(result.value);
+        } else if (options.validate) {
+          const result = options.validate(input);
+          if (result === true) {
+            resolve(input);
+          } else {
+            const errorMsg = typeof result === "string" ? result : "Invalid input";
+            console.error(`\u2717 ${errorMsg}`);
+            password(message, options).then(resolve);
+          }
+        } else {
+          resolve(input);
+        }
+      } else if (key === "") {
+        cleanup();
+        process.exit(0);
+      } else if (key === "\x7F" || key === "\b") {
+        if (input.length > 0) {
+          input = input.slice(0, -1);
+          process.stdout.write("\b \b");
+        }
+      } else if (key.length === 1 && key >= " ") {
+        input += key;
+        process.stdout.write("*");
+      }
+    });
+  });
+}

package/dist/spinner.d.ts

@@ -0,0 +1,2 @@
+import type { Spinner, SpinnerOptions } from "./types.js";
+export declare function createSpinner(options?: SpinnerOptions | string): Spinner;

package/dist/spinner.js

@@ -0,0 +1,73 @@
+const SPINNER_FRAMES = ["\u280B", "\u2819", "\u2839", "\u2838", "\u283C", "\u2834", "\u2826", "\u2827", "\u2807", "\u280F"];
+const CLEAR_LINE = "\x1B[2K";
+const CURSOR_START = "\x1B[G";
+export function createSpinner(options) {
+  const config = typeof options === "string" ? { text: options } : options || {};
+  let isSpinning = false;
+  let frameIndex = 0;
+  let intervalId = null;
+  let currentText = config.text || "";
+  const render = (symbol, text) => {
+    process.stdout.write(`${CLEAR_LINE}${CURSOR_START}${symbol} ${text}`);
+  };
+  const spinner = {
+    start(text) {
+      if (isSpinning) {
+        return;
+      }
+      isSpinning = true;
+      if (text !== void 0) {
+        currentText = text;
+      }
+      process.stdout.write("\x1B[?25l");
+      intervalId = setInterval(() => {
+        const frame = SPINNER_FRAMES[frameIndex];
+        render(frame, currentText);
+        frameIndex = (frameIndex + 1) % SPINNER_FRAMES.length;
+      }, 80);
+    },
+    stop(text) {
+      if (!isSpinning) {
+        return;
+      }
+      isSpinning = false;
+      if (intervalId) {
+        clearInterval(intervalId);
+        intervalId = null;
+      }
+      process.stdout.write(CLEAR_LINE + CURSOR_START);
+      process.stdout.write("\x1B[?25h");
+      if (text) {
+        console.log(text);
+      }
+    },
+    succeed(text) {
+      this.stop();
+      console.log(`\u2705 ${text || currentText}`);
+    },
+    fail(text) {
+      this.stop();
+      console.log(`\u274C ${text || currentText}`);
+    },
+    warn(text) {
+      this.stop();
+      console.log(`\u26A0\uFE0F  ${text || currentText}`);
+    },
+    info(text) {
+      this.stop();
+      console.log(`\u2139\uFE0F  ${text || currentText}`);
+    },
+    update(text) {
+      currentText = text;
+      if (isSpinning) {
+        render(SPINNER_FRAMES[frameIndex], currentText);
+      }
+    }
+  };
+  process.on("exit", () => spinner.stop());
+  process.on("SIGINT", () => {
+    spinner.stop();
+    process.exit(0);
+  });
+  return spinner;
+}

package/dist/types.d.ts

@@ -0,0 +1,82 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+export interface PromptOptions {
+    default?: string;
+    validate?: (input: string) => boolean | string;
+    schema?: StandardSchemaV1;
+    placeholder?: string;
+    multiline?: boolean;
+}
+export interface ConfirmOptions {
+    default?: boolean;
+}
+export interface SelectOption<T = string> {
+    label: string;
+    value: T;
+    hint?: string;
+}
+export interface SelectOptions<T = string> {
+    options: SelectOption<T>[];
+    default?: T;
+    hint?: string;
+}
+export interface MultiSelectOptions<T = string> extends SelectOptions<T> {
+    min?: number;
+    max?: number;
+}
+export interface SpinnerOptions {
+    text?: string;
+    color?: string;
+}
+export interface Spinner {
+    start(text?: string): void;
+    stop(text?: string): void;
+    succeed(text?: string): void;
+    fail(text?: string): void;
+    warn(text?: string): void;
+    info(text?: string): void;
+    update(text: string): void;
+}
+export type ColorFunction = (text: string) => string;
+export interface Colors {
+    black: ColorFunction;
+    red: ColorFunction;
+    green: ColorFunction;
+    yellow: ColorFunction;
+    blue: ColorFunction;
+    magenta: ColorFunction;
+    cyan: ColorFunction;
+    white: ColorFunction;
+    gray: ColorFunction;
+    brightRed: ColorFunction;
+    brightGreen: ColorFunction;
+    brightYellow: ColorFunction;
+    brightBlue: ColorFunction;
+    brightMagenta: ColorFunction;
+    brightCyan: ColorFunction;
+    brightWhite: ColorFunction;
+    bgRed: ColorFunction;
+    bgGreen: ColorFunction;
+    bgYellow: ColorFunction;
+    bgBlue: ColorFunction;
+    bgMagenta: ColorFunction;
+    bgCyan: ColorFunction;
+    bgWhite: ColorFunction;
+    bold: ColorFunction;
+    dim: ColorFunction;
+    italic: ColorFunction;
+    underline: ColorFunction;
+    strikethrough: ColorFunction;
+    reset: ColorFunction;
+    strip: (text: string) => string;
+}
+export interface RemptsUtils {
+    prompt: {
+        <T = string>(message: string, options?: PromptOptions): Promise<T>;
+        confirm(message: string, options?: ConfirmOptions): Promise<boolean>;
+        select<T = string>(message: string, options: SelectOptions<T>): Promise<T>;
+        password<T = string>(message: string, options?: PromptOptions): Promise<T>;
+        text(message: string, options?: PromptOptions): Promise<string>;
+        multiselect<T = string>(message: string, options: MultiSelectOptions<T>): Promise<T[]>;
+    };
+    spinner: (options?: SpinnerOptions | string) => Spinner;
+}

package/dist/validation.d.ts

@@ -0,0 +1,13 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+/**
+ * Validate a value against a schema and throw SchemaError on failure
+ */
+export declare function validate<TSchema extends StandardSchemaV1>(schema: TSchema, value: unknown): Promise<StandardSchemaV1.InferOutput<TSchema>>;
+/**
+ * Validate multiple fields and return aggregated errors
+ */
+export declare function validateFields<T extends Record<string, StandardSchemaV1>>(schemas: T, values: Record<string, unknown>): Promise<{
+    [K in keyof T]: StandardSchemaV1.InferOutput<T[K]>;
+} | {
+    errors: Record<string, string[]>;
+}>;

package/dist/validation.js

@@ -0,0 +1,24 @@
+import { SchemaError } from "@standard-schema/utils";
+export async function validate(schema, value) {
+  const result = await schema["~standard"].validate(value);
+  if (result.issues) {
+    throw new SchemaError(result.issues);
+  }
+  return result.value;
+}
+export async function validateFields(schemas, values) {
+  const results = {};
+  const errors = {};
+  for (const [field, schema] of Object.entries(schemas)) {
+    const result = await schema["~standard"].validate(values[field]);
+    if (result.issues) {
+      errors[field] = result.issues.map((issue) => issue.message);
+    } else {
+      results[field] = result.value;
+    }
+  }
+  if (Object.keys(errors).length > 0) {
+    return { errors };
+  }
+  return results;
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@reliverse/rempts-utils",
+  "version": "2.3.1",
+  "description": "Built-in utilities for Rempts CLI framework - prompts, spinners, and colors",
+  "keywords": [
+    "cli",
+    "prompts",
+    "rempts",
+    "spinner",
+    "terminal",
+    "utilities"
+  ],
+  "homepage": "https://github.com/reliverse/dler#readme",
+  "bugs": {
+    "url": "https://github.com/reliverse/dler/issues"
+  },
+  "license": "MIT",
+  "author": "blefnk",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/reliverse/dler.git",
+    "directory": "packages/utils"
+  },
+  "files": [
+    "dist",
+    "package.json",
+    "README.md"
+  ],
+  "type": "module",
+  "module": "./src/mod.ts",
+  "types": "./src/mod.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/mod.d.ts",
+      "import": "./dist/mod.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@reliverse/relico": "2.3.1",
+    "@standard-schema/spec": "^1.1.0",
+    "@standard-schema/utils": "^0.3.0",
+    "arktype": "^2.1.29"
+  },
+  "engines": {
+    "bun": ">=1.3.5"
+  }
+}