// effects: pure
/**
 * Curried functional utilities for array operations and composition.
 *
 * Several utilities here are thin curried adapters over `@std/collections`,
 * keeping the project's pipe-friendly calling convention while delegating the
 * actual work to the standard library.
 */

import {
  chunk as stdChunk,
  distinct as stdDistinct,
  distinctBy as stdDistinctBy,
  mapNotNullish as stdMapNotNullish,
  partition as stdPartition,
  sumOf as stdSumOf,
} from "@std/collections";

// --- Pipe type helpers ---
//
// `pipe` threads intermediate types left-to-right so that an unannotated
// callback in a later stage (e.g. `map((x) => x.id)` after a `filter(...)`)
// infers its parameter type from the previous stage's output. This is achieved
// with arity-numbered overloads: TS threads A→B→C… across explicit parameters
// far more readily than across a generic tuple, and the per-stage contextual
// type lets the curried combinators (`map`, `filter`, `flatMap`, …) resolve
// their element type parameter from the boundary instead of collapsing to
// `unknown`. Omitting a variadic fallback is deliberate — a mismatched chain
// has no matching overload and fails to compile, which is the safety contract
// callers rely on. The largest chain in the repo today is 7 stages, and the
// overloads cover 9, so adding a stage means adding one overload line.

/**
 * Compose functions left-to-right (pipe).
 */
export function pipe<A>(): (a: A) => A;
export function pipe<A, B>(ab: (a: A) => B): (a: A) => B;
export function pipe<A, B, C>(ab: (a: A) => B, bc: (b: B) => C): (a: A) => C;
export function pipe<A, B, C, D>(
  ab: (a: A) => B,
  bc: (b: B) => C,
  cd: (c: C) => D,
): (a: A) => D;
export function pipe<A, B, C, D, E>(
  ab: (a: A) => B,
  bc: (b: B) => C,
  cd: (c: C) => D,
  de: (d: D) => E,
): (a: A) => E;
export function pipe<A, B, C, D, E, F>(
  ab: (a: A) => B,
  bc: (b: B) => C,
  cd: (c: C) => D,
  de: (d: D) => E,
  ef: (e: E) => F,
): (a: A) => F;
export function pipe<A, B, C, D, E, F, G>(
  ab: (a: A) => B,
  bc: (b: B) => C,
  cd: (c: C) => D,
  de: (d: D) => E,
  ef: (e: E) => F,
  fg: (f: F) => G,
): (a: A) => G;
export function pipe<A, B, C, D, E, F, G, H>(
  ab: (a: A) => B,
  bc: (b: B) => C,
  cd: (c: C) => D,
  de: (d: D) => E,
  ef: (e: E) => F,
  fg: (f: F) => G,
  gh: (g: G) => H,
): (a: A) => H;
export function pipe<A, B, C, D, E, F, G, H, I>(
  ab: (a: A) => B,
  bc: (b: B) => C,
  cd: (c: C) => D,
  de: (d: D) => E,
  ef: (e: E) => F,
  fg: (f: F) => G,
  gh: (g: G) => H,
  hi: (h: H) => I,
): (a: A) => I;
export function pipe<A, B, C, D, E, F, G, H, I, J>(
  ab: (a: A) => B,
  bc: (b: B) => C,
  cd: (c: C) => D,
  de: (d: D) => E,
  ef: (e: E) => F,
  fg: (f: F) => G,
  gh: (g: G) => H,
  hi: (h: H) => I,
  ij: (i: I) => J,
): (a: A) => J;
export function pipe(
  ...fns: Array<(arg: unknown) => unknown>
): (value: unknown) => unknown {
  return (value: unknown): unknown => fns.reduce((acc, fn) => fn(acc), value);
}

/**
 * Curried filter
 */
export const filter =
  <T>(predicate: (item: T) => boolean) =>
  (array: readonly T[]): T[] =>
    array.filter(predicate);

/**
 * Curried map
 */
export const map =
  <T, U>(fn: (item: T) => U) =>
  (array: readonly T[]): U[] =>
    array.map(fn);

/**
 * Curried flatMap
 */
export const flatMap =
  <T, U>(fn: (item: T) => U[]) =>
  (array: T[]): U[] =>
    array.flatMap(fn);

/**
 * Split an array into [matching, rest] by a predicate, keeping order.
 * Curried adapter over `@std/collections.partition`.
 */
export const partition =
  <T>(predicate: (item: T) => boolean) =>
  (array: T[]): [T[], T[]] =>
    stdPartition(array, predicate);

/**
 * Curried map that drops null/undefined results in one pass.
 * Curried adapter over `@std/collections.mapNotNullish`.
 * Replaces the two-step pattern: compact(map(fn)(array))
 */
export const mapNotNullish =
  <T, U>(fn: (item: T) => U | null | undefined) =>
  (array: Iterable<T>): U[] =>
    stdMapNotNullish(array, fn);

/** Check items in order and stop at the first reported problem. */
export const firstProblem =
  <T>(check: (item: T) => string | null | Promise<string | null>) =>
  async (items: readonly T[]): Promise<string | null> => {
    for (const item of items) {
      const problem = await check(item);
      if (problem) return problem;
    }
    return null;
  };

/**
 * Curried reduce
 */
export const reduce =
  <T, U>(fn: (acc: U, item: T) => U, initial: U) =>
  (array: T[]): U =>
    array.reduce(fn, initial);

/**
 * Non-mutating sort with comparator
 */
export const sort =
  <T>(comparator: (a: T, b: T) => number) =>
  (array: T[]): T[] =>
    array.toSorted(comparator);

/** Sort strings in ascending locale order without changing the input. */
export const sortStrings = (array: string[]): string[] =>
  sort((a: string, b: string) => a.localeCompare(b))(array);

/** The numbers, each once, smallest first. */
export const sortedNumbers = (array: readonly number[]): number[] =>
  unique([...array]).sort((a: number, b: number) => a - b);

/**
 * Remove duplicate values (by reference/value equality), keeping first
 * occurrences in order. Curried adapter over `@std/collections.distinct`.
 */
export const unique = <T>(array: T[]): T[] => stdDistinct(array);

/**
 * Remove duplicates by a key function, keeping first occurrences in order.
 * Curried adapter over `@std/collections.distinctBy`.
 */
export const uniqueBy =
  <T>(fn: (item: T) => unknown) =>
  (array: T[]): T[] =>
    stdDistinctBy(array, fn);

/**
 * Group rows by a key, keeping only the chosen value from each row.
 * Keys appear in first-occurrence order and each value list preserves input
 * order.
 */
export const groupToMap =
  <T, K, V>(keyOf: (row: T) => K, valueFrom: (row: T) => V) =>
  (rows: readonly T[]): Map<K, V[]> =>
    new Map(
      [...Map.groupBy(rows, keyOf)].map(([key, group]) => [
        key,
        group.map(valueFrom),
      ]),
    );

/**
 * Key items by their own id, so a caller can look one up. Hand-rolled because
 * `@std/collections.associateBy` keys by a string and gives back an object,
 * while every caller here has number ids and wants a Map.
 */
export const byId = <T extends { id: number }>(
  items: readonly T[],
): Map<number, T> => new Map(items.map((item) => [item.id, item]));

/** Keep the items a test accepts, then take one thing from each. */
export const keepAndTake =
  <T, R>(
    keep: (item: T) => boolean,
    take: (item: T) => R,
  ): ((items: readonly T[]) => R[]) =>
  (items) =>
    items.filter(keep).map(take);

/** Whether two records hold the same value in every named field. */
export const sameOn =
  <T>(...fields: readonly (keyof T)[]): ((left: T, right: T) => boolean) =>
  (left, right) =>
    fields.every((field) => left[field] === right[field]);

/** A Map holding an empty list for each key, ready to be filled. */
export const emptyListsFor = <Key, Value>(
  keys: readonly Key[],
): Map<Key, Value[]> => new Map(keys.map((key) => [key, []]));

/**
 * Whether two sequences hold the same values, in the same order. It stops at
 * the first difference, so how long it takes says how much matched: never
 * compare secrets with it.
 */
export const sameOrder = <T>(
  left: ArrayLike<T>,
  right: ArrayLike<T>,
): boolean => {
  if (left.length !== right.length) return false;
  for (let index = 0; index < left.length; index++) {
    if (left[index] !== right[index]) return false;
  }
  return true;
};

/** Read a required map entry, failing where a broken completeness invariant is
 * first observed instead of passing an undefined value onward. */
export const requiredMapValue = <Key, Value>(
  values: ReadonlyMap<Key, Value>,
  key: Key,
  errorMessage: string,
): Value => {
  const value = values.get(key);
  if (value === undefined) throw new Error(errorMessage);
  return value;
};

/**
 * Remove null and undefined values from array
 */
export const isNullish = (value: unknown): value is null | undefined =>
  value === null || value === undefined;

export const isNotNullish = <T>(value: T | null | undefined): value is T =>
  !isNullish(value);

/** Ask whether a value is one of a fixed list: `isOneOf(["a", "b"])("a")` is
 * true. Curried, so a list of words becomes one named check. */
export const isOneOf =
  (values: readonly string[]): ((value: string | undefined) => boolean) =>
  (value) =>
    value !== undefined && values.includes(value);

export const compact = <T>(array: (T | null | undefined)[]): T[] =>
  array.filter(isNotNullish);

/**
 * The keys of `all` that no listed item carries. The second argument list is
 * curried so a caller reads "these keys, not covered by that list".
 */
export const notCoveredBy =
  <T, K>(keyOf: (item: T) => K, knowns: readonly T[]) =>
  (all: readonly K[]): K[] => {
    const carried = new Set(knowns.map(keyOf));
    return all.filter((key) => !carried.has(key));
  };

/**
 * Alternative combinator: try a sequence of producers in order and return the
 * first that yields a defined value, or undefined if every one declines.
 *
 * Producers run lazily and may be async (each is awaited before the next is
 * tried), so later, more expensive lookups are skipped once one claims the
 * input. Use it to fold an ordered set of fallible parsers/handlers into a
 * single "first match wins" lookup instead of an `if … else if …` ladder. A
 * `null` result counts as a match (the producer claimed the input but found it
 * invalid), distinct from `undefined` ("not mine — try the next").
 */
export const firstMatch = async <T>(
  producers: ReadonlyArray<() => T | undefined | Promise<T | undefined>>,
): Promise<T | undefined> => {
  for (const produce of producers) {
    const value = await produce();
    if (value !== undefined) return value;
  }
  return;
};

/**
 * Lazy evaluation - compute once on first call, cache forever.
 * Use instead of `let x = null; const getX = () => x ??= compute();`
 */
export const once = <T>(fn: () => T): (() => T) => {
  let computed = false;
  let value: T;
  return (): T => {
    if (!computed) {
      value = fn();
      computed = true;
    }
    return value;
  };
};

/**
 * Resettable lazy reference - like once() but can be reset for testing.
 * Returns [get, set] tuple where set(null) resets to uncomputed state.
 */
export const lazyRef = <T>(
  fn: () => T,
): [get: () => T, set: (value: T | null) => void] => {
  let computed = false;
  let value: T;
  const get = (): T => {
    if (!computed) {
      value = fn();
      computed = true;
    }
    return value;
  };
  const set = (newValue: T | null): void => {
    if (newValue === null) {
      computed = false;
    } else {
      value = newValue;
      computed = true;
    }
  };
  return [get, set];
};

/**
 * Resource management pattern (like Haskell's bracket or try-with-resources).
 * Ensures cleanup happens even if the operation throws.
 *
 * @example
 * const withConnection = bracket(
 *   () => openConnection(),
 *   (conn) => conn.close()
 * );
 * const result = await withConnection(async (conn) => conn.query('SELECT 1'));
 */
export const bracket =
  <R>(acquire: () => R | Promise<R>, release: (r: R) => void | Promise<void>) =>
  async <T>(use: (r: R) => T | Promise<T>): Promise<T> => {
    const resource = await acquire();
    try {
      return await use(resource);
    } finally {
      await release(resource);
    }
  };

/**
 * Narrow an unknown value to string, defaulting to "" if not a string.
 * Replaces `typeof x === "string" ? x : ""` at type boundaries.
 */
export const asString = (value: unknown): string =>
  typeof value === "string" ? value : "";

/**
 * Join an array of strings into a single string (curried reduce shorthand).
 * Replaces the common pattern: reduce((acc: string, s: string) => acc + s, "")
 */
export const joinStrings = reduce((acc: string, s: string) => acc + s, "");

/**
 * Curried sum-by-selector. Adds up the numbers produced by `selector` for each
 * item. Curried adapter over `@std/collections.sumOf`.
 * Replaces the common pattern: reduce((acc, x) => acc + selector(x), 0)
 */
export const sumOf =
  <T>(selector: (item: T) => number) =>
  (array: Iterable<T>): number =>
    stdSumOf(array, selector);

/**
 * Sum an array of numbers (identity selector shorthand for sumOf).
 * Replaces the common pattern: reduce((acc, n) => acc + n, 0)
 */
export const sum = sumOf((n: number) => n);

/**
 * Curried group-and-sum: accumulate `valueOf(item)` into a `Map` keyed by
 * `keyOf(item)`. Replaces the common pattern:
 *   const m = new Map(); for (const x of xs) m.set(k(x), (m.get(k(x)) ?? 0) + v(x))
 */
export const sumByKey =
  <T, K>(keyOf: (item: T) => K, amountOf: (item: T) => number) =>
  (items: Iterable<T>): Map<K, number> => {
    const totals = new Map<K, number>();
    for (const item of items) {
      const key = keyOf(item);
      totals.set(key, (totals.get(key) ?? 0) + amountOf(item));
    }
    return totals;
  };

/** Return a value unchanged. */
export const identity = <T>(value: T): T => value;

/** Index items by one field and chosen value. Keys keep first-occurrence order,
 * while later matching items replace the stored value. */
export const mapBy =
  <T, Key extends keyof T, V>(key: Key, valueFrom: (item: T) => V) =>
  (items: Iterable<T>): Map<T[Key], V> => {
    const result = new Map<T[Key], V>();
    for (const item of items) result.set(item[key], valueFrom(item));
    return result;
  };

/** Index items by `id` and a chosen value. */
export const mapById = <T extends { id: unknown }, V>(
  valueFrom: (item: T) => V,
): ((items: Iterable<T>) => Map<T["id"], V>) => mapBy("id", valueFrom);

/** Index one field from each item by its `id`. */
export const fieldById =
  <Field extends PropertyKey>(field: Field) =>
  <T extends { id: unknown } & Record<Field, unknown>>(
    items: Iterable<T>,
  ): Map<T["id"], T[Field]> =>
    mapById((item: T) => item[field])(items);

/**
 * A copy of `base` with `extra` entries merged on top (an `extra` key wins over
 * the same key in `base`). Curried so a constant overlay (a fixed content type,
 * a default set) can extend whatever record it is given.
 */
export const extendedBy =
  <V>(extra: Record<string, V>) =>
  (base: Record<string, V>): Record<string, V> => ({ ...base, ...extra });

/**
 * Split an array into chunks of a given size.
 * Curried adapter over `@std/collections.chunk` (which throws for size < 1).
 */
export const chunk =
  (size: number) =>
  <T>(array: T[]): T[][] =>
    stdChunk(array, size);

/**
 * Whole numbers counting up from `start`, stopping before `end` ([] when `end`
 * is not past `start`). Hand-rolled because `@std/collections` has no numeric
 * range helper. Iterating this bounded array replaces hand-counted loops,
 * which a single slip in their step can make endless.
 */
export const range = (start: number, end: number): number[] =>
  Array.from({ length: Math.max(0, end - start) }, (_, i) => start + i);

/**
 * Map over a promise-returning function in parallel (Promise.all)
 */
export const mapParallel =
  <T, U>(fn: (item: T) => Promise<U>) =>
  (array: readonly T[]): Promise<U[]> =>
    Promise.all(array.map(fn));

/** Collection cache returned by collectionCache() */
export type CollectionCache<T> = {
  getAll: () => Promise<T[]>;
  invalidate: () => void;
  size: () => number;
};

/**
 * Create an in-memory collection cache with TTL.
 * Loads all items via fetchAll on first access or after invalidation/expiry,
 * then serves from memory until the TTL expires or invalidate() is called.
 * Takes the clock as an argument: pass nowMs, or a fake clock in a test.
 *
 * Uses a generation counter to prevent a race condition where a concurrent
 * fetchAll() that started before an invalidation could overwrite the cache
 * with stale data.
 */
export const collectionCache = <T>(
  fetchAll: () => Promise<T[]>,
  ttlMs: number,
  now: () => number,
): CollectionCache<T> => {
  const [getState, setState] = lazyRef<{ items: T[] | null; time: number }>(
    () => ({ items: null, time: 0 }),
  );
  let generation = 0;
  return {
    getAll: async (): Promise<T[]> => {
      const state = getState();
      if (state.items !== null && now() - state.time <= ttlMs) {
        return state.items;
      }
      const gen = generation;
      const items = await fetchAll();
      if (gen === generation) {
        setState({ items, time: now() });
      }
      return items;
    },
    invalidate: (): void => {
      generation++;
      setState(null);
    },
    size: (): number => getState().items?.length ?? 0,
  };
};

/** TTL cache returned by ttlCache() */
export type TtlCache<K, V> = {
  get: (key: K) => V | undefined;
  set: (key: K, value: V) => void;
  clear: () => void;
  size: () => number;
};

/**
 * Create a TTL (Time-To-Live) cache.
 * Entries expire after ttlMs milliseconds.
 * Takes the clock as an argument: pass nowMs, or a fake clock in a test.
 * Give maxEntries a value to bound the cache: storing a new key at the cap
 * drops the oldest-stored entry first. Bound any cache whose keys can be
 * chosen from outside (e.g. unknown session cookies), so a flood of unique
 * keys cannot grow it without limit. Leave it unset for caches whose keyspace
 * our own data already bounds — the keyed entity caches rely on holding every
 * row of their table.
 */
export const ttlCache = <K, V>(
  ttlMs: number,
  now: () => number,
  maxEntries?: number,
): TtlCache<K, V> => {
  const cache = new Map<K, { value: V; cachedAt: number }>();
  return {
    clear: (): void => {
      cache.clear();
    },
    get: (key: K): V | undefined => {
      const entry = cache.get(key);
      if (!entry) return;
      if (now() - entry.cachedAt > ttlMs) {
        cache.delete(key);
        return;
      }
      return entry.value;
    },
    set: (key: K, value: V): void => {
      // Deleting first re-inserts a refreshed key at the newest position, so
      // the Map's first key is always the oldest-stored entry.
      cache.delete(key);
      if (maxEntries !== undefined && cache.size >= maxEntries) {
        const oldest = cache.keys().next();
        if (!oldest.done) cache.delete(oldest.value);
      }
      cache.set(key, { cachedAt: now(), value });
    },
    size: (): number => cache.size,
  };
};