@enspirit/bmg-js 1.0.0 → 1.0.2

package/dist/operators/_helpers.d.ts

@@ -0,0 +1,142 @@
+import { OperationalOperand, RelationOperand, Renaming, RenamingFunc, Tuple, JoinKeys, AttrName } from "@/types";
+/**
+ * Generates a unique string key for a tuple, used for equality comparison and deduplication.
+ * Handles nested relations by converting them to sorted tuple keys.
+ *
+ * @example
+ * tupleKey({ name: 'Alice', age: 30 })
+ * // => '[["age",30],["name","Alice"]]'
+ *
+ * @example
+ * tupleKey({ id: 1, items: Bmg([{ x: 1 }, { x: 2 }]) })
+ * // => '[["id",1],["items",[...]]]' (nested relation converted to sorted keys)
+ */
+export declare const tupleKey: (tuple: Tuple) => string;
+/**
+ * Removes duplicate tuples from an array, preserving order of first occurrence.
+ * Uses tupleKey() for equality comparison.
+ *
+ * @example
+ * deduplicate([
+ *   { id: 1, name: 'Alice' },
+ *   { id: 2, name: 'Bob' },
+ *   { id: 1, name: 'Alice' },  // duplicate
+ * ])
+ * // => [{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }]
+ */
+export declare const deduplicate: (tuples: Tuple[]) => Tuple[];
+/**
+ * Converts a RelationOperand (Relation or Tuple[]) to an OperationalOperand
+ * that provides a uniform interface for iteration and output.
+ *
+ * @example
+ * // With array input, output remains array
+ * const op = toOperationalOperand([{ id: 1 }]);
+ * [...op.tuples()];        // => [{ id: 1 }]
+ * op.output([{ id: 2 }]);  // => [{ id: 2 }]
+ *
+ * @example
+ * // With Relation input, output is a new Relation
+ * const op = toOperationalOperand(Bmg([{ id: 1 }]));
+ * [...op.tuples()];        // => [{ id: 1 }]
+ * op.output([{ id: 2 }]);  // => Bmg([{ id: 2 }])
+ */
+export declare const toOperationalOperand: (operand: RelationOperand) => OperationalOperand;
+/**
+ * Converts a Renaming (object or function) to a RenamingFunc.
+ *
+ * @example
+ * // Object renaming
+ * const fn = toRenamingFunc({ name: 'fullName', age: 'years' });
+ * fn('name');  // => 'fullName'
+ * fn('age');   // => 'years'
+ * fn('other'); // => 'other' (unchanged)
+ *
+ * @example
+ * // Function renaming (passed through)
+ * const fn = toRenamingFunc(attr => attr.toUpperCase());
+ * fn('name'); // => 'NAME'
+ */
+export declare const toRenamingFunc: (renaming: Renaming) => RenamingFunc;
+export declare const error: (msg: string) => never;
+/**
+ * Finds attribute names that exist in both left and right tuple arrays.
+ * Used for natural joins when no explicit keys are provided.
+ *
+ * @example
+ * const left = [{ id: 1, name: 'Alice', city: 'NYC' }];
+ * const right = [{ city: 'NYC', country: 'USA' }];
+ * getCommonAttrs(left, right);
+ * // => ['city']
+ *
+ * @example
+ * const left = [{ a: 1, b: 2 }];
+ * const right = [{ b: 2, c: 3 }];
+ * getCommonAttrs(left, right);
+ * // => ['b']
+ */
+export declare const getCommonAttrs: (left: Tuple[], right: Tuple[]) => AttrName[];
+/**
+ * Normalizes JoinKeys to a Record<AttrName, AttrName> mapping left attrs to right attrs.
+ *
+ * @example
+ * // undefined => use common attributes
+ * normalizeKeys(undefined, [{ id: 1, city: 'NYC' }], [{ city: 'NYC' }]);
+ * // => { city: 'city' }
+ *
+ * @example
+ * // Array of common attribute names
+ * normalizeKeys(['city', 'country'], leftTuples, rightTuples);
+ * // => { city: 'city', country: 'country' }
+ *
+ * @example
+ * // Object mapping left attr to right attr
+ * normalizeKeys({ city: 'location' }, leftTuples, rightTuples);
+ * // => { city: 'location' }
+ */
+export declare const normalizeKeys: (keys: JoinKeys | undefined, leftTuples: Tuple[], rightTuples: Tuple[]) => Record<AttrName, AttrName>;
+/**
+ * Checks if two tuples match on the specified key mapping.
+ *
+ * @example
+ * const keyMap = { city: 'location' };
+ * tuplesMatch({ id: 1, city: 'NYC' }, { location: 'NYC', pop: 8 }, keyMap);
+ * // => true (left.city === right.location)
+ *
+ * @example
+ * const keyMap = { city: 'city' };
+ * tuplesMatch({ city: 'NYC' }, { city: 'LA' }, keyMap);
+ * // => false
+ */
+export declare const tuplesMatch: (left: Tuple, right: Tuple, keyMap: Record<AttrName, AttrName>) => boolean;
+/**
+ * Creates a string key from a tuple's join attributes for fast Set-based lookups.
+ * Used by matching/not_matching for efficient semi-join operations.
+ *
+ * @example
+ * const keyMap = { first: 'fname', last: 'lname' };
+ *
+ * // Left side uses left attr names (keys of keyMap)
+ * matchKey({ id: 1, first: 'John', last: 'Doe' }, keyMap, 'left');
+ * // => '"John"|"Doe"'
+ *
+ * // Right side uses right attr names (values of keyMap)
+ * matchKey({ fname: 'John', lname: 'Doe', age: 30 }, keyMap, 'right');
+ * // => '"John"|"Doe"'
+ */
+export declare const matchKey: (tuple: Tuple, keyMap: Record<AttrName, AttrName>, side: 'left' | 'right') => string;
+/**
+ * Removes join key attributes from a right tuple when merging.
+ * Used to avoid duplicate columns in join results.
+ *
+ * @example
+ * const keyMap = { city: 'location' };
+ * projectOutKeys({ location: 'NYC', country: 'USA', pop: 8 }, keyMap);
+ * // => { country: 'USA', pop: 8 }  (location removed)
+ *
+ * @example
+ * const keyMap = { a: 'a', b: 'b' };
+ * projectOutKeys({ a: 1, b: 2, c: 3 }, keyMap);
+ * // => { c: 3 }  (a and b removed)
+ */
+export declare const projectOutKeys: (tuple: Tuple, keyMap: Record<AttrName, AttrName>) => Tuple;

package/dist/operators/allbut.d.ts

@@ -0,0 +1,2 @@
+import { RelationOperand, AttrName } from "../types";
+export declare const allbut: (operand: RelationOperand, attrs: AttrName[]) => RelationOperand;

package/dist/operators/autowrap.d.ts

@@ -0,0 +1,2 @@
+import { AutowrapOptions, RelationOperand } from "../types";
+export declare const autowrap: (operand: RelationOperand, options?: AutowrapOptions) => RelationOperand;

package/dist/operators/constants.d.ts

@@ -0,0 +1,2 @@
+import { RelationOperand, Tuple } from "../types";
+export declare const constants: (operand: RelationOperand, consts: Tuple) => RelationOperand;

package/dist/operators/cross_product.d.ts

@@ -0,0 +1,3 @@
+import { RelationOperand } from "../types";
+export declare const cross_product: (left: RelationOperand, right: RelationOperand) => RelationOperand;
+export { cross_product as cross_join };

package/dist/operators/exclude.d.ts

@@ -0,0 +1,2 @@
+import { RelationOperand, Predicate } from "../types";
+export declare const exclude: (operand: RelationOperand, p: Predicate) => RelationOperand;

package/dist/operators/extend.d.ts

@@ -0,0 +1,2 @@
+import { RelationOperand, Extension } from "../types";
+export declare const extend: (operand: RelationOperand, extension: Extension) => RelationOperand;

package/dist/operators/group.d.ts

@@ -0,0 +1,2 @@
+import { RelationOperand, AttrName } from "../types";
+export declare const group: (operand: RelationOperand, attrs: AttrName[], as: AttrName) => RelationOperand;

package/dist/operators/image.d.ts

@@ -0,0 +1,2 @@
+import { RelationOperand, JoinKeys, AttrName } from "../types";
+export declare const image: (left: RelationOperand, right: RelationOperand, as: AttrName, keys?: JoinKeys) => RelationOperand;

package/dist/operators/index.d.ts

@@ -0,0 +1,30 @@
+export * from './restrict';
+export * from './where';
+export * from './exclude';
+export * from './constants';
+export * from './rename';
+export * from './prefix';
+export * from './suffix';
+export * from './project';
+export * from './allbut';
+export * from './extend';
+export * from './union';
+export * from './minus';
+export * from './intersect';
+export * from './matching';
+export * from './not_matching';
+export * from './join';
+export * from './left_join';
+export * from './cross_product';
+export * from './image';
+export * from './summarize';
+export * from './group';
+export * from './ungroup';
+export * from './wrap';
+export * from './unwrap';
+export * from './autowrap';
+export * from './transform';
+export * from './isRelation';
+export * from './isEqual';
+export * from './one';
+export * from './yByX';

package/dist/operators/intersect.d.ts

@@ -0,0 +1,2 @@
+import { RelationOperand } from "../types";
+export declare const intersect: (left: RelationOperand, right: RelationOperand) => RelationOperand;

package/dist/operators/isEqual.d.ts

@@ -0,0 +1,2 @@
+import { RelationOperand } from "../types";
+export declare const isEqual: (left: RelationOperand, right: RelationOperand) => boolean;

package/dist/operators/isRelation.d.ts

@@ -0,0 +1 @@
+export declare const isRelation: (op: any) => boolean;

package/dist/operators/join.d.ts

@@ -0,0 +1,2 @@
+import { RelationOperand, JoinKeys } from "../types";
+export declare const join: (left: RelationOperand, right: RelationOperand, keys?: JoinKeys) => RelationOperand;

package/dist/operators/left_join.d.ts

@@ -0,0 +1,2 @@
+import { RelationOperand, JoinKeys } from "../types";
+export declare const left_join: (left: RelationOperand, right: RelationOperand, keys?: JoinKeys) => RelationOperand;

package/dist/operators/matching.d.ts

@@ -0,0 +1,2 @@
+import { RelationOperand, JoinKeys } from "../types";
+export declare const matching: (left: RelationOperand, right: RelationOperand, keys?: JoinKeys) => RelationOperand;

package/dist/operators/minus.d.ts

@@ -0,0 +1,2 @@
+import { RelationOperand } from "../types";
+export declare const minus: (left: RelationOperand, right: RelationOperand) => RelationOperand;

package/dist/operators/not_matching.d.ts

@@ -0,0 +1,2 @@
+import { RelationOperand, JoinKeys } from "../types";
+export declare const not_matching: (left: RelationOperand, right: RelationOperand, keys?: JoinKeys) => RelationOperand;

package/dist/operators/one.d.ts

@@ -0,0 +1,2 @@
+import { RelationOperand, Tuple } from "../types";
+export declare const one: (operand: RelationOperand) => Tuple;

package/dist/operators/prefix.d.ts

@@ -0,0 +1,2 @@
+import { PrefixOptions, RelationOperand } from "../types";
+export declare const prefix: (operand: RelationOperand, pfx: string, options?: PrefixOptions) => RelationOperand;

package/dist/operators/project.d.ts

@@ -0,0 +1,2 @@
+import { RelationOperand, AttrName } from "../types";
+export declare const project: (operand: RelationOperand, attrs: AttrName[]) => RelationOperand;

package/dist/operators/rename.d.ts

@@ -0,0 +1,2 @@
+import { RelationOperand, Renaming } from "../types";
+export declare const rename: (operand: RelationOperand, renaming: Renaming) => RelationOperand;

package/dist/operators/restrict.d.ts

@@ -0,0 +1,2 @@
+import { RelationOperand, Predicate } from "../types";
+export declare const restrict: (operand: RelationOperand, p: Predicate) => RelationOperand;

package/dist/operators/suffix.d.ts

@@ -0,0 +1,2 @@
+import { RelationOperand, SuffixOptions } from "../types";
+export declare const suffix: (operand: RelationOperand, sfx: string, options?: SuffixOptions) => RelationOperand;

package/dist/operators/summarize.d.ts

@@ -0,0 +1,2 @@
+import { RelationOperand, AttrName, Aggregators } from "../types";
+export declare const summarize: (operand: RelationOperand, by: AttrName[], aggs: Aggregators) => RelationOperand;

package/dist/operators/transform.d.ts

@@ -0,0 +1,2 @@
+import { RelationOperand, Transformation } from "../types";
+export declare const transform: (operand: RelationOperand, transformation: Transformation) => RelationOperand;

package/dist/operators/ungroup.d.ts

@@ -0,0 +1,2 @@
+import { RelationOperand, AttrName } from "../types";
+export declare const ungroup: (operand: RelationOperand, attr: AttrName) => RelationOperand;

package/dist/operators/union.d.ts

@@ -0,0 +1,2 @@
+import { RelationOperand } from "../types";
+export declare const union: (left: RelationOperand, right: RelationOperand) => RelationOperand;

package/dist/operators/unwrap.d.ts

@@ -0,0 +1,2 @@
+import { RelationOperand, AttrName } from "../types";
+export declare const unwrap: (operand: RelationOperand, attr: AttrName) => RelationOperand;

package/dist/operators/where.d.ts

@@ -0,0 +1 @@
+export { restrict as where } from './restrict';

package/dist/operators/wrap.d.ts

@@ -0,0 +1,2 @@
+import { RelationOperand, AttrName } from "../types";
+export declare const wrap: (operand: RelationOperand, attrs: AttrName[], as: AttrName) => RelationOperand;

package/dist/operators/yByX.d.ts

@@ -0,0 +1,2 @@
+import { AttrName, RelationOperand, Tuple } from "../types";
+export declare const yByX: (operand: RelationOperand, y: AttrName, x: AttrName) => Tuple;

package/dist/support/toPredicateFunc.d.ts

@@ -0,0 +1,2 @@
+import { Predicate, PredicateFunc } from '../types';
+export declare const toPredicateFunc: (p: Predicate) => PredicateFunc;

package/dist/types.d.ts

@@ -0,0 +1,162 @@
+/**
+ * Type definitions for Bmg.js relational algebra library.
+ *
+ * This file defines all types needed for type-safe relational operations:
+ * - Base types (AttrName, Tuple)
+ * - Utility types for transformations (Renamed, Prefixed, Joined, etc.)
+ * - The Relation interface with all operators
+ * - Helper types for predicates, extensions, aggregators, etc.
+ */
+/** Attribute name in a tuple */
+export type AttrName = string;
+/** A tuple is a record mapping attribute names to values */
+export type Tuple = Record<AttrName, unknown>;
+/** 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 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];
+};
+/** 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>>>;
+/**
+ * Typed join keys for array form: keys must exist on BOTH operands.
+ * Example: suppliers.join(parts, ['city']) - 'city' must be a key of both.
+ */
+export type TypedJoinKeysArray<L, R> = (keyof L & keyof R & string)[];
+/**
+ * Typed join keys for object form: maps left keys to right keys.
+ * Example: suppliers.join(parts, { sid: 'supplier_id' })
+ * - Left key (sid) must exist on L
+ * - Right key (supplier_id) must exist on R
+ */
+export type TypedJoinKeysObject<L, R> = {
+    [K in keyof L & string]?: keyof R & string;
+};
+/** 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>;
+/** Result of ungroup: remove relation attr, flatten its tuple type */
+export type Ungrouped<T, K extends keyof T> = T[K] extends Relation<infer N> ? Omit<T, K> & N : Omit<T, K>;
+export type AggregatorName = 'count' | 'sum' | 'min' | 'max' | 'avg' | 'collect';
+export type AggregatorSpec = {
+    op: AggregatorName;
+    attr: AttrName;
+};
+export type AggregatorFunc = (tuples: Tuple[]) => unknown;
+export type Aggregator = AggregatorName | AggregatorSpec | AggregatorFunc;
+export type Aggregators = Record<AttrName, Aggregator>;
+/** 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]>;
+};
+/** Predicate function that receives a typed tuple */
+export type TypedPredicateFunc<T> = (t: T) => boolean;
+/** Predicate: either a partial tuple for equality matching, or a function */
+export type TypedPredicate<T> = Partial<T> | TypedPredicateFunc<T>;
+export type PredicateFunc = ((t: Tuple) => any);
+export type Predicate = Tuple | PredicateFunc;
+/** Extension function that receives a typed tuple */
+export type TypedExtensionFunc<T, R> = (tuple: T) => R;
+/** Extension definition: function returning value, or attribute name to copy */
+export type TypedExtension<T, E extends Record<string, unknown>> = {
+    [K in keyof E]: TypedExtensionFunc<T, E[K]> | keyof T;
+};
+export type ExtensionFunc = (tuple: Tuple) => unknown;
+export type Extension = Record<AttrName, ExtensionFunc | AttrName>;
+export interface PrefixOptions {
+    except?: AttrName[];
+}
+export interface SuffixOptions {
+    except?: AttrName[];
+}
+export interface AutowrapOptions {
+    separator?: string;
+}
+export type Renaming = RenamingObj | RenamingFunc;
+export type RenamingFunc = (attr: AttrName) => AttrName;
+export type RenamingObj = Record<AttrName, AttrName>;
+export type JoinKeys = AttrName[] | Record<AttrName, AttrName>;
+export type TransformFunc = (value: unknown) => unknown;
+export type Transformation = TransformFunc | TransformFunc[] | Record<AttrName, TransformFunc | TransformFunc[]>;
+/**
+ * Relation interface with generic type parameter for tuple type.
+ * Default parameter `Tuple` ensures backwards compatibility.
+ *
+ * @typeParam T - The tuple type for this relation. Defaults to `Tuple` (Record<string, unknown>).
+ *
+ * @example
+ * // Untyped usage (backwards compatible)
+ * const r = Bmg([{ id: 1 }]);  // Relation<Tuple>
+ *
+ * @example
+ * // Typed usage with full type safety
+ * interface Person { id: number; name: string }
+ * const r = Bmg<Person>([{ id: 1, name: 'Alice' }]);
+ * r.project(['id']);  // Relation<{ id: number }>
+ */
+export interface Relation<T = Tuple> {
+    restrict(p: TypedPredicate<T>): Relation<T>;
+    where(p: TypedPredicate<T>): Relation<T>;
+    exclude(p: TypedPredicate<T>): Relation<T>;
+    project<K extends keyof T>(attrs: K[]): Relation<Pick<T, K>>;
+    allbut<K extends keyof T>(attrs: K[]): Relation<Omit<T, K>>;
+    extend<E extends Record<string, unknown>>(e: TypedExtension<T, E>): Relation<T & E>;
+    constants<C extends Tuple>(consts: C): Relation<T & C>;
+    rename<R extends RenameMap<T>>(r: R): Relation<Renamed<T, R>>;
+    prefix<P extends string, Ex extends keyof T = never>(pfx: P, options?: {
+        except?: Ex[];
+    }): Relation<Prefixed<T, P, Ex>>;
+    suffix<S extends string, Ex extends keyof T = never>(sfx: S, options?: {
+        except?: Ex[];
+    }): Relation<Suffixed<T, S, Ex>>;
+    union(right: RelationOperand<T>): Relation<T>;
+    minus(right: RelationOperand<T>): Relation<T>;
+    intersect(right: RelationOperand<T>): Relation<T>;
+    matching<R>(right: RelationOperand<R>, keys?: TypedJoinKeysArray<T, R> | TypedJoinKeysObject<T, R>): Relation<T>;
+    not_matching<R>(right: RelationOperand<R>, keys?: TypedJoinKeysArray<T, R> | TypedJoinKeysObject<T, R>): Relation<T>;
+    join<R>(right: RelationOperand<R>, keys?: TypedJoinKeysArray<T, R> | TypedJoinKeysObject<T, R>): Relation<Joined<T, R>>;
+    left_join<R>(right: RelationOperand<R>, keys?: TypedJoinKeysArray<T, R> | TypedJoinKeysObject<T, R>): Relation<LeftJoined<T, R>>;
+    cross_product<R>(right: RelationOperand<R>): Relation<T & R>;
+    cross_join<R>(right: RelationOperand<R>): Relation<T & R>;
+    image<R, As extends string>(right: RelationOperand<R>, as: As, keys?: TypedJoinKeysArray<T, R> | TypedJoinKeysObject<T, R>): Relation<T & Record<As, Relation<Omit<R, keyof T & keyof R>>>>;
+    group<K extends keyof T, As extends string>(attrs: K[], as: As): Relation<Omit<T, K> & Record<As, Relation<Pick<T, K>>>>;
+    ungroup<K extends keyof T>(attr: K): Relation<Ungrouped<T, K>>;
+    wrap<K extends keyof T, As extends string>(attrs: K[], as: As): Relation<Wrapped<T, K, As>>;
+    unwrap<K extends keyof T>(attr: K): Relation<Unwrapped<T, K>>;
+    summarize<By extends keyof T, Aggs extends Aggregators>(by: By[], aggs: Aggs): Relation<Pick<T, By> & AggregatorResults<Aggs>>;
+    transform(t: Transformation): Relation<T>;
+    autowrap(options?: AutowrapOptions): Relation<Tuple>;
+    one(): T;
+    yByX<Y extends keyof T, X extends keyof T>(y: Y, x: X): Record<T[X] & PropertyKey, T[Y]>;
+    toArray(): T[];
+    isEqual(right: any): boolean;
+}
+export type RelationOperand<T = Tuple> = Relation<T> | T[];
+export interface OperationalOperand<T = Tuple> {
+    tuples(): Iterable<T>;
+    output(tuples: T[]): RelationOperand<T>;
+}

package/package.json

@@ -1,9 +1,21 @@
 {
   "name": "@enspirit/bmg-js",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Relational algebra for JavaScript/TypeScript - work with arrays of objects using powerful set operations",
-  "keywords": ["relational", "algebra", "relation", "set", "query", "data", "functional"],
+  "keywords": [
+    "relational",
+    "algebra",
+    "relation",
+    "set",
+    "query",
+    "data",
+    "functional"
+  ],
   "license": "MIT",
+  "files": [
+    "dist",
+    "src"
+  ],
   "repository": {
     "type": "git",
     "url": "https://github.com/enspirit/bmg.js"
@@ -11,24 +23,26 @@
   "type": "module",
   "source": "src/index.ts",
   "exports": {
-    "types": "./dist/src/index.d.ts",
+    "types": "./dist/index.d.ts",
     "require": "./dist/bmg.cjs",
     "default": "./dist/bmg.modern.js"
   },
   "main": "./dist/bmg.cjs",
   "module": "./dist/bmg.module.js",
-  "types": "./dist/src/index.d.ts",
+  "types": "./dist/index.d.ts",
   "unpkg": "./dist/bmg.umd.js",
   "scripts": {
-    "build": "microbundle",
+    "generate:lib-definitions": "npx tsx scripts/generate-lib-definitions.ts",
+    "build": "npm run generate:lib-definitions && microbundle --no-generateTypes && tsc -p tsconfig.build.json",
     "dev": "microbundle watch",
     "test": "vitest run",
     "test:watch": "vitest"
   },
   "devDependencies": {
     "microbundle": "^0.15.1",
+    "tsx": "^4.19.0",
     "vite-tsconfig-paths": "^5.1.4",
-    "vitest": "^1.4.0"
+    "vitest": "^4.0.16"
   },
   "packageManager": "pnpm@8.11.0+sha1.01bf39424f1008f29012bbae851d2acb8a20a0d0"
 }

package/src/Relation/Memory.ts

@@ -32,7 +32,6 @@ import {
 import type {
   AttrName,
   AutowrapOptions,
-  JoinKeys,
   Relation,
   RelationOperand,
   Transformation,
@@ -48,8 +47,10 @@ import type {
   Wrapped,
   Unwrapped,
   Ungrouped,
+  AggregatorResults,
+  TypedJoinKeysArray,
+  TypedJoinKeysObject,
 } from "../types";
-import type { AggregatorResults } from "../utility-types";
 
 /**
  * In-memory implementation of the Relation interface.
@@ -126,22 +127,22 @@ export class MemoryRelation<T = Tuple> implements Relation<T> {
 
   // === Semi-join operators ===
 
-  matching<R>(right: RelationOperand<R>, keys?: JoinKeys): Relation<T> {
-    return matching(this as any, right as any, keys) as unknown as Relation<T>;
+  matching<R>(right: RelationOperand<R>, keys?: TypedJoinKeysArray<T, R> | TypedJoinKeysObject<T, R>): Relation<T> {
+    return matching(this as any, right as any, keys as any) as unknown as Relation<T>;
   }
 
-  not_matching<R>(right: RelationOperand<R>, keys?: JoinKeys): Relation<T> {
-    return not_matching(this as any, right as any, keys) as unknown as Relation<T>;
+  not_matching<R>(right: RelationOperand<R>, keys?: TypedJoinKeysArray<T, R> | TypedJoinKeysObject<T, R>): Relation<T> {
+    return not_matching(this as any, right as any, keys as any) as unknown as Relation<T>;
   }
 
   // === Join operators ===
 
-  join<R>(right: RelationOperand<R>, keys?: JoinKeys): Relation<Joined<T, R>> {
-    return join(this as any, right as any, keys) as unknown as Relation<Joined<T, R>>;
+  join<R>(right: RelationOperand<R>, keys?: TypedJoinKeysArray<T, R> | TypedJoinKeysObject<T, R>): Relation<Joined<T, R>> {
+    return join(this as any, right as any, keys as any) as unknown as Relation<Joined<T, R>>;
   }
 
-  left_join<R>(right: RelationOperand<R>, keys?: JoinKeys): Relation<LeftJoined<T, R>> {
-    return left_join(this as any, right as any, keys) as unknown as Relation<LeftJoined<T, R>>;
+  left_join<R>(right: RelationOperand<R>, keys?: TypedJoinKeysArray<T, R> | TypedJoinKeysObject<T, R>): Relation<LeftJoined<T, R>> {
+    return left_join(this as any, right as any, keys as any) as unknown as Relation<LeftJoined<T, R>>;
   }
 
   cross_product<R>(right: RelationOperand<R>): Relation<T & R> {
@@ -154,8 +155,8 @@ export class MemoryRelation<T = Tuple> implements Relation<T> {
 
   // === Nesting operators ===
 
-  image<R, As extends string>(right: RelationOperand<R>, as: As, keys?: JoinKeys): Relation<T & Record<As, Relation<Omit<R, keyof T & keyof R>>>> {
-    return image(this as any, right as any, as, keys) as unknown as Relation<T & Record<As, Relation<Omit<R, keyof T & keyof R>>>>;
+  image<R, As extends string>(right: RelationOperand<R>, as: As, keys?: TypedJoinKeysArray<T, R> | TypedJoinKeysObject<T, R>): Relation<T & Record<As, Relation<Omit<R, keyof T & keyof R>>>> {
+    return image(this as any, right as any, as, keys as any) as unknown as Relation<T & Record<As, Relation<Omit<R, keyof T & keyof R>>>>;
   }
 
   group<K extends keyof T, As extends string>(attrs: K[], as: As): Relation<Omit<T, K> & Record<As, Relation<Pick<T, K>>>> {

package/src/index.ts

@@ -1,6 +1,6 @@
 export * from './operators';
 export * from './types';
-export * from './utility-types';
+export { LIB_DEFINITIONS } from './lib-definitions';
 
 import { MemoryRelation } from './Relation';
 import { isRelation } from './operators';