@enspirit/bmg-js 1.0.1 → 1.1.0

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/{dist/src/src/operators/where.d.ts → src/sync/operators/where.ts}

@@ -1 +1 @@
-export { restrict as where } from './restrict';
+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

@@ -1,36 +1,118 @@
-import type {
-  RenameMap, Renamed,
-  Prefixed, Suffixed,
-  Joined, LeftJoined,
-  Wrapped, Unwrapped,
-  AggregatorResults
-} 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.
+ */
+
+// ============================================================================
+// Base Types
+// ============================================================================
+
+/** 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>
+
+// ============================================================================
+// Rename Types
+// ============================================================================
+
+/** 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];
+};
 
 // ============================================================================
-// Group/Ungroup Types (defined here due to Relation dependency)
+// Prefix/Suffix Types
 // ============================================================================
 
+/** 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];
+};
+
+// ============================================================================
+// Join Types
+// ============================================================================
+
+/** 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 };
+
+// ============================================================================
+// Wrap/Unwrap Types
+// ============================================================================
+
+/** 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 AttrName = string
-export type Tuple = Record<AttrName, unknown>
+// ============================================================================
+// Aggregator Types
+// ============================================================================
 
-export interface PrefixOptions {
-  except?: 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 interface SuffixOptions {
-  except?: AttrName[]
-}
+/** 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;
 
-export interface AutowrapOptions {
-  separator?: string
-}
+/** Map aggregator definitions to their result types */
+export type AggregatorResults<Aggs extends Record<string, unknown>> = {
+  [K in keyof Aggs]: AggregatorResult<Aggs[K]>;
+};
 
 // ============================================================================
-// Typed Predicates
+// Predicate Types
 // ============================================================================
 
 /** Predicate function that receives a typed tuple */
@@ -39,8 +121,12 @@ 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>
 
+// Legacy predicate types (for backwards compatibility with standalone operators)
+export type PredicateFunc = ((t: Tuple) => any)
+export type Predicate = Tuple | PredicateFunc
+
 // ============================================================================
-// Typed Extensions
+// Extension Types
 // ============================================================================
 
 /** Extension function that receives a typed tuple */
@@ -51,8 +137,43 @@ 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>
+
 // ============================================================================
-// Generic Relation Interface
+// Other Helper Types
+// ============================================================================
+
+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
 // ============================================================================
 
 /**
@@ -102,19 +223,19 @@ export interface Relation<T = Tuple> {
 
   // === Semi-join operators (preserve left type) ===
 
-  matching<R>(right: RelationOperand<R>, keys?: JoinKeys): Relation<T>
-  not_matching<R>(right: RelationOperand<R>, keys?: JoinKeys): 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 operators ===
 
-  join<R>(right: RelationOperand<R>, keys?: JoinKeys): Relation<Joined<T, R>>
-  left_join<R>(right: RelationOperand<R>, keys?: JoinKeys): Relation<LeftJoined<T, R>>
+  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>
 
   // === Nesting operators ===
 
-  image<R, As extends string>(right: RelationOperand<R>, as: As, keys?: JoinKeys): Relation<T & Record<As, Relation<Omit<R, keyof T & keyof 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>>
@@ -138,10 +259,14 @@ 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
 }
 
 // ============================================================================
-// Operands and Helpers
+// Operands
 // ============================================================================
 
 export type RelationOperand<T = Tuple> = Relation<T> | T[]
@@ -150,29 +275,3 @@ export interface OperationalOperand<T = Tuple> {
   tuples(): Iterable<T>
   output(tuples: T[]): RelationOperand<T>
 }
-
-// Legacy predicate types (for backwards compatibility with standalone operators)
-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[]>
-
-// Re-export utility types for convenience
-export type { RenameMap, Renamed, Prefixed, Suffixed, Joined, LeftJoined, Wrapped, Unwrapped } from './utility-types';
-// Ungrouped is defined in this file (not utility-types) due to Relation dependency

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/dist/src/Relation.d.ts

@@ -1,8 +0,0 @@
-import { Predicate, Tuple } from "./types";
-export declare class Relation {
-    private tuples;
-    constructor(tuples: Tuple[]);
-    restrict(p: Predicate): Relation;
-    one(): Tuple;
-    toArray(): Tuple[];
-}

package/dist/src/index.d.ts

@@ -1,27 +0,0 @@
-export * from './operators';
-export * from './types';
-export * from './utility-types';
-import { MemoryRelation } from './Relation';
-/**
- * Creates a new in-memory relation from an array of tuples.
- *
- * @typeParam T - The tuple type. Inferred from input or explicitly provided.
- *
- * @example
- * // Untyped usage (backwards compatible)
- * const r = Bmg([{ id: 1, name: 'Alice' }]);
- *
- * @example
- * // Typed usage with explicit type parameter
- * interface Person { id: number; name: string }
- * const r = Bmg<Person>([{ id: 1, name: 'Alice' }]);
- * r.project(['id']);  // Autocomplete suggests 'id' | 'name'
- *
- * @example
- * // Type is inferred from input
- * const r = Bmg([{ id: 1, name: 'Alice' }] as const);
- */
-export declare function Bmg<T>(tuples: T[]): MemoryRelation<T>;
-export declare namespace Bmg {
-    var isRelation: (op: any) => boolean;
-}

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

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

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

@@ -1 +0,0 @@
-export declare const isRelation: (op: any) => boolean;

package/dist/src/src/index.d.ts

@@ -1,27 +0,0 @@
-export * from './operators';
-export * from './types';
-export * from './utility-types';
-import { MemoryRelation } from './Relation';
-/**
- * Creates a new in-memory relation from an array of tuples.
- *
- * @typeParam T - The tuple type. Inferred from input or explicitly provided.
- *
- * @example
- * // Untyped usage (backwards compatible)
- * const r = Bmg([{ id: 1, name: 'Alice' }]);
- *
- * @example
- * // Typed usage with explicit type parameter
- * interface Person { id: number; name: string }
- * const r = Bmg<Person>([{ id: 1, name: 'Alice' }]);
- * r.project(['id']);  // Autocomplete suggests 'id' | 'name'
- *
- * @example
- * // Type is inferred from input
- * const r = Bmg([{ id: 1, name: 'Alice' }] as const);
- */
-export declare function Bmg<T>(tuples: T[]): MemoryRelation<T>;
-export declare namespace Bmg {
-    var isRelation: (op: any) => boolean;
-}