@enspirit/bmg-js 1.0.0

package/.claude/safe-setup/.env.example

@@ -0,0 +1,3 @@
+# Git configuration (used for commits inside the container)
+GIT_USER_NAME=Your Name
+GIT_USER_EMAIL=your.email@example.com

package/.claude/safe-setup/Dockerfile.claude

@@ -0,0 +1,36 @@
+FROM alpine:latest
+
+# Install packages: base tools, node, ruby, postgresql client
+RUN apk update && apk add --no-cache \
+    bash \
+    curl \
+    git \
+    build-base \
+    nodejs \
+    npm \
+    vim \
+    sudo
+
+# Create non-root user with sudo access
+RUN addgroup -S bmg && adduser -S bmg -G bmg \
+    && echo "bmg ALL=(ALL) NOPASSWD:ALL" >> /etc/sudoers
+
+# Install Claude Code CLI globally
+RUN npm install -g @anthropic-ai/claude-code
+
+# Set up working directory
+WORKDIR /workspace
+
+# Copy and set up entrypoint
+COPY entrypoint.sh /entrypoint.sh
+RUN chmod +x /entrypoint.sh
+
+# Create .claude directory for history persistence
+RUN mkdir -p /home/bmg/.claude && chown -R bmg:bmg /home/bmg/.claude
+
+# Switch to non-root user
+USER bmg
+
+# Use entrypoint to configure git and run command
+ENTRYPOINT ["/entrypoint.sh"]
+CMD ["bash"]

package/.claude/safe-setup/HACKING.md

@@ -0,0 +1,63 @@
+# Hacking on Bmg with Claude Code
+
+This Docker setup provides a sandboxed environment with all tools needed to hack on Bmg:
+- Node.js
+- Claude Code CLI
+
+## Prerequisites
+
+1. Docker and Docker Compose installed
+2. A Claude Code account
+
+## Getting Started
+
+```bash
+cd .claude/safe-setup
+
+# Create your .env file from template
+cp .env.example .env
+
+# Edit .env to set your git identity
+# GIT_USER_NAME=Your Name
+# GIT_USER_EMAIL=your.email@example.com
+
+# Build and start containers
+make up
+
+# Enter the dev environment
+make shell
+```
+
+## Persistent Data
+
+- **Claude history**: Stored in a named Docker volume (`claude-history`) that persists across container restarts
+- **Git configuration**: Automatically set from `GIT_USER_NAME` and `GIT_USER_EMAIL` environment variables
+
+## Inside the Container
+
+You're now user `bmg` in `/workspace` (the Bmg project root).
+
+```bash
+# Install project dependencies
+npm install
+
+# Run tests
+npm run test
+
+# Use Claude Code
+claude
+```
+
+PostgreSQL is pre-configured via environment variables. Just run `psql` to connect.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `make up` | Build and start containers |
+| `make down` | Stop containers |
+| `make shell` | Enter dev container |
+| `make restart` | Restart everything |
+| `make logs` | Follow container logs |
+| `make status` | Show container status |
+| `make clean` | Remove containers and images |

package/.claude/safe-setup/Makefile

@@ -0,0 +1,22 @@
+.PHONY: up down shell restart clean logs status
+
+up:
+	docker compose up -d --build
+	@echo "Containers started. Use 'make shell' to access dev environment"
+
+down:
+	docker compose down
+
+shell:
+	docker compose exec dev bash
+
+restart: down up
+
+clean: down
+	docker compose down --rmi all --volumes
+
+logs:
+	docker compose logs -f
+
+status:
+	@docker compose ps

package/.claude/safe-setup/docker-compose.yml

@@ -0,0 +1,18 @@
+services:
+
+  dev:
+    build:
+      context: .
+      dockerfile: Dockerfile.claude
+    container_name: claude
+    volumes:
+      - ../..:/workspace
+      - claude-history:/home/bmg/.claude
+    environment:
+      - GIT_USER_NAME=${GIT_USER_NAME:-}
+      - GIT_USER_EMAIL=${GIT_USER_EMAIL:-}
+    stdin_open: true
+    tty: true
+
+volumes:
+  claude-history:

package/.claude/safe-setup/entrypoint.sh

@@ -0,0 +1,13 @@
+#!/bin/bash
+
+# Configure git user/email from environment variables if provided
+if [ -n "$GIT_USER_NAME" ]; then
+    git config --global user.name "$GIT_USER_NAME"
+fi
+
+if [ -n "$GIT_USER_EMAIL" ]; then
+    git config --global user.email "$GIT_USER_EMAIL"
+fi
+
+# Execute the command passed to the container
+exec "$@"

package/.claude/settings.local.json

@@ -0,0 +1,9 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npm run test:*)",
+      "Bash(npx tsc:*)",
+      "Bash(wc:*)"
+    ]
+  }
+}

package/.claude/typescript-annotations.md

@@ -0,0 +1,273 @@
+# TypeScript Type Safety Implementation Plan
+
+## Goal
+Add opt-in generic type parameters to enable:
+- IDE autocomplete on tuple attributes
+- Compile-time validation of attribute names
+- Type transformation tracking through operator chains
+
+## Core Changes
+
+### 1. Generic Relation Interface (`src/types.ts`)
+
+```typescript
+export interface Relation<T extends Tuple = Tuple> {
+  one(): T;
+  toArray(): T[];
+
+  // Preserve type
+  restrict(p: TypedPredicate<T>): Relation<T>;
+  where(p: TypedPredicate<T>): Relation<T>;
+
+  // Transform type
+  project<K extends keyof T>(attrs: K[]): Relation<Pick<T, K>>;
+  allbut<K extends keyof T>(attrs: K[]): Relation<Omit<T, K>>;
+  rename<R extends RenameMap<T>>(r: R): Relation<Renamed<T, R>>;
+  extend<E extends Record<string, unknown>>(e: TypedExtension<T, E>): Relation<T & E>;
+  constants<C extends Tuple>(c: C): Relation<T & C>;
+
+  // Binary ops - combine types
+  join<R extends Tuple>(right: RelationOperand<R>, keys?: JoinKeys<T, R>): Relation<Joined<T, R>>;
+  left_join<R extends Tuple>(right: RelationOperand<R>, keys?: JoinKeys<T, R>): Relation<LeftJoined<T, R>>;
+  cross_product<R extends Tuple>(right: RelationOperand<R>): Relation<T & R>;
+
+  // Nesting
+  group<K extends keyof T, As extends string>(attrs: K[], as: As): Relation<Grouped<T, K, As>>;
+  ungroup<K extends keyof T>(attr: K): Relation<Ungrouped<T, K>>;
+  // ...
+}
+```
+
+### 2. Generic MemoryRelation Class (`src/Relation/Memory.ts`)
+
+```typescript
+export class MemoryRelation<T extends Tuple = Tuple> implements Relation<T> {
+  constructor(private tuples: T[]) {}
+
+  project<K extends keyof T>(attrs: K[]): MemoryRelation<Pick<T, K>> {
+    return project(this, attrs as string[]) as MemoryRelation<Pick<T, K>>;
+  }
+  // ...
+}
+```
+
+### 3. Generic Bmg Factory (`src/index.ts`)
+
+```typescript
+export function Bmg<T extends Tuple>(tuples: T[]): MemoryRelation<T>;
+export function Bmg(tuples: Tuple[]): MemoryRelation<Tuple>;
+export function Bmg<T extends Tuple = Tuple>(tuples: T[]): MemoryRelation<T> {
+  return new MemoryRelation<T>(tuples);
+}
+```
+
+### 4. Utility Types (`src/utility-types.ts` - new file)
+
+```typescript
+// Rename: { name: 'fullName' } transforms { name, age } to { fullName, age }
+export type RenameMap<T> = { [K in keyof T]?: string };
+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];
+};
+
+// Join: combine left & right, remove duplicate keys from right
+export type CommonKeys<L, R> = Extract<keyof L, keyof R>;
+export type Joined<L, R> = L & Omit<R, CommonKeys<L, R>>;
+export type LeftJoined<L, R> = L & Partial<Omit<R, CommonKeys<L, R>>>;
+
+// Group/Ungroup
+export type Grouped<T, K extends keyof T, As extends string> =
+  Omit<T, K> & Record<As, Relation<Pick<T, K>>>;
+export type Ungrouped<T, K extends keyof T> =
+  T[K] extends Relation<infer N> ? Omit<T, K> & N : never;
+
+// Wrap/Unwrap
+export type Wrapped<T, K extends keyof T, As extends string> =
+  Omit<T, K> & Record<As, Pick<T, K>>;
+export type Unwrapped<T, K extends keyof T> =
+  T[K] extends Record<string, unknown> ? Omit<T, K> & T[K] : never;
+
+// Prefix/Suffix (template literal types)
+export type Prefixed<T, P extends string, Ex extends keyof T = never> = {
+  [K in keyof T as K extends Ex ? K : `${P}${K & string}`]: T[K];
+};
+```
+
+### 5. Typed Predicates (`src/types.ts`)
+
+```typescript
+export type TypedPredicateFunc<T> = (t: T) => boolean;
+export type TypedPredicate<T> = TypedPredicateFunc<T> | Partial<T>;
+```
+
+## Implementation Phases
+
+### Phase 1: Foundation
+1. Add `Relation<T = Tuple>` interface with generics
+2. Add `MemoryRelation<T = Tuple>` class
+3. Update `Bmg<T>()` factory
+4. Type these operators first (highest value):
+   - `one()`, `toArray()` - return `T` / `T[]`
+   - `project()` - `Pick<T, K>`
+   - `allbut()` - `Omit<T, K>`
+   - `restrict()`, `where()`, `exclude()` - preserve `T` with typed predicate
+
+### Phase 2: Structure-Changing Operators
+- `extend()` - `T & E`
+- `constants()` - `T & C`
+- `rename()` - `Renamed<T, R>`
+- `prefix()`, `suffix()` - template literal types
+
+### Phase 3: Binary Operations
+- `union()`, `minus()`, `intersect()` - require same `T`
+- `join()` - `Joined<T, R>`
+- `left_join()` - `LeftJoined<T, R>`
+- `cross_product()` - `T & R`
+- `matching()`, `not_matching()` - preserve `T`
+
+### Phase 4: Nesting Operators
+- `group()` - `Grouped<T, K, As>`
+- `ungroup()` - `Ungrouped<T, K>`
+- `wrap()` - `Wrapped<T, K, As>`
+- `unwrap()` - `Unwrapped<T, K>`
+- `image()` - adds `Relation<...>` attribute
+
+### Phase 5: Complex Operators
+- `summarize()` - infer result from aggregators
+- `transform()` - preserve structure, optional value type tracking
+- `autowrap()` - return `Relation<Tuple>` (dynamic, un-typeable)
+
+## Backwards Compatibility
+
+- Default type parameter `= Tuple` ensures existing untyped code compiles
+- When `T = Tuple = Record<string, unknown>`, `keyof T = string`, so any string[] is accepted
+- No breaking changes to existing API
+
+## Files to Modify
+
+| File | Changes |
+|------|---------|
+| `src/types.ts` | Add generics to `Relation`, typed predicates |
+| `src/utility-types.ts` (new) | Utility types: `Renamed`, `Joined`, `Grouped`, etc. |
+| `src/Relation/Memory.ts` | Add `<T>` parameter, update method signatures |
+| `src/index.ts` | Update `Bmg` factory with type inference |
+| `src/operators/_helpers.ts` | Generic `toOperationalOperand<T>` |
+
+## Example Usage After Implementation
+
+```typescript
+// Opt-in: provide type for full type safety
+interface Supplier {
+  sid: string;
+  name: string;
+  status: number;
+  city: string;
+}
+
+const suppliers = Bmg<Supplier>([
+  { sid: 'S1', name: 'Smith', status: 20, city: 'London' },
+]);
+
+// IDE autocomplete: suggests 'sid', 'name', 'status', 'city'
+const result = suppliers
+  .project(['sid', 'name'])      // Relation<{ sid: string; name: string }>
+  .rename({ name: 'fullName' })  // Relation<{ sid: string; fullName: string }>
+  .extend({ upper: t => t.fullName.toUpperCase() }); // t.fullName autocompletes
+
+// Compile error for invalid attributes
+suppliers.project(['invalid']); // Error: 'invalid' not in keyof Supplier
+
+// Untyped usage still works (backwards compatible)
+const r = Bmg([{ a: 1 }]);  // Relation<Tuple>
+r.project(['a']);           // Works, no validation
+```
+
+## Test Plan
+
+### 1. Compile-Time Type Tests
+
+Create `tests/types/relation.test-d.ts` using vitest's type testing:
+
+```typescript
+import { Bmg } from 'src';
+import { expectTypeOf } from 'vitest';
+
+interface Person { id: number; name: string; age: number }
+
+describe('Type Safety', () => {
+  const people = Bmg<Person>([{ id: 1, name: 'Alice', age: 30 }]);
+
+  it('project narrows type to Pick<T, K>', () => {
+    const result = people.project(['id', 'name']);
+    expectTypeOf(result.one()).toEqualTypeOf<{ id: number; name: string }>();
+  });
+
+  it('rejects invalid attribute names', () => {
+    // @ts-expect-error - 'invalid' is not a key of Person
+    people.project(['invalid']);
+  });
+
+  it('restrict preserves type with typed predicate', () => {
+    const result = people.restrict(t => t.age > 25);
+    expectTypeOf(result.one()).toEqualTypeOf<Person>();
+  });
+
+  it('predicate function receives typed tuple', () => {
+    people.restrict(t => {
+      expectTypeOf(t.id).toBeNumber();
+      expectTypeOf(t.name).toBeString();
+      return true;
+    });
+  });
+
+  it('join combines types correctly', () => {
+    interface Order { orderId: number; personId: number; total: number }
+    const orders = Bmg<Order>([]);
+    const joined = people.join(orders, { id: 'personId' });
+    expectTypeOf(joined.one()).toEqualTypeOf<{
+      id: number; name: string; age: number; orderId: number; total: number
+    }>();
+  });
+
+  it('rename transforms keys', () => {
+    const renamed = people.rename({ name: 'fullName' });
+    expectTypeOf(renamed.one()).toEqualTypeOf<{ id: number; fullName: string; age: number }>();
+  });
+
+  it('untyped usage still works', () => {
+    const r = Bmg([{ a: 1 }]);  // Relation<Tuple>
+    r.project(['a']);           // Should compile
+    r.project(['anything']);    // Should compile (no validation when T=Tuple)
+  });
+});
+```
+
+### 2. Runtime Tests
+
+All 152 existing tests must continue to pass without modification - validates backwards compatibility.
+
+### 3. Type Test Coverage by Phase
+
+| Phase | Type Tests |
+|-------|-----------|
+| Phase 1 | `project`, `allbut`, `restrict`, `one`, `toArray` |
+| Phase 2 | `extend`, `constants`, `rename`, `prefix`, `suffix` |
+| Phase 3 | `join`, `left_join`, `cross_product`, `union`, `minus` |
+| Phase 4 | `group`, `ungroup`, `wrap`, `unwrap`, `image` |
+| Phase 5 | `summarize`, `transform`, `autowrap` (escape hatch) |
+
+### 4. Test File Structure
+
+```
+tests/
+  types/
+    relation.test-d.ts    # Core Relation<T> type tests
+    operators.test-d.ts   # Operator type transformation tests
+    utility-types.test-d.ts  # Utility type unit tests
+```
+
+## Limitations
+
+- Function-based `rename()` loses type tracking (only object syntax typed)
+- `autowrap()` returns `Relation<Tuple>` (dynamic structure)
+- Requires TypeScript 4.1+ for template literal types

package/.github/workflows/test.yml

@@ -0,0 +1,26 @@
+name: Tests
+
+on:
+  push:
+    branches: ['*']
+  pull_request:
+    branches: ['*']
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install dependencies
+        run: pnpm install
+
+      - name: Run tests
+        run: pnpm test

package/CLAUDE.md

@@ -0,0 +1,48 @@
+# What is Bmg.js ?
+
+A Typescript implementation of BMG, a relational algebra originally implemented
+in/for Ruby :
+
+- https://github.com/enspirit/bmg
+- https://www.relational-algebra.dev/
+
+The aim of bmg.js is NOT to implement the SQL compiler, but only to provide an
+implementation of main algebra operators to work on arrays of javascript objects.
+
+## Development flow
+
+* List operators to support, by order of importance
+* Add each operator, in order, with unit tests.
+* One commit per operator, don't forget to adapt the README.
+* Tests MUST succeed at all times, run them with `npm run test`
+
+## Theory
+
+IMPORTANT rules:
+
+1. Relations NEVER have duplicates
+2. Order of tuples and order or attributes in a tuple are not important semantically
+3. Mathematically, relations are sets of tuples ; tuples are sets of (attr, value) pairs.
+4. Two relations are equal of they have the exact same set of exact same tuples.
+
+## About unit tests
+
+IMPORTANT rules:
+
+* Favor purely relational tests: compare an obtained relation with the expected relation
+  using `isEqual`.
+* Do NEVER access the "first" tuple, since there is no such tuple.
+* Instead, use `r.restrict(...predicate...).one` with a predicate that selects the
+  tuple you are interested in. `one` will correctly fail if your assumption is wrong.
+
+## Implemented operators
+
+**Relational:** restrict, where, exclude, project, allbut, extend, rename, prefix, suffix, constants, union, minus, intersect, matching, not_matching, join, left_join, cross_product, cross_join, image, summarize, group, ungroup, wrap, unwrap, autowrap, transform
+
+**Non-relational:** one, yByX, toArray, isRelation, isEqual
+
+## TODO
+
+- [ ] sort - Order tuples by attributes
+- [ ] page - Pagination (offset + limit)
+- [ ] size, empty, first, exists - Utility helpers

package/Makefile

@@ -0,0 +1,2 @@
+dist/bmg.cjs: src/**/*
+	pnpm run build

package/README.md

@@ -0,0 +1,170 @@
+# Bmg.js - Relational Algebra for JavaScript/TypeScript
+
+A TypeScript/JavaScript implementation of [BMG](https://www.relational-algebra.dev/), providing relational algebra operators for working with arrays of objects.
+
+## Installation
+
+```bash
+npm install @enspirit/bmg-js
+```
+
+## Quick Start
+
+Using the Relation abstraction:
+
+```typescript
+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:
+
+```typescript
+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:
+
+```typescript
+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](./example/index.ts) 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 |
+| | `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](https://elo-lang.org).
+
+## Versioning
+
+Bmg.js follows [Semantic Versioning](https://semver.org/) (SemVer):
+
+- **MAJOR** (x.0.0) - Breaking changes to the API (renamed operators, changed signatures, removed features)
+- **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