@osaedasia/std

std

A collection of standard utility classes and functions designed to enhance your TypeScript development experience.

The library is available through the following package managers:

• jsr
• npm

Table of Contents

• Features

• Usage

  • StringBuilder
    • Basic Usage
    • Using Initial Value
    • Loop Appending
    • Clearing and Reusing
  • RandomArray
    • Basic Usage
  • UserAgent
    • Basic Usage
  • LocalStorage
    • Basic Usage
  • Url
    • Basic Usage
  • UrlHash
    • Basic Usage
  • RandomUUID
    • Basic Usage

• Reporting Issues

• LICENCE

Features

• Lightweight and Fast: Minimal overhead, focusing on performance and simplicity.
• Efficient String Manipulation: Build strings efficiently without the performance overhead of regular string concatenation.
• Random Element Selection: Easily pick random elements from arrays using the RandomArray utility.
• Random User Agents: Generate random valid User Agent strings for testing or other use cases.
• Local Storage Utilities: Type-safe wrapper for browser's localStorage API.
• URL Manipulation: Robust URL handling and normalization utilities.
• UUID Generation: RFC 4122 compliant Version 4 UUID generation.

Usage

StringBuilder

The StringBuilder class provides a way to build strings efficiently by appending multiple parts. It's especially useful when dealing with loops or conditions that require frequent string concatenations.

Basic Usage

To start using StringBuilder, first import it from the library and create a new instance. You can then use the append method to add strings, and toString to get the final concatenated string.

import { StringBuilder } from '@osaedasia/std';

const builder = new StringBuilder();
builder.append('Hello, ');
builder.append('world!');
console.log(builder.toString()); // Output: Hello, world!

Using Initial Value

You can initialize StringBuilder with an initial value by passing a string to its constructor. This is helpful when you have a starting string and want to build upon it.

import { StringBuilder } from '@osaedasia/std';

const builder = new StringBuilder({
    initialValue: 'Start: '
});
builder.append('Middle, ');
builder.append('End.');
console.log(builder.toString()); // Output: Start: Middle, End.

Loop Appending

When building a string within a loop, StringBuilder enhances performance by minimizing the overhead of string concatenation. Here's how you can use it in a loop to create a multi-line string:

import { StringBuilder } from '@osaedasia/std';

const builder = new StringBuilder();
for (let i = 0; i < 5; i++) {
    builder.append(`Line ${i}\n`);
}
console.log(builder.toString());
// Output:
// Line 0
// Line 1
// Line 2
// Line 3
// Line 4

Clearing and Reusing

If you need to reuse the StringBuilder instance for building a new string, you can clear its content using the clear method. This allows you to reset the builder without creating a new instance.

import { StringBuilder } from '@osaedasia/std';

const builder = new StringBuilder({
    initialValue: 'Initial '
});
builder.append('Content.');
console.log(builder.toString()); // Output: Initial Content.

builder.clear();
builder.append('New Content.');
console.log(builder.toString()); // Output: New Content.

RandomArray

The RandomArray utility class provides methods to handle random operations on arrays.

Basic Usage

import { RandomArray } from "@/osaedasia/std";

const colors = ['red', 'green', 'blue'];
const randomColor = RandomArray.pickRandom(colors);
console.log(randomColor); // Output could be 'red', 'green', or 'blue'

UserAgent

The UserAgent utility class generates random valid User Agent strings.

Basic Usage

import { UserAgent } from '@osaedasia/std';

const userAgentString = UserAgent.random();
console.log(userAgentString);
// Possible output:
// Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/116.0.0.0 Safari/537.36

LocalStorage

The LocalStorage utility provides a type-safe wrapper around the browser's localStorage API.

Basic Usage

import { LocalStorage } from '@osaedasia/std';

// Store data
interface User {
    id: number;
    name: string;
}
const user: User = { id: 1, name: "John" };
LocalStorage.setItem("user", user);

// Retrieve data
const savedUser = LocalStorage.getItem<User>("user");
console.log(savedUser); // { id: 1, name: "John" }

// Remove data
LocalStorage.removeItem("user");

Url

The Url utility provides URL normalization and manipulation capabilities.

Basic Usage

import { Url } from '@osaedasia/std';

// Normalize URLs
const normalized = Url.normalize('https://example.com/Path//to///PAge');
console.log(normalized); // 'https://example.com/path/to/page/'

// Without trailing slash
const withoutSlash = Url.normalize('https://example.com/path//to///page', false);
console.log(withoutSlash); // 'https://example.com/path/to/page'

UrlHash

The UrlHash utility handles URL hash fragments and their associated query parameters.

Basic Usage

import { UrlHash } from '@osaedasia/std';

// Parse URL with hash and parameters
const parsed = UrlHash.parse('https://example.com/page#section?param1=value1');
console.log(parsed);
// {
//   href: 'https://example.com/page',
//   hash: 'section',
//   searchParams: URLSearchParams {'param1' => 'value1'}
// }

RandomUUID

The RandomUUID utility generates RFC 4122 compliant Version 4 UUIDs.

Basic Usage

import { RandomUUID } from '@osaedasia/std';

// Generate a new UUID
const uuid = RandomUUID.v4;
console.log(uuid); // e.g., "123e4567-e89b-4456-8234-567812345678"

Reporting Issues

If you encounter any issues while using the library, feel free to report them by creating an issue on the GitLab repository. Since I’m the sole maintainer, please provide as much detail as possible to help me resolve the issue efficiently. Make sure to include:

• Clear description of the problem.
• Steps to reproduce the issue.
• library version.
• Relevant information such as:
  • Stack trace.
  • Environment details (e.g., operating system, Node.js version, Deno version, etc.).
  • Code snippets where the issue occurs.

Your detailed feedback is crucial in improving the library for everyone.

LICENCE

MIT License

Copyright (c) 2024 Osaedasia

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.