@rimbu/deep 0.14.5 → 1.0.0-alpha.1

package/src/match.mts

@@ -0,0 +1,700 @@
+import {
+  type IsAnyFunc,
+  type IsArray,
+  isPlainObj,
+  type IsPlainObj,
+  type NotIterable,
+} from '@rimbu/base';
+import type { Protected } from './internal.mjs';
+import type { Tuple } from './tuple.mjs';
+
+/**
+ * The type to determine the allowed input values for the `match` function.
+ * @typeparam T - the type of value to match
+ * @typeparam C - utility type
+ */
+export type Match<T, C extends Partial<T> = Partial<T>> = Match.Entry<
+  T,
+  C,
+  T,
+  T
+>;
+
+export namespace Match {
+  /**
+   * Determines the various allowed match types for given type `T`.
+   * @typeparam T - the input value type
+   * @typeparam C - utility type
+   * @typeparam P - the parent type
+   * @typeparam R - the root object type
+   */
+  export type Entry<T, C, P, R> = IsAnyFunc<T> extends true
+    ? // function can only be directly matched
+      T
+    : IsPlainObj<T> extends true
+    ? // determine allowed match values for object
+      Match.WithResult<T, P, R, Match.Obj<T, C, P, R>>
+    : IsArray<T> extends true
+    ? // determine allowed match values for array or tuple
+      | Match.Arr<T, C, P, R>
+        | Match.Entry<T[number & keyof T], C[number & keyof C], P, R>[]
+        | Match.Func<
+            T,
+            P,
+            R,
+            | Match.Arr<T, C, P, R>
+            | Match.Entry<T[number & keyof T], C[number & keyof C], P, R>[]
+          >
+    : // only accept values with same interface
+      Match.WithResult<T, P, R, { [K in keyof C]: C[K & keyof T] }>;
+
+  /**
+   * The type that determines allowed matchers for objects.
+   * @typeparam T - the input value type
+   * @typeparam C - utility type
+   * @typeparam P - the parent type
+   * @typeparam R - the root object type
+   */
+  export type Obj<T, C, P, R> =
+    | Match.ObjProps<T, C, R>
+    | Match.CompoundForObj<T, C, P, R>;
+
+  /**
+   * The type to determine allowed matchers for object properties.
+   * @typeparam T - the input value type
+   * @typeparam C - utility type
+   * @typeparam R - the root object type
+   */
+  export type ObjProps<T, C, R> = {
+    [K in keyof C]?: K extends keyof T ? Match.Entry<T[K], C[K], T, R> : never;
+  };
+
+  /**
+   * The type that determines allowed matchers for arrays/tuples.
+   * @typeparam T - the input value type
+   * @typeparam C - utility type
+   * @typeparam P - the parent type
+   * @typeparam R - the root object type
+   */
+  export type Arr<T, C, P, R> =
+    | C
+    | Match.CompoundForArr<T, C, P, R>
+    | Match.TraversalForArr<T, C, R>
+    | (Match.TupIndices<T, C, R> & {
+        [K in Match.CompoundType | Match.ArrayTraversalType]?: never;
+      });
+
+  /**
+   * A type that either directly results in result type `S` or is a function taking the value, parent, and root values, and
+   * returns a value of type `S`.
+   * @typeparam T - the input value type
+   * @typeparam P - the parent type
+   * @typeparam R - the root object type
+   * @typeparam S - the result type
+   */
+  export type WithResult<T, P, R, S> = S | Match.Func<T, P, R, S>;
+
+  /**
+   * Type used to determine the allowed function types. Always includes booleans.
+   * @typeparam T - the input value type
+   * @typeparam P - the parent type
+   * @typeparam R - the root object type
+   * @typeparam S - the allowed return value type
+   */
+  export type Func<T, P, R, S> = (
+    current: Protected<T>,
+    parent: Protected<P>,
+    root: Protected<R>
+  ) => boolean | S;
+
+  /**
+   * Type used to indicate an object containing matches for tuple indices.
+   * @typeparam T - the input value type
+   * @typeparam C - utility type
+   * @typeparam R - the root object type
+   */
+  export type TupIndices<T, C, R> = {
+    [K in Tuple.KeysOf<C>]?: Match.Entry<T[K & keyof T], C[K], T, R>;
+  } & NotIterable;
+
+  /**
+   * Compound keys used to indicate the type of compound.
+   */
+  export type CompoundType = 'every' | 'some' | 'none' | 'single';
+
+  /**
+   * Keys used to indicate an array match traversal.
+   */
+  export type ArrayTraversalType = `${CompoundType}Item`;
+
+  /**
+   * Compount matcher for objects, can only be an array staring with a compound type keyword.
+   * @typeparam T - the input value type
+   * @typeparam C - utility type
+   * @typeparam P - the parent type
+   * @typeparam R - the root object type
+   */
+  export type CompoundForObj<T, C, P, R> = [
+    Match.CompoundType,
+    ...Match.Entry<T, C, P, R>[]
+  ];
+
+  /**
+   * Defines an object containing exactly one `CompoundType` key, having an array of matchers.
+   * @typeparam T - the input value type
+   * @typeparam C - utility type
+   * @typeparam P - the parent type
+   * @typeparam R - the root object type
+   */
+  export type CompoundForArr<T, C, P, R> = {
+    [K in Match.CompoundType]: {
+      [K2 in Match.CompoundType]?: K2 extends K
+        ? Match.Entry<T, C, P, R>[]
+        : never;
+    };
+  }[Match.CompoundType];
+
+  /**
+   * Defines an object containing exactly one `TraversalType` key, having a matcher for the array element type.
+   * @typeparam T - the input value type
+   * @typeparam C - utility type
+   * @typeparam R - the root object type
+   */
+  export type TraversalForArr<T, C, R> = {
+    [K in Match.ArrayTraversalType]: {
+      [K2 in Match.ArrayTraversalType]?: K2 extends K
+        ? Match.Entry<T[number & keyof T], C[number & keyof C], T, R>
+        : never;
+    };
+  }[Match.ArrayTraversalType];
+
+  /**
+   * Utility type for collecting match failure reasons
+   */
+  export type FailureLog = string[];
+}
+
+/**
+ * Returns true if the given `value` object matches the given `matcher`, false otherwise.
+ * @typeparam T - the input value type
+ * @typeparam C - utility type
+ * @param source - the value to match (should be a plain object)
+ * @param matcher - a matcher object or a function taking the matcher API and returning a match object
+ * @param failureLog - (optional) a string array that can be passed to collect reasons why the match failed
+ * @example
+ * ```ts
+ * const input = { a: 1, b: { c: true, d: 'a' } }
+ * match(input, { a: 1 }) // => true
+ * match(input, { a: 2 }) // => false
+ * match(input, { a: (v) => v > 10 }) // => false
+ * match(input, { b: { c: true }}) // => true
+ * match(input, (['every', { a: (v) => v > 0 }, { b: { c: true } }]) // => true
+ * match(input, { b: { c: (v, parent, root) => v && parent.d.length > 0 && root.a > 0 } })
+ *  // => true
+ * ```
+ */
+export function match<T, C extends Partial<T> = Partial<T>>(
+  source: T,
+  matcher: Match<T, C>,
+  failureLog?: Match.FailureLog
+): boolean {
+  return matchEntry(source, source, source, matcher as any, failureLog);
+}
+
+/**
+ * Match a generic match entry against the given source.
+ */
+function matchEntry<T, C, P, R>(
+  source: T,
+  parent: P,
+  root: R,
+  matcher: Match.Entry<T, C, P, R>,
+  failureLog?: Match.FailureLog
+): boolean {
+  if (Object.is(source, matcher)) {
+    // value and target are exactly the same, always will be true
+    return true;
+  }
+
+  if (matcher === null || matcher === undefined) {
+    // these matchers can only be direct matches, and previously it was determined that
+    // they are not equal
+    failureLog?.push(
+      `value ${JSON.stringify(source)} did not match matcher ${matcher}`
+    );
+
+    return false;
+  }
+
+  if (typeof source === 'function') {
+    // function source values can only be directly matched
+    const result = Object.is(source, matcher);
+
+    if (!result) {
+      failureLog?.push(
+        `both value and matcher are functions, but they do not have the same reference`
+      );
+    }
+
+    return result;
+  }
+
+  if (typeof matcher === 'function') {
+    // resolve match function first
+    const matcherResult = matcher(source, parent, root);
+
+    if (typeof matcherResult === 'boolean') {
+      // function resulted in a direct match result
+
+      if (!matcherResult) {
+        failureLog?.push(
+          `function matcher returned false for value ${JSON.stringify(source)}`
+        );
+      }
+
+      return matcherResult;
+    }
+
+    // function resulted in a value that needs to be further matched
+    return matchEntry(source, parent, root, matcherResult, failureLog);
+  }
+
+  if (isPlainObj(source)) {
+    // source ia a plain object, can be partially matched
+    return matchPlainObj(source, parent, root, matcher as any, failureLog);
+  }
+
+  if (Array.isArray(source)) {
+    // source is an array
+    return matchArr(source, parent, root, matcher as any, failureLog);
+  }
+
+  // already determined above that the source and matcher are not equal
+
+  failureLog?.push(
+    `value ${JSON.stringify(
+      source
+    )} does not match given matcher ${JSON.stringify(matcher)}`
+  );
+
+  return false;
+}
+
+/**
+ * Match an array matcher against the given source.
+ */
+function matchArr<T extends any[], C, P, R>(
+  source: T,
+  parent: P,
+  root: R,
+  matcher: Match.Arr<T, C, P, R>,
+  failureLog?: Match.FailureLog
+): boolean {
+  if (Array.isArray(matcher)) {
+    // directly compare array contents
+    const length = source.length;
+
+    if (length !== matcher.length) {
+      // if lengths not equal, arrays are not equal
+
+      failureLog?.push(
+        `array lengths are not equal: value length ${source.length} !== matcher length ${matcher.length}`
+      );
+
+      return false;
+    }
+
+    // loop over arrays, matching every value
+    let index = -1;
+    while (++index < length) {
+      if (
+        !matchEntry(source[index], source, root, matcher[index], failureLog)
+      ) {
+        // item did not match, return false
+
+        failureLog?.push(
+          `index ${index} does not match with value ${JSON.stringify(
+            source[index]
+          )} and matcher ${matcher[index]}`
+        );
+
+        return false;
+      }
+    }
+
+    // all items are equal
+    return true;
+  }
+
+  // matcher is plain object
+
+  if (typeof matcher === 'object' && null !== matcher) {
+    if (`every` in matcher) {
+      return matchCompound(
+        source,
+        parent,
+        root,
+        ['every', ...(matcher.every as any)],
+        failureLog
+      );
+    }
+    if (`some` in matcher) {
+      return matchCompound(
+        source,
+        parent,
+        root,
+        ['some', ...(matcher.some as any)],
+        failureLog
+      );
+    }
+    if (`none` in matcher) {
+      return matchCompound(
+        source,
+        parent,
+        root,
+        ['none', ...(matcher.none as any)],
+        failureLog
+      );
+    }
+    if (`single` in matcher) {
+      return matchCompound(
+        source,
+        parent,
+        root,
+        ['single', ...(matcher.single as any)],
+        failureLog
+      );
+    }
+    if (`someItem` in matcher) {
+      return matchTraversal(
+        source,
+        root,
+        'someItem',
+        matcher.someItem as any,
+        failureLog
+      );
+    }
+    if (`everyItem` in matcher) {
+      return matchTraversal(
+        source,
+        root,
+        'everyItem',
+        matcher.everyItem as any,
+        failureLog
+      );
+    }
+    if (`noneItem` in matcher) {
+      return matchTraversal(
+        source,
+        root,
+        'noneItem',
+        matcher.noneItem as any,
+        failureLog
+      );
+    }
+    if (`singleItem` in matcher) {
+      return matchTraversal(
+        source,
+        root,
+        'singleItem',
+        matcher.singleItem as any,
+        failureLog
+      );
+    }
+  }
+
+  // matcher is plain object with index keys
+
+  for (const index in matcher as any) {
+    const matcherAtIndex = (matcher as any)[index];
+
+    if (!(index in source)) {
+      // source does not have item at given index
+
+      failureLog?.push(
+        `index ${index} does not exist in source ${JSON.stringify(
+          source
+        )} but should match matcher ${JSON.stringify(matcherAtIndex)}`
+      );
+
+      return false;
+    }
+
+    // match the source item at the given index
+    const result = matchEntry(
+      (source as any)[index],
+      source,
+      root,
+      matcherAtIndex,
+      failureLog
+    );
+
+    if (!result) {
+      // item did not match
+
+      failureLog?.push(
+        `index ${index} does not match with value ${JSON.stringify(
+          (source as any)[index]
+        )} and matcher ${JSON.stringify(matcherAtIndex)}`
+      );
+
+      return false;
+    }
+  }
+
+  // all items match
+
+  return true;
+}
+
+/**
+ * Match an object matcher against the given source.
+ */
+function matchPlainObj<T extends object, C, P, R>(
+  source: T,
+  parent: P,
+  root: R,
+  matcher: Match.Obj<T, C, P, R>,
+  failureLog?: Match.FailureLog
+): boolean {
+  if (Array.isArray(matcher)) {
+    // the matcher is of compound type
+    return matchCompound(source, parent, root, matcher as any, failureLog);
+  }
+
+  // partial object props matcher
+
+  for (const key in matcher) {
+    if (!(key in source)) {
+      // the source does not have the given key
+
+      failureLog?.push(
+        `key ${key} is specified in matcher but not present in value ${JSON.stringify(
+          source
+        )}`
+      );
+
+      return false;
+    }
+
+    // match the source value at the given key with the matcher at given key
+    const result = matchEntry(
+      (source as any)[key],
+      source,
+      root,
+      matcher[key],
+      failureLog
+    );
+
+    if (!result) {
+      failureLog?.push(
+        `key ${key} does not match in value ${JSON.stringify(
+          (source as any)[key]
+        )} with matcher ${JSON.stringify(matcher[key])}`
+      );
+      return false;
+    }
+  }
+
+  // all properties match
+
+  return true;
+}
+
+/**
+ * Match a compound matcher against the given source.
+ */
+function matchCompound<T, C, P, R>(
+  source: T,
+  parent: P,
+  root: R,
+  compound: [Match.CompoundType, ...Match.Entry<T, C, P, R>[]],
+  failureLog?: Match.FailureLog
+): boolean {
+  // first item indicates compound match type
+  const matchType = compound[0];
+
+  const length = compound.length;
+
+  // start at index 1
+  let index = 0;
+
+  type Entry = Match.Entry<T, C, P, R>;
+
+  switch (matchType) {
+    case 'every': {
+      while (++index < length) {
+        // if any item does not match, return false
+        const result = matchEntry(
+          source,
+          parent,
+          root,
+          compound[index] as Entry,
+          failureLog
+        );
+
+        if (!result) {
+          failureLog?.push(
+            `in compound "every": match at index ${index} failed`
+          );
+
+          return false;
+        }
+      }
+
+      return true;
+    }
+    case 'none': {
+      // if any item matches, return false
+      while (++index < length) {
+        const result = matchEntry(
+          source,
+          parent,
+          root,
+          compound[index] as Entry,
+          failureLog
+        );
+
+        if (result) {
+          failureLog?.push(
+            `in compound "none": match at index ${index} succeeded`
+          );
+
+          return false;
+        }
+      }
+
+      return true;
+    }
+    case 'single': {
+      // if not exactly one item matches, return false
+      let onePassed = false;
+
+      while (++index < length) {
+        const result = matchEntry(
+          source,
+          parent,
+          root,
+          compound[index] as Entry,
+          failureLog
+        );
+
+        if (result) {
+          if (onePassed) {
+            failureLog?.push(
+              `in compound "single": multiple matches succeeded`
+            );
+
+            return false;
+          }
+
+          onePassed = true;
+        }
+      }
+
+      if (!onePassed) {
+        failureLog?.push(`in compound "single": no matches succeeded`);
+      }
+
+      return onePassed;
+    }
+    case 'some': {
+      // if any item matches, return true
+      while (++index < length) {
+        const result = matchEntry(
+          source,
+          parent,
+          root,
+          compound[index] as Entry,
+          failureLog
+        );
+
+        if (result) {
+          return true;
+        }
+      }
+
+      failureLog?.push(`in compound "some": no matches succeeded`);
+
+      return false;
+    }
+  }
+}
+
+function matchTraversal<T extends any[], C extends any[], R>(
+  source: T,
+  root: R,
+  matchType: Match.ArrayTraversalType,
+  matcher: Match.Entry<T[keyof T], C[keyof C], T, R>,
+  failureLog?: Match.FailureLog
+): boolean {
+  let index = -1;
+  const length = source.length;
+
+  switch (matchType) {
+    case 'someItem': {
+      while (++index < length) {
+        if (matchEntry(source[index], source, root, matcher, failureLog)) {
+          return true;
+        }
+      }
+
+      failureLog?.push(
+        `in array traversal "someItem": no items matched given matcher`
+      );
+
+      return false;
+    }
+    case 'everyItem': {
+      while (++index < length) {
+        if (!matchEntry(source[index], source, root, matcher, failureLog)) {
+          failureLog?.push(
+            `in array traversal "everyItem": at least one item did not match given matcher`
+          );
+          return false;
+        }
+      }
+
+      return true;
+    }
+    case 'noneItem': {
+      while (++index < length) {
+        if (matchEntry(source[index], source, root, matcher, failureLog)) {
+          failureLog?.push(
+            `in array traversal "noneItem": at least one item matched given matcher`
+          );
+          return false;
+        }
+      }
+
+      return true;
+    }
+    case 'singleItem': {
+      let singleMatched = false;
+
+      while (++index < length) {
+        if (matchEntry(source[index], source, root, matcher, failureLog)) {
+          if (singleMatched) {
+            failureLog?.push(
+              `in array traversal "singleItem": more than one item matched given matcher`
+            );
+
+            return false;
+          }
+
+          singleMatched = true;
+        }
+      }
+
+      if (!singleMatched) {
+        failureLog?.push(
+          `in array traversal "singleItem": no item matched given matcher`
+        );
+
+        return false;
+      }
+
+      return true;
+    }
+  }
+}