@fgv/ts-utils 5.0.0-2 → 5.0.0-21

package/src/packlets/base/mapResults.ts

@@ -0,0 +1,302 @@
+/*
+ * 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

@@ -0,0 +1,120 @@
+/*
+ * 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));
+  }
+}

package/src/packlets/base/normalize.ts

@@ -0,0 +1,144 @@
+/*
+ * Copyright (c) 2021 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 { mapResults } from './mapResults';
+import { Result, fail, succeed } from './result';
+
+/**
+ * @internal
+ */
+export type Entry<T> = [string | number | symbol, T];
+
+/**
+ * @internal
+ */
+export type ResultEntry<T> = [string | number | symbol, Result<T>];
+
+/**
+ * Normalizes an arbitrary JSON object
+ * @public
+ */
+export class Normalizer {
+  /**
+   * Normalizes the supplied value
+   *
+   * @param from - The value to be normalized
+   * @returns A normalized version of the value
+   */
+  public normalize<T>(from: T): Result<T> {
+    switch (typeof from) {
+      case 'string':
+      case 'bigint':
+      case 'boolean':
+      case 'number':
+      case 'symbol':
+      case 'undefined':
+        return this.normalizeLiteral(from);
+      case 'object':
+        if (from === null || from instanceof Date || from instanceof RegExp) {
+          return this.normalizeLiteral(from);
+        } else if (Array.isArray(from)) {
+          return this._normalizeArray(from) as unknown as Result<T>;
+        } else if (from instanceof Map) {
+          return succeed(new Map(this.normalizeEntries(from.entries())) as unknown as T);
+        } else if (from instanceof Set) {
+          return succeed(new Set(this.normalizeEntries(from.entries())) as unknown as T);
+        }
+        const obj: { [key in number | string | symbol]: unknown } = {};
+        for (const e of this.normalizeEntries(Object.entries(from as unknown as object))) {
+          obj[e[0]] = e[1];
+        }
+        return succeed(obj as T);
+    }
+    return fail(`normalize: Unexpected type - cannot normalize '${typeof from}'`);
+  }
+
+  /**
+   * Compares two property names from some object being normalized.
+   * @param k1 - First key to be compared.
+   * @param k2 - Second key to be compared.
+   * @returns `1` if `k1` is greater, `-1` if `k2` is greater and
+   * `0` if they are equal.
+   * @internal
+   */
+  protected _compareKeys(k1: unknown, k2: unknown): number {
+    const cs1 = String(k1);
+    const cs2 = String(k2);
+    if (cs1 > cs2) {
+      return 1;
+    }
+    if (cs2 > cs1) {
+      return -1;
+    }
+    /* c8 ignore next 2 */
+    return 0;
+  }
+
+  /**
+   * Normalizes an array of object property entries (e.g. as returned by `Object.entries()`).
+   * @remarks
+   * Converts property names (entry key) to string and then sorts as string.
+   * @param entries - The entries to be normalized.
+   * @returns A normalized sorted array of entries.
+   */
+  public normalizeEntries<T = unknown>(entries: Iterable<Entry<T>>): Entry<T>[] {
+    return Array.from(entries)
+      .sort((e1, e2) => this._compareKeys(e1[0], e2[0]))
+      .map((e) => [e[0], this.normalize(e[1])] as ResultEntry<T>)
+      .filter((e) => e[1].isSuccess())
+      .map((e) => [e[0], e[1].orThrow()]);
+  }
+
+  protected _normalizeArray(from: unknown[]): Result<unknown[]> {
+    return mapResults(from.map((v) => this.normalize(v)));
+  }
+
+  /**
+   * Normalizes the supplied literal value
+   * @param from - The literal value to be normalized.
+   * @returns A normalized value for the literal.
+   */
+  public normalizeLiteral<T>(from: T): Result<T> {
+    // TODO: Apply configurable normalization rules
+    switch (typeof from) {
+      case 'string':
+        return succeed(from);
+      case 'bigint':
+      case 'boolean':
+      case 'number':
+      case 'symbol':
+      case 'undefined':
+        return succeed(from);
+    }
+    if (from === null) {
+      return succeed(from);
+    }
+    if (from instanceof Date) {
+      return succeed(from);
+    }
+    if (from instanceof RegExp) {
+      return succeed(from);
+    }
+    /* c8 ignore next 2 */
+    return fail(`cannot normalize ${JSON.stringify(from)}`);
+  }
+}