@fgv/ts-utils 5.0.0-22 → 5.0.0-23

package/src/packlets/base/logger.ts

@@ -1,156 +0,0 @@
-/*
- * Copyright (c) 2020 Erik Fortune
- *
- * 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.
- */
-import { Failure, Success, fail, succeed } from './result';
-
-/**
- * @public
- */
-export type LogLevel = 'detail' | 'info' | 'warning' | 'error' | 'silent';
-
-/**
- * @public
- */
-// eslint-disable-next-line @typescript-eslint/naming-convention
-export interface Logger {
-  log(message?: unknown, ...parameters: unknown[]): Success<string | undefined>;
-  detail(message?: unknown, ...parameters: unknown[]): Success<string | undefined>;
-  info(message?: unknown, ...parameters: unknown[]): Success<string | undefined>;
-  warn(message?: unknown, ...parameters: unknown[]): Success<string | undefined>;
-  warnAndFail<T>(message?: unknown, ...parameters: unknown[]): Failure<T>;
-  error<T>(message?: unknown, ...parameters: unknown[]): Failure<T>;
-}
-
-/**
- * @public
- */
-export abstract class LoggerBase {
-  public logLevel: LogLevel = 'info';
-
-  public constructor(logLevel?: LogLevel) {
-    this.logLevel = logLevel ?? 'info';
-  }
-
-  public detail(message?: unknown, ...parameters: unknown[]): Success<string | undefined> {
-    if (this.logLevel === 'detail') {
-      return this.log(message, parameters);
-    }
-    return succeed(undefined);
-  }
-
-  public info(message?: unknown, ...parameters: unknown[]): Success<string | undefined> {
-    if (this.logLevel === 'detail' || this.logLevel === 'info') {
-      return this.log(message, parameters);
-    }
-    return succeed(undefined);
-  }
-
-  public warn(message?: unknown, ...parameters: unknown[]): Success<string | undefined> {
-    if (this.logLevel !== 'error' && this.logLevel !== 'silent') {
-      return this.log(message, parameters);
-    }
-    return succeed(undefined);
-  }
-
-  public warnAndFail<T>(message?: unknown, ...parameters: unknown[]): Failure<T> {
-    const formatted = this._format(message, ...parameters);
-    if (this.logLevel !== 'error' && this.logLevel !== 'silent') {
-      const result = this.log(formatted);
-      return fail(result.value ?? formatted);
-    }
-    return fail(formatted);
-  }
-
-  public error<T>(message?: unknown, ...parameters: unknown[]): Failure<T> {
-    const formatted = this._format(message, ...parameters);
-    if (this.logLevel !== 'silent') {
-      const result = this.log(formatted);
-      return fail(result.value ?? formatted);
-    }
-    return fail(formatted);
-  }
-
-  public log(message?: unknown, ...parameters: unknown[]): Success<string | undefined> {
-    const messageString = this._format(message, ...parameters);
-    if (this.logLevel === 'silent') {
-      return this._innerSilent(messageString);
-    }
-    return this._innerLog(messageString);
-  }
-
-  protected _format(message?: unknown, ...parameters: unknown[]): string {
-    const raw = [message, ...parameters];
-    const filtered = raw.filter((m): m is string => m !== undefined);
-    const strings = filtered.map((m) => m.toString());
-    const joined = strings.join('');
-    return joined;
-  }
-
-  protected _innerSilent(__message: string): Success<string | undefined> {
-    return succeed(undefined);
-  }
-
-  protected abstract _innerLog(message: string): Success<string | undefined>;
-}
-
-/**
- * @public
- */
-export class InMemoryLogger extends LoggerBase {
-  protected _messages: string[] = [];
-  protected _silent: string[] = [];
-
-  public constructor(logLevel?: LogLevel) {
-    super(logLevel);
-  }
-
-  public get messages(): string[] {
-    return this._messages;
-  }
-  public get silent(): string[] {
-    return this._silent;
-  }
-
-  public clear(): void {
-    this._messages = [];
-    this._silent = [];
-  }
-
-  protected _innerLog(message: string): Success<string | undefined> {
-    this._messages.push(message);
-    return succeed(message);
-  }
-
-  protected _innerSilent(message: string): Success<string | undefined> {
-    this._silent.push(message);
-    return succeed(undefined);
-  }
-}
-
-/**
- * @public
- */
-export class NoOpLogger extends LoggerBase {
-  protected _innerLog(message: string): Success<string | undefined> {
-    // no-op
-    return succeed(message);
-  }
-}

package/src/packlets/base/mapResults.ts

@@ -1,302 +0,0 @@
-/*
- * Copyright (c) 2020 Erik Fortune
- *
- * 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.
- */
-
-import { DetailedResult, IMessageAggregator, Result, fail, succeed } from './result';
-
-/**
- * Aggregates successful result values from a collection of {@link Result | Result<T>}.
- * @param results - The collection of {@link Result | Result<T>} to be mapped.
- * @param aggregatedErrors  - Optional string array to which any error messages will be
- * appended.  Each error is appended as an individual string.
- * @returns  If all {@link Result | results} are successful, returns {@link Success} with an
- * array containing all returned values.  If any {@link Result | results} failed, returns
- * {@link Failure} with a concatenated summary of all error messages.
- * @public
- */
-export function mapResults<T>(
-  results: Iterable<Result<T>>,
-  aggregatedErrors?: IMessageAggregator
-): Result<T[]> {
-  const errors: string[] = [];
-  const elements: T[] = [];
-
-  for (const result of results) {
-    if (result.isSuccess()) {
-      elements.push(result.value);
-    } else {
-      errors.push(result.message);
-    }
-  }
-
-  if (errors.length > 0) {
-    aggregatedErrors?.addMessages(errors);
-    return fail(errors.join('\n'));
-  }
-  return succeed(elements);
-}
-
-/**
- * Aggregates successful results from a collection of {@link DetailedResult | DetailedResult<T, TD>},
- * optionally ignoring certain error details.
- * @param results - The collection of {@link DetailedResult | DetailedResult<T, TD>} to be mapped.
- * @param ignore - An array of error detail values (of type `<TD>`) that should be ignored.
- * @param aggregatedErrors  - Optional string array to which any non-ignorable error messages will be
- * appended.  Each error is appended as an individual string.
- * @returns {@link Success} with an array containing all successful results if all results either
- * succeeded or returned error details listed in `ignore`.  If any results failed with details
- * that cannot be ignored, returns {@link Failure} with an concatenated summary of all non-ignorable
- * error messages.
- * @public
- */
-export function mapDetailedResults<T, TD>(
-  results: Iterable<DetailedResult<T, TD>>,
-  ignore: TD[],
-  aggregatedErrors?: IMessageAggregator
-): Result<T[]> {
-  const errors: string[] = [];
-  const elements: T[] = [];
-
-  for (const result of results) {
-    if (result.isSuccess()) {
-      elements.push(result.value);
-    } else if (result.detail && !ignore.includes(result.detail)) {
-      errors.push(result.message);
-    }
-  }
-
-  if (errors.length > 0) {
-    aggregatedErrors?.addMessages(errors);
-    return fail(errors.join('\n'));
-  }
-  return succeed(elements);
-}
-
-/**
- * Aggregates successful results from a a collection of {@link Result | Result<T>}.
- * @param results - An `Iterable` of {@link Result | Result<T>} from which success
- * results are to be aggregated.
- * @param aggregatedErrors  - Optional string array to which any returned error messages will be
- * appended.  Each error is appended as an individual string.
- * @returns {@link Success} with an array of `<T>` if any results were successful. If
- * all {@link Result | results} failed, returns {@link Failure} with a concatenated
- * summary of all error messages.
- * @public
- */
-export function mapSuccess<T>(
-  results: Iterable<Result<T>>,
-  aggregatedErrors?: IMessageAggregator
-): Result<T[]> {
-  const errors: string[] = [];
-  const elements: T[] = [];
-
-  for (const result of results) {
-    if (result.isSuccess()) {
-      elements.push(result.value);
-    } else {
-      errors.push(result.message);
-    }
-  }
-
-  if (elements.length === 0 && errors.length > 0) {
-    aggregatedErrors?.addMessages(errors);
-    return fail(errors.join('\n'));
-  }
-  return succeed(elements);
-}
-
-/**
- * Aggregates error messages from a collection of {@link Result | Result<T>}.
- * @param results - An iterable collection of {@link Result | Result<T>} for which
- * error messages are aggregated.
- * @param aggregatedErrors  - Optional string array to which any returned error messages will be
- * appended.  Each error is appended as an individual string.
- * @returns An array of strings consisting of all error messages returned by
- * {@link Result | results} in the source collection. Ignores {@link Success}
- * results and returns an empty array if there were no errors.
- * @public
- */
-export function mapFailures<T>(
-  results: Iterable<Result<T>>,
-  aggregatedErrors?: IMessageAggregator
-): string[] {
-  const errors: string[] = [];
-  for (const result of results) {
-    if (result.isFailure()) {
-      errors.push(result.message);
-      aggregatedErrors?.addMessage(result.message);
-    }
-  }
-  return errors;
-}
-
-/**
- * Determines if an iterable collection of {@link Result | Result<T>} were all successful.
- * @param results - The collection of {@link Result | Result<T>} to be tested.
- * @param successValue - The value to be returned if results are successful.
- * @param aggregatedErrors  - Optional string array to which any returned error messages will be
- * appended.  Each error is appended as an individual string.
- * @returns Returns {@link Success} with `successValue` if all {@link Result | results} are successful.
- * If any are unsuccessful, returns {@link Failure} with a concatenated summary of the error
- * messages from all failed elements.
- * @public
- */
-export function allSucceed<T>(
-  results: Iterable<Result<unknown>>,
-  successValue: T,
-  aggregatedErrors?: IMessageAggregator
-): Result<T> {
-  const errors: string[] = [];
-
-  if (results !== undefined) {
-    for (const result of results) {
-      if (result.isFailure()) {
-        errors.push(result.message);
-      }
-    }
-  }
-
-  if (errors.length > 0) {
-    aggregatedErrors?.addMessages(errors);
-    return fail(errors.join('\n'));
-  }
-  return succeed(successValue);
-}
-
-/**
- * String-keyed record of initialization functions to be passed to {@link (populateObject:1)}
- * or {@link (populateObject:2)}.
- * @public
- */
-export type FieldInitializers<T> = { [key in keyof T]: (state: Partial<T>) => Result<T[key]> };
-
-/**
- * Options for the {@link (populateObject:1)} function.
- * @public
- */
-// eslint-disable-next-line @typescript-eslint/naming-convention
-export interface PopulateObjectOptions<T> {
-  /**
-   * If present, specifies the order in which property values should
-   * be evaluated.  Any keys not listed are evaluated after all listed
-   * keys in indeterminate order.  If 'order' is not present, keys
-   * are evaluated in indeterminate order.
-   */
-  order?: (keyof T)[];
-
-  /**
-   * Specify handling of `undefined` values.  By default, successful
-   * `undefined` results are written to the result object.  If this value
-   * is `true` then `undefined` results are suppressed for all properties.
-   * If this value is an array of property keys then `undefined` results
-   * are suppressed for those properties only.
-   */
-  suppressUndefined?: boolean | (keyof T)[];
-}
-
-/**
- * Populates an an object based on a prototype full of field initializers that return {@link Result | Result<T[key]>}.
- * Returns {@link Success} with the populated object if all initializers succeed, or {@link Failure} with a
- * concatenated list of all error messages.
- * @param initializers - An object with the shape of the target but with initializer functions for
- * each property.
- * @param options - An optional {@link PopulateObjectOptions | set of options} which
- * modify the behavior of this call.
- * @param aggregatedErrors  - Optional string array to which any returned error messages will be
- * appended.  Each error is appended as an individual string.
- * {@label WITH_OPTIONS}
- * @public
- */
-export function populateObject<T>(
-  initializers: FieldInitializers<T>,
-  options?: PopulateObjectOptions<T>,
-  aggregatedErrors?: IMessageAggregator
-): Result<T>;
-
-/**
- * Populates an an object based on a prototype full of field initializers that return {@link Result | Result<T[key]>}.
- * Returns {@link Success} with the populated object if all initializers succeed, or {@link Failure} with a
- * concatenated list of all error messages.
- * @param initializers - An object with the shape of the target but with initializer functions for
- * each property.
- * @param order - Optional order in which keys should be written.
- * @param aggregatedErrors  - Optional string array to which any returned error messages will be
- * appended.  Each error is appended as an individual string.
- * @public
- * {@label WITH_ORDER}
- * @deprecated Pass {@link PopulateObjectOptions} instead.
- */
-export function populateObject<T>(
-  initializers: FieldInitializers<T>,
-  order: (keyof T)[] | undefined,
-  aggregatedErrors?: IMessageAggregator
-): Result<T>;
-
-export function populateObject<T>(
-  initializers: FieldInitializers<T>,
-  optionsOrOrder?: PopulateObjectOptions<T> | (keyof T)[],
-  aggregatedErrors?: IMessageAggregator
-): Result<T> {
-  const options: PopulateObjectOptions<T> = optionsOrOrder
-    ? Array.isArray(optionsOrOrder)
-      ? { order: optionsOrOrder }
-      : optionsOrOrder
-    : {};
-  const state = {} as { [key in keyof T]: T[key] };
-  const errors: string[] = [];
-  const keys: (keyof T)[] = Array.from(options.order ?? []);
-  const foundKeys = new Set<keyof T>(options.order);
-
-  // start with the supplied order then append anything else we find
-  for (const key in initializers) {
-    if (!foundKeys.has(key)) {
-      keys.push(key);
-      foundKeys.add(key);
-    }
-  }
-
-  for (const key of keys) {
-    if (initializers[key]) {
-      const result = initializers[key](state);
-      if (result.isSuccess()) {
-        if (result.value === undefined) {
-          if (
-            options.suppressUndefined === true ||
-            (Array.isArray(options.suppressUndefined) && options.suppressUndefined.includes(key))
-          ) {
-            continue;
-          }
-        }
-        state[key] = result.value;
-      } else {
-        errors.push(result.message);
-      }
-    } else {
-      errors.push(`populateObject: Key ${String(key)} is present but has no initializer`);
-    }
-  }
-
-  if (errors.length > 0) {
-    aggregatedErrors?.addMessages(errors);
-    return fail(errors.join('\n'));
-  }
-  return succeed(state as T);
-}

package/src/packlets/base/messageAggregator.ts

@@ -1,120 +0,0 @@
-/*
- * Copyright (c) 2024 Erik Fortune
- *
- * 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.
- */
-
-import { IMessageAggregator, Result, fail } from './result';
-
-/**
- * A simple error aggregator to simplify collecting and reporting all errors in
- * a flow.
- * @public
- */
-export class MessageAggregator implements IMessageAggregator {
-  private readonly _messages: string[];
-
-  /**
-   * Constructs a new {@link MessageAggregator | ErrorAggregator} with an
-   * optionally specified initial set of error messages.
-   * @param errors - optional array of errors to be included
-   * in the aggregation.
-   */
-  public constructor(errors?: string[]) {
-    this._messages = errors ? Array.from(errors) : [];
-  }
-
-  /**
-   * {@inheritdoc IMessageAggregator.hasMessages}
-   */
-  public get hasMessages(): boolean {
-    return this._messages.length > 0;
-  }
-
-  /**
-   * {@inheritdoc IMessageAggregator.numMessages}
-   */
-  public get numMessages(): number {
-    return this._messages.length;
-  }
-
-  /**
-   * {@inheritdoc IMessageAggregator.messages}
-   */
-  public get messages(): string[] {
-    return this._messages;
-  }
-
-  /**
-   * {@inheritdoc IMessageAggregator.addMessage}
-   */
-  public addMessage(message: string | undefined): this {
-    if (message) {
-      this._messages.push(message);
-    }
-    return this;
-  }
-
-  /**
-   * {@inheritdoc IMessageAggregator.addMessages}
-   */
-  public addMessages(messages: string[] | undefined): this {
-    if (messages && messages.length > 0) {
-      this._messages.push(...messages);
-    }
-    return this;
-  }
-
-  /**
-   * {@inheritdoc IMessageAggregator.toString}
-   */
-  public toString(separator?: string): string {
-    return this._messages.join(separator ?? '\n');
-  }
-
-  /**
-   * If any error messages have been aggregated, returns
-   * {@link Failure | Failure<T>} with the aggregated
-   * messages concatenated using the optionally-supplied
-   * separator, or newline.   If the supplied {@link Result | Result<T>}
-   * contains an error message that has not already been aggregated,
-   * it will be included in the aggregated messages.
-   *
-   * If no error messages have been aggregated, returns
-   * the supplied {@link Result | Result<T>}.
-   * @param result - The {@link Result | Result<T>} to be returned
-   * if no messages have been aggregated.
-   * @param separator - Optional string separator used to construct
-   * the error message.
-   * @returns {@link Failure | Failure<T>} with an aggregated message
-   * if any error messages were collected, the supplied
-   * {@link Result | Result<T>} otherwise.
-   */
-  public returnOrReport<T>(result: Result<T>, separator?: string): Result<T> {
-    if (!this.hasMessages) {
-      return result;
-    }
-    if (!result.success) {
-      if (!this._messages.find((s) => s === result.message)) {
-        return fail([...this._messages, result.message].join(separator ?? '\n'));
-      }
-    }
-    return fail(this.toString(separator));
-  }
-}