Script subsystem
Run user-authored server.js lifecycle hooks in an isolated sandbox around data writes.
The script subsystem runs user-authored hooks from objects/<name>/server.js in an isolated
sandbox. Hooks run around data writes — validation, pre-write mutation, post-write side effects —
and bridge back to the engine for any data or service access.
Script is an optional subsystem. It's disabled by default, and when it's off it isn't loaded at all: no import, no workers, zero overhead.
Optional native dependency: the sandbox backend uses
isolated-vm, declared as anoptionalDependency. If you don't enable the script subsystem, it's never installed or loaded. If it's missing at startup while the subsystem is enabled, the engine fails fast withscript.sandbox.unavailable(npm install isolated-vm) instead of a raw module error.
In this section
- Authoring hooks — the hook list, examples, and editing
server.jsover the API - Context API —
this.*,this.db.objects, and restricted SQL - Sandbox & errors — isolation, limits and failure semantics
Enable
// weavekit.config.ts
export default {
// ...
subsystems: {
script: {
enabled: true,
sandbox: {
timeout: 5000, // overall hook timeout (ms)
queryTimeout: 2000, // per this.db call timeout (ms)
memoryLimit: 64 * 1024 * 1024, // sandbox heap limit (bytes)
maxConcurrentScripts: 10, // concurrent hook executions (over → script.busy)
maxObjectsPerQuery: 100, // rows a script may fetch per db.objects(...).find() (clamped; global cap 1000)
rls: { role: 'weavekit_query' }, // db.query row-level security role (on by default when script is enabled)
},
// services: { ... } // optional: custom this.services implementations
},
},
};Programmatic use
Beyond weave dev, you can wire the dispatcher yourself:
import { createScriptDispatcher, createDataAccess, createPool, ObjectRegistry } from '@weave-kit/engine';
const dispatcher = await createScriptDispatcher({
objectsDir: join(projectRoot, 'objects'),
registry,
pool,
dataAccess, // RBAC-decorated — serves this.db.objects
config: { sandbox: { timeout: 5000, queryTimeout: 2000 } },
});
const dataAccess = createDataAccess({ script: dispatcher }); // hooks now fire on writes
// ...
await dispatcher.close(); // terminates all workers