Omniscript Best Practices

September 4, 2025 · View on GitHub

Project Structure

myapp/
├── src/
│   ├── components/    # UI components
│   ├── models/       # Data models
│   ├── services/     # Business logic
│   └── utils/        # Helper functions
├── tests/           # Test files
├── package.json     # Dependencies
└── omni.json       # Omniscript config

Performance Best Practices

Memory Management

Enable garbage collection in long-running applications:

runtime.enableGarbageCollection();

Monitor memory usage regularly:

const usage = runtime.getMemoryUsage();
if (usage.allocated > THRESHOLD) {
  runtime.runGarbageCollector();
}

Check for circular references in development:

runtime.detectCircularReferences();

Reactive Programming

Use Signal for simple state management:

const counter = new Signal<number>(0);
counter.subscribe((value) => updateUI(value));

Use Stream for event-driven programming:

const events = new Stream<Event>();
events.subscribe((event) => handleEvent(event));

Thread Safety

Use thread-safe collections for concurrent access:

// Do
const list = new List<number>();
await list.push(1);

// Don't
const array = [];
array.push(1); // Not thread-safe

Use the Actor model for complex state management:

const actor = runtime.createActor((msg, state) => {
  // State updates are automatically thread-safe
  return state + msg;
}, 0);

Error Handling

Use Result Type

function divide(a: number, b: number): Result<number, Error> {
  if (b === 0) {
    return Result.Err(new Error("Division by zero"));
  }
  return Result.Ok(a / b);
}

Pattern Matching for Error Cases

match result {
  Ok(value) => handleSuccess(value),
  Err(error) => handleError(error)
}

Async Error Handling

try {
  const result = await asyncOperation();
} catch (error) {
  console.error("Operation failed:", error);
}

Testing

Unit Testing

Test each component in isolation
Use descriptive test names
Test edge cases

describe("MathUtils", () => {
  test("factorial computes correct value", () => {
    expect(MathUtils.factorial(5)).toBe(120);
  });

  test("gcd finds greatest common divisor", () => {
    expect(MathUtils.gcd(48, 18)).toBe(6);
  });
});

Integration Testing

Test component interactions
Test real-world scenarios
Use realistic test data

describe("Database Integration", () => {
  test("saves and retrieves user", async () => {
    const user = new User("test");
    await db.save(user);
    const retrieved = await db.find(user.id);
    expect(retrieved).toEqual(user);
  });
});

Performance Optimization

JIT Compilation

Enable JIT for hot code paths:

{
  "compiler": {
    "jit": true,
    "optimizations": {
      "simd": true,
      "parallelExecution": true
    }
  }
}

SIMD Operations

Use SIMD-optimized operations for numerical computations:

class Vector {
  @simd
  add(other: Vector): Vector {
    // Automatically uses SIMD instructions
    return new Vector(this.x + other.x, this.y + other.y);
  }
}

Parallel Execution

Use parallel execution for CPU-intensive tasks:

runtime.enableParallelExecution();

Security

Input Validation

Validate all user input
Use type constraints
Sanitize data before processing

function processUserInput(input: string): Result<Output, Error> {
  if (!isValid(input)) {
    return Result.Err(new Error("Invalid input"));
  }
  return Result.Ok(process(input));
}

Resource Management

Use automatic resource cleanup:

using resource = open("file.txt") {
  // Resource automatically cleaned up after block
}

Error Messages

Don't expose internal details in error messages
Log detailed errors internally
Return safe error messages to users

Documentation

Code Documentation

Document public APIs
Include examples
Explain complex algorithms

/**
 * Computes factorial of a number
 * @param n The number to compute factorial for
 * @returns The factorial of n
 * @throws Error if n is negative
 *
 * @example
 * MathUtils.factorial(5) // Returns 120
 */
static factorial(n: number): number {
  if (n < 0) throw new Error("Negative input");
  return n === 0 ? 1 : n * factorial(n - 1);
}

Generated Documentation

Keep documentation up to date
Include usage examples
Document error cases

Version Control

Commit Messages

Use clear commit messages
Reference issue numbers
Describe breaking changes

Branch Strategy

Use feature branches
Protect main branch
Regular integration

Deployment

Configuration

Use environment variables
Separate dev/prod configs
Version control safe defaults

Monitoring

Enable performance monitoring
Track memory usage
Log important events

runtime.enableDebugMode();
runtime.enableMemoryManagement();