@enspirit/bmg-js 1.0.0

package/example/README.md

@@ -0,0 +1,22 @@
+# Bmg.js Example
+
+Demonstrates relational algebra operations using the classic suppliers/parts/shipments dataset with full TypeScript type safety.
+
+## Running the example
+
+```bash
+npm install
+npm start
+```
+
+## What's covered
+
+- Basic operations: `restrict`, `project`, `rename`
+- Extending relations: `extend`, `constants`
+- Set operations: `union`, `minus`, `intersect`
+- Join operations: `join`, `left_join`, `matching`, `not_matching`
+- Aggregation: `summarize` with `count`, `sum`, `avg`, `min`, `max`
+- Grouping and nesting: `group`, `image`, `wrap`
+- Data transformation: `transform`, `allbut`
+- Extracting tuples: `one()`
+- Relation properties: `isEqual`, `Bmg.isRelation`

package/example/index.ts

@@ -0,0 +1,316 @@
+/**
+ * Bmg.js Example - Relational Algebra Operations (TypeScript)
+ *
+ * This example demonstrates chaining various relational operators
+ * using the classic suppliers/parts/shipments dataset with full type safety.
+ */
+
+import { Bmg, Relation } from '@enspirit/bmg-js';
+
+// =============================================================================
+// Type Definitions
+// =============================================================================
+
+interface Supplier {
+  sid: string;
+  name: string;
+  status: number;
+  city: string;
+}
+
+interface Part {
+  pid: string;
+  pname: string;
+  color: string;
+  weight: number;
+  city: string;
+}
+
+interface Shipment {
+  sid: string;
+  pid: string;
+  qty: number;
+}
+
+// =============================================================================
+// Sample Data: Suppliers, Parts, and Shipments
+// =============================================================================
+
+const suppliers = Bmg<Supplier>([
+  { 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' },
+]);
+
+const parts = Bmg<Part>([
+  { pid: 'P1', pname: 'Nut', color: 'Red', weight: 12, city: 'London' },
+  { pid: 'P2', pname: 'Bolt', color: 'Green', weight: 17, city: 'Paris' },
+  { pid: 'P3', pname: 'Screw', color: 'Blue', weight: 17, city: 'Oslo' },
+  { pid: 'P4', pname: 'Screw', color: 'Red', weight: 14, city: 'London' },
+  { pid: 'P5', pname: 'Cam', color: 'Blue', weight: 12, city: 'Paris' },
+  { pid: 'P6', pname: 'Cog', color: 'Red', weight: 19, city: 'London' },
+]);
+
+const shipments = Bmg<Shipment>([
+  { sid: 'S1', pid: 'P1', qty: 300 },
+  { sid: 'S1', pid: 'P2', qty: 200 },
+  { sid: 'S1', pid: 'P3', qty: 400 },
+  { sid: 'S1', pid: 'P4', qty: 200 },
+  { sid: 'S1', pid: 'P5', qty: 100 },
+  { sid: 'S1', pid: 'P6', qty: 100 },
+  { sid: 'S2', pid: 'P1', qty: 300 },
+  { sid: 'S2', pid: 'P2', qty: 400 },
+  { sid: 'S3', pid: 'P2', qty: 200 },
+  { sid: 'S4', pid: 'P2', qty: 200 },
+  { sid: 'S4', pid: 'P4', qty: 300 },
+  { sid: 'S4', pid: 'P5', qty: 400 },
+]);
+
+// Helper to print results
+const printRelation = <T>(title: string, relation: Relation<T>): void => {
+  console.log(`\n${'='.repeat(60)}`);
+  console.log(title);
+  console.log('='.repeat(60));
+  console.log(relation.toArray());
+};
+
+// =============================================================================
+// Example 1: Basic Operations - restrict, project, rename
+// =============================================================================
+
+console.log('\n*** EXAMPLE 1: Basic Operations ***');
+
+// Find suppliers in Paris, showing only their id and name
+// Type: Relation<{ sid: string; name: string }>
+const parisSuppliers = suppliers
+  .restrict({ city: 'Paris' })
+  .project(['sid', 'name']);
+
+printRelation('Suppliers in Paris (id and name only)', parisSuppliers);
+
+// Rename attributes for clarity
+// Type: Relation<{ supplierId: string; supplierName: string; city: string }>
+const renamedSuppliers = suppliers
+  .project(['sid', 'name', 'city'])
+  .rename({ sid: 'supplierId', name: 'supplierName' });
+
+printRelation('Suppliers with renamed attributes', renamedSuppliers);
+
+// =============================================================================
+// Example 2: Extending Relations - extend, constants, prefix
+// =============================================================================
+
+console.log('\n*** EXAMPLE 2: Extending Relations ***');
+
+// Add computed attributes
+// Type: Relation<Part & { weightInKg: number; description: string }>
+const partsWithMetrics = parts
+  .extend({
+    weightInKg: (t: Part) => t.weight / 1000,
+    description: (t: Part) => `${t.color} ${t.pname}`,
+  })
+  .project(['pid', 'description', 'weight', 'weightInKg']);
+
+printRelation('Parts with computed metrics', partsWithMetrics);
+
+// Add constant values
+const taggedParts = parts
+  .restrict({ color: 'Red' })
+  .constants({ category: 'Primary', inStock: true })
+  .project(['pid', 'pname', 'category', 'inStock']);
+
+printRelation('Red parts with constant tags', taggedParts);
+
+// =============================================================================
+// Example 3: Set Operations - union, minus, intersect
+// =============================================================================
+
+console.log('\n*** EXAMPLE 3: Set Operations ***');
+
+const partCities = parts.project(['city']);
+
+// Cities where we have either suppliers or parts
+const allCities = suppliers.project(['city']).union(partCities);
+printRelation('All cities (suppliers OR parts)', allCities);
+
+// Cities where we have both suppliers and parts
+const commonCities = suppliers.project(['city']).intersect(partCities);
+printRelation('Common cities (suppliers AND parts)', commonCities);
+
+// Cities with parts but no suppliers
+const partOnlyCities = partCities.minus(suppliers.project(['city']));
+printRelation('Cities with parts but no suppliers', partOnlyCities);
+
+// =============================================================================
+// Example 4: Join Operations - join, left_join, matching
+// =============================================================================
+
+console.log('\n*** EXAMPLE 4: Join Operations ***');
+
+// Natural join: suppliers and parts in the same city
+const supplierPartsInSameCity = suppliers
+  .project(['sid', 'name', 'city'])
+  .join(parts.project(['pid', 'pname', 'city']));
+
+printRelation('Suppliers and parts in the same city', supplierPartsInSameCity);
+
+// Full shipment details with supplier and part info
+const fullShipments = shipments
+  .join(suppliers.project(['sid', 'name']), ['sid'])
+  .join(parts.project(['pid', 'pname', 'color']), ['pid'])
+  .project(['name', 'pname', 'color', 'qty']);
+
+printRelation('Full shipment details', fullShipments);
+
+// Left join: all suppliers with their shipments (if any)
+const suppliersWithShipments = suppliers
+  .project(['sid', 'name'])
+  .left_join(
+    shipments.summarize(['sid'], { totalQty: { op: 'sum', attr: 'qty' } }),
+    ['sid']
+  );
+
+printRelation('All suppliers with total shipped qty', suppliersWithShipments);
+
+// Matching: suppliers who have shipped something
+const activeSuppliers = suppliers.matching(shipments, ['sid']);
+printRelation('Suppliers who have made shipments', activeSuppliers);
+
+// Not matching: suppliers who haven't shipped anything
+const inactiveSuppliers = suppliers.not_matching(shipments, ['sid']);
+printRelation('Suppliers with no shipments', inactiveSuppliers);
+
+// =============================================================================
+// Example 5: Aggregation - summarize
+// =============================================================================
+
+console.log('\n*** EXAMPLE 5: Aggregation ***');
+
+// Count suppliers per city
+const suppliersPerCity = suppliers.summarize(['city'], {
+  supplierCount: 'count',
+  avgStatus: { op: 'avg', attr: 'status' },
+});
+
+printRelation('Suppliers per city with average status', suppliersPerCity);
+
+// Shipment statistics per supplier
+const shipmentStats = shipments
+  .join(suppliers.project(['sid', 'name']), ['sid'])
+  .summarize(['name'], {
+    shipmentCount: 'count',
+    totalQty: { op: 'sum', attr: 'qty' },
+    avgQty: { op: 'avg', attr: 'qty' },
+    minQty: { op: 'min', attr: 'qty' },
+    maxQty: { op: 'max', attr: 'qty' },
+  });
+
+printRelation('Shipment statistics per supplier', shipmentStats);
+
+// Grand total
+const grandTotal = shipments.summarize([], {
+  totalShipments: 'count',
+  totalQuantity: { op: 'sum', attr: 'qty' },
+});
+
+printRelation('Grand total', grandTotal);
+
+// =============================================================================
+// Example 6: Grouping and Nesting - group, image, wrap
+// =============================================================================
+
+console.log('\n*** EXAMPLE 6: Grouping and Nesting ***');
+
+// Group parts: nest pid and pname into a 'items' relation, grouped by color
+const partsByColor = parts
+  .project(['color', 'pid', 'pname'])
+  .group(['pid', 'pname'], 'items');
+
+printRelation('Parts grouped by color (nested items)', partsByColor);
+
+// Show expanded view of one group
+const redParts = partsByColor.restrict({ color: 'Red' }).one();
+console.log('Red parts items:', redParts.items.toArray());
+
+// Image: for each supplier, get their shipped parts
+const supplierParts = suppliers
+  .project(['sid', 'name'])
+  .image(shipments.project(['sid', 'pid', 'qty']), 'shipments', ['sid']);
+
+printRelation('Each supplier with their shipments', supplierParts);
+
+// Wrap: combine part attributes into a nested object
+const wrappedParts = parts.wrap(['color', 'weight'], 'specs');
+
+printRelation('Parts with wrapped specs', wrappedParts);
+
+// =============================================================================
+// Example 7: Complex Chained Query
+// =============================================================================
+
+console.log('\n*** EXAMPLE 7: Complex Chained Query ***');
+
+// Find supplier quantities by part color
+const supplierQtyByColor = shipments
+  .join(parts.project(['pid', 'color']), ['pid'])
+  .join(suppliers.project(['sid', 'name']), ['sid'])
+  .summarize(['color', 'name'], {
+    totalQty: { op: 'sum', attr: 'qty' },
+  })
+  .project(['color', 'name', 'totalQty']);
+
+printRelation('Supplier quantities by part color', supplierQtyByColor);
+
+// =============================================================================
+// Example 8: Data Transformation - transform, allbut
+// =============================================================================
+
+console.log('\n*** EXAMPLE 8: Data Transformation ***');
+
+// Transform all string values to uppercase
+const uppercasedSuppliers = suppliers.transform({
+  name: (v: unknown) => (v as string).toUpperCase(),
+  city: (v: unknown) => (v as string).toUpperCase(),
+});
+
+printRelation('Suppliers with uppercase names and cities', uppercasedSuppliers);
+
+// Allbut: select all attributes except some
+// Type: Relation<{ pid: string; pname: string; color: string; weight: number }>
+const partsWithoutLocation = parts.allbut(['city']);
+
+printRelation('Parts without city attribute', partsWithoutLocation);
+
+// =============================================================================
+// Example 9: Using .one() to extract a single tuple
+// =============================================================================
+
+console.log('\n*** EXAMPLE 9: Extracting Single Tuples ***');
+
+// Get a specific supplier - returns typed Supplier
+const smith: Supplier = suppliers.restrict({ sid: 'S1' }).one();
+console.log('\nSupplier S1 (Smith):', smith);
+
+// Get the total quantity shipped
+const total = shipments.summarize([], { total: { op: 'sum', attr: 'qty' } }).one();
+console.log('Total quantity shipped:', total.total);
+
+// =============================================================================
+// Example 10: Checking Relation Properties
+// =============================================================================
+
+console.log('\n*** EXAMPLE 10: Relation Properties ***');
+
+// Check if two relations are equal
+const parisSuppliers1 = suppliers.restrict({ city: 'Paris' });
+const parisSuppliers2 = suppliers.restrict((t: Supplier) => t.city === 'Paris');
+
+console.log('\nAre the two Paris supplier queries equal?', parisSuppliers1.isEqual(parisSuppliers2));
+
+// Check if something is a relation
+console.log('Is suppliers a relation?', Bmg.isRelation(suppliers));
+console.log('Is an array a relation?', Bmg.isRelation([{ a: 1 }]));
+
+console.log('\n*** ALL EXAMPLES COMPLETED ***\n');

package/example/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "bmg-example",
+  "type": "module",
+  "version": "1.0.0",
+  "description": "Examples demonstrating Bmg.js relational algebra operations",
+  "scripts": {
+    "start": "tsx index.ts"
+  },
+  "dependencies": {
+    "@enspirit/bmg-js": "file:.."
+  },
+  "devDependencies": {
+    "tsx": "^4.7.0",
+    "typescript": "^5.3.0"
+  }
+}

package/example/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true
+  },
+  "include": ["*.ts"]
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@enspirit/bmg-js",
+  "version": "1.0.0",
+  "description": "Relational algebra for JavaScript/TypeScript - work with arrays of objects using powerful set operations",
+  "keywords": ["relational", "algebra", "relation", "set", "query", "data", "functional"],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/enspirit/bmg.js"
+  },
+  "type": "module",
+  "source": "src/index.ts",
+  "exports": {
+    "types": "./dist/src/index.d.ts",
+    "require": "./dist/bmg.cjs",
+    "default": "./dist/bmg.modern.js"
+  },
+  "main": "./dist/bmg.cjs",
+  "module": "./dist/bmg.module.js",
+  "types": "./dist/src/index.d.ts",
+  "unpkg": "./dist/bmg.umd.js",
+  "scripts": {
+    "build": "microbundle",
+    "dev": "microbundle watch",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "devDependencies": {
+    "microbundle": "^0.15.1",
+    "vite-tsconfig-paths": "^5.1.4",
+    "vitest": "^1.4.0"
+  },
+  "packageManager": "pnpm@8.11.0+sha1.01bf39424f1008f29012bbae851d2acb8a20a0d0"
+}

package/src/Relation/Memory.ts

@@ -0,0 +1,213 @@
+import {
+  allbut,
+  autowrap,
+  constants,
+  cross_product,
+  exclude,
+  extend,
+  group,
+  image,
+  intersect,
+  isEqual,
+  join,
+  left_join,
+  matching,
+  minus,
+  not_matching,
+  one,
+  prefix,
+  project,
+  rename,
+  restrict,
+  suffix,
+  summarize,
+  where,
+  transform,
+  ungroup,
+  union,
+  unwrap,
+  wrap,
+  yByX,
+} from "../operators";
+import type {
+  AttrName,
+  AutowrapOptions,
+  JoinKeys,
+  Relation,
+  RelationOperand,
+  Transformation,
+  Tuple,
+  TypedPredicate,
+  TypedExtension,
+  RenameMap,
+  Renamed,
+  Prefixed,
+  Suffixed,
+  Joined,
+  LeftJoined,
+  Wrapped,
+  Unwrapped,
+  Ungrouped,
+} from "../types";
+import type { AggregatorResults } from "../utility-types";
+
+/**
+ * In-memory implementation of the Relation interface.
+ *
+ * @typeParam T - The tuple type for this relation. Defaults to `Tuple` (Record<string, unknown>).
+ */
+export class MemoryRelation<T = Tuple> implements Relation<T> {
+
+  constructor(private tuples: T[]) {
+    this.tuples = tuples;
+  }
+
+  // === Type-preserving operators ===
+
+  restrict(p: TypedPredicate<T>): Relation<T> {
+    return restrict(this as any, p as any) as unknown as Relation<T>;
+  }
+
+  where(p: TypedPredicate<T>): Relation<T> {
+    return where(this as any, p as any) as unknown as Relation<T>;
+  }
+
+  exclude(p: TypedPredicate<T>): Relation<T> {
+    return exclude(this as any, p as any) as unknown as Relation<T>;
+  }
+
+  // === Projection operators ===
+
+  project<K extends keyof T>(attrs: K[]): Relation<Pick<T, K>> {
+    return project(this as any, attrs as AttrName[]) as unknown as Relation<Pick<T, K>>;
+  }
+
+  allbut<K extends keyof T>(attrs: K[]): Relation<Omit<T, K>> {
+    return allbut(this as any, attrs as AttrName[]) as unknown as Relation<Omit<T, K>>;
+  }
+
+  // === Extension operators ===
+
+  extend<E extends Record<string, unknown>>(e: TypedExtension<T, E>): Relation<T & E> {
+    return extend(this as any, e as any) as unknown as Relation<T & E>;
+  }
+
+  constants<C extends Tuple>(consts: C): Relation<T & C> {
+    return constants(this as any, consts) as unknown as Relation<T & C>;
+  }
+
+  // === Rename operators ===
+
+  rename<R extends RenameMap<T>>(r: R): Relation<Renamed<T, R>> {
+    return rename(this as any, r as any) as unknown as Relation<Renamed<T, R>>;
+  }
+
+  prefix<P extends string, Ex extends keyof T = never>(pfx: P, options?: { except?: Ex[] }): Relation<Prefixed<T, P, Ex>> {
+    return prefix(this as any, pfx, options as any) as unknown as Relation<Prefixed<T, P, Ex>>;
+  }
+
+  suffix<S extends string, Ex extends keyof T = never>(sfx: S, options?: { except?: Ex[] }): Relation<Suffixed<T, S, Ex>> {
+    return suffix(this as any, sfx, options as any) as unknown as Relation<Suffixed<T, S, Ex>>;
+  }
+
+  // === Set operators ===
+
+  union(right: RelationOperand<T>): Relation<T> {
+    return union(this as any, right as any) as unknown as Relation<T>;
+  }
+
+  minus(right: RelationOperand<T>): Relation<T> {
+    return minus(this as any, right as any) as unknown as Relation<T>;
+  }
+
+  intersect(right: RelationOperand<T>): Relation<T> {
+    return intersect(this as any, right as any) as unknown as Relation<T>;
+  }
+
+  // === Semi-join operators ===
+
+  matching<R>(right: RelationOperand<R>, keys?: JoinKeys): Relation<T> {
+    return matching(this as any, right as any, keys) as unknown as Relation<T>;
+  }
+
+  not_matching<R>(right: RelationOperand<R>, keys?: JoinKeys): Relation<T> {
+    return not_matching(this as any, right as any, keys) as unknown as Relation<T>;
+  }
+
+  // === Join operators ===
+
+  join<R>(right: RelationOperand<R>, keys?: JoinKeys): Relation<Joined<T, R>> {
+    return join(this as any, right as any, keys) as unknown as Relation<Joined<T, R>>;
+  }
+
+  left_join<R>(right: RelationOperand<R>, keys?: JoinKeys): Relation<LeftJoined<T, R>> {
+    return left_join(this as any, right as any, keys) as unknown as Relation<LeftJoined<T, R>>;
+  }
+
+  cross_product<R>(right: RelationOperand<R>): Relation<T & R> {
+    return cross_product(this as any, right as any) as unknown as Relation<T & R>;
+  }
+
+  cross_join<R>(right: RelationOperand<R>): Relation<T & R> {
+    return cross_product(this as any, right as any) as unknown as 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>>>> {
+    return image(this as any, right as any, as, keys) as unknown as 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>>>> {
+    return group(this as any, attrs as AttrName[], as) as unknown as Relation<Omit<T, K> & Record<As, Relation<Pick<T, K>>>>;
+  }
+
+  ungroup<K extends keyof T>(attr: K): Relation<Ungrouped<T, K>> {
+    return ungroup(this as any, attr as AttrName) as unknown as Relation<Ungrouped<T, K>>;
+  }
+
+  wrap<K extends keyof T, As extends string>(attrs: K[], as: As): Relation<Wrapped<T, K, As>> {
+    return wrap(this as any, attrs as AttrName[], as) as unknown as Relation<Wrapped<T, K, As>>;
+  }
+
+  unwrap<K extends keyof T>(attr: K): Relation<Unwrapped<T, K>> {
+    return unwrap(this as any, attr as AttrName) as unknown as Relation<Unwrapped<T, K>>;
+  }
+
+  // === Aggregation ===
+
+  summarize<By extends keyof T, Aggs extends Record<string, unknown>>(by: By[], aggs: Aggs): Relation<Pick<T, By> & AggregatorResults<Aggs>> {
+    return summarize(this as any, by as AttrName[], aggs as any) as unknown as Relation<Pick<T, By> & AggregatorResults<Aggs>>;
+  }
+
+  // === Transform ===
+
+  transform(t: Transformation): Relation<T> {
+    return transform(this as any, t) as unknown as Relation<T>;
+  }
+
+  // === Dynamic ===
+
+  autowrap(options?: AutowrapOptions): Relation<Tuple> {
+    return autowrap(this as any, options) as Relation<Tuple>;
+  }
+
+  // === Non-relational ===
+
+  one(): T {
+    return one(this as any) as T;
+  }
+
+  toArray(): T[] {
+    return this.tuples;
+  }
+
+  yByX<Y extends keyof T, X extends keyof T>(y: Y, x: X): Record<T[X] & PropertyKey, T[Y]> {
+    return yByX(this as any, y as AttrName, x as AttrName) as Record<T[X] & PropertyKey, T[Y]>;
+  }
+
+  isEqual(right: any): boolean {
+    return isEqual(this as any, right as any);
+  }
+
+}

package/src/Relation/index.ts

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

package/src/index.ts

@@ -0,0 +1,31 @@
+export * from './operators';
+export * from './types';
+export * from './utility-types';
+
+import { MemoryRelation } from './Relation';
+import { isRelation } from './operators';
+
+/**
+ * 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 function Bmg<T>(tuples: T[]): MemoryRelation<T> {
+  return new MemoryRelation<T>(tuples);
+}
+
+Bmg.isRelation = isRelation;