@goast/core 0.4.0-beta4 → 0.4.1

package/src/src/utils/string-builder/string-builder.test.ts

@@ -0,0 +1,188 @@
+import "../../../_dnt.test_polyfills.js";
+import { EOL } from 'node:os';
+
+import { expect } from '../../../deps/jsr.io/@std/expect/1.0.12/mod.js';
+import { describe, it } from '../../../deps/jsr.io/@std/testing/1.0.9/bdd.js';
+
+import type { StringBuilderOptions } from './options.js';
+import { StringBuilder } from './string-builder.js';
+
+describe('fromString', () => {
+  it('should create a StringBuilder instance with the given string', () => {
+    const str = 'test string';
+    const sb = StringBuilder.fromString(str);
+    expect(sb.toString()).toEqual(str);
+  });
+
+  it('should create a StringBuilder instance with the given string and options', () => {
+    const str = 'test string';
+    const options: Partial<StringBuilderOptions> = {
+      newLine: '\r\n',
+    };
+    const sb = StringBuilder.fromString(str, options);
+    expect(sb.toString()).toEqual(str);
+    expect(sb.options).toEqual(expect.objectContaining(options));
+  });
+});
+
+describe('build', () => {
+  it('should build a string using a StringBuilder build action', () => {
+    const buildAction = (builder: StringBuilder) => {
+      builder.append('hello');
+      builder.append('world');
+    };
+    const result = StringBuilder.build(buildAction);
+    expect(result).toEqual('helloworld');
+  });
+
+  it('should build a string using a StringBuilder build action and options', () => {
+    const buildAction = (builder: StringBuilder) => {
+      builder.appendLine('hello');
+      builder.append('world');
+    };
+    const options: Partial<StringBuilderOptions> = {
+      newLine: '\r\n--',
+    };
+    const result = StringBuilder.build(buildAction, options);
+    expect(result).toEqual(`hello${options.newLine}world`);
+  });
+});
+
+describe('append', () => {
+  it('should append a string to the end of the StringBuilder', () => {
+    const sb = new StringBuilder();
+    sb.append('hello');
+    expect(sb.toString()).toEqual('hello');
+  });
+
+  it('should append multiple strings to the end of the StringBuilder', () => {
+    const sb = new StringBuilder();
+    sb.append('hello', ' ', 'world');
+    expect(sb.toString()).toEqual('hello world');
+  });
+
+  it('should ignore nullish or empty strings', () => {
+    const sb = new StringBuilder();
+    sb.append('', null, undefined, 'hello');
+    expect(sb.toString()).toEqual('hello');
+  });
+});
+
+describe('appendLine', () => {
+  it('should append a string followed by a new line to the end of the StringBuilder', () => {
+    const sb = new StringBuilder();
+    sb.appendLine('hello');
+    expect(sb.toString()).toEqual(`hello${EOL}`);
+  });
+
+  it('should append multiple strings followed by a new line to the end of the StringBuilder', () => {
+    const sb = new StringBuilder();
+    sb.appendLine('hello', 'world');
+    expect(sb.toString()).toEqual(`helloworld${EOL}`);
+  });
+
+  it('should ignore nullish or empty strings', () => {
+    const sb = new StringBuilder();
+    sb.appendLine('', null, undefined, 'hello');
+    expect(sb.toString()).toEqual(`hello${EOL}`);
+  });
+
+  it('should append a string followed by a custom new line to the end of the StringBuilder', () => {
+    const options: StringBuilderOptions = {
+      newLine: '\r\n--',
+    };
+    const sb = new StringBuilder(options);
+    sb.appendLine('hello');
+    expect(sb.toString()).toEqual(`hello${options.newLine}`);
+  });
+});
+
+describe('prepend', () => {
+  it('should prepend a string to the beginning of the StringBuilder', () => {
+    const sb = new StringBuilder();
+    sb.append('world');
+    sb.prepend('hello ');
+    expect(sb.toString()).toEqual('hello world');
+  });
+
+  it('should prepend multiple strings to the beginning of the StringBuilder', () => {
+    const sb = new StringBuilder();
+    sb.append('world');
+    sb.prepend('hello ', 'there, ');
+    expect(sb.toString()).toEqual('hello there, world');
+  });
+
+  it('should ignore nullish or empty strings', () => {
+    const sb = new StringBuilder();
+    sb.append('world');
+    sb.prepend('', null, undefined, 'hello ');
+    expect(sb.toString()).toEqual('hello world');
+  });
+
+  it('should prepend a string built by another StringBuilder', () => {
+    const sb = new StringBuilder();
+    sb.append('world');
+    sb.prepend((builder) => builder.append('hello '));
+    expect(sb.toString()).toEqual('hello world');
+  });
+
+  it('should create the StringBuilder for the function with the same options as the current StringBuilder', () => {
+    const options: StringBuilderOptions = {
+      newLine: '\r\n--',
+    };
+    const sb = new StringBuilder(options);
+    sb.append('world');
+    sb.prepend((builder) => builder.appendLine('hello '));
+    expect(sb.toString()).toEqual(`hello ${options.newLine}world`);
+  });
+});
+
+describe('prependLine', () => {
+  it('should prepend a string followed by a new line to the beginning of the StringBuilder', () => {
+    const sb = new StringBuilder();
+    sb.append('world');
+    sb.prependLine('hello');
+    expect(sb.toString()).toEqual(`hello${EOL}world`);
+  });
+
+  it('should prepend a string followed by a custom new line to the beginning of the StringBuilder', () => {
+    const options: StringBuilderOptions = {
+      newLine: '\r\n--',
+    };
+    const sb = new StringBuilder(options);
+    sb.append('world');
+    sb.prependLine('hello');
+    expect(sb.toString()).toEqual(`hello${options.newLine}world`);
+  });
+
+  it('should prepend multiple strings followed by a new line to the beginning of the StringBuilder', () => {
+    const sb = new StringBuilder();
+    sb.append('world');
+    sb.prependLine('hello', 'there');
+    expect(sb.toString()).toEqual(`hellothere${EOL}world`);
+  });
+
+  it('should ignore nullish or empty strings', () => {
+    const sb = new StringBuilder();
+    sb.append('world');
+    sb.prependLine('', null, undefined, 'hello');
+    expect(sb.toString()).toEqual(`hello${EOL}world`);
+  });
+
+  it('should prepend a string built by another StringBuilder', () => {
+    const sb = new StringBuilder();
+    sb.append('world');
+    sb.prependLine((builder) => builder.append('hello '));
+    expect(sb.toString()).toEqual(`hello ${EOL}world`);
+  });
+
+  it('should create the StringBuilder for the function with the same options as the current StringBuilder', () => {
+    const options: StringBuilderOptions = {
+      newLine: '\r\n--',
+    };
+    const sb = new StringBuilder(options);
+    sb.append('world');
+    sb.prependLine((builder) => builder.appendLine('hello '));
+    expect(sb.toString()).toEqual(`hello ${options.newLine}${options.newLine}world`);
+  });
+});

package/src/src/utils/string-builder/string-builder.ts

@@ -0,0 +1,165 @@
+import { isNullish } from '../common.utils.js';
+import type { Nullable, SingleOrMultiple } from '../type.utils.js';
+import { defaultStringBuilderOptions, type StringBuilderOptions } from './options.js';
+
+export type BuilderFn<TBuilder extends StringBuilder> = (builder: TBuilder) => void;
+export type Primitive = string | number | boolean;
+
+export type AppendParam<TBuilder extends StringBuilder, TAdditionalAppends> = SingleOrMultiple<
+  | Primitive
+  | null
+  | undefined
+  | BuilderFn<TBuilder>
+  // eslint-disable-next-line @typescript-eslint/ban-types
+  | TAdditionalAppends
+  | {
+    __type: 'append-value-group';
+    values: AppendParam<TBuilder, TAdditionalAppends>[];
+    separator: string | null;
+  }
+>;
+
+export const AdditionalAppendsSymbol = Symbol('AdditionalAppends');
+
+/**
+ * Represents a mutable string of characters.
+ */
+export class StringBuilder<TAdditionalAppends = never> {
+  private readonly _options: StringBuilderOptions;
+  protected str: string = '';
+
+  [AdditionalAppendsSymbol](_: TAdditionalAppends): void {
+    throw new Error('This method should never be called.');
+  }
+
+  public get options(): StringBuilderOptions {
+    return this._options;
+  }
+
+  /**
+   * Initializes a new instance of the StringBuilder class.
+   * @param options The options.
+   */
+  constructor(options?: Partial<StringBuilderOptions>) {
+    this._options = { ...defaultStringBuilderOptions, ...options };
+  }
+
+  /**
+   * Creates a new StringBuilder instance and appends the specified string to it.
+   * @param str The string to append.
+   * @param options The options.
+   * @returns A new StringBuilder instance.
+   */
+  public static fromString(str: string, options?: Partial<StringBuilderOptions>): StringBuilder {
+    const builder = new StringBuilder(options);
+    builder.append(str);
+    return builder;
+  }
+
+  /**
+   * Builds a string using a StringBuilder build action.
+   * @param buildAction The build action to perform on the StringBuilder instance.
+   * @param options The options for the StringBuilder instance.
+   * @returns The built string.
+   */
+  public static build(buildAction: AppendParam<StringBuilder, never>, options?: Partial<StringBuilderOptions>): string {
+    const builder = new StringBuilder(options);
+    builder.append(buildAction);
+    return builder.toString();
+  }
+
+  protected appendSingle(value: AppendParam<this, TAdditionalAppends>) {
+    if (isNullish(value)) return;
+    if (Array.isArray(value)) {
+      for (const part of value) {
+        this.appendSingle(part);
+      }
+    } else if (typeof value === 'string') {
+      this.str += value;
+    } else if (typeof value === 'number' || typeof value === 'boolean') {
+      this.str += value.toString();
+    } else if (typeof value === 'function') {
+      (value as (builder: this) => void)(this);
+    } else if (
+      typeof value === 'object' &&
+      value !== null &&
+      '__type' in value &&
+      value.__type === 'append-value-group'
+    ) {
+      let isFirst = true;
+      for (const part of value.values) {
+        if (!isFirst && value.separator) {
+          this.append(value.separator);
+        }
+        this.appendSingle(part);
+        isFirst = false;
+      }
+    }
+  }
+
+  /**
+   * Appends one or more strings to the end of the current StringBuilder.
+   * @param value The string(s) to append.
+   * @returns The current StringBuilder.
+   */
+  public append(...value: AppendParam<this, TAdditionalAppends>[]): this {
+    for (const part of value) {
+      this.appendSingle(part);
+    }
+    return this;
+  }
+
+  /**
+   * Appends one or more strings to the end of the current StringBuilder, followed by a line terminator.
+   * @param value
+   * @returns
+   */
+  public appendLine(...value: Nullable<AppendParam<this, TAdditionalAppends>>[]): this {
+    return this.append(...value, '\n');
+  }
+
+  /**
+   * Prepends one or more strings to the beginning of the current StringBuilder.
+   * @param value The string(s) to prepend.
+   * @returns The current StringBuilder.
+   */
+  public prepend(...value: AppendParam<StringBuilder, never>[]): this {
+    for (const part of value.reverse()) {
+      if (isNullish(part)) continue;
+      if (typeof part === 'function') {
+        const builder = new StringBuilder(this.options);
+        part(builder);
+        this.str = builder.str + this.str;
+      } else if (typeof part === 'string') {
+        this.str = part + this.str;
+      } else {
+        this.str = part.toString() + this.str;
+      }
+    }
+    return this;
+  }
+
+  /**
+   * Prepends one or more strings to the beginning of the current StringBuilder, followed by a line terminator.
+   * @param value The string(s) to prepend.
+   * @returns The current StringBuilder.
+   */
+  public prependLine(...value: AppendParam<StringBuilder, never>[]): this {
+    return this.prepend(...value, '\n');
+  }
+
+  /**
+   * Converts the value of this instance to a string.
+   * @returns A string whose value is the same as this instance.
+   */
+  public toString(): string {
+    return this.str.replace(/\r?\n/g, this._options.newLine);
+  }
+
+  /**
+   * Removes all characters from the current StringBuilder.
+   */
+  public clear(): void {
+    this.str = '';
+  }
+}

package/src/src/utils/string-builder/utils.ts

@@ -0,0 +1,69 @@
+import { concatSingleOrMultiple, notNullish } from '../common.utils.js';
+import type { Nullable } from '../type.utils.js';
+import type { AdditionalAppendsSymbol, AppendParam, BuilderFn, Primitive, StringBuilder } from './string-builder.js';
+
+export type BasicAppendValue<TBuilder extends StringBuilder = StringBuilder> =
+  | Primitive
+  | BuilderFn<TBuilder>
+  | BasicAppendValueGroup<TBuilder>;
+export type BasicAppendValueGroup<TBuilder extends StringBuilder = StringBuilder> = {
+  __type: 'append-value-group';
+  values: BasicAppendValue<TBuilder>[];
+  separator: string | null;
+};
+
+export type AppendValue<TBuilder extends StringBuilder = StringBuilder> = NonNullable<
+  AppendParam<TBuilder, Parameters<TBuilder[typeof AdditionalAppendsSymbol]>[0]>
+>;
+export type AppendValueGroup<TBuilder extends StringBuilder = StringBuilder> = {
+  __type: 'append-value-group';
+  values: AppendValue<TBuilder>[];
+  separator: string | null;
+};
+
+/** @deprecated Use AppendValue<TBuilder> instead */
+export type TextOrBuilderFn<TBuilder> = string | ((builder: TBuilder) => void);
+
+export function basicAppendValueGroup<TBuilder extends StringBuilder = StringBuilder>(
+  values: Nullable<Nullable<BasicAppendValue<TBuilder>>[]>,
+  separator?: Nullable<string>,
+): BasicAppendValueGroup<TBuilder> {
+  return {
+    __type: 'append-value-group',
+    values: values?.filter(notNullish) ?? [],
+    separator: separator ?? null,
+  };
+}
+
+export function appendValueGroup<TBuilder extends StringBuilder = StringBuilder>(
+  values: Nullable<Nullable<AppendValue<TBuilder>>[]>,
+  separator?: Nullable<string>,
+): AppendValueGroup<TBuilder> {
+  return {
+    __type: 'append-value-group',
+    values: values?.filter(notNullish) ?? [],
+    separator: separator ?? null,
+  };
+}
+
+export function isAppendValue(value: unknown): value is AppendValue<never> {
+  return (
+    typeof value === 'string' ||
+    typeof value === 'number' ||
+    typeof value === 'boolean' ||
+    typeof value === 'function' ||
+    isAppendValueGroup(value)
+  );
+}
+
+export function isAppendValueGroup<TBuilder extends StringBuilder = StringBuilder>(
+  value: unknown,
+): value is AppendValueGroup<TBuilder> {
+  return typeof value === 'object' && value !== null && '__type' in value && value.__type === 'append-value-group';
+}
+
+export function concatAppendValues<TBuilder extends StringBuilder = StringBuilder>(
+  ...values: AppendValue<TBuilder>[]
+): AppendValue<TBuilder> {
+  return concatSingleOrMultiple(...values) as AppendValue<TBuilder>;
+}