@enspirit/bmg-js 1.0.0

package/tests/operators/isEqual.test.ts

@@ -0,0 +1,111 @@
+import { describe, it, expect } from 'vitest';
+import { Bmg } from 'src';
+import { isEqual } from 'src/operators';
+
+describe('.isEqual', () => {
+
+  it('returns true for identical relations', () => {
+    const r = Bmg([
+      { id: 1, name: 'Alice' },
+      { id: 2, name: 'Bob' },
+    ]);
+    expect(r.isEqual(r)).to.be.true;
+  })
+
+  it('returns true for relations with same tuples', () => {
+    const r1 = Bmg([
+      { id: 1, name: 'Alice' },
+      { id: 2, name: 'Bob' },
+    ]);
+    const r2 = Bmg([
+      { id: 1, name: 'Alice' },
+      { id: 2, name: 'Bob' },
+    ]);
+    expect(r1.isEqual(r2)).to.be.true;
+  })
+
+  it('returns true regardless of tuple order', () => {
+    const r1 = Bmg([
+      { id: 1, name: 'Alice' },
+      { id: 2, name: 'Bob' },
+    ]);
+    const r2 = Bmg([
+      { id: 2, name: 'Bob' },
+      { id: 1, name: 'Alice' },
+    ]);
+    expect(r1.isEqual(r2)).to.be.true;
+  })
+
+  it('returns true regardless of attribute order', () => {
+    const r1 = Bmg([
+      { id: 1, name: 'Alice' },
+    ]);
+    const r2 = Bmg([
+      { name: 'Alice', id: 1 },
+    ]);
+    expect(r1.isEqual(r2)).to.be.true;
+  })
+
+  it('ignores duplicates (set semantics)', () => {
+    const r1 = Bmg([
+      { id: 1, name: 'Alice' },
+      { id: 1, name: 'Alice' },
+    ]);
+    const r2 = Bmg([
+      { id: 1, name: 'Alice' },
+    ]);
+    expect(r1.isEqual(r2)).to.be.true;
+  })
+
+  it('returns false for different tuple count', () => {
+    const r1 = Bmg([
+      { id: 1, name: 'Alice' },
+      { id: 2, name: 'Bob' },
+    ]);
+    const r2 = Bmg([
+      { id: 1, name: 'Alice' },
+    ]);
+    expect(r1.isEqual(r2)).to.be.false;
+  })
+
+  it('returns false for different tuple values', () => {
+    const r1 = Bmg([
+      { id: 1, name: 'Alice' },
+    ]);
+    const r2 = Bmg([
+      { id: 1, name: 'Bob' },
+    ]);
+    expect(r1.isEqual(r2)).to.be.false;
+  })
+
+  it('returns false for different attributes', () => {
+    const r1 = Bmg([
+      { id: 1, name: 'Alice' },
+    ]);
+    const r2 = Bmg([
+      { id: 1, city: 'Paris' },
+    ]);
+    expect(r1.isEqual(r2)).to.be.false;
+  })
+
+  it('returns true for empty relations', () => {
+    const r1 = Bmg([]);
+    const r2 = Bmg([]);
+    expect(r1.isEqual(r2)).to.be.true;
+  })
+
+  ///
+
+  it('can be used standalone', () => {
+    const left = [{ id: 1, name: 'Alice' }];
+    const right = [{ name: 'Alice', id: 1 }];
+    expect(isEqual(left, right)).to.be.true;
+  })
+
+  it('works with array operand', () => {
+    const r = Bmg([{ id: 1, name: 'Alice' }]);
+    const arr = [{ id: 1, name: 'Alice' }];
+    expect(r.isEqual(arr)).to.be.true;
+  })
+
+});

package/tests/operators/join.test.ts

@@ -0,0 +1,116 @@
+import { describe, it, expect } from 'vitest';
+import { Bmg } from 'src';
+import { join , isEqual } from 'src/operators';
+
+describe('.join', () => {
+
+  const suppliers = Bmg([
+    { sid: 'S1', name: 'Smith', city: 'London' },
+    { sid: 'S2', name: 'Jones', city: 'Paris' },
+    { sid: 'S3', name: 'Blake', city: 'Paris' },
+  ]);
+
+  const parts = Bmg([
+    { pid: 'P1', pname: 'Nut', city: 'London' },
+    { pid: 'P2', pname: 'Bolt', city: 'Paris' },
+    { pid: 'P3', pname: 'Screw', city: 'Athens' },
+  ]);
+
+  it('performs natural join on common attributes', () => {
+    const result = suppliers.join(parts);
+    const expected = Bmg([
+      { sid: 'S1', name: 'Smith', city: 'London', pid: 'P1', pname: 'Nut' },
+      { sid: 'S2', name: 'Jones', city: 'Paris', pid: 'P2', pname: 'Bolt' },
+      { sid: 'S3', name: 'Blake', city: 'Paris', pid: 'P2', pname: 'Bolt' },
+    ]);
+    expect(result.isEqual(expected)).to.be.true;
+  })
+
+  it('joins on specified attributes as [common_attr]', () => {
+    const result = suppliers.join(parts, ['city']);
+    const expected = Bmg([
+      { sid: 'S1', name: 'Smith', city: 'London', pid: 'P1', pname: 'Nut' },
+      { sid: 'S2', name: 'Jones', city: 'Paris', pid: 'P2', pname: 'Bolt' },
+      { sid: 'S3', name: 'Blake', city: 'Paris', pid: 'P2', pname: 'Bolt' },
+    ]);
+    expect(result.isEqual(expected)).to.be.true;
+  })
+
+  it('joins on multiple attributes as [attr1, attr2]', () => {
+    const inventory = Bmg([
+      { warehouse: 'W1', city: 'London', stock: 100 },
+      { warehouse: 'W2', city: 'London', stock: 200 },
+      { warehouse: 'W1', city: 'Paris', stock: 150 },
+    ]);
+    const shipments = Bmg([
+      { warehouse: 'W1', city: 'London', qty: 10 },
+      { warehouse: 'W1', city: 'Paris', qty: 20 },
+    ]);
+    const result = inventory.join(shipments, ['warehouse', 'city']);
+    const expected = Bmg([
+      { warehouse: 'W1', city: 'London', stock: 100, qty: 10 },
+      { warehouse: 'W1', city: 'Paris', stock: 150, qty: 20 },
+    ]);
+    expect(result.isEqual(expected)).to.be.true;
+  })
+
+  it('joins on different attribute names as { left: right }', () => {
+    const locations = Bmg([
+      { location: 'London', country: 'UK' },
+      { location: 'Paris', country: 'France' },
+    ]);
+    const result = suppliers.join(locations, { city: 'location' });
+    const expected = Bmg([
+      { sid: 'S1', name: 'Smith', city: 'London', country: 'UK' },
+      { sid: 'S2', name: 'Jones', city: 'Paris', country: 'France' },
+      { sid: 'S3', name: 'Blake', city: 'Paris', country: 'France' },
+    ]);
+    expect(result.isEqual(expected)).to.be.true;
+  })
+
+  it('joins on multiple different attribute names as { left1: right1, left2: right2 }', () => {
+    const people = Bmg([
+      { id: 1, first: 'John', last: 'Doe' },
+      { id: 2, first: 'Jane', last: 'Smith' },
+      { id: 3, first: 'John', last: 'Smith' },
+    ]);
+    const records = Bmg([
+      { fname: 'John', lname: 'Doe', score: 85 },
+      { fname: 'Jane', lname: 'Smith', score: 90 },
+    ]);
+    const result = people.join(records, { first: 'fname', last: 'lname' });
+    const expected = Bmg([
+      { id: 1, first: 'John', last: 'Doe', score: 85 },
+      { id: 2, first: 'Jane', last: 'Smith', score: 90 },
+    ]);
+    expect(result.isEqual(expected)).to.be.true;
+  })
+
+  it('returns empty for no matches', () => {
+    const other = Bmg([{ city: 'Tokyo' }]);
+    const result = suppliers.join(other);
+    expect(result.isEqual(Bmg([]))).to.be.true;
+  })
+
+  it('handles cartesian product when no common attrs', () => {
+    const colors = Bmg([{ color: 'red' }, { color: 'blue' }]);
+    const sizes = Bmg([{ size: 'S' }, { size: 'M' }]);
+    const result = colors.join(sizes);
+    const expected = Bmg([
+      { color: 'red', size: 'S' },
+      { color: 'red', size: 'M' },
+      { color: 'blue', size: 'S' },
+      { color: 'blue', size: 'M' },
+    ]);
+    expect(result.isEqual(expected)).to.be.true;
+  })
+
+  ///
+
+  it('can be used standalone', () => {
+    const res = join(suppliers.toArray(), parts.toArray(), ['city']);
+    const expected = suppliers.join(parts, ['city']);
+    expect(isEqual(res, expected)).to.be.true;
+  })
+
+});

package/tests/operators/left_join.test.ts

@@ -0,0 +1,116 @@
+import { describe, it, expect } from 'vitest';
+import { Bmg } from 'src';
+import { left_join , isEqual } from 'src/operators';
+
+describe('.left_join', () => {
+
+  const orders = Bmg([
+    { oid: 1, customer_id: 'C1', amount: 100 },
+    { oid: 2, customer_id: 'C2', amount: 200 },
+    { oid: 3, customer_id: 'C3', amount: 150 },
+  ]);
+
+  const customers = Bmg([
+    { customer_id: 'C1', name: 'Alice' },
+    { customer_id: 'C2', name: 'Bob' },
+  ]);
+
+  it('joins matching tuples and keeps non-matching with null', () => {
+    const result = orders.left_join(customers);
+    const expected = Bmg([
+      { oid: 1, customer_id: 'C1', amount: 100, name: 'Alice' },
+      { oid: 2, customer_id: 'C2', amount: 200, name: 'Bob' },
+      { oid: 3, customer_id: 'C3', amount: 150, name: null },
+    ]);
+    expect(result.isEqual(expected)).to.be.true;
+  })
+
+  it('supports explicit keys as { left: right }', () => {
+    const suppliers = Bmg([
+      { sid: 'S1', city: 'London' },
+      { sid: 'S2', city: 'Paris' },
+      { sid: 'S3', city: 'Athens' },
+    ]);
+    const cities = Bmg([
+      { location: 'London', country: 'UK' },
+      { location: 'Paris', country: 'France' },
+    ]);
+    const result = suppliers.left_join(cities, { city: 'location' });
+    const expected = Bmg([
+      { sid: 'S1', city: 'London', country: 'UK' },
+      { sid: 'S2', city: 'Paris', country: 'France' },
+      { sid: 'S3', city: 'Athens', country: null },
+    ]);
+    expect(result.isEqual(expected)).to.be.true;
+  })
+
+  it('supports explicit keys as [common_attr]', () => {
+    const result = orders.left_join(customers, ['customer_id']);
+    const expected = Bmg([
+      { oid: 1, customer_id: 'C1', amount: 100, name: 'Alice' },
+      { oid: 2, customer_id: 'C2', amount: 200, name: 'Bob' },
+      { oid: 3, customer_id: 'C3', amount: 150, name: null },
+    ]);
+    expect(result.isEqual(expected)).to.be.true;
+  })
+
+  it('supports multiple keys as [attr1, attr2]', () => {
+    const inventory = Bmg([
+      { warehouse: 'W1', city: 'London', stock: 100 },
+      { warehouse: 'W2', city: 'London', stock: 200 },
+      { warehouse: 'W1', city: 'Paris', stock: 150 },
+    ]);
+    const shipments = Bmg([
+      { warehouse: 'W1', city: 'London', shipped: 50 },
+    ]);
+    const result = inventory.left_join(shipments, ['warehouse', 'city']);
+    const expected = Bmg([
+      { warehouse: 'W1', city: 'London', stock: 100, shipped: 50 },
+      { warehouse: 'W2', city: 'London', stock: 200, shipped: null },
+      { warehouse: 'W1', city: 'Paris', stock: 150, shipped: null },
+    ]);
+    expect(result.isEqual(expected)).to.be.true;
+  })
+
+  it('supports multiple keys as { left1: right1, left2: right2 }', () => {
+    const people = Bmg([
+      { id: 1, first: 'John', last: 'Doe' },
+      { id: 2, first: 'Jane', last: 'Smith' },
+      { id: 3, first: 'John', last: 'Smith' },
+    ]);
+    const records = Bmg([
+      { fname: 'John', lname: 'Doe', score: 85 },
+      { fname: 'Jane', lname: 'Smith', score: 90 },
+    ]);
+    const result = people.left_join(records, { first: 'fname', last: 'lname' });
+    const expected = Bmg([
+      { id: 1, first: 'John', last: 'Doe', score: 85 },
+      { id: 2, first: 'Jane', last: 'Smith', score: 90 },
+      { id: 3, first: 'John', last: 'Smith', score: null },
+    ]);
+    expect(result.isEqual(expected)).to.be.true;
+  })
+
+  it('handles multiple matches', () => {
+    const left = Bmg([{ id: 1, city: 'Paris' }]);
+    const right = Bmg([
+      { city: 'Paris', name: 'A' },
+      { city: 'Paris', name: 'B' },
+    ]);
+    const result = left.left_join(right);
+    const expected = Bmg([
+      { id: 1, city: 'Paris', name: 'A' },
+      { id: 1, city: 'Paris', name: 'B' },
+    ]);
+    expect(result.isEqual(expected)).to.be.true;
+  })
+
+  ///
+
+  it('can be used standalone', () => {
+    const res = left_join(orders.toArray(), customers.toArray());
+    const expected = orders.left_join(customers);
+    expect(isEqual(res, expected)).to.be.true;
+  })
+
+});

package/tests/operators/matching.test.ts

@@ -0,0 +1,91 @@
+import { describe, it, expect } from 'vitest';
+import { Bmg } from 'src';
+import { matching , isEqual } from 'src/operators';
+
+describe('.matching', () => {
+
+  const orders = Bmg([
+    { oid: 1, customer_id: 'C1', amount: 100 },
+    { oid: 2, customer_id: 'C2', amount: 200 },
+    { oid: 3, customer_id: 'C3', amount: 150 },
+  ]);
+
+  const customers = Bmg([
+    { customer_id: 'C1', name: 'Alice' },
+    { customer_id: 'C2', name: 'Bob' },
+  ]);
+
+  it('returns tuples from left that match right on common attrs', () => {
+    const result = orders.matching(customers);
+    const expected = Bmg([
+      { oid: 1, customer_id: 'C1', amount: 100 },
+      { oid: 2, customer_id: 'C2', amount: 200 },
+    ]);
+    expect(result.isEqual(expected)).to.be.true;
+  })
+
+  it('supports explicit keys as [common_attr]', () => {
+    const result = orders.matching(customers, ['customer_id']);
+    const expected = Bmg([
+      { oid: 1, customer_id: 'C1', amount: 100 },
+      { oid: 2, customer_id: 'C2', amount: 200 },
+    ]);
+    expect(result.isEqual(expected)).to.be.true;
+  })
+
+  it('supports multiple keys as [attr1, attr2]', () => {
+    const inventory = Bmg([
+      { warehouse: 'W1', city: 'London', stock: 100 },
+      { warehouse: 'W2', city: 'London', stock: 200 },
+      { warehouse: 'W1', city: 'Paris', stock: 150 },
+    ]);
+    const shipments = Bmg([
+      { warehouse: 'W1', city: 'London' },
+      { warehouse: 'W1', city: 'Paris' },
+    ]);
+    const result = inventory.matching(shipments, ['warehouse', 'city']);
+    const expected = Bmg([
+      { warehouse: 'W1', city: 'London', stock: 100 },
+      { warehouse: 'W1', city: 'Paris', stock: 150 },
+    ]);
+    expect(result.isEqual(expected)).to.be.true;
+  })
+
+  it('supports explicit keys as { left: right }', () => {
+    const suppliers = Bmg([
+      { sid: 'S1', city: 'London' },
+      { sid: 'S2', city: 'Paris' },
+    ]);
+    const cities = Bmg([{ location: 'London' }]);
+    const result = suppliers.matching(cities, { city: 'location' });
+    const expected = Bmg([{ sid: 'S1', city: 'London' }]);
+    expect(result.isEqual(expected)).to.be.true;
+  })
+
+  it('supports multiple keys as { left1: right1, left2: right2 }', () => {
+    const people = Bmg([
+      { id: 1, first: 'John', last: 'Doe' },
+      { id: 2, first: 'Jane', last: 'Smith' },
+      { id: 3, first: 'John', last: 'Smith' },
+    ]);
+    const records = Bmg([
+      { fname: 'John', lname: 'Doe' },
+      { fname: 'Jane', lname: 'Smith' },
+    ]);
+    const result = people.matching(records, { first: 'fname', last: 'lname' });
+    const expected = Bmg([
+      { id: 1, first: 'John', last: 'Doe' },
+      { id: 2, first: 'Jane', last: 'Smith' },
+    ]);
+    expect(result.isEqual(expected)).to.be.true;
+  })
+
+  ///
+
+  it('can be used standalone', () => {
+    const res = matching(orders.toArray(), customers.toArray());
+    const expected = orders.matching(customers);
+    expect(isEqual(res, expected)).to.be.true;
+  })
+
+});

package/tests/operators/minus.test.ts

@@ -0,0 +1,47 @@
+import { describe, it, expect } from 'vitest';
+import { Bmg } from 'src';
+import { minus , isEqual } from 'src/operators';
+
+describe('.minus', () => {
+
+  const left = Bmg([
+    { id: 1, name: 'Alice' },
+    { id: 2, name: 'Bob' },
+    { id: 3, name: 'Charlie' },
+  ]);
+
+  const right = Bmg([
+    { id: 2, name: 'Bob' },
+    { id: 4, name: 'Diana' },
+  ]);
+
+  it('returns tuples in left but not in right', () => {
+    const result = left.minus(right);
+    const expected = Bmg([
+      { id: 1, name: 'Alice' },
+      { id: 3, name: 'Charlie' },
+    ]);
+    expect(result.isEqual(expected)).to.be.true;
+  })
+
+  it('returns empty when left is subset of right', () => {
+    const small = Bmg([{ id: 2, name: 'Bob' }]);
+    const result = small.minus(right);
+    expect(result.isEqual(Bmg([]))).to.be.true;
+  })
+
+  it('returns all when no overlap', () => {
+    const other = Bmg([{ id: 99, name: 'Nobody' }]);
+    const result = left.minus(other);
+    expect(result.isEqual(left)).to.be.true;
+  })
+
+  ///
+
+  it('can be used standalone', () => {
+    const res = minus(left.toArray(), right.toArray());
+    const expected = left.minus(right);
+    expect(isEqual(res, expected)).to.be.true;
+  })
+
+});

package/tests/operators/not_matching.test.ts

@@ -0,0 +1,104 @@
+import { describe, it, expect } from 'vitest';
+import { Bmg } from 'src';
+import { not_matching , isEqual } from 'src/operators';
+
+describe('.not_matching', () => {
+
+  const orders = Bmg([
+    { oid: 1, customer_id: 'C1', amount: 100 },
+    { oid: 2, customer_id: 'C2', amount: 200 },
+    { oid: 3, customer_id: 'C3', amount: 150 },
+  ]);
+
+  const customers = Bmg([
+    { customer_id: 'C1', name: 'Alice' },
+    { customer_id: 'C2', name: 'Bob' },
+  ]);
+
+  it('returns tuples from left that do NOT match right', () => {
+    const result = orders.not_matching(customers);
+    const expected = Bmg([
+      { oid: 3, customer_id: 'C3', amount: 150 },
+    ]);
+    expect(result.isEqual(expected)).to.be.true;
+  })
+
+  it('returns all when no matches', () => {
+    const empty = Bmg([{ customer_id: 'C99' }]);
+    const result = orders.not_matching(empty);
+    expect(result.isEqual(orders)).to.be.true;
+  })
+
+  it('returns empty when all match', () => {
+    const all = Bmg([
+      { customer_id: 'C1' },
+      { customer_id: 'C2' },
+      { customer_id: 'C3' },
+    ]);
+    const result = orders.not_matching(all);
+    expect(result.isEqual(Bmg([]))).to.be.true;
+  })
+
+  it('supports explicit keys as [common_attr]', () => {
+    const result = orders.not_matching(customers, ['customer_id']);
+    const expected = Bmg([
+      { oid: 3, customer_id: 'C3', amount: 150 },
+    ]);
+    expect(result.isEqual(expected)).to.be.true;
+  })
+
+  it('supports multiple keys as [attr1, attr2]', () => {
+    const inventory = Bmg([
+      { warehouse: 'W1', city: 'London', stock: 100 },
+      { warehouse: 'W2', city: 'London', stock: 200 },
+      { warehouse: 'W1', city: 'Paris', stock: 150 },
+    ]);
+    const shipments = Bmg([
+      { warehouse: 'W1', city: 'London' },
+    ]);
+    const result = inventory.not_matching(shipments, ['warehouse', 'city']);
+    const expected = Bmg([
+      { warehouse: 'W2', city: 'London', stock: 200 },
+      { warehouse: 'W1', city: 'Paris', stock: 150 },
+    ]);
+    expect(result.isEqual(expected)).to.be.true;
+  })
+
+  it('supports explicit keys as { left: right }', () => {
+    const suppliers = Bmg([
+      { sid: 'S1', city: 'London' },
+      { sid: 'S2', city: 'Paris' },
+      { sid: 'S3', city: 'Athens' },
+    ]);
+    const cities = Bmg([{ location: 'London' }, { location: 'Paris' }]);
+    const result = suppliers.not_matching(cities, { city: 'location' });
+    const expected = Bmg([{ sid: 'S3', city: 'Athens' }]);
+    expect(result.isEqual(expected)).to.be.true;
+  })
+
+  it('supports multiple keys as { left1: right1, left2: right2 }', () => {
+    const people = Bmg([
+      { id: 1, first: 'John', last: 'Doe' },
+      { id: 2, first: 'Jane', last: 'Smith' },
+      { id: 3, first: 'John', last: 'Smith' },
+    ]);
+    const records = Bmg([
+      { fname: 'John', lname: 'Doe' },
+      { fname: 'Jane', lname: 'Smith' },
+    ]);
+    const result = people.not_matching(records, { first: 'fname', last: 'lname' });
+    const expected = Bmg([
+      { id: 3, first: 'John', last: 'Smith' },
+    ]);
+    expect(result.isEqual(expected)).to.be.true;
+  })
+
+  ///
+
+  it('can be used standalone', () => {
+    const res = not_matching(orders.toArray(), customers.toArray());
+    const expected = orders.not_matching(customers);
+    expect(isEqual(res, expected)).to.be.true;
+  })
+
+});

package/tests/operators/one.test.ts

@@ -0,0 +1,19 @@
+import { describe, it, expect } from 'vitest';
+import { SUPPLIERS } from 'tests/fixtures';
+import { one } from 'src/operators';
+
+describe('.one', () => {
+
+  it('is available on relations', () => {
+    expect(typeof SUPPLIERS.one).to.eql('function')
+  })
+
+  ///
+
+  it('can be used standalone', () => {
+    const tuple = { sid: 'S1' }
+    const tuples = [tuple]
+    expect(one(tuples)).to.eql(tuple)
+  })
+
+});

package/tests/operators/prefix.test.ts

@@ -0,0 +1,37 @@
+import { describe, it, expect } from 'vitest';
+import { Bmg } from 'src';
+import { SUPPLIERS } from 'tests/fixtures';
+import { prefix , isEqual } from 'src/operators';
+
+describe('.prefix', () => {
+
+  it('prefixes all attribute names', () => {
+    const prefixed = SUPPLIERS.prefix('supplier_');
+    const expected = Bmg([
+      {supplier_sid: 'S1', supplier_name: 'Smith', supplier_status: 20, supplier_city: 'London' },
+      {supplier_sid: 'S2', supplier_name: 'Jones', supplier_status: 10, supplier_city: 'Paris' },
+      {supplier_sid: 'S3', supplier_name: 'Blake', supplier_status: 30, supplier_city: 'Paris' },
+      {supplier_sid: 'S4', supplier_name: 'Clark', supplier_status: 20, supplier_city: 'London' },
+      {supplier_sid: 'S5', supplier_name: 'Adams', supplier_status: 30, supplier_city: 'Athens' },
+    ]);
+    expect(prefixed.isEqual(expected)).to.be.true;
+  })
+
+  it('can exclude specific attributes', () => {
+    const prefixed = SUPPLIERS.prefix('s_', { except: ['sid'] });
+    const smith = prefixed.restrict({sid: 'S1'}).one();
+    expect(smith).to.have.property('sid', 'S1');
+    expect(smith).to.have.property('s_name', 'Smith');
+    expect(smith).to.have.property('s_city', 'London');
+  })
+
+  ///
+
+  it('can be used standalone', () => {
+    const input = SUPPLIERS.toArray();
+    const res = prefix(input, 'x_');
+    const expected = SUPPLIERS.prefix('x_');
+    expect(isEqual(res, expected)).to.be.true;
+  })
+
+});

package/tests/operators/project.test.ts

@@ -0,0 +1,48 @@
+import { describe, it, expect } from 'vitest';
+import { Bmg } from 'src';
+import { SUPPLIERS } from 'tests/fixtures';
+import { project , isEqual } from 'src/operators';
+
+describe('.project', () => {
+
+  it('keeps only specified attributes', () => {
+    const result = SUPPLIERS.project(['name', 'city']);
+    const expected = Bmg([
+      { name: 'Smith', city: 'London' },
+      { name: 'Jones', city: 'Paris' },
+      { name: 'Blake', city: 'Paris' },
+      { name: 'Clark', city: 'London' },
+      { name: 'Adams', city: 'Athens' },
+    ]);
+    expect(result.isEqual(expected)).to.be.true;
+  })
+
+  it('removes duplicates (set semantics)', () => {
+    // Projecting to 'city' only should yield 3 unique cities, not 5 tuples
+    const result = SUPPLIERS.project(['city']);
+    const expected = Bmg([
+      { city: 'London' },
+      { city: 'Paris' },
+      { city: 'Athens' },
+    ]);
+    expect(result.isEqual(expected)).to.be.true;
+  })
+
+  it('ignores missing attributes', () => {
+    // @ts-expect-error - testing runtime behavior with invalid attribute
+    const result = SUPPLIERS.project(['name', 'nonexistent']);
+    const smith = result.restrict({ name: 'Smith' }).one();
+    expect(smith).to.have.property('name');
+    expect(smith).to.not.have.property('nonexistent');
+  })
+
+  ///
+
+  it('can be used standalone', () => {
+    const input = SUPPLIERS.toArray();
+    const res = project(input, ['name', 'city']);
+    const expected = SUPPLIERS.project(['name', 'city']);
+    expect(isEqual(res, expected)).to.be.true;
+  })
+
+});