Installation

From npm (Enterprise)

npm install @hyperbridge/forge

Subpath Imports

Import only what you need using subpath imports:

// Client-side UI
import { createElement, useState, useEffect } from '@hyperbridge/forge/client';

// Server-side
import { Forge, Router } from '@hyperbridge/forge/server';

// Data & ORM
import { PgConnection, Model } from '@hyperbridge/forge/data';

// Auth
import { PasswordAuth, JWT, OAuth2Provider } from '@hyperbridge/forge/auth';

// Forms with validation
import { Form, fromSchema } from '@hyperbridge/forge/form';
import { Schema } from '@hyperbridge/forge/schema';

// Animations
import { Tween, Spring, onScroll } from '@hyperbridge/forge/animate';

// And more...
import { Chart } from '@hyperbridge/forge/chart';
import { SearchForge } from '@hyperbridge/forge/search';
import { Notify } from '@hyperbridge/forge/notify';
import { I18n } from '@hyperbridge/forge/i18n';
import { PDFForge } from '@hyperbridge/forge/pdf';
import { SMTPClient } from '@hyperbridge/forge/mail';
import { CLI } from '@hyperbridge/forge/cli';
import { TestRunner, expect } from '@hyperbridge/forge/test';

Quick Start

Browser UI with forge/client

import { createElement as h, useState, render } from '@hyperbridge/forge/client';

function App() {
  const [count, setCount] = useState(0);
  return h('div', { style: { padding: '20px' } },
    h('h1', null, `Count: ${count}`),
    h('button',
      { onClick: () => setCount(count + 1) },
      'Increment'
    )
  );
}

render(h(App), document.getElementById('root'));

Server with forge/server

import { Forge, Router } from '@hyperbridge/forge/server';

const app = new Forge();
const router = new Router();

router.get('/', (req, res) => {
  res.json({ message: 'Hello World' });
});

router.get('/users/:id', async (req, res) => {
  const { id } = req.params;
  res.json({ id, name: 'John Doe' });
});

app.use(router);
app.listen(3000, () => console.log('Server running on :3000'));

Forms with Validation

import { Form, fromSchema } from '@hyperbridge/forge/form';
import { Schema } from '@hyperbridge/forge/schema';

const schema = Schema.object({
  email: Schema.string().email('Invalid email'),
  password: Schema.string().min(8, 'Min 8 chars'),
  name: Schema.string(),
});

const form = new Form({ schema });

async function handleSubmit(data) {
  const result = await form.validate(data);
  if (result.valid) {
    console.log('Validated:', result.data);
  } else {
    console.log('Errors:', result.errors);
  }
}

Database Queries

import { PgConnection, Model } from '@hyperbridge/forge/data';

class User extends Model {
  static table = 'users';
}

const conn = new PgConnection({
  host: 'localhost',
  user: 'postgres',
  password: 'secret',
  database: 'myapp',
});

// Insert
const user = await conn.insert('users', {
  email: 'john@example.com',
  name: 'John Doe',
});

// Query
const users = await conn.query('SELECT * FROM users');

// Update
await conn.update('users', { name: 'Jane' }, { where: { id: 1 } });

// Delete
await conn.delete('users', { where: { id: 1 } });

Authentication

import { PasswordAuth, JWT } from '@hyperbridge/forge/auth';

const auth = new PasswordAuth();

// Register
const result = await auth.register('john@example.com', 'password123');

// Login
const session = await auth.login('john@example.com', 'password123');

// Verify token
const decoded = await JWT.verify(session.token, 'secret-key');

// OAuth2
import { OAuth2Provider } from '@hyperbridge/forge/auth';

const google = new OAuth2Provider('google', {
  clientId: 'YOUR_CLIENT_ID',
  clientSecret: 'YOUR_SECRET',
  redirectUri: 'http://localhost:3000/auth/google/callback',
});

const authUrl = google.getAuthUrl();

Animations

import { Tween, Spring, onScroll, stagger } from '@hyperbridge/forge/animate';

// Tween animation
const tween = new Tween({
  target: element,
  duration: 500,
  values: { opacity: [0, 1], y: [20, 0] },
  easing: 'easeOutQuad',
});
tween.play();

// Spring animation
const spring = new Spring({
  target: element,
  tension: 300,
  friction: 10,
  mass: 1,
  values: { scale: [0.8, 1] },
});

// Scroll-triggered animation
onScroll((progress) => {
  element.style.opacity = progress;
});

// Stagger elements
const elements = document.querySelectorAll('.item');
stagger(elements, {
  duration: 300,
  delay: 50,
});

forge/client

Fiber-based concurrent UI framework with VDOM, 146+ APIs, priority lanes, hooks, signals, atoms, routing, CSS-in-JS, SSR, and more. Zero dependencies. ~8,750 lines.

Core Rendering

import { h, render, Fragment } from '@hyperbridge/forge/client';

function App() {
  return h(Fragment, null,
    h('h1', null, 'Hello HBForge'),
    h('p', null, 'Fiber-based concurrent rendering')
  );
}

render(h(App), document.getElementById('root'));

Hooks

import { h, useState, useEffect, useRef } from '@hyperbridge/forge/client';

function Timer() {
  const [seconds, setSeconds] = useState(0);
  const intervalRef = useRef(null);

  useEffect(() => {
    intervalRef.current = setInterval(() => {
      setSeconds(s => s + 1);
    }, 1000);
    return () => clearInterval(intervalRef.current);
  }, []);

  return h('p', null, `Elapsed: ${seconds}s`);
}

Signals & Reactive State

Signals provide fine-grained reactivity outside the VDOM. Unlike hooks, which schedule a component re-render, a signal update surgically patches the DOM node it is bound to. This makes signals ideal for high-frequency updates like counters, progress bars, and real-time data feeds.

import { h, signal, computed, useSignal, bindSignalToText } from '@hyperbridge/forge/client';

const count = signal(0);
const doubled = computed(() => count.value * 2);

function Display() {
  const val = useSignal(doubled);
  return h('p', null, `Doubled: ${val}`);
}

// Direct DOM binding — bypasses VDOM entirely
const el = document.getElementById('counter');
bindSignalToText(count, el);
count.value = 5; // el.textContent instantly becomes "5"

Atoms & Global State

import { h, atom, derived, useAtom } from '@hyperbridge/forge/client';

const todosAtom = atom([]);
const countAtom = derived([todosAtom], ([todos]) => todos.length);

function TodoList() {
  const [todos, setTodos] = useAtom(todosAtom);
  const [count] = useAtom(countAtom);

  const add = () => setTodos(t => [...t, { text: 'New', done: false }]);

  return h('div', null,
    h('p', null, `${count} items`),
    h('button', { onClick: add }, 'Add Todo'),
    ...todos.map(t => h('p', null, t.text))
  );
}

Async Data & Mutations

import { h, useAsync, useMutation, invalidateCache } from '@hyperbridge/forge/client';

function UserProfile({ userId }) {
  const { data: user, loading, error } = useAsync(
    () => fetch(`/api/users/${userId}`).then(r => r.json()),
    [userId]
  );
  const { mutate: updateName, loading: saving } = useMutation(
    (name) => fetch(`/api/users/${userId}`, {
      method: 'PATCH', body: JSON.stringify({ name }),
    })
  );

  if (loading) return h('p', null, 'Loading...');
  if (error) return h('p', null, `Error: ${error.message}`);

  return h('div', null,
    h('h2', null, user.name),
    h('button', {
      onClick: () => updateName('New Name').then(() => invalidateCache()),
      disabled: saving,
    }, saving ? 'Saving...' : 'Rename')
  );
}

Router & Navigation

import { h, render, Router, Route, Link, useRouter } from '@hyperbridge/forge/client';

function Home() {
  return h('div', null,
    h('h1', null, 'Home'),
    h(Link, { to: '/users/42' }, 'View User')
  );
}

function UserPage() {
  const { params, back } = useRouter();
  return h('div', null,
    h('h1', null, `User #${params.id}`),
    h('button', { onClick: back }, 'Go Back')
  );
}

const router = new Router([
  new Route('/', Home),
  new Route('/users/:id', UserPage),
]);

// Navigation guards
router.beforeEach((to, from) => {
  if (to.path.startsWith('/admin') && !isLoggedIn()) return false;
});

render(h(router), document.getElementById('root'));

Context & Selectors

import { h, createContext, useContextSelector } from '@hyperbridge/forge/client';

const AppContext = createContext({ user: null, theme: 'dark', lang: 'en' });

// Only re-renders when user.name changes — not on theme/lang changes
function UserName() {
  const name = useContextSelector(AppContext, ctx => ctx.user?.name);
  return h('span', null, name || 'Guest');
}

Forms & Validation

CSS-in-JS

import { h, css, styled, keyframes, globalStyles } from '@hyperbridge/forge/client';

globalStyles(`body { margin: 0; font-family: system-ui; }`);

const fadeIn = keyframes(`
  from { opacity: 0; transform: translateY(10px); }
  to   { opacity: 1; transform: translateY(0); }
`);

const cardClass = css(`
  padding: 24px;
  border-radius: 12px;
  background: #1a1a2e;
  animation: ${fadeIn} 0.3s ease-out;
`);

const Button = styled('button', `
  padding: 10px 20px;
  border: none;
  border-radius: 6px;
  background: #6366f1;
  color: white;
  cursor: pointer;
  &:hover { background: #4f46e5; }
`);

function Card() {
  return h('div', { className: cardClass },
    h(Button, { onClick: () => alert('Clicked') }, 'Click Me')
  );
}

Animation Hooks

import { h, useSpring, Animated } from '@hyperbridge/forge/client';

function BouncyCard() {
  const [style, api] = useSpring({ scale: 1, opacity: 1 });

  return h(Animated.div, {
    style,
    onMouseEnter: () => api.start({ scale: 1.05 }),
    onMouseLeave: () => api.start({ scale: 1 }),
  }, 'Hover me!');
}

Transitions

Batching & Concurrent

use() Hook

import { h, use, Suspense } from '@hyperbridge/forge/client';

const dataPromise = fetch('/api/data').then(r => r.json());

function DataView() {
  const data = use(dataPromise); // suspends until resolved
  return h('pre', null, JSON.stringify(data, null, 2));
}

function App() {
  return h(Suspense, { fallback: h('p', null, 'Loading...') },
    h(DataView)
  );
}

SSR & Server Components

Error Boundaries

import { h, createRecoverableErrorBoundary } from '@hyperbridge/forge/client';

const SafeZone = createRecoverableErrorBoundary({
  maxRetries: 3,
  fallback: (error, retry) => h('div', null,
    h('p', null, `Error: ${error.message}`),
    h('button', { onClick: retry }, 'Retry')
  ),
  onError: (error) => console.error('Boundary caught:', error),
});

function App() {
  return h(SafeZone, null, h(RiskyComponent));
}

Events & EventBus

Internationalization (i18n)

Head & Meta Management

Theme & Accessibility

import { h, createTheme, ThemeProvider, useTheme } from '@hyperbridge/forge/client';

const lightTheme = createTheme({
  bg: '#ffffff', text: '#1a202c', primary: '#6366f1',
});
const darkTheme = createTheme({
  bg: '#0a0a0f', text: '#f1f5f9', primary: '#818cf8',
});

function ThemeToggle() {
  const { theme, setTheme } = useTheme();
  return h('button', {
    onClick: () => setTheme(theme === lightTheme ? darkTheme : lightTheme),
  }, 'Toggle Theme');
}

function App() {
  return h(ThemeProvider, { theme: darkTheme }, h(ThemeToggle));
}

Fetch Client

import { createFetchClient } from '@hyperbridge/forge/client';

const api = createFetchClient({
  baseURL: 'https://api.example.com',
  timeout: 5000,
  retry: 3,
  interceptors: {
    request: (config) => {
      config.headers.Authorization = `Bearer ${getToken()}`;
      return config;
    },
    response: (response) => {
      if (response.status === 401) refreshToken();
      return response;
    },
  },
});

const users = await api.get('/users');
await api.post('/users', { name: 'Alice' });

Multi-Tab Sync & Web Vitals

import { h, useSyncedState, reportWebVitals } from '@hyperbridge/forge/client';

// Sync cart state across tabs
function CartIcon() {
  const [cartCount, setCartCount] = useSyncedState('cart-count', 0);
  // Updates in one tab instantly reflect in all other tabs
  return h('span', null, `Cart (${cartCount})`);
}

// Report metrics to analytics
reportWebVitals((metric) => {
  console.log(metric.name, metric.value); // "LCP" 1234
  navigator.sendBeacon('/analytics', JSON.stringify(metric));
});

Utility Hooks

import { h, useLocalStorage, useMediaQuery, useOnClickOutside, useRef }
  from '@hyperbridge/forge/client';

function Dropdown() {
  const ref = useRef(null);
  const [open, setOpen] = useLocalStorage('dropdown-open', false);
  const isMobile = useMediaQuery('(max-width: 768px)');

  useOnClickOutside(ref, () => setOpen(false));

  return h('div', { ref },
    h('button', { onClick: () => setOpen(o => !o) },
      isMobile ? 'Menu' : 'Options'
    ),
    open && h('ul', { className: 'dropdown' },
      h('li', null, 'Profile'),
      h('li', null, 'Settings'),
      h('li', null, 'Logout')
    )
  );
}

Advanced APIs

DevTools

Form Actions

import { h, useFormState, useFormAction, ProgressiveForm } from '@hyperbridge/forge/client';

function CreatePost() {
  const [state, formAction] = useFormState('/api/posts', { error: null, success: false });
  const { pending } = useFormAction(formAction);

  return h(ProgressiveForm, { action: formAction },
    h('input', { name: 'title', placeholder: 'Post title', required: true }),
    h('textarea', { name: 'body', placeholder: 'Write your post...' }),
    h('button', { type: 'submit', disabled: pending }, pending ? 'Saving...' : 'Publish'),
    state.error && h('p', { class: 'error' }, state.error),
    state.success && h('p', { class: 'success' }, 'Post created!')
  );
}

Hydration Mismatch Detection

import { h, hydrateWithMismatchDetection, configureHydration } from '@hyperbridge/forge/client';

configureHydration({
  mode: 'strict',                     // 'strict' | 'warn' | 'silent'
  onMismatch(path, expected, actual) {
    reportToMonitoring({ path, expected, actual });
  }
});

function App() {
  return h('div', null,
    h('h1', null, 'My App'),
    h('span', { suppressHydrationWarning: true }, new Date().toLocaleTimeString())
  );
}

hydrateWithMismatchDetection(h(App), document.getElementById('root'));

Enhanced Server Components

import { h, createServerAction, ServerBoundary, registerClientComponent } from '@hyperbridge/forge/client';

// Server action — runs on the server, callable from client
const saveUser = createServerAction(async (formData) => {
  const user = await db.users.update(formData.id, {
    name: formData.name,
    email: formData.email
  });
  return { success: true, user };
});

// Client island inside a server-rendered page
const LikeButton = registerClientComponent(function LikeButton({ postId }) {
  const [liked, setLiked] = useState(false);
  return h('button', { onClick: () => setLiked(!liked) }, liked ? 'Liked' : 'Like');
});

function UserProfile({ userId }) {
  return h(ServerBoundary, { fallback: h('p', null, 'Loading profile...') },
    h('div', { class: 'profile' },
      h('h2', null, 'User Profile'),
      h(LikeButton, { postId: userId })
    )
  );
}

Auto-Memoization

import { h, render, enableAutoMemo, disableAutoMemo, AutoMemoProvider } from '@hyperbridge/forge/client';

// Enable globally — all components are auto-memoized
enableAutoMemo();

function ExpensiveList({ items }) {
  return h('ul', null, items.map(item =>
    h('li', { key: item.id }, item.name)
  ));
}

function App() {
  return h('div', null,
    h(ExpensiveList, { items: data }),            // auto-memoized
    h(AutoMemoProvider, { enabled: false },
      h(AlwaysRerenderWidget, null)               // opts out of auto-memo
    )
  );
}

render(h(App), document.getElementById('root'));

Enhanced useOptimistic

import { h, useOptimisticAction, useOptimisticMutation } from '@hyperbridge/forge/client';

function TodoList() {
  const [todos, addTodo] = useOptimisticMutation('/api/todos', {
    add(current, newTodo) {
      return [...current, { ...newTodo, id: 'temp-' + Date.now(), pending: true }];
    },
    rollback(current, failedTodo) {
      return current.filter(t => t.id !== failedTodo.id);
    }
  });

  const [likeState, likeAction] = useOptimisticAction(
    '/api/like',
    (prev, postId) => ({ ...prev, [postId]: (prev[postId] || 0) + 1 })
  );

  return h('div', null,
    h('button', { onClick: () => addTodo({ title: 'New task' }) }, 'Add Todo'),
    h('ul', null, todos.map(todo =>
      h('li', { key: todo.id, class: todo.pending ? 'pending' : '' }, todo.title)
    ))
  );
}

Test Utilities

import { h } from '@hyperbridge/forge/client';
import { renderForTest, screen, fireEvent, waitForUpdate, act } from '@hyperbridge/forge/client/test';

function Counter() {
  const [count, setCount] = useState(0);
  return h('div', null,
    h('span', { 'data-testid': 'count' }, String(count)),
    h('button', { onClick: () => setCount(c => c + 1) }, 'Increment')
  );
}

// Test
const { cleanup } = renderForTest(h(Counter));

expect(screen.getByTestId('count').textContent).toBe('0');

await act(async () => {
  fireEvent.click(screen.getByText('Increment'));
  await waitForUpdate();
});

expect(screen.getByTestId('count').textContent).toBe('1');
cleanup();

Hot Module Replacement

import { h, render, preserveStateOnHMR } from '@hyperbridge/forge/client';
import { createHMRClient } from '@hyperbridge/forge/client/hmr';

const hmr = createHMRClient({ port: 3001 });

const App = preserveStateOnHMR('App', function App() {
  const [count, setCount] = useState(0);
  return h('div', null,
    h('p', null, `Count: ${count}`),
    h('button', { onClick: () => setCount(c => c + 1) }, '+1')
  );
});

render(h(App), document.getElementById('root'));

// Accept hot updates and re-render
if (hmr.hot) {
  hmr.hot.accept('./App', (updatedModule) => {
    render(h(updatedModule.default), document.getElementById('root'));
  });

  hmr.hot.dispose(() => {
    console.log('Cleaning up before hot reload...');
  });
}

forge/server

Full-featured HTTP framework — radix-trie router, 20+ built-in middleware, WebSocket (RFC 6455), GraphQL engine, cron scheduler, task queue, JWT auth, circuit breaker, LRU cache, HTTP client, PubSub, plugin system, DI container, OpenTelemetry tracing, Prometheus metrics, HTTP/2, cluster mode, and more. 120+ APIs, zero dependencies, ~7,500 lines.

1. Core

import { Forge } from '@hyperbridge/forge/server';

const app = new Forge();
app.set('env', 'production');

app.onShutdown(async () => {
  await db.close();
  console.log('Cleanup complete');
});

app.get('/api/status', (req, res) => {
  res.json({ status: 'ok', uptime: process.uptime() });
});

app.listen(3000, () => console.log('Running'));

// Cluster mode — spawns one worker per CPU core
Forge.cluster(() => {
  const app = new Forge();
  app.get('/', (req, res) => res.json({ pid: process.pid }));
  app.listen(3000);
}, { workers: 4 });

2. Router

const app = new Forge();

// Route params
app.get('/users/:id', (req, res) => {
  res.json({ userId: req.params.id });
});

// Wildcard catch-all
app.get('/files/*', (req, res) => {
  res.json({ path: req.params['*'] });
});

// Route groups with shared auth middleware
app.group('/api/v1', (g) => {
  g.use(authMiddleware);
  g.get('/users', listUsers);
  g.post('/users', createUser);
  g.group('/admin', (admin) => {
    admin.get('/stats', getStats);
  });
});

app.listen(3000);

3. Middleware (21+)

import { Forge, bodyParser, cors, helmet, logger, rateLimit,
         compression, serveStatic, timeout } from '@hyperbridge/forge/server';

const app = new Forge();

// Middleware stack
app.use(logger({ level: 'info' }));
app.use(cors({ origin: 'https://myapp.com', credentials: true }));
app.use(helmet({ csp: "default-src 'self'" }));
app.use(compression({ threshold: 512 }));
app.use(rateLimit({ windowMs: 60000, max: 100 }));
app.use(timeout(30000));
app.use(bodyParser.json({ limit: '2mb' }));
app.use(serveStatic('./public', { maxAge: 86400 }));

app.get('/api/data', (req, res) => res.json({ ok: true }));
app.listen(3000);

rateLimit Options

4. WebSocket

import { Forge, WebSocketServer } from '@hyperbridge/forge/server';

const app = new Forge();

app.ws((wss) => {
  wss.on('connection', (client, req) => {
    console.log(`Client ${client.id} connected`);

    wss.join(client, 'lobby');

    client.on('message', (data) => {
      // Broadcast to room
      wss.to('lobby').emit({ type: 'chat', ...data });
    });

    client.on('close', () => {
      wss.leave(client, 'lobby');
    });
  });
});

app.listen(3000);

5. GraphQL Engine

import { Forge, DataLoader } from '@hyperbridge/forge/server';

const app = new Forge();

const schema = `
  type User { id: ID!, name: String!, email: String }
  type Query {
    user(id: ID!): User
    users: [User!]!
  }
  type Mutation {
    createUser(name: String!, email: String!): User!
  }
`;

const userLoader = new DataLoader(async (ids) => {
  const users = await db.findByIds(ids);
  return ids.map(id => users.find(u => u.id === id) || null);
});

app.graphql(schema, {
  Query: {
    user: (_, { id }) => userLoader.load(id),
    users: () => db.allUsers(),
  },
  Mutation: {
    createUser: (_, { name, email }) => db.createUser({ name, email }),
  },
});

app.listen(3000); // GraphQL at POST /graphql

6. CronScheduler

import { Forge } from '@hyperbridge/forge/server';

const app = new Forge();

// Run every day at 2:00 AM
app.cron('cleanup', '0 2 * * *', async () => {
  await db.cleanup();
  console.log('Daily maintenance complete');
});

// Run every 5 minutes
app.cron('sync', '*/5 * * * *', async () => {
  await syncExternalData();
});

app.listen(3000);

7. TaskQueue

import { TaskQueue } from '@hyperbridge/forge/server';

const queue = new TaskQueue({ concurrency: 10 });
queue.persist('./data/jobs.json').restore();

queue.register('sendEmail', async (data) => {
  await emailService.send(data.to, data.subject, data.body);
});

queue.on('failed', (task, err) => {
  console.error(`Task ${task.id} failed: ${err.message}`);
});

await queue.add('sendEmail', {
  to: 'user@example.com',
  subject: 'Welcome',
  body: 'Hello!'
}, { priority: 10, maxRetries: 5 });

8. JWT

import { Forge, JWT } from '@hyperbridge/forge/server';

const jwt = new JWT(process.env.JWT_SECRET, { expiresIn: 7200 });
const app = new Forge();

app.post('/auth/login', async (req, res) => {
  const user = await authenticate(req.body);
  const token = jwt.sign({ id: user.id, role: user.role });
  res.json({ token });
});

// Protected route
app.get('/api/profile', jwt.middleware(), (req, res) => {
  res.json({ user: req.user });
});

app.listen(3000);

9. Validator & Schema

import { Forge, v } from '@hyperbridge/forge/server';

const app = new Forge();

const createUserSchema = v.object({
  name: v.string().min(2).max(100),
  email: v.string().email(),
  age: v.number().int().min(18).optional(),
  role: v.enum(['admin', 'user']).default('user'),
});

app.post('/users', createUserSchema.bodyParser(), (req, res) => {
  // req.body is validated and transformed
  res.status(201).json(req.body);
});

app.listen(3000);

10. CircuitBreaker

import { CircuitBreaker } from '@hyperbridge/forge/server';

const breaker = new CircuitBreaker(
  (url) => fetch(url).then(r => r.json()),
  { threshold: 3, timeout: 5000, resetTimeout: 15000 }
);

breaker.on('open', () => console.warn('Circuit opened!'));

try {
  const data = await breaker.fire('https://api.example.com/data');
} catch (err) {
  // Fallback logic when circuit is open
}

11. LRU Cache

import { LRUCache } from '@hyperbridge/forge/server';

const cache = new LRUCache({ max: 500, ttl: 60000 });

cache.set('user:42', { id: 42, name: 'Alice' });
const user = cache.get('user:42'); // { id: 42, name: 'Alice' }
console.log(cache.size); // 1

12. PubSub

import { PubSub } from '@hyperbridge/forge/server';

const pubsub = new PubSub();

// Wildcard pattern
pubsub.subscribe('order.*', (data, topic) => {
  console.log(`Event ${topic}:`, data);
});

pubsub.publish('order.created', { id: 1, total: 99.99 }); // matches
pubsub.publish('order.shipped', { id: 1 });                // matches

13. HTTP Client

import { httpClient } from '@hyperbridge/forge/server';

const { data } = await httpClient.get('https://api.example.com/users', {
  headers: { Authorization: 'Bearer ...' },
  timeout: 5000,
});

await httpClient.post('https://api.example.com/users', {
  name: 'Alice', email: 'alice@example.com'
});

14. Plugin System

import { Forge } from '@hyperbridge/forge/server';

const authPlugin = {
  name: 'auth',
  async register(app, opts) {
    app.decorate('authenticate', (req) => { /* ... */ });
    app.addHook('onRequest', async (req, res) => {
      req.user = await app.authenticate(req);
    });
    app.get('/auth/me', (req, res) => res.json(req.user));
  }
};

const app = new Forge();
await app.register(authPlugin, { secret: 'my-secret' });
app.listen(3000);

15. Dependency Injection

import { createContainer, Forge } from '@hyperbridge/forge/server';

const container = createContainer();
container.register('logger', () => new Logger(), { lifetime: 'singleton' });
container.register('userService', (logger) => new UserService(logger));
container.register('requestCtx', () => new RequestContext(), { lifetime: 'scoped' });

const app = new Forge();
app.use(container.middleware());

app.get('/users', (req, res) => {
  const svc = req.container.resolve('userService');
  res.json(svc.findAll());
});

app.listen(3000);

16. OpenTelemetry Tracing

import { createTracer, Forge } from '@hyperbridge/forge/server';

const tracer = createTracer('my-service');
const app = new Forge();
app.use(tracer.middleware());

app.get('/api/data', async (req, res) => {
  const result = await tracer.trace('fetchData', async (span) => {
    span.setAttribute('db.system', 'postgres');
    const data = await db.query('SELECT * FROM items');
    span.addEvent('query-complete', { rowCount: data.length });
    return data;
  });
  res.json(result);
});

app.listen(3000);

17. Prometheus Metrics

import { createMetrics, Forge } from '@hyperbridge/forge/server';

const metrics = createMetrics({ prefix: 'myapp_' });
const app = new Forge();

app.use(metrics.middleware());
app.use(metrics.endpoint('/metrics'));

const orderCounter = metrics.counter({
  name: 'orders_total',
  help: 'Total orders placed',
});

app.post('/orders', (req, res) => {
  orderCounter.inc({ status: 'created' });
  res.status(201).json({ ok: true });
});

app.listen(3000); // Prometheus scrapes GET /metrics

18. Webhook Verification

import { Forge, verifyWebhook } from '@hyperbridge/forge/server';

const app = new Forge();

app.post('/webhooks/stripe',
  verifyWebhook({
    secret: process.env.STRIPE_SECRET,
    header: 'stripe-signature',
    tolerance: 300,
    parse: (header) => {
      const parts = {};
      header.split(',').forEach(p => {
        const [k, val] = p.split('=');
        parts[k] = val;
      });
      return { timestamp: parts.t, signature: parts.v1 };
    },
  }),
  (req, res) => {
    console.log('Verified webhook:', req.body);
    res.json({ received: true });
  }
);

app.listen(3000);

19. Enhanced Sessions

import { Forge, sessionEnhanced, createRedisSessionStore }
  from '@hyperbridge/forge/server';

const app = new Forge();

app.use(sessionEnhanced({
  secret: 'session-secret',
  maxAge: 86400,
  store: createRedisSessionStore({ host: '127.0.0.1', port: 6379 }),
  rotateInterval: 3600,
}));

app.post('/login', async (req, res) => {
  req.session.userId = user.id;
  await req.session.regenerate(); // new session ID, same data
  res.json({ ok: true });
});

app.get('/dashboard', (req, res) => {
  const error = req.flash('error');
  res.json({ userId: req.session.userId, flashError: error });
});

20. Backpressure

import { Forge, backpressure } from '@hyperbridge/forge/server';

const bp = backpressure({
  maxConcurrent: 50,
  maxQueue: 200,
  queueTimeout: 5000,
  strategy: 'priority',
  getPriority: (req) => req.headers['x-priority'] === 'high' ? 10 : 0,
});

const app = new Forge();
app.use(bp);

app.get('/stats', (req, res) => res.json(bp.stats()));
app.listen(3000);

21. Config Management

import { createConfig } from '@hyperbridge/forge/server';

const config = createConfig({
  port: { type: 'number', default: 3000, env: 'PORT' },
  db: {
    host: { type: 'string', default: 'localhost', env: 'DB_HOST' },
    port: { type: 'number', default: 5432, env: 'DB_PORT' },
    name: { type: 'string', required: true, env: 'DB_NAME' },
  },
  logLevel: { type: 'string', enum: ['debug','info','warn','error'], default: 'info' },
});

config.load({ envFile: '.env', jsonFile: 'config.json' });

console.log(config.get('db.host'));  // 'localhost' or DB_HOST value
console.log(config.isProduction);    // true if NODE_ENV=production

22. Streaming JSON

import { Forge } from '@hyperbridge/forge/server';

const app = new Forge();

// NDJSON streaming from async generator
app.get('/stream', async (req, res) => {
  async function* generate() {
    for (let i = 0; i < 100; i++) {
      yield { id: i, timestamp: Date.now() };
    }
  }
  await res.streamJSON(generate());
});

// Server-Sent Events with typed events
app.get('/events', (req, res) => {
  const sse = res.sseStream({ retry: 5000, keepAlive: 15000 });

  const interval = setInterval(() => {
    sse.event('tick', { time: new Date().toISOString() });
  }, 1000);

  req.on('close', () => {
    clearInterval(interval);
    sse.close();
  });
});

app.listen(3000);

23. Request/Response Interceptors

import { Forge } from '@hyperbridge/forge/server';

const app = new Forge();

// Log every request before parsing
app.addHook('preParsing', async (req, res) => {
  console.log(`Incoming: ${req.method} ${req.url}`);
});

// Transform all JSON responses
app.addHook('preSerialization', async (req, res, data) => {
  return { ...data, timestamp: Date.now(), requestId: req.id };
});

app.get('/api/users', (req, res) => {
  res.json({ users: [] }); // { users: [], timestamp: ..., requestId: ... }
});

app.listen(3000);

24. HTTP/2

import { Forge, createHttp2Server } from '@hyperbridge/forge/server';
import fs from 'fs';

const app = new Forge();

app.get('/', (req, res) => {
  // Push CSS and JS before the client requests them
  if (res.push) {
    res.push('/styles.css', { file: './public/styles.css', contentType: 'text/css' });
    res.push('/app.js', { file: './public/app.js', contentType: 'application/javascript' });
  }
  res.html('<html><head><link rel="stylesheet" href="/styles.css"></head>...</html>');
});

const server = createHttp2Server(app, {
  key: fs.readFileSync('key.pem'),
  cert: fs.readFileSync('cert.pem'),
});
server.listen(3000);

25. OpenAPI

import { Forge, generateOpenAPI } from '@hyperbridge/forge/server';

const app = new Forge();
app.get('/users/:id', (req, res) => { /* ... */ });
app.post('/users', (req, res) => { /* ... */ });

const spec = app.openapi({
  title: 'My API',
  version: '2.0.0',
  description: 'User management API',
});

app.get('/docs/openapi.json', (req, res) => res.json(spec));
app.listen(3000);

26. HTTPS & ACME

import { Forge, createHttpsServer } from '@hyperbridge/forge/server';

const app = new Forge();
app.get('/', (req, res) => res.json({ secure: true }));

// Auto-obtain TLS cert via Let's Encrypt
const server = await createHttpsServer(app, {
  domain: 'api.example.com',
  email: 'admin@example.com',
  certDir: './.forge-certs',
  port: 443,
});

27. Cluster

import { Forge } from '@hyperbridge/forge/server';

Forge.cluster(() => {
  const app = new Forge();

  app.get('/', (req, res) => {
    res.json({ worker: process.pid });
  });

  app.onShutdown(async () => {
    await db.close();
  });

  app.listen(3000);
}, { workers: 8 });

Response Helpers

Request Properties

Type-Safe RPC

import { Forge, createRPCRouter, procedure, mergeRouters } from '@hyperbridge/forge/server';

const userRouter = createRPCRouter({
  getUser: procedure
    .input({ id: 'string' })
    .query(async ({ input, ctx }) => {
      return ctx.db.users.findById(input.id);
    }),

  updateUser: procedure
    .input({ id: 'string', name: 'string', email: 'string?' })
    .mutation(async ({ input, ctx }) => {
      return ctx.db.users.update(input.id, input);
    })
});

const postRouter = createRPCRouter({
  list: procedure.query(async ({ ctx }) => ctx.db.posts.findAll())
});

const appRouter = mergeRouters({ user: userRouter, post: postRouter });

const app = new Forge();
app.use('/rpc', appRouter);   // POST /rpc/user.getUser, /rpc/post.list, etc.
app.listen(3000);

AI/LLM Streaming

import { Forge } from '@hyperbridge/forge/server';

const app = new Forge();

// Stream LLM tokens — OpenAI-compatible SSE
app.post('/api/chat', async (req, res) => {
  const { messages } = req.body;
  const llmStream = await callLLM({ messages, stream: true });

  res.streamTokens(async function* () {
    for await (const chunk of llmStream) {
      yield { content: chunk.text, role: 'assistant' };
    }
  });
});

// Stream arbitrary data chunks
app.get('/api/feed', (req, res) => {
  res.streamChunks(async function* () {
    yield { event: 'status', data: { connected: true } };
    for await (const update of liveUpdates()) {
      yield { event: 'update', data: update, id: update.id };
    }
  }, { retry: 3000 });
});

app.listen(3000);

Content Negotiation

import { Forge, negotiate } from '@hyperbridge/forge/server';

const app = new Forge();
app.use(negotiate());

app.get('/api/users/:id', async (req, res) => {
  const user = await db.users.findById(req.params.id);

  res.vary('Accept');
  res.format({
    'application/json': () => res.json(user),
    'text/html':        () => res.html(`<h1>${user.name}</h1>`),
    'text/csv':         () => res.text(`${user.id},${user.name},${user.email}`),
    default:            () => res.status(406).json({ error: 'Not Acceptable' })
  });
});

app.listen(3000);

Streaming Uploads

import { Forge, streamUpload } from '@hyperbridge/forge/server';
import { createWriteStream } from 'fs';

const app = new Forge();

app.post('/api/upload', streamUpload({
  maxSize: '500mb',
  allowedTypes: ['video/*', 'image/*'],
  onProgress(bytes, total) { console.log(`${Math.round(bytes/total*100)}%`); }
}), async (req, res) => {
  // req.file is a readable stream — pipe directly to storage
  const dest = createWriteStream(`./uploads/${req.file.filename}`);
  await req.file.stream.pipe(dest);

  res.status(201).json({
    filename: req.file.filename,
    size: req.file.size,
    type: req.file.mimetype
  });
});

app.listen(3000);

Test Client

import { Forge } from '@hyperbridge/forge/server';

const app = new Forge();
app.get('/api/health', (req, res) => res.json({ status: 'ok' }));
app.post('/api/users', (req, res) => {
  res.status(201).json({ id: 1, name: req.body.name });
});

// Test without starting a server
const res = await app.inject()
  .get('/api/health')
  .expect(200)
  .expect('content-type', /json/)
  .end();

console.assert(res.body.status === 'ok');

// Test POST with body
const created = await app.inject()
  .post('/api/users')
  .set('Authorization', 'Bearer test-token')
  .send({ name: 'Alice' })
  .expect(201)
  .end();

console.assert(created.body.name === 'Alice');

Dev Mode

import { Forge, devLogger } from '@hyperbridge/forge/server';

const app = new Forge();

if (process.env.NODE_ENV !== 'production') {
  app.enableDevMode({
    errorOverlay: true,          // rich HTML error pages with stack traces
    watchDirs: ['./src'],        // auto-restart on file changes
    openBrowser: true            // open browser on first listen
  });

  app.use(devLogger({
    filter: (req) => !req.path.startsWith('/health'),
    colorize: true,
    showBody: true               // log request/response bodies
  }));
}

app.get('/', (req, res) => res.json({ hello: 'world' }));
app.listen(3000);
// DevLogger output: GET / 200 1.2ms 27B

OpenAPI 3.1

import { Forge, generateOpenAPI31, swaggerUI } from '@hyperbridge/forge/server';

const app = new Forge();

app.get('/api/users', { summary: 'List users', tags: ['Users'] }, (req, res) => {
  res.json([{ id: 1, name: 'Alice' }]);
});

app.post('/api/users', {
  summary: 'Create user',
  tags: ['Users'],
  body: { name: 'string', email: 'string' },
  response: { 201: { id: 'number', name: 'string' } }
}, (req, res) => {
  res.status(201).json({ id: 2, name: req.body.name });
});

// Mount spec + UI
app.swagger({
  path: '/docs',
  info: { title: 'My API', version: '2.0.0' }
});

// Or manually:
// const spec = generateOpenAPI31(app, { info: { title: 'My API', version: '2.0.0' } });
// app.get('/openapi.json', (req, res) => res.json(spec));
// app.use('/docs', swaggerUI({ specUrl: '/openapi.json' }));

app.listen(3000);
// Swagger UI at http://localhost:3000/docs

Enhanced Errors

import { Forge, EnhancedForgeError, notFound, badRequest, unauthorized } from '@hyperbridge/forge/server';

const app = new Forge();

// Typed error handlers — catch specific error codes
app.onError('VALIDATION', (err, req, res) => {
  res.status(400).json({
    code: err.code,
    message: err.message,
    fields: err.details.fields     // per-field validation errors
  });
});

app.onError('NOT_FOUND', (err, req, res) => {
  res.status(404).json({ code: err.code, message: err.message });
});

// Throw enhanced errors from routes
app.get('/api/users/:id', async (req, res) => {
  const user = await db.users.findById(req.params.id);
  if (!user) throw notFound(`User ${req.params.id} not found`);

  res.json(user);
});

app.post('/api/users', async (req, res) => {
  if (!req.body.email) {
    throw badRequest('Validation failed', {
      fields: { email: 'Email is required' }
    });
  }

  // EnhancedForgeError with cause chain
  try {
    const user = await db.users.create(req.body);
    res.status(201).json(user);
  } catch (dbErr) {
    throw new EnhancedForgeError('DB_ERROR', 'Failed to create user', 500, { cause: dbErr });
  }
});

app.listen(3000);

forge/auth

Complete authentication system with password, JWT, OAuth2, MagicLink, TOTP, RBAC, and session management.

JWT Constructor Options

Core APIs

Example: Password Authentication

import { PasswordAuth, JWT } from '@hyperbridge/forge/auth';

const auth = new PasswordAuth({ saltRounds: 10 });

// Register
async function register(email, password) {
  const user = await auth.register(email, password);
  return { success: true, userId: user.id };
}

// Login
async function login(email, password) {
  const user = await auth.login(email, password);
  const token = JWT.sign({ userId: user.id }, 'secret-key', { expiresIn: '7d' });
  return { token, user };
}

// Verify token in middleware
app.use((req, res, next) => {
  const token = req.headers.authorization?.split(' ')[1];
  if (!token) return res.status(401).json({ error: 'Unauthorized' });

  try {
    const decoded = JWT.verify(token, 'secret-key');
    req.user = decoded;
    next();
  } catch (err) {
    res.status(401).json({ error: 'Invalid token' });
  }
});

Example: OAuth2

import { OAuth2Provider } from '@hyperbridge/forge/auth';

const google = new OAuth2Provider('google', {
  clientId: process.env.GOOGLE_CLIENT_ID,
  clientSecret: process.env.GOOGLE_CLIENT_SECRET,
  redirectUri: 'http://localhost:3000/auth/google/callback',
});

// Get auth URL for login button
router.get('/auth/google', (req, res) => {
  const authUrl = google.getAuthUrl();
  res.redirect(authUrl);
});

// Handle callback
router.get('/auth/google/callback', async (req, res) => {
  const { code } = req.query;
  const token = await google.handleCallback(code);
  const user = await google.getUserInfo(token);

  // Create or update user in database
  const dbUser = await createOrUpdateUser(user);
  const jwtToken = JWT.sign({ userId: dbUser.id }, 'secret-key');

  res.redirect(`/dashboard?token=${jwtToken}`);
});

Example: RBAC (Role-Based Access Control)

import { RBAC } from '@hyperbridge/forge/auth';

const rbac = new RBAC();

// Define roles and permissions
rbac.defineRole('admin', ['users:read', 'users:write', 'users:delete']);
rbac.defineRole('editor', ['posts:read', 'posts:write']);
rbac.defineRole('viewer', ['posts:read']);

// Grant role to user
rbac.grantRole('user-123', 'admin');

// Check permission in middleware
function requirePermission(permission) {
  return (req, res, next) => {
    if (rbac.hasPermission(req.user.id, permission)) {
      next();
    } else {
      res.status(403).json({ error: 'Forbidden' });
    }
  };
}

// Protect route
router.delete('/api/users/:id', requirePermission('users:delete'), (req, res) => {
  // Delete user
});

forge/data

PostgreSQL ORM with connection pooling, query builder, migrations, transactions, and relationships.

Core APIs

Example: Connection & Basic Queries

import { PgConnection } from '@hyperbridge/forge/data';

const db = new PgConnection({
  host: 'localhost',
  port: 5432,
  user: 'postgres',
  password: 'secret',
  database: 'myapp',
});

// Raw query
const users = await db.query('SELECT * FROM users WHERE age > $1', [18]);

// Insert
const user = await db.insert('users', {
  email: 'john@example.com',
  name: 'John Doe',
  age: 30,
});

// Update
await db.update('users', { age: 31 }, { where: { id: 1 } });

// Delete
await db.delete('users', { where: { id: 1 } });

// Count
const count = await db.count('users', { where: { age: { '>': 18 } } });

Example: Models

import { Model } from '@hyperbridge/forge/data';

class User extends Model {
  static table = 'users';
  static schema = {
    id: 'serial primary key',
    email: 'varchar(255) unique',
    name: 'varchar(255)',
    age: 'integer',
  };
}

// Create
const user = await User.create({
  email: 'jane@example.com',
  name: 'Jane Doe',
  age: 28,
});

// Read
const user = await User.findById(1);
const allUsers = await User.findMany();
const adults = await User.where({ age: { '>=': 18 } }).get();

// Update
user.name = 'Jane Smith';
await user.save();

// Delete
await user.delete();

Example: Query Builder

import { QueryBuilder } from '@hyperbridge/forge/data';

const query = new QueryBuilder('users')
  .select('id', 'name', 'email')
  .where('age', '>', 18)
  .andWhere('status', '=', 'active')
  .orderBy('name', 'asc')
  .limit(10);

const users = await query.get();
const count = await query.count();
const sql = query.toSQL(); // Get generated SQL

Example: Migrations

import { Migrator } from '@hyperbridge/forge/data';

const migrator = new Migrator(db, './migrations');

// Create migration
await migrator.create('create_users_table', async (m) => {
  m.createTable('users', (table) => {
    table.increments('id');
    table.string('email').unique();
    table.string('name');
    table.integer('age');
    table.timestamps(); // created_at, updated_at
  });
});

// Run migrations
await migrator.latest();

// Rollback
await migrator.rollback();

// Check status
const status = await migrator.status();

Example: Transactions

import { PgConnection } from '@hyperbridge/forge/data';

const db = new PgConnection({ /* ... */ });

await db.transaction(async (trx) => {
  // Create user
  const user = await trx.insert('users', { email: 'john@example.com' });

  // Create related record
  await trx.insert('profiles', { userId: user.id, bio: 'Hello' });

  // Both succeed together, or both rollback
});

// If error in transaction, everything rolls back automatically

forge/form

Form management with validation, field arrays, async validation, and schema binding.

Core APIs

Example: Basic Form

import { h, useState } from '@hyperbridge/forge/client';
import { Form } from '@hyperbridge/forge/form';

export function LoginForm() {
  const form = new Form({
    initialValues: { email: '', password: '' },
    validate: (values) => {
      const errors = {};
      if (!values.email) errors.email = 'Email required';
      if (!values.password) errors.password = 'Password required';
      return errors;
    },
  });

  async function handleSubmit(values) {
    const response = await fetch('/api/login', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(values),
    });
    const data = await response.json();
    localStorage.setItem('token', data.token);
  }

  return h('form', { onSubmit: (e) => {
    e.preventDefault();
    form.submit(handleSubmit);
  }},
    h('input', {
      name: 'email',
      type: 'email',
      value: form.values.email,
      onChange: (e) => form.setField('email', e.target.value),
    }),
    form.errors.email && h('p', { style: { color: 'red' } }, form.errors.email),

    h('input', {
      name: 'password',
      type: 'password',
      value: form.values.password,
      onChange: (e) => form.setField('password', e.target.value),
    }),
    form.errors.password && h('p', { style: { color: 'red' } }, form.errors.password),

    h('button', { type: 'submit', disabled: form.isSubmitting }, 'Login')
  );
}

Example: Form with Schema

import { Form, fromSchema } from '@hyperbridge/forge/form';
import { Schema } from '@hyperbridge/forge/schema';

const schema = Schema.object({
  email: Schema.string().email('Invalid email').min(1, 'Required'),
  password: Schema.string().min(8, 'Min 8 characters'),
  confirmPassword: Schema.string(),
}).refine(
  (data) => data.password === data.confirmPassword,
  { message: 'Passwords do not match', path: ['confirmPassword'] }
);

const form = fromSchema(schema);

form.values = {
  email: '',
  password: '',
  confirmPassword: '',
};

async function handleSubmit() {
  const result = await form.validate();
  if (result.valid) {
    // Submit form
    console.log('Validated:', result.data);
  }
}

Example: Field Arrays (Dynamic Fields)

import { Form } from '@hyperbridge/forge/form';

const form = new Form({
  initialValues: {
    contacts: [
      { name: '', email: '' },
    ],
  },
});

function ContactsForm() {
  return h('div', null,
    form.values.contacts.map((contact, index) =>
      h('div', { key: index },
        h('input', {
          value: contact.name,
          onChange: (e) => form.setField(`contacts.${index}.name`, e.target.value),
          placeholder: 'Name',
        }),
        h('input', {
          value: contact.email,
          onChange: (e) => form.setField(`contacts.${index}.email`, e.target.value),
          placeholder: 'Email',
        }),
        h('button', {
          onClick: () => form.removeField(`contacts.${index}`),
        }, 'Remove'),
      )
    ),
    h('button', {
      onClick: () => form.addField('contacts', { name: '', email: '' }),
    }, 'Add Contact'),
  );
}

forge/animate

Zero-dependency animation engine with spring physics, tweens, gestures, scroll-linked timelines, FLIP layout animations, SVG morphing, text effects, motion paths, and 50+ transition presets. 80+ APIs. ~3,500 lines.

Tween & Core Animation

import { Tween, animate } from '@hyperbridge/forge/animate';

// Full Tween API
const tween = new Tween({
  duration: 800,
  easing: 'easeOutCubic',
  values: { opacity: [0, 1], x: [100, 0], y: [-50, 0] },
  onUpdate: (v) => {
    el.style.opacity = v.opacity;
    el.style.transform = `translate(${v.x}px, ${v.y}px)`;
  },
});
tween.play();
tween.pause();
tween.reverse();
tween.seek(0.5); // jump to 50%

// Shorthand
animate('.box', { opacity: 1, transform: 'translateY(0)' }, { duration: 600 });

Spring Physics

import { Spring, springPresets, springChain } from '@hyperbridge/forge/animate';

const spring = new Spring({
  ...springPresets.wobbly,
  values: { scale: [0.8, 1], opacity: [0, 1] },
  onUpdate: (v) => {
    el.style.transform = `scale(${v.scale})`;
    el.style.opacity = v.opacity;
  },
});
spring.play();

// Chain springs: fade in, then scale up, then slide right
springChain([
  { values: { opacity: [0, 1] }, ...springPresets.gentle },
  { values: { scale: [0.9, 1] }, ...springPresets.stiff },
  { values: { x: [0, 100] }, ...springPresets.wobbly },
], (v) => { /* onUpdate for each step */ });

Spring Configuration

Easing Functions

Timeline & Sequencing

import { Timeline, Tween, sequence } from '@hyperbridge/forge/animate';

const tl = new Timeline();
tl.add(new Tween({ duration: 300, values: { opacity: [0, 1] }, onUpdate: ... }));
tl.add(new Tween({ duration: 500, values: { x: [0, 200] }, onUpdate: ... }), 200); // overlap by 100ms
tl.play();

// Or use sequence for strict ordering
sequence([
  animate('.title', { opacity: 1 }, { duration: 400 }),
  animate('.subtitle', { opacity: 1 }, { duration: 300 }),
  animate('.cta', { opacity: 1, transform: 'scale(1)' }, { duration: 500 }),
]);

Stagger Animations

import { stagger, staggerGrid } from '@hyperbridge/forge/animate';

// Simple stagger
stagger(document.querySelectorAll('.card'), {
  duration: 500,
  delay: 80,
  easing: 'easeOutQuad',
  values: { opacity: [0, 1], y: [30, 0] },
});

// Grid stagger — animate from center outward
staggerGrid(document.querySelectorAll('.grid-item'), {
  columns: 4,
  from: 'center',
  duration: 400,
  delay: 60,
  values: { scale: [0, 1], opacity: [0, 1] },
});

Scroll Animations

import { scrollTimeline, parallax, inView } from '@hyperbridge/forge/animate';

// Scroll-linked animation (GSAP ScrollTrigger-style)
scrollTimeline('.progress-bar', {
  trigger: '.section',
  start: 'top center',
  end: 'bottom center',
  animation: { scaleX: [0, 1] },
});

// Parallax layers
parallax('.bg-layer', { speed: 0.3 });
parallax('.fg-layer', { speed: 0.8 });

scrollTimeline Options

Viewport & Reveal

Gesture System

import { gesture, draggable, inertia } from '@hyperbridge/forge/animate';

// Full gesture handling
gesture(card, {
  onDrag: ({ x, y, velocity }) => {
    card.style.transform = `translate(${x}px, ${y}px)`;
  },
  onDragEnd: ({ velocity }) => {
    inertia(card, { velocity, friction: 0.95 });
  },
});

// Simple draggable
draggable('.handle', { axis: 'x', bounds: '.container' });

Layout Animations (FLIP)

import { flip, layoutTransition } from '@hyperbridge/forge/animate';

// Manual FLIP for a layout change
flip(listContainer, () => {
  // DOM mutation happens here
  listContainer.prepend(listContainer.lastChild);
}, { duration: 400, easing: 'easeOutCubic' });

// Auto FLIP — watches for any DOM changes
const cleanup = layoutTransition('.grid', {
  duration: 350,
  easing: 'easeInOutQuad',
});

SVG & Path Animations

Text Animations

import { splitText, typewriter, scrambleText, stagger } from '@hyperbridge/forge/animate';

// Split and stagger characters
const { chars } = splitText('.heading');
stagger(chars, {
  duration: 400, delay: 30,
  values: { opacity: [0, 1], y: [20, 0] },
});

// Typewriter effect
typewriter('.terminal-text', { speed: 50, cursor: true });

// Scramble reveal
scrambleText('.secret-code', { duration: 1500, chars: '!@#$%^&*' });

Presence & Transitions

Motion Values & Reactivity

Performance Utilities

Reduced Motion & Accessibility

import { animate, respectMotionPreference, prefersReducedMotion } from '@hyperbridge/forge/animate';

// Automatically respects user preferences
const safeAnimate = respectMotionPreference(animate);
safeAnimate('.hero', { opacity: 1, y: 0 }, { duration: 600 });
// If reduced motion: instant jump, no animation

// Manual check
if (!prefersReducedMotion()) {
  animate('.fancy-element', { rotate: 360 }, { duration: 2000 });
}

forge/chart

SVG chart library with line, bar, pie, scatter, radar, heatmap, treemap, gauge, and funnel charts.

Quick Start

Every chart follows the same pattern: pick a type, point to a container, pass data, and call render(). The data shape is consistent across all chart types — labels for categories, series for datasets.

Chart Constructor Parameters

Instance Methods

Supported Charts

Example: Line Chart

import { Chart } from '@hyperbridge/forge/chart';

const chart = new Chart({
  type: 'line',
  container: document.getElementById('chart'),
  data: {
    labels: ['Jan', 'Feb', 'Mar', 'Apr', 'May'],
    series: [
      { name: 'Sales', data: [120, 150, 200, 180, 220] },
      { name: 'Profit', data: [30, 45, 60, 50, 80] },
    ],
  },
  options: {
    title: 'Monthly Performance',
    responsive: true,
    animation: true,
  },
});

chart.render();

Example: Pie Chart

import { Chart } from '@hyperbridge/forge/chart';

const chart = new Chart({
  type: 'pie',
  container: document.getElementById('chart'),
  data: {
    labels: ['Desktop', 'Mobile', 'Tablet'],
    series: [
      { name: 'Traffic', data: [45, 35, 20] },
    ],
  },
  options: {
    title: 'Traffic by Device',
    colors: ['#6366f1', '#22d3ee', '#f97316'],
  },
});

chart.render();

Example: Real-Time Dashboard

import { Chart } from '@hyperbridge/forge/chart';

// Live-updating gauge
const gauge = new Chart({
  type: 'gauge',
  container: document.getElementById('cpu-gauge'),
  data: { value: 0, min: 0, max: 100, label: 'CPU %' },
  options: {
    colors: ['#22c55e', '#eab308', '#ef4444'], // green → yellow → red
    thresholds: [60, 85],
    animation: { duration: 300 },
  },
});
gauge.render();

// Update every second from WebSocket
ws.on('metrics', (data) => {
  gauge.update({ value: data.cpuPercent });
});

Example: Export Chart

// Export as SVG string
const svgString = chart.toSVG();
document.getElementById('preview').innerHTML = svgString;

// Export as PNG blob for download
const blob = await chart.toImage('png');
const url = URL.createObjectURL(blob);
const a = document.createElement('a');
a.href = url;
a.download = 'chart.png';
a.click();

forge/schema

Zod-compatible schema validation with TypeScript inference and composable validators.

Core Types

Example: Basic Schema

import { Schema } from '@hyperbridge/forge/schema';

const userSchema = Schema.object({
  id: Schema.number().positive(),
  email: Schema.string().email(),
  age: Schema.number().min(0).max(120),
  isActive: Schema.boolean().default(true),
  role: Schema.enum(['admin', 'user', 'guest']),
  tags: Schema.array(Schema.string()),
  metadata: Schema.object({
    created: Schema.date(),
    updated: Schema.date(),
  }),
});

// Parse data
const data = {
  id: 1,
  email: 'john@example.com',
  age: 30,
  role: 'user',
  tags: ['premium', 'verified'],
  metadata: { created: new Date(), updated: new Date() },
};

const result = userSchema.safeParse(data);
if (result.success) {
  console.log('Valid:', result.data);
} else {
  console.log('Errors:', result.errors);
}

Example: Async Validation

import { Schema } from '@hyperbridge/forge/schema';

const userSchema = Schema.object({
  email: Schema.string()
    .email()
    .async()
    .refine(
      async (email) => {
        const exists = await checkEmailExists(email);
        return !exists;
      },
      { message: 'Email already registered' }
    ),
  username: Schema.string()
    .min(3)
    .async()
    .refine(
      async (username) => {
        const available = await checkUsernameAvailable(username);
        return available;
      },
      { message: 'Username taken' }
    ),
});

const result = await userSchema.parseAsync({
  email: 'new@example.com',
  username: 'johndoe',
});

Example: Transform & Refine

import { Schema } from '@hyperbridge/forge/schema';

const passwordSchema = Schema.object({
  password: Schema.string().min(8),
  confirmPassword: Schema.string(),
})
  .transform((data) => ({
    ...data,
    password: hashPassword(data.password),
  }))
  .refine(
    (data) => data.password === data.confirmPassword,
    {
      message: 'Passwords do not match',
      path: ['confirmPassword'],
    }
  );

const result = passwordSchema.parse({
  password: 'MyPassword123',
  confirmPassword: 'MyPassword123',
});

forge/test

Testing framework with expect matchers, mocking, DOM testing, and code coverage.

Test Runner Configuration

Expect Matchers

Core APIs

Example: Unit Test

import { describe, it, expect } from '@hyperbridge/forge/test';

describe('Math utilities', () => {
  it('should add numbers', () => {
    expect(2 + 2).toBe(4);
  });

  it('should handle floats', () => {
    expect(0.1 + 0.2).toBeCloseTo(0.3);
  });

  it('should throw on invalid input', () => {
    expect(() => divide(10, 0)).toThrow('Division by zero');
  });
});

Example: Mocking

import { describe, it, expect, fn, spyOn } from '@hyperbridge/forge/test';

describe('API calls', () => {
  it('should call fetch with correct URL', async () => {
    const mockFetch = fn();
    global.fetch = mockFetch;

    mockFetch.mockResolvedValueOnce({
      json: () => Promise.resolve({ id: 1, name: 'John' }),
    });

    const data = await fetchUser(1);

    expect(mockFetch).toHaveBeenCalledWith('/api/users/1');
    expect(data.name).toBe('John');
  });

  it('should retry on failure', async () => {
    const api = { call: fn() };
    api.call.mockRejectedValueOnce(new Error('Network error'));
    api.call.mockResolvedValueOnce({ success: true });

    const result = await retryCall(() => api.call());

    expect(api.call).toHaveBeenCalledTimes(2);
    expect(result.success).toBe(true);
  });
});

Example: DOM Testing

import { describe, it, expect, render, screen, fireEvent } from '@hyperbridge/forge/test';
import { Counter } from './Counter';

describe('Counter Component', () => {
  it('should render count', () => {
    render(Counter);
    expect(screen.getByText('Count: 0')).toBeDefined();
  });

  it('should increment on button click', () => {
    render(Counter);
    const button = screen.getByRole('button', { name: 'Increment' });

    fireEvent.click(button);
    expect(screen.getByText('Count: 1')).toBeDefined();
  });

  it('should update after async operation', async () => {
    render(DataComponent);

    expect(screen.getByText('Loading...')).toBeDefined();

    await waitFor(() => {
      expect(screen.getByText('Data loaded')).toBeDefined();
    });
  });
});

forge/mail

Email sending with SMTP, email templates, Resend API integration, and queue support.

SMTPClient Configuration

sendMail Parameters

Core APIs

Example: SMTP Email

import { SMTPClient } from '@hyperbridge/forge/mail';

const smtp = new SMTPClient({
  host: 'smtp.gmail.com',
  port: 587,
  secure: false,
  auth: {
    user: 'your-email@gmail.com',
    pass: 'your-app-password',
  },
});

await smtp.sendMail({
  from: 'noreply@example.com',
  to: 'user@example.com',
  subject: 'Welcome!',
  html: '
Welcome to our app
Thanks for signing up!
',
});

Example: Resend API

import { ResendTransport } from '@hyperbridge/forge/mail';

const resend = new ResendTransport({
  apiKey: process.env.RESEND_API_KEY,
});

// Send email
const result = await resend.sendMail({
  from: 'onboarding@resend.dev',
  to: 'user@example.com',
  subject: 'Welcome!',
  html: '
Welcome
',
});

// Send batch
await resend.sendBatch([
  { to: 'user1@example.com', subject: 'Hello User 1', html: '...' },
  { to: 'user2@example.com', subject: 'Hello User 2', html: '...' },
]);

// Create audience
const audience = await resend.createAudience({ name: 'My List' });

// Add contacts
await resend.addContact(audience.id, 'user@example.com');

// Send broadcast
await resend.createBroadcast({
  audienceId: audience.id,
  subject: 'Monthly Newsletter',
  html: '...',
});

Example: Email Templates

import { EmailTemplate } from '@hyperbridge/forge/mail';

const welcomeTemplate = new EmailTemplate({
  name: 'welcome',
  html: `
    
Welcome, {{name}}!
    
Your account {{email}} has been created.
    
Verify Email
  `,
});

const html = welcomeTemplate.render({
  name: 'John',
  email: 'john@example.com',
  verifyLink: 'https://example.com/verify?token=...',
});

await smtp.sendMail({
  from: 'noreply@example.com',
  to: 'john@example.com',
  subject: 'Welcome to Our App',
  html,
});

forge/pdf

PDF generation with text, tables, images, fonts, watermarks, and signatures.

PDFForge Constructor

Drawing Methods

Core APIs

• PDFForge.create() - Create document
• text(content, x, y, options) - Add text
• heading(text, x, y, size) - Add heading
• table(data, options) - Add table
• image(src, x, y, width, height) - Add image
• rect(x, y, width, height, options) - Draw rectangle
• line(x1, y1, x2, y2, options) - Draw line
• page() - Add new page
• footer(text) / header(text) - Add page header/footer
• watermark(text) - Add watermark
• signature(imageData, x, y) - Add signature
• export(format) - Export to PDF/Buffer/Stream

Example: Basic Invoice

import { PDFForge } from '@hyperbridge/forge/pdf';

const pdf = new PDFForge();

// Title
pdf.heading('Invoice', 50, 50, 24);

// Company info
pdf.text('Acme Corp', 50, 90);
pdf.text('123 Business St, City', 50, 110);

// Invoice items
pdf.table([
  ['Item', 'Qty', 'Price', 'Total'],
  ['Widget A', '5', '$10', '$50'],
  ['Widget B', '3', '$20', '$60'],
  ['', '', 'Total:', '$110'],
], {
  x: 50,
  y: 150,
  width: 500,
});

// Footer
pdf.footer('Thank you for your business!');

// Export
const buffer = pdf.export('buffer');
await fs.promises.writeFile('invoice.pdf', buffer);

Example: Report with Images

import { PDFForge } from '@hyperbridge/forge/pdf';

const pdf = new PDFForge();

// Title
pdf.heading('Monthly Report', 50, 50);

// Text
pdf.text('Performance Summary:', 50, 100);
pdf.text('Sales increased by 25% this month.', 50, 120);

// Add chart image
pdf.image('./chart.png', 50, 150, 500, 300);

// New page
pdf.page();
pdf.heading('Detailed Analytics', 50, 50);

// More content...

const buffer = pdf.export('buffer');

forge/search

Full-text search engine with BM25 ranking, facets, aggregations, and persistence.

SearchForge Constructor

Search Options

Core APIs

• SearchForge.create(options) - Create index
• add(id, doc) - Index document
• search(query, options) - Search indexed docs
• suggest(prefix) - Auto-complete suggestions
• remove(id) - Remove document from index
• export() / import() - Persistence
• BM25 ranking - Relevance scoring
• Phrase matching - Exact phrase search
• Boolean operators - AND, OR, NOT
• Field weighting - Boost important fields
• Facets - Filter by category
• Aggregations - Group and count results

Example: Basic Search Index

import { SearchForge } from '@hyperbridge/forge/search';

const search = new SearchForge({
  fields: ['title', 'body', 'tags'],
  fieldWeights: { title: 2, body: 1, tags: 1.5 },
});

// Index documents
search.add('doc-1', {
  title: 'Getting Started with HBForge',
  body: 'HBForge is a complete JavaScript framework...',
  tags: ['tutorial', 'beginner'],
});

search.add('doc-2', {
  title: 'Advanced Features',
  body: 'Learn about animations and forms...',
  tags: ['advanced', 'guide'],
});

// Search
const results = search.search('HBForge framework', {
  limit: 10,
  offset: 0,
});

console.log(results);
// [
//   { id: 'doc-1', score: 2.5, doc: {...} },
//   { id: 'doc-2', score: 0.8, doc: {...} }
// ]

Example: Advanced Queries

import { SearchForge } from '@hyperbridge/forge/search';

const search = new SearchForge({ fields: ['title', 'body', 'category'] });

// Load documents...

// Phrase search
const phrases = search.search('"HBForge framework"');

// Boolean operators
const complex = search.search('(HBForge OR framework) AND -deprecated');

// Field-specific search
const titleSearch = search.search('title:animations');

// Faceted search
const results = search.search('animation', {
  facets: ['tags', 'category'],
});

// Auto-complete
const suggestions = search.suggest('HB');
// ['HBForge', 'HTTP', 'HTML']

forge/notify

Notification system with toast, alert, modal, WebSocket delivery, email, and SMS channels.

Notify Constructor

Notification Object

Core APIs

• NotificationManager - Main manager
• create(options) - Create notification
• send(notification) - Send notification
• dismiss(id) - Dismiss notification
• Toast, Alert, Modal - Channel types
• Email, SMS - Delivery channels
• WebSocket - Real-time delivery
• Priority levels - Urgent, High, Normal, Low
• Read receipts - Track if read
• Scheduling - Send at specific time

Example: Toast Notifications

import { Notify } from '@hyperbridge/forge/notify';

const notify = new Notify();

// Success toast
notify.toast({
  message: 'Account created successfully!',
  type: 'success',
  duration: 3000,
});

// Error toast
notify.toast({
  message: 'Something went wrong. Please try again.',
  type: 'error',
  duration: 5000,
});

// Info with action
notify.toast({
  message: 'Update available',
  type: 'info',
  action: {
    label: 'Refresh',
    onClick: () => window.location.reload(),
  },
});

Example: Channel Selection

import { Notify } from '@hyperbridge/forge/notify';

const notify = new Notify({
  channels: ['toast', 'email', 'websocket'],
});

// Send via all channels
await notify.send({
  title: 'Important Update',
  message: 'New features are available',
  channels: ['toast', 'email', 'websocket'],
  priority: 'high',
  user: {
    id: 'user-123',
    email: 'user@example.com',
  },
});

// Toast only
await notify.toast({ message: 'Quick notification' });

// Email only
await notify.email({
  to: 'user@example.com',
  subject: 'Weekly Report',
  html: '
Your Report
...',
});

forge/cli

CLI framework with commands, options, prompts, colors, spinners, and config management.

CLI Constructor

Command Definition

Interactive Prompts

Core APIs

• CLI - Main CLI class
• command(name, fn) - Define command
• option(name, config) - Add option/flag
• argument(name, config) - Add argument
• Prompt - Interactive prompts
• Spinner - Loading spinner
• ProgressBar - Progress visualization
• colors - Terminal colors
• table - Format data tables
• log - Logging utilities

Example: CLI Application

import { CLI, Prompt, Spinner, colors } from '@hyperbridge/forge/cli';

const cli = new CLI({
  name: 'myapp',
  version: '1.0.0',
  description: 'My awesome CLI tool',
});

// Define command
cli.command('create', async (args, options) => {
  const name = await Prompt.input('Project name:');

  const spinner = new Spinner(`Creating ${name}...`);
  spinner.start();

  // Do work...
  await new Promise(r => setTimeout(r, 2000));

  spinner.succeed(`Project created: ${colors.green(name)}`);
});

// Define another command
cli.command('build', async (args, options) => {
  const watch = options.watch || false;
  console.log(`Building${watch ? ' (watch)' : ''}...`);
  // Build logic...
});

cli.command('serve', async (args, options) => {
  const port = options.port || 3000;
  console.log(`Server running on ${colors.cyan(`http://localhost:${port}`)}`);
});

// Parse and execute
cli.parse(process.argv);

Example: Interactive Prompts

import { Prompt, colors } from '@hyperbridge/forge/cli';

// Text input
const name = await Prompt.input('Your name:');

// Confirmation
const proceed = await Prompt.confirm('Continue?');

// Select from options
const choice = await Prompt.select('Choose one:', [
  { label: 'Option A', value: 'a' },
  { label: 'Option B', value: 'b' },
  { label: 'Option C', value: 'c' },
]);

// Multi-select
const tags = await Prompt.multiSelect('Select tags:', [
  'important',
  'urgent',
  'feature',
  'bugfix',
]);

// Display results
console.log(`${colors.green('✓')} Name: ${name}`);
console.log(`${colors.blue('ℹ')} Choice: ${choice}`);
console.log(`${colors.yellow('⚠')} Tags: ${tags.join(', ')}`);

forge/i18n

Internationalization with translations, formatting, and locale management.

I18n Constructor

Translation API

Formatting API

Core APIs

• I18n - Main i18n class
• t(key, context) - Translate key
• setLocale(locale) - Set current locale
• getLocale() - Get current locale
• formatDate(date, locale) - Format date
• formatTime(date, locale) - Format time
• formatNumber(num, locale) - Format number
• formatCurrency(amount, currency) - Format currency
• formatList(items) - Format list
• formatRelative(date) - Relative time (e.g., "2 hours ago")
• pluralize(count, keys) - Plural handling
• isRTL(locale) - Check RTL language

Example: Setup & Usage

import { I18n } from '@hyperbridge/forge/i18n';

const i18n = new I18n({
  defaultLocale: 'en',
  fallbackLocale: 'en',
});

// Register translations
i18n.addMessages('en', {
  'greeting': 'Hello, {name}!',
  'items.one': 'You have 1 item',
  'items.other': 'You have {count} items',
  'welcome': 'Welcome to {app}',
});

i18n.addMessages('es', {
  'greeting': '¡Hola, {name}!',
  'items.one': 'Tienes 1 artículo',
  'items.other': 'Tienes {count} artículos',
  'welcome': 'Bienvenido a {app}',
});

// Translate
console.log(i18n.t('greeting', { name: 'John' }));
// en: "Hello, John!"
// es: "¡Hola, John!"

// Pluralize
console.log(i18n.t('items', { count: 1 }));
// "You have 1 item" (en) / "Tienes 1 artículo" (es)

console.log(i18n.t('items', { count: 5 }));
// "You have 5 items" (en) / "Tienes 5 artículos" (es)

Example: Formatting

import { I18n } from '@hyperbridge/forge/i18n';

const i18n = new I18n({ defaultLocale: 'en-US' });

// Date formatting
const date = new Date('2026-03-15');
console.log(i18n.formatDate(date)); // "3/15/2026"
console.log(i18n.formatDate(date, 'es-ES')); // "15/3/2026"

// Number formatting
console.log(i18n.formatNumber(1234.56)); // "1,234.56" (en-US)
console.log(i18n.formatNumber(1234.56, 'de-DE')); // "1.234,56"

// Currency formatting
console.log(i18n.formatCurrency(99.99, 'USD')); // "$99.99"
console.log(i18n.formatCurrency(99.99, 'EUR', 'de-DE')); // "99,99 €"

// Relative time
console.log(i18n.formatRelative(new Date() - 3600000)); // "1 hour ago"
console.log(i18n.formatRelative(new Date() + 86400000)); // "in 1 day"

// List formatting
const items = ['Apple', 'Banana', 'Orange'];
console.log(i18n.formatList(items)); // "Apple, Banana, and Orange"
console.log(i18n.formatList(items, 'es-ES')); // "Apple, Banana y Orange"