@synstack/str 1.0.1-alpha.0

package/src/str.chainable.ts

@@ -0,0 +1,291 @@
+import { Pipeable } from "@synstack/pipe";
+import * as changeCase from "change-case";
+import * as lib from "./str.lib";
+
+export type Stringable = {
+  toString: () => string;
+};
+
+export class Str extends Pipeable<Str, string> {
+  public constructor(private readonly text: string) {
+    super();
+  }
+
+  public valueOf(): string {
+    return this.text;
+  }
+
+  public toString() {
+    return this.text;
+  }
+
+  public instanceOf(): Str {
+    return this;
+  }
+
+  /**
+   * Remove empty lines at the start of the text but leave whitespace on the first line with content
+   */
+  public chopEmptyLinesStart() {
+    return new Str(lib.chopEmptyLinesStart(this.text));
+  }
+
+  /**
+   * Remove empty lines at the end of the text but leave whitespace on the last line with content
+   */
+  public chopEmptyLinesEnd() {
+    return new Str(lib.chopEmptyLinesEnd(this.text));
+  }
+
+  /**
+   * Remove all space (\s) characters in lines without content
+   */
+  public trimEmptyLines() {
+    return new Str(lib.trimEmptyLines(this.text));
+  }
+
+  /**
+   * Remove all spaces (\s) characters at the end of lines
+   */
+  public trimLinesTrailingSpaces() {
+    return new Str(lib.trimLinesTrailingSpaces(this.text));
+  }
+
+  /**
+   * Removes the leading and trailing white space and line terminator characters
+   */
+  public trim() {
+    return new Str(lib.trim(this.text));
+  }
+
+  /**
+   * Removes the leading white space and line terminator characters
+   */
+  public trimStart() {
+    return new Str(lib.trimStart(this.text));
+  }
+
+  /**
+   * Removes the trailing white space and line terminator characters
+   */
+  public trimEnd() {
+    return new Str(lib.trimEnd(this.text));
+  }
+
+  /**
+   * Split a string into substrings using the specified separator and return them as an array
+   */
+  public split(separator: string | RegExp, limit?: number) {
+    return lib.split(this.text, separator, limit).map((v) => new Str(v));
+  }
+
+  /**
+   * Add line numbers to a string
+   * @param separator The separator to use between the line number and the line content.
+   * Defaults to ":"
+   */
+  public addLineNumbers(separator: string = ":") {
+    return new Str(lib.addLineNumbers(this.text, separator));
+  }
+
+  /**
+   * Returns the character at the specified index
+   * @return string or undefined if the index is out of bounds
+   */
+  public at(index: number) {
+    return this.text.at(index);
+  }
+
+  /**
+   * Returns the length of the string
+   */
+  public length() {
+    return this.text.length;
+  }
+
+  /**
+   * Indent the string by the specified number of spaces
+   * @param size The number of spaces to indent by
+   * @param char The character to use for indentation. Defaults to " "
+   */
+  public indent(size: number, char: string = " ") {
+    return new Str(lib.indent(this.text, size, char));
+  }
+
+  /**
+   * Dedent the string by the specified number of spaces
+   * @param indentation The number of spaces to dedent by.
+   * If not provided, it will be calculated automatically based on the maximum indentation in the string.
+   */
+  public dedent(indentation?: number) {
+    return new Str(lib.dedent(this.text, indentation));
+  }
+
+  /**
+   * Chop the string at the start by the specified number of characters
+   */
+  public chopStart(count: number) {
+    return new Str(lib.chopStart(this.text, count));
+  }
+
+  /**
+   * Chop the string at the end by the specified number of characters
+   */
+  public chopEnd(count: number) {
+    if (count === 0) return this;
+    return new Str(lib.chopEnd(this.text, count));
+  }
+
+  /**
+   * Remove successive newlines of the specified repetition or more
+   * @param maxRepeat the maximum number of newlines to allow
+   */
+  public chopRepeatNewlines(maxRepeat: number) {
+    if (maxRepeat === 0) return this;
+    return new Str(lib.chopRepeatNewlines(this.text, maxRepeat));
+  }
+
+  /**
+   * Take the first n characters of the string
+   */
+  public takeStart(count: number) {
+    return new Str(lib.takeStart(this.text, count));
+  }
+
+  /**
+   * Take the last n characters of the string
+   */
+  public takeEnd(count: number) {
+    return new Str(lib.takeEnd(this.text, count));
+  }
+
+  /**
+   * Returns the last line of the string
+   */
+  public lastLine() {
+    return new Str(lib.lastLine(this.text));
+  }
+
+  /**
+   * Returns the first line of the string
+   */
+  public firstLine() {
+    return new Str(lib.firstLine(this.text));
+  }
+
+  /**
+   * Returns the number of leading spaces in the string
+   */
+  public leadingSpacesCount() {
+    return lib.leadingSpacesCount(this.text);
+  }
+
+  /**
+   * Returns the indentation level of the string skipping empty lines in the process
+   */
+  public indentation() {
+    return lib.indentation(this.text);
+  }
+
+  /**
+   * Returns true if the string is empty or contains only whitespace
+   */
+  public isEmpty() {
+    return lib.isEmpty(this.text);
+  }
+
+  /**
+   * Converts the string to camel case
+   */
+  public camelCase() {
+    return new Str(changeCase.camelCase(this.text));
+  }
+
+  /**
+   * Converts the string to capital case
+   */
+  public capitalCase() {
+    return new Str(changeCase.capitalCase(this.text));
+  }
+
+  /**
+   * Converts the string to constant case
+   */
+  public constantCase() {
+    return new Str(changeCase.constantCase(this.text));
+  }
+
+  /**
+   * Converts the string to dot case
+   */
+  public dotCase() {
+    return new Str(changeCase.dotCase(this.text));
+  }
+
+  /**
+   * Converts the string to kebab case
+   */
+  public kebabCase() {
+    return new Str(changeCase.kebabCase(this.text));
+  }
+
+  /**
+   * Converts the string to no case
+   */
+  public noCase() {
+    return new Str(changeCase.noCase(this.text));
+  }
+
+  /**
+   * Converts the string to pascal case
+   */
+  public pascalCase() {
+    return new Str(changeCase.pascalCase(this.text));
+  }
+
+  /**
+   * Converts the string to pascal snake case
+   */
+  public pascalSnakeCase() {
+    return new Str(changeCase.pascalSnakeCase(this.text));
+  }
+
+  /**
+   * Converts the string to path case
+   */
+  public pathCase() {
+    return new Str(changeCase.pathCase(this.text));
+  }
+
+  /**
+   * Converts the string to sentence case
+   */
+  public sentenceCase() {
+    return new Str(changeCase.sentenceCase(this.text));
+  }
+
+  /**
+   * Converts the string to snake case
+   */
+  public snakeCase() {
+    return new Str(changeCase.snakeCase(this.text));
+  }
+
+  /**
+   * Converts the string to train case
+   */
+  public trainCase() {
+    return new Str(changeCase.trainCase(this.text));
+  }
+
+  /**
+   * Shorthand for `.toString()`
+   */
+  public get str() {
+    return this.toString();
+  }
+}
+
+export const str = (text: Stringable) => {
+  return new Str(text.toString());
+};

package/src/str.index.ts

@@ -0,0 +1,2 @@
+export * from "./str.bundle";
+export type { Str } from "./str.chainable";

package/src/str.lib.ts

@@ -0,0 +1,186 @@
+/**
+ * Remove empty lines at the start of the text but leave whitespace on the first line with content
+ */
+export const chopEmptyLinesStart = (text: string) => {
+  return text.replace(/^(\s*\n)+/, "");
+};
+
+/**
+ * Remove empty lines at the end of the text but leave whitespace on the last line with content
+ */
+export const chopEmptyLinesEnd = (text: string) => {
+  return text.replace(/(\n\s*)+$/, "");
+};
+
+/**
+ * Remove all space (\s) characters in lines without content
+ */
+export const trimEmptyLines = (text: string) => {
+  return text.replace(/(^|\n)\s+(\n|$)/g, "$1$2");
+};
+
+/**
+ * Remove all space (\s) characters at the end of lines
+ */
+export const trimLinesTrailingSpaces = (text: string) => {
+  return text.replace(/ +(\n|$)/g, "$1");
+};
+
+/**
+ * Removes the leading and trailing white space and line terminator characters
+ */
+export const trim = (text: string) => {
+  return text.trim();
+};
+
+/**
+ * Removes the leading white space and line terminator characters
+ */
+export const trimStart = (text: string) => {
+  return text.trimStart();
+};
+
+/**
+ * Removes the trailing white space and line terminator characters
+ */
+export const trimEnd = (text: string) => {
+  return text.trimEnd();
+};
+
+/**
+ * Split a string into substrings using the specified separator and return them as an array
+ */
+export const split = (
+  text: string,
+  separator: string | RegExp,
+  limit?: number,
+) => {
+  return text.split(separator, limit);
+};
+
+/**
+ * Add line numbers to a string
+ * @param text The string to add line numbers to
+ * @param separator The separator to use between the line number and the line content.
+ * Defaults to ":"
+ */
+export const addLineNumbers = (text: string, separator: string = ":") => {
+  return text
+    .split("\n")
+    .map((line, index) => `${index}${separator}${line}`)
+    .join("\n");
+};
+
+/**
+ * Returns the indentation level of the string skipping empty lines in the process
+ */
+export const indentation = (text: string) => {
+  return (
+    text.split("\n").reduce((acc: number | null, line) => {
+      if (line.trim() === "") return acc;
+      const indentation = leadingSpacesCount(line);
+      if (acc === null) return indentation;
+      return Math.min(acc, indentation);
+    }, null) ?? 0
+  );
+};
+
+/**
+ * Indent the string by the specified number of spaces
+ * @param size The number of spaces to indent by
+ * @param char The character to use for indentation. Defaults to " "
+ */
+export const indent = (text: string, size: number, char: string = " ") => {
+  if (size === 0) return text;
+
+  const indentStr = char.repeat(size);
+  return text
+    .split("\n")
+    .map((line) => indentStr + line)
+    .join("\n");
+};
+
+/**
+ * Dedent the string by the specified number of spaces
+ * @param indentation The number of spaces to dedent by.
+ * If not provided, it will be calculated automatically based on the maximum indentation in the string.
+ */
+export const dedent = (text: string, size?: number) => {
+  const _size = size ?? indentation(text);
+  if (_size === 0) return text;
+  const regex = new RegExp(`^\\s{1,${_size}}`);
+  return text
+    .split("\n")
+    .map((line) => line.replace(regex, ""))
+    .join("\n");
+};
+
+/**
+ * Chop the string at the end by the specified number of characters
+ */
+export const chopEnd = (text: string, count: number) => {
+  if (count === 0) return text;
+  return text.slice(0, -count);
+};
+
+/**
+ * Chop the string at the start by the specified number of characters
+ */
+export const chopStart = (text: string, count: number) => {
+  if (count === 0) return text;
+  return text.slice(count);
+};
+
+/**
+ * Remove successive newlines of the specified repetition or more
+ * @param maxRepeat the maximum number of newlines to allow
+ */
+export const chopRepeatNewlines = (text: string, maxRepeat: number) => {
+  if (maxRepeat === 0) return text;
+  return text.replace(
+    new RegExp(`\n{${maxRepeat + 1},}`, "g"),
+    "\n".repeat(maxRepeat),
+  );
+};
+
+/**
+ * Take the first n characters of the string
+ */
+export const takeStart = (text: string, count: number) => {
+  return text.slice(0, count);
+};
+
+/**
+ * Take the last n characters of the string
+ */
+export const takeEnd = (text: string, count: number) => {
+  return text.slice(-count);
+};
+
+/**
+ * Returns the last line of the string
+ */
+export const lastLine = (text: string) => {
+  return text.split("\n").at(-1) ?? "";
+};
+
+/**
+ * Returns the first line of the string
+ */
+export const firstLine = (text: string) => {
+  return text.split("\n").at(0) ?? "";
+};
+
+/**
+ * Returns the number of leading spaces in the string
+ */
+export const leadingSpacesCount = (text: string) => {
+  return text.match(/^\s+/)?.at(0)?.length ?? 0;
+};
+
+/**
+ * Returns true if the string is empty or contains only whitespace
+ */
+export const isEmpty = (text: string) => {
+  return text.trim() === "";
+};