feat(variations): add lazy and eager generator functions

Author: macarie

packages/variations/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@wluwd/variations",
-	"description": "",
+	"description": "Generate all possible variations of object properties using cartesian products",
 	"version": "0.1.0",
 	"license": "MIT",
 	"repository": {

packages/variations/readme.md

@@ -1 +1,266 @@
 # @wluwd/variations
+
+> Generate all possible variations of object properties using cartesian products
+
+A lightweight, type-safe utility for generating all combinations of object properties. Perfect for testing component variants, creating configuration matrices, or any scenario where you need exhaustive combinations.
+
+## Features
+
+- 📦 **Type-safety**: full TypeScript support with precise type inference
+- 🪶 **Lightweight**: zero dependencies, ESM-only, minimal bundle size
+- 🏎️ **Efficient**: memory-efficient lazy evaluation for large datasets
+- 🌐 **Universal**: works in LTS Node.js (20+) and modern browsers
+
+## Installation
+
+> [!WARNING]
+> This package is ESM only. Ensure your project uses `"type": "module"` in `package.json`.
+
+```bash
+npm install @wluwd/variations
+```
+
+```bash
+pnpm add @wluwd/variations
+```
+
+```bash
+yarn add @wluwd/variations
+```
+
+## The Problem
+
+When testing UI components with multiple props, manually writing test cases becomes unsustainable.
+
+```tsx
+// Manual approach - error-prone and difficult and exhausting to maintain
+it('renders primary small button', () => { /* ... */ })
+it('renders primary normal button', () => { /* ... */ })
+it('renders primary large button', () => { /* ... */ })
+it('renders secondary small button', () => { /* ... */ })
+// ... many more tests to write by hand
+```
+
+What if there's a better way though? That's where this library comes into play:
+
+```tsx
+// Automated approach - declarative and maintainable
+const testCases = eagerVariations({
+  variant: ['primary', 'secondary', 'destructive'],
+  size: ['small', 'normal', 'large'],
+  status: ['idle', 'loading', 'disabled']
+});
+
+it.for(testCases)('Button: %o', (props) => { /* ... */ });
+// ✨ all tests generated automatically
+```
+
+## Quick Start
+
+### Basic Usage
+
+```ts
+import { eagerVariations } from '@wluwd/variations';
+
+const configs = eagerVariations({
+  color: ['red', 'blue', 'green'],
+  size: ['small', 'large']
+});
+
+console.log(configs);
+// [
+//   { color: 'red', size: 'small' },
+//   { color: 'red', size: 'large' },
+//   { color: 'blue', size: 'small' },
+//   { color: 'blue', size: 'large' },
+//   { color: 'green', size: 'small' },
+//   { color: 'green', size: 'large' }
+// ]
+```
+
+### Type-Safe Factory
+
+For better autocomplete and output type inference, use `defineVariations`:
+```ts
+import { defineVariations } from '@wluwd/variations';
+
+interface ButtonProps {
+  variant: 'primary' | 'secondary';
+  size: 'small' | 'large';
+}
+
+const { eager, lazy } = defineVariations<ButtonProps>();
+
+// 🪄 Full autocomplete with inferred output type:
+//  { variant: 'primary'; size: 'small' | 'large' }
+const variations = eager({
+  variant: ['primary'],
+  size: ['small', 'large']
+});
+```
+
+### With Filtering
+
+```ts
+const validConfigs = eagerVariations(
+  {
+    variant: ['primary', 'link'],
+    size: ['small', 'large']
+  },
+  {
+    // Skip invalid combinations
+    filter: v => !(v.variant === 'link' && v.size === 'large')
+  }
+);
+```
+
+### Memory-Efficient Processing
+
+For large datasets, use `lazyVariations` to process one variation at a time:
+
+```ts
+import { lazyVariations } from '@wluwd/variations';
+
+for (const config of lazyVariations({
+  variant: ['primary', 'secondary', 'destructive'],
+  size: ['small', 'normal', 'large'],
+  status: ['idle', 'loading', 'disabled']
+})) {
+  // Process each of 27 variations without loading all into memory
+  await processConfig(config);
+}
+```
+
+## API
+
+### `eagerVariations(base, options?)`
+
+Generates all variations and returns them as an array.
+
+**Parameters:**
+- `base` - Object where each property is an array of possible values
+- `options?` - Optional configuration object
+  - `filter?` - Function to filter which variations to include
+  - `safe?` - If `true`, returns empty array for invalid input instead of throwing
+
+**Returns:** Array of all variation objects
+
+### `lazyVariations(base, options?)`
+
+Generates variations one at a time using a generator.
+
+**Parameters:** Same as `eagerVariations`
+
+**Yields:** Individual variation objects
+
+### `defineVariations<T>()`
+
+Creates a type-safe factory bound to a specific interface. It returns an object with two methods: `eager` and `lazy`. These work the same way as their stand-alone counterparts.
+
+```ts
+interface ButtonProps {
+  variant: 'primary' | 'secondary';
+  size: 'small' | 'large';
+}
+
+const { eager } = defineVariations<ButtonProps>();
+
+// 🪄 `eager` provides autocomplete for properties
+const variations = eager({
+  variant: ['primary'],
+  size: ['small', 'large']
+});
+// typeof variations → Array<{ variant: 'primary', size: 'small' | 'large' }>
+```
+
+### `VariationsInput<T>`
+
+Type helper for explicitly typing variation inputs.
+
+```ts
+interface ButtonProps {
+  variant: 'primary' | 'secondary';
+  size: 'small' | 'large';
+}
+
+const input = {
+  variant: ['primary', 'secondary'],
+  size: ['small']
+} satisfies VariationsInput<ButtonProps>;
+```
+
+This type is useful when directly using `eagerVariations` or `lazyVariations` as it allows to get the same output type as the helpers bound by `defineVariations`:
+
+```ts
+interface ButtonProps {
+  variant: 'primary' | 'secondary';
+  size: 'small' | 'large';
+}
+
+const variations = eagerVariations({
+  variant: ['primary'],
+  size: ['small', 'large']
+} satisfies VariationsInput<ButtonProps>);
+
+// typeof variations → Array<{ variant: 'primary', size: 'small' | 'large' }>
+```
+
+## Real-World Example
+
+Visual regression testing for a design system:
+
+```tsx
+import { eagerVariations } from '@wluwd/variations';
+import { render } from '@testing-library/react';
+
+interface ButtonProps {
+  variant: 'primary' | 'secondary' | 'destructive' | 'link';
+  size: 'small' | 'normal' | 'large';
+  status?: 'loading' | 'disabled';
+}
+
+describe('Button visual regression', () => {
+  const cases = eagerVariations({
+    variant: ['primary', 'secondary', 'destructive', 'link'],
+    size: ['small', 'normal', 'large'],
+    status: [undefined, 'loading', 'disabled']
+  } satisfies VariationsInput<ButtonProps>);
+
+  it.for(cases)('matches snapshot: %o', async (props) => {
+    const screen = render(<Button {...props}>Click me</Button>);
+
+    // Test default state
+    expect(screen.getButton()).toMatchSnapshot();
+
+    // Test hover state
+    await userEvent.hover(screen.getButton());
+    expect(screen.getButton()).toMatchSnapshot();
+
+    // Test active state
+    await userEvent.click(screen.getButton());
+    expect(screen.getButton()).toMatchSnapshot();
+  });
+});
+
+// ✨ Generates 108 comprehensive tests automatically
+```
+
+## Background
+
+This library was born from the need to test design system components exhaustively without manual overhead. What started as checking a handful of button variants eventually grew to 120+ combinations that needed verification for every CSS change.
+
+Read the full story: [When Manual Testing Becomes Unsustainable](https://macarie.me/writing/when-manual-testing-becomes-unsustainable/).
+
+## Performance
+
+The algorithm uses an odometer/mixed-radix counter approach that:
+
+- Only updates changed dimensions between iterations
+- Maintains stable object shapes for optimization
+- Supports lazy evaluation to avoid loading all combinations into memory
+
+Keys are processed left-to-right, with leftmost keys being most stable (changing least frequently).
+
+## License
+
+MIT