Annotations

In kdts, compiler directives are provided via satisfies expressions, or when it's more convenient, through the @satisfies {} jsdoc tags.

Overridable

Constant variable declarations can be annotated as Overridable. For such variables, the default initializer can be overridden with values supplied from the command line:

worker.ts

import { Overridable } from "@kimlikdao/kdts";

const Status = 404 satisfies Overridable;
const HostUrl = "https://example.com" satisfies Overridable;

export default () => Response.redirect(HostUrl, Status);

When compiled with kdts worker.ts --override HostUrl="test.com" --override Status=405, we get

worker.out.js

export default()=>Response.redirect("test.com",405);

Function classes

In kdts, to achieve better optimizations, functions can be annotated as belonging to certain function classes. For example:

/** @satisfies {PureFn} */
const greet = (name: string) => `Hi, ${name}!`;

Here, greet is annotated as being PureFn , which promises to the compiler that the function has no side effects, does not depend on mutable external state (hence deterministic) and returns a fresh value (we will introduce this formally later; primitives are always fresh).

If the function depended on external mutable state but is side-effect free, we can use the weaker marker SideEffectFreeFn:

/** @satisfies {SideEffectFreeFn} */
const rand = (a: number, b: number) => a + Math.random() * (b - a);

An InlineFn is inlined to each call site and the function body is compiled away completely:

/** @satisfies {InlineFn} */
const ensureArray = <T>(x: T | T[]): T[] => Array.isArray(x) ? x : [x];

Now, each time ensureArray(x) is called, we will see the expression Array.isArray(x) ? x : [x] inlined, unless kdts can prove x to be an array or not an array from the declared or inferred types. In such cases, the function call is compiled to x or [x] .

FreshValue

Before we go over all function classes, let us define FreshValue first. A FreshValue is defined recursively as a primitive (such as string, number, bigint etc) or a fresh object containing FreshValue s. For instance the following are all FreshValues

"Abc",
{ name: "Abc", age: 1 },
new Uint8Array([1, 2, 3]),
Uint8Array.fromHex("abcd").buffer,

The following is not a FreshValue

const person = { name: "Abc", age: 1 };
{ person }

since person is not a fresh object.

List of function classes

Here is the full list of function annotations kdts currently optimizes with:

Annotation	Meaning
DeterministicFn	A function which doesn't read external mutable state
SideEffectFreeFn	A function which doesn't change its argument or any external state
MethodFn	A class method which can only change state reachable from `this`. Further, it cannot read external mutable state.
InPlaceFn	A function which mutates only state reachable from its arguments. Further, it cannot read external mutable state.
InPlaceRandFn	A function which mutates only state reachable from its arguments. It can read external mutable state.
PureAliasFn	A function which doesn't read external mutable state and is side-effect free.
PureFn	A PureAliasFn which also returns a FreshValue
InlineFn	A function which will be inlined to each call site and the function body will be compiled away.
NoInlineFn	A function which cannot be inlined and calls to it must be preserved as-is.
InlineFriendlyFn	A function the compiler is encouraged to inline when profitable, but unlike InlineFn it is not required to inline every call site.

Examples

/**
 * Partitions the array into chunks of size n, except for the last chunk which
 * can be smaller, but not empty.
 *
 * For n ≤ 0, returns []
 *
 * @satisfies {PureFn}
 */
const chunk = <T>(arr: T[], n: number): T[][] => {
  if (n <= 0) return [];
  const result: T[][] = [];
  for (let i = 0; i < arr.length; i += n)
    result.push(arr.slice(i, i + n));
  return result;
};

/**
 * Shuffles the array uniformly at random in place.
 * @satisfies {InPlaceRandFn}
 */
const shuffle = <T>(arr: T[]): T[] => {
  for (let i = arr.length - 1; i > 0; --i) {
    const j = (Math.random() * (i + 1)) | 0;
    [arr[i], arr[j]] = [arr[j], arr[i]];
  }
  return arr;
};

/** @satisfies {SideEffectFreeFn & NoInlineFn} */
const byId = (id: string): HTMLElement =>
  document.getElementById(id) as HTMLElement;

LargeConstant

A constant variable declaration can be marked as a large constant; this will prevent it from being inlined to each use of it.

import { LargeConstant } from "@kimlikdao/kdts";
import { arfCurve } from "@kimlikdao/lib/crypto/arfCurve";

const P = (1n << 254n) + 0x224698fc094cf91b992d30ed00000001n satisfies LargeConstant;
const Pallas: Curve = arfCurve(P, 5n);

PureExpr

Marks an expression as side-effect free and deterministic.

import { Overridable, PureExpr } from "@kimlikdao/kdts";
import { f, g } from "./util";

const KeepConsole = true satisfies Overridable;

const x = f(100 + g(5)) + f(g(2)) satisfies PureExpr;

if (KeepConsole)
  console.log(x);

Now kdts is free to eliminate the entire initializer expression of x. If `KeepConsole=true`, kdts is free to replace x with the evaluated result in console.log(x).