Bmg.js - Relational Algebra for JavaScript/TypeScript

A TypeScript/JavaScript implementation of BMG, providing relational algebra operators for working with arrays of objects.

Installation

npm install @enspirit/bmg-js

Quick Start

Using the Relation abstraction:

import { Bmg } from '@enspirit/bmg-js'

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' },
])

// Chain operations fluently
const parisSuppliers = suppliers
  .restrict({ city: 'Paris' })
  .project(['sid', 'name'])

console.log(parisSuppliers.toArray())
// => [{ sid: 'S2', name: 'Jones' }, { sid: 'S3', name: 'Blake' }]

// Extract a single tuple
const smith = suppliers.restrict({ sid: 'S1' }).one()
// => { sid: 'S1', name: 'Smith', status: 20, city: 'London' }

Using standalone operators on plain arrays:

import { restrict, project } from '@enspirit/bmg-js'

const suppliers = [
  { sid: 'S1', name: 'Smith', city: 'London' },
  { sid: 'S2', name: 'Jones', city: 'Paris' },
]

const result = project(restrict(suppliers, { city: 'Paris' }), ['name'])
// => [{ name: 'Jones' }]

TypeScript Support

Bmg.js provides full TypeScript support with generic types:

import { Bmg } from '@enspirit/bmg-js'

interface Supplier {
  sid: string
  name: string
  status: number
  city: string
}

const suppliers = Bmg<Supplier>([
  { sid: 'S1', name: 'Smith', status: 20, city: 'London' },
])

// Type-safe operations with autocomplete
const projected = suppliers.project(['sid', 'name'])
// Type: Relation<{ sid: string; name: string }>

const one = suppliers.restrict({ sid: 'S1' }).one()
// Type: Supplier

See the full type-safe example for more.

Available Operators

| Category | Operator | Description | |----------|----------|-------------| | Filtering | restrict(predicate) | Keep tuples matching predicate | | | where(predicate) | Alias for restrict | | | exclude(predicate) | Keep tuples NOT matching predicate | | | matching(other, keys?) | Semi-join (tuples with match in other) | | | not_matching(other, keys?) | Anti-join (tuples without match) | | Projection | project(attrs) | Keep only specified attributes | | | allbut(attrs) | Keep all attributes except specified | | Extension | extend(extensions) | Add computed attributes | | | constants(values) | Add constant attributes | | Renaming | rename(mapping) | Rename attributes | | | prefix(pfx, options?) | Add prefix to attribute names | | | suffix(sfx, options?) | Add suffix to attribute names | | Set Operations | union(other) | Set union of two relations | | | minus(other) | Set difference (tuples in left but not right) | | | intersect(other) | Set intersection (tuples in both) | | Join Operations | join(other, keys?) | Natural join on common/specified attributes | | | left_join(other, keys?) | Left outer join | | | cross_product(other) | Cartesian product | | | cross_join(other) | Alias for cross_product | | Nesting & Grouping | image(other, as, keys?) | Nest matching tuples as relation attribute | | | group(attrs, as) | Group attributes into nested relation | | | ungroup(attr) | Flatten nested relation | | | wrap(attrs, as) | Wrap attributes into tuple-valued attribute | | | unwrap(attr) | Flatten tuple-valued attribute | | | autowrap(options?) | Auto-wrap by separator pattern | | Aggregation | summarize(by, aggregators) | Group and aggregate | | Transformation | transform(transformation) | Transform attribute values | | Non-Relational | one() | Extract single tuple (throws if not exactly one) | | | toArray() | Convert relation to array | | | isEqual(other) | Check set equality | | | yByX(y, x) | Create { x-value: y-value } mapping | | | toText(options?) | Render as ASCII table | | | Bmg.isRelation(value) | Check if value is a Relation (static) |

Built-in aggregators for summarize: count, sum, min, max, avg, collect

Theory

Bmg.js implements relational algebra with these principles:

1. No duplicates - Relations are sets; duplicate tuples are automatically removed
2. Order independence - Tuple order and attribute order have no semantic meaning
3. Set equality - Two relations are equal if they contain the same tuples

Horizon

The aim is to have a language where one can write beautiful functional expressions:

suppliers
  |> restrict( _ ~> _.status > 20 )
  |> rename(sid: 'id', name: 'lastname')
  |> restrict(city: 'Paris')
  |> one

This will be provided by Elo.

Versioning

Bmg.js follows Semantic Versioning (SemVer). See API.md for the public API reference.

• MAJOR (x.0.0) - Breaking changes to the public API
• MINOR (0.x.0) - New operators or features, fully backward-compatible
• PATCH (0.0.x) - Bug fixes and performance improvements, no API changes

For Bmg.js specifically:

• Adding a new operator (e.g., sort, page) is a minor release
• Fixing incorrect behavior in an existing operator is a patch release
• Changing an operator's signature or renaming it is a major release

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/new-operator)
3. Add your changes with tests
4. Ensure tests pass: npm run test
5. Commit following conventional commits (e.g., feat: add sort operator)
6. Open a pull request

When adding a new operator:

• Add the operator implementation
• Add unit tests (use relational comparisons with isEqual, avoid accessing "first" tuple)
• Update the README operators table
• One commit per operator

License

MIT