@enspirit/bmg-js 1.0.0 → 1.0.2

package/example/index.ts

@@ -1,316 +0,0 @@
-/**
- * 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

@@ -1,16 +0,0 @@
-{
-  "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

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

package/src/utility-types.ts

@@ -1,77 +0,0 @@
-/**
- * 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

@@ -1,16 +0,0 @@
-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

@@ -1,9 +0,0 @@
-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' },
-])

package/tests/operators/allbut.test.ts

@@ -1,51 +0,0 @@
-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

@@ -1,82 +0,0 @@
-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

@@ -1,37 +0,0 @@
-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;
-  })
-
-});