@pyreon/rx 0.11.0

package/src/aggregation.ts

@@ -0,0 +1,86 @@
+import { computed } from "@pyreon/reactivity"
+import type { KeyOf, ReadableSignal } from "./types"
+import { isSignal, resolveKey } from "./types"
+
+function reactive<TIn, TOut>(source: TIn, fn: (val: any) => TOut): any {
+  if (isSignal(source)) return computed(() => fn((source as ReadableSignal<any>)()))
+  return fn(source)
+}
+
+/** Count items in collection. */
+export function count<T>(source: ReadableSignal<T[]>): ReturnType<typeof computed<number>>
+export function count<T>(source: T[]): number
+export function count<T>(source: ReadableSignal<T[]> | T[]): any {
+  return reactive(source, (arr: T[]) => arr.length)
+}
+
+/** Sum numeric values. Optionally by key. */
+export function sum<T>(
+  source: ReadableSignal<T[]>,
+  key?: KeyOf<T>,
+): ReturnType<typeof computed<number>>
+export function sum<T>(source: T[], key?: KeyOf<T>): number
+export function sum<T>(source: ReadableSignal<T[]> | T[], key?: KeyOf<T>): any {
+  const getVal = key ? resolveKey(key) : (item: T) => item as unknown as number
+  return reactive(source, (arr: T[]) => arr.reduce((acc, item) => acc + Number(getVal(item)), 0))
+}
+
+/** Find minimum item. Optionally by key. */
+export function min<T>(
+  source: ReadableSignal<T[]>,
+  key?: KeyOf<T>,
+): ReturnType<typeof computed<T | undefined>>
+export function min<T>(source: T[], key?: KeyOf<T>): T | undefined
+export function min<T>(source: ReadableSignal<T[]> | T[], key?: KeyOf<T>): any {
+  const getVal = key ? resolveKey(key) : (item: T) => item as unknown as number
+  return reactive(source, (arr: T[]) => {
+    if (arr.length === 0) return undefined
+    let result = arr[0] as T
+    let minVal = Number(getVal(result))
+    for (let i = 1; i < arr.length; i++) {
+      const val = Number(getVal(arr[i] as T))
+      if (val < minVal) {
+        minVal = val
+        result = arr[i] as T
+      }
+    }
+    return result
+  })
+}
+
+/** Find maximum item. Optionally by key. */
+export function max<T>(
+  source: ReadableSignal<T[]>,
+  key?: KeyOf<T>,
+): ReturnType<typeof computed<T | undefined>>
+export function max<T>(source: T[], key?: KeyOf<T>): T | undefined
+export function max<T>(source: ReadableSignal<T[]> | T[], key?: KeyOf<T>): any {
+  const getVal = key ? resolveKey(key) : (item: T) => item as unknown as number
+  return reactive(source, (arr: T[]) => {
+    if (arr.length === 0) return undefined
+    let result = arr[0] as T
+    let maxVal = Number(getVal(result))
+    for (let i = 1; i < arr.length; i++) {
+      const val = Number(getVal(arr[i] as T))
+      if (val > maxVal) {
+        maxVal = val
+        result = arr[i] as T
+      }
+    }
+    return result
+  })
+}
+
+/** Average of numeric values. Optionally by key. */
+export function average<T>(
+  source: ReadableSignal<T[]>,
+  key?: KeyOf<T>,
+): ReturnType<typeof computed<number>>
+export function average<T>(source: T[], key?: KeyOf<T>): number
+export function average<T>(source: ReadableSignal<T[]> | T[], key?: KeyOf<T>): any {
+  const getVal = key ? resolveKey(key) : (item: T) => item as unknown as number
+  return reactive(source, (arr: T[]) => {
+    if (arr.length === 0) return 0
+    return arr.reduce((acc, item) => acc + Number(getVal(item)), 0) / arr.length
+  })
+}

package/src/collections.ts

@@ -0,0 +1,189 @@
+import { computed } from "@pyreon/reactivity"
+import type { KeyOf, ReadableSignal } from "./types"
+import { isSignal, resolveKey } from "./types"
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+function reactive<TIn, TOut>(
+  source: TIn,
+  fn: (val: any) => TOut,
+): TIn extends ReadableSignal<any> ? ReturnType<typeof computed<TOut>> : TOut {
+  if (isSignal(source)) {
+    return computed(() => fn((source as ReadableSignal<any>)())) as any
+  }
+  return fn(source) as any
+}
+
+// ─── Collection transforms ──────────────────────────────────────────────────
+
+/** Filter items by predicate. Signal in → Computed out. */
+export function filter<T>(
+  source: ReadableSignal<T[]>,
+  predicate: (item: T, index: number) => boolean,
+): ReturnType<typeof computed<T[]>>
+export function filter<T>(source: T[], predicate: (item: T, index: number) => boolean): T[]
+export function filter<T>(
+  source: ReadableSignal<T[]> | T[],
+  predicate: (item: T, index: number) => boolean,
+): any {
+  return reactive(source, (arr: T[]) => arr.filter(predicate))
+}
+
+/** Map items to a new type. */
+export function map<T, U>(
+  source: ReadableSignal<T[]>,
+  fn: (item: T, index: number) => U,
+): ReturnType<typeof computed<U[]>>
+export function map<T, U>(source: T[], fn: (item: T, index: number) => U): U[]
+export function map<T, U>(
+  source: ReadableSignal<T[]> | T[],
+  fn: (item: T, index: number) => U,
+): any {
+  return reactive(source, (arr: T[]) => arr.map(fn))
+}
+
+/** Sort items by key or comparator. */
+export function sortBy<T>(
+  source: ReadableSignal<T[]>,
+  key: KeyOf<T>,
+): ReturnType<typeof computed<T[]>>
+export function sortBy<T>(source: T[], key: KeyOf<T>): T[]
+export function sortBy<T>(source: ReadableSignal<T[]> | T[], key: KeyOf<T>): any {
+  const getKey = resolveKey(key)
+  return reactive(source, (arr: T[]) =>
+    [...arr].sort((a, b) => {
+      const ka = getKey(a)
+      const kb = getKey(b)
+      return ka < kb ? -1 : ka > kb ? 1 : 0
+    }),
+  )
+}
+
+/** Group items by key. Returns Record<string, T[]>. */
+export function groupBy<T>(
+  source: ReadableSignal<T[]>,
+  key: KeyOf<T>,
+): ReturnType<typeof computed<Record<string, T[]>>>
+export function groupBy<T>(source: T[], key: KeyOf<T>): Record<string, T[]>
+export function groupBy<T>(source: ReadableSignal<T[]> | T[], key: KeyOf<T>): any {
+  const getKey = resolveKey(key)
+  return reactive(source, (arr: T[]) => {
+    const result: Record<string, T[]> = {}
+    for (const item of arr) {
+      const k = String(getKey(item))
+      let group = result[k]
+      if (!group) {
+        group = []
+        result[k] = group
+      }
+      group.push(item)
+    }
+    return result
+  })
+}
+
+/** Index items by key. Returns Record<string, T> (last wins on collision). */
+export function keyBy<T>(
+  source: ReadableSignal<T[]>,
+  key: KeyOf<T>,
+): ReturnType<typeof computed<Record<string, T>>>
+export function keyBy<T>(source: T[], key: KeyOf<T>): Record<string, T>
+export function keyBy<T>(source: ReadableSignal<T[]> | T[], key: KeyOf<T>): any {
+  const getKey = resolveKey(key)
+  return reactive(source, (arr: T[]) => {
+    const result: Record<string, T> = {}
+    for (const item of arr) result[String(getKey(item))] = item
+    return result
+  })
+}
+
+/** Deduplicate items by key. */
+export function uniqBy<T>(
+  source: ReadableSignal<T[]>,
+  key: KeyOf<T>,
+): ReturnType<typeof computed<T[]>>
+export function uniqBy<T>(source: T[], key: KeyOf<T>): T[]
+export function uniqBy<T>(source: ReadableSignal<T[]> | T[], key: KeyOf<T>): any {
+  const getKey = resolveKey(key)
+  return reactive(source, (arr: T[]) => {
+    const seen = new Set<string | number>()
+    return arr.filter((item) => {
+      const k = getKey(item)
+      if (seen.has(k)) return false
+      seen.add(k)
+      return true
+    })
+  })
+}
+
+/** Take the first n items. */
+export function take<T>(source: ReadableSignal<T[]>, n: number): ReturnType<typeof computed<T[]>>
+export function take<T>(source: T[], n: number): T[]
+export function take<T>(source: ReadableSignal<T[]> | T[], n: number): any {
+  return reactive(source, (arr: T[]) => arr.slice(0, n))
+}
+
+/** Split into chunks of given size. */
+export function chunk<T>(
+  source: ReadableSignal<T[]>,
+  size: number,
+): ReturnType<typeof computed<T[][]>>
+export function chunk<T>(source: T[], size: number): T[][]
+export function chunk<T>(source: ReadableSignal<T[]> | T[], size: number): any {
+  return reactive(source, (arr: T[]) => {
+    const result: T[][] = []
+    for (let i = 0; i < arr.length; i += size) result.push(arr.slice(i, i + size))
+    return result
+  })
+}
+
+/** Flatten one level of nesting. */
+export function flatten<T>(source: ReadableSignal<T[][]>): ReturnType<typeof computed<T[]>>
+export function flatten<T>(source: T[][]): T[]
+export function flatten<T>(source: ReadableSignal<T[][]> | T[][]): any {
+  return reactive(source, (arr: T[][]) => arr.flat())
+}
+
+/** Find the first item matching a predicate. */
+export function find<T>(
+  source: ReadableSignal<T[]>,
+  predicate: (item: T) => boolean,
+): ReturnType<typeof computed<T | undefined>>
+export function find<T>(source: T[], predicate: (item: T) => boolean): T | undefined
+export function find<T>(source: ReadableSignal<T[]> | T[], predicate: (item: T) => boolean): any {
+  return reactive(source, (arr: T[]) => arr.find(predicate))
+}
+
+/** Skip the first n items. */
+export function skip<T>(source: ReadableSignal<T[]>, n: number): ReturnType<typeof computed<T[]>>
+export function skip<T>(source: T[], n: number): T[]
+export function skip<T>(source: ReadableSignal<T[]> | T[], n: number): any {
+  return reactive(source, (arr: T[]) => arr.slice(n))
+}
+
+/** Take the last n items. */
+export function last<T>(source: ReadableSignal<T[]>, n: number): ReturnType<typeof computed<T[]>>
+export function last<T>(source: T[], n: number): T[]
+export function last<T>(source: ReadableSignal<T[]> | T[], n: number): any {
+  return reactive(source, (arr: T[]) => arr.slice(-n))
+}
+
+/** Map over values of a Record. Useful after groupBy. */
+export function mapValues<T, U>(
+  source: ReadableSignal<Record<string, T>>,
+  fn: (value: T, key: string) => U,
+): ReturnType<typeof computed<Record<string, U>>>
+export function mapValues<T, U>(
+  source: Record<string, T>,
+  fn: (value: T, key: string) => U,
+): Record<string, U>
+export function mapValues<T, U>(
+  source: ReadableSignal<Record<string, T>> | Record<string, T>,
+  fn: (value: T, key: string) => U,
+): any {
+  return reactive(source, (obj: Record<string, T>) => {
+    const result: Record<string, U> = {}
+    for (const key of Object.keys(obj)) result[key] = fn(obj[key] as T, key)
+    return result
+  })
+}

package/src/index.ts

@@ -0,0 +1,114 @@
+import { average, count, max, min, sum } from "./aggregation"
+import {
+  chunk,
+  filter,
+  find,
+  flatten,
+  groupBy,
+  keyBy,
+  last,
+  map,
+  mapValues,
+  skip,
+  sortBy,
+  take,
+  uniqBy,
+} from "./collections"
+import { combine, distinct, scan } from "./operators"
+import { pipe } from "./pipe"
+import { search } from "./search"
+import { debounce, throttle } from "./timing"
+
+export type { KeyOf, ReadableSignal } from "./types"
+
+/**
+ * Signal-aware reactive transforms.
+ *
+ * Every function is overloaded:
+ * - `Signal<T[]>` input → returns `Computed<R>` (reactive)
+ * - `T[]` input → returns `R` (static)
+ *
+ * @example
+ * ```ts
+ * import { rx } from "@pyreon/rx"
+ *
+ * const users = signal<User[]>([])
+ * const active = rx.filter(users, u => u.active)      // Computed<User[]>
+ * const sorted = rx.sortBy(active, "name")             // Computed<User[]>
+ * const top10 = rx.take(sorted, 10)                    // Computed<User[]>
+ *
+ * // Or pipe:
+ * const result = rx.pipe(users,
+ *   items => items.filter(u => u.active),
+ *   items => items.sort((a, b) => a.name.localeCompare(b.name)),
+ *   items => items.slice(0, 10),
+ * )
+ * ```
+ */
+export const rx = {
+  // Collections
+  filter,
+  map,
+  sortBy,
+  groupBy,
+  keyBy,
+  uniqBy,
+  take,
+  skip,
+  last,
+  chunk,
+  flatten,
+  find,
+  mapValues,
+
+  // Aggregation
+  count,
+  sum,
+  min,
+  max,
+  average,
+
+  // Operators
+  distinct,
+  scan,
+  combine,
+
+  // Timing
+  debounce,
+  throttle,
+
+  // Search
+  search,
+
+  // Pipe
+  pipe,
+} as const
+
+// Also export individual functions for tree-shaking
+export {
+  average,
+  chunk,
+  combine,
+  count,
+  debounce,
+  distinct,
+  filter,
+  find,
+  flatten,
+  groupBy,
+  keyBy,
+  last,
+  map,
+  mapValues,
+  max,
+  min,
+  pipe,
+  scan,
+  search,
+  skip,
+  sortBy,
+  sum,
+  take,
+  throttle,
+  uniqBy,
+}

package/src/operators.ts

@@ -0,0 +1,75 @@
+import { computed, effect, signal } from "@pyreon/reactivity"
+import type { ReadableSignal } from "./types"
+
+/**
+ * Distinct — skip consecutive duplicate values from a signal.
+ * Uses `Object.is` by default, or a custom equality function.
+ */
+export function distinct<T>(
+  source: ReadableSignal<T>,
+  equals: (a: T, b: T) => boolean = Object.is,
+): ReadableSignal<T> {
+  const result = signal(source())
+
+  effect(() => {
+    const val = source()
+    if (!equals(val, result.peek())) {
+      result.set(val)
+    }
+  })
+
+  return result
+}
+
+/**
+ * Scan — running accumulator over signal changes.
+ * Like Array.reduce but emits the accumulated value on each source change.
+ *
+ * @example
+ * ```ts
+ * const clicks = signal(0)
+ * const total = rx.scan(clicks, (acc, val) => acc + val, 0)
+ * // clicks: 1 → total: 1
+ * // clicks: 3 → total: 4
+ * // clicks: 2 → total: 6
+ * ```
+ */
+export function scan<T, U>(
+  source: ReadableSignal<T>,
+  reducer: (acc: U, value: T) => U,
+  initial: U,
+): ReadableSignal<U> {
+  const result = signal(initial)
+
+  effect(() => {
+    const val = source()
+    result.set(reducer(result.peek(), val))
+  })
+
+  return result
+}
+
+/**
+ * Combine multiple signals into a single computed value.
+ *
+ * @example
+ * ```ts
+ * const fullName = rx.combine(firstName, lastName, (f, l) => `${f} ${l}`)
+ * ```
+ */
+export function combine<A, B, R>(
+  a: ReadableSignal<A>,
+  b: ReadableSignal<B>,
+  fn: (a: A, b: B) => R,
+): ReturnType<typeof computed<R>>
+export function combine<A, B, C, R>(
+  a: ReadableSignal<A>,
+  b: ReadableSignal<B>,
+  c: ReadableSignal<C>,
+  fn: (a: A, b: B, c: C) => R,
+): ReturnType<typeof computed<R>>
+export function combine(...args: any[]): any {
+  const fn = args[args.length - 1] as (...vals: any[]) => any
+  const sources = args.slice(0, -1) as ReadableSignal<any>[]
+  return computed(() => fn(...sources.map((s) => s())))
+}

package/src/pipe.ts

@@ -0,0 +1,66 @@
+import { computed } from "@pyreon/reactivity"
+import type { ReadableSignal } from "./types"
+import { isSignal } from "./types"
+
+/**
+ * Pipe a signal through a chain of transform functions.
+ * Each transform receives the resolved value (not the signal) and returns a new value.
+ * The entire chain is wrapped in a single `computed()`.
+ *
+ * @example
+ * ```ts
+ * const topRisks = rx.pipe(
+ *   findings,
+ *   (items) => items.filter(f => f.severity === "critical"),
+ *   (items) => items.sort((a, b) => b.score - a.score),
+ *   (items) => items.slice(0, 10),
+ * )
+ * // topRisks() → reactive, type-safe
+ * ```
+ */
+export function pipe<A, B>(
+  source: ReadableSignal<A>,
+  f1: (a: A) => B,
+): ReturnType<typeof computed<B>>
+export function pipe<A, B, C>(
+  source: ReadableSignal<A>,
+  f1: (a: A) => B,
+  f2: (b: B) => C,
+): ReturnType<typeof computed<C>>
+export function pipe<A, B, C, D>(
+  source: ReadableSignal<A>,
+  f1: (a: A) => B,
+  f2: (b: B) => C,
+  f3: (c: C) => D,
+): ReturnType<typeof computed<D>>
+export function pipe<A, B, C, D, E>(
+  source: ReadableSignal<A>,
+  f1: (a: A) => B,
+  f2: (b: B) => C,
+  f3: (c: C) => D,
+  f4: (d: D) => E,
+): ReturnType<typeof computed<E>>
+export function pipe<A, B, C, D, E, F>(
+  source: ReadableSignal<A>,
+  f1: (a: A) => B,
+  f2: (b: B) => C,
+  f3: (c: C) => D,
+  f4: (d: D) => E,
+  f5: (e: E) => F,
+): ReturnType<typeof computed<F>>
+// Plain value overloads
+export function pipe<A, B>(source: A, f1: (a: A) => B): B
+export function pipe<A, B, C>(source: A, f1: (a: A) => B, f2: (b: B) => C): C
+export function pipe<A, B, C, D>(source: A, f1: (a: A) => B, f2: (b: B) => C, f3: (c: C) => D): D
+export function pipe(source: any, ...fns: Array<(v: any) => any>): any {
+  if (isSignal(source)) {
+    return computed(() => {
+      let val = (source as ReadableSignal<any>)()
+      for (const fn of fns) val = fn(val)
+      return val
+    })
+  }
+  let val = source
+  for (const fn of fns) val = fn(val)
+  return val
+}

package/src/search.ts

@@ -0,0 +1,34 @@
+import { computed } from "@pyreon/reactivity"
+import type { ReadableSignal } from "./types"
+import { isSignal } from "./types"
+
+/**
+ * Search items by substring matching across specified keys.
+ * Case-insensitive. Signal-aware — reactive when either source or query is a signal.
+ *
+ * @example
+ * ```ts
+ * const results = rx.search(users, searchQuery, ["name", "email"])
+ * ```
+ */
+export function search<T>(
+  source: ReadableSignal<T[]> | T[],
+  query: ReadableSignal<string> | string,
+  keys: (keyof T)[],
+): any {
+  const isReactive = isSignal(source) || isSignal(query)
+
+  const doSearch = (): T[] => {
+    const arr = isSignal(source) ? (source as ReadableSignal<T[]>)() : source
+    const q = (isSignal(query) ? (query as ReadableSignal<string>)() : query).toLowerCase().trim()
+    if (!q) return arr
+    return arr.filter((item) =>
+      keys.some((key) => {
+        const val = item[key]
+        return typeof val === "string" && val.toLowerCase().includes(q)
+      }),
+    )
+  }
+
+  return isReactive ? computed(doSearch) : doSearch()
+}

package/src/tests/aggregation.test.ts

@@ -0,0 +1,83 @@
+import { signal } from "@pyreon/reactivity"
+import { describe, expect, it } from "vitest"
+import { average, count, max, min, sum } from "../aggregation"
+
+describe("aggregation — plain values", () => {
+  it("count", () => {
+    expect(count([1, 2, 3])).toBe(3)
+    expect(count([])).toBe(0)
+  })
+
+  it("sum", () => {
+    expect(sum([1, 2, 3])).toBe(6)
+  })
+
+  it("sum with key", () => {
+    const items = [{ v: 10 }, { v: 20 }, { v: 30 }]
+    expect(sum(items, "v")).toBe(60)
+  })
+
+  it("min", () => {
+    const items = [{ v: 3 }, { v: 1 }, { v: 2 }]
+    expect(min(items, "v")?.v).toBe(1)
+  })
+
+  it("max", () => {
+    const items = [{ v: 3 }, { v: 1 }, { v: 2 }]
+    expect(max(items, "v")?.v).toBe(3)
+  })
+
+  it("min/max empty array", () => {
+    expect(min([])).toBeUndefined()
+    expect(max([])).toBeUndefined()
+  })
+
+  it("average", () => {
+    expect(average([2, 4, 6])).toBe(4)
+  })
+
+  it("average with key", () => {
+    const items = [{ v: 10 }, { v: 20 }, { v: 30 }]
+    expect(average(items, "v")).toBe(20)
+  })
+
+  it("average empty array returns 0", () => {
+    expect(average([])).toBe(0)
+  })
+})
+
+describe("aggregation — signal values", () => {
+  it("count returns computed", () => {
+    const src = signal([1, 2, 3])
+    const c = count(src)
+    expect(c()).toBe(3)
+    src.set([1])
+    expect(c()).toBe(1)
+  })
+
+  it("sum returns computed", () => {
+    const src = signal([1, 2, 3])
+    const s = sum(src)
+    expect(s()).toBe(6)
+    src.set([10, 20])
+    expect(s()).toBe(30)
+  })
+
+  it("average returns computed", () => {
+    const src = signal([2, 4, 6])
+    const avg = average(src)
+    expect(avg()).toBe(4)
+
+    src.set([10, 20])
+    expect(avg()).toBe(15)
+  })
+
+  it("average with key returns computed", () => {
+    const src = signal([{ v: 10 }, { v: 20 }, { v: 30 }])
+    const avg = average(src, "v")
+    expect(avg()).toBe(20)
+
+    src.set([{ v: 100 }])
+    expect(avg()).toBe(100)
+  })
+})