@enspirit/bmg-js 1.0.0

package/tests/operators/allbut.test.ts

@@ -0,0 +1,51 @@
+import { describe, it, expect } from 'vitest';
+import { Bmg } from 'src';
+import { SUPPLIERS } from 'tests/fixtures';
+import { allbut, isEqual } from 'src/operators';
+
+describe('.allbut', () => {
+
+  it('removes specified attributes', () => {
+    const result = SUPPLIERS.allbut(['status', 'city']);
+    const expected = Bmg([
+      { sid: 'S1', name: 'Smith' },
+      { sid: 'S2', name: 'Jones' },
+      { sid: 'S3', name: 'Blake' },
+      { sid: 'S4', name: 'Clark' },
+      { sid: 'S5', name: 'Adams' },
+    ]);
+    expect(result.isEqual(expected)).to.be.true;
+  })
+
+  it('removes duplicates (set semantics)', () => {
+    // Keeping only status should yield 3 unique values, not 5 tuples
+    const result = SUPPLIERS.allbut(['sid', 'name', 'city']);
+    const expected = Bmg([
+      { status: 20 },
+      { status: 10 },
+      { status: 30 },
+    ]);
+    expect(result.isEqual(expected)).to.be.true;
+  })
+
+  it('keeps all attributes when excluding none', () => {
+    const result = SUPPLIERS.allbut([]);
+    expect(result.isEqual(SUPPLIERS)).to.be.true;
+  })
+
+  it('ignores non-existent attributes', () => {
+    // @ts-expect-error - testing runtime behavior with invalid attribute
+    const result = SUPPLIERS.allbut(['nonexistent']);
+    expect(result.isEqual(SUPPLIERS)).to.be.true;
+  })
+
+  ///
+
+  it('can be used standalone', () => {
+    const input = SUPPLIERS.toArray();
+    const res = allbut(input, ['status', 'city']);
+    const expected = SUPPLIERS.allbut(['status', 'city']);
+    expect(isEqual(res, expected)).to.be.true;
+  })
+
+});

package/tests/operators/autowrap.test.ts

@@ -0,0 +1,82 @@
+import { describe, it, expect } from 'vitest';
+import { Bmg } from 'src';
+import { autowrap , isEqual } from 'src/operators';
+
+describe('.autowrap', () => {
+
+  it('wraps attributes based on underscore separator by default', () => {
+    const flat = Bmg([
+      { id: 1, address_street: '123 Main', address_city: 'NYC' },
+    ]);
+    const result = flat.autowrap();
+    const tuple = result.one();
+    expect(tuple.id).to.eql(1);
+    expect(tuple.address).to.eql({ street: '123 Main', city: 'NYC' });
+  })
+
+  it('allows custom separator', () => {
+    const flat = Bmg([
+      { id: 1, 'address.street': '123 Main', 'address.city': 'NYC' },
+    ]);
+    const result = flat.autowrap({ separator: '.' });
+    const tuple = result.one();
+    expect(tuple.id).to.eql(1);
+    expect(tuple.address).to.eql({ street: '123 Main', city: 'NYC' });
+  })
+
+  it('handles attributes without separator', () => {
+    const flat = Bmg([
+      { id: 1, name: 'John' },
+    ]);
+    const result = flat.autowrap();
+    const tuple = result.one();
+    expect(tuple).to.eql({ id: 1, name: 'John' });
+  })
+
+  it('handles multiple prefixes', () => {
+    const flat = Bmg([
+      { id: 1, home_city: 'NYC', work_city: 'Boston' },
+    ]);
+    const result = flat.autowrap();
+    const tuple = result.one();
+    expect(tuple.id).to.eql(1);
+    expect(tuple.home).to.eql({ city: 'NYC' });
+    expect(tuple.work).to.eql({ city: 'Boston' });
+  })
+
+  it('handles nested separators (one level only)', () => {
+    const flat = Bmg([
+      { id: 1, address_home_city: 'NYC' },
+    ]);
+    const result = flat.autowrap();
+    const tuple = result.one();
+    expect(tuple.id).to.eql(1);
+    // Only first level split: address -> { home_city: 'NYC' }
+    expect(tuple.address).to.eql({ home_city: 'NYC' });
+  })
+
+  it('autowraps multiple tuples correctly', () => {
+    const flat = Bmg([
+      { id: 1, address_street: '123 Main', address_city: 'NYC' },
+      { id: 2, address_street: '456 Oak', address_city: 'Boston' },
+      { id: 3, address_street: '789 Pine', address_city: 'Chicago' },
+    ]);
+    const result = flat.autowrap();
+    const expected = Bmg([
+      { id: 1, address: { street: '123 Main', city: 'NYC' } },
+      { id: 2, address: { street: '456 Oak', city: 'Boston' } },
+      { id: 3, address: { street: '789 Pine', city: 'Chicago' } },
+    ]);
+    expect(result.isEqual(expected)).to.be.true;
+  })
+
+  ///
+
+  it('can be used standalone', () => {
+    const input = Bmg([{ id: 1, addr_city: 'NYC' }]);
+    const res = autowrap(input.toArray());
+    const expected = input.autowrap();
+    expect(isEqual(res, expected)).to.be.true;
+  })
+
+});

package/tests/operators/constants.test.ts

@@ -0,0 +1,37 @@
+import { describe, it, expect } from 'vitest';
+
+import { SUPPLIERS } from 'tests/fixtures';
+import { constants , isEqual } from 'src/operators';
+
+describe('.constants', () => {
+
+  it('adds constant attributes to all tuples', () => {
+    const withType = SUPPLIERS.constants({type: 'supplier'});
+    const smith = withType.restrict({sid: 'S1'}).one();
+    expect(smith.type).to.eql('supplier');
+    expect(smith.name).to.eql('Smith');
+  })
+
+  it('can add multiple constants', () => {
+    const result = SUPPLIERS.constants({type: 'supplier', active: true});
+    const jones = result.restrict({sid: 'S2'}).one();
+    expect(jones.type).to.eql('supplier');
+    expect(jones.active).to.eql(true);
+  })
+
+  it('overwrites existing attributes', () => {
+    const result = SUPPLIERS.constants({city: 'Unknown'});
+    const smith = result.restrict({sid: 'S1'}).one();
+    expect(smith.city).to.eql('Unknown');
+  })
+
+  ///
+
+  it('can be used standalone', () => {
+    const input = SUPPLIERS.toArray();
+    const res = constants(input, { type: 'supplier' });
+    const expected = SUPPLIERS.constants({ type: 'supplier' });
+    expect(isEqual(res, expected)).to.be.true;
+  })
+
+});

package/tests/operators/cross_product.test.ts

@@ -0,0 +1,90 @@
+import { describe, it, expect } from 'vitest';
+import { Bmg } from 'src';
+import { cross_product, cross_join , isEqual } from 'src/operators';
+
+describe('.cross_product', () => {
+
+  const colors = Bmg([
+    { color: 'red' },
+    { color: 'blue' },
+  ]);
+
+  const sizes = Bmg([
+    { size: 'S' },
+    { size: 'M' },
+    { size: 'L' },
+  ]);
+
+  it('computes cartesian product of two relations', () => {
+    const result = colors.cross_product(sizes);
+    const expected = Bmg([
+      { color: 'red', size: 'S' },
+      { color: 'red', size: 'M' },
+      { color: 'red', size: 'L' },
+      { color: 'blue', size: 'S' },
+      { color: 'blue', size: 'M' },
+      { color: 'blue', size: 'L' },
+    ]);
+    expect(result.isEqual(expected)).to.be.true;
+  })
+
+  it('cross_join is an alias for cross_product', () => {
+    const withCrossProduct = colors.cross_product(sizes);
+    const withCrossJoin = colors.cross_join(sizes);
+    expect(withCrossProduct.isEqual(withCrossJoin)).to.be.true;
+  })
+
+  it('handles DUM', () => {
+    const empty = Bmg([]);
+    const result = colors.cross_product(empty);
+    expect(result.toArray()).to.eql([]);
+  })
+
+  it('handles DEE', () => {
+    const empty = Bmg([{}]);
+    const result = colors.cross_product(empty);
+    expect(result.isEqual(colors)).to.be.true;
+  })
+
+  it('clashing right attributes are ignored', () => {
+    const left = Bmg([{ x: 1, y: 2 }]);
+    const right = Bmg([{ y: 100, z: 3 }]);
+    const result = left.cross_product(right);
+    const expected = Bmg([{ x: 1, y: 2, z: 3 }]);
+    expect(result.isEqual(expected)).to.be.true;
+  })
+
+  it('clashing right attributes are ignored with multiple tuples', () => {
+    const left = Bmg([
+      { x: 1, y: 'a' },
+      { x: 2, y: 'b' },
+    ]);
+    const right = Bmg([
+      { y: 'ignored', z: 10 },
+      { y: 'also_ignored', z: 20 },
+    ]);
+    const result = left.cross_product(right);
+    const expected = Bmg([
+      { x: 1, y: 'a', z: 10 },
+      { x: 1, y: 'a', z: 20 },
+      { x: 2, y: 'b', z: 10 },
+      { x: 2, y: 'b', z: 20 },
+    ]);
+    expect(result.isEqual(expected)).to.be.true;
+  })
+
+  ///
+
+  it('can be used standalone', () => {
+    const res = cross_product(colors.toArray(), sizes.toArray());
+    const expected = colors.cross_product(sizes);
+    expect(isEqual(res, expected)).to.be.true;
+  })
+
+  it('cross_join standalone is also available', () => {
+    const res = cross_join(colors.toArray(), sizes.toArray());
+    const expected = colors.cross_join(sizes);
+    expect(isEqual(res, expected)).to.be.true;
+  })
+
+});

package/tests/operators/exclude.test.ts

@@ -0,0 +1,43 @@
+import { describe, it, expect } from 'vitest';
+import { Bmg } from 'src';
+import { SUPPLIERS } from 'tests/fixtures';
+import { exclude , isEqual } from 'src/operators';
+
+describe('.exclude', () => {
+
+  it('filters out tuples matching the predicate', () => {
+    const nonParis = SUPPLIERS.exclude({city: 'Paris'});
+    const expected = Bmg([
+      {sid: 'S1', name: 'Smith', status: 20, city: 'London' },
+      {sid: 'S4', name: 'Clark', status: 20, city: 'London' },
+      {sid: 'S5', name: 'Adams', status: 30, city: 'Athens' },
+    ]);
+    expect(nonParis.isEqual(expected)).to.be.true;
+  })
+
+  it('works with a function predicate', () => {
+    const lowStatus = SUPPLIERS.exclude((t) => (t.status as number) >= 20);
+    const expected = Bmg([
+      {sid: 'S2', name: 'Jones', status: 10, city: 'Paris' },
+    ]);
+    expect(lowStatus.isEqual(expected)).to.be.true;
+  })
+
+  it('is the inverse of restrict', () => {
+    const restricted = SUPPLIERS.restrict({city: 'Paris'});
+    const excluded = SUPPLIERS.exclude({city: 'Paris'});
+    // Union of restrict and exclude should give the original relation
+    const reunion = restricted.union(excluded);
+    expect(reunion.isEqual(SUPPLIERS)).to.be.true;
+  })
+
+  ///
+
+  it('can be used standalone', () => {
+    const input = SUPPLIERS.toArray();
+    const res = exclude(input, { city: 'Paris' });
+    const expected = SUPPLIERS.exclude({ city: 'Paris' });
+    expect(isEqual(res, expected)).to.be.true;
+  })
+
+});

package/tests/operators/extend.test.ts

@@ -0,0 +1,45 @@
+import { describe, it, expect } from 'vitest';
+
+import { SUPPLIERS } from 'tests/fixtures';
+import { extend , isEqual } from 'src/operators';
+
+describe('.extend', () => {
+
+  it('adds computed attributes', () => {
+    const result = SUPPLIERS.extend({
+      statusLabel: (t) => `Status: ${t.status}`
+    });
+    const smith = result.restrict({ sid: 'S1' }).one();
+    expect(smith.statusLabel).to.eql('Status: 20');
+    expect(smith.name).to.eql('Smith');
+  })
+
+  it('copies attributes with string shortcut', () => {
+    const result = SUPPLIERS.extend({
+      location: 'city'
+    });
+    const smith = result.restrict({ sid: 'S1' }).one();
+    expect(smith.location).to.eql('London');
+    expect(smith.city).to.eql('London');
+  })
+
+  it('supports multiple extensions', () => {
+    const result = SUPPLIERS.extend({
+      location: 'city',
+      doubled: (t) => (t.status as number) * 2
+    });
+    const smith = result.restrict({ sid: 'S1' }).one();
+    expect(smith.location).to.eql('London');
+    expect(smith.doubled).to.eql(40);
+  })
+
+  ///
+
+  it('can be used standalone', () => {
+    const input = SUPPLIERS.toArray();
+    const res = extend(input, { location: 'city' });
+    const expected = SUPPLIERS.extend({ location: 'city' });
+    expect(isEqual(res, expected)).to.be.true;
+  })
+
+});

package/tests/operators/group.test.ts

@@ -0,0 +1,69 @@
+import { describe, it, expect } from 'vitest';
+import { Bmg } from 'src';
+import { group , isEqual } from 'src/operators';
+
+describe('.group', () => {
+
+  const orders = Bmg([
+    { order_id: 1, customer: 'Alice', item: 'Apple', qty: 2 },
+    { order_id: 1, customer: 'Alice', item: 'Banana', qty: 3 },
+    { order_id: 2, customer: 'Bob', item: 'Cherry', qty: 1 },
+  ]);
+
+  it('groups specified attributes into nested relation', () => {
+    const result = orders.group(['item', 'qty'], 'items');
+    const expected = Bmg([
+      {
+        order_id: 1,
+        customer: 'Alice',
+        items: Bmg([
+          { item: 'Apple', qty: 2 },
+          { item: 'Banana', qty: 3 },
+        ])
+      },
+      {
+        order_id: 2,
+        customer: 'Bob',
+        items: Bmg([
+          { item: 'Cherry', qty: 1 },
+        ])
+      },
+    ]);
+    expect(result.isEqual(expected)).to.be.true;
+  })
+
+  it('preserves non-grouped attributes', () => {
+    const result = orders.group(['item', 'qty'], 'items');
+    const bob = result.restrict({ customer: 'Bob' }).one();
+    expect(bob).to.have.property('order_id', 2);
+    expect(bob).to.have.property('customer', 'Bob');
+    expect(bob).to.have.property('items');
+    expect(Object.keys(bob).sort()).to.eql(['customer', 'items', 'order_id']);
+  })
+
+  it('handles single-item groups', () => {
+    const result = orders.group(['item', 'qty'], 'items');
+    const bobOnly = result.restrict({ customer: 'Bob' });
+    const expected = Bmg([{
+      order_id: 2,
+      customer: 'Bob',
+      items: Bmg([{ item: 'Cherry', qty: 1 }])
+    }]);
+    expect(bobOnly.isEqual(expected)).to.be.true;
+  })
+
+  it('handles empty relation', () => {
+    const empty = Bmg([]);
+    const result = empty.group(['x'], 'grouped');
+    expect(result.isEqual(Bmg([]))).to.be.true;
+  })
+
+  ///
+
+  it('can be used standalone', () => {
+    const res = group(orders.toArray(), ['item', 'qty'], 'items');
+    const expected = orders.group(['item', 'qty'], 'items');
+    expect(isEqual(res, expected)).to.be.true;
+  })
+
+});

package/tests/operators/image.test.ts

@@ -0,0 +1,152 @@
+import { describe, it, expect } from 'vitest';
+import { Bmg } from 'src';
+import { image , isEqual } from 'src/operators';
+
+describe('.image', () => {
+
+  const suppliers = Bmg([
+    { sid: 'S1', name: 'Smith', city: 'London' },
+    { sid: 'S2', name: 'Jones', city: 'Paris' },
+    { sid: 'S3', name: 'Blake', city: 'Paris' },
+  ]);
+
+  const shipments = Bmg([
+    { sid: 'S1', pid: 'P1', qty: 100 },
+    { sid: 'S1', pid: 'P2', qty: 200 },
+    { sid: 'S2', pid: 'P1', qty: 300 },
+  ]);
+
+  it('adds relation-valued attribute with matching tuples', () => {
+    const result = suppliers.image(shipments, 'shipments');
+    const expected = Bmg([
+      {
+        sid: 'S1', name: 'Smith', city: 'London',
+        shipments: Bmg([
+          { pid: 'P1', qty: 100 },
+          { pid: 'P2', qty: 200 },
+        ])
+      },
+      {
+        sid: 'S2', name: 'Jones', city: 'Paris',
+        shipments: Bmg([
+          { pid: 'P1', qty: 300 },
+        ])
+      },
+      {
+        sid: 'S3', name: 'Blake', city: 'Paris',
+        shipments: Bmg([])
+      },
+    ]);
+    expect(result.isEqual(expected)).to.be.true;
+  })
+
+  it('supports explicit keys as { left: right }', () => {
+    const cities = Bmg([
+      { location: 'London', country: 'UK' },
+      { location: 'Paris', country: 'France' },
+    ]);
+    const result = suppliers.image(cities, 'city_info', { city: 'location' });
+    const expected = Bmg([
+      { sid: 'S1', name: 'Smith', city: 'London', city_info: Bmg([{ country: 'UK' }]) },
+      { sid: 'S2', name: 'Jones', city: 'Paris', city_info: Bmg([{ country: 'France' }]) },
+      { sid: 'S3', name: 'Blake', city: 'Paris', city_info: Bmg([{ country: 'France' }]) },
+    ]);
+    expect(result.isEqual(expected)).to.be.true;
+  })
+
+  it('supports explicit keys as [common_attr]', () => {
+    const result = suppliers.image(shipments, 'shipments', ['sid']);
+    const expected = Bmg([
+      {
+        sid: 'S1', name: 'Smith', city: 'London',
+        shipments: Bmg([
+          { pid: 'P1', qty: 100 },
+          { pid: 'P2', qty: 200 },
+        ])
+      },
+      {
+        sid: 'S2', name: 'Jones', city: 'Paris',
+        shipments: Bmg([
+          { pid: 'P1', qty: 300 },
+        ])
+      },
+      {
+        sid: 'S3', name: 'Blake', city: 'Paris',
+        shipments: Bmg([])
+      },
+    ]);
+    expect(result.isEqual(expected)).to.be.true;
+  })
+
+  it('supports multiple attributes as join key', () => {
+    const inventory = Bmg([
+      { warehouse: 'W1', city: 'London', stock: 100 },
+      { warehouse: 'W2', city: 'London', stock: 200 },
+      { warehouse: 'W3', city: 'Paris', stock: 150 },
+    ]);
+    const orders = Bmg([
+      { warehouse: 'W1', city: 'London', item: 'A', qty: 10 },
+      { warehouse: 'W1', city: 'London', item: 'B', qty: 20 },
+      { warehouse: 'W3', city: 'Paris', item: 'C', qty: 30 },
+    ]);
+    const result = inventory.image(orders, 'orders', ['warehouse', 'city']);
+    const expected = Bmg([
+      {
+        warehouse: 'W1', city: 'London', stock: 100,
+        orders: Bmg([
+          { item: 'A', qty: 10 },
+          { item: 'B', qty: 20 },
+        ])
+      },
+      {
+        warehouse: 'W2', city: 'London', stock: 200,
+        orders: Bmg([])
+      },
+      {
+        warehouse: 'W3', city: 'Paris', stock: 150,
+        orders: Bmg([
+          { item: 'C', qty: 30 },
+        ])
+      },
+    ]);
+    expect(result.isEqual(expected)).to.be.true;
+  })
+
+  it('supports multiple attributes as { left: right } object', () => {
+    const people = Bmg([
+      { id: 1, first: 'John', last: 'Doe' },
+      { id: 2, first: 'Jane', last: 'Smith' },
+    ]);
+    const records = Bmg([
+      { fname: 'John', lname: 'Doe', year: 2020, score: 85 },
+      { fname: 'John', lname: 'Doe', year: 2021, score: 90 },
+      { fname: 'Jane', lname: 'Smith', year: 2020, score: 95 },
+    ]);
+    const result = people.image(records, 'scores', { first: 'fname', last: 'lname' });
+    const expected = Bmg([
+      {
+        id: 1, first: 'John', last: 'Doe',
+        scores: Bmg([
+          { year: 2020, score: 85 },
+          { year: 2021, score: 90 },
+        ])
+      },
+      {
+        id: 2, first: 'Jane', last: 'Smith',
+        scores: Bmg([
+          { year: 2020, score: 95 },
+        ])
+      },
+    ]);
+    expect(result.isEqual(expected)).to.be.true;
+  })
+
+  ///
+
+  it('can be used standalone', () => {
+    const res = image(suppliers.toArray(), shipments.toArray(), 'shipments');
+    const expected = suppliers.image(shipments, 'shipments');
+    expect(isEqual(res, expected)).to.be.true;
+  })
+
+});

package/tests/operators/intersect.test.ts

@@ -0,0 +1,53 @@
+import { describe, it, expect } from 'vitest';
+import { Bmg } from 'src';
+import { intersect , isEqual } from 'src/operators';
+
+describe('.intersect', () => {
+
+  const left = Bmg([
+    { id: 1, name: 'Alice' },
+    { id: 2, name: 'Bob' },
+    { id: 3, name: 'Charlie' },
+  ]);
+
+  const right = Bmg([
+    { id: 2, name: 'Bob' },
+    { id: 3, name: 'Charlie' },
+    { id: 4, name: 'Diana' },
+  ]);
+
+  it('returns tuples present in both relations', () => {
+    const result = left.intersect(right);
+    const expected = Bmg([
+      { id: 2, name: 'Bob' },
+      { id: 3, name: 'Charlie' },
+    ]);
+    expect(result.isEqual(expected)).to.be.true;
+  })
+
+  it('returns empty when no overlap', () => {
+    const other = Bmg([{ id: 99, name: 'Nobody' }]);
+    const result = left.intersect(other);
+    expect(result.isEqual(Bmg([]))).to.be.true;
+  })
+
+  it('returns all when identical', () => {
+    const result = left.intersect(left);
+    expect(result.isEqual(left)).to.be.true;
+  })
+
+  it('is commutative (set semantics)', () => {
+    const lr = left.intersect(right);
+    const rl = right.intersect(left);
+    expect(lr.isEqual(rl)).to.be.true;
+  })
+
+  ///
+
+  it('can be used standalone', () => {
+    const res = intersect(left.toArray(), right.toArray());
+    const expected = left.intersect(right);
+    expect(isEqual(res, expected)).to.be.true;
+  })
+
+});