runtime-compiler 3.2.0 → 4.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 aquapi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,17 +1,131 @@
-# `runtime-compiler`
-A code generation system for JS.
+A code generation system.
 
-## Modes
-- `default`: Build & run.
-- `build`: Build only.
-- `hydrate`: Run only.
+# Usage
+See [examples](https://github.com/re-utils/runtime-compiler/tree/main/examples).
 
+# Code generation
+Code generation is a trick used in a lot of high performance libraries, especially schema validators (TypeBox, Ajv, Sury, ...).
 ```ts
-import { isHydrating, onlyBuild } from 'runtime-compiler/config';
+const schema = {
+  id: t.string,
+  pwd: t.string
+};
 
-// Whether the process is in `hydrate` mode
-isHydrating;
+// Can be compiled to a fast check function
+const check = (0, eval)(`
+  (d) => typeof d === 'object'
+    && d !== null
+    && typeof d.id === 'string'
+    && typeof d.pwd === 'string'
+`);
+```
+
+Backend frameworks like Elysia also use it to optimize their request handling:
+```ts
+// Not exactly what Elysia generates but u get the idea
+switch (path) {
+  case '/': return handleHome();
+  case '/user': {
+    // Calls can be analyzed to remove
+    // unused fields in the context object
+    const c = { ... };
 
-// Whether the process is in `build` mode
-onlyBuild;
+    // Inline hook calls
+    onRequestHook(c);
+    handleRequest(c);
+    afterRequestHook(c);
+
+    return sendResponse(c);
+  }
+}
+```
+
+For cases that code generation works, it is usually much easier to write and setup than AST transformations, compiles faster, and also has more flexibility.
+
+The output startup cost is higher than AST transformations though, but this library has primitives to minimize that additional cost.
+
+## Writing codegen
+The first example was pretty simple, but what if we want to use an user-defined value?
+```ts
+const check = (0, eval)(`
+  (d) => typeof d === 'string' && checkEmail(d)
+`);
+```
+
+This works but it breaks with closures (similarly for other types of unserializable data):
+```ts
+import { checkEmail } from './utils.ts';
+
+// eval returns the value of the last statement
+const check = (0, eval)(`
+  const checkEmail = ${checkEmail.toString()};
+  (d) => typeof d === 'string' && checkEmail(d)
+`);
+
+// For a checkEmail function like this it would
+// break as emailRegex is not available in eval scope
+const emailRegex = /.../;
+const checkEmail = (str: string) => emailRegex.test(str);
+```
+
+We gonna need a dependency array to inject user-defined values into the eval scope:
+```ts
+import { checkEmail } from './utils.ts';
+
+const buildCheck = (0, eval)(`(deps) => {
+  const checkEmail = deps[0];
+  return (d) => typeof d === 'string' && checkEmail(d)
+}`);
+
+const check = buildCheck([checkEmail]);
+```
+
+## Problems
+Code generation has 2 main problems:
+- It has a startup time, memory usage and bundle size cost.
+- It does not work on certain runtimes.
+
+This library merges all `eval()` calls into 1 (which makes it able to do ahead of time compilation) and make compiled values easier to work with.
+```ts
+const check1 = compile(schema1);
+const check2 = compile(schema2);
+
+// Can be rewritten as
+const check1Id = compile(schema1);
+const check2Id = compile(schema2);
+
+// For ahead-of-time compilation to work
+// this evaluate() call can just be replaced with
+// whatever code is generated at the moment
+evaluate();
+
+const check1 = artifact(check1Id);
+const check2 = artifact(check2Id);
+```
+
+The ahead of time output can be:
+```js
+// Store dependencies and build outputs
+const check1Id = compile(schema1);
+const check2Id = compile(schema2);
+
+$[0] = (d) => typeof d === 'string';
+$[1] = (d) => Number.isInteger(d) && d > -1 && d < 256;
+
+const check1 = artifact(check1Id);
+const check2 = artifact(check2Id);
+```
+
+We can remove the codegen cost with flags:
+```ts
+const compile = IS_AOT
+  // This is the compile() function after build, since
+  // we don't need to codegen anymore
+  ? () => reserveArtifact()
+  : (schema1) => {
+    ...;
+    const schemaId = reserveArtifact();
+    emit(`$[${schemaId}]=${builtFnCode}`);
+    return schemaId;
+  }
 ```

package/build/index.d.ts

@@ -0,0 +1,6 @@
+export declare const getPromiseResolvers: (res: any, rej: any) => void;
+export declare const runInWorker: (code: string) => Promise<string[]>;
+/**
+* Requires code to not bundle "runtime-compiler/env" and "runtime-compiler/globals"
+*/
+export declare const compile: (code: string) => Promise<string>;

package/build/index.js

@@ -0,0 +1 @@
+import{Worker}from"node:worker_threads";let curRes,curRej;export const getPromiseResolvers=(res,rej)=>{curRes=res;curRej=rej};let workerOptions={eval:!0};export const runInWorker=code=>{let p=new Promise(getPromiseResolvers),worker=new Worker(`import"runtime-compiler/env/build";import{__rtcpl_ct__}from"runtime-compiler/globals";import{parentPort as __rtcpl_pp__}from"node:worker_threads";${code};\n__rtcpl_pp__.postMessage(__rtcpl_ct__)`,workerOptions);worker.once("message",curRes);worker.once("error",curRej);return p};export const compile=async code=>{let str='import"runtime-compiler/env/aot";import{__rtcpl_setup_aot__}from"runtime-compiler/globals";';for(let i=0,codes=await runInWorker(code);i<codes.length;i++)str+=`__rtcpl_setup_aot__($=>{${codes[i]}});`;return str+code};

package/build/rolldown.d.ts

@@ -0,0 +1,16 @@
+import type { Plugin } from "rolldown";
+interface ImportBinding {
+	name: string;
+	alias: string;
+}
+interface ImportStatement {
+	start: number;
+	end: number;
+	bindings: ImportBinding[];
+}
+export declare const parseImports: (code: string) => {
+	envImports: ImportStatement;
+	globalsImports: ImportStatement;
+};
+declare const _default: () => Plugin;
+export default _default;

package/build/rolldown.js

@@ -0,0 +1 @@
+import{runInWorker}from"./index.js";let parseImportBindings=(code,start,end)=>{let startSpecs=code.indexOf("{",start),endSpecs=code.lastIndexOf("}",end);if(-1===start&&-1===end)throw new Error("Only named imports replacement is supported!");let bindings=[];for(let i=0,specifiers=code.slice(startSpecs+1,endSpecs-1).split(",");i<specifiers.length;i++){let specifier=specifiers[i].trim();if(""===specifier)continue;let parts=specifier.split(" as ",2);if(1===parts.length){let name=parts[0].trim();bindings.push({name,alias:name})}else bindings.push({name:parts[0].trim(),alias:parts[1].trim()})}return{bindings,start,end}};export const parseImports=code=>{let envImports,globalsImports;for(let start=0,eol=code.indexOf("\n");eol>-1&&(null==envImports||null==globalsImports);eol=code.indexOf("\n",start=eol+1))code.startsWith("import",start)&&(code.endsWith('"runtime-compiler/env";',eol)?envImports=parseImportBindings(code,start,eol):code.endsWith('"runtime-compiler/globals";',eol)&&(globalsImports=parseImportBindings(code,start,eol)));return{envImports,globalsImports}};export default(()=>({name:"rolldown-plugin-runtime-compiler",resolveId:{filter:{id:/^runtime-compiler\/(?:env|globals)$/},handler:()=>!1},renderChunk:async(code,chunk)=>{if(!chunk.imports.includes("runtime-compiler/globals")||!chunk.imports.includes("runtime-compiler/env"))return null;let{envImports,globalsImports}=parseImports(code),aotCode="const __rtcpl_atf__=[],__rtcpl_aot_fns__=[],__rtcpl_setup_aot__=f=>{__rtcpl_aot_fns__.push(f)};let __rtcpl_aot_fn_idx__=0;";for(let i=0,{bindings}=envImports;i<bindings.length;i++){let{name,alias}=bindings[i];aotCode+="IS_AOT"===name?`const ${alias}=true;`:"IS_BUILD"===name||"IS_JIT"===name?`const ${alias}=false;`:""}for(let i=0,{bindings}=globalsImports;i<bindings.length;i++){let{name,alias}=bindings[i];aotCode+="artifact"===name?`const ${alias}=i=>__rtcpl_atf__[i];`:"emit"===name?`const ${alias}=()=>{};`:"evaluate"===name?`const ${alias}=()=>__rtcpl_aot_fns__[__rtcpl_aot_fn_idx__++](__rtcpl_atf__);`:"reserveArtifact"===name?`const ${alias}=()=>__rtcpl_atf__.push(undefined)-1;`:"importArtifact"===name?`const ${alias}=v=>__rtcpl_atf__.push(v)-1;`:""}for(let i=0,codes=await runInWorker(code);i<codes.length;i++)aotCode+=`__rtcpl_setup_aot__($=>{${codes[i]}});`;aotCode+=envImports.start<globalsImports.start?code.slice(0,envImports.start)+code.slice(envImports.end,globalsImports.start)+code.slice(globalsImports.end):code.slice(0,globalsImports.start)+code.slice(globalsImports.end,envImports.start)+code.slice(envImports.end);return{code:aotCode}}}));

package/env/aot.js

@@ -0,0 +1 @@
+import{setAOT}from"./index.js";setAOT();

package/env/build.js

@@ -0,0 +1 @@
+import{setBuild}from"./index.js";setBuild();

package/env/index.d.ts

@@ -0,0 +1,3 @@
+export declare let IS_JIT: boolean;
+export declare let IS_BUILD: boolean;
+export declare let IS_AOT: boolean;

package/env/index.js

@@ -0,0 +1 @@
+export let IS_JIT=!0;export let IS_BUILD=!1;export let IS_AOT=!1;export const setBuild=()=>{IS_JIT=!1;IS_BUILD=!0;IS_AOT=!1};export const setAOT=()=>{IS_JIT=!1;IS_BUILD=!1;IS_AOT=!0};

package/globals.d.ts

@@ -0,0 +1,10 @@
+export type Artifact<T> = number & {
+	"~": T;
+};
+export declare const importArtifact: <T>(value: T) => Artifact<T>;
+export declare const reserveArtifact: <T>() => Artifact<T>;
+export declare let evaluate: <T>() => T;
+export declare const emit: (code: string) => void;
+export type ArtifactsRecord = Record<any, Artifact<any>>;
+export type ArtifactGroup<T extends ArtifactsRecord> = <K extends keyof T>(k: K) => T[K]["~"];
+export declare const artifact: <T>(id: Artifact<T>) => T;

package/globals.js

@@ -0,0 +1 @@
+import{IS_AOT,IS_BUILD}from"./env/index.js";import{emptyFn}from"./utils.js";let __rtcpl_atf__=[];export const importArtifact=value=>__rtcpl_atf__.push(value)-1;export const reserveArtifact=()=>__rtcpl_atf__.push(void 0)-1;let content="";export let __rtcpl_ct__=[];export let evaluate=IS_AOT?()=>__rtcpl_aot_fns__[__rtcpl_aot_fn_idx__++](__rtcpl_atf__):IS_BUILD?()=>{__rtcpl_ct__.push(content);let currentContent=content;content="";if(currentContent.length>0)return(0,eval)(`$=>{${currentContent}}`)(__rtcpl_atf__)}:()=>{let currentContent=content;content="";if(currentContent.length>0)return(0,eval)(`$=>{${currentContent}}`)(__rtcpl_atf__)};export const emit=IS_AOT?emptyFn:code=>{content+=code};let __rtcpl_aot_fns__=[],__rtcpl_aot_fn_idx__=0;export const __rtcpl_setup_aot__=fn=>{__rtcpl_aot_fns__.push(fn)};export const artifact=id=>__rtcpl_atf__[id];

package/package.json

@@ -1 +1 @@
-{"name":"runtime-compiler","version":"3.2.0","description":"Universal compiler system","keywords":[],"repository":{},"homepage":"","license":"MIT","type":"module","exports":{"./utils":"./utils.js","./config":"./config/index.js",".":"./index.js","./config/mode/hydrate":"./config/mode/hydrate.js","./config/mode/build":"./config/mode/build.js","./config/loader/hydrate":"./config/loader/hydrate.js","./config/loader/build":"./config/loader/build.js"}}
+{"name":"runtime-compiler","version":"4.0.0","description":"A compiler system.","keywords":[],"homepage":"","license":"MIT","repository":"","type":"module","exports":{"./*":"./*.js","./build":"./build/index.js","./env":"./env/index.js"}}

package/scope.d.ts

@@ -0,0 +1,13 @@
+export type Scope = [start: string, end: string, nextId: number];
+/**
+* Get next available id in a scope.
+*/
+export declare const scopeNextId: (scope: Scope) => number;
+/**
+* Get scope content.
+*/
+export declare const scopeContent: (scope: Scope) => string;
+/**
+* Fork a new scope.
+*/
+export declare const scopeFork: <T extends Scope>(scope: T) => T;

package/scope.js

@@ -0,0 +1 @@
+export const scopeNextId=scope=>scope[2]++;export const scopeContent=scope=>`{${scope[0]+scope[1]}}`;export const scopeFork=scope=>scope.slice();

package/utils.d.ts

@@ -1,43 +1 @@
-import { type Expression, type Value } from "./index.ts";
-/**
-* Placeholder for `hydrate` mode.
-*/
-export declare const noOp: () => string;
-/**
-* Async function constructor
-*/
-export declare const AsyncFunction: typeof Function;
-/**
-* Derive a value from other expressions.
-* Use in `default` and `build` mode.
-*
-* @example
-* const newValue = derive(
-*   ['Math.random()' as Expression<number>],
-*   (rand) => rand * 10
-* ); // '$[0](Math.random())'
-*
-* // In hydrate mode
-* injectExternal((rand) => rand * 10);
-*/
-export declare const derive: <
-	const Expressions extends Expression<any>[],
-	R
->(values: Expressions, fn: (...args: { [K in keyof Expressions] : Expressions[K]["~type"] }) => R) => Value<R>;
-/**
-* Derive a value from other expressions.
-* Use in `default` and `build` mode.
-*
-* @example
-* const newValue = deriveAsync(
-*   ['await fetch("http://example.com")' as Expression<Response>],
-*   async (res) => await res.text()
-* ); // 'await $[0](await fetch("http://example.com"))'
-*
-* // In hydrate mode
-* injectExternal((rand) => rand * 10);
-*/
-export declare const deriveAsync: <
-	const Expressions extends Expression<any>[],
-	R
->(values: Expressions, fn: (...args: { [K in keyof Expressions] : Expressions[K]["~type"] }) => Promise<R>) => Expression<R>;
+export declare const emptyFn: () => void;

package/utils.js

@@ -1 +1 @@
-import{injectExternal}from"./index.js";export let noOp=()=>``;export let AsyncFunction=(async()=>{}).constructor;export let derive=(r,i)=>injectExternal(i)+`(`+r.join()+`)`;export let deriveAsync=(r,i)=>`await `+injectExternal(i)+`(`+r.join()+`)`;
+export const emptyFn=()=>{};

package/config/index.d.ts

@@ -1,8 +0,0 @@
-/**
-* False when in `default` and `build` mode, true in `hydrate` mode
-*/
-export declare let isHydrating: boolean;
-/**
-* False when in `default` and `hydrate` mode, true in `build` mode
-*/
-export declare let onlyBuild: boolean;

package/config/index.js

@@ -1 +0,0 @@
-export let isHydrating=false;export let onlyBuild=false;export let hydrating=()=>{isHydrating=true};export let building=()=>{onlyBuild=true};

package/config/loader/build.d.ts

@@ -1 +0,0 @@
-export {};

package/config/loader/build.js

@@ -1 +0,0 @@
-import{building}from"../index.js";building();

package/config/loader/hydrate.d.ts

@@ -1 +0,0 @@
-export {};

package/config/loader/hydrate.js

@@ -1 +0,0 @@
-import{hydrating}from"../index.js";hydrating();

package/config/mode/build.d.ts

@@ -1,2 +0,0 @@
-export declare const isHydrating: boolean;
-export declare const onlyBuild: boolean;

package/config/mode/build.js

@@ -1 +0,0 @@
-export let isHydrating=false;export let onlyBuild=true;

package/config/mode/hydrate.d.ts

@@ -1,2 +0,0 @@
-export declare const isHydrating: boolean;
-export declare const onlyBuild: boolean;

package/config/mode/hydrate.js

@@ -1 +0,0 @@
-export let isHydrating=true;export let onlyBuild=false;

package/index.d.ts

@@ -1,119 +0,0 @@
-export type Expression<T> = string & {
-	"~type": T
-};
-export type Value<T> = Expression<T> & {
-	"~value": 0
-};
-export type Identifier<T> = Value<T> & {
-	"~id": 0
-};
-export type ExportedDependency<T> = number & {
-	"~type": T
-};
-export interface Scope {
-	/**
-	* Current scope content.
-	*/
-	0: string;
-	/**
-	* Next available id.
-	*/
-	1: number;
-	/**
-	* End scope content.
-	*/
-	2: string;
-	slice: () => this;
-}
-/**
-* External dependencies
-*/
-export declare const $: any[];
-/**
-* Inject an external dependency.
-*/
-export declare const injectExternal: <T>(val: T) => Value<T>;
-/**
-* Get next available identifier name in a scope
-*/
-export declare const nextId: <T>(scope: Scope) => Identifier<T>;
-export declare const content: <T>(scope: Scope) => string;
-/**
-* Declare a new variable in a scope
-*
-* @example
-* declareLocal(scope, '1;');
-*/
-export declare const declareLocal: <T>(scope: Scope, str: string) => Identifier<T>;
-/**
-* Declare a new variable in a scope
-*/
-export declare const declareExternal: <T>(scope: Scope, val: T) => Identifier<T>;
-interface ExportToParent {
-	<T>(scope: Scope, expr: Expression<T>, parentScope: Scope): Identifier<T>;
-	(scope: Scope, expr: string, parentScope: Scope): string;
-}
-/**
-* Export a local expression to a parent local variable.
-* Use in `default` and `build` mode.
-*
-* @example
-* // Fork scope
-* const childScope = ['', parentScope.id];
-* // let d0;{let d1=1;d0=d1}
-* const id = exportTo(childScope, declareLocal(childScope, '1'), parentScope); // d0
-*/
-export declare const exportToParent: ExportToParent;
-/**
-* Mark current available variable id to be already in use.
-* Use in `hydrate` mode.
-* @param scope
-*/
-export declare const markDeclared: (scope: Scope) => void;
-export declare let statements: string;
-interface ExportScope {
-	<T>(scope: Scope, value: Expression<T>): ExportedDependency<T>;
-	<T>(scope: Scope, value: string): ExportedDependency<T>;
-}
-/**
-* Export a local dependency of a scope.
-* Use in `default` and `build` mode.
-*/
-export declare const exportScope: ExportScope;
-/**
-* Export a value.
-* Use in `default` and `build` mode.
-*
-* @example
-* exportLocal('1;');
-*/
-export declare const exportLocal: <T>(value: string) => ExportedDependency<T>;
-/**
-* Mark a slot to export a dependency.
-* Use in `hydrate` mode.
-*/
-export declare const markExported: <T>() => ExportedDependency<T>;
-/**
-* Get the value of an exported dependency.
-* Use in `default` mode.
-* @param idx
-*/
-export declare const getDependency: <T>(idx: ExportedDependency<T>) => T;
-/**
-* Get built statements and reset for next build.
-* Use in `build` mode.
-*/
-export declare const getStatements: () => string;
-/**
-* Store temporary build data.
-*/
-export declare let buildData: any[];
-/**
-* @example
-* const slot = createBuildSlot();
-*
-* // Reset after every build
-* buildData[slot] ??= data;
-*/
-export declare const createBuildSlot: () => number;
-export {};

package/index.js

@@ -1 +0,0 @@
-;export let $=[];export let injectExternal=f=>`$[${$.push(f)-1}]`;export let nextId=e=>`d`+ e[1]++;export let content=e=>e[0]+e[2];export let declareLocal=(e,f)=>{let m=nextId(e);e[0]+=`let ${m}=`+f;return m};export let declareExternal=(f,m)=>{let h=nextId(f);f[0]+=`let ${h}=$[${$.push(m)-1}];`;return h};export let exportToParent=(e,f,h)=>{let g=nextId(h);h[0]+=`let ${g};{${content(e)+g}=${f}}`;return g};export let markDeclared=e=>{e[1]++};export let statements=``;export let exportScope=(f,p)=>(statements+=`{${content(f)}$[${$.length}]=${p}}`,$.length++);export let exportLocal=f=>(statements+=`$[${$.length}]=${f}`,$.length++);export let markExported=()=>$.length++;export let getDependency=f=>{if(statements.length>0){globalThis.__rt_externals__=$;(0,eval)(`{let $=__rt_externals__;`+statements+`}`);globalThis.__rt_externals__=null;statements=``;buildData=[]}return $[f]};export let getStatements=()=>{let e=statements;statements=``;buildData=[];return e};export let buildData=[];let nextSlot=0;export let createBuildSlot=()=>nextSlot++;