smartstring/readme.md

# @push.rocks/smartstring 

🎯 **Smart string manipulation for TypeScript** - Your comprehensive toolkit for handling strings, domains, Git URLs, and encodings with elegance and precision.

## Why smartstring?

When working with strings in modern JavaScript/TypeScript applications, you often need more than just basic manipulation. You need to:
- Parse and validate domains and URLs
- Handle Git repository URLs across different formats  
- Encode/decode Base64 for data transmission
- Normalize indentation in code generators
- Create cryptographically secure random strings
- Validate string encodings
- Parse Docker environment variables

**smartstring** unifies all these capabilities in a single, tree-shakeable, TypeScript-native package with zero setup overhead.

## Install

```bash
npm install @push.rocks/smartstring --save
```

Or using pnpm (recommended):

```bash
pnpm add @push.rocks/smartstring
```

## Features at a Glance

✅ **Domain parsing** - Extract protocols, subdomains, domains, and TLDs  
✅ **Git URL handling** - Parse and convert between SSH and HTTPS formats  
✅ **Base64 encoding** - Standard and URL-safe Base64 operations  
✅ **Smart indentation** - Indent, outdent, and normalize multi-line strings  
✅ **Random strings** - Pattern-based and cryptographically secure generation  
✅ **String normalization** - Clean and standardize whitespace  
✅ **Type checking** - Validate UTF-8 and Base64 encodings  
✅ **Docker env parsing** - Transform Docker environment arrays to objects  

## Usage

### 🌐 Domain Parsing

Extract detailed information from any URL or domain string:

```typescript
import { Domain } from '@push.rocks/smartstring';

const domain = new Domain('https://subdomain.example.com:3000/path');

console.log(domain.protocol);        // 'https'
console.log(domain.hostname);        // 'subdomain.example.com'  
console.log(domain.port);            // '3000'
console.log(domain.pathname);        // '/path'
console.log(domain.fullUrl);         // 'https://subdomain.example.com:3000/path'

// Domain level extraction
console.log(domain.level1);          // 'com' - TLD
console.log(domain.level2);          // 'example' - Domain  
console.log(domain.level3);          // 'subdomain' - Subdomain
console.log(domain.zoneName);        // 'example.com' - Full domain without subdomain
console.log(domain.subdomain);       // 'subdomain'
```

### 🔧 Git Repository URLs

Parse and convert Git repository URLs between SSH and HTTPS formats:

```typescript
import { GitRepo } from '@push.rocks/smartstring';

// Parse SSH format
const repo = new GitRepo('git@github.com:user/awesome-project.git');
console.log(repo.host);              // 'github.com'
console.log(repo.user);              // 'user'
console.log(repo.repo);              // 'awesome-project'
console.log(repo.httpsUrl);          // 'https://github.com/user/awesome-project.git'

// Parse HTTPS format  
const httpsRepo = new GitRepo('https://gitlab.com/team/project.git');
console.log(httpsRepo.sshUrl);       // 'git@gitlab.com:team/project.git'
console.log(httpsRepo.httpsUrl);     // 'https://gitlab.com/team/project.git'
```

### 🔐 Base64 Encoding

Handle Base64 encoding with both standard and URL-safe variants:

```typescript
import { Base64, base64 } from '@push.rocks/smartstring';

// Using the Base64 class
const encoded = new Base64('Hello World! 👋', 'string');
console.log(encoded.base64String);      // Standard Base64
console.log(encoded.base64UriString);   // URL-safe Base64
console.log(encoded.simpleString);      // Decoded string

// Using utility functions
const quickEncode = base64.encode('Secret message');
const quickDecode = base64.decode(quickEncode);

// Validate Base64 strings
console.log(base64.isBase64('SGVsbG8='));           // true
console.log(base64.isBase64('Not Base64!'));        // false

// URL-safe Base64 operations
const urlSafeEncoded = base64.encodeUri('https://example.com/path?param=value');
const urlSafeDecoded = base64.decodeUri(urlSafeEncoded);
```

### 📐 Smart Indentation

Manage indentation in multi-line strings with precision:

```typescript
import { indent } from '@push.rocks/smartstring';

// Indent with spaces
const indented = indent.indent('Line 1\nLine 2\nLine 3', 4);
// Result:
//     Line 1
//     Line 2  
//     Line 3

// Indent with custom prefix
const prefixed = indent.indentWithPrefix('Item 1\nItem 2', '> ');
// Result:
// > Item 1
// > Item 2

// Add prefix to first line only
const firstLinePrefixed = indent.addPrefix('Chapter\nContent here', '# ');
// Result:
// # Chapter
// Content here

// Normalize irregular indentation
const messy = `
    function hello() {
            console.log('Hi');
        return true;
    }
`;
const clean = indent.normalize(messy);
// Result: Properly aligned with minimum indentation preserved
```

### 🎲 Random String Generation

Create random strings with specific patterns or cryptographic security:

```typescript
import { create } from '@push.rocks/smartstring';

// Pattern-based random strings
// A = uppercase, a = lowercase, 0 = number, ! = special, * = any
const password = create.createRandomString('Aa0!', 16);
// Example: "Kg7$Lp2@Qm9#Xn4!"

const alphanumeric = create.createRandomString('Aa0', 10);  
// Example: "K7gLp2Qm9X"

const numbers = create.createRandomString('0', 6);
// Example: "472819"

// Cryptographically secure random strings
const cryptoId = create.createCryptoRandomString();
// Example: "f7b2d8e0-3c4a-4b9c-8d2e-1f0a7b9c8d7e"
```

### 🧹 String Normalization

Clean and standardize strings for consistent formatting:

```typescript
import { normalize } from '@push.rocks/smartstring';

const messyString = `
    This text has
        inconsistent indentation
            and too much whitespace   


    between lines...
`;

const cleaned = normalize.standard(messyString);
// Result: Properly formatted with consistent spacing

// Custom normalization  
const customNormalized = normalize.normal(messyString);
```

### 🔍 String Type Validation

Check string encodings and types:

```typescript
import { type } from '@push.rocks/smartstring';

// Check if string is valid UTF-8
const isValidUtf8 = type.isUtf8('Hello 世界');
console.log(isValidUtf8);  // true

// Check if string is Base64
const isBase64String = type.isBase64('SGVsbG8gV29ybGQ=');  
console.log(isBase64String);  // true
```

### 🐳 Docker Environment Variables

Parse Docker-style environment variable arrays:

```typescript
import { docker } from '@push.rocks/smartstring';

const envArray = [
  'NODE_ENV=production',
  'PORT=3000',
  'DATABASE_URL=postgresql://localhost:5432/mydb',
  'API_KEY=secret123'
];

const envObject = docker.makeEnvObject(envArray);

console.log(envObject.NODE_ENV);      // 'production'
console.log(envObject.PORT);          // '3000'  
console.log(envObject.DATABASE_URL);  // 'postgresql://localhost:5432/mydb'
console.log(envObject.API_KEY);       // 'secret123'

// Use in Docker-related configurations
// Perfect for parsing process.env or Docker Compose outputs
```

## API Reference

### Classes

- **`Domain`** - URL/domain parser with component extraction
- **`GitRepo`** - Git repository URL parser and converter  
- **`Base64`** - Base64 encoder/decoder with multiple formats

### Modules

- **`create`** - Random string generation
  - `createRandomString(pattern, length, options)` - Pattern-based generation
  - `createCryptoRandomString()` - Cryptographically secure strings

- **`indent`** - Indentation management
  - `indent(text, spaces)` - Add spaces to each line
  - `indentWithPrefix(text, prefix)` - Add custom prefix to each line
  - `normalize(text)` - Fix inconsistent indentation
  - `addPrefix(text, prefix)` - Add prefix to first line only

- **`normalize`** - String normalization
  - `standard(text)` - Apply standard normalization
  - `normal(text)` - Basic normalization

- **`type`** - String type checking
  - `isUtf8(text)` - Validate UTF-8 encoding
  - `isBase64(text)` - Validate Base64 format

- **`base64`** - Base64 utilities
  - `encode(text)` - Standard Base64 encoding
  - `decode(text)` - Standard Base64 decoding
  - `encodeUri(text)` - URL-safe Base64 encoding
  - `decodeUri(text)` - URL-safe Base64 decoding
  - `isBase64(text)` - Check if string is valid Base64

- **`docker`** - Docker utilities
  - `makeEnvObject(envArray)` - Convert env array to object

## Real-World Examples

### Building a URL Shortener

```typescript
import { Domain, create, base64 } from '@push.rocks/smartstring';

function createShortUrl(longUrl: string): string {
  const domain = new Domain(longUrl);
  const shortCode = create.createRandomString('Aa0', 6);
  const encoded = base64.encodeUri(`${domain.hostname}${domain.pathname}`);
  
  return `short.ly/${shortCode}`;
}
```

### Processing Code Templates

```typescript
import { indent, normalize } from '@push.rocks/smartstring';

function generateComponent(name: string, props: string[]): string {
  const propsSection = props
    .map(prop => `${prop}: string;`)
    .join('\n');
    
  const template = `
export interface ${name}Props {
${indent.indent(propsSection, 2)}
}

export function ${name}(props: ${name}Props) {
${indent.indent('// Component implementation', 2)}
}
`;

  return normalize.standard(template);
}
```

### Git Repository Manager

```typescript
import { GitRepo } from '@push.rocks/smartstring';

class RepoManager {
  repos: Map<string, GitRepo> = new Map();
  
  addRepo(url: string): void {
    const repo = new GitRepo(url);
    this.repos.set(repo.repo, repo);
  }
  
  getCloneCommand(name: string, useSSH = false): string {
    const repo = this.repos.get(name);
    if (!repo) throw new Error('Repository not found');
    
    const url = useSSH ? repo.sshUrl : repo.httpsUrl;
    return `git clone ${url}`;
  }
}
```

## Browser Support

This package is built for modern environments and includes:
- ✅ Full ES Module support
- ✅ Tree-shaking ready
- ✅ TypeScript definitions
- ✅ Browser-compatible (via bundlers)
- ✅ Node.js 14+ support

## Development

```bash
# Clone the repository
git clone https://code.foss.global/push.rocks/smartstring.git

# Install dependencies
pnpm install

# Run tests
pnpm test

# Build the project
pnpm build
```

## 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.