@enspirit/bmg-js 1.0.0

package/src/operators/one.ts

@@ -0,0 +1,17 @@
+import { RelationOperand, Tuple } from "../types";
+import { toOperationalOperand, error } from "./_helpers";
+
+export const one = (operand: RelationOperand): Tuple => {
+  const op = toOperationalOperand(operand);
+  const iterable = op.tuples();
+  let tuple;
+  for (const t of iterable) {
+    if (tuple) {
+      return error('More than one tuple found');
+    } else {
+      tuple = t;
+    }
+  }
+  if (tuple) return tuple;
+  return error('Relation is empty');
+}

package/src/operators/prefix.ts

@@ -0,0 +1,7 @@
+import { PrefixOptions, RelationOperand } from "../types";
+import { rename } from "./rename";
+
+export const prefix = (operand: RelationOperand, pfx: string, options?: PrefixOptions): RelationOperand => {
+  const except = new Set(options?.except ?? []);
+  return rename(operand, (attr) => except.has(attr) ? attr : `${pfx}${attr}`);
+}

package/src/operators/project.ts

@@ -0,0 +1,18 @@
+import { RelationOperand, AttrName, Tuple } from "../types";
+import { toOperationalOperand, deduplicate } from "./_helpers";
+
+export const project = (operand: RelationOperand, attrs: AttrName[]): RelationOperand => {
+  const op = toOperationalOperand(operand);
+  const iterable = op.tuples();
+  const result: Tuple[] = [];
+  for (const tuple of iterable) {
+    const projected = attrs.reduce((memo, attr) => {
+      if (attr in tuple) {
+        memo[attr] = tuple[attr];
+      }
+      return memo;
+    }, {} as Tuple);
+    result.push(projected);
+  }
+  return op.output(deduplicate(result));
+}

package/src/operators/rename.ts

@@ -0,0 +1,17 @@
+import { RelationOperand, Renaming, Tuple } from "../types";
+import { toOperationalOperand, toRenamingFunc } from "./_helpers";
+
+export const rename = (operand: RelationOperand, renaming: Renaming): RelationOperand => {
+  const op = toOperationalOperand(operand);
+  const iterable = op.tuples();
+  const renamingFunc = toRenamingFunc(renaming)
+  const result: Tuple[] = [];
+  for (const tuple of iterable) {
+    const renamed = Object.keys(tuple).reduce((memo, attr) => {
+      memo[renamingFunc(attr)] = tuple[attr];
+      return memo;
+    }, {})
+    result.push(renamed);
+  }
+  return op.output(result)
+}

package/src/operators/restrict.ts

@@ -0,0 +1,14 @@
+import { toPredicateFunc } from "../support/toPredicateFunc";
+import { RelationOperand, Predicate, Tuple } from "../types";
+import { toOperationalOperand } from "./_helpers";
+
+export const restrict = (operand: RelationOperand, p: Predicate): RelationOperand => {
+  const op = toOperationalOperand(operand);
+  const iterable = op.tuples();
+  const f = toPredicateFunc(p)
+  const kept: Tuple[] = [];
+  for (const tuple of iterable) {
+    if (f(tuple)) kept.push(tuple);
+  }
+  return op.output(kept)
+}

package/src/operators/suffix.ts

@@ -0,0 +1,7 @@
+import { RelationOperand, SuffixOptions } from "../types";
+import { rename } from "./rename";
+
+export const suffix = (operand: RelationOperand, sfx: string, options?: SuffixOptions): RelationOperand => {
+  const except = new Set(options?.except ?? []);
+  return rename(operand, (attr) => except.has(attr) ? attr : `${attr}${sfx}`);
+}

package/src/operators/summarize.ts

@@ -0,0 +1,85 @@
+import { RelationOperand, AttrName, Tuple, Aggregator, Aggregators } from "../types";
+import { toOperationalOperand } from "./_helpers";
+
+const groupKey = (tuple: Tuple, by: AttrName[]): string => {
+  const keyParts = by.map(attr => JSON.stringify(tuple[attr]));
+  return keyParts.join('|');
+}
+
+const pickAttrs = (tuple: Tuple, attrs: AttrName[]): Tuple => {
+  return attrs.reduce((acc, attr) => {
+    acc[attr] = tuple[attr];
+    return acc;
+  }, {} as Tuple);
+}
+
+const applyAggregator = (tuples: Tuple[], agg: Aggregator): unknown => {
+  if (typeof agg === 'function') {
+    return agg(tuples);
+  }
+
+  const spec = typeof agg === 'string' ? { op: agg, attr: '' } : agg;
+  const { op, attr } = spec;
+
+  switch (op) {
+    case 'count':
+      return tuples.length;
+
+    case 'sum': {
+      return tuples.reduce((sum, t) => sum + (Number(t[attr]) || 0), 0);
+    }
+
+    case 'min': {
+      const values = tuples.map(t => t[attr]).filter(v => v !== undefined && v !== null);
+      return values.length > 0 ? Math.min(...values.map(Number)) : null;
+    }
+
+    case 'max': {
+      const values = tuples.map(t => t[attr]).filter(v => v !== undefined && v !== null);
+      return values.length > 0 ? Math.max(...values.map(Number)) : null;
+    }
+
+    case 'avg': {
+      const values = tuples.map(t => Number(t[attr])).filter(v => !isNaN(v));
+      return values.length > 0 ? values.reduce((a, b) => a + b, 0) / values.length : null;
+    }
+
+    case 'collect': {
+      return tuples.map(t => t[attr]);
+    }
+
+    default:
+      throw new Error(`Unknown aggregator: ${op}`);
+  }
+}
+
+export const summarize = (
+  operand: RelationOperand,
+  by: AttrName[],
+  aggs: Aggregators
+): RelationOperand => {
+  const op = toOperationalOperand(operand);
+  const tuples = [...op.tuples()];
+
+  // Group tuples
+  const groups = new Map<string, Tuple[]>();
+  for (const tuple of tuples) {
+    const key = groupKey(tuple, by);
+    if (!groups.has(key)) {
+      groups.set(key, []);
+    }
+    groups.get(key)!.push(tuple);
+  }
+
+  // Apply aggregators to each group
+  const result: Tuple[] = [];
+  for (const groupTuples of groups.values()) {
+    const row: Tuple = pickAttrs(groupTuples[0], by);
+    for (const [resultAttr, agg] of Object.entries(aggs)) {
+      row[resultAttr] = applyAggregator(groupTuples, agg);
+    }
+    result.push(row);
+  }
+
+  return op.output(result);
+}

package/src/operators/transform.ts

@@ -0,0 +1,40 @@
+import { RelationOperand, Transformation, Tuple } from "../types";
+import { toOperationalOperand } from "./_helpers";
+
+export const transform = (operand: RelationOperand, transformation: Transformation): RelationOperand => {
+  const op = toOperationalOperand(operand);
+  const iterable = op.tuples();
+  const result: Tuple[] = [];
+
+  for (const tuple of iterable) {
+    const transformed: Tuple = {};
+
+    for (const [attr, value] of Object.entries(tuple)) {
+      transformed[attr] = applyTransformation(value, attr, transformation);
+    }
+
+    result.push(transformed);
+  }
+
+  return op.output(result);
+}
+
+const applyTransformation = (value: unknown, attr: string, transformation: Transformation): unknown => {
+  if (typeof transformation === 'function') {
+    // Single function - apply to all values
+    return transformation(value);
+  } else if (Array.isArray(transformation)) {
+    // Array of functions - chain them
+    return transformation.reduce((v, fn) => fn(v), value);
+  } else {
+    // Object with attr-specific transformers
+    const fn = transformation[attr];
+    if (fn) {
+      if (Array.isArray(fn)) {
+        return fn.reduce((v, f) => f(v), value);
+      }
+      return fn(value);
+    }
+    return value;
+  }
+}

package/src/operators/ungroup.ts

@@ -0,0 +1,41 @@
+import { RelationOperand, AttrName, Tuple, Relation } from "../types";
+import { toOperationalOperand } from "./_helpers";
+import { isRelation } from "./isRelation";
+
+const toTupleArray = (value: unknown): Tuple[] => {
+  if (isRelation(value)) {
+    return (value as Relation).toArray();
+  }
+  if (Array.isArray(value)) {
+    return value;
+  }
+  throw new Error(`Value is not a relation or array`);
+}
+
+export const ungroup = (operand: RelationOperand, attr: AttrName): RelationOperand => {
+  const op = toOperationalOperand(operand);
+  const tuples = [...op.tuples()];
+  const result: Tuple[] = [];
+
+  for (const tuple of tuples) {
+    const nested = toTupleArray(tuple[attr]);
+
+    // Get base attributes (all except the grouped one)
+    const base: Tuple = {};
+    for (const [key, value] of Object.entries(tuple)) {
+      if (key !== attr) {
+        base[key] = value;
+      }
+    }
+
+    // Flatten each nested tuple
+    for (const nestedTuple of nested) {
+      result.push({
+        ...base,
+        ...nestedTuple
+      });
+    }
+  }
+
+  return op.output(result);
+}

package/src/operators/union.ts

@@ -0,0 +1,27 @@
+import { RelationOperand, Tuple } from "../types";
+import { toOperationalOperand, tupleKey } from "./_helpers";
+
+export const union = (left: RelationOperand, right: RelationOperand): RelationOperand => {
+  const opLeft = toOperationalOperand(left);
+  const opRight = toOperationalOperand(right);
+  const seen = new Set<string>();
+  const result: Tuple[] = [];
+
+  for (const tuple of opLeft.tuples()) {
+    const key = tupleKey(tuple);
+    if (!seen.has(key)) {
+      seen.add(key);
+      result.push(tuple);
+    }
+  }
+
+  for (const tuple of opRight.tuples()) {
+    const key = tupleKey(tuple);
+    if (!seen.has(key)) {
+      seen.add(key);
+      result.push(tuple);
+    }
+  }
+
+  return opLeft.output(result);
+}

package/src/operators/unwrap.ts

@@ -0,0 +1,29 @@
+import { RelationOperand, AttrName, Tuple } from "../types";
+import { toOperationalOperand } from "./_helpers";
+
+export const unwrap = (operand: RelationOperand, attr: AttrName): RelationOperand => {
+  const op = toOperationalOperand(operand);
+  const iterable = op.tuples();
+  const result: Tuple[] = [];
+
+  for (const tuple of iterable) {
+    const wrapped = tuple[attr] as Tuple;
+    if (typeof wrapped !== 'object' || wrapped === null || Array.isArray(wrapped)) {
+      throw new Error(`Attribute '${attr}' is not a tuple (object)`);
+    }
+
+    const unwrapped: Tuple = {};
+    for (const [key, value] of Object.entries(tuple)) {
+      if (key !== attr) {
+        unwrapped[key] = value;
+      }
+    }
+
+    result.push({
+      ...unwrapped,
+      ...wrapped
+    });
+  }
+
+  return op.output(result);
+}

package/src/operators/where.ts

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

package/src/operators/wrap.ts

@@ -0,0 +1,29 @@
+import { RelationOperand, AttrName, Tuple } from "../types";
+import { toOperationalOperand } from "./_helpers";
+
+export const wrap = (operand: RelationOperand, attrs: AttrName[], as: AttrName): RelationOperand => {
+  const op = toOperationalOperand(operand);
+  const iterable = op.tuples();
+  const wrappedSet = new Set(attrs);
+  const result: Tuple[] = [];
+
+  for (const tuple of iterable) {
+    const wrapped: Tuple = {};
+    const remaining: Tuple = {};
+
+    for (const [key, value] of Object.entries(tuple)) {
+      if (wrappedSet.has(key)) {
+        wrapped[key] = value;
+      } else {
+        remaining[key] = value;
+      }
+    }
+
+    result.push({
+      ...remaining,
+      [as]: wrapped
+    });
+  }
+
+  return op.output(result);
+}

package/src/operators/yByX.ts

@@ -0,0 +1,12 @@
+import { AttrName, RelationOperand, Tuple } from "../types";
+import { toOperationalOperand } from "./_helpers";
+
+export const yByX = (operand: RelationOperand, y: AttrName, x: AttrName): Tuple => {
+  const op = toOperationalOperand(operand);
+  const iterable = op.tuples();
+  const hash = {};
+  for (const tuple of iterable) {
+    hash[`${tuple[x]}`] = tuple[y];
+  }
+  return hash;
+}

package/src/support/toPredicateFunc.ts

@@ -0,0 +1,12 @@
+import { Predicate, PredicateFunc, Tuple } from '../types';
+
+export const toPredicateFunc = (p: Predicate): PredicateFunc => {
+  if (typeof(p) === 'function') {
+    return p as PredicateFunc;
+  } else {
+    const expected = p as Tuple;
+    return (t: Tuple) => {
+      return Object.keys(expected).every(k => t[k] === expected[k])
+    }
+  }
+}

package/src/types.ts

@@ -0,0 +1,178 @@
+import type {
+  RenameMap, Renamed,
+  Prefixed, Suffixed,
+  Joined, LeftJoined,
+  Wrapped, Unwrapped,
+  AggregatorResults
+} from './utility-types';
+
+// ============================================================================
+// Group/Ungroup Types (defined here due to Relation dependency)
+// ============================================================================
+
+/** 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>
+
+export interface PrefixOptions {
+  except?: AttrName[]
+}
+
+export interface SuffixOptions {
+  except?: AttrName[]
+}
+
+export interface AutowrapOptions {
+  separator?: string
+}
+
+// ============================================================================
+// Typed Predicates
+// ============================================================================
+
+/** Predicate function that receives a typed tuple */
+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>
+
+// ============================================================================
+// Typed Extensions
+// ============================================================================
+
+/** Extension function that receives a typed tuple */
+export type TypedExtensionFunc<T, R> = (tuple: T) => R
+
+/** Extension definition: function returning value, or attribute name to copy */
+export type TypedExtension<T, E extends Record<string, unknown>> = {
+  [K in keyof E]: TypedExtensionFunc<T, E[K]> | keyof T;
+}
+
+// ============================================================================
+// Generic Relation Interface
+// ============================================================================
+
+/**
+ * Relation interface with generic type parameter for tuple type.
+ * Default parameter `Tuple` ensures backwards compatibility.
+ *
+ * @typeParam T - The tuple type for this relation. Defaults to `Tuple` (Record<string, unknown>).
+ *
+ * @example
+ * // Untyped usage (backwards compatible)
+ * const r = Bmg([{ id: 1 }]);  // Relation<Tuple>
+ *
+ * @example
+ * // Typed usage with full type safety
+ * interface Person { id: number; name: string }
+ * const r = Bmg<Person>([{ id: 1, name: 'Alice' }]);
+ * r.project(['id']);  // Relation<{ id: number }>
+ */
+export interface Relation<T = Tuple> {
+  // === Type-preserving operators ===
+
+  restrict(p: TypedPredicate<T>): Relation<T>
+  where(p: TypedPredicate<T>): Relation<T>
+  exclude(p: TypedPredicate<T>): Relation<T>
+
+  // === Projection operators ===
+
+  project<K extends keyof T>(attrs: K[]): Relation<Pick<T, K>>
+  allbut<K extends keyof T>(attrs: K[]): Relation<Omit<T, K>>
+
+  // === Extension operators ===
+
+  extend<E extends Record<string, unknown>>(e: TypedExtension<T, E>): Relation<T & E>
+  constants<C extends Tuple>(consts: C): Relation<T & C>
+
+  // === Rename operators ===
+
+  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>>
+
+  // === Set operators (require same type) ===
+
+  union(right: RelationOperand<T>): Relation<T>
+  minus(right: RelationOperand<T>): Relation<T>
+  intersect(right: RelationOperand<T>): Relation<T>
+
+  // === 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>
+
+  // === 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>>
+  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>>>>
+  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>>
+
+  // === Aggregation ===
+
+  summarize<By extends keyof T, Aggs extends Aggregators>(by: By[], aggs: Aggs): Relation<Pick<T, By> & AggregatorResults<Aggs>>
+
+  // === Transform ===
+
+  transform(t: Transformation): Relation<T>
+
+  // === Dynamic (loses type precision) ===
+
+  autowrap(options?: AutowrapOptions): Relation<Tuple>
+
+  // === Non-relational ===
+
+  one(): T
+  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
+}
+
+// ============================================================================
+// Operands and Helpers
+// ============================================================================
+
+export type RelationOperand<T = Tuple> = Relation<T> | T[]
+
+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/utility-types.ts

@@ -0,0 +1,77 @@
+/**
+ * Utility types for type transformations in relational operators.
+ * These enable compile-time tracking of how operators transform tuple types.
+ */
+
+import type { Tuple } from './types';
+
+// ============================================================================
+// 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];
+};
+
+// ============================================================================
+// 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>>>;
+
+// ============================================================================
+// 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>;
+
+// Note: Ungrouped is defined in types.ts since it references Relation
+
+// ============================================================================
+// Aggregator Result Types
+// ============================================================================
+
+/** 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;
+
+/** Map aggregator definitions to their result types */
+export type AggregatorResults<Aggs extends Record<string, unknown>> = {
+  [K in keyof Aggs]: AggregatorResult<Aggs[K]>;
+};

package/tests/bmg.test.ts

@@ -0,0 +1,16 @@
+import { describe, it, expect } from 'vitest';
+import { Bmg } from 'src';
+
+describe('BMG.js', () => {
+  it('exists', () => {
+    expect(Bmg).not.toBe(undefined);
+  });
+
+  it('allows building relations', () => {
+    const r = Bmg([
+      {sid: 'S1', name: 'Smith'},
+      {sid: 'S2', name: 'Jones'},
+    ])
+    expect(Bmg.isRelation(r)).toBeTruthy()
+  })
+});

package/tests/fixtures.ts

@@ -0,0 +1,9 @@
+import { Bmg } from 'src'
+
+export const SUPPLIERS = Bmg([
+  {sid: 'S1', name: 'Smith', status: 20, city: 'London' },
+  {sid: 'S2', name: 'Jones', status: 10, city: 'Paris' },
+  {sid: 'S3', name: 'Blake', status: 30, city: 'Paris' },
+  {sid: 'S4', name: 'Clark', status: 20, city: 'London' },
+  {sid: 'S5', name: 'Adams', status: 30, city: 'Athens' },
+])