@cliffy-ga/core

> Alpha Release - API may change. Not recommended for production use.

Cliffy is a reactive framework built on Functional Reactive Programming (FRP) and Geometric Algebra (GA). It provides elegant primitives for building collaborative, real-time applications.

Installation

``bash
npm install @cliffy-ga/core
`

Quick Start

`typescript
import init, { behavior, combine, wedge } from '@cliffy-ga/core';
import { html, mount } from '@cliffy-ga/core/html';

await init();

// Create reactive state
const count = behavior(0);

// Derive new behaviors
const doubled = count.map(n => n * 2);

// Combine multiple behaviors
const sum = wedge(count, doubled).map((a, b) => a + b);

// Render with Algebraic TSX
const app = html

mount(app, '#app');
`

Core Concepts

$3

A Behavior represents a value that changes over time. Unlike React state, behaviors are continuous signals with automatic dependency tracking.

`typescript
const name = behavior('World');

// Read current value
name.sample(); // 'World'

// Update value
name.set('Cliffy');
name.update(s => s.toUpperCase());

// Derive new behaviors
const greeting = name.map(n => Hello, ${n}!);

// Subscribe to changes
name.subscribe(value => console.log(value));
`

$3

Use combine for two behaviors, or wedge for any number:

`typescript
// Two behaviors
const area = combine(width, height, (w, h) => w * h);

// Three or more behaviors (wedge product)
const volume = wedge(width, height, depth).map((w, h, d) => w h d);

const isValid = wedge(a, b, c, d).map((a, b, c, d) =>
a && b && c && d
);
`

The wedge function creates a Blade - inspired by Clifford algebra's wedge product (∧) which combines vectors into higher-grade multivectors.

$3

`typescript
// Project through a condition (null when false)
const message = isVisible.project(() => 'Hello!');

// Select between two values
const theme = isDarkMode.select(
() => 'dark',
() => 'light'
);
`

$3

An Event represents discrete occurrences over time.

`typescript
const clicks = event();

// Emit events
clicks.emit(mouseEvent);

// Transform events
const xPositions = clicks.map(e => e.clientX);

// Filter events
const leftClicks = clicks.filter(e => e.button === 0);

// Accumulate into a Behavior
const clickCount = clicks.fold(0, (count, _) => count + 1);
`

Geometric Types

For animations and spatial applications, Cliffy exposes geometric algebra primitives:

`typescript
import { Rotor, Translation, Transform, GeometricState } from '@cliffy-ga/core';

// Rotations (no gimbal lock)
const rot = Rotor.xy(Math.PI / 2); // 90° in XY plane

// Translations
const move = new Translation(10, 0, 0);

// Combined transforms
const transform = Transform.fromRotorAndTranslation(rot, move);

// Interpolation with .blend()
const midRotation = startRot.blend(endRot, 0.5);
const midPosition = startPos.blend(endPos, t);
`

Algebraic TSX

The html tagged template provides reactive DOM rendering:

`typescript
import { html, mount } from '@cliffy-ga/core/html';

const todos = behavior([]);
const newTodo = behavior('');

const app = html

mount(app, '#app');
`

API Reference

$3

| Method | Description |
|--------|-------------|
| sample() | Get current value |
| set(value) | Set new value |
| update(fn) | Transform value with function |
| map(fn) | Derive new behavior |
| combine(other, fn) | Combine with another behavior |
| project(fn) | Project value through condition |
| select(thenFn, elseFn) | Select between two values |
| subscribe(fn) | React to changes |

$3

| Function | Description |
|----------|-------------|
| combine(a, b, fn) | Combine two behaviors |
| wedge(...behaviors) | Create a Blade from multiple behaviors |
| Blade.map(fn) | Project blade to new behavior |

$3

| Type | Description |
|------|-------------|
| Rotor | Rotation (no gimbal lock) |
| Translation | 3D translation |
| Transform | Combined rotation + translation |
| GeometricState | General multivector state |
| Versor | Rotation or reflection |

All geometric types support .blend(other, t)` for interpolation.

Alpha Status

This is an alpha release. The following may change:

- API names and signatures
- Module structure and exports
- Performance characteristics
- Error messages and handling

Please report issues at: https://github.com/industrial-algebra/cliffy/issues

License

MIT