@enspirit/bmg-js 1.0.2 → 1.1.0

package/dist/sync/Relation/index.d.ts

@@ -0,0 +1 @@
+export * from './Memory';

package/dist/sync/operators/_helpers.d.ts

@@ -0,0 +1,142 @@
+import { OperationalOperand, RelationOperand, Renaming, RenamingFunc, Tuple, JoinKeys, AttrName } from "@/types";
+/**
+ * Generates a unique string key for a tuple, used for equality comparison and deduplication.
+ * Handles nested relations by converting them to sorted tuple keys.
+ *
+ * @example
+ * tupleKey({ name: 'Alice', age: 30 })
+ * // => '[["age",30],["name","Alice"]]'
+ *
+ * @example
+ * tupleKey({ id: 1, items: Bmg([{ x: 1 }, { x: 2 }]) })
+ * // => '[["id",1],["items",[...]]]' (nested relation converted to sorted keys)
+ */
+export declare const tupleKey: (tuple: Tuple) => string;
+/**
+ * Removes duplicate tuples from an array, preserving order of first occurrence.
+ * Uses tupleKey() for equality comparison.
+ *
+ * @example
+ * deduplicate([
+ *   { id: 1, name: 'Alice' },
+ *   { id: 2, name: 'Bob' },
+ *   { id: 1, name: 'Alice' },  // duplicate
+ * ])
+ * // => [{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }]
+ */
+export declare const deduplicate: (tuples: Tuple[]) => Tuple[];
+/**
+ * Converts a RelationOperand (Relation or Tuple[]) to an OperationalOperand
+ * that provides a uniform interface for iteration and output.
+ *
+ * @example
+ * // With array input, output remains array
+ * const op = toOperationalOperand([{ id: 1 }]);
+ * [...op.tuples()];        // => [{ id: 1 }]
+ * op.output([{ id: 2 }]);  // => [{ id: 2 }]
+ *
+ * @example
+ * // With Relation input, output is a new Relation
+ * const op = toOperationalOperand(Bmg([{ id: 1 }]));
+ * [...op.tuples()];        // => [{ id: 1 }]
+ * op.output([{ id: 2 }]);  // => Bmg([{ id: 2 }])
+ */
+export declare const toOperationalOperand: (operand: RelationOperand) => OperationalOperand;
+/**
+ * Converts a Renaming (object or function) to a RenamingFunc.
+ *
+ * @example
+ * // Object renaming
+ * const fn = toRenamingFunc({ name: 'fullName', age: 'years' });
+ * fn('name');  // => 'fullName'
+ * fn('age');   // => 'years'
+ * fn('other'); // => 'other' (unchanged)
+ *
+ * @example
+ * // Function renaming (passed through)
+ * const fn = toRenamingFunc(attr => attr.toUpperCase());
+ * fn('name'); // => 'NAME'
+ */
+export declare const toRenamingFunc: (renaming: Renaming) => RenamingFunc;
+export declare const error: (msg: string) => never;
+/**
+ * Finds attribute names that exist in both left and right tuple arrays.
+ * Used for natural joins when no explicit keys are provided.
+ *
+ * @example
+ * const left = [{ id: 1, name: 'Alice', city: 'NYC' }];
+ * const right = [{ city: 'NYC', country: 'USA' }];
+ * getCommonAttrs(left, right);
+ * // => ['city']
+ *
+ * @example
+ * const left = [{ a: 1, b: 2 }];
+ * const right = [{ b: 2, c: 3 }];
+ * getCommonAttrs(left, right);
+ * // => ['b']
+ */
+export declare const getCommonAttrs: (left: Tuple[], right: Tuple[]) => AttrName[];
+/**
+ * Normalizes JoinKeys to a Record<AttrName, AttrName> mapping left attrs to right attrs.
+ *
+ * @example
+ * // undefined => use common attributes
+ * normalizeKeys(undefined, [{ id: 1, city: 'NYC' }], [{ city: 'NYC' }]);
+ * // => { city: 'city' }
+ *
+ * @example
+ * // Array of common attribute names
+ * normalizeKeys(['city', 'country'], leftTuples, rightTuples);
+ * // => { city: 'city', country: 'country' }
+ *
+ * @example
+ * // Object mapping left attr to right attr
+ * normalizeKeys({ city: 'location' }, leftTuples, rightTuples);
+ * // => { city: 'location' }
+ */
+export declare const normalizeKeys: (keys: JoinKeys | undefined, leftTuples: Tuple[], rightTuples: Tuple[]) => Record<AttrName, AttrName>;
+/**
+ * Checks if two tuples match on the specified key mapping.
+ *
+ * @example
+ * const keyMap = { city: 'location' };
+ * tuplesMatch({ id: 1, city: 'NYC' }, { location: 'NYC', pop: 8 }, keyMap);
+ * // => true (left.city === right.location)
+ *
+ * @example
+ * const keyMap = { city: 'city' };
+ * tuplesMatch({ city: 'NYC' }, { city: 'LA' }, keyMap);
+ * // => false
+ */
+export declare const tuplesMatch: (left: Tuple, right: Tuple, keyMap: Record<AttrName, AttrName>) => boolean;
+/**
+ * Creates a string key from a tuple's join attributes for fast Set-based lookups.
+ * Used by matching/not_matching for efficient semi-join operations.
+ *
+ * @example
+ * const keyMap = { first: 'fname', last: 'lname' };
+ *
+ * // Left side uses left attr names (keys of keyMap)
+ * matchKey({ id: 1, first: 'John', last: 'Doe' }, keyMap, 'left');
+ * // => '"John"|"Doe"'
+ *
+ * // Right side uses right attr names (values of keyMap)
+ * matchKey({ fname: 'John', lname: 'Doe', age: 30 }, keyMap, 'right');
+ * // => '"John"|"Doe"'
+ */
+export declare const matchKey: (tuple: Tuple, keyMap: Record<AttrName, AttrName>, side: 'left' | 'right') => string;
+/**
+ * Removes join key attributes from a right tuple when merging.
+ * Used to avoid duplicate columns in join results.
+ *
+ * @example
+ * const keyMap = { city: 'location' };
+ * projectOutKeys({ location: 'NYC', country: 'USA', pop: 8 }, keyMap);
+ * // => { country: 'USA', pop: 8 }  (location removed)
+ *
+ * @example
+ * const keyMap = { a: 'a', b: 'b' };
+ * projectOutKeys({ a: 1, b: 2, c: 3 }, keyMap);
+ * // => { c: 3 }  (a and b removed)
+ */
+export declare const projectOutKeys: (tuple: Tuple, keyMap: Record<AttrName, AttrName>) => Tuple;

package/dist/sync/operators/allbut.d.ts

@@ -0,0 +1,2 @@
+import { RelationOperand, AttrName } from "../../types";
+export declare const allbut: (operand: RelationOperand, attrs: AttrName[]) => RelationOperand;

package/dist/sync/operators/autowrap.d.ts

@@ -0,0 +1,2 @@
+import { AutowrapOptions, RelationOperand } from "../../types";
+export declare const autowrap: (operand: RelationOperand, options?: AutowrapOptions) => RelationOperand;

package/dist/sync/operators/constants.d.ts

@@ -0,0 +1,2 @@
+import { RelationOperand, Tuple } from "../../types";
+export declare const constants: (operand: RelationOperand, consts: Tuple) => RelationOperand;

package/dist/sync/operators/cross_product.d.ts

@@ -0,0 +1,3 @@
+import { RelationOperand } from "../../types";
+export declare const cross_product: (left: RelationOperand, right: RelationOperand) => RelationOperand;
+export { cross_product as cross_join };

package/dist/sync/operators/exclude.d.ts

@@ -0,0 +1,2 @@
+import { RelationOperand, Predicate } from "../../types";
+export declare const exclude: (operand: RelationOperand, p: Predicate) => RelationOperand;

package/dist/sync/operators/extend.d.ts

@@ -0,0 +1,2 @@
+import { RelationOperand, Extension } from "../../types";
+export declare const extend: (operand: RelationOperand, extension: Extension) => RelationOperand;

package/dist/sync/operators/group.d.ts

@@ -0,0 +1,2 @@
+import { RelationOperand, AttrName } from "../../types";
+export declare const group: (operand: RelationOperand, attrs: AttrName[], as: AttrName) => RelationOperand;

package/dist/sync/operators/image.d.ts

@@ -0,0 +1,2 @@
+import { RelationOperand, JoinKeys, AttrName } from "../../types";
+export declare const image: (left: RelationOperand, right: RelationOperand, as: AttrName, keys?: JoinKeys) => RelationOperand;

package/dist/sync/operators/index.d.ts

@@ -0,0 +1,30 @@
+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';

package/dist/sync/operators/intersect.d.ts

@@ -0,0 +1,2 @@
+import { RelationOperand } from "../../types";
+export declare const intersect: (left: RelationOperand, right: RelationOperand) => RelationOperand;

package/dist/sync/operators/isEqual.d.ts

@@ -0,0 +1 @@
+export declare const isEqual: (left: any, right: any) => boolean;

package/dist/sync/operators/isRelation.d.ts

@@ -0,0 +1,2 @@
+import { Relation } from "@/types";
+export declare const isRelation: (op: unknown) => op is Relation<import("@/types").Tuple>;

package/dist/sync/operators/join.d.ts

@@ -0,0 +1,2 @@
+import { RelationOperand, JoinKeys } from "../../types";
+export declare const join: (left: RelationOperand, right: RelationOperand, keys?: JoinKeys) => RelationOperand;

package/dist/sync/operators/left_join.d.ts

@@ -0,0 +1,2 @@
+import { RelationOperand, JoinKeys } from "../../types";
+export declare const left_join: (left: RelationOperand, right: RelationOperand, keys?: JoinKeys) => RelationOperand;

package/dist/sync/operators/matching.d.ts

@@ -0,0 +1,2 @@
+import { RelationOperand, JoinKeys } from "../../types";
+export declare const matching: (left: RelationOperand, right: RelationOperand, keys?: JoinKeys) => RelationOperand;

package/dist/sync/operators/minus.d.ts

@@ -0,0 +1,2 @@
+import { RelationOperand } from "../../types";
+export declare const minus: (left: RelationOperand, right: RelationOperand) => RelationOperand;

package/dist/sync/operators/not_matching.d.ts

@@ -0,0 +1,2 @@
+import { RelationOperand, JoinKeys } from "../../types";
+export declare const not_matching: (left: RelationOperand, right: RelationOperand, keys?: JoinKeys) => RelationOperand;

package/dist/sync/operators/one.d.ts

@@ -0,0 +1,2 @@
+import { RelationOperand, Tuple } from "../../types";
+export declare const one: (operand: RelationOperand) => Tuple;

package/dist/sync/operators/prefix.d.ts

@@ -0,0 +1,2 @@
+import { PrefixOptions, RelationOperand } from "../../types";
+export declare const prefix: (operand: RelationOperand, pfx: string, options?: PrefixOptions) => RelationOperand;

package/dist/sync/operators/project.d.ts

@@ -0,0 +1,2 @@
+import { RelationOperand, AttrName } from "../../types";
+export declare const project: (operand: RelationOperand, attrs: AttrName[]) => RelationOperand;

package/dist/sync/operators/rename.d.ts

@@ -0,0 +1,2 @@
+import { RelationOperand, Renaming } from "../../types";
+export declare const rename: (operand: RelationOperand, renaming: Renaming) => RelationOperand;

package/dist/sync/operators/restrict.d.ts

@@ -0,0 +1,2 @@
+import { RelationOperand, Predicate } from "../../types";
+export declare const restrict: (operand: RelationOperand, p: Predicate) => RelationOperand;

package/dist/sync/operators/suffix.d.ts

@@ -0,0 +1,2 @@
+import { RelationOperand, SuffixOptions } from "../../types";
+export declare const suffix: (operand: RelationOperand, sfx: string, options?: SuffixOptions) => RelationOperand;

package/dist/sync/operators/summarize.d.ts

@@ -0,0 +1,2 @@
+import { RelationOperand, AttrName, Aggregators } from "../../types";
+export declare const summarize: (operand: RelationOperand, by: AttrName[], aggs: Aggregators) => RelationOperand;

package/dist/sync/operators/transform.d.ts

@@ -0,0 +1,2 @@
+import { RelationOperand, Transformation } from "../../types";
+export declare const transform: (operand: RelationOperand, transformation: Transformation) => RelationOperand;

package/dist/sync/operators/ungroup.d.ts

@@ -0,0 +1,2 @@
+import { RelationOperand, AttrName } from "../../types";
+export declare const ungroup: (operand: RelationOperand, attr: AttrName) => RelationOperand;

package/dist/sync/operators/union.d.ts

@@ -0,0 +1,2 @@
+import { RelationOperand } from "../../types";
+export declare const union: (left: RelationOperand, right: RelationOperand) => RelationOperand;

package/dist/sync/operators/unwrap.d.ts

@@ -0,0 +1,2 @@
+import { RelationOperand, AttrName } from "../../types";
+export declare const unwrap: (operand: RelationOperand, attr: AttrName) => RelationOperand;

package/dist/sync/operators/wrap.d.ts

@@ -0,0 +1,2 @@
+import { RelationOperand, AttrName } from "../../types";
+export declare const wrap: (operand: RelationOperand, attrs: AttrName[], as: AttrName) => RelationOperand;

package/dist/sync/operators/yByX.d.ts

@@ -0,0 +1,2 @@
+import { AttrName, RelationOperand, Tuple } from "../../types";
+export declare const yByX: (operand: RelationOperand, y: AttrName, x: AttrName) => Tuple;

package/dist/types.d.ts

@@ -90,6 +90,12 @@ export type Extension = Record<AttrName, ExtensionFunc | AttrName>;
 export interface PrefixOptions {
     except?: AttrName[];
 }
+export interface TextOptions {
+    /** Precision for floating point numbers (default: 3) */
+    floatPrecision?: number;
+    /** Maximum width to trim output at */
+    trimAt?: number;
+}
 export interface SuffixOptions {
     except?: AttrName[];
 }
@@ -154,6 +160,7 @@ export 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;
+    toText(options?: TextOptions): string;
 }
 export type RelationOperand<T = Tuple> = Relation<T> | T[];
 export interface OperationalOperand<T = Tuple> {

package/dist/writer/Text.d.ts

@@ -0,0 +1,40 @@
+import { Relation, Tuple } from '../types';
+/**
+ * Options for text rendering
+ */
+export interface TextOptions {
+    /** Format string for floating point numbers (default: '%.3f' style) */
+    floatPrecision?: number;
+    /** Maximum width to trim output at */
+    trimAt?: number;
+}
+/**
+ * Text writer for rendering relations as ASCII tables
+ */
+export declare class TextWriter {
+    readonly options: TextOptions;
+    constructor(options?: TextOptions);
+    /**
+     * Renders a relation or tuple array to an ASCII table string
+     */
+    render(input: Relation | Tuple[] | Tuple, output?: string): string;
+    eachLine(input: Relation | Tuple[] | Tuple): Generator<string>;
+}
+/**
+ * Renders a relation as an ASCII table string
+ *
+ * @param operand - The relation or tuple array to render
+ * @param options - Text rendering options
+ * @returns ASCII table string representation
+ *
+ * @example
+ * const r = Bmg([{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }]);
+ * console.log(toText(r));
+ * // +----+-------+
+ * // | id | name  |
+ * // +----+-------+
+ * // |  1 | Alice |
+ * // |  2 | Bob   |
+ * // +----+-------+
+ */
+export declare const toText: (operand: Relation | Tuple[] | Tuple, options?: TextOptions) => string;

package/dist/writer/index.d.ts

@@ -0,0 +1 @@
+export * from './Text';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enspirit/bmg-js",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "Relational algebra for JavaScript/TypeScript - work with arrays of objects using powerful set operations",
   "keywords": [
     "relational",

package/src/Relation/index.ts

@@ -1 +1,2 @@
-export * from './Memory';
+// Re-export sync Relation for backward compatibility
+export * from '../sync/Relation';

package/src/async/Relation/Base.ts

@@ -0,0 +1,245 @@
+import type { AsyncRelation, AsyncRelationOperand } from '../types';
+import type { Tuple, TypedPredicate, TypedExtension, AttrName, Relation, RenameMap, Renamed, Prefixed, Suffixed, Transformation, JoinKeys, Aggregators, AutowrapOptions, TextOptions } from '../../types';
+import { MemoryRelation } from '../../sync/Relation';
+import {
+  restrict as restrictOp,
+  where as whereOp,
+  exclude as excludeOp,
+} from '../operators/restrict';
+import {
+  project as projectOp,
+  allbut as allbutOp,
+} from '../operators/project';
+import { extend as extendOp } from '../operators/extend';
+import { constants as constantsOp } from '../operators/constants';
+import { rename as renameOp } from '../operators/rename';
+import { prefix as prefixOp } from '../operators/prefix';
+import { suffix as suffixOp } from '../operators/suffix';
+import { transform as transformOp } from '../operators/transform';
+import { union as unionOp } from '../operators/union';
+import { minus as minusOp } from '../operators/minus';
+import { intersect as intersectOp } from '../operators/intersect';
+import { matching as matchingOp } from '../operators/matching';
+import { not_matching as notMatchingOp } from '../operators/not_matching';
+import { join as joinOp } from '../operators/join';
+import { left_join as leftJoinOp } from '../operators/left_join';
+import { cross_product as crossProductOp } from '../operators/cross_product';
+import { group as groupOp } from '../operators/group';
+import { ungroup as ungroupOp } from '../operators/ungroup';
+import { wrap as wrapOp } from '../operators/wrap';
+import { unwrap as unwrapOp } from '../operators/unwrap';
+import { image as imageOp } from '../operators/image';
+import { summarize as summarizeOp } from '../operators/summarize';
+import { autowrap as autowrapOp } from '../operators/autowrap';
+import { yByX as yByXOp } from '../operators/yByX';
+import { one as oneOp } from '../operators/one';
+import { toArray as toArrayOp } from '../operators/toArray';
+import { toText as toTextSync } from '../../writer';
+
+/**
+ * Base implementation of AsyncRelation using lazy evaluation.
+ * Each operator returns a new BaseAsyncRelation wrapping the transformed iterable.
+ */
+export class BaseAsyncRelation<T = Tuple> implements AsyncRelation<T> {
+  constructor(private source: AsyncIterable<T>) {}
+
+  // === Type-preserving operators ===
+
+  restrict(p: TypedPredicate<T>): AsyncRelation<T> {
+    return new BaseAsyncRelation(restrictOp(this.source, p as any));
+  }
+
+  where(p: TypedPredicate<T>): AsyncRelation<T> {
+    return new BaseAsyncRelation(whereOp(this.source, p as any));
+  }
+
+  exclude(p: TypedPredicate<T>): AsyncRelation<T> {
+    return new BaseAsyncRelation(excludeOp(this.source, p as any));
+  }
+
+  // === Projection operators ===
+
+  project<K extends keyof T>(attrs: K[]): AsyncRelation<Pick<T, K>> {
+    return new BaseAsyncRelation(
+      projectOp(this.source, attrs as AttrName[])
+    ) as unknown as AsyncRelation<Pick<T, K>>;
+  }
+
+  allbut<K extends keyof T>(attrs: K[]): AsyncRelation<Omit<T, K>> {
+    return new BaseAsyncRelation(
+      allbutOp(this.source, attrs as AttrName[])
+    ) as unknown as AsyncRelation<Omit<T, K>>;
+  }
+
+  // === Extension operators ===
+
+  extend<E extends Record<string, unknown>>(e: TypedExtension<T, E>): AsyncRelation<T & E> {
+    return new BaseAsyncRelation(
+      extendOp(this.source, e as any)
+    ) as unknown as AsyncRelation<T & E>;
+  }
+
+  constants<C extends Tuple>(consts: C): AsyncRelation<T & C> {
+    return new BaseAsyncRelation(
+      constantsOp(this.source, consts)
+    ) as unknown as AsyncRelation<T & C>;
+  }
+
+  // === Rename operators ===
+
+  rename<R extends RenameMap<T>>(r: R): AsyncRelation<Renamed<T, R>> {
+    return new BaseAsyncRelation(
+      renameOp(this.source, r as any)
+    ) as unknown as AsyncRelation<Renamed<T, R>>;
+  }
+
+  prefix<P extends string, Ex extends keyof T = never>(pfx: P, options?: { except?: Ex[] }): AsyncRelation<Prefixed<T, P, Ex>> {
+    return new BaseAsyncRelation(
+      prefixOp(this.source, pfx, options as any)
+    ) as unknown as AsyncRelation<Prefixed<T, P, Ex>>;
+  }
+
+  suffix<S extends string, Ex extends keyof T = never>(sfx: S, options?: { except?: Ex[] }): AsyncRelation<Suffixed<T, S, Ex>> {
+    return new BaseAsyncRelation(
+      suffixOp(this.source, sfx, options as any)
+    ) as unknown as AsyncRelation<Suffixed<T, S, Ex>>;
+  }
+
+  transform(t: Transformation): AsyncRelation<T> {
+    return new BaseAsyncRelation(
+      transformOp(this.source, t)
+    ) as unknown as AsyncRelation<T>;
+  }
+
+  // === Set operations ===
+
+  union(other: AsyncRelationOperand<T>): AsyncRelation<T> {
+    return new BaseAsyncRelation(
+      unionOp(this.source, other)
+    ) as unknown as AsyncRelation<T>;
+  }
+
+  minus(other: AsyncRelationOperand<T>): AsyncRelation<T> {
+    return new BaseAsyncRelation(
+      minusOp(this.source, other)
+    ) as unknown as AsyncRelation<T>;
+  }
+
+  intersect(other: AsyncRelationOperand<T>): AsyncRelation<T> {
+    return new BaseAsyncRelation(
+      intersectOp(this.source, other)
+    ) as unknown as AsyncRelation<T>;
+  }
+
+  // === Semi-joins ===
+
+  matching<U>(other: AsyncRelationOperand<U>, keys?: JoinKeys): AsyncRelation<T> {
+    return new BaseAsyncRelation(
+      matchingOp(this.source, other, keys)
+    ) as unknown as AsyncRelation<T>;
+  }
+
+  not_matching<U>(other: AsyncRelationOperand<U>, keys?: JoinKeys): AsyncRelation<T> {
+    return new BaseAsyncRelation(
+      notMatchingOp(this.source, other, keys)
+    ) as unknown as AsyncRelation<T>;
+  }
+
+  // === Joins ===
+
+  join<U>(other: AsyncRelationOperand<U>, keys?: JoinKeys): AsyncRelation<T & U> {
+    return new BaseAsyncRelation(
+      joinOp(this.source, other, keys)
+    ) as unknown as AsyncRelation<T & U>;
+  }
+
+  left_join<U>(other: AsyncRelationOperand<U>, keys?: JoinKeys): AsyncRelation<T & Partial<U>> {
+    return new BaseAsyncRelation(
+      leftJoinOp(this.source, other, keys)
+    ) as unknown as AsyncRelation<T & Partial<U>>;
+  }
+
+  cross_product<U>(other: AsyncRelationOperand<U>): AsyncRelation<T & U> {
+    return new BaseAsyncRelation(
+      crossProductOp(this.source, other)
+    ) as unknown as AsyncRelation<T & U>;
+  }
+
+  cross_join<U>(other: AsyncRelationOperand<U>): AsyncRelation<T & U> {
+    return this.cross_product(other);
+  }
+
+  // === Nesting/Grouping ===
+
+  group<K extends keyof T>(attrs: K[], as: string): AsyncRelation<Omit<T, K> & Record<string, Relation<Pick<T, K>>>> {
+    return new BaseAsyncRelation(
+      groupOp(this.source, attrs as string[], as)
+    ) as unknown as AsyncRelation<Omit<T, K> & Record<string, Relation<Pick<T, K>>>>;
+  }
+
+  ungroup(attr: string): AsyncRelation<Tuple> {
+    return new BaseAsyncRelation(
+      ungroupOp(this.source, attr)
+    ) as unknown as AsyncRelation<Tuple>;
+  }
+
+  wrap<K extends keyof T>(attrs: K[], as: string): AsyncRelation<Omit<T, K> & Record<string, Pick<T, K>>> {
+    return new BaseAsyncRelation(
+      wrapOp(this.source, attrs as string[], as)
+    ) as unknown as AsyncRelation<Omit<T, K> & Record<string, Pick<T, K>>>;
+  }
+
+  unwrap(attr: string): AsyncRelation<Tuple> {
+    return new BaseAsyncRelation(
+      unwrapOp(this.source, attr)
+    ) as unknown as AsyncRelation<Tuple>;
+  }
+
+  image<U>(other: AsyncRelationOperand<U>, as: string, keys?: JoinKeys): AsyncRelation<T & Record<string, Relation<U>>> {
+    return new BaseAsyncRelation(
+      imageOp(this.source, other, as, keys)
+    ) as unknown as AsyncRelation<T & Record<string, Relation<U>>>;
+  }
+
+  summarize<K extends keyof T>(by: K[], aggs: Aggregators): AsyncRelation<Pick<T, K> & Tuple> {
+    return new BaseAsyncRelation(
+      summarizeOp(this.source, by as string[], aggs)
+    ) as unknown as AsyncRelation<Pick<T, K> & Tuple>;
+  }
+
+  autowrap(options?: AutowrapOptions): AsyncRelation<Tuple> {
+    return new BaseAsyncRelation(
+      autowrapOp(this.source, options)
+    ) as unknown as AsyncRelation<Tuple>;
+  }
+
+  // === Terminal operations ===
+
+  one(): Promise<T> {
+    return oneOp(this.source);
+  }
+
+  toArray(): Promise<T[]> {
+    return toArrayOp(this.source);
+  }
+
+  async toRelation(): Promise<Relation<T>> {
+    const tuples = await toArrayOp(this.source);
+    return new MemoryRelation<T>(tuples);
+  }
+
+  yByX(y: string, x: string): Promise<Tuple> {
+    return yByXOp(this.source, y, x);
+  }
+
+  async toText(options?: TextOptions): Promise<string> {
+    const tuples = await toArrayOp(this.source);
+    return toTextSync(tuples as Tuple[], options);
+  }
+
+  // === Async iteration ===
+
+  [Symbol.asyncIterator](): AsyncIterator<T> {
+    return this.source[Symbol.asyncIterator]();
+  }
+}

package/src/async/Relation/index.ts

@@ -0,0 +1,31 @@
+import { BaseAsyncRelation } from './Base';
+import type { AsyncRelation, AsyncRelationOperand } from '../types';
+import { isEqual as isEqualOp } from '../operators/isEqual';
+
+export { BaseAsyncRelation };
+
+/**
+ * Creates a new async relation from an AsyncIterable source.
+ *
+ * @typeParam T - The tuple type. Inferred from input or explicitly provided.
+ *
+ * @example
+ * // From an async iterable
+ * const suppliers = AsyncBmg(fetchSuppliersFromDB());
+ *
+ * @example
+ * // Chained operations (lazy - no execution yet)
+ * const query = AsyncBmg(source)
+ *   .restrict({ city: 'London' })
+ *   .project(['sid', 'name']);
+ *
+ * // Terminal operation triggers execution
+ * const results = await query.toArray();
+ */
+export function AsyncBmg<T>(source: AsyncIterable<T>): AsyncRelation<T> {
+  return new BaseAsyncRelation<T>(source);
+}
+
+AsyncBmg.isEqual = <T, U>(left: AsyncRelationOperand<T>, right: AsyncRelationOperand<U>): Promise<boolean> => {
+  return isEqualOp(left, right);
+};