Veda Client Framework

A lightweight reactive framework for building semantic web applications with fine-grained reactivity and RDF/linked data support.

Features

• 🎯 Fine-grained reactivity - Vue 3-inspired reactive system with automatic dependency tracking
• 🧩 Web Components - Built on native Custom Elements API
• 🔗 Semantic data - First-class RDF/linked data model support
• 📝 Declarative templates - JSX-like syntax with reactive expressions
• 🔄 Built-in components - Loop, If, Property, Relation components
• ♻️ Circular references - Automatic handling for RDF graph structures
• 📦 Minimal footprint - ~50 KB browser bundle, ~85 KB with Node.js (includes ws)
• 🎨 TypeScript - Full type definitions included

Quick Start

Installation

Using npm:

npm install github:semantic-machines/veda-client

Using pnpm:

pnpm add github:semantic-machines/veda-client

For development:

# Clone repository
git clone https://github.com/semantic-machines/veda-client.git
cd veda-client

# Install dependencies
pnpm install

# Build
pnpm build

# Run tests
pnpm test

Your First Component

import Component, { html } from 'veda-client';

class Counter extends Component(HTMLElement) {
  static tag = 'app-counter';

  constructor() {
    super();
    this.state.count = 0;
  }

  increment = () => this.state.count++;

  render() {
    return html`
      <div>
        <p>Count: {this.state.count}</p>
        <button onclick="{increment}">+</button>
      </div>
    `;
  }
}

customElements.define(Counter.tag, Counter);

Reactive List with Loop

import Component, { html, Loop } from 'veda-client';

class TodoList extends Component(HTMLElement) {
  constructor() {
    super();
    this.state.todos = [
      { id: 1, text: 'Learn Veda', done: false },
      { id: 2, text: 'Build app', done: false }
    ];
  }

  render() {
    return html`
      <ul>
        <${Loop} items="{this.state.todos}" key="id" as="todo">
          <li>{todo.text}</li>
        </${Loop}>
      </ul>
    `;
  }
}

Documentation

• API Reference - Complete API documentation
• Architecture Guide - Framework internals and design decisions
• Reactivity Guide - Comprehensive reactivity tutorial
• FAQ - Frequently asked questions and solutions
• Performance Benchmarks - Measured performance metrics
• Style Guide - Best practices and coding patterns
• Changelog - Version history and breaking changes
• Troubleshooting - Common issues and solutions
• Security - Security best practices
• Limitations - Known limitations and workarounds
• Roadmap - Future plans

Examples

• TodoMVC - Full-featured todo app (app-todo/)
  • Imperative version - Manual control with Loop
  • Declarative version - Property bindings
• Simple examples - See examples/ directory

Core Concepts

Exported API

The framework exports the following modules from ./src/index.js:

Module	Export	Description	Source
Core	Component	Base class for creating reactive web components	Component.js
	html	Template tag for safe HTML rendering	Component.js
	safe	Function to escape HTML and remove expressions	Component.js
	raw	Template tag for raw HTML (use with caution)	Component.js
	reactive	Create reactive objects for state management	Component.js
	effect	Create auto-tracking effect	Component.js
	computed	Create computed value	Reactive.js
Components	Loop	List rendering with reconciliation	LoopComponent.js
	If	Conditional rendering	IfComponent.js
Data	Model	RDF/semantic data model	Model.js
	Backend	Backend API communication	Backend.js
	Subscription	WebSocket subscriptions	Subscription.js
Reactivity	flushEffects	Manually flush effect queue	Effect.js
	trigger	Manually trigger effects	Effect.js
	untrack	Disable tracking in callback	Effect.js
	pauseTracking	Pause dependency tracking	Effect.js
	resumeTracking	Resume dependency tracking	Effect.js
Utilities	Router	Hash-based router	Router.js
	Emitter	Event emitter mixin	Emitter.js
	BackendError	Backend error class	BackendError.js
	genUri, guid, timeout, diff, eq, dashToCamel, decorator	Utility functions	Util.js
Types	Reactive<T>	TypeScript type for reactive objects	Reactive.d.ts
	ReactiveOptions	Options for reactive() function	Reactive.d.ts
	ComponentInstance	Component instance type	Component.d.ts
	ModelValue	RDF value type	Model.d.ts

Not exported (declarative syntax only):

• PropertyComponent - Use <span property="v-s:title"></span>
• RelationComponent - Use <ul rel="v-s:hasTodo"></ul>
• ValueComponent - Internal base class

Not exported (internal APIs):

• Value - RDF value serialization (import directly: import Value from 'veda-client/src/Value.js')
• WeakCache - Weak reference cache (import directly: import WeakCache from 'veda-client/src/WeakCache.js')

See API.md for complete API documentation.

Reactivity

import { reactive, effect, computed } from 'veda-client';

const state = reactive({ count: 0 });

effect(() => {
  console.log('Count:', state.count);
});

state.count++; // Logs: "Count: 1"

Semantic Data Models

import { Model } from 'veda-client';

const person = new Model('d:Person1');
await person.load();
console.log(person['v-s:name']); // ['John Doe']

person['v-s:age'] = [30];
await person.save();

Built-in Components

import { Loop, If } from 'veda-client';

// Conditional rendering
<${If} condition="{this.isVisible}">
  <div>Content</div>
</${If}>

// List rendering with reconciliation
<${Loop} items="{this.items}" key="id" as="item">
  <item-card></item-card>
</${Loop}>

Browser Support

• Chrome/Edge 88+
• Firefox 85+
• Safari 14+

Requires:

• Custom Elements v1
• ES Modules
• Proxy
• WeakMap

Bundle Size

• Browser: ~50 KB (minified, without ws)
• Node.js: ~85 KB (minified, includes ws for WebSocket support)
• Both versions are bundled and tree-shakeable

Testing

# All tests
pnpm test

# Unit tests only (fast)
pnpm test:unit

# Integration tests (requires server)
pnpm test:integration

Test coverage:

• 99.4% with integration tests (requires backend: pnpm c8)
• 91.08% unit tests only (pnpm c8:unit)

See test/README.md for detailed testing guide

TypeScript

Full TypeScript definitions included:

import Component, { html } from 'veda-client';
import type { Reactive } from 'veda-client';

interface AppState {
  count: number;
}

class App extends Component(HTMLElement) {
  state: Reactive<AppState>;

  constructor() {
    super();
    // State is automatically reactive
    this.state.count = 0;
  }
}

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new features
4. Ensure all tests pass (pnpm test)
5. Submit a pull request

Testing guidelines: See test/README.md for test structure, best practices, and writing tests.

License

MIT License - see LICENSE for details

Credits

Inspired by:

• Vue 3 reactivity system
• Lit HTML templates
• Semantic web standards (RDF, RDFS, OWL)

---

📖 Read the API docs | 🚀 View examples | ❓ FAQ | 💬 Report issues