@enspirit/bmg-js 1.0.0

package/tests/operators/rename.test.ts

@@ -0,0 +1,39 @@
+import { describe, it, expect } from 'vitest';
+import { Bmg } from 'src';
+import { SUPPLIERS } from 'tests/fixtures';
+import { rename , isEqual } from 'src/operators';
+
+describe('.rename', () => {
+
+  const renaming = {sid: 'id', name: 'lastname'}
+
+  it('allows renaming relation tuples', () => {
+    const renamed = SUPPLIERS.rename(renaming);
+    const expected = Bmg([
+      {id: 'S1', lastname: 'Smith', status: 20, city: 'London' },
+      {id: 'S2', lastname: 'Jones', status: 10, city: 'Paris' },
+      {id: 'S3', lastname: 'Blake', status: 30, city: 'Paris' },
+      {id: 'S4', lastname: 'Clark', status: 20, city: 'London' },
+      {id: 'S5', lastname: 'Adams', status: 30, city: 'Athens' },
+    ]);
+    expect(renamed.isEqual(expected)).to.be.true;
+  })
+
+  ///
+
+  it('can be used standalone', () => {
+    const input = SUPPLIERS.toArray();
+    const res = rename(input, renaming);
+    const expected = SUPPLIERS.rename(renaming);
+    expect(isEqual(res, expected)).to.be.true;
+  })
+
+  it('supports a pure function', () => {
+    const input = SUPPLIERS.toArray();
+    const renamed = rename(input, (attr) => attr.toUpperCase()) as any[];
+    const smith = Bmg(renamed).restrict({ SID: 'S1' }).one();
+    const keys = Object.keys(smith).sort();
+    expect(keys).to.eql(['CITY', 'NAME', 'SID', 'STATUS']);
+  })
+
+});

package/tests/operators/restrict.test.ts

@@ -0,0 +1,27 @@
+import { describe, it, expect } from 'vitest';
+
+import { SUPPLIERS } from 'tests/fixtures';
+import { restrict , isEqual } from 'src/operators';
+
+describe('.restrict', () => {
+
+  it('allows filtering relations', () => {
+    const smith = SUPPLIERS.restrict((t) => t.sid === 'S1').one()
+    expect(smith.name).to.eql('Smith')
+  })
+
+  it('has a tuple shortcut', () => {
+    const smith = SUPPLIERS.restrict({sid: 'S1'}).one()
+    expect(smith.name).to.eql('Smith')
+  })
+
+  ///
+
+  it('can be used standalone', () => {
+    const input = SUPPLIERS.toArray();
+    const res = restrict(input, { sid: 'S1' });
+    const expected = SUPPLIERS.restrict({ sid: 'S1' });
+    expect(isEqual(res, expected)).to.be.true;
+  })
+
+});

package/tests/operators/suffix.test.ts

@@ -0,0 +1,37 @@
+import { describe, it, expect } from 'vitest';
+import { Bmg } from 'src';
+import { SUPPLIERS } from 'tests/fixtures';
+import { suffix , isEqual } from 'src/operators';
+
+describe('.suffix', () => {
+
+  it('suffixes all attribute names', () => {
+    const suffixed = SUPPLIERS.suffix('_s');
+    const expected = Bmg([
+      {sid_s: 'S1', name_s: 'Smith', status_s: 20, city_s: 'London' },
+      {sid_s: 'S2', name_s: 'Jones', status_s: 10, city_s: 'Paris' },
+      {sid_s: 'S3', name_s: 'Blake', status_s: 30, city_s: 'Paris' },
+      {sid_s: 'S4', name_s: 'Clark', status_s: 20, city_s: 'London' },
+      {sid_s: 'S5', name_s: 'Adams', status_s: 30, city_s: 'Athens' },
+    ]);
+    expect(suffixed.isEqual(expected)).to.be.true;
+  })
+
+  it('can exclude specific attributes', () => {
+    const suffixed = SUPPLIERS.suffix('_x', { except: ['sid'] });
+    const smith = suffixed.restrict({sid: 'S1'}).one();
+    expect(smith).to.have.property('sid', 'S1');
+    expect(smith).to.have.property('name_x', 'Smith');
+    expect(smith).to.have.property('city_x', 'London');
+  })
+
+  ///
+
+  it('can be used standalone', () => {
+    const input = SUPPLIERS.toArray();
+    const res = suffix(input, '_y');
+    const expected = SUPPLIERS.suffix('_y');
+    expect(isEqual(res, expected)).to.be.true;
+  })
+
+});

package/tests/operators/summarize.test.ts

@@ -0,0 +1,109 @@
+import { describe, it, expect } from 'vitest';
+import { SUPPLIERS } from 'tests/fixtures';
+import { Bmg } from 'src';
+import { summarize, isEqual } from 'src/operators';
+
+describe('.summarize', () => {
+
+  it('counts tuples per group', () => {
+    const result = SUPPLIERS.summarize(['city'], { count: 'count' });
+    const expected = Bmg([
+      { city: 'London', count: 2 },
+      { city: 'Paris', count: 2 },
+      { city: 'Athens', count: 1 },
+    ]);
+    expect(result.isEqual(expected)).to.be.true;
+  })
+
+  it('sums values per group', () => {
+    const result = SUPPLIERS.summarize(['city'], {
+      totalStatus: { op: 'sum', attr: 'status' }
+    });
+    const expected = Bmg([
+      { city: 'London', totalStatus: 40 },  // 20 + 20
+      { city: 'Paris', totalStatus: 40 },   // 10 + 30
+      { city: 'Athens', totalStatus: 30 },
+    ]);
+    expect(result.isEqual(expected)).to.be.true;
+  })
+
+  it('computes min/max per group', () => {
+    const result = SUPPLIERS.summarize(['city'], {
+      minStatus: { op: 'min', attr: 'status' },
+      maxStatus: { op: 'max', attr: 'status' }
+    });
+    const expected = Bmg([
+      { city: 'London', minStatus: 20, maxStatus: 20 },
+      { city: 'Paris', minStatus: 10, maxStatus: 30 },
+      { city: 'Athens', minStatus: 30, maxStatus: 30 },
+    ]);
+    expect(result.isEqual(expected)).to.be.true;
+  })
+
+  it('computes average per group', () => {
+    const result = SUPPLIERS.summarize(['city'], {
+      avgStatus: { op: 'avg', attr: 'status' }
+    });
+    const expected = Bmg([
+      { city: 'London', avgStatus: 20 },   // (20 + 20) / 2
+      { city: 'Paris', avgStatus: 20 },    // (10 + 30) / 2
+      { city: 'Athens', avgStatus: 30 },
+    ]);
+    expect(result.isEqual(expected)).to.be.true;
+  })
+
+  it('collects values per group', () => {
+    const result = SUPPLIERS.summarize(['city'], {
+      names: { op: 'collect', attr: 'name' }
+    });
+    // collect returns arrays - check specific group
+    const paris = result.restrict({ city: 'Paris' }).one();
+    expect(paris.names).to.include('Jones');
+    expect(paris.names).to.include('Blake');
+  })
+
+  it('supports custom aggregator functions', () => {
+    const data = Bmg([
+      { city: 'NYC', name: 'Alice' },
+      { city: 'NYC', name: 'Bob' },
+    ]);
+    const result = data.summarize(['city'], {
+      names: (tuples) => tuples.map(t => t.name).sort().join(', ')
+    });
+    const expected = Bmg([
+      { city: 'NYC', names: 'Alice, Bob' }
+    ]);
+    expect(result.isEqual(expected)).to.be.true;
+  })
+
+  it('supports multiple group-by attributes', () => {
+    const data = Bmg([
+      { a: 1, b: 'x', v: 10 },
+      { a: 1, b: 'x', v: 20 },
+      { a: 1, b: 'y', v: 30 },
+      { a: 2, b: 'x', v: 40 },
+    ]);
+    const result = data.summarize(['a', 'b'], { sum: { op: 'sum', attr: 'v' } });
+    const expected = Bmg([
+      { a: 1, b: 'x', sum: 30 },
+      { a: 1, b: 'y', sum: 30 },
+      { a: 2, b: 'x', sum: 40 },
+    ]);
+    expect(result.isEqual(expected)).to.be.true;
+  })
+
+  it('handles empty by array (grand total)', () => {
+    const result = SUPPLIERS.summarize([], { total: 'count' });
+    const expected = Bmg([{ total: 5 }]);
+    expect(result.isEqual(expected)).to.be.true;
+  })
+
+  ///
+
+  it('can be used standalone', () => {
+    const standalone = summarize(SUPPLIERS.toArray(), ['city'], { count: 'count' });
+    const expected = SUPPLIERS.summarize(['city'], { count: 'count' });
+    expect(isEqual(standalone, expected)).to.be.true;
+  })
+
+});

package/tests/operators/transform.test.ts

@@ -0,0 +1,94 @@
+import { describe, it, expect } from 'vitest';
+import { Bmg } from 'src';
+import { transform, isEqual } from 'src/operators';
+
+describe('.transform', () => {
+
+  it('applies a function to all attribute values', () => {
+    const data = Bmg([
+      { id: 1, value: 10 },
+      { id: 2, value: 20 },
+    ]);
+    const result = data.transform(String);
+    const expected = Bmg([
+      { id: '1', value: '10' },
+      { id: '2', value: '20' },
+    ]);
+    expect(result.isEqual(expected)).to.be.true;
+  })
+
+  it('applies specific functions to named attributes', () => {
+    const data = Bmg([
+      { name: 'alice', status: 10, city: 'NYC' },
+      { name: 'bob', status: 20, city: 'LA' },
+    ]);
+    const result = data.transform({
+      name: (v) => (v as string).toUpperCase(),
+      status: (v) => (v as number) * 2
+    });
+    const expected = Bmg([
+      { name: 'ALICE', status: 20, city: 'NYC' },
+      { name: 'BOB', status: 40, city: 'LA' },
+    ]);
+    expect(result.isEqual(expected)).to.be.true;
+  })
+
+  it('chains multiple transformations with array', () => {
+    const data = Bmg([
+      { id: 1, value: 10 },
+      { id: 2, value: 20 },
+    ]);
+    const result = data.transform([
+      String,
+      (v) => `[${v}]`
+    ]);
+    const expected = Bmg([
+      { id: '[1]', value: '[10]' },
+      { id: '[2]', value: '[20]' },
+    ]);
+    expect(result.isEqual(expected)).to.be.true;
+  })
+
+  it('chains per-attribute transformations', () => {
+    const data = Bmg([
+      { name: 'Alice' },
+      { name: 'Bob' },
+    ]);
+    const result = data.transform({
+      name: [(v) => (v as string).toLowerCase(), (v) => (v as string).toUpperCase()]
+    });
+    const expected = Bmg([
+      { name: 'ALICE' },
+      { name: 'BOB' },
+    ]);
+    expect(result.isEqual(expected)).to.be.true;
+  })
+
+  it('leaves attributes without transformers unchanged', () => {
+    const data = Bmg([
+      { id: 1, name: 'alice', status: 10 },
+      { id: 2, name: 'bob', status: 20 },
+    ]);
+    const result = data.transform({
+      name: (v) => (v as string).toUpperCase()
+    });
+    const expected = Bmg([
+      { id: 1, name: 'ALICE', status: 10 },
+      { id: 2, name: 'BOB', status: 20 },
+    ]);
+    expect(result.isEqual(expected)).to.be.true;
+  })
+
+  ///
+
+  it('can be used standalone', () => {
+    const data = Bmg([
+      { name: 'alice', value: 10 },
+      { name: 'bob', value: 20 },
+    ]);
+    const standalone = transform(data.toArray(), { name: (v) => (v as string).toUpperCase() });
+    const expected = data.transform({ name: (v) => (v as string).toUpperCase() });
+    expect(isEqual(standalone, expected)).to.be.true;
+  })
+
+});

package/tests/operators/ungroup.test.ts

@@ -0,0 +1,67 @@
+import { describe, it, expect } from 'vitest';
+import { Bmg } from 'src';
+import { ungroup , isEqual } from 'src/operators';
+
+describe('.ungroup', () => {
+
+  const grouped = Bmg([
+    {
+      order_id: 1,
+      customer: 'Alice',
+      items: [
+        { item: 'Apple', qty: 2 },
+        { item: 'Banana', qty: 3 },
+      ]
+    },
+    {
+      order_id: 2,
+      customer: 'Bob',
+      items: [
+        { item: 'Cherry', qty: 1 },
+      ]
+    },
+  ]);
+
+  it('flattens nested relation into parent tuples', () => {
+    const result = grouped.ungroup('items');
+    const expected = 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 },
+    ]);
+    expect(result.isEqual(expected)).to.be.true;
+  })
+
+  it('preserves parent attributes', () => {
+    const result = grouped.ungroup('items') as any;
+    const appleRow = result.restrict({ item: 'Apple' }).one();
+    expect(appleRow.order_id).to.eql(1);
+    expect(appleRow.customer).to.eql('Alice');
+  })
+
+  it('merges nested attributes', () => {
+    const result = grouped.ungroup('items') as any;
+    const appleRow = result.restrict({ item: 'Apple' }).one();
+    expect(appleRow.item).to.eql('Apple');
+    expect(appleRow.qty).to.eql(2);
+  })
+
+  it('is the inverse of 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 },
+    ]);
+    const roundtrip = orders.group(['item', 'qty'], 'items').ungroup('items');
+    expect(roundtrip.isEqual(orders)).to.be.true;
+  })
+
+  ///
+
+  it('can be used standalone', () => {
+    const res = ungroup(grouped.toArray(), 'items');
+    const expected = grouped.ungroup('items');
+    expect(isEqual(res, expected)).to.be.true;
+  })
+
+});

package/tests/operators/union.test.ts

@@ -0,0 +1,51 @@
+import { describe, it, expect } from 'vitest';
+import { Bmg } from 'src';
+import { union , isEqual } from 'src/operators';
+
+describe('.union', () => {
+
+  const left = Bmg([
+    { id: 1, name: 'Alice' },
+    { id: 2, name: 'Bob' },
+  ]);
+
+  const right = Bmg([
+    { id: 2, name: 'Bob' },
+    { id: 3, name: 'Charlie' },
+  ]);
+
+  it('combines tuples from both relations', () => {
+    const result = left.union(right);
+    const expected = Bmg([
+      { id: 1, name: 'Alice' },
+      { id: 2, name: 'Bob' },
+      { id: 3, name: 'Charlie' },
+    ]);
+    expect(result.isEqual(expected)).to.be.true;
+  })
+
+  it('removes duplicates', () => {
+    const result = left.union(right);
+    const expected = Bmg([
+      { id: 1, name: 'Alice' },
+      { id: 2, name: 'Bob' },
+      { id: 3, name: 'Charlie' },
+    ]);
+    expect(result.isEqual(expected)).to.be.true;
+  })
+
+  it('is commutative (set semantics)', () => {
+    const lr = left.union(right);
+    const rl = right.union(left);
+    expect(lr.isEqual(rl)).to.be.true;
+  })
+
+  ///
+
+  it('can be used standalone', () => {
+    const res = union(left.toArray(), right.toArray());
+    const expected = left.union(right);
+    expect(isEqual(res, expected)).to.be.true;
+  })
+
+});

package/tests/operators/unwrap.test.ts

@@ -0,0 +1,50 @@
+import { describe, it, expect } from 'vitest';
+import { Bmg } from 'src';
+import { SUPPLIERS } from 'tests/fixtures';
+import { unwrap , isEqual } from 'src/operators';
+
+describe('.unwrap', () => {
+
+  const wrapped = Bmg([
+    { sid: 'S1', name: 'Smith', details: { status: 20, city: 'London' } },
+    { sid: 'S2', name: 'Jones', details: { status: 10, city: 'Paris' } },
+  ]);
+
+  it('flattens tuple-valued attribute', () => {
+    const result = wrapped.unwrap('details');
+    const expected = Bmg([
+      { sid: 'S1', name: 'Smith', status: 20, city: 'London' },
+      { sid: 'S2', name: 'Jones', status: 10, city: 'Paris' },
+    ]);
+    expect(result.isEqual(expected)).to.be.true;
+  })
+
+  it('removes the wrapped attribute', () => {
+    const result = wrapped.unwrap('details');
+    const smith = result.restrict({ sid: 'S1' }).one();
+    expect(smith).to.not.have.property('details');
+  })
+
+  it('is the inverse of wrap', () => {
+    const roundtrip = SUPPLIERS.wrap(['status', 'city'], 'details').unwrap('details');
+    expect(roundtrip.isEqual(SUPPLIERS)).to.be.true;
+  })
+
+  it('handles deeply nested unwrap', () => {
+    const nested = Bmg([
+      { id: 1, outer: { inner: { value: 42 } } }
+    ]);
+    const result = nested.unwrap('outer');
+    const expected = Bmg([{ id: 1, inner: { value: 42 } }]);
+    expect(result.isEqual(expected)).to.be.true;
+  })
+
+  ///
+
+  it('can be used standalone', () => {
+    const res = unwrap(wrapped.toArray(), 'details');
+    const expected = wrapped.unwrap('details');
+    expect(isEqual(res, expected)).to.be.true;
+  })
+
+});

package/tests/operators/where.test.ts

@@ -0,0 +1,33 @@
+import { describe, it, expect } from 'vitest';
+
+import { SUPPLIERS } from 'tests/fixtures';
+import { where , isEqual } from 'src/operators';
+
+describe('.where', () => {
+
+  it('allows filtering relations (alias for restrict)', () => {
+    const smith = SUPPLIERS.where((t) => t.sid === 'S1').one()
+    expect(smith.name).to.eql('Smith')
+  })
+
+  it('has a tuple shortcut', () => {
+    const smith = SUPPLIERS.where({sid: 'S1'}).one()
+    expect(smith.name).to.eql('Smith')
+  })
+
+  it('returns same result as restrict', () => {
+    const withWhere = SUPPLIERS.where({city: 'Paris'});
+    const withRestrict = SUPPLIERS.restrict({city: 'Paris'});
+    expect(withWhere.isEqual(withRestrict)).to.be.true;
+  })
+
+  ///
+
+  it('can be used standalone', () => {
+    const input = SUPPLIERS.toArray();
+    const res = where(input, { sid: 'S1' });
+    const expected = SUPPLIERS.where({ sid: 'S1' });
+    expect(isEqual(res, expected)).to.be.true;
+  })
+
+});

package/tests/operators/wrap.test.ts

@@ -0,0 +1,54 @@
+import { describe, it, expect } from 'vitest';
+import { Bmg } from 'src';
+import { SUPPLIERS } from 'tests/fixtures';
+import { wrap , isEqual } from 'src/operators';
+
+describe('.wrap', () => {
+
+  it('wraps specified attributes into a tuple', () => {
+    const result = SUPPLIERS.wrap(['status', 'city'], 'details');
+    const expected = Bmg([
+      { sid: 'S1', name: 'Smith', details: { status: 20, city: 'London' } },
+      { sid: 'S2', name: 'Jones', details: { status: 10, city: 'Paris' } },
+      { sid: 'S3', name: 'Blake', details: { status: 30, city: 'Paris' } },
+      { sid: 'S4', name: 'Clark', details: { status: 20, city: 'London' } },
+      { sid: 'S5', name: 'Adams', details: { status: 30, city: 'Athens' } },
+    ]);
+    expect(result.isEqual(expected)).to.be.true;
+  })
+
+  it('preserves non-wrapped attributes', () => {
+    const result = SUPPLIERS.wrap(['status', 'city'], 'details');
+    const smith = result.restrict({ sid: 'S1' }).one();
+    expect(smith.sid).to.eql('S1');
+    expect(smith.name).to.eql('Smith');
+    expect(Object.keys(smith).sort()).to.eql(['details', 'name', 'sid']);
+  })
+
+  it('handles wrapping all attributes', () => {
+    const result = SUPPLIERS.wrap(['sid', 'name', 'status', 'city'], 'all');
+    const expected = Bmg([
+      { all: { sid: 'S1', name: 'Smith', status: 20, city: 'London' } },
+      { all: { sid: 'S2', name: 'Jones', status: 10, city: 'Paris' } },
+      { all: { sid: 'S3', name: 'Blake', status: 30, city: 'Paris' } },
+      { all: { sid: 'S4', name: 'Clark', status: 20, city: 'London' } },
+      { all: { sid: 'S5', name: 'Adams', status: 30, city: 'Athens' } },
+    ]);
+    expect(result.isEqual(expected)).to.be.true;
+  })
+
+  it('handles wrapping single attribute', () => {
+    const result = SUPPLIERS.wrap(['city'], 'location');
+    const smith = result.restrict({ sid: 'S1' }).one();
+    expect(smith.location).to.eql({ city: 'London' });
+  })
+
+  ///
+
+  it('can be used standalone', () => {
+    const res = wrap(SUPPLIERS.toArray(), ['status', 'city'], 'details');
+    const expected = SUPPLIERS.wrap(['status', 'city'], 'details');
+    expect(isEqual(res, expected)).to.be.true;
+  })
+
+});

package/tests/operators/yByX.test.ts

@@ -0,0 +1,32 @@
+import { describe, it, expect } from 'vitest';
+import { SUPPLIERS } from 'tests/fixtures';
+import { yByX } from 'src/operators';
+
+describe('.yByX', () => {
+
+  it('is available on relations', () => {
+    expect(SUPPLIERS.yByX('name', 'sid')).to.eql({
+      'S1': 'Smith',
+      'S2': 'Jones',
+      'S3': 'Blake',
+      'S4': 'Clark',
+      'S5': 'Adams',
+    })
+  })
+
+  ///
+
+  it('can be used standalone', () => {
+    const tuples = [
+      {sid: 'S1', name: 'Smith'},
+      {sid: 'S2', name: 'Jones'},
+    ]
+    expect(yByX(tuples, 'name', 'sid')).to.eql(
+      {
+        'S1': 'Smith',
+        'S2': 'Jones',
+      }
+    )
+  })
+
+});