🎯 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

npm install @push.rocks/smartstring --save

Or using pnpm (recommended):

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
✅ Text encodings - Decode and encode Windows-1252 the same on every runtime, decode by a declared label, and tell UTF-8 from Windows-1252
✅ Docker env parsing - Transform Docker environment arrays to objects
✅ Credential redaction - Hide tokens, passwords, keys and cookies in failure text and logs, then bound it to a byte budget without exposing part of a secret

Usage

🌐 Domain Parsing

Extract detailed information from any URL or domain string:

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:

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:

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:

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:

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:

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:

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

🔤 Text Encodings

Decode bytes into text the same on every runtime:

import { encoding } from '@push.rocks/smartstring';

// Windows-1252 by the WHATWG Encoding Standard's index, not by the runtime's TextDecoder
encoding.decodeWindows1252(Uint8Array.of(0x96, 0x80, 0xe4)); // '–€ä'

// by a declared label: every label the standard maps to windows-1252 (latin1, iso-8859-1, us-ascii, cp1252, …)
// is decoded by the table, every other encoding by the runtime; undefined for a label the registry does not know
encoding.decodeText(bytes, 'ISO-8859-1');
encoding.decodeText(bytes, 'iso-8859-15');

// a file without a declared encoding: UTF-8 where it is valid UTF-8 (a BOM removed), else Windows-1252
const { text, encoding: found } = encoding.decodeUtf8OrWindows1252(bytes);

// encode by the standard's single-byte encoder (the index's five C1 controls included),
// naming each character the index does not list (written as '?')
const { bytes: written, replaced } = encoding.encodeWindows1252('Kőbánya – 12 €');

Why a table of its own: some Node.js versions decode Windows-1252 as Latin-1 (nodejs/node#60888; 22.13.0 to 22.22.0, 23.x, 24.0.0 to 24.13.0 and 25.0.0 to 25.3.x), so every character of 0x80–0x9F (€, the dashes, the typographic quotes) comes out as a control character. Other encodings, ISO-8859-15 among them, are decoded correctly by those runtimes and stay the runtime's.

🐳 Docker Environment Variables

Parse Docker-style environment variable arrays:

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

🔒 Credential Redaction

Hide credentials in failure text, command output and log lines before you show or store them:

import { redact } from '@push.rocks/smartstring';

redact.redactCredentials('Authorization: Bearer eyFAKE.FAKE.FAKE (status 401)');
// 'Authorization: Bearer *** (status 401)'

redact.redactCredentials('GET https://user:FAKE@git.example.com/repo?key=FAKE&page=2');
// 'GET https://***@git.example.com/repo?key=***&page=2'

// redact the whole text first, then cut it to at most maxBytes UTF-8 bytes (the marker included)
const { text, truncated } = redact.redactAndBound(stderr, { maxBytes: 1024, keep: 'tail', marker: '… ' });

redactCredentials(text) replaces every credential value with *** and keeps what names it, so a message still says which setting leaked:

Headers: Authorization and Proxy-Authorization with any scheme (a one-word scheme such as Bearer, Basic or token stays; a parameter scheme such as Digest or AWS4-HMAC-SHA256, or an unknown one, hides the rest of the line), Cookie/Set-Cookie, Api-Key, X-Api-Key, X-Goog-Api-Key, X-Auth-Token and other X-…-Token/Secret/Auth headers, GitLab's PRIVATE-TOKEN — as Name: value lines and as JSON or JavaScript object keys.
Bearer tokens anywhere, when token-shaped (16 characters or more, or holding a digit or one of ._~+/-), so "Bearer authentication failed" and Bearer realm="api" stay readable.
Query and form parameters after ?, & or ; whose name ends in token, secret, password/passwd, passphrase, key (as a whole word: key, api_key, apiKey, apikey, not monkey or keyboard), sig, signature, credential(s), auth, otp or jwt, or session-id names (jsessionid, PHPSESSID), plus the exact names code, assertion, client_assertion, session, sid. state, zipcode, errorcode and tokenizer keep their values. In plain text name=value pairs count when the name is a credential setting (password=, api_key=, NPM_TOKEN=, SSH_KEY=); code=1 or session=… there stay.
URL userinfo: scheme://user:pass@host and scheme://token@host become scheme://***@host.
Settings: JSON, YAML and JavaScript credential keys, environment variables, .npmrc _authToken, --token-style options, docker login -p, curl -u user:pass and .netrc entries.
Known token shapes: Anthropic and OpenAI (sk-ant-…, sk-proj-…, sk-…), Google (AIza…), GitHub (ghp_, gho_, ghu_, ghs_, ghr_, github_pat_), GitLab (glpat-), npm (npm_…), Slack (xox[abeprs]-…), AWS access key IDs (AKIA…, ASIA…), JSON Web Tokens and PEM private key blocks.

It also removes ANSI escape sequences and turns every other control character except tab and line feed into a space (a CRLF becomes a line feed), so a value cannot forge log lines. Every pattern runs in linear time, so megabytes of output are safe to redact.

redactAndBound(text, { maxBytes, keep, marker }) is the only way to cut: it redacts the whole text first, then keeps the head or the tail within maxBytes UTF-8 bytes, the marker (default …) included. A cut never splits a character and lands only on whitespace, so the word it would cut through is dropped whole: no part of a credential whose context lies beyond the cut is kept, and a single word larger than the budget leaves only the marker. truncated says whether it cut. It throws a RangeError when maxBytes is not an integer or is smaller than the marker.

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
encoding - Text encodings, the same on every runtime
- decodeWindows1252(bytes) / encodeWindows1252(text) - Windows-1252 by the Encoding Standard's index; encoding lists each character written as ?
- windows1252ByteOf(codePoint) - The byte of a code point, or undefined
- isValidUtf8(bytes) - Whether bytes are valid UTF-8
- encodingOfLabel(label) - The encoding a label names (Encoding Standard registry)
- decodeText(bytes, label, { fatal }) - Decode by a declared label
- decodeUtf8OrWindows1252(bytes) - UTF-8 where valid, else Windows-1252
redact - Credential redaction for failure text and logs
- redactCredentials(text) - Hide every credential value, keep its name
- redactAndBound(text, { maxBytes, keep: 'head' | 'tail', marker? }) - Redact, then cut to a UTF-8 byte budget at whitespace
- redactionMarker - The replacement, ***

Real-World Examples

Building a URL Shortener

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

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

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

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

readme.md Unescape Escape

@push.rocks/smartstring