@enspirit/bmg-js 1.0.2 → 1.1.0

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
 }
 
 // ============================================================================

package/src/writer/Text.ts

@@ -0,0 +1,305 @@
+import { Relation, Tuple } from '../types';
+import { isRelation } from '../sync/operators/isRelation';
+
+/**
+ * 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;
+}
+
+// Type guards
+const isTupleLike = (t: unknown): t is Tuple =>
+  t !== null && typeof t === 'object' && !Array.isArray(t);
+
+const isRelationLike = (r: unknown): r is Relation | Tuple[] =>
+  isRelation(r) || (Array.isArray(r) && r.every(isTupleLike));
+
+/**
+ * Utility function to get max of two nullable numbers
+ */
+const max = (x: number | null, y: number | null): number => {
+  if (x === null) return y ?? 0;
+  if (y === null) return x;
+  return x > y ? x : y;
+};
+
+/**
+ * Represents a single cell in the table
+ */
+class Cell {
+  private value: unknown;
+  private renderer: TextWriter;
+  private _textRendering: string | null = null;
+  private _minWidth: number | null = null;
+
+  constructor(renderer: TextWriter, value: unknown) {
+    this.renderer = renderer;
+    this.value = value;
+  }
+
+  get minWidth(): number {
+    if (this._minWidth === null) {
+      this._minWidth = this.renderingLines().reduce(
+        (maxLen, line) => max(maxLen, line.length),
+        0
+      );
+    }
+    return this._minWidth;
+  }
+
+  renderingLines(size?: number): string[] {
+    if (size === undefined) {
+      return this.textRendering.split('\n');
+    } else if (typeof this.value === 'number') {
+      // Right-align numbers
+      return this.renderingLines().map(l => l.padStart(size));
+    } else {
+      // Left-align other values
+      return this.renderingLines().map(l => l.padEnd(size));
+    }
+  }
+
+  get textRendering(): string {
+    if (this._textRendering === null) {
+      this._textRendering = this.computeTextRendering();
+    }
+    return this._textRendering;
+  }
+
+  private computeTextRendering(): string {
+    const value = this.value;
+
+    if (value === null) {
+      return '[null]';
+    }
+    if (value === undefined) {
+      return '[undefined]';
+    }
+    if (typeof value === 'symbol') {
+      return value.toString();
+    }
+    if (typeof value === 'number') {
+      if (Number.isInteger(value)) {
+        return String(value);
+      }
+      const precision = this.renderer.options.floatPrecision ?? 3;
+      return value.toFixed(precision);
+    }
+    if (isRelationLike(value)) {
+      return this.renderer.render(value, '');
+    }
+    if (Array.isArray(value)) {
+      return this.arrayRendering(value);
+    }
+    if (value instanceof Date) {
+      return value.toISOString();
+    }
+    if (typeof value === 'object') {
+      return JSON.stringify(value);
+    }
+    return String(value);
+  }
+
+  private arrayRendering(value: unknown[]): string {
+    if (value.length > 0 && isTupleLike(value[0])) {
+      return this.renderer.render(value as Tuple[], '');
+    }
+    if (value.length === 0) {
+      return '[]';
+    }
+    const values = value.map(x => {
+      const cell = new Cell(this.renderer, x);
+      return cell.textRendering;
+    });
+    const totalLength = values.reduce((sum, s) => sum + s.length, 0);
+    if (totalLength < 20) {
+      return '[' + values.join(', ') + ']';
+    } else {
+      return '[' + values.join(',\n ') + ']';
+    }
+  }
+}
+
+/**
+ * Represents a row of cells in the table
+ */
+class Row {
+  private cells: Cell[];
+
+  constructor(renderer: TextWriter, values: unknown[]) {
+    this.cells = values.map(v => new Cell(renderer, v));
+  }
+
+  minWidths(): number[] {
+    return this.cells.map(cell => cell.minWidth);
+  }
+
+  renderingLines(sizes: number[]): string[] {
+    let nbLines = 0;
+    const byCell = this.cells.map((cell, i) => {
+      const lines = cell.renderingLines(sizes[i]);
+      nbLines = max(nbLines, lines.length);
+      return lines;
+    });
+
+    const grid: string[] = [];
+    for (let lineI = 0; lineI < nbLines; lineI++) {
+      const lineContent = byCell
+        .map((cellLines, i) => cellLines[lineI] ?? ' '.repeat(sizes[i]))
+        .join(' | ');
+      grid.push('| ' + lineContent + ' |');
+    }
+
+    return grid.length === 0 ? ['|  |'] : grid;
+  }
+}
+
+/**
+ * Represents the entire table structure
+ */
+class Table {
+  private renderer: TextWriter;
+  private header: Row;
+  private rows: Row[];
+  private _sizes: number[] | null = null;
+  private _sep: string | null = null;
+
+  constructor(renderer: TextWriter, records: unknown[][], attributes: string[]) {
+    this.renderer = renderer;
+    this.header = new Row(renderer, attributes);
+    this.rows = records.map(r => new Row(renderer, r));
+  }
+
+  get sizes(): number[] {
+    if (this._sizes === null) {
+      const headerWidths = this.header.minWidths();
+      this._sizes = this.rows.reduce((memo, row) => {
+        const rowWidths = row.minWidths();
+        return memo.map((w, i) => max(w, rowWidths[i] ?? 0));
+      }, headerWidths);
+    }
+    return this._sizes;
+  }
+
+  get sep(): string {
+    if (this._sep === null) {
+      this._sep = '+-' + this.sizes.map(s => '-'.repeat(s)).join('-+-') + '-+';
+    }
+    return this._sep;
+  }
+
+  *eachLine(): Generator<string> {
+    const trimAt = this.renderer.options.trimAt;
+
+    if (trimAt !== undefined) {
+      for (const line of this.eachLineRaw()) {
+        yield line.substring(0, trimAt);
+      }
+    } else {
+      yield* this.eachLineRaw();
+    }
+  }
+
+  private *eachLineRaw(): Generator<string> {
+    yield this.sep;
+    yield this.header.renderingLines(this.sizes)[0];
+    yield this.sep;
+    for (const row of this.rows) {
+      for (const line of row.renderingLines(this.sizes)) {
+        yield line;
+      }
+    }
+    yield this.sep;
+  }
+
+  *[Symbol.iterator](): Generator<string> {
+    for (const line of this.eachLine()) {
+      yield line.trimEnd() + '\n';
+    }
+  }
+
+  toString(): string {
+    let result = '';
+    for (const line of this) {
+      result += line;
+    }
+    return result;
+  }
+}
+
+/**
+ * Text writer for rendering relations as ASCII tables
+ */
+export class TextWriter {
+  readonly options: TextOptions;
+
+  constructor(options: TextOptions = {}) {
+    this.options = options;
+  }
+
+  /**
+   * Renders a relation or tuple array to an ASCII table string
+   */
+  render(input: Relation | Tuple[] | Tuple, output: string = ''): string {
+    for (const line of this.eachLine(input)) {
+      output += line;
+    }
+    return output;
+  }
+
+  *eachLine(input: Relation | Tuple[] | Tuple): Generator<string> {
+    // Handle single tuple
+    let tuples: Tuple[];
+    if (isTupleLike(input) && !isRelation(input)) {
+      tuples = [input];
+    } else if (isRelation(input)) {
+      tuples = input.toArray();
+    } else {
+      tuples = input;
+    }
+
+    // Collect all attribute names across all tuples
+    const attrs = tuples.reduce((memo: string[], tuple) => {
+      for (const key of Object.keys(tuple)) {
+        if (!memo.includes(key)) {
+          memo.push(key);
+        }
+      }
+      return memo;
+    }, []);
+
+    // Build records array (values in attribute order)
+    const records = tuples.map(t => attrs.map(a => t[a]));
+
+    const table = new Table(this, records, attrs);
+    yield* table;
+  }
+}
+
+/**
+ * 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 const toText = (
+  operand: Relation | Tuple[] | Tuple,
+  options: TextOptions = {}
+): string => {
+  return new TextWriter(options).render(operand);
+};

package/src/writer/index.ts

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

package/src/operators/isRelation.ts

@@ -1,5 +0,0 @@
-import { MemoryRelation } from "@/Relation";
-
-export const isRelation = (op) => {
-  return op != null && op.constructor === MemoryRelation;
-}