Comptime.ts

<div align="center"> <img src="https://raw.githubusercontent.com/feathers-studio/comptime.ts/master/docs/comptime.ts.svg" alt="Hyperactive"> </div> <div align="center"> <h1>⚡️ comptime.ts</h1> </div> <div align="center"> <a href="https://github.com/feathers-studio/comptime.ts" target="_blank"> <svg height="32" viewBox="0 0 24 24" version="1.1" width="32" xmlns="http://www.w3.org/2000/svg" fill="currentColor"> <path d="M12 1C5.9225 1 1 5.9225 1 12C1 16.8675 4.14875 20.9787 8.52125 22.4362C9.07125 22.5325 9.2775 22.2025 9.2775 21.9137C9.2775 21.6525 9.26375 20.7862 9.26375 19.865C6.5 20.3737 5.785 19.1912 5.565 18.5725C5.44125 18.2562 4.905 17.28 4.4375 17.0187C4.0525 16.8125 3.5025 16.3037 4.42375 16.29C5.29 16.2762 5.90875 17.0875 6.115 17.4175C7.105 19.0812 8.68625 18.6137 9.31875 18.325C9.415 17.61 9.70375 17.1287 10.02 16.8537C7.5725 16.5787 5.015 15.63 5.015 11.4225C5.015 10.2262 5.44125 9.23625 6.1425 8.46625C6.0325 8.19125 5.6475 7.06375 6.2525 5.55125C6.2525 5.55125 7.17375 5.2625 9.2775 6.67875C10.1575 6.43125 11.0925 6.3075 12.0275 6.3075C12.9625 6.3075 13.8975 6.43125 14.7775 6.67875C16.8813 5.24875 17.8025 5.55125 17.8025 5.55125C18.4075 7.06375 18.0225 8.19125 17.9125 8.46625C18.6138 9.23625 19.04 10.2125 19.04 11.4225C19.04 15.6437 16.4688 16.5787 14.0213 16.8537C14.42 17.1975 14.7638 17.8575 14.7638 18.8887C14.7638 20.36 14.75 21.5425 14.75 21.9137C14.75 22.2025 14.9563 22.5462 15.5063 22.4362C19.8513 20.9787 23 16.8537 23 12C23 5.9225 18.0775 1 12 1Z"> </path> </svg> </a> </div>

A dead-simple TypeScript compiler that does one thing really well: enables compile-time evaluation of expressions marked with comptime.

This is useful for optimising your code by moving computations from runtime to compile time. This project was inspired by Bun macros and Zig comptime (hence the name).

Warning: You are responsible for ensuring that the expressions you mark with comptime are safe to evaluate at compile time. comptime.ts does not perform any isolation. However, comptime imports are only allowed in project files, and not in node_modules. You may however import from node_modules as comptime.

Quick References

• ↗️ Serialisation Reference
• ↗️ Error Reference

Contents

• What is comptime.ts?
• Examples
  • 1. Simple sum function
  • 2. Turn emotion CSS into a zero-runtime CSS library
  • 3. Calculate constants at compile time
• Installation
• Usage
  • With Vite
  • With Bun bundler
  • Command Line Interface
  • Via API
• Forcing comptime evaluation
  • Resolving promises
  • Opting out of comptime virality
• Using other import attributes
• Running code after comptime evaluation
• How it works
• Limitations
• Best practices
• Troubleshooting
• Supporting the project
• License

What is comptime.ts?

comptime.ts allows you to evaluate expressions at compile time, similar to compile-time macros in other languages. This can help optimise your code by moving computations from runtime to compile time.

Examples

1. Simple sum function

import { sum } from "./sum.ts" with { type: "comptime" };

console.log(sum(1, 2));

Compiles to:

console.log(3);

2. Turn emotion CSS into a zero-runtime CSS library

import { css } from "@emotion/css" with { type: "comptime" };

const style = css`
  color: red;
  font-size: 16px;
`;

div({ class: style });

Compiles to:

const style = "css-x2wxma";
div({ class: style });

Note: The @emotion/css import got removed from the output. You'll need to somehow add the styles back to your project somehow. See running code after comptime evaluation for an example of emitting the styles as a CSS file. Alternatively, you might write a bundler plugin to import the CSS cache from @emotion/css and emit them as a CSS file, etc.

3. Calculate constants at compile time

import { ms } from "ms" with { type: "comptime" };

const HOUR = ms("1 hour");

Compiles to:

const HOUR = 3600000;

Apart from function calls and tagged template literals, all sorts of expressions are supported (even more complex cases like index access and imported constants). The only limitation is that the resultant value must be serialisable (see serialisation).

Note: The import statements marked with type: "comptime" are removed in the output. We assume you have other tooling (like Vite) to handle other unused redundant statements left behind after comptime evaluation.

Installation

bun add comptime.ts

# or

pnpm add comptime.ts

# or

npm install comptime.ts

Usage

With Vite

Add the plugin to your Vite configuration:

import { comptime } from "comptime.ts/vite";

export default defineConfig({
	plugins: [comptime()],
});

In case comptime.ts is significantly slowing down your dev server, and your comptime functions behave identically at runtime and comptime, you may enable it only in production builds:

import { comptime } from "comptime.ts/vite";

export default defineConfig({
	build: {
		rollupOptions: {
			plugins: [comptime()],
		},
	},
});

With Bun bundler

Add the plugin to your Bun bundler configuration:

import { comptime } from "comptime.ts/bun";

await Bun.build({
	entrypoints: ["./index.ts"],
	outdir: "./out",
	plugins: [comptime()],
});

Command Line Interface

You can also use the CLI:

npx comptime.ts --project tsconfig.json --outdir out

Or use Bun if you prefer:

bunx --bun comptime.ts --project tsconfig.json --outdir out

Via API

Use the API directly:

import { comptimeCompiler } from "comptime.ts/api";

await comptimeCompiler({ tsconfigPath: "tsconfig.json" }, "./out");

Forcing comptime evaluation of arbitrary expressions (and resolving promises)

We can abuse the fact that any function imported with the type: "comptime" option will be evaluated at compile time.

This library exports a comptime() function that can be used to force comptime evaluation of an expression. It has to be imported with the "comptime" attribute. Any expressions contained within it will be evaluated at compile time. If the result is a promise, the resolved value will be inlined.

Note: Technically the comptime() function by itself doesn't do anything by itself. It's an identity function. It's the with { type: "comptime" } attribute that makes the compiler evaluate the expression at compile time.

import { comptime } from "comptime.ts" with { type: "comptime" };

Use it to force comptime evaluation of an expression.

const x = comptime(1 + 2);

When the compiler is run, the expression will be evaluated at compile time.

const x = 3;

Resolving promises

const x = comptime(Promise.resolve(1 + 2));

When the compiler is run, the promise will be resolved and the result will be inlined at compile time.

const x = 3;

Note: The compiler always resolves promises returned by the evaluation, but this might not reflect in your types, in which case it's useful to use the comptime() function to infer the correct type.

Opting out of comptime virality

Normally, comptime.ts will eagerly extend comptime to expressions that include a comptime expression.

import { foo } from "./foo.ts" with { type: "comptime" };

const x = foo().bar[1];

Compiles to:

const x = 2;

Notice how the whole expression, foo().bar[1], is evaluated at compile time. You can opt-out of this behaviour by wrapping your expression in parentheses.

<!-- prettier-ignore -->

const x = (foo().bar)[1];

Compiles to:

<!-- prettier-ignore -->

const x = ([1, 2])[1];

In this case, foo().bar is evaluated at comptime, but [1] is left untouched.

Note: Your formatter might remove the extraneous parentheses, so you may need to ignore the line (such as with prettier-ignore comments). You are of course free to extract the expression to its own line:

const res = foo().bar;
const x = res[1];

Compiles to:

const res = [1, 2];
const x = res[1];

This also results in only foo().bar being evaluated at comptime, and doesn't upset your formatter.

Using other import attributes

You can use other import attributes alongside type: "comptime". Support for them depends on the runtime you are using. For instance, to import JSON as at comptime, you can do:

import items from "./items.json" with { type: "comptime+json" };
console.log(items.map(items => items.name));

Compiles to:

console.log(["item1", "item2", "item3"]);

The same applies to other import attributes, such as comptime+text, comptime+bytes, etc., as supported by your runtime.

Since expressions are viral, the entire expression items.map(...) is evaluated at comptime. This is desirable in most cases, since some computation has moved to comptime. See opting out of comptime virality for how to avoid this if needed. You can also assign the imported value to a variable to embed the JSON data in your cod