completengine Documentation #

bash Copy

# Using npm
npm install completengine

# Using yarn
yarn add completengine

# Using pnpm
pnpm add completengine

bash Copy

npm install -g completengine
completengine init my-project

bash Copy

npx completengine --version
# Output: completengine v2.4.1

javascript Copy

// complete.config.js
export default {
  target: 'universal',
  optimize: true,
  concurrency: 4,
  plugins: [
    compression(),
    analytics({ silent: true })
  ],
  events: {
    maxListeners: 100,
    errorStrategy: 'propagate'
  }
}

bash Copy

# Run with debug logging
CE_LOG_LEVEL=debug npx completengine build

# Run with 8 parallel threads
CE_CONCURRENCY=8 npx completengine build

javascript Copy

import { engine } from 'completengine'

const app = engine.create({
  target: 'node',
  concurrency: 8,
  optimize: true
})

const result = await app.build()

javascript Copy

const scenario = {
  name: 'load-test',
  actors: 1000,
  duration: 5000,
  events: [
    { type: 'spawn', at: 0, count: 100 },
    { type: 'interact', at: 500, pattern: 'random' },
    { type: 'checkpoint', at: 2500 }
  ]
}

const result = await app.simulate(scenario)
// result.completed  -> true
// result.elapsed    -> 4230
// result.events     -> 15420

javascript Copy

const app = engine.create({ /* config */ })

app.on('build:start', (ctx) => {
  // Fires before build begins
})

app.on('build:complete', (result) => {
  // Fires when build finishes
})

app.on('sim:tick', (tick) => {
  // Fires each simulation tick
  // tick.frame, tick.actors, tick.elapsed
})

app.on('error', (err) => {
  // Centralized error handler
})

javascript Copy

import { compression, profiler } from 'completengine/plugins'

const app = engine.create({
  plugins: [
    compression({ level: 9 }),
    profiler({ output: './profile.json' })
  ]
})

javascript Copy

export function myPlugin(options = {}) {
  return {
    name: 'my-plugin',
    version: '1.0.0',

    setup(engine) {
      // Called once during engine.create()
    },

    beforeBuild(ctx) {
      // Modify build context before build starts
      ctx.meta.startTime = Date.now()
    },

    afterBuild(ctx, result) {
      // Access build result, emit metrics, etc.
      const elapsed = Date.now() - ctx.meta.startTime
    },

    teardown() {
      // Called on engine.destroy()
    }
  }
}

javascript Copy

// 1. Use the cache plugin for repeated builds
import { cache } from 'completengine/plugins'

const app = engine.create({
  plugins: [cache({ maxAge: 3600000 })],
  concurrency: navigator.hardwareConcurrency || 4
})

// 2. Use incremental builds in watch mode
const watcher = app.watch('src/**/*.js')

// 3. Limit simulation scope for dev
const devResult = await app.simulate({
  actors: 100,       // Fewer actors in dev
  duration: 1000,    // Shorter duration
  sampling: 0.1      // Sample 10% of events
})

javascript Copy

import { EngineError } from 'completengine'

try {
  await app.build()
} catch (err) {
  if (err instanceof EngineError) {
    // err.code    -> 'BUILD_FAILED'
    // err.message -> 'Build failed: missing entry'
    // err.hint    -> 'Check that src/index.js exists'
    // err.context -> { file: 'src/index.js' }
  }
}

javascript Copy

import { test, expect } from 'completengine/test'

test('handles 1000 concurrent actors', async () => {
  const app = engine.create({ concurrency: 8 })
  const result = await app.simulate({
    actors: 1000,
    duration: 5000
  })

  expect(result.completed).toBe(true)
  expect(result.errors).toHaveLength(0)
  expect(result.elapsed).toBeLessThan(6000)
})

test('recovers from actor failure', async () => {
  const app = engine.create()
  const result = await app.simulate({
    actors: 10,
    failAt: 5,
    events: [{ type: 'crash', target: 3 }]
  })

  expect(result.recovered).toBe(true)
  expect(result.activeActors).toBe(9)
})

bash Copy

# Run all tests
npx completengine test

# Run with coverage
npx completengine test --coverage

# Run specific test file
npx completengine test sim.test.js