@enspirit/bmg-js 1.0.2 → 1.1.1

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,11 @@
-export * from './operators';
+export * from './sync/operators';
 export * from './types';
 export { LIB_DEFINITIONS } from './lib-definitions';
+export { toText } from './writer';
+export type { TextOptions, BorderStyleName } 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 +31,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';

package/src/{Relation → sync/Relation}/Memory.ts

@@ -34,6 +34,7 @@ import type {
   AutowrapOptions,
   Relation,
   RelationOperand,
+  TextOptions,
   Transformation,
   Tuple,
   TypedPredicate,
@@ -50,7 +51,8 @@ import type {
   AggregatorResults,
   TypedJoinKeysArray,
   TypedJoinKeysObject,
-} from "../types";
+} from "../../types";
+import { toText } from "../../writer";
 
 /**
  * In-memory implementation of the Relation interface.
@@ -211,4 +213,10 @@ export class MemoryRelation<T = Tuple> implements Relation<T> {
     return isEqual(this as any, right as any);
   }
 
+  // === Display ===
+
+  toText(options?: TextOptions): string {
+    return toText(this as any, options);
+  }
+
 }

package/src/sync/Relation/index.ts

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

package/src/{operators → sync/operators}/_helpers.ts

@@ -1,5 +1,5 @@
 import { OperationalOperand, Relation, RelationOperand, Renaming, RenamingFunc, Tuple, JoinKeys, AttrName } from "@/types";
-import { MemoryRelation } from '@/Relation';
+import { MemoryRelation } from '@/sync/Relation';
 import { isRelation } from "./isRelation";
 
 const valueKey = (value: unknown): unknown => {

package/src/{operators → sync/operators}/allbut.ts

@@ -1,4 +1,4 @@
-import { RelationOperand, AttrName, Tuple } from "../types";
+import { RelationOperand, AttrName, Tuple } from "../../types";
 import { toOperationalOperand, deduplicate } from "./_helpers";
 
 export const allbut = (operand: RelationOperand, attrs: AttrName[]): RelationOperand => {

package/src/{operators → sync/operators}/autowrap.ts

@@ -1,4 +1,4 @@
-import { AutowrapOptions, RelationOperand, Tuple } from "../types";
+import { AutowrapOptions, RelationOperand, Tuple } from "../../types";
 import { toOperationalOperand } from "./_helpers";
 
 export const autowrap = (operand: RelationOperand, options?: AutowrapOptions): RelationOperand => {

package/src/{operators → sync/operators}/constants.ts

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

package/src/{operators → sync/operators}/cross_product.ts

@@ -1,4 +1,4 @@
-import { RelationOperand, Tuple } from "../types";
+import { RelationOperand, Tuple } from "../../types";
 import { toOperationalOperand, deduplicate } from "./_helpers";
 
 export const cross_product = (left: RelationOperand, right: RelationOperand): RelationOperand => {

package/src/{operators → sync/operators}/exclude.ts

@@ -1,5 +1,5 @@
-import { toPredicateFunc } from "../support/toPredicateFunc";
-import { RelationOperand, Predicate, Tuple } from "../types";
+import { toPredicateFunc } from "../../support/toPredicateFunc";
+import { RelationOperand, Predicate, Tuple } from "../../types";
 import { toOperationalOperand } from "./_helpers";
 
 export const exclude = (operand: RelationOperand, p: Predicate): RelationOperand => {

package/src/{operators → sync/operators}/extend.ts

@@ -1,4 +1,4 @@
-import { RelationOperand, Extension, Tuple } from "../types";
+import { RelationOperand, Extension, Tuple } from "../../types";
 import { toOperationalOperand } from "./_helpers";
 
 export const extend = (operand: RelationOperand, extension: Extension): RelationOperand => {

package/src/{operators → sync/operators}/group.ts

@@ -1,6 +1,6 @@
-import { RelationOperand, AttrName, Tuple } from "../types";
+import { RelationOperand, AttrName, Tuple } from "../../types";
 import { toOperationalOperand } from "./_helpers";
-import { MemoryRelation } from "@/Relation";
+import { MemoryRelation } from "@/sync/Relation";
 
 const groupKey = (tuple: Tuple, byAttrs: AttrName[]): string => {
   const keyParts = byAttrs.map(attr => JSON.stringify(tuple[attr]));

package/src/{operators → sync/operators}/image.ts

@@ -1,6 +1,6 @@
-import { RelationOperand, JoinKeys, Tuple, AttrName } from "../types";
+import { RelationOperand, JoinKeys, Tuple, AttrName } from "../../types";
 import { toOperationalOperand, normalizeKeys, tuplesMatch, projectOutKeys } from "./_helpers";
-import { MemoryRelation } from "@/Relation";
+import { MemoryRelation } from "@/sync/Relation";
 
 export const image = (left: RelationOperand, right: RelationOperand, as: AttrName, keys?: JoinKeys): RelationOperand => {
   const opLeft = toOperationalOperand(left);

package/src/sync/operators/index.ts

@@ -0,0 +1,31 @@
+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/src/{operators → sync/operators}/intersect.ts

@@ -1,4 +1,4 @@
-import { RelationOperand, Tuple } from "../types";
+import { RelationOperand, Tuple } from "../../types";
 import { toOperationalOperand, tupleKey } from "./_helpers";
 
 export const intersect = (left: RelationOperand, right: RelationOperand): RelationOperand => {

package/src/{operators → sync/operators}/isEqual.ts

@@ -1,7 +1,6 @@
-import { RelationOperand } from "../types";
 import { toOperationalOperand, tupleKey } from "./_helpers";
 
-export const isEqual = (left: RelationOperand, right: RelationOperand): boolean => {
+export const isEqual = (left: any, right: any): boolean => {
   const opLeft = toOperationalOperand(left);
   const opRight = toOperationalOperand(right);
 

package/src/sync/operators/isRelation.ts

@@ -0,0 +1,6 @@
+import { MemoryRelation } from "@/sync/Relation";
+import { Relation } from "@/types";
+
+export const isRelation = (op: unknown): op is Relation => {
+  return op != null && (op as object).constructor === MemoryRelation;
+}

package/src/{operators → sync/operators}/join.ts

@@ -1,4 +1,4 @@
-import { RelationOperand, JoinKeys, Tuple, AttrName } from "../types";
+import { RelationOperand, JoinKeys, Tuple, AttrName } from "../../types";
 import { toOperationalOperand, normalizeKeys, tuplesMatch, projectOutKeys } from "./_helpers";
 
 const mergeTuples = (left: Tuple, right: Tuple, keyMap: Record<AttrName, AttrName>): Tuple => {

package/src/{operators → sync/operators}/left_join.ts

@@ -1,4 +1,4 @@
-import { RelationOperand, JoinKeys, Tuple, AttrName } from "../types";
+import { RelationOperand, JoinKeys, Tuple, AttrName } from "../../types";
 import { toOperationalOperand, normalizeKeys, tuplesMatch } from "./_helpers";
 
 const getRightAttrs = (rightTuples: Tuple[], keyMap: Record<AttrName, AttrName>): AttrName[] => {

package/src/{operators → sync/operators}/matching.ts

@@ -1,4 +1,4 @@
-import { RelationOperand, JoinKeys, Tuple } from "../types";
+import { RelationOperand, JoinKeys, Tuple } from "../../types";
 import { toOperationalOperand, normalizeKeys, matchKey } from "./_helpers";
 
 export const matching = (left: RelationOperand, right: RelationOperand, keys?: JoinKeys): RelationOperand => {

package/src/{operators → sync/operators}/minus.ts

@@ -1,4 +1,4 @@
-import { RelationOperand, Tuple } from "../types";
+import { RelationOperand, Tuple } from "../../types";
 import { toOperationalOperand, tupleKey } from "./_helpers";
 
 export const minus = (left: RelationOperand, right: RelationOperand): RelationOperand => {

package/src/{operators → sync/operators}/not_matching.ts

@@ -1,4 +1,4 @@
-import { RelationOperand, JoinKeys, Tuple } from "../types";
+import { RelationOperand, JoinKeys, Tuple } from "../../types";
 import { toOperationalOperand, normalizeKeys, matchKey } from "./_helpers";
 
 export const not_matching = (left: RelationOperand, right: RelationOperand, keys?: JoinKeys): RelationOperand => {

package/src/{operators → sync/operators}/one.ts

@@ -1,4 +1,4 @@
-import { RelationOperand, Tuple } from "../types";
+import { RelationOperand, Tuple } from "../../types";
 import { toOperationalOperand, error } from "./_helpers";
 
 export const one = (operand: RelationOperand): Tuple => {

package/src/{operators → sync/operators}/prefix.ts

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

package/src/{operators → sync/operators}/project.ts

@@ -1,4 +1,4 @@
-import { RelationOperand, AttrName, Tuple } from "../types";
+import { RelationOperand, AttrName, Tuple } from "../../types";
 import { toOperationalOperand, deduplicate } from "./_helpers";
 
 export const project = (operand: RelationOperand, attrs: AttrName[]): RelationOperand => {

package/src/{operators → sync/operators}/rename.ts

@@ -1,4 +1,4 @@
-import { RelationOperand, Renaming, Tuple } from "../types";
+import { RelationOperand, Renaming, Tuple } from "../../types";
 import { toOperationalOperand, toRenamingFunc } from "./_helpers";
 
 export const rename = (operand: RelationOperand, renaming: Renaming): RelationOperand => {

package/src/{operators → sync/operators}/restrict.ts

@@ -1,5 +1,5 @@
-import { toPredicateFunc } from "../support/toPredicateFunc";
-import { RelationOperand, Predicate, Tuple } from "../types";
+import { toPredicateFunc } from "../../support/toPredicateFunc";
+import { RelationOperand, Predicate, Tuple } from "../../types";
 import { toOperationalOperand } from "./_helpers";
 
 export const restrict = (operand: RelationOperand, p: Predicate): RelationOperand => {

package/src/{operators → sync/operators}/suffix.ts

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

package/src/{operators → sync/operators}/summarize.ts

@@ -1,4 +1,4 @@
-import { RelationOperand, AttrName, Tuple, Aggregator, Aggregators } from "../types";
+import { RelationOperand, AttrName, Tuple, Aggregator, Aggregators } from "../../types";
 import { toOperationalOperand } from "./_helpers";
 
 const groupKey = (tuple: Tuple, by: AttrName[]): string => {

package/src/{operators → sync/operators}/transform.ts

@@ -1,4 +1,4 @@
-import { RelationOperand, Transformation, Tuple } from "../types";
+import { RelationOperand, Transformation, Tuple } from "../../types";
 import { toOperationalOperand } from "./_helpers";
 
 export const transform = (operand: RelationOperand, transformation: Transformation): RelationOperand => {

package/src/{operators → sync/operators}/ungroup.ts

@@ -1,4 +1,4 @@
-import { RelationOperand, AttrName, Tuple, Relation } from "../types";
+import { RelationOperand, AttrName, Tuple, Relation } from "../../types";
 import { toOperationalOperand } from "./_helpers";
 import { isRelation } from "./isRelation";
 

package/src/{operators → sync/operators}/union.ts

@@ -1,4 +1,4 @@
-import { RelationOperand, Tuple } from "../types";
+import { RelationOperand, Tuple } from "../../types";
 import { toOperationalOperand, tupleKey } from "./_helpers";
 
 export const union = (left: RelationOperand, right: RelationOperand): RelationOperand => {

package/src/{operators → sync/operators}/unwrap.ts

@@ -1,4 +1,4 @@
-import { RelationOperand, AttrName, Tuple } from "../types";
+import { RelationOperand, AttrName, Tuple } from "../../types";
 import { toOperationalOperand } from "./_helpers";
 
 export const unwrap = (operand: RelationOperand, attr: AttrName): RelationOperand => {

package/src/sync/operators/where.ts

@@ -0,0 +1 @@
+export { restrict as where } from './restrict';

package/src/{operators → sync/operators}/wrap.ts

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

package/src/{operators → sync/operators}/yByX.ts

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

package/src/types.ts

@@ -148,6 +148,13 @@ 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[]
 }
@@ -252,6 +259,10 @@ 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
+
+  // === Display ===
+
+  toText(options?: TextOptions): string
 }
 
 // ============================================================================