# JavaScript, TypeScript and Python

The `giz` command also runs JavaScript, TypeScript and Python programs. They run on one VM (`vm/`): an interpreter and
a JIT that both languages share. You need no Node.js and no Python install.

## Run a program

```sh
giz run main.ts          # also .js, .mjs, .cjs and .py
giz main.py ARG...       # the short form
```

The first run builds the VM and caches it, as it caches any program. VM flags, such as `--no-jit`, go before the
file. The flags are listed in [the VM internals](../internals/vm.md#1-run).

## Build one executable

```sh
giz build main.ts -o app
```

The result is the VM with the files of your project: the folder of the nearest `package.json` at or above the script,
else the script's folder. The first start unpacks the project into the cache and runs the entry there, so `require`,
`node_modules` and file reads find the project as it was built.

## JavaScript and TypeScript

- Modules resolve as in Node: `package.json` `main`, `exports` and `imports`, `node_modules`, `.ts` files, JSON
  modules, CommonJS and ES modules.
- `eval` and `new Function` work. A syntax error names the file and the line.
- Node's own `lib/` runs on the VM. It starts at the first built-in `require`, or at the first use of a Node global
  (`process`, `Buffer`, `URL`, `fetch`), so a plain script does not pay for it.
- A `.ts` file runs with its types removed. Decorators follow TC39 2023.

Add an npm package to a project with its exact version. Installation scripts never run:

```sh
giz get . npm:semver@7
```

```typescript
import semver from "semver";
console.log(semver.satisfies("1.2.3", "^1.0.0"));
```

## Python

- `sys.path` is the script's folder, then `PYTHONPATH`, then the `site-packages` of `$VIRTUAL_ENV` or of the nearest
  `.venv` above the script, then the standard library of CPython 3.15 (fetched once into the cache).
- Python source (your program, the standard library and site-packages) runs on the VM. The hot C modules (`sys`,
  `math`, `itertools`, `_json`, `_sre`, `_struct` and others) are native in the VM.
- Any other C module, such as a wheel's `.so` or pydantic-core, runs in CPython 3.15 through a bridge. The VM loads
  it at the first such import.

## Speed

Each program runs as a whole process, best of 5. Ratio is the reference time divided by the VM time: above 1, the VM
is faster.

| Program | Reference | Ratio |
| --- | --- | --- |
| fib.js, loop.js, obj.js, prop.js, method.js | Bun 1.3.11 | 1.08 to 1.86 |
| fib.py, loop.py, nbody.py, attr.py, method.py | PyPy 7.3.20 | 1.10 to 1.90 |
| An empty program (start and exit) | Bun, PyPy | 2.06 (JS), 6.08 (Python) |

Each program and its number are in [the VM internals](../internals/vm.md#5-performance).