@decaf-ts/utils 0.2.12 → 0.3.0

package/LICENSE.md

@@ -1,157 +1,21 @@
-# GNU LESSER GENERAL PUBLIC LICENSE
-
-Version 3, 29 June 2007
-
-Copyright (C) 2025 Tiago Venceslau
-<https://github.com/Tiago Venceslau>
-
-Everyone is permitted to copy and distribute verbatim copies of this
-license document, but changing it is not allowed.
-
-This version of the GNU Lesser General Public License incorporates the
-terms and conditions of version 3 of the GNU General Public License,
-supplemented by the additional permissions listed below.
-
-## 0. Additional Definitions.
-
-As used herein, "this License" refers to version 3 of the GNU Lesser
-General Public License, and the "GNU GPL" refers to version 3 of the
-GNU General Public License.
-
-"The Library" refers to a covered work governed by this License, other
-than an Application or a Combined Work as defined below.
-
-An "Application" is any work that makes use of an interface provided
-by the Library, but which is not otherwise based on the Library.
-Defining a subclass of a class defined by the Library is deemed a mode
-of using an interface provided by the Library.
-
-A "Combined Work" is a work produced by combining or linking an
-Application with the Library. The particular version of the Library
-with which the Combined Work was made is also called the "Linked
-Version".
-
-The "Minimal Corresponding Source" for a Combined Work means the
-Corresponding Source for the Combined Work, excluding any source code
-for portions of the Combined Work that, considered in isolation, are
-based on the Application, and not on the Linked Version.
-
-The "Corresponding Application Code" for a Combined Work means the
-object code and/or source code for the Application, including any data
-and utility programs needed for reproducing the Combined Work from the
-Application, but excluding the System Libraries of the Combined Work.
-
-## 1. Exception to Section 3 of the GNU GPL.
-
-You may convey a covered work under sections 3 and 4 of this License
-without being bound by section 3 of the GNU GPL.
-
-## 2. Conveying Modified Versions.
-
-If you modify a copy of the Library, and, in your modifications, a
-facility refers to a function or data to be supplied by an Application
-that uses the facility (other than as an argument passed when the
-facility is invoked), then you may convey a copy of the modified
-version:
-
--   a) under this License, provided that you make a good faith effort
-    to ensure that, in the event an Application does not supply the
-    function or data, the facility still operates, and performs
-    whatever part of its purpose remains meaningful, or
--   b) under the GNU GPL, with none of the additional permissions of
-    this License applicable to that copy.
-
-## 3. Object Code Incorporating Material from Library Header Files.
-
-The object code form of an Application may incorporate material from a
-header file that is part of the Library. You may convey such object
-code under terms of your choice, provided that, if the incorporated
-material is not limited to numerical parameters, data structure
-layouts and accessors, or small macros, inline functions and templates
-(ten or fewer lines in length), you do both of the following:
-
--   a) Give prominent notice with each copy of the object code that
-    the Library is used in it and that the Library and its use are
-    covered by this License.
--   b) Accompany the object code with a copy of the GNU GPL and this
-    license document.
-
-## 4. Combined Works.
-
-You may convey a Combined Work under terms of your choice that, taken
-together, effectively do not restrict modification of the portions of
-the Library contained in the Combined Work and reverse engineering for
-debugging such modifications, if you also do each of the following:
-
--   a) Give prominent notice with each copy of the Combined Work that
-    the Library is used in it and that the Library and its use are
-    covered by this License.
--   b) Accompany the Combined Work with a copy of the GNU GPL and this
-    license document.
--   c) For a Combined Work that displays copyright notices during
-    execution, include the copyright notice for the Library among
-    these notices, as well as a reference directing the user to the
-    copies of the GNU GPL and this license document.
--   d) Do one of the following:
-    -   0) Convey the Minimal Corresponding Source under the terms of
-           this License, and the Corresponding Application Code in a form
-           suitable for, and under terms that permit, the user to
-           recombine or relink the Application with a modified version of
-           the Linked Version to produce a modified Combined Work, in the
-           manner specified by section 6 of the GNU GPL for conveying
-           Corresponding Source.
-    -   1) Use a suitable shared library mechanism for linking with
-           the Library. A suitable mechanism is one that (a) uses at run
-           time a copy of the Library already present on the user's
-           computer system, and (b) will operate properly with a modified
-           version of the Library that is interface-compatible with the
-           Linked Version.
--   e) Provide Installation Information, but only if you would
-    otherwise be required to provide such information under section 6
-    of the GNU GPL, and only to the extent that such information is
-    necessary to install and execute a modified version of the
-    Combined Work produced by recombining or relinking the Application
-    with a modified version of the Linked Version. (If you use option
-    4d0, the Installation Information must accompany the Minimal
-    Corresponding Source and Corresponding Application Code. If you
-    use option 4d1, you must provide the Installation Information in
-    the manner specified by section 6 of the GNU GPL for conveying
-    Corresponding Source.)
-
-## 5. Combined Libraries.
-
-You may place library facilities that are a work based on the Library
-side by side in a single library together with other library
-facilities that are not Applications and are not covered by this
-License, and convey such a combined library under terms of your
-choice, if you do both of the following:
-
--   a) Accompany the combined library with a copy of the same work
-    based on the Library, uncombined with any other library
-    facilities, conveyed under the terms of this License.
--   b) Give prominent notice with the combined library that part of it
-    is a work based on the Library, and explaining where to find the
-    accompanying uncombined form of the same work.
-
-## 6. Revised Versions of the GNU Lesser General Public License.
-
-The Free Software Foundation may publish revised and/or new versions
-of the GNU Lesser General Public License from time to time. Such new
-versions will be similar in spirit to the present version, but may
-differ in detail to address new problems or concerns.
-
-Each version is given a distinguishing version number. If the Library
-as you received it specifies that a certain numbered version of the
-GNU Lesser General Public License "or any later version" applies to
-it, you have the option of following the terms and conditions either
-of that published version or of any later version published by the
-Free Software Foundation. If the Library as you received it does not
-specify a version number of the GNU Lesser General Public License, you
-may choose any version of the GNU Lesser General Public License ever
-published by the Free Software Foundation.
-
-If the Library as you received it specifies that a proxy can decide
-whether future versions of the GNU Lesser General Public License shall
-apply, that proxy's public statement of acceptance of any version is
-permanent authorization for you to choose that version for the
-Library.
+# MIT License
+
+Copyright (c) 2025 Tiago Venceslau
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -2,7 +2,8 @@
 
 ## Decaf's Utils Module
 
-Provides basic text, fs and cli functionality
+A comprehensive TypeScript utility library providing robust tools for command-line interfaces, input handling, output management, file system operations, HTTP requests, text processing, and more. This module serves as a foundation for building powerful CLI applications with standardized input parsing, flexible output formatting, and a rich set of utility functions.
+
 
 ![Licence](https://img.shields.io/github/license/decaf-ts/utils.svg?style=plastic)
 ![GitHub language count](https://img.shields.io/github/languages/count/decaf-ts/utils?style=plastic)
@@ -18,12 +19,6 @@ Provides basic text, fs and cli functionality
 ![Pull Requests](https://img.shields.io/github/issues-pr-closed/decaf-ts/utils.svg)
 ![Maintained](https://img.shields.io/badge/Maintained%3F-yes-green.svg)
 
-![Line Coverage](workdocs/reports/coverage/badge-lines.svg)
-![Function Coverage](workdocs/reports/coverage/badge-functions.svg)
-![Statement Coverage](workdocs/reports/coverage/badge-statements.svg)
-![Branch Coverage](workdocs/reports/coverage/badge-branches.svg)
-
-
 ![Forks](https://img.shields.io/github/forks/decaf-ts/utils.svg)
 ![Stars](https://img.shields.io/github/stars/decaf-ts/utils.svg)
 ![Watchers](https://img.shields.io/github/watchers/decaf-ts/utils.svg)
@@ -35,15 +30,41 @@ Documentation available [here](https://decaf-ts.github.io/utils/)
 
 ### Description
 
-Provides Basic functionality to standardize APIs across repositories:
+The Decaf Utils module is a comprehensive TypeScript utility library designed to standardize APIs across repositories and provide a robust foundation for building command-line interface (CLI) applications. The library is organized into several key components:
+
+#### CLI Module
+The CLI module provides a structured framework for creating command-line applications:
+- Abstract `Command` class for implementing custom CLI commands with standardized input handling, logging, and execution flow
+- Command option handling with support for common flags like verbose, version, help, etc.
+- Standardized command execution flow with proper error handling
 
- - cli;
- - input;
- - output;
- - utils'
+#### Input Module
+The Input module offers tools for handling user input and command-line arguments:
+- `UserInput` class for creating interactive prompts with various input types (text, number, confirmation, etc.)
+- Support for input validation, formatting, and default values
+- Command-line argument parsing with type checking and validation
+- Methods for repeatedly asking for input until valid responses are received
 
+#### Utils Module
+The Utils module contains a wide range of utility functions:
+- **File System Operations**: Reading, writing, copying, and deleting files and directories
+- **Package Management**: Retrieving package information, managing dependencies, and version handling
+- **HTTP Utilities**: Simple client for downloading files from URLs
+- **Text Processing**: String interpolation, case conversion (camelCase, snake_case, etc.), and regular expression utilities
+- **Environment Handling**: Working with environment variables and configuration
 
+#### Writers Module
+The Writers module provides different strategies for handling command output:
+- `OutputWriter` interface defining a standard contract for output handling
+- `StandardOutputWriter` for handling standard command-line output with proper logging
+- `RegexpOutputWriter` for processing output with regular expressions and pattern matching
 
+#### Output Module
+The Output module offers utilities for formatting and displaying output:
+- Common output formatting functions
+- Banner display capabilities
+
+This library serves as a light version of the Decaf CLI tool, providing all the essential utilities needed for building robust command-line applications with consistent input handling, output formatting, and error management.
 
 
 ### How to Use
@@ -51,7 +72,377 @@ Provides Basic functionality to standardize APIs across repositories:
 - [Initial Setup](./tutorials/For%20Developers.md#_initial-setup_)
 - [Installation](./tutorials/For%20Developers.md#installation)
 
+## Examples
+
+### CLI Module
+
+#### Creating a Custom Command
+
+The Command class provides a foundation for creating custom CLI commands with standardized input handling and execution flow.
+
+```typescript
+import { Command, CommandOptions } from '@decaf-ts/utils';
+
+// Define input options interface
+interface MyCommandOptions {
+  filename: string;
+  dryRun: boolean;
+}
+
+// Create a custom command class
+class MyCommand extends Command<MyCommandOptions, string> {
+  constructor() {
+    // Define command options with their configurations
+    const options: CommandOptions<MyCommandOptions> = {
+      filename: {
+        type: 'string',
+        short: 'f',
+        default: 'output.txt'
+      },
+      dryRun: {
+        type: 'boolean',
+        short: 'd',
+        default: false
+      }
+    };
+
+    super('my-command', options);
+  }
+
+  // Override the help method to provide custom help information
+  protected help(): void {
+    this.log.info(`
+      Usage: my-command [options]
+
+      Options:
+        -f, --filename  Specify output filename (default: output.txt)
+        -d, --dryRun    Run without making changes (default: false)
+        -h, --help      Show help information
+        -v, --version   Show version information
+    `);
+  }
+
+  // Implement the run method to define command behavior
+  protected async run(answers: { filename: string; dryRun: boolean }): Promise<string> {
+    this.log.info(`Running command with filename: ${answers.filename}, dryRun: ${answers.dryRun}`);
 
+    // Command implementation here
+
+    return 'Command executed successfully';
+  }
+}
+
+// Execute the command
+async function main() {
+  const command = new MyCommand();
+  const result = await command.execute();
+  console.log(result);
+}
+
+main().catch(console.error);
+```
+
+### Input Module
+
+#### Creating Interactive Prompts
+
+The UserInput class allows you to create interactive prompts for collecting user input.
+
+```typescript
+import { UserInput } from '@decaf-ts/utils';
+
+async function collectUserInfo() {
+  // Create a text input for name
+  const nameInput = new UserInput('name')
+    .setMessage('What is your name?')
+    .setInitial('User');
+
+  // Create a number input for age with validation
+  const ageInput = new UserInput('age')
+    .setType('number')
+    .setMessage('How old are you?')
+    .setMin(0)
+    .setMax(120)
+    .setValidate(value => {
+      if (value < 18) return 'You must be at least 18 years old';
+      return true;
+    });
+
+  // Create a confirmation input
+  const confirmInput = new UserInput('confirm')
+    .setType('confirm')
+    .setMessage('Is this information correct?')
+    .setInitial(true);
+
+  // Ask for all inputs and get the answers
+  const answers = await UserInput.ask([nameInput, ageInput, confirmInput]);
+
+  console.log(`Hello ${answers.name}, you are ${answers.age} years old.`);
+  console.log(`Information confirmed: ${answers.confirm ? 'Yes' : 'No'}`);
+
+  return answers;
+}
+
+collectUserInfo().catch(console.error);
+```
+
+#### Using Convenience Methods for Input
+
+UserInput provides static convenience methods for common input scenarios.
+
+```typescript
+import { UserInput } from '@decaf-ts/utils';
+
+async function quickInputExample() {
+  // Ask for text input
+  const name = await UserInput.askText('name', 'What is your name?', undefined, 'User');
+
+  // Ask for number input
+  const age = await UserInput.askNumber('age', 'How old are you?', 0, 120);
+
+  // Ask for confirmation
+  const confirm = await UserInput.askConfirmation('confirm', 'Is this information correct?', true);
+
+  // Ask for text with validation and retry until valid
+  const email = await UserInput.insistForText(
+    'email',
+    'What is your email address?',
+    (value) => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value),
+    undefined,
+    undefined,
+    false,
+    3 // Maximum 3 attempts
+  );
+
+  console.log(`Name: ${name}, Age: ${age}, Email: ${email}, Confirmed: ${confirm}`);
+}
+
+quickInputExample().catch(console.error);
+```
+
+#### Parsing Command-Line Arguments
+
+```typescript
+import { UserInput, ParseArgsOptionsConfig } from '@decaf-ts/utils';
+
+// Define command-line options
+const options: ParseArgsOptionsConfig = {
+  verbose: {
+    type: 'boolean',
+    short: 'V',
+    default: false
+  },
+  output: {
+    type: 'string',
+    short: 'o',
+    default: 'output.txt'
+  },
+  count: {
+    type: 'string',
+    short: 'c',
+    default: '10'
+  }
+};
+
+// Parse command-line arguments
+const args = UserInput.parseArgs(options);
+
+console.log('Parsed arguments:', args.values);
+console.log('Positional arguments:', args.positionals);
+```
+
+### Utils Module
+
+#### File System Operations
+
+```typescript
+import { 
+  readFile, 
+  writeFile, 
+  patchFile, 
+  getAllFiles, 
+  copyFile, 
+  renameFile, 
+  deletePath 
+} from '@decaf-ts/utils';
+
+// Read a file
+const content = readFile('./config.json');
+console.log('File content:', content);
+
+// Write to a file
+writeFile('./output.txt', 'Hello, world!');
+
+// Patch a file with replacements
+patchFile('./template.txt', {
+  '{{name}}': 'John Doe',
+  '{{date}}': new Date().toISOString()
+});
+
+// Get all files in a directory
+const files = getAllFiles('./src', (file) => file.endsWith('.ts'));
+console.log('TypeScript files:', files);
+
+// Copy a file
+copyFile('./source.txt', './destination.txt');
+
+// Rename a file
+renameFile('./old-name.txt', './new-name.txt');
+
+// Delete a file or directory
+deletePath('./temp');
+```
+
+#### Package Management
+
+```typescript
+import { 
+  getPackage, 
+  getPackageVersion, 
+  setPackageAttribute, 
+  getDependencies, 
+  installDependencies 
+} from '@decaf-ts/utils';
+
+// Get package information
+const pkg = getPackage();
+console.log('Package:', pkg);
+
+// Get package version
+const version = getPackageVersion();
+console.log('Version:', version);
+
+// Set a package attribute
+setPackageAttribute('version', '1.0.1');
+
+// Get dependencies
+async function manageDependencies() {
+  const deps = await getDependencies();
+  console.log('Production dependencies:', deps.prod);
+  console.log('Development dependencies:', deps.dev);
+  console.log('Peer dependencies:', deps.peer);
+
+  // Install dependencies
+  await installDependencies({
+    prod: ['lodash', 'axios'],
+    dev: ['typescript', 'jest']
+  });
+}
+
+manageDependencies().catch(console.error);
+```
+
+#### HTTP Utilities
+
+```typescript
+import { HttpClient } from '@decaf-ts/utils';
+
+async function downloadExample() {
+  try {
+    // Download a file from a URL
+    const content = await HttpClient.downloadFile('https://example.com/api/data.json');
+    console.log('Downloaded content:', content);
+
+    // Parse JSON content
+    const data = JSON.parse(content);
+    console.log('Parsed data:', data);
+
+    return data;
+  } catch (error) {
+    console.error('Download failed:', error);
+    throw error;
+  }
+}
+
+downloadExample().catch(console.error);
+```
+
+#### Text Processing
+
+```typescript
+import { 
+  padEnd, 
+  patchPlaceholders, 
+  patchString, 
+  toCamelCase, 
+  toSnakeCase, 
+  toKebabCase, 
+  toPascalCase, 
+  toENVFormat 
+} from '@decaf-ts/utils';
+
+// Pad a string
+const padded = padEnd('Hello', 10, '-');
+console.log(padded); // 'Hello-----'
+
+// Replace placeholders
+const template = 'Hello, ${name}! Today is ${day}.';
+const filled = patchPlaceholders(template, {
+  name: 'Alice',
+  day: 'Monday'
+});
+console.log(filled); // 'Hello, Alice! Today is Monday.'
+
+// Replace strings
+const patched = patchString('Hello, world!', {
+  'world': 'universe'
+});
+console.log(patched); // 'Hello, universe!'
+
+// Case conversion
+const text = 'hello world';
+console.log(toCamelCase(text));   // 'helloWorld'
+console.log(toSnakeCase(text));   // 'hello_world'
+console.log(toKebabCase(text));   // 'hello-world'
+console.log(toPascalCase(text));  // 'HelloWorld'
+console.log(toENVFormat(text));   // 'HELLO_WORLD'
+```
+
+### Writers Module
+
+#### Using StandardOutputWriter
+
+```typescript
+import { StandardOutputWriter } from '@decaf-ts/utils';
+
+// Create a promise executor
+const executor = {
+  resolve: (value: string) => console.log(`Command succeeded with: ${value}`),
+  reject: (error: Error) => console.error(`Command failed with: ${error.message}`)
+};
+
+// Create a standard output writer
+const writer = new StandardOutputWriter('ls -la', executor);
+
+// Handle command output
+writer.data('File list output...');
+writer.data('file1.txt');
+writer.data('file2.txt');
+
+// Handle command completion
+writer.exit(0, ['Command executed successfully']);
+```
+
+#### Using RegexpOutputWriter
+
+```typescript
+import { RegexpOutputWriter } from '@decaf-ts/utils';
+
+// Create a promise executor
+const executor = {
+  resolve: (value: string) => console.log(`Found version: ${value}`),
+  reject: (error: Error) => console.error(`Error: ${error.message}`)
+};
+
+// Create a regexp output writer that matches version numbers
+const writer = new RegexpOutputWriter('node --version', executor, /v(\d+\.\d+\.\d+)/);
+
+// Process output that contains a version number
+writer.data('v14.17.0');  // This will automatically resolve with "v14.17.0"
+
+// Process error output
+writer.error('Command not found: node');  // This will be logged as an error
+```
 
 
 ### Related