@enspirit/bmg-js 1.0.1 → 1.1.0

package/dist/{src/src/types.d.ts → types.d.ts}

@@ -1,101 +1,169 @@
-import type { RenameMap, Renamed, Prefixed, Suffixed, Joined, LeftJoined, Wrapped, Unwrapped, AggregatorResults } from './utility-types';
-/** Result of ungroup: remove relation attr, flatten its tuple type */
-export type Ungrouped<T, K extends keyof T> = T[K] extends Relation<infer N> ? Omit<T, K> & N : Omit<T, K>;
-export type AttrName = string;
-export type Tuple = Record<AttrName, unknown>;
-export interface PrefixOptions {
-    except?: AttrName[];
-}
-export interface SuffixOptions {
-    except?: AttrName[];
-}
-export interface AutowrapOptions {
-    separator?: string;
-}
-/** Predicate function that receives a typed tuple */
-export type TypedPredicateFunc<T> = (t: T) => boolean;
-/** Predicate: either a partial tuple for equality matching, or a function */
-export type TypedPredicate<T> = Partial<T> | TypedPredicateFunc<T>;
-/** Extension function that receives a typed tuple */
-export type TypedExtensionFunc<T, R> = (tuple: T) => R;
-/** Extension definition: function returning value, or attribute name to copy */
-export type TypedExtension<T, E extends Record<string, unknown>> = {
-    [K in keyof E]: TypedExtensionFunc<T, E[K]> | keyof T;
-};
-/**
- * Relation interface with generic type parameter for tuple type.
- * Default parameter `Tuple` ensures backwards compatibility.
- *
- * @typeParam T - The tuple type for this relation. Defaults to `Tuple` (Record<string, unknown>).
- *
- * @example
- * // Untyped usage (backwards compatible)
- * const r = Bmg([{ id: 1 }]);  // Relation<Tuple>
- *
- * @example
- * // Typed usage with full type safety
- * interface Person { id: number; name: string }
- * const r = Bmg<Person>([{ id: 1, name: 'Alice' }]);
- * r.project(['id']);  // Relation<{ id: number }>
- */
-export interface Relation<T = Tuple> {
-    restrict(p: TypedPredicate<T>): Relation<T>;
-    where(p: TypedPredicate<T>): Relation<T>;
-    exclude(p: TypedPredicate<T>): Relation<T>;
-    project<K extends keyof T>(attrs: K[]): Relation<Pick<T, K>>;
-    allbut<K extends keyof T>(attrs: K[]): Relation<Omit<T, K>>;
-    extend<E extends Record<string, unknown>>(e: TypedExtension<T, E>): Relation<T & E>;
-    constants<C extends Tuple>(consts: C): Relation<T & C>;
-    rename<R extends RenameMap<T>>(r: R): Relation<Renamed<T, R>>;
-    prefix<P extends string, Ex extends keyof T = never>(pfx: P, options?: {
-        except?: Ex[];
-    }): Relation<Prefixed<T, P, Ex>>;
-    suffix<S extends string, Ex extends keyof T = never>(sfx: S, options?: {
-        except?: Ex[];
-    }): Relation<Suffixed<T, S, Ex>>;
-    union(right: RelationOperand<T>): Relation<T>;
-    minus(right: RelationOperand<T>): Relation<T>;
-    intersect(right: RelationOperand<T>): Relation<T>;
-    matching<R>(right: RelationOperand<R>, keys?: JoinKeys): Relation<T>;
-    not_matching<R>(right: RelationOperand<R>, keys?: JoinKeys): Relation<T>;
-    join<R>(right: RelationOperand<R>, keys?: JoinKeys): Relation<Joined<T, R>>;
-    left_join<R>(right: RelationOperand<R>, keys?: JoinKeys): Relation<LeftJoined<T, R>>;
-    cross_product<R>(right: RelationOperand<R>): Relation<T & R>;
-    cross_join<R>(right: RelationOperand<R>): Relation<T & R>;
-    image<R, As extends string>(right: RelationOperand<R>, as: As, keys?: JoinKeys): Relation<T & Record<As, Relation<Omit<R, keyof T & keyof R>>>>;
-    group<K extends keyof T, As extends string>(attrs: K[], as: As): Relation<Omit<T, K> & Record<As, Relation<Pick<T, K>>>>;
-    ungroup<K extends keyof T>(attr: K): Relation<Ungrouped<T, K>>;
-    wrap<K extends keyof T, As extends string>(attrs: K[], as: As): Relation<Wrapped<T, K, As>>;
-    unwrap<K extends keyof T>(attr: K): Relation<Unwrapped<T, K>>;
-    summarize<By extends keyof T, Aggs extends Aggregators>(by: By[], aggs: Aggs): Relation<Pick<T, By> & AggregatorResults<Aggs>>;
-    transform(t: Transformation): Relation<T>;
-    autowrap(options?: AutowrapOptions): Relation<Tuple>;
-    one(): T;
-    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;
-}
-export type RelationOperand<T = Tuple> = Relation<T> | T[];
-export interface OperationalOperand<T = Tuple> {
-    tuples(): Iterable<T>;
-    output(tuples: T[]): RelationOperand<T>;
-}
-export type PredicateFunc = ((t: Tuple) => any);
-export type Predicate = Tuple | PredicateFunc;
-export type Renaming = RenamingObj | RenamingFunc;
-export type RenamingFunc = (attr: AttrName) => AttrName;
-export type RenamingObj = Record<AttrName, AttrName>;
-export type ExtensionFunc = (tuple: Tuple) => unknown;
-export type Extension = Record<AttrName, ExtensionFunc | AttrName>;
-export type JoinKeys = AttrName[] | Record<AttrName, AttrName>;
-export type AggregatorName = 'count' | 'sum' | 'min' | 'max' | 'avg' | 'collect';
-export type AggregatorSpec = {
-    op: AggregatorName;
-    attr: AttrName;
-};
-export type AggregatorFunc = (tuples: Tuple[]) => unknown;
-export type Aggregator = AggregatorName | AggregatorSpec | AggregatorFunc;
-export type Aggregators = Record<AttrName, Aggregator>;
-export type TransformFunc = (value: unknown) => unknown;
-export type Transformation = TransformFunc | TransformFunc[] | Record<AttrName, TransformFunc | TransformFunc[]>;
-export type { RenameMap, Renamed, Prefixed, Suffixed, Joined, LeftJoined, Wrapped, Unwrapped } from './utility-types';
+/**
+ * Type definitions for Bmg.js relational algebra library.
+ *
+ * This file defines all types needed for type-safe relational operations:
+ * - Base types (AttrName, Tuple)
+ * - Utility types for transformations (Renamed, Prefixed, Joined, etc.)
+ * - The Relation interface with all operators
+ * - Helper types for predicates, extensions, aggregators, etc.
+ */
+/** Attribute name in a tuple */
+export type AttrName = string;
+/** A tuple is a record mapping attribute names to values */
+export type Tuple = Record<AttrName, unknown>;
+/** Map from old attribute names to new attribute names */
+export type RenameMap<T> = {
+    [K in keyof T]?: string;
+};
+/** Transform tuple type by renaming keys according to RenameMap */
+export type Renamed<T, R extends RenameMap<T>> = {
+    [K in keyof T as K extends keyof R ? (R[K] extends string ? R[K] : K) : K]: T[K];
+};
+/** Prefix all keys except those in Except */
+export type Prefixed<T, P extends string, Except extends keyof T = never> = {
+    [K in keyof T as K extends Except ? K : `${P}${K & string}`]: T[K];
+};
+/** Suffix all keys except those in Except */
+export type Suffixed<T, S extends string, Except extends keyof T = never> = {
+    [K in keyof T as K extends Except ? K : `${K & string}${S}`]: T[K];
+};
+/** Extract common keys between two tuple types */
+export type CommonKeys<L, R> = Extract<keyof L, keyof R>;
+/** Result of inner join: L & R with R's common keys removed */
+export type Joined<L, R> = L & Omit<R, CommonKeys<L, R>>;
+/** Result of left join: L & optional R attributes (common keys removed) */
+export type LeftJoined<L, R> = L & Partial<Omit<R, CommonKeys<L, R>>>;
+/**
+ * Typed join keys for array form: keys must exist on BOTH operands.
+ * Example: suppliers.join(parts, ['city']) - 'city' must be a key of both.
+ */
+export type TypedJoinKeysArray<L, R> = (keyof L & keyof R & string)[];
+/**
+ * Typed join keys for object form: maps left keys to right keys.
+ * Example: suppliers.join(parts, { sid: 'supplier_id' })
+ * - Left key (sid) must exist on L
+ * - Right key (supplier_id) must exist on R
+ */
+export type TypedJoinKeysObject<L, R> = {
+    [K in keyof L & string]?: keyof R & string;
+};
+/** Result of wrap: remove wrapped attrs, add nested object */
+export type Wrapped<T, K extends keyof T, As extends string> = Omit<T, K> & Record<As, Pick<T, K>>;
+/** Result of unwrap: remove object attr, spread its properties */
+export type Unwrapped<T, K extends keyof T> = T[K] extends Record<string, unknown> ? Omit<T, K> & T[K] : Omit<T, K>;
+/** Result of ungroup: remove relation attr, flatten its tuple type */
+export type Ungrouped<T, K extends keyof T> = T[K] extends Relation<infer N> ? Omit<T, K> & N : Omit<T, K>;
+export type AggregatorName = 'count' | 'sum' | 'min' | 'max' | 'avg' | 'collect';
+export type AggregatorSpec = {
+    op: AggregatorName;
+    attr: AttrName;
+};
+export type AggregatorFunc = (tuples: Tuple[]) => unknown;
+export type Aggregator = AggregatorName | AggregatorSpec | AggregatorFunc;
+export type Aggregators = Record<AttrName, Aggregator>;
+/** Infer result type from aggregator specification */
+export type AggregatorResult<A> = A extends 'count' ? number : A extends {
+    op: 'count';
+} ? number : A extends {
+    op: 'sum' | 'avg' | 'min' | 'max';
+} ? number | null : A extends {
+    op: 'collect';
+} ? unknown[] : A extends (tuples: Tuple[]) => infer R ? R : unknown;
+/** Map aggregator definitions to their result types */
+export type AggregatorResults<Aggs extends Record<string, unknown>> = {
+    [K in keyof Aggs]: AggregatorResult<Aggs[K]>;
+};
+/** Predicate function that receives a typed tuple */
+export type TypedPredicateFunc<T> = (t: T) => boolean;
+/** Predicate: either a partial tuple for equality matching, or a function */
+export type TypedPredicate<T> = Partial<T> | TypedPredicateFunc<T>;
+export type PredicateFunc = ((t: Tuple) => any);
+export type Predicate = Tuple | PredicateFunc;
+/** Extension function that receives a typed tuple */
+export type TypedExtensionFunc<T, R> = (tuple: T) => R;
+/** Extension definition: function returning value, or attribute name to copy */
+export type TypedExtension<T, E extends Record<string, unknown>> = {
+    [K in keyof E]: TypedExtensionFunc<T, E[K]> | keyof T;
+};
+export type ExtensionFunc = (tuple: Tuple) => unknown;
+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[];
+}
+export interface AutowrapOptions {
+    separator?: string;
+}
+export type Renaming = RenamingObj | RenamingFunc;
+export type RenamingFunc = (attr: AttrName) => AttrName;
+export type RenamingObj = Record<AttrName, AttrName>;
+export type JoinKeys = AttrName[] | Record<AttrName, AttrName>;
+export type TransformFunc = (value: unknown) => unknown;
+export type Transformation = TransformFunc | TransformFunc[] | Record<AttrName, TransformFunc | TransformFunc[]>;
+/**
+ * Relation interface with generic type parameter for tuple type.
+ * Default parameter `Tuple` ensures backwards compatibility.
+ *
+ * @typeParam T - The tuple type for this relation. Defaults to `Tuple` (Record<string, unknown>).
+ *
+ * @example
+ * // Untyped usage (backwards compatible)
+ * const r = Bmg([{ id: 1 }]);  // Relation<Tuple>
+ *
+ * @example
+ * // Typed usage with full type safety
+ * interface Person { id: number; name: string }
+ * const r = Bmg<Person>([{ id: 1, name: 'Alice' }]);
+ * r.project(['id']);  // Relation<{ id: number }>
+ */
+export interface Relation<T = Tuple> {
+    restrict(p: TypedPredicate<T>): Relation<T>;
+    where(p: TypedPredicate<T>): Relation<T>;
+    exclude(p: TypedPredicate<T>): Relation<T>;
+    project<K extends keyof T>(attrs: K[]): Relation<Pick<T, K>>;
+    allbut<K extends keyof T>(attrs: K[]): Relation<Omit<T, K>>;
+    extend<E extends Record<string, unknown>>(e: TypedExtension<T, E>): Relation<T & E>;
+    constants<C extends Tuple>(consts: C): Relation<T & C>;
+    rename<R extends RenameMap<T>>(r: R): Relation<Renamed<T, R>>;
+    prefix<P extends string, Ex extends keyof T = never>(pfx: P, options?: {
+        except?: Ex[];
+    }): Relation<Prefixed<T, P, Ex>>;
+    suffix<S extends string, Ex extends keyof T = never>(sfx: S, options?: {
+        except?: Ex[];
+    }): Relation<Suffixed<T, S, Ex>>;
+    union(right: RelationOperand<T>): Relation<T>;
+    minus(right: RelationOperand<T>): Relation<T>;
+    intersect(right: RelationOperand<T>): Relation<T>;
+    matching<R>(right: RelationOperand<R>, keys?: TypedJoinKeysArray<T, R> | TypedJoinKeysObject<T, R>): Relation<T>;
+    not_matching<R>(right: RelationOperand<R>, keys?: TypedJoinKeysArray<T, R> | TypedJoinKeysObject<T, R>): Relation<T>;
+    join<R>(right: RelationOperand<R>, keys?: TypedJoinKeysArray<T, R> | TypedJoinKeysObject<T, R>): Relation<Joined<T, R>>;
+    left_join<R>(right: RelationOperand<R>, keys?: TypedJoinKeysArray<T, R> | TypedJoinKeysObject<T, R>): Relation<LeftJoined<T, R>>;
+    cross_product<R>(right: RelationOperand<R>): Relation<T & R>;
+    cross_join<R>(right: RelationOperand<R>): Relation<T & R>;
+    image<R, As extends string>(right: RelationOperand<R>, as: As, keys?: TypedJoinKeysArray<T, R> | TypedJoinKeysObject<T, R>): Relation<T & Record<As, Relation<Omit<R, keyof T & keyof R>>>>;
+    group<K extends keyof T, As extends string>(attrs: K[], as: As): Relation<Omit<T, K> & Record<As, Relation<Pick<T, K>>>>;
+    ungroup<K extends keyof T>(attr: K): Relation<Ungrouped<T, K>>;
+    wrap<K extends keyof T, As extends string>(attrs: K[], as: As): Relation<Wrapped<T, K, As>>;
+    unwrap<K extends keyof T>(attr: K): Relation<Unwrapped<T, K>>;
+    summarize<By extends keyof T, Aggs extends Aggregators>(by: By[], aggs: Aggs): Relation<Pick<T, By> & AggregatorResults<Aggs>>;
+    transform(t: Transformation): Relation<T>;
+    autowrap(options?: AutowrapOptions): Relation<Tuple>;
+    one(): T;
+    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> {
+    tuples(): Iterable<T>;
+    output(tuples: T[]): RelationOperand<T>;
+}

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.1",
+  "version": "1.1.0",
   "description": "Relational algebra for JavaScript/TypeScript - work with arrays of objects using powerful set operations",
   "keywords": [
     "relational",
@@ -23,22 +23,24 @@
   "type": "module",
   "source": "src/index.ts",
   "exports": {
-    "types": "./dist/src/index.d.ts",
+    "types": "./dist/index.d.ts",
     "require": "./dist/bmg.cjs",
     "default": "./dist/bmg.modern.js"
   },
   "main": "./dist/bmg.cjs",
   "module": "./dist/bmg.module.js",
-  "types": "./dist/src/index.d.ts",
+  "types": "./dist/index.d.ts",
   "unpkg": "./dist/bmg.umd.js",
   "scripts": {
-    "build": "microbundle",
+    "generate:lib-definitions": "npx tsx scripts/generate-lib-definitions.ts",
+    "build": "npm run generate:lib-definitions && microbundle --no-generateTypes && tsc -p tsconfig.build.json",
     "dev": "microbundle watch",
     "test": "vitest run",
     "test:watch": "vitest"
   },
   "devDependencies": {
     "microbundle": "^0.15.1",
+    "tsx": "^4.19.0",
     "vite-tsconfig-paths": "^5.1.4",
     "vitest": "^4.0.16"
   },

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