YOUSEFUL / FILEMAKER

YsflJS — function reference

Function prefix YsflJs_, 15 functions. Runs JavaScript from FileMaker either in process (QuickJS-ng 0.16.2, ES2023, embedded in the plugin) or out of process through Node.js.

Modes

mode	engine	state between calls	notes
`inproc` (default)	QuickJS inside FileMaker	globals persist until `YsflJs_Reset`	no `require`; `console`, `fm`, `JSON`, ES2023 built-ins; timeouts interrupt the engine
`worker`	one `node.exe` kept alive per session	persists until `Reset`, `Stop`, a timeout or a crash	full Node: `require`, `process`, `Buffer`, npm modules
`process`	a fresh `node.exe` per call	none	safest isolation

Set the session default with YsflJs_Configure ( "mode=worker" ) or per call with the options parameter. Node is found through node=<path>, the YSFL_NODE environment variable, PATH, or the usual install folders. The Node host script is written to %LOCALAPPDATA%\Youseful\hosts\ysfljs_host.js.

Options (per call or via Configure)

mode=inproc|process|worker, timeout=<sec> (default 60), node=<path to node.exe>, param=<text> (rest of the line; available as fm.param).

Functions

Function	Returns
`YsflJs_Run ( code ; {options} )`	the completion value of the code (like a REPL: `1 + 2` → `3`, objects as JSON, `undefined`/`null` → `""`); when there is no value, whatever `console.log` printed
`YsflJs_RunFile ( path ; {options} )`	same, from a `.js` file (UTF-8, BOM tolerated)
`YsflJs_Call ( function ; {argsJSON} ; {options} )`	calls a function defined earlier (dotted names allowed) with a JSON array of arguments
`YsflJs_Set ( name ; value ; {type} )`	defines a global; `text` (default), `number`, `bool`, `json`
`YsflJs_Get ( name )`	a global's value (objects as JSON)
`YsflJs_Output`	`console.log` output of the last call
`YsflJs_Error`	full error text (with stack) of the last call
`YsflJs_Reset`	fresh global scope (worker: the process keeps running)
`YsflJs_Stop`	ends the worker process
`YsflJs_Configure ( options )`	session defaults
`YsflJs_Mode`	effective mode, engine or node path, whether a worker is running
`YsflJs_Version`	plugin, QuickJS version, node path
`YsflJs_Register`, `YsflJs_LastError`, `YsflJs_LastErrorText`

Failures return ? ErrorName: message; YsflJs_Error has the stack trace.

Talking to FileMaker from the script

fm.evaluate ( expr ) evaluates a FileMaker calculation and returns its text; fm.sql ( query ) runs ExecuteSQL and returns rows separated by ¶, columns by tab; fm.param is the param= option. These work in every mode (out of process they travel through the plugin's pipe while the FileMaker call is in flight).

Notes

Promises are not awaited: a Run that evaluates to a promise returns {}. Use synchronous code or resolve inside the script.
The in-process engine has a 4 MB stack and interrupts scripts at the timeout; the worker is killed and restarted at the timeout, losing its state.

Set Variable [ $total ; YsflJs_Run ( "JSON.parse(fm.sql('SELECT amount FROM Orders').split('\r').map(Number).reduce((a,b)=>a+b, 0))" ) ]
Set Variable [ $r ; YsflJs_Configure ( "mode=worker" ) ]
Set Variable [ $csv ; YsflJs_Run ( "const {parse} = require('csv-parse/sync'); parse(fm.param, {columns: true}).length" ; "param=" & Import::Text ) ]