API Reference

This section provides detailed documentation for the LokaScript API.

Core API

The main entry point for LokaScript is the hyperscript object:

import { hyperscript } from '@lokascript/core';

// Process all hyperscript attributes in the DOM
hyperscript.processNode(document.body);

// Compile a hyperscript string to an executable
const result = hyperscript.compileSync('on click toggle .active');

// Execute hyperscript code directly
await hyperscript.eval('toggle .active on #myElement', element);

API v2 (Recommended)

The v2 API provides cleaner methods with structured results:

compileSync(code, options?)

Synchronous compilation with structured result.

const result = hyperscript.compileSync('toggle .active');

if (result.ok) {
  console.log('Parser:', result.meta.parser); // 'semantic' or 'traditional'
  console.log('Confidence:', result.meta.semanticConfidence);
  // Execute the compiled code
  await result.executable.execute(element, {});
} else {
  console.error('Errors:', result.errors);
}

Returns:

interface CompileResult {
  ok: boolean;
  executable?: CompiledExecutable;
  errors?: CompileError[];
  meta: {
    parser: 'semantic' | 'traditional';
    semanticConfidence?: number;
    semanticLanguage?: string;
    warnings: string[];
  };
}

compileAsync(code, options?)

Async compilation for language loading.

const result = await hyperscript.compileAsync(code, { language: 'ja' });

eval(code, element?, options?)

Compile and execute in one call.

// Execute on specific element
await hyperscript.eval('add .clicked to me', button);

// Execute without element context
await hyperscript.eval('log "Hello World"');

// Execute with options
await hyperscript.eval('toggle .active', element, { language: 'en' });

validate(code, options?)

Validate hyperscript syntax without executing.

const validation = await hyperscript.validate('toggle .active');

if (!validation.valid) {
  validation.errors.forEach(err => {
    console.error(`Line ${err.line}: ${err.message}`);
  });
}

Returns:

interface ValidationResult {
  valid: boolean;
  errors: ValidationError[];
  warnings: string[];
}

createContext(element?, parent?)

Create execution context with optional parent inheritance.

const parent = hyperscript.createContext();
const child = hyperscript.createContext(element, parent);

Compilation Options

interface CompileOptions {
  language?: string; // Language code (e.g., 'en', 'ja', 'es')
  confidenceThreshold?: number; // Min confidence for semantic parsing (0-1)
  traditional?: boolean; // Force traditional parser
}

Compilation Metadata

Every compilation returns metadata about parser decisions:

const result = hyperscript.compileSync('toggle .active');
console.log(result.meta);
// {
//   parser: 'semantic',
//   semanticConfidence: 0.98,
//   semanticLanguage: 'en',
//   warnings: []
// }

This helps identify:

  • Which parser processed the code (semantic vs traditional)
  • Confidence score if semantic parser was used
  • Any warnings about ambiguous syntax

Legacy API

The following methods still work but show deprecation warnings:

Legacy Method v2 Replacement
compile() compileSync()
run() eval()
evaluate() eval()

API Sections

Core Functions

Commands

LokaScript includes 43 commands organized by category:

Expressions

Quick Example

<button
  _="on click
  add .loading to me
  fetch /api/data as json
  put result.message into #output
  remove .loading from me"
>
  Load Data
</button>

Next Steps

Edit this page on GitHub