@enspirit/bmg-js 1.0.2 → 1.1.0

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
+    };
+  }
+}

package/src/async/operators/wrap.ts

@@ -0,0 +1,32 @@
+import type { AsyncRelationOperand } from '../types';
+import type { AttrName, Tuple } from '../../types';
+
+/**
+ * Wraps specified attributes into a nested object.
+ */
+export async function* wrap<T>(
+  operand: AsyncRelationOperand<T>,
+  attrs: AttrName[],
+  as: AttrName
+): AsyncIterable<Tuple> {
+  const wrappedSet = new Set(attrs);
+
+  for await (const tuple of operand) {
+    const t = tuple as Tuple;
+    const wrapped: Tuple = {};
+    const remaining: Tuple = {};
+
+    for (const [key, value] of Object.entries(t)) {
+      if (wrappedSet.has(key)) {
+        wrapped[key] = value;
+      } else {
+        remaining[key] = value;
+      }
+    }
+
+    yield {
+      ...remaining,
+      [as]: wrapped
+    };
+  }
+}

package/src/async/operators/yByX.ts

@@ -0,0 +1,19 @@
+import type { AsyncRelationOperand } from '../types';
+import type { AttrName, Tuple } from '../../types';
+
+/**
+ * Builds a key-value map from two attributes.
+ * Terminal operation - returns a Promise.
+ */
+export const yByX = async <T>(
+  operand: AsyncRelationOperand<T>,
+  y: AttrName,
+  x: AttrName
+): Promise<Tuple> => {
+  const hash: Tuple = {};
+  for await (const tuple of operand) {
+    const t = tuple as Tuple;
+    hash[`${t[x]}`] = t[y];
+  }
+  return hash;
+};

package/src/async/types.ts

@@ -0,0 +1,86 @@
+import type { Tuple, TypedPredicate, Relation, TypedExtension, RenameMap, Renamed, Prefixed, Suffixed, Transformation, JoinKeys, AttrName, Aggregators, AutowrapOptions, TextOptions } from '../types';
+
+/**
+ * Async version of the Relation interface.
+ * Operations are lazy - they build a pipeline that executes only when
+ * a terminal method (one(), toArray()) is awaited.
+ *
+ * @typeParam T - The tuple type for this relation.
+ */
+export interface AsyncRelation<T = Tuple> {
+  // === Type-preserving operators ===
+
+  restrict(p: TypedPredicate<T>): AsyncRelation<T>
+  where(p: TypedPredicate<T>): AsyncRelation<T>
+  exclude(p: TypedPredicate<T>): AsyncRelation<T>
+
+  // === Projection operators ===
+
+  project<K extends keyof T>(attrs: K[]): AsyncRelation<Pick<T, K>>
+  allbut<K extends keyof T>(attrs: K[]): AsyncRelation<Omit<T, K>>
+
+  // === Extension operators ===
+
+  extend<E extends Record<string, unknown>>(e: TypedExtension<T, E>): AsyncRelation<T & E>
+  constants<C extends Tuple>(consts: C): AsyncRelation<T & C>
+
+  // === Rename operators ===
+
+  rename<R extends RenameMap<T>>(r: R): AsyncRelation<Renamed<T, R>>
+  prefix<P extends string, Ex extends keyof T = never>(pfx: P, options?: { except?: Ex[] }): AsyncRelation<Prefixed<T, P, Ex>>
+  suffix<S extends string, Ex extends keyof T = never>(sfx: S, options?: { except?: Ex[] }): AsyncRelation<Suffixed<T, S, Ex>>
+  transform(t: Transformation): AsyncRelation<T>
+
+  // === Set operations ===
+
+  union(other: AsyncRelationOperand<T>): AsyncRelation<T>
+  minus(other: AsyncRelationOperand<T>): AsyncRelation<T>
+  intersect(other: AsyncRelationOperand<T>): AsyncRelation<T>
+
+  // === Semi-joins ===
+
+  matching<U = Tuple>(other: AsyncRelationOperand<U>, keys?: JoinKeys): AsyncRelation<T>
+  not_matching<U = Tuple>(other: AsyncRelationOperand<U>, keys?: JoinKeys): AsyncRelation<T>
+
+  // === Joins ===
+
+  join<U = Tuple>(other: AsyncRelationOperand<U>, keys?: JoinKeys): AsyncRelation<T & U>
+  left_join<U = Tuple>(other: AsyncRelationOperand<U>, keys?: JoinKeys): AsyncRelation<T & Partial<U>>
+  cross_product<U = Tuple>(other: AsyncRelationOperand<U>): AsyncRelation<T & U>
+  cross_join<U = Tuple>(other: AsyncRelationOperand<U>): AsyncRelation<T & U>
+
+  // === Nesting/Grouping ===
+
+  group<K extends keyof T>(attrs: K[], as: AttrName): AsyncRelation<Omit<T, K> & Record<string, Relation<Pick<T, K>>>>
+  ungroup(attr: AttrName): AsyncRelation<Tuple>
+  wrap<K extends keyof T>(attrs: K[], as: AttrName): AsyncRelation<Omit<T, K> & Record<string, Pick<T, K>>>
+  unwrap(attr: AttrName): AsyncRelation<Tuple>
+  image<U = Tuple>(other: AsyncRelationOperand<U>, as: AttrName, keys?: JoinKeys): AsyncRelation<T & Record<string, Relation<U>>>
+  summarize<K extends keyof T>(by: K[], aggs: Aggregators): AsyncRelation<Pick<T, K> & Tuple>
+  autowrap(options?: AutowrapOptions): AsyncRelation<Tuple>
+
+  // === Terminal operations (return Promises) ===
+
+  one(): Promise<T>
+  toArray(): Promise<T[]>
+  toRelation(): Promise<Relation<T>>
+  yByX(y: AttrName, x: AttrName): Promise<Tuple>
+  toText(options?: TextOptions): Promise<string>
+
+  // === Async iteration ===
+
+  [Symbol.asyncIterator](): AsyncIterator<T>
+}
+
+/**
+ * What can be passed as an operand to async operators.
+ */
+export type AsyncRelationOperand<T = Tuple> = AsyncRelation<T> | AsyncIterable<T>
+
+/**
+ * Async version of OperationalOperand for internal use by operators.
+ */
+export interface AsyncOperationalOperand<T = Tuple> {
+  tuples(): AsyncIterable<T>
+  output(tuples: AsyncIterable<T>): AsyncRelationOperand<T>
+}

package/src/async.ts

@@ -0,0 +1,4 @@
+export * from './async/types';
+export * as asyncOps from './async/operators';
+export { AsyncBmg, BaseAsyncRelation } from './async/Relation';
+export { toText, TextWriter } from './writer';

package/src/index.ts

@@ -1,9 +1,10 @@
-export * from './operators';
+export * from './sync/operators';
 export * from './types';
 export { LIB_DEFINITIONS } from './lib-definitions';
+export { toText } from './writer';
 
-import { MemoryRelation } from './Relation';
-import { isRelation } from './operators';
+import { MemoryRelation } from './sync/Relation';
+import { isRelation } from './sync/operators';
 
 /**
  * Creates a new in-memory relation from an array of tuples.
@@ -29,3 +30,15 @@ export function Bmg<T>(tuples: T[]): MemoryRelation<T> {
 }
 
 Bmg.isRelation = isRelation;
+
+/**
+ * DEE - The relation with no attributes and exactly one tuple.
+ * This is the identity element for natural join.
+ */
+export const DEE = new MemoryRelation<Record<string, never>>([{}]);
+
+/**
+ * DUM - The relation with no attributes and no tuples.
+ * This is the identity element for union.
+ */
+export const DUM = new MemoryRelation<Record<string, never>>([]);

package/src/lib-definitions.ts

@@ -152,6 +152,13 @@ interface PrefixOptions {
   except?: AttrName[]
 }
 
+interface TextOptions {
+  /** Precision for floating point numbers (default: 3) */
+  floatPrecision?: number;
+  /** Maximum width to trim output at */
+  trimAt?: number;
+}
+
 interface SuffixOptions {
   except?: AttrName[]
 }
@@ -256,6 +263,10 @@ interface Relation<T = Tuple> {
   yByX<Y extends keyof T, X extends keyof T>(y: Y, x: X): Record<T[X] & PropertyKey, T[Y]>
   toArray(): T[]
   isEqual(right: any): boolean
+
+  // === Display ===
+
+  toText(options?: TextOptions): string
 }
 
 // ============================================================================

package/src/operators/index.ts

@@ -1,31 +1,2 @@
-export * from './restrict'
-export * from './where'
-export * from './exclude'
-export * from './constants'
-export * from './rename'
-export * from './prefix'
-export * from './suffix'
-export * from './project'
-export * from './allbut'
-export * from './extend'
-export * from './union'
-export * from './minus'
-export * from './intersect'
-export * from './matching'
-export * from './not_matching'
-export * from './join'
-export * from './left_join'
-export * from './cross_product'
-export * from './image'
-export * from './summarize'
-export * from './group'
-export * from './ungroup'
-export * from './wrap'
-export * from './unwrap'
-export * from './autowrap'
-export * from './transform'
-
-export * from './isRelation'
-export * from './isEqual'
-export * from './one'
-export * from './yByX'
+// Re-export sync operators for backward compatibility
+export * from '../sync/operators';