|
| 1 | + |
| 2 | +### Transform SQL to JavaScript code |
| 3 | + |
| 4 | +If you want to fiddle with speed you can pre-generate the JS code that will be running your query. |
| 5 | + |
| 6 | +The returned function has the signature `function(params, cb)` and is designed to be called with `alasql` as context. |
| 7 | + |
| 8 | +```js |
| 9 | +import alasql from 'alasql'; |
| 10 | +import {compileToJS} from 'alasql/precompile'; |
| 11 | + |
| 12 | +const jsCode = compileToJS('SELECT * FROM ? WHERE pop > 1000000', 'my_db'); |
| 13 | + |
| 14 | +const selectPop = new Function('return ' + jsCode)().bind(alasql); |
| 15 | + |
| 16 | +// Now you can call it like a regular alasql function, but without the SQL |
| 17 | +let data = [{city: 'Copenhagen', pop: 1300000}, {city: 'Aarhus', pop: 300000}]; |
| 18 | +let res = selectPop([data]); |
| 19 | +// res will be [{city: 'Copenhagen', pop: 1300000}] |
| 20 | +``` |
| 21 | + |
| 22 | +This example is not useful in it self, as it is all done during exeuction time (you could just as well have used alasql.compile() directly). However, if you precompile the function at build time, it can be a significant performance boost as the execution don't have to parse the SQL. There is an example of how to do this with Bun in [examples/precompileJS](https://github.com/AlaSQL/alasql/tree/develop/examples/precompileJS) |
| 23 | + |
| 24 | + |
| 25 | +--------- |
| 26 | + |
| 27 | + |
| 28 | +# AlaSQL Precompile Module |
| 29 | + |
| 30 | +This module provides SQL compilation functionality that allows you to pre-compile SQL queries into JavaScript code, skipping SQL parsing on execution. |
| 31 | + |
| 32 | +The functionality is experimental - so proceed with caution and expect changes. |
| 33 | + |
| 34 | +## Installation |
| 35 | + |
| 36 | +```javascript |
| 37 | +import { compileToJS } from 'alasql/precompile'; |
| 38 | +``` |
| 39 | + |
| 40 | +## Functions |
| 41 | + |
| 42 | +### `compileToJS(sql, databaseid?)` - Precompile |
| 43 | + |
| 44 | +Compiles a SQL statement to JavaScript source code that expects an AlaSQL engine as `this`. This is useful for performance optimization as it eliminates SQL parsing overhead at runtime. |
| 45 | + |
| 46 | +**Parameters:** |
| 47 | +- `sql` (string): SQL statement to compile |
| 48 | +- `databaseid` (string, optional): Database identifier |
| 49 | + |
| 50 | +**Returns:** Generated JavaScript source code string |
| 51 | + |
| 52 | +## Usage Example |
| 53 | + |
| 54 | +```javascript |
| 55 | +import { compileToJS } from 'alasql/precompile'; |
| 56 | + |
| 57 | +const sql = 'SELECT name, age FROM users WHERE age > ?'; |
| 58 | +const jsCode = compileToJS(sql); |
| 59 | + |
| 60 | +// Create a function from the compiled code |
| 61 | +const queryFn = new Function('return ' + jsCode)().bind(alasql); |
| 62 | + |
| 63 | +// Execute the function (requires AlaSQL) |
| 64 | +const result = queryFn([users, 18]); |
| 65 | +``` |
| 66 | + |
| 67 | +## Build-time Compilation |
| 68 | + |
| 69 | +You can use this function with build tools like Bun, Vite, or Webpack to compile SQL queries at build time: |
| 70 | + |
| 71 | +```javascript |
| 72 | +// Using Bun macro for precompile |
| 73 | +import { compileToJS } from './my-queries.js' with { type: 'macro' }; |
| 74 | + |
| 75 | +const queryFn = new Function('return ' + compileToJS('SELECT * FROM users'))().bind(alasql); |
| 76 | +``` |
| 77 | + |
| 78 | +## Benefits |
| 79 | + |
| 80 | +- **Performance**: Eliminate SQL parsing overhead at runtime |
| 81 | +- **Flexibility**: Still has access to full AlaSQL functionality |
| 82 | +- **Debugging**: Can still use AlaSQL debugging tools |
| 83 | +- **Works with database tables**: Supports both parameterized queries and database tables |
0 commit comments