@enspirit/bmg-js 1.0.2 → 1.1.1

package/dist/sync/Relation/Memory.d.ts

@@ -0,0 +1,46 @@
+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.
+ *
+ * @typeParam T - The tuple type for this relation. Defaults to `Tuple` (Record<string, unknown>).
+ */
+export declare class MemoryRelation<T = Tuple> implements Relation<T> {
+    private tuples;
+    constructor(tuples: T[]);
+    restrict(p: TypedPredicate<T>): Relation<T>;
+    where(p: TypedPredicate<T>): Relation<T>;
+    exclude(p: TypedPredicate<T>): Relation<T>;
+    project<K extends keyof T>(attrs: K[]): Relation<Pick<T, K>>;
+    allbut<K extends keyof T>(attrs: K[]): Relation<Omit<T, K>>;
+    extend<E extends Record<string, unknown>>(e: TypedExtension<T, E>): Relation<T & E>;
+    constants<C extends Tuple>(consts: C): Relation<T & C>;
+    rename<R extends RenameMap<T>>(r: R): Relation<Renamed<T, R>>;
+    prefix<P extends string, Ex extends keyof T = never>(pfx: P, options?: {
+        except?: Ex[];
+    }): Relation<Prefixed<T, P, Ex>>;
+    suffix<S extends string, Ex extends keyof T = never>(sfx: S, options?: {
+        except?: Ex[];
+    }): Relation<Suffixed<T, S, Ex>>;
+    union(right: RelationOperand<T>): Relation<T>;
+    minus(right: RelationOperand<T>): Relation<T>;
+    intersect(right: RelationOperand<T>): Relation<T>;
+    matching<R>(right: RelationOperand<R>, keys?: TypedJoinKeysArray<T, R> | TypedJoinKeysObject<T, R>): Relation<T>;
+    not_matching<R>(right: RelationOperand<R>, keys?: TypedJoinKeysArray<T, R> | TypedJoinKeysObject<T, R>): Relation<T>;
+    join<R>(right: RelationOperand<R>, keys?: TypedJoinKeysArray<T, R> | TypedJoinKeysObject<T, R>): Relation<Joined<T, R>>;
+    left_join<R>(right: RelationOperand<R>, keys?: TypedJoinKeysArray<T, R> | TypedJoinKeysObject<T, R>): Relation<LeftJoined<T, R>>;
+    cross_product<R>(right: RelationOperand<R>): Relation<T & R>;
+    cross_join<R>(right: RelationOperand<R>): Relation<T & R>;
+    image<R, As extends string>(right: RelationOperand<R>, as: As, keys?: TypedJoinKeysArray<T, R> | TypedJoinKeysObject<T, R>): Relation<T & Record<As, Relation<Omit<R, keyof T & keyof R>>>>;
+    group<K extends keyof T, As extends string>(attrs: K[], as: As): Relation<Omit<T, K> & Record<As, Relation<Pick<T, K>>>>;
+    ungroup<K extends keyof T>(attr: K): Relation<Ungrouped<T, K>>;
+    wrap<K extends keyof T, As extends string>(attrs: K[], as: As): Relation<Wrapped<T, K, As>>;
+    unwrap<K extends keyof T>(attr: K): Relation<Unwrapped<T, K>>;
+    summarize<By extends keyof T, Aggs extends Record<string, unknown>>(by: By[], aggs: Aggs): Relation<Pick<T, By> & AggregatorResults<Aggs>>;
+    transform(t: Transformation): Relation<T>;
+    autowrap(options?: AutowrapOptions): Relation<Tuple>;
+    one(): 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/sync/Relation/index.d.ts

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

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

@@ -0,0 +1,142 @@
+import { OperationalOperand, RelationOperand, Renaming, RenamingFunc, Tuple, JoinKeys, AttrName } from "@/types";
+/**
+ * Generates a unique string key for a tuple, used for equality comparison and deduplication.
+ * Handles nested relations by converting them to sorted tuple keys.
+ *
+ * @example
+ * tupleKey({ name: 'Alice', age: 30 })
+ * // => '[["age",30],["name","Alice"]]'
+ *
+ * @example
+ * tupleKey({ id: 1, items: Bmg([{ x: 1 }, { x: 2 }]) })
+ * // => '[["id",1],["items",[...]]]' (nested relation converted to sorted keys)
+ */
+export declare const tupleKey: (tuple: Tuple) => string;
+/**
+ * Removes duplicate tuples from an array, preserving order of first occurrence.
+ * Uses tupleKey() for equality comparison.
+ *
+ * @example
+ * deduplicate([
+ *   { id: 1, name: 'Alice' },
+ *   { id: 2, name: 'Bob' },
+ *   { id: 1, name: 'Alice' },  // duplicate
+ * ])
+ * // => [{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }]
+ */
+export declare const deduplicate: (tuples: Tuple[]) => Tuple[];
+/**
+ * Converts a RelationOperand (Relation or Tuple[]) to an OperationalOperand
+ * that provides a uniform interface for iteration and output.
+ *
+ * @example
+ * // With array input, output remains array
+ * const op = toOperationalOperand([{ id: 1 }]);
+ * [...op.tuples()];        // => [{ id: 1 }]
+ * op.output([{ id: 2 }]);  // => [{ id: 2 }]
+ *
+ * @example
+ * // With Relation input, output is a new Relation
+ * const op = toOperationalOperand(Bmg([{ id: 1 }]));
+ * [...op.tuples()];        // => [{ id: 1 }]
+ * op.output([{ id: 2 }]);  // => Bmg([{ id: 2 }])
+ */
+export declare const toOperationalOperand: (operand: RelationOperand) => OperationalOperand;
+/**
+ * Converts a Renaming (object or function) to a RenamingFunc.
+ *
+ * @example
+ * // Object renaming
+ * const fn = toRenamingFunc({ name: 'fullName', age: 'years' });
+ * fn('name');  // => 'fullName'
+ * fn('age');   // => 'years'
+ * fn('other'); // => 'other' (unchanged)
+ *
+ * @example
+ * // Function renaming (passed through)
+ * const fn = toRenamingFunc(attr => attr.toUpperCase());
+ * fn('name'); // => 'NAME'
+ */
+export declare const toRenamingFunc: (renaming: Renaming) => RenamingFunc;
+export declare const error: (msg: string) => never;
+/**
+ * Finds attribute names that exist in both left and right tuple arrays.
+ * Used for natural joins when no explicit keys are provided.
+ *
+ * @example
+ * const left = [{ id: 1, name: 'Alice', city: 'NYC' }];
+ * const right = [{ city: 'NYC', country: 'USA' }];
+ * getCommonAttrs(left, right);
+ * // => ['city']
+ *
+ * @example
+ * const left = [{ a: 1, b: 2 }];
+ * const right = [{ b: 2, c: 3 }];
+ * getCommonAttrs(left, right);
+ * // => ['b']
+ */
+export declare const getCommonAttrs: (left: Tuple[], right: Tuple[]) => AttrName[];
+/**
+ * Normalizes JoinKeys to a Record<AttrName, AttrName> mapping left attrs to right attrs.
+ *
+ * @example
+ * // undefined => use common attributes
+ * normalizeKeys(undefined, [{ id: 1, city: 'NYC' }], [{ city: 'NYC' }]);
+ * // => { city: 'city' }
+ *
+ * @example
+ * // Array of common attribute names
+ * normalizeKeys(['city', 'country'], leftTuples, rightTuples);
+ * // => { city: 'city', country: 'country' }
+ *
+ * @example
+ * // Object mapping left attr to right attr
+ * normalizeKeys({ city: 'location' }, leftTuples, rightTuples);
+ * // => { city: 'location' }
+ */
+export declare const normalizeKeys: (keys: JoinKeys | undefined, leftTuples: Tuple[], rightTuples: Tuple[]) => Record<AttrName, AttrName>;
+/**
+ * Checks if two tuples match on the specified key mapping.
+ *
+ * @example
+ * const keyMap = { city: 'location' };
+ * tuplesMatch({ id: 1, city: 'NYC' }, { location: 'NYC', pop: 8 }, keyMap);
+ * // => true (left.city === right.location)
+ *
+ * @example
+ * const keyMap = { city: 'city' };
+ * tuplesMatch({ city: 'NYC' }, { city: 'LA' }, keyMap);
+ * // => false
+ */
+export declare const tuplesMatch: (left: Tuple, right: Tuple, keyMap: Record<AttrName, AttrName>) => boolean;
+/**
+ * Creates a string key from a tuple's join attributes for fast Set-based lookups.
+ * Used by matching/not_matching for efficient semi-join operations.
+ *
+ * @example
+ * const keyMap = { first: 'fname', last: 'lname' };
+ *
+ * // Left side uses left attr names (keys of keyMap)
+ * matchKey({ id: 1, first: 'John', last: 'Doe' }, keyMap, 'left');
+ * // => '"John"|"Doe"'
+ *
+ * // Right side uses right attr names (values of keyMap)
+ * matchKey({ fname: 'John', lname: 'Doe', age: 30 }, keyMap, 'right');
+ * // => '"John"|"Doe"'
+ */
+export declare const matchKey: (tuple: Tuple, keyMap: Record<AttrName, AttrName>, side: 'left' | 'right') => string;
+/**
+ * Removes join key attributes from a right tuple when merging.
+ * Used to avoid duplicate columns in join results.
+ *
+ * @example
+ * const keyMap = { city: 'location' };
+ * projectOutKeys({ location: 'NYC', country: 'USA', pop: 8 }, keyMap);
+ * // => { country: 'USA', pop: 8 }  (location removed)
+ *
+ * @example
+ * const keyMap = { a: 'a', b: 'b' };
+ * projectOutKeys({ a: 1, b: 2, c: 3 }, keyMap);
+ * // => { c: 3 }  (a and b removed)
+ */
+export declare const projectOutKeys: (tuple: Tuple, keyMap: Record<AttrName, AttrName>) => Tuple;

package/dist/sync/operators/allbut.d.ts

@@ -0,0 +1,2 @@
+import { RelationOperand, AttrName } from "../../types";
+export declare const allbut: (operand: RelationOperand, attrs: AttrName[]) => RelationOperand;

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

@@ -0,0 +1,2 @@
+import { AutowrapOptions, RelationOperand } from "../../types";
+export declare const autowrap: (operand: RelationOperand, options?: AutowrapOptions) => RelationOperand;

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

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

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

@@ -0,0 +1,3 @@
+import { RelationOperand } from "../../types";
+export declare const cross_product: (left: RelationOperand, right: RelationOperand) => RelationOperand;
+export { cross_product as cross_join };

package/dist/sync/operators/exclude.d.ts

@@ -0,0 +1,2 @@
+import { RelationOperand, Predicate } from "../../types";
+export declare const exclude: (operand: RelationOperand, p: Predicate) => RelationOperand;

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

@@ -0,0 +1,2 @@
+import { RelationOperand, Extension } from "../../types";
+export declare const extend: (operand: RelationOperand, extension: Extension) => RelationOperand;

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

@@ -0,0 +1,2 @@
+import { RelationOperand, AttrName } from "../../types";
+export declare const group: (operand: RelationOperand, attrs: AttrName[], as: AttrName) => RelationOperand;

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

@@ -0,0 +1,2 @@
+import { RelationOperand, JoinKeys, AttrName } from "../../types";
+export declare const image: (left: RelationOperand, right: RelationOperand, as: AttrName, keys?: JoinKeys) => RelationOperand;

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

@@ -0,0 +1,30 @@
+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/dist/sync/operators/intersect.d.ts

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

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

@@ -0,0 +1 @@
+export declare const isEqual: (left: any, right: any) => boolean;

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

@@ -0,0 +1,2 @@
+import { Relation } from "@/types";
+export declare const isRelation: (op: unknown) => op is Relation<import("@/types").Tuple>;

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

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

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

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

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

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

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

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

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

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

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

@@ -0,0 +1,2 @@
+import { RelationOperand, Tuple } from "../../types";
+export declare const one: (operand: RelationOperand) => Tuple;

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

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

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

@@ -0,0 +1,2 @@
+import { RelationOperand, AttrName } from "../../types";
+export declare const project: (operand: RelationOperand, attrs: AttrName[]) => RelationOperand;

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

@@ -0,0 +1,2 @@
+import { RelationOperand, Renaming } from "../../types";
+export declare const rename: (operand: RelationOperand, renaming: Renaming) => RelationOperand;

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

@@ -0,0 +1,2 @@
+import { RelationOperand, Predicate } from "../../types";
+export declare const restrict: (operand: RelationOperand, p: Predicate) => RelationOperand;

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

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

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

@@ -0,0 +1,2 @@
+import { RelationOperand, AttrName, Aggregators } from "../../types";
+export declare const summarize: (operand: RelationOperand, by: AttrName[], aggs: Aggregators) => RelationOperand;

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

@@ -0,0 +1,2 @@
+import { RelationOperand, Transformation } from "../../types";
+export declare const transform: (operand: RelationOperand, transformation: Transformation) => RelationOperand;

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

@@ -0,0 +1,2 @@
+import { RelationOperand, AttrName } from "../../types";
+export declare const ungroup: (operand: RelationOperand, attr: AttrName) => RelationOperand;

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

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

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

@@ -0,0 +1,2 @@
+import { RelationOperand, AttrName } from "../../types";
+export declare const unwrap: (operand: RelationOperand, attr: AttrName) => RelationOperand;

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

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

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

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

package/dist/types.d.ts

@@ -90,6 +90,12 @@ export type Extension = Record<AttrName, ExtensionFunc | AttrName>;
 export interface PrefixOptions {
     except?: AttrName[];
 }
+export interface TextOptions {
+    /** Precision for floating point numbers (default: 3) */
+    floatPrecision?: number;
+    /** Maximum width to trim output at */
+    trimAt?: number;
+}
 export interface SuffixOptions {
     except?: AttrName[];
 }
@@ -154,6 +160,7 @@ 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;
+    toText(options?: TextOptions): string;
 }
 export type RelationOperand<T = Tuple> = Relation<T> | T[];
 export interface OperationalOperand<T = Tuple> {

package/dist/writer/Text.d.ts

@@ -0,0 +1,68 @@
+import { Relation, Tuple } from '../types';
+/**
+ * Characters used for table borders
+ */
+export interface BorderChars {
+    topLeft: string;
+    topCenter: string;
+    topRight: string;
+    midLeft: string;
+    midCenter: string;
+    midRight: string;
+    bottomLeft: string;
+    bottomCenter: string;
+    bottomRight: string;
+    horizontal: string;
+    vertical: string;
+}
+/** ASCII border style (default) - maximum compatibility */
+export declare const ASCII_BORDER: BorderChars;
+/** Unicode single-line border style */
+export declare const SINGLE_BORDER: BorderChars;
+/** Unicode double-line border style */
+export declare const DOUBLE_BORDER: BorderChars;
+/** Unicode rounded corners border style */
+export declare const ROUNDED_BORDER: BorderChars;
+/** Border style preset names */
+export type BorderStyleName = 'ascii' | 'single' | 'double' | 'rounded';
+/**
+ * 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;
+    /** Border style: preset name or custom BorderChars object */
+    border?: BorderStyleName | BorderChars;
+}
+/**
+ * Text writer for rendering relations as ASCII tables
+ */
+export declare class TextWriter {
+    readonly options: TextOptions;
+    constructor(options?: TextOptions);
+    /**
+     * Renders a relation or tuple array to an ASCII table string
+     */
+    render(input: Relation | Tuple[] | Tuple, output?: string): string;
+    eachLine(input: Relation | Tuple[] | Tuple): Generator<string>;
+}
+/**
+ * Renders a relation as an ASCII table string
+ *
+ * @param operand - The relation or tuple array to render
+ * @param options - Text rendering options
+ * @returns ASCII table string representation
+ *
+ * @example
+ * const r = Bmg([{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }]);
+ * console.log(toText(r));
+ * // +----+-------+
+ * // | id | name  |
+ * // +----+-------+
+ * // |  1 | Alice |
+ * // |  2 | Bob   |
+ * // +----+-------+
+ */
+export declare const toText: (operand: Relation | Tuple[] | Tuple, options?: TextOptions) => string;

package/dist/writer/index.d.ts

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enspirit/bmg-js",
-  "version": "1.0.2",
+  "version": "1.1.1",
   "description": "Relational algebra for JavaScript/TypeScript - work with arrays of objects using powerful set operations",
   "keywords": [
     "relational",

package/src/Relation/index.ts

@@ -1 +1,2 @@
-export * from './Memory';
+// Re-export sync Relation for backward compatibility
+export * from '../sync/Relation';