beautyfiglet/readme.md

# @push.rocks/beautyfiglet
A Node.js module for creating figlet text displays.

## Install

To install `@push.rocks/beautyfiglet`, you should have Node.js and npm installed on your machine. Once you have these prerequisites, you can install the package via npm by running the following command in your terminal:

```sh
npm install @push.rocks/beautyfiglet
```

Alternatively, you can include it as a dependency in your `package.json` file:

```json
{
  "dependencies": {
    "@push.rocks/beautyfiglet": "^1.0.7"
  }
}
```

Then execute:

```sh
npm install
```

## Usage

`@push.rocks/beautyfiglet` is a versatile Node.js module that lets you generate figlet-style ASCII art easily. Below, we will explore its functionalities with detailed examples, encompassing various scenarios to showcase how you can leverage this module in your projects.

### Basic Initialization

Begin by importing the `BeautyFiglet` class into your TypeScript file. You can access its methods to create ASCII art from text strings.

```typescript
import { BeautyFiglet } from '@push.rocks/beautyfiglet';

// A simple demonstration of using the standard export
console.log('Welcome to BeautyFiglet!'); // Outputs: Welcome to BeautyFiglet!
```

### Rendering Text with Figlet

Figlet is immensely popular for turning strings into ASCII banners. The following code illustrates how to convert text into a figlet display using `BeautyFiglet`.

```typescript
(async () => {
  const figletText = await BeautyFiglet.renderDefault('Hello, World!');
  console.log(figletText);
})();
```

### Customizing Font

`BeautyFiglet` not only supports different versions of text layouts, but it also allows you to specify fonts, making your output unique.

```typescript
(async () => {
  const customFiglet = await BeautyFiglet.renderText('Beautiful Text', 'Ghost');
  console.log(customFiglet);
})();
```

### Fetching Available Fonts

Understanding what fonts are available can help in making aesthetic decisions for your text.

```typescript
(async () => {
  const fontsList = await BeautyFiglet.listFonts();
  console.log('Available Fonts:');
  console.log(fontsList.join(', '));
})();
```

### Using Custom Layouts

In addition to fonts, the layout of the text can be altered. You can specify both horizontal and vertical layouts.

```typescript
import figlet from 'figlet';

const renderCustomLayout = (text: string, font: string, hLayout: string, vLayout: string): Promise<string> => {
  return new Promise((resolve, reject) => {
    figlet.text(text, { font, horizontalLayout: hLayout, verticalLayout: vLayout }, (err, data) => {
      if (err) reject(`Error: ${err.message}`);
      else resolve(data);
    });
  });
};

// Example usage
(async () => {
  try {
    const customLayoutText = await renderCustomLayout('Creative Layout', 'Ghost', 'full', 'full');
    console.log(customLayoutText);
  } catch (error) {
    console.error(error);
  }
})();
```

### Synchronous Text Rendering

For situations requiring synchronous execution such as small scripts and testing scenarios, `textSync` comes in handy.

```typescript
import { figlet } from '@push.rocks/beautyfiglet.plugins';

const artwork = figlet.textSync('Synchronicity!', {
  font: 'Standard',
  horizontalLayout: 'default',
  verticalLayout: 'default'
});

console.log(artwork);
```

### Enhancing Output with Color

To add more flair to your text displays, consider integrating popular color-coordinating libraries like `chalk`.

```typescript
import figlet from 'figlet';
import chalk from 'chalk';

(async () => {
  const colorizedText = await BeautyFiglet.renderText('Color Me Beautiful', 'Standard');
  console.log(chalk.magentaBright(colorizedText));
})();
```

### Robust Error Handling

Error handling is paramount in any application. This becomes even more pronounced when fonts or integrations might fail.

```typescript
(async () => {
  try {
    const result = await BeautyFiglet.renderText('Error Test', 'NonExistentFont');
    console.log(result);
  } catch (error) {
    console.error(`Caught an error: ${error}`);
  }
})();
```

### Web Server Integration

The module can effectively serve dynamically generated ASCII text over HTTP. Here's a simple example using Express:

```typescript
import express from 'express';
import { BeautyFiglet } from '@push.rocks/beautyfiglet';

const app = express();

app.get('/api/art/:text', async (req, res) => {
  const textToRender = req.params.text;
  
  try {
    const asciiArt = await BeautyFiglet.renderDefault(textToRender);
    res.send(`<pre>${asciiArt}</pre>`);
  } catch (error) {
    res.status(500).send(`Error: ${error.message}`);
  }
});

app.listen(4000, () => {
  console.log('Server running at http://localhost:4000/');
});
```

### Command-Line Interface (CLI)

Expand the utility of `BeautyFiglet` by creating a CLI tool for generating ASCII art directly from the command line.

```typescript
#!/usr/bin/env node
import { BeautyFiglet } from '@push.rocks/beautyfiglet';
import { Command } from 'commander';

const program = new Command();
program.version('1.0.7');

program
  .option('-t, --text <text>', 'Text to render')
  .option('-f, --font <font>', 'Font for rendering', 'Standard')
  .action(async (cmd) => {
    try {
      const asciiArt = await BeautyFiglet.renderText(cmd.text, cmd.font);
      console.log(asciiArt);
    } catch (error) {
      console.error(`Error: ${error}`);
    }
  });

program.parse(process.argv);
```

Running this tool involves these steps:

1. Save the script as `beautyfiglet-cli.ts`.
2. Ensure it is marked as executable:

```sh
chmod +x ./beautyfiglet-cli.ts
```

3. Link via npm:

```sh
npm link
```

4. Execute with:

```sh
beautyfiglet-cli --text "Hello World" --font "Ghost"
```

This command-line example showcases flexibility and enhanced usability for developers integrating the module seamlessly into their workflow.

### Summary of Best Practices

The extensive usage of `@push.rocks/beautyfiglet` demonstrates the importance of proper setup and thorough understanding of available options. From simple implementations to elaborate, colorful arrangements, this module empowers developers to unleash creativity with text in aesthetic and programmable ways.

Delve deeper into font choices and optional configurations to fully capitalize on this versatile tool for crafting meaningful ASCII text displays, all the while ensuring continuous learning of new patterns and module updates. With vigilant error management and the integration of expressive styles, your applications can achieve a blend of functionality and flair unmatched by basic textual representation.

This concludes the elaborate coverage of the `@push.rocks/beautyfiglet` module and its extensive capabilities within Node.js projects.

## License and Legal Information

This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository. 

**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

### Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.

### Company Information

Task Venture Capital GmbH  
Registered at District court Bremen HRB 35230 HB, Germany

For any legal inquiries or if you require further information, please contact us via email at hello@task.vc.

By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.