@enspirit/bmg-js 1.0.2 → 1.1.0

package/README.md

@@ -111,6 +111,7 @@ See the [full type-safe example](./example/index.ts) for more.
 | | `toArray()` | Convert relation to array |
 | | `isEqual(other)` | Check set equality |
 | | `yByX(y, x)` | Create `{ x-value: y-value }` mapping |
+| | `toText(options?)` | Render as ASCII table |
 | | `Bmg.isRelation(value)` | Check if value is a Relation (static) |
 
 Built-in aggregators for `summarize`: `count`, `sum`, `min`, `max`, `avg`, `collect`
@@ -139,9 +140,9 @@ This will be provided by [Elo](https://elo-lang.org).
 
 ## Versioning
 
-Bmg.js follows [Semantic Versioning](https://semver.org/) (SemVer):
+Bmg.js follows [Semantic Versioning](https://semver.org/) (SemVer). See [API.md](API.md) for the public API reference.
 
-- **MAJOR** (x.0.0) - Breaking changes to the API (renamed operators, changed signatures, removed features)
+- **MAJOR** (x.0.0) - Breaking changes to the public API
 - **MINOR** (0.x.0) - New operators or features, fully backward-compatible
 - **PATCH** (0.0.x) - Bug fixes and performance improvements, no API changes
 

package/dist/AsyncRelation/Base.d.ts

@@ -0,0 +1,47 @@
+import type { AsyncRelation, AsyncRelationOperand } from '../async-types';
+import type { Tuple, TypedPredicate, TypedExtension, Relation, RenameMap, Renamed, Prefixed, Suffixed, Transformation, JoinKeys, Aggregators, AutowrapOptions, TextOptions } from '../types';
+/**
+ * Base implementation of AsyncRelation using lazy evaluation.
+ * Each operator returns a new BaseAsyncRelation wrapping the transformed iterable.
+ */
+export declare class BaseAsyncRelation<T = Tuple> implements AsyncRelation<T> {
+    private source;
+    constructor(source: AsyncIterable<T>);
+    restrict(p: TypedPredicate<T>): AsyncRelation<T>;
+    where(p: TypedPredicate<T>): AsyncRelation<T>;
+    exclude(p: TypedPredicate<T>): AsyncRelation<T>;
+    project<K extends keyof T>(attrs: K[]): AsyncRelation<Pick<T, K>>;
+    allbut<K extends keyof T>(attrs: K[]): AsyncRelation<Omit<T, K>>;
+    extend<E extends Record<string, unknown>>(e: TypedExtension<T, E>): AsyncRelation<T & E>;
+    constants<C extends Tuple>(consts: C): AsyncRelation<T & C>;
+    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>;
+    union(other: AsyncRelationOperand<T>): AsyncRelation<T>;
+    minus(other: AsyncRelationOperand<T>): AsyncRelation<T>;
+    intersect(other: AsyncRelationOperand<T>): AsyncRelation<T>;
+    matching<U>(other: AsyncRelationOperand<U>, keys?: JoinKeys): AsyncRelation<T>;
+    not_matching<U>(other: AsyncRelationOperand<U>, keys?: JoinKeys): AsyncRelation<T>;
+    join<U>(other: AsyncRelationOperand<U>, keys?: JoinKeys): AsyncRelation<T & U>;
+    left_join<U>(other: AsyncRelationOperand<U>, keys?: JoinKeys): AsyncRelation<T & Partial<U>>;
+    cross_product<U>(other: AsyncRelationOperand<U>): AsyncRelation<T & U>;
+    cross_join<U>(other: AsyncRelationOperand<U>): AsyncRelation<T & U>;
+    group<K extends keyof T>(attrs: K[], as: string): AsyncRelation<Omit<T, K> & Record<string, Relation<Pick<T, K>>>>;
+    ungroup(attr: string): AsyncRelation<Tuple>;
+    wrap<K extends keyof T>(attrs: K[], as: string): AsyncRelation<Omit<T, K> & Record<string, Pick<T, K>>>;
+    unwrap(attr: string): AsyncRelation<Tuple>;
+    image<U>(other: AsyncRelationOperand<U>, as: string, 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>;
+    one(): Promise<T>;
+    toArray(): Promise<T[]>;
+    toRelation(): Promise<Relation<T>>;
+    yByX(y: string, x: string): Promise<Tuple>;
+    toText(options?: TextOptions): Promise<string>;
+    [Symbol.asyncIterator](): AsyncIterator<T>;
+}

package/dist/AsyncRelation/index.d.ts

@@ -0,0 +1,25 @@
+import { BaseAsyncRelation } from './Base';
+import type { AsyncRelation, AsyncRelationOperand } from '../async-types';
+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 declare function AsyncBmg<T>(source: AsyncIterable<T>): AsyncRelation<T>;
+export declare namespace AsyncBmg {
+    var isEqual: <T, U>(left: AsyncRelationOperand<T>, right: AsyncRelationOperand<U>) => Promise<boolean>;
+}

package/dist/Relation/Memory.d.ts

@@ -1,4 +1,4 @@
-import type { AutowrapOptions, Relation, RelationOperand, Transformation, Tuple, TypedPredicate, TypedExtension, RenameMap, Renamed, Prefixed, Suffixed, Joined, LeftJoined, Wrapped, Unwrapped, Ungrouped, AggregatorResults, TypedJoinKeysArray, TypedJoinKeysObject } from "../types";
+import type { AutowrapOptions, Relation, RelationOperand, TextOptions, Transformation, Tuple, TypedPredicate, TypedExtension, RenameMap, Renamed, Prefixed, Suffixed, Joined, LeftJoined, Wrapped, Unwrapped, Ungrouped, AggregatorResults, TypedJoinKeysArray, TypedJoinKeysObject } from "../types";
 /**
  * In-memory implementation of the Relation interface.
  *
@@ -42,4 +42,5 @@ export declare class MemoryRelation<T = Tuple> implements Relation<T> {
     toArray(): T[];
     yByX<Y extends keyof T, X extends keyof T>(y: Y, x: X): Record<T[X] & PropertyKey, T[Y]>;
     isEqual(right: any): boolean;
+    toText(options?: TextOptions): string;
 }

package/dist/Relation/index.d.ts

@@ -1 +1 @@
-export * from './Memory';
+export * from '../sync/Relation';

package/dist/async/Relation/Base.d.ts

@@ -0,0 +1,47 @@
+import type { AsyncRelation, AsyncRelationOperand } from '../types';
+import type { Tuple, TypedPredicate, TypedExtension, Relation, RenameMap, Renamed, Prefixed, Suffixed, Transformation, JoinKeys, Aggregators, AutowrapOptions, TextOptions } from '../../types';
+/**
+ * Base implementation of AsyncRelation using lazy evaluation.
+ * Each operator returns a new BaseAsyncRelation wrapping the transformed iterable.
+ */
+export declare class BaseAsyncRelation<T = Tuple> implements AsyncRelation<T> {
+    private source;
+    constructor(source: AsyncIterable<T>);
+    restrict(p: TypedPredicate<T>): AsyncRelation<T>;
+    where(p: TypedPredicate<T>): AsyncRelation<T>;
+    exclude(p: TypedPredicate<T>): AsyncRelation<T>;
+    project<K extends keyof T>(attrs: K[]): AsyncRelation<Pick<T, K>>;
+    allbut<K extends keyof T>(attrs: K[]): AsyncRelation<Omit<T, K>>;
+    extend<E extends Record<string, unknown>>(e: TypedExtension<T, E>): AsyncRelation<T & E>;
+    constants<C extends Tuple>(consts: C): AsyncRelation<T & C>;
+    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>;
+    union(other: AsyncRelationOperand<T>): AsyncRelation<T>;
+    minus(other: AsyncRelationOperand<T>): AsyncRelation<T>;
+    intersect(other: AsyncRelationOperand<T>): AsyncRelation<T>;
+    matching<U>(other: AsyncRelationOperand<U>, keys?: JoinKeys): AsyncRelation<T>;
+    not_matching<U>(other: AsyncRelationOperand<U>, keys?: JoinKeys): AsyncRelation<T>;
+    join<U>(other: AsyncRelationOperand<U>, keys?: JoinKeys): AsyncRelation<T & U>;
+    left_join<U>(other: AsyncRelationOperand<U>, keys?: JoinKeys): AsyncRelation<T & Partial<U>>;
+    cross_product<U>(other: AsyncRelationOperand<U>): AsyncRelation<T & U>;
+    cross_join<U>(other: AsyncRelationOperand<U>): AsyncRelation<T & U>;
+    group<K extends keyof T>(attrs: K[], as: string): AsyncRelation<Omit<T, K> & Record<string, Relation<Pick<T, K>>>>;
+    ungroup(attr: string): AsyncRelation<Tuple>;
+    wrap<K extends keyof T>(attrs: K[], as: string): AsyncRelation<Omit<T, K> & Record<string, Pick<T, K>>>;
+    unwrap(attr: string): AsyncRelation<Tuple>;
+    image<U>(other: AsyncRelationOperand<U>, as: string, 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>;
+    one(): Promise<T>;
+    toArray(): Promise<T[]>;
+    toRelation(): Promise<Relation<T>>;
+    yByX(y: string, x: string): Promise<Tuple>;
+    toText(options?: TextOptions): Promise<string>;
+    [Symbol.asyncIterator](): AsyncIterator<T>;
+}

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

@@ -0,0 +1,25 @@
+import { BaseAsyncRelation } from './Base';
+import type { AsyncRelation, AsyncRelationOperand } from '../types';
+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 declare function AsyncBmg<T>(source: AsyncIterable<T>): AsyncRelation<T>;
+export declare namespace AsyncBmg {
+    var isEqual: <T, U>(left: AsyncRelationOperand<T>, right: AsyncRelationOperand<U>) => Promise<boolean>;
+}

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

@@ -0,0 +1,16 @@
+import type { AsyncRelationOperand, AsyncOperationalOperand, AsyncRelation } from '../types';
+/**
+ * Type guard to check if a value implements AsyncRelation.
+ */
+export declare const isAsyncRelation: <T>(value: unknown) => value is AsyncRelation<T>;
+/**
+ * Converts an AsyncRelationOperand to an AsyncOperationalOperand
+ * that provides a uniform interface for async iteration and output.
+ */
+export declare const toAsyncOperationalOperand: <T>(operand: AsyncRelationOperand<T>) => AsyncOperationalOperand<T>;
+/**
+ * Async generator that removes duplicate tuples.
+ * Uses tupleKey() for equality comparison.
+ */
+export declare function deduplicateAsync<T>(source: AsyncIterable<T>): AsyncGenerator<T>;
+export declare const error: (msg: string) => never;

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

@@ -0,0 +1,7 @@
+import type { AsyncRelationOperand } from '../types';
+import type { AutowrapOptions, Tuple } from '../../types';
+/**
+ * Automatically wraps attributes based on naming convention.
+ * Attributes with separator (default '_') are grouped into nested objects.
+ */
+export declare function autowrap<T>(operand: AsyncRelationOperand<T>, options?: AutowrapOptions): AsyncIterable<Tuple>;

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

@@ -0,0 +1,6 @@
+import type { AsyncRelationOperand } from '../types';
+import type { Tuple } from '../../types';
+/**
+ * Adds constant attributes to each tuple.
+ */
+export declare const constants: <T>(operand: AsyncRelationOperand<T>, consts: Tuple) => AsyncIterable<Tuple>;

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

@@ -0,0 +1,9 @@
+import type { AsyncRelationOperand } from '../types';
+import type { Tuple } from '../../types';
+/**
+ * Cartesian product: combines every left tuple with every right tuple.
+ * Left attributes override right on clash. Removes duplicates.
+ * Materializes both sides.
+ */
+export declare function cross_product<T, U>(left: AsyncRelationOperand<T>, right: AsyncRelationOperand<U>): AsyncIterable<Tuple>;
+export { cross_product as cross_join };

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

@@ -0,0 +1,7 @@
+import type { AsyncRelationOperand } from '../types';
+import type { Extension, Tuple } from '../../types';
+/**
+ * Extends each tuple with new attributes.
+ * Extension can be functions (computed) or attribute names (copied).
+ */
+export declare const extend: <T>(operand: AsyncRelationOperand<T>, extension: Extension) => AsyncIterable<Tuple>;

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

@@ -0,0 +1,7 @@
+import type { AsyncRelationOperand } from '../types';
+import type { AttrName, Tuple } from '../../types';
+/**
+ * Groups specified attributes into a nested relation.
+ * Materializes all tuples to perform grouping.
+ */
+export declare function group<T>(operand: AsyncRelationOperand<T>, attrs: AttrName[], as: AttrName): AsyncIterable<Tuple>;

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

@@ -0,0 +1,8 @@
+import type { AsyncRelationOperand } from '../types';
+import type { JoinKeys, Tuple, AttrName } from '../../types';
+/**
+ * Adds a relation-valued attribute with matching tuples from right.
+ * Each left tuple gets a nested relation of matching right tuples.
+ * Materializes both sides.
+ */
+export declare function image<T, U>(left: AsyncRelationOperand<T>, right: AsyncRelationOperand<U>, as: AttrName, keys?: JoinKeys): AsyncIterable<Tuple>;

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

@@ -0,0 +1,28 @@
+export { restrict, where, exclude } from './restrict';
+export { project, allbut } from './project';
+export { extend } from './extend';
+export { constants } from './constants';
+export { rename } from './rename';
+export { prefix } from './prefix';
+export { suffix } from './suffix';
+export { transform } from './transform';
+export { union } from './union';
+export { minus } from './minus';
+export { intersect } from './intersect';
+export { matching } from './matching';
+export { not_matching } from './not_matching';
+export { join } from './join';
+export { left_join } from './left_join';
+export { cross_product, cross_join } from './cross_product';
+export { group } from './group';
+export { ungroup } from './ungroup';
+export { wrap } from './wrap';
+export { unwrap } from './unwrap';
+export { image } from './image';
+export { summarize } from './summarize';
+export { autowrap } from './autowrap';
+export { yByX } from './yByX';
+export { isEqual } from './isEqual';
+export { one } from './one';
+export { toArray } from './toArray';
+export { isAsyncRelation, toAsyncOperationalOperand, deduplicateAsync } from './_helpers';

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

@@ -0,0 +1,7 @@
+import type { AsyncRelationOperand } from '../types';
+import type { Tuple } from '../../types';
+/**
+ * Set intersection: returns tuples present in both relations.
+ * Materializes right side first, then streams left.
+ */
+export declare function intersect<T>(left: AsyncRelationOperand<T>, right: AsyncRelationOperand<T>): AsyncIterable<Tuple>;

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

@@ -0,0 +1,7 @@
+import type { AsyncRelationOperand } from '../types';
+/**
+ * Compares two async relations for equality.
+ * Two relations are equal if they contain the exact same set of tuples.
+ * Terminal operation - returns a Promise.
+ */
+export declare const isEqual: <T, U>(left: AsyncRelationOperand<T>, right: AsyncRelationOperand<U>) => Promise<boolean>;

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

@@ -0,0 +1,7 @@
+import type { AsyncRelationOperand } from '../types';
+import type { JoinKeys, Tuple } from '../../types';
+/**
+ * Natural join: combines tuples from left and right where join keys match.
+ * Materializes both sides (needed for key detection and nested loop join).
+ */
+export declare function join<T, U>(left: AsyncRelationOperand<T>, right: AsyncRelationOperand<U>, keys?: JoinKeys): AsyncIterable<Tuple>;

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

@@ -0,0 +1,8 @@
+import type { AsyncRelationOperand } from '../types';
+import type { JoinKeys, Tuple } from '../../types';
+/**
+ * Left outer join: combines tuples, keeping all left tuples.
+ * Non-matching left tuples have null for right attributes.
+ * Materializes both sides.
+ */
+export declare function left_join<T, U>(left: AsyncRelationOperand<T>, right: AsyncRelationOperand<U>, keys?: JoinKeys): AsyncIterable<Tuple>;

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

@@ -0,0 +1,7 @@
+import type { AsyncRelationOperand } from '../types';
+import type { JoinKeys, Tuple } from '../../types';
+/**
+ * Semi-join: returns tuples from left that have a matching tuple in right.
+ * Materializes right side first to build key set.
+ */
+export declare function matching<T, U>(left: AsyncRelationOperand<T>, right: AsyncRelationOperand<U>, keys?: JoinKeys): AsyncIterable<Tuple>;

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

@@ -0,0 +1,7 @@
+import type { AsyncRelationOperand } from '../types';
+import type { Tuple } from '../../types';
+/**
+ * Set difference: returns tuples in left but not in right.
+ * Materializes right side first, then streams left.
+ */
+export declare function minus<T>(left: AsyncRelationOperand<T>, right: AsyncRelationOperand<T>): AsyncIterable<Tuple>;

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

@@ -0,0 +1,7 @@
+import type { AsyncRelationOperand } from '../types';
+import type { JoinKeys, Tuple } from '../../types';
+/**
+ * Anti semi-join: returns tuples from left that have no matching tuple in right.
+ * Materializes right side first to build key set.
+ */
+export declare function not_matching<T, U>(left: AsyncRelationOperand<T>, right: AsyncRelationOperand<U>, keys?: JoinKeys): AsyncIterable<Tuple>;

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

@@ -0,0 +1,6 @@
+import type { AsyncRelationOperand } from '../types';
+/**
+ * Returns the single tuple from the relation.
+ * Throws if the relation is empty or has more than one tuple.
+ */
+export declare const one: <T>(operand: AsyncRelationOperand<T>) => Promise<T>;

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

@@ -0,0 +1,6 @@
+import type { AsyncRelationOperand } from '../types';
+import type { PrefixOptions, Tuple } from '../../types';
+/**
+ * Prefixes all attribute names (except those in options.except).
+ */
+export declare const prefix: <T>(operand: AsyncRelationOperand<T>, pfx: string, options?: PrefixOptions) => AsyncIterable<Tuple>;

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

@@ -0,0 +1,10 @@
+import type { AsyncRelationOperand } from '../types';
+import type { Tuple, AttrName } from '../../types';
+/**
+ * Projects tuples to specified attributes with deduplication.
+ */
+export declare const project: <T>(operand: AsyncRelationOperand<T>, attrs: AttrName[]) => AsyncIterable<Tuple>;
+/**
+ * Projects out (removes) specified attributes with deduplication.
+ */
+export declare const allbut: <T>(operand: AsyncRelationOperand<T>, attrs: AttrName[]) => AsyncIterable<Tuple>;

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

@@ -0,0 +1,6 @@
+import type { AsyncRelationOperand } from '../types';
+import type { Renaming, Tuple } from '../../types';
+/**
+ * Renames attributes in each tuple.
+ */
+export declare const rename: <T>(operand: AsyncRelationOperand<T>, renaming: Renaming) => AsyncIterable<Tuple>;

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

@@ -0,0 +1,14 @@
+import type { AsyncRelationOperand } from '../types';
+import type { Predicate } from '../../types';
+/**
+ * Filters tuples that match the predicate.
+ */
+export declare const restrict: <T>(operand: AsyncRelationOperand<T>, p: Predicate) => AsyncIterable<T>;
+/**
+ * Alias for restrict.
+ */
+export declare const where: <T>(operand: AsyncRelationOperand<T>, p: Predicate) => AsyncIterable<T>;
+/**
+ * Filters tuples that do NOT match the predicate.
+ */
+export declare const exclude: <T>(operand: AsyncRelationOperand<T>, p: Predicate) => AsyncIterable<T>;

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

@@ -0,0 +1,6 @@
+import type { AsyncRelationOperand } from '../types';
+import type { SuffixOptions, Tuple } from '../../types';
+/**
+ * Suffixes all attribute names (except those in options.except).
+ */
+export declare const suffix: <T>(operand: AsyncRelationOperand<T>, sfx: string, options?: SuffixOptions) => AsyncIterable<Tuple>;

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

@@ -0,0 +1,8 @@
+import type { AsyncRelationOperand } from '../types';
+import type { AttrName, Tuple, Aggregators } from '../../types';
+/**
+ * Aggregates tuples by grouping attributes.
+ * Supports count, sum, min, max, avg, collect, and custom functions.
+ * Materializes all tuples to perform grouping.
+ */
+export declare function summarize<T>(operand: AsyncRelationOperand<T>, by: AttrName[], aggs: Aggregators): AsyncIterable<Tuple>;

package/dist/async/operators/toArray.d.ts

@@ -0,0 +1,5 @@
+import type { AsyncRelationOperand } from '../types';
+/**
+ * Collects all tuples from the async relation into an array.
+ */
+export declare const toArray: <T>(operand: AsyncRelationOperand<T>) => Promise<T[]>;

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

@@ -0,0 +1,9 @@
+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 declare function transform<T>(operand: AsyncRelationOperand<T>, transformation: Transformation): AsyncIterable<Tuple>;

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

@@ -0,0 +1,7 @@
+import type { AsyncRelationOperand } from '../types';
+import type { AttrName, Tuple } from '../../types';
+/**
+ * Flattens a nested relation attribute back into parent tuples.
+ * Materializes all tuples to perform ungrouping.
+ */
+export declare function ungroup<T>(operand: AsyncRelationOperand<T>, attr: AttrName): AsyncIterable<Tuple>;

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

@@ -0,0 +1,6 @@
+import type { AsyncRelationOperand } from '../types';
+import type { Tuple } from '../../types';
+/**
+ * Combines tuples from two relations, removing duplicates.
+ */
+export declare function union<T>(left: AsyncRelationOperand<T>, right: AsyncRelationOperand<T>): AsyncIterable<Tuple>;

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

@@ -0,0 +1,6 @@
+import type { AsyncRelationOperand } from '../types';
+import type { AttrName, Tuple } from '../../types';
+/**
+ * Unwraps a nested object attribute back into the parent tuple.
+ */
+export declare function unwrap<T>(operand: AsyncRelationOperand<T>, attr: AttrName): AsyncIterable<Tuple>;

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

@@ -0,0 +1,6 @@
+import type { AsyncRelationOperand } from '../types';
+import type { AttrName, Tuple } from '../../types';
+/**
+ * Wraps specified attributes into a nested object.
+ */
+export declare function wrap<T>(operand: AsyncRelationOperand<T>, attrs: AttrName[], as: AttrName): AsyncIterable<Tuple>;

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

@@ -0,0 +1,7 @@
+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 declare const yByX: <T>(operand: AsyncRelationOperand<T>, y: AttrName, x: AttrName) => Promise<Tuple>;

package/dist/async/types.d.ts

@@ -0,0 +1,58 @@
+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> {
+    restrict(p: TypedPredicate<T>): AsyncRelation<T>;
+    where(p: TypedPredicate<T>): AsyncRelation<T>;
+    exclude(p: TypedPredicate<T>): AsyncRelation<T>;
+    project<K extends keyof T>(attrs: K[]): AsyncRelation<Pick<T, K>>;
+    allbut<K extends keyof T>(attrs: K[]): AsyncRelation<Omit<T, K>>;
+    extend<E extends Record<string, unknown>>(e: TypedExtension<T, E>): AsyncRelation<T & E>;
+    constants<C extends Tuple>(consts: C): AsyncRelation<T & C>;
+    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>;
+    union(other: AsyncRelationOperand<T>): AsyncRelation<T>;
+    minus(other: AsyncRelationOperand<T>): AsyncRelation<T>;
+    intersect(other: AsyncRelationOperand<T>): AsyncRelation<T>;
+    matching<U = Tuple>(other: AsyncRelationOperand<U>, keys?: JoinKeys): AsyncRelation<T>;
+    not_matching<U = Tuple>(other: AsyncRelationOperand<U>, keys?: JoinKeys): AsyncRelation<T>;
+    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>;
+    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>;
+    one(): Promise<T>;
+    toArray(): Promise<T[]>;
+    toRelation(): Promise<Relation<T>>;
+    yByX(y: AttrName, x: AttrName): Promise<Tuple>;
+    toText(options?: TextOptions): Promise<string>;
+    [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/dist/async-operators/_helpers.d.ts

@@ -0,0 +1,16 @@
+import type { AsyncRelationOperand, AsyncOperationalOperand, AsyncRelation } from '../async-types';
+/**
+ * Type guard to check if a value implements AsyncRelation.
+ */
+export declare const isAsyncRelation: <T>(value: unknown) => value is AsyncRelation<T>;
+/**
+ * Converts an AsyncRelationOperand to an AsyncOperationalOperand
+ * that provides a uniform interface for async iteration and output.
+ */
+export declare const toAsyncOperationalOperand: <T>(operand: AsyncRelationOperand<T>) => AsyncOperationalOperand<T>;
+/**
+ * Async generator that removes duplicate tuples.
+ * Uses tupleKey() for equality comparison.
+ */
+export declare function deduplicateAsync<T>(source: AsyncIterable<T>): AsyncGenerator<T>;
+export declare const error: (msg: string) => never;

package/dist/async-operators/autowrap.d.ts

@@ -0,0 +1,7 @@
+import type { AsyncRelationOperand } from '../async-types';
+import type { AutowrapOptions, Tuple } from '../types';
+/**
+ * Automatically wraps attributes based on naming convention.
+ * Attributes with separator (default '_') are grouped into nested objects.
+ */
+export declare function autowrap<T>(operand: AsyncRelationOperand<T>, options?: AutowrapOptions): AsyncIterable<Tuple>;

package/dist/async-operators/constants.d.ts

@@ -0,0 +1,6 @@
+import type { AsyncRelationOperand } from '../async-types';
+import type { Tuple } from '../types';
+/**
+ * Adds constant attributes to each tuple.
+ */
+export declare const constants: <T>(operand: AsyncRelationOperand<T>, consts: Tuple) => AsyncIterable<Tuple>;

package/dist/async-operators/cross_product.d.ts

@@ -0,0 +1,9 @@
+import type { AsyncRelationOperand } from '../async-types';
+import type { Tuple } from '../types';
+/**
+ * Cartesian product: combines every left tuple with every right tuple.
+ * Left attributes override right on clash. Removes duplicates.
+ * Materializes both sides.
+ */
+export declare function cross_product<T, U>(left: AsyncRelationOperand<T>, right: AsyncRelationOperand<U>): AsyncIterable<Tuple>;
+export { cross_product as cross_join };

package/dist/async-operators/extend.d.ts

@@ -0,0 +1,7 @@
+import type { AsyncRelationOperand } from '../async-types';
+import type { Extension, Tuple } from '../types';
+/**
+ * Extends each tuple with new attributes.
+ * Extension can be functions (computed) or attribute names (copied).
+ */
+export declare const extend: <T>(operand: AsyncRelationOperand<T>, extension: Extension) => AsyncIterable<Tuple>;

package/dist/async-operators/group.d.ts

@@ -0,0 +1,7 @@
+import type { AsyncRelationOperand } from '../async-types';
+import type { AttrName, Tuple } from '../types';
+/**
+ * Groups specified attributes into a nested relation.
+ * Materializes all tuples to perform grouping.
+ */
+export declare function group<T>(operand: AsyncRelationOperand<T>, attrs: AttrName[], as: AttrName): AsyncIterable<Tuple>;

package/dist/async-operators/image.d.ts

@@ -0,0 +1,8 @@
+import type { AsyncRelationOperand } from '../async-types';
+import type { JoinKeys, Tuple, AttrName } from '../types';
+/**
+ * Adds a relation-valued attribute with matching tuples from right.
+ * Each left tuple gets a nested relation of matching right tuples.
+ * Materializes both sides.
+ */
+export declare function image<T, U>(left: AsyncRelationOperand<T>, right: AsyncRelationOperand<U>, as: AttrName, keys?: JoinKeys): AsyncIterable<Tuple>;