@enspirit/bmg-js 1.0.2 → 1.1.1

package/src/async/operators/join.ts

@@ -0,0 +1,39 @@
+import type { AsyncRelationOperand } from '../types';
+import type { JoinKeys, Tuple, AttrName } from '../../types';
+import { normalizeKeys, tuplesMatch, projectOutKeys } from '../../sync/operators/_helpers';
+
+const mergeTuples = (left: Tuple, right: Tuple, keyMap: Record<AttrName, AttrName>): Tuple => {
+  return { ...left, ...projectOutKeys(right, keyMap) };
+};
+
+/**
+ * Natural join: combines tuples from left and right where join keys match.
+ * Materializes both sides (needed for key detection and nested loop join).
+ */
+export async function* join<T, U>(
+  left: AsyncRelationOperand<T>,
+  right: AsyncRelationOperand<U>,
+  keys?: JoinKeys
+): AsyncIterable<Tuple> {
+  // Materialize both sides
+  const leftTuples: Tuple[] = [];
+  const rightTuples: Tuple[] = [];
+
+  for await (const tuple of left) {
+    leftTuples.push(tuple as Tuple);
+  }
+  for await (const tuple of right) {
+    rightTuples.push(tuple as Tuple);
+  }
+
+  const keyMap = normalizeKeys(keys, leftTuples, rightTuples);
+
+  // Nested loop join
+  for (const leftTuple of leftTuples) {
+    for (const rightTuple of rightTuples) {
+      if (tuplesMatch(leftTuple, rightTuple, keyMap)) {
+        yield mergeTuples(leftTuple, rightTuple, keyMap);
+      }
+    }
+  }
+}

package/src/async/operators/left_join.ts

@@ -0,0 +1,55 @@
+import type { AsyncRelationOperand } from '../types';
+import type { JoinKeys, Tuple, AttrName } from '../../types';
+import { normalizeKeys, tuplesMatch } from '../../sync/operators/_helpers';
+
+const getRightAttrs = (rightTuples: Tuple[], keyMap: Record<AttrName, AttrName>): AttrName[] => {
+  if (rightTuples.length === 0) return [];
+  const rightKeys = new Set(Object.values(keyMap));
+  return Object.keys(rightTuples[0]).filter(attr => !rightKeys.has(attr));
+};
+
+const mergeTuples = (left: Tuple, right: Tuple | null, rightAttrs: AttrName[]): Tuple => {
+  const result = { ...left };
+  for (const attr of rightAttrs) {
+    result[attr] = right ? right[attr] : null;
+  }
+  return result;
+};
+
+/**
+ * Left outer join: combines tuples, keeping all left tuples.
+ * Non-matching left tuples have null for right attributes.
+ * Materializes both sides.
+ */
+export async function* left_join<T, U>(
+  left: AsyncRelationOperand<T>,
+  right: AsyncRelationOperand<U>,
+  keys?: JoinKeys
+): AsyncIterable<Tuple> {
+  // Materialize both sides
+  const leftTuples: Tuple[] = [];
+  const rightTuples: Tuple[] = [];
+
+  for await (const tuple of left) {
+    leftTuples.push(tuple as Tuple);
+  }
+  for await (const tuple of right) {
+    rightTuples.push(tuple as Tuple);
+  }
+
+  const keyMap = normalizeKeys(keys, leftTuples, rightTuples);
+  const rightAttrs = getRightAttrs(rightTuples, keyMap);
+
+  for (const leftTuple of leftTuples) {
+    let matched = false;
+    for (const rightTuple of rightTuples) {
+      if (tuplesMatch(leftTuple, rightTuple, keyMap)) {
+        yield mergeTuples(leftTuple, rightTuple, rightAttrs);
+        matched = true;
+      }
+    }
+    if (!matched) {
+      yield mergeTuples(leftTuple, null, rightAttrs);
+    }
+  }
+}

package/src/async/operators/matching.ts

@@ -0,0 +1,39 @@
+import type { AsyncRelationOperand } from '../types';
+import type { JoinKeys, Tuple } from '../../types';
+import { normalizeKeys, matchKey } from '../../sync/operators/_helpers';
+
+/**
+ * Semi-join: returns tuples from left that have a matching tuple in right.
+ * Materializes right side first to build key set.
+ */
+export async function* matching<T, U>(
+  left: AsyncRelationOperand<T>,
+  right: AsyncRelationOperand<U>,
+  keys?: JoinKeys
+): AsyncIterable<Tuple> {
+  // Materialize both sides to normalize keys (need sample tuples)
+  const leftTuples: Tuple[] = [];
+  const rightTuples: Tuple[] = [];
+
+  for await (const tuple of left) {
+    leftTuples.push(tuple as Tuple);
+  }
+  for await (const tuple of right) {
+    rightTuples.push(tuple as Tuple);
+  }
+
+  const keyMap = normalizeKeys(keys, leftTuples, rightTuples);
+
+  // Build right key set
+  const rightKeys = new Set<string>();
+  for (const tuple of rightTuples) {
+    rightKeys.add(matchKey(tuple, keyMap, 'right'));
+  }
+
+  // Yield left tuples that match
+  for (const tuple of leftTuples) {
+    if (rightKeys.has(matchKey(tuple, keyMap, 'left'))) {
+      yield tuple;
+    }
+  }
+}

package/src/async/operators/minus.ts

@@ -0,0 +1,28 @@
+import type { AsyncRelationOperand } from '../types';
+import type { Tuple } from '../../types';
+import { tupleKey } from '../../sync/operators/_helpers';
+
+/**
+ * Set difference: returns tuples in left but not in right.
+ * Materializes right side first, then streams left.
+ */
+export async function* minus<T>(
+  left: AsyncRelationOperand<T>,
+  right: AsyncRelationOperand<T>
+): AsyncIterable<Tuple> {
+  // Materialize right side into a set of keys
+  const rightKeys = new Set<string>();
+  for await (const tuple of right) {
+    rightKeys.add(tupleKey(tuple as Tuple));
+  }
+
+  // Stream left, filtering out tuples present in right
+  const seen = new Set<string>();
+  for await (const tuple of left) {
+    const key = tupleKey(tuple as Tuple);
+    if (!rightKeys.has(key) && !seen.has(key)) {
+      seen.add(key);
+      yield tuple as Tuple;
+    }
+  }
+}

package/src/async/operators/not_matching.ts

@@ -0,0 +1,39 @@
+import type { AsyncRelationOperand } from '../types';
+import type { JoinKeys, Tuple } from '../../types';
+import { normalizeKeys, matchKey } from '../../sync/operators/_helpers';
+
+/**
+ * Anti semi-join: returns tuples from left that have no matching tuple in right.
+ * Materializes right side first to build key set.
+ */
+export async function* not_matching<T, U>(
+  left: AsyncRelationOperand<T>,
+  right: AsyncRelationOperand<U>,
+  keys?: JoinKeys
+): AsyncIterable<Tuple> {
+  // Materialize both sides to normalize keys (need sample tuples)
+  const leftTuples: Tuple[] = [];
+  const rightTuples: Tuple[] = [];
+
+  for await (const tuple of left) {
+    leftTuples.push(tuple as Tuple);
+  }
+  for await (const tuple of right) {
+    rightTuples.push(tuple as Tuple);
+  }
+
+  const keyMap = normalizeKeys(keys, leftTuples, rightTuples);
+
+  // Build right key set
+  const rightKeys = new Set<string>();
+  for (const tuple of rightTuples) {
+    rightKeys.add(matchKey(tuple, keyMap, 'right'));
+  }
+
+  // Yield left tuples that don't match
+  for (const tuple of leftTuples) {
+    if (!rightKeys.has(matchKey(tuple, keyMap, 'left'))) {
+      yield tuple;
+    }
+  }
+}

package/src/async/operators/one.ts

@@ -0,0 +1,25 @@
+import type { AsyncRelationOperand } from '../types';
+import { toAsyncOperationalOperand, error } from './_helpers';
+
+/**
+ * Returns the single tuple from the relation.
+ * Throws if the relation is empty or has more than one tuple.
+ */
+export const one = async <T>(
+  operand: AsyncRelationOperand<T>
+): Promise<T> => {
+  const op = toAsyncOperationalOperand(operand);
+  let result: T | undefined;
+
+  for await (const tuple of op.tuples()) {
+    if (result !== undefined) {
+      return error('More than one tuple found');
+    }
+    result = tuple;
+  }
+
+  if (result !== undefined) {
+    return result;
+  }
+  return error('Relation is empty');
+};

package/src/async/operators/prefix.ts

@@ -0,0 +1,15 @@
+import type { AsyncRelationOperand } from '../types';
+import type { PrefixOptions, Tuple } from '../../types';
+import { rename } from './rename';
+
+/**
+ * Prefixes all attribute names (except those in options.except).
+ */
+export const prefix = <T>(
+  operand: AsyncRelationOperand<T>,
+  pfx: string,
+  options?: PrefixOptions
+): AsyncIterable<Tuple> => {
+  const except = new Set(options?.except ?? []);
+  return rename(operand, (attr) => except.has(attr) ? attr : `${pfx}${attr}`);
+};

package/src/async/operators/project.ts

@@ -0,0 +1,64 @@
+import type { AsyncRelationOperand } from '../types';
+import type { Tuple, AttrName } from '../../types';
+import { toAsyncOperationalOperand, deduplicateAsync } from './_helpers';
+
+/**
+ * Async generator that projects tuples to specified attributes.
+ */
+async function* projectGen<T>(
+  source: AsyncIterable<T>,
+  attrs: AttrName[]
+): AsyncGenerator<Tuple> {
+  for await (const tuple of source) {
+    const t = tuple as Tuple;
+    const projected = attrs.reduce((memo, attr) => {
+      if (attr in t) {
+        memo[attr] = t[attr];
+      }
+      return memo;
+    }, {} as Tuple);
+    yield projected;
+  }
+}
+
+/**
+ * Projects tuples to specified attributes with deduplication.
+ */
+export const project = <T>(
+  operand: AsyncRelationOperand<T>,
+  attrs: AttrName[]
+): AsyncIterable<Tuple> => {
+  const op = toAsyncOperationalOperand(operand);
+  return deduplicateAsync(projectGen(op.tuples(), attrs));
+};
+
+/**
+ * Async generator that projects out (removes) specified attributes.
+ */
+async function* allbutGen<T>(
+  source: AsyncIterable<T>,
+  attrs: AttrName[]
+): AsyncGenerator<Tuple> {
+  const excludeSet = new Set(attrs);
+  for await (const tuple of source) {
+    const t = tuple as Tuple;
+    const projected: Tuple = {};
+    for (const [attr, value] of Object.entries(t)) {
+      if (!excludeSet.has(attr)) {
+        projected[attr] = value;
+      }
+    }
+    yield projected;
+  }
+}
+
+/**
+ * Projects out (removes) specified attributes with deduplication.
+ */
+export const allbut = <T>(
+  operand: AsyncRelationOperand<T>,
+  attrs: AttrName[]
+): AsyncIterable<Tuple> => {
+  const op = toAsyncOperationalOperand(operand);
+  return deduplicateAsync(allbutGen(op.tuples(), attrs));
+};

package/src/async/operators/rename.ts

@@ -0,0 +1,33 @@
+import type { AsyncRelationOperand } from '../types';
+import type { Renaming, Tuple } from '../../types';
+import { toAsyncOperationalOperand } from './_helpers';
+import { toRenamingFunc } from '../../sync/operators/_helpers';
+
+/**
+ * Async generator that renames attributes in each tuple.
+ */
+async function* renameGen<T>(
+  source: AsyncIterable<T>,
+  renaming: Renaming
+): AsyncGenerator<Tuple> {
+  const renamingFunc = toRenamingFunc(renaming);
+  for await (const tuple of source) {
+    const t = tuple as Tuple;
+    const renamed = Object.keys(t).reduce((memo, attr) => {
+      memo[renamingFunc(attr)] = t[attr];
+      return memo;
+    }, {} as Tuple);
+    yield renamed;
+  }
+}
+
+/**
+ * Renames attributes in each tuple.
+ */
+export const rename = <T>(
+  operand: AsyncRelationOperand<T>,
+  renaming: Renaming
+): AsyncIterable<Tuple> => {
+  const op = toAsyncOperationalOperand(operand);
+  return renameGen(op.tuples(), renaming);
+};

package/src/async/operators/restrict.ts

@@ -0,0 +1,61 @@
+import type { AsyncRelationOperand } from '../types';
+import type { Predicate } from '../../types';
+import { toPredicateFunc } from '../../support/toPredicateFunc';
+import { toAsyncOperationalOperand } from './_helpers';
+
+/**
+ * Async generator that filters tuples based on a predicate.
+ */
+async function* restrictGen<T>(
+  source: AsyncIterable<T>,
+  predicate: (t: T) => boolean
+): AsyncGenerator<T> {
+  for await (const tuple of source) {
+    if (predicate(tuple)) {
+      yield tuple;
+    }
+  }
+}
+
+/**
+ * Filters tuples that match the predicate.
+ */
+export const restrict = <T>(
+  operand: AsyncRelationOperand<T>,
+  p: Predicate
+): AsyncIterable<T> => {
+  const op = toAsyncOperationalOperand(operand);
+  const f = toPredicateFunc(p) as (t: T) => boolean;
+  return restrictGen(op.tuples(), f);
+};
+
+/**
+ * Alias for restrict.
+ */
+export const where = restrict;
+
+/**
+ * Async generator that excludes tuples based on a predicate.
+ */
+async function* excludeGen<T>(
+  source: AsyncIterable<T>,
+  predicate: (t: T) => boolean
+): AsyncGenerator<T> {
+  for await (const tuple of source) {
+    if (!predicate(tuple)) {
+      yield tuple;
+    }
+  }
+}
+
+/**
+ * Filters tuples that do NOT match the predicate.
+ */
+export const exclude = <T>(
+  operand: AsyncRelationOperand<T>,
+  p: Predicate
+): AsyncIterable<T> => {
+  const op = toAsyncOperationalOperand(operand);
+  const f = toPredicateFunc(p) as (t: T) => boolean;
+  return excludeGen(op.tuples(), f);
+};

package/src/async/operators/suffix.ts

@@ -0,0 +1,15 @@
+import type { AsyncRelationOperand } from '../types';
+import type { SuffixOptions, Tuple } from '../../types';
+import { rename } from './rename';
+
+/**
+ * Suffixes all attribute names (except those in options.except).
+ */
+export const suffix = <T>(
+  operand: AsyncRelationOperand<T>,
+  sfx: string,
+  options?: SuffixOptions
+): AsyncIterable<Tuple> => {
+  const except = new Set(options?.except ?? []);
+  return rename(operand, (attr) => except.has(attr) ? attr : `${attr}${sfx}`);
+};

package/src/async/operators/summarize.ts

@@ -0,0 +1,90 @@
+import type { AsyncRelationOperand } from '../types';
+import type { AttrName, Tuple, Aggregator, Aggregators } from '../../types';
+
+const groupKey = (tuple: Tuple, by: AttrName[]): string => {
+  const keyParts = by.map(attr => JSON.stringify(tuple[attr]));
+  return keyParts.join('|');
+};
+
+const pickAttrs = (tuple: Tuple, attrs: AttrName[]): Tuple => {
+  return attrs.reduce((acc, attr) => {
+    acc[attr] = tuple[attr];
+    return acc;
+  }, {} as Tuple);
+};
+
+const applyAggregator = (tuples: Tuple[], agg: Aggregator): unknown => {
+  if (typeof agg === 'function') {
+    return agg(tuples);
+  }
+
+  const spec = typeof agg === 'string' ? { op: agg, attr: '' } : agg;
+  const { op, attr } = spec;
+
+  switch (op) {
+    case 'count':
+      return tuples.length;
+
+    case 'sum': {
+      return tuples.reduce((sum, t) => sum + (Number(t[attr]) || 0), 0);
+    }
+
+    case 'min': {
+      const values = tuples.map(t => t[attr]).filter(v => v !== undefined && v !== null);
+      return values.length > 0 ? Math.min(...values.map(Number)) : null;
+    }
+
+    case 'max': {
+      const values = tuples.map(t => t[attr]).filter(v => v !== undefined && v !== null);
+      return values.length > 0 ? Math.max(...values.map(Number)) : null;
+    }
+
+    case 'avg': {
+      const values = tuples.map(t => Number(t[attr])).filter(v => !isNaN(v));
+      return values.length > 0 ? values.reduce((a, b) => a + b, 0) / values.length : null;
+    }
+
+    case 'collect': {
+      return tuples.map(t => t[attr]);
+    }
+
+    default:
+      throw new Error(`Unknown aggregator: ${op}`);
+  }
+};
+
+/**
+ * Aggregates tuples by grouping attributes.
+ * Supports count, sum, min, max, avg, collect, and custom functions.
+ * Materializes all tuples to perform grouping.
+ */
+export async function* summarize<T>(
+  operand: AsyncRelationOperand<T>,
+  by: AttrName[],
+  aggs: Aggregators
+): AsyncIterable<Tuple> {
+  // Materialize all tuples
+  const tuples: Tuple[] = [];
+  for await (const tuple of operand) {
+    tuples.push(tuple as Tuple);
+  }
+
+  // Group tuples
+  const groups = new Map<string, Tuple[]>();
+  for (const tuple of tuples) {
+    const key = groupKey(tuple, by);
+    if (!groups.has(key)) {
+      groups.set(key, []);
+    }
+    groups.get(key)!.push(tuple);
+  }
+
+  // Apply aggregators to each group
+  for (const groupTuples of groups.values()) {
+    const row: Tuple = pickAttrs(groupTuples[0], by);
+    for (const [resultAttr, agg] of Object.entries(aggs)) {
+      row[resultAttr] = applyAggregator(groupTuples, agg);
+    }
+    yield row;
+  }
+}

package/src/async/operators/toArray.ts

@@ -0,0 +1,18 @@
+import type { AsyncRelationOperand } from '../types';
+import { toAsyncOperationalOperand } from './_helpers';
+
+/**
+ * Collects all tuples from the async relation into an array.
+ */
+export const toArray = async <T>(
+  operand: AsyncRelationOperand<T>
+): Promise<T[]> => {
+  const op = toAsyncOperationalOperand(operand);
+  const result: T[] = [];
+
+  for await (const tuple of op.tuples()) {
+    result.push(tuple);
+  }
+
+  return result;
+};

package/src/async/operators/transform.ts

@@ -0,0 +1,43 @@
+import type { AsyncRelationOperand } from '../types';
+import type { Transformation, Tuple } from '../../types';
+
+/**
+ * Applies transformation functions to attribute values.
+ * - Single function: applies to all values
+ * - Array of functions: chains them in order
+ * - Object with attr keys: applies per-attribute transformers
+ */
+export async function* transform<T>(
+  operand: AsyncRelationOperand<T>,
+  transformation: Transformation
+): AsyncIterable<Tuple> {
+  for await (const tuple of operand) {
+    const transformed: Tuple = {};
+
+    for (const [attr, value] of Object.entries(tuple as Tuple)) {
+      transformed[attr] = applyTransformation(value, attr, transformation);
+    }
+
+    yield transformed;
+  }
+}
+
+const applyTransformation = (value: unknown, attr: string, transformation: Transformation): unknown => {
+  if (typeof transformation === 'function') {
+    // Single function - apply to all values
+    return transformation(value);
+  } else if (Array.isArray(transformation)) {
+    // Array of functions - chain them
+    return transformation.reduce((v, fn) => fn(v), value);
+  } else {
+    // Object with attr-specific transformers
+    const fn = transformation[attr];
+    if (fn) {
+      if (Array.isArray(fn)) {
+        return fn.reduce((v, f) => f(v), value);
+      }
+      return fn(value);
+    }
+    return value;
+  }
+};

package/src/async/operators/ungroup.ts

@@ -0,0 +1,43 @@
+import type { AsyncRelationOperand } from '../types';
+import type { AttrName, Tuple, Relation } from '../../types';
+import { isRelation } from '../../sync/operators/isRelation';
+
+const toTupleArray = (value: unknown): Tuple[] => {
+  if (isRelation(value)) {
+    return (value as Relation).toArray();
+  }
+  if (Array.isArray(value)) {
+    return value;
+  }
+  throw new Error(`Value is not a relation or array`);
+};
+
+/**
+ * Flattens a nested relation attribute back into parent tuples.
+ * Materializes all tuples to perform ungrouping.
+ */
+export async function* ungroup<T>(
+  operand: AsyncRelationOperand<T>,
+  attr: AttrName
+): AsyncIterable<Tuple> {
+  for await (const tuple of operand) {
+    const t = tuple as Tuple;
+    const nested = toTupleArray(t[attr]);
+
+    // Get base attributes (all except the grouped one)
+    const base: Tuple = {};
+    for (const [key, value] of Object.entries(t)) {
+      if (key !== attr) {
+        base[key] = value;
+      }
+    }
+
+    // Flatten each nested tuple
+    for (const nestedTuple of nested) {
+      yield {
+        ...base,
+        ...nestedTuple
+      };
+    }
+  }
+}

package/src/async/operators/union.ts

@@ -0,0 +1,29 @@
+import type { AsyncRelationOperand } from '../types';
+import type { Tuple } from '../../types';
+import { tupleKey } from '../../sync/operators/_helpers';
+
+/**
+ * Combines tuples from two relations, removing duplicates.
+ */
+export async function* union<T>(
+  left: AsyncRelationOperand<T>,
+  right: AsyncRelationOperand<T>
+): AsyncIterable<Tuple> {
+  const seen = new Set<string>();
+
+  for await (const tuple of left) {
+    const key = tupleKey(tuple as Tuple);
+    if (!seen.has(key)) {
+      seen.add(key);
+      yield tuple as Tuple;
+    }
+  }
+
+  for await (const tuple of right) {
+    const key = tupleKey(tuple as Tuple);
+    if (!seen.has(key)) {
+      seen.add(key);
+      yield tuple as Tuple;
+    }
+  }
+}

package/src/async/operators/unwrap.ts

@@ -0,0 +1,31 @@
+import type { AsyncRelationOperand } from '../types';
+import type { AttrName, Tuple } from '../../types';
+
+/**
+ * Unwraps a nested object attribute back into the parent tuple.
+ */
+export async function* unwrap<T>(
+  operand: AsyncRelationOperand<T>,
+  attr: AttrName
+): AsyncIterable<Tuple> {
+  for await (const tuple of operand) {
+    const t = tuple as Tuple;
+    const wrapped = t[attr] as Tuple;
+
+    if (typeof wrapped !== 'object' || wrapped === null || Array.isArray(wrapped)) {
+      throw new Error(`Attribute '${attr}' is not a tuple (object)`);
+    }
+
+    const unwrapped: Tuple = {};
+    for (const [key, value] of Object.entries(t)) {
+      if (key !== attr) {
+        unwrapped[key] = value;
+      }
+    }
+
+    yield {
+      ...unwrapped,
+      ...wrapped
+    };
+  }
+}