conjure-js 0.0.13 → 0.0.14

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "conjure-js",
   "private": false,
-  "version": "0.0.13",
+  "version": "0.0.14",
   "type": "module",
   "repository": {
     "type": "git",

package/src/bin/version.ts

@@ -1,4 +1,4 @@
 // This file is auto-generated by scripts/gen-version.mjs
 // Do not edit manually - changes will be overwritten
 
-export const VERSION = '0.0.13'
+export const VERSION = '0.0.14'

package/src/core/assertions.ts

@@ -1,5 +1,4 @@
 import {
-  valueKeywords,
   type CljAtom,
   type CljBoolean,
   type CljCons,
@@ -15,6 +14,7 @@ import {
   type CljNamespace,
   type CljNativeFunction,
   type CljNumber,
+  type CljPending,
   type CljReduced,
   type CljRegex,
   type CljSet,
@@ -25,7 +25,8 @@ import {
   type CljVector,
   type CljVolatile,
 } from './types.ts'
-import { specialFormKeywords } from './evaluator/special-forms.ts'
+
+import { specialFormKeywords, valueKeywords } from './keywords.ts'
 
 export const isNil = (value: CljValue): boolean => value.kind === 'nil'
 export const isBoolean = (value: CljValue): value is CljBoolean =>
@@ -67,7 +68,9 @@ export const isJsValue = (value: CljValue): value is CljJsValue =>
 
 /** True for any value that can be invoked like a function (IFn). */
 export const isCallable = (value: CljValue): boolean =>
-  isAFunction(value) || isKeyword(value) || isMap(value) ||
+  isAFunction(value) ||
+  isKeyword(value) ||
+  isMap(value) ||
   (isJsValue(value) && typeof value.value === 'function')
 export const isMultiMethod = (value: CljValue): value is CljMultiMethod =>
   value.kind === 'multi-method'
@@ -207,6 +210,9 @@ export const isEqual = (a: CljValue, b: CljValue): boolean => {
 export const isNumber = (value: CljValue): value is CljNumber =>
   value.kind === 'number'
 
+export const isPending = (value: CljValue): value is CljPending =>
+  value.kind === 'pending'
+
 // Main assertion interface for the entire package
 export const is = {
   nil: isNil,
@@ -242,4 +248,5 @@ export const is = {
   cljValue: isCljValue,
   equal: isEqual,
   jsValue: isJsValue,
+  pending: isPending,
 }

package/src/core/bootstrap.ts

@@ -5,6 +5,7 @@ import { v } from './factories'
 import type { CljNamespace, CljValue, Env, EvaluationContext } from './types'
 import { ensureNamespaceInRegistry, processRequireSpec } from './registry'
 import type { NamespaceRegistry } from './registry'
+import { specialFormKeywords } from './keywords'
 
 // ---------------------------------------------------------------------------
 // wireNsCore — wires *ns*, namespace introspection fns, require, and resolve
@@ -112,8 +113,10 @@ export function wireNsCore(
         if (theVar.ns !== ns.name) return
         const isPrivate = (theVar.meta?.entries ?? []).some(
           ([k, val]) =>
-            k.kind === 'keyword' && k.name === ':private' &&
-            val.kind === 'boolean' && val.value === true
+            k.kind === 'keyword' &&
+            k.name === ':private' &&
+            val.kind === 'boolean' &&
+            val.value === true
         )
         if (!isPrivate) entries.push([v.symbol(name), theVar])
       })
@@ -195,27 +198,7 @@ export function wireNsCore(
     v.nativeFn('special-symbol?', (sym: CljValue) => {
       if (sym === undefined || !isSymbol(sym)) return v.boolean(false)
       const specials = new Set([
-        'def',
-        'if',
-        'do',
-        'let',
-        'quote',
-        'var',
-        'fn',
-        'loop',
-        'recur',
-        'throw',
-        'try',
-        'catch',
-        'finally',
-        'ns',
-        'defmacro',
-        'binding',
-        'monitor-enter',
-        'monitor-exit',
-        'new',
-        'set!',
-        '.',
+        ...Object.values(specialFormKeywords),
         'import',
       ])
       return v.boolean(specials.has(sym.name))
@@ -306,6 +289,7 @@ export function wireIdeStubs(registry: NamespaceRegistry, coreEnv: Env): void {
   )
 
   // Java class stubs — Cursive references these as bare symbols for type checks
+  // other IDE integrations may probe the env to access the capabilities of the runtime
   for (const javaClass of [
     'Class',
     'Object',

package/src/core/compiler/binding.ts

@@ -0,0 +1,164 @@
+import { is } from '../assertions.ts'
+import { assertRecurInTailPosition } from '../evaluator/recur-check.ts'
+import { v } from '../factories.ts'
+import type {
+  CljList,
+  CljValue,
+  CompiledExpr,
+  CompileEnv,
+  CompileFn,
+  SlotRef,
+} from '../types.ts'
+import { findLoopTarget } from './compile-env.ts'
+import { compileDo } from './control-flow.ts'
+
+const BINDINGS_POS = 1
+const BODY_START_POS = 2
+
+export function compileLet(
+  node: CljList,
+  compileEnv: CompileEnv | null,
+  compile: CompileFn
+): CompiledExpr | null {
+  const bindings = node.value[BINDINGS_POS]
+  // must be a vector with an even number of elements, else bail out
+  if (!is.vector(bindings) || bindings.value.length % 2 !== 0) return null
+
+  let currentCompileEnv = compileEnv
+  const slotInits: Array<[SlotRef, CompiledExpr]> = []
+
+  for (let i = 0; i < bindings.value.length; i += 2) {
+    const pattern = bindings.value[i]
+    // destructuring pattern not supported yet
+    if (!is.symbol(pattern)) return null
+    const slot: SlotRef = { value: null }
+
+    const compiledInit = compile(bindings.value[i + 1], currentCompileEnv)
+    // unsupported init form, bail out
+    if (compiledInit === null) return null
+    slotInits.push([slot, compiledInit])
+
+    currentCompileEnv = {
+      bindings: new Map([[pattern.name, slot]]),
+      outer: currentCompileEnv,
+    }
+  }
+
+  // compile the body with full env (all bindings in scope)
+  const body = node.value.slice(BODY_START_POS)
+  const compiledBody = compileDo(body, currentCompileEnv, compile)
+  // unsupported body form, bail out
+  if (compiledBody === null) return null
+
+  return (env, ctx) => {
+    // save all previous slot values (handles recursive/nested lets)
+    const prevSlotValues = slotInits.map(([slot]) => slot.value)
+
+    // evaluate inits sequentially, writing. into slots
+    for (const [slot, compiledInit] of slotInits) {
+      slot.value = compiledInit(env, ctx)
+    }
+
+    const result = compiledBody(env, ctx)
+
+    // restore prev slot values
+    slotInits.forEach(([slot], index) => {
+      slot.value = prevSlotValues[index]
+    })
+
+    return result
+  }
+}
+
+export function compileLoop(
+  node: CljList,
+  compileEnv: CompileEnv | null,
+  compile: CompileFn
+): CompiledExpr | null {
+  const bindings = node.value[BINDINGS_POS]
+  if (!is.vector(bindings) || bindings.value.length % 2 !== 0) return null
+  const body = node.value.slice(BODY_START_POS)
+  assertRecurInTailPosition(body)
+
+  let currentCompileEnv = compileEnv
+  const slotInits: Array<[SlotRef, CompiledExpr]> = []
+  const namedSlots: Array<[string, SlotRef]> = []
+
+  for (let i = 0; i < bindings.value.length; i += 2) {
+    const pattern = bindings.value[i]
+    // destructuring pattern not supported yet
+    if (!is.symbol(pattern)) return null
+    const compiledInit = compile(bindings.value[i + 1], currentCompileEnv)
+    // unsuported init, bail out
+    if (compiledInit === null) return null
+    const slot: SlotRef = { value: null }
+    slotInits.push([slot, compiledInit])
+    namedSlots.push([pattern.name, slot])
+
+    currentCompileEnv = {
+      bindings: new Map([[pattern.name, slot]]),
+      outer: currentCompileEnv,
+    }
+  }
+  const slots = slotInits.map((entry) => entry[0])
+  const recurTarget: { args: CljValue[] | null } = { args: null }
+  // map of ALL slots, outer: compileEnv, loop: { slots, recurTarget }
+  const loopCompileEnv = {
+    bindings: new Map(namedSlots),
+    outer: compileEnv,
+    loop: {
+      slots,
+      recurTarget,
+    },
+  }
+  const compiledBody = compileDo(body, loopCompileEnv, compile)
+  if (compiledBody === null) return null
+
+  return (env, ctx) => {
+    for (const [slot, compiledInit] of slotInits) {
+      slot.value = compiledInit(env, ctx)
+    }
+
+    while (true) {
+      recurTarget.args = null
+      const result = compiledBody(env, ctx)
+      if (recurTarget.args !== null) {
+        // rebind!
+        for (let i = 0; i < slots.length; i++) {
+          slots[i].value = recurTarget.args[i]
+        }
+      } else {
+        return result
+      }
+    }
+  }
+}
+
+export function compileRecur(
+  node: CljList,
+  compileEnv: CompileEnv | null,
+  compile: CompileFn
+): CompiledExpr | null {
+  const loopInfo = findLoopTarget(compileEnv)
+  // no compiler loop in scope, bail out
+  // this will fallback to a thrown CljSignal in the interpreter
+  if (loopInfo === null) return null
+  const { recurTarget, slots } = loopInfo
+  const argForms = node.value.slice(BINDINGS_POS)
+  // Arity mismatch, bail out
+  if (argForms.length !== slots.length) return null
+
+  const compiledArgs: CompiledExpr[] = []
+  for (const arg of argForms) {
+    const compiled = compile(arg, compileEnv)
+    if (compiled === null) return null
+    compiledArgs.push(compiled)
+  }
+  return (env, ctx) => {
+    // important: evaluate ALL new values before writting ANY slot
+    const newArgs = compiledArgs.map((compiledArg) => compiledArg(env, ctx))
+    recurTarget.args = newArgs
+    // return value ignored, loop checks recurTarget.args
+    return v.nil()
+  }
+}

package/src/core/compiler/callable.ts

@@ -0,0 +1,41 @@
+import { is } from '../assertions.ts'
+import { EvaluationError } from '../errors.ts'
+import { dispatchMultiMethod } from '../evaluator/dispatch.ts'
+import { maybeHydrateErrorPos } from '../positions.ts'
+import { printString } from '../printer.ts'
+import type { CljList, CompiledExpr, CompileEnv, CompileFn } from '../types.ts'
+
+export function compileCall(
+  node: CljList,
+  compileEnv: CompileEnv | null,
+  compile: CompileFn
+): CompiledExpr | null {
+  const head = node.value[0]
+  const compiledOp = compile(head, compileEnv)
+  if (compiledOp === null) return null
+  const compiledArgs: CompiledExpr[] = []
+  for (const arg of node.value.slice(1)) {
+    const compiled = compile(arg, compileEnv)
+    // Uncompilable argument, bail out
+    if (compiled === null) return null
+    compiledArgs.push(compiled)
+  }
+  return (env, ctx) => {
+    const op = compiledOp(env, ctx)
+    if (is.multiMethod(op)) {
+      const args = compiledArgs.map((c) => c!(env, ctx))
+      return dispatchMultiMethod(op, args, ctx, env)
+    }
+    if (!is.callable(op)) {
+      const name = is.symbol(head) ? head.name : printString(head)
+      throw new EvaluationError(`${name} is not callable`, { list: node, env })
+    }
+    const args = compiledArgs.map((carg) => carg!(env, ctx))
+    try {
+      return ctx.applyCallable(op, args, env)
+    } catch (ex) {
+      maybeHydrateErrorPos(ex, node)
+      throw ex
+    }
+  }
+}

package/src/core/compiler/compile-env.ts

@@ -0,0 +1,40 @@
+import type { CompileEnv, SlotRef } from '../types.ts'
+
+/**
+ * Finds a slot in the compile environment by symbol name.
+ * Returns null if the slot is not found.
+ * Slots are equivalent to local bindings in the interpreter.
+ * The difference is that slots use array indexing instead of recursive name lookup.
+ * Slots are allocated at compile time, which reduces object allocation overhead.
+ * The values are swapped temporarily duration evaluation of compiled code.
+ */
+export function findSlot(
+  symbolName: string,
+  compileEnv: CompileEnv | null
+): SlotRef | null {
+  let current: CompileEnv | null = compileEnv
+  while (current) {
+    const slot = current.bindings.get(symbolName)
+    if (slot !== undefined) return slot
+    current = current.outer
+  }
+  return null
+}
+
+/**
+ * Finds the closest loop target in the compile environment.
+ * Used for loop/recur compilation, this eliminates the overhead of throwing a RecurSignal,
+ * The strategy used by the evaluator. Instead, a loop start marks a target in the compileEnv
+ * the recur finds the nearest target and updates the bindings.
+ * The compiled loop will observe the bindings after evaluating the body,
+ * while they are not null, the loop will continue.
+ */
+export function findLoopTarget(compileEnv: CompileEnv | null) {
+  if (compileEnv === null) return null
+  let current: CompileEnv | null = compileEnv
+  while (current) {
+    if (current.loop) return current.loop
+    current = current.outer
+  }
+  return null
+}

package/src/core/compiler/control-flow.ts

@@ -0,0 +1,79 @@
+import { is } from '../assertions.ts'
+import { v } from '../factories.ts'
+import type {
+  CljList,
+  CljValue,
+  CompiledExpr,
+  CompileEnv,
+  CompileFn,
+} from '../types.ts'
+
+const IF_TEST_POS = 1
+const IF_THEN_POS = 2
+const IF_ELSE_POS = 3
+
+/**
+ * Compiles an if expression to a js closure.
+ * Short-circuits: only evaluates taken branch after test result.
+ * Returns null if test, then, or else cannot be compiled.
+ * Falling back to the interpreter.
+ *
+ * (if test then else?)
+ */
+export function compileIf(
+  node: CljList,
+  compileEnv: CompileEnv | null,
+  compile: CompileFn
+): CompiledExpr | null {
+  const compiledTest = compile(node.value[IF_TEST_POS], compileEnv)
+  const compiledThen = compile(node.value[IF_THEN_POS], compileEnv)
+  const hasElse = node.value.length > IF_ELSE_POS
+  const compiledElse = hasElse
+    ? compile(node.value[IF_ELSE_POS], compileEnv)
+    : null
+  if (
+    compiledTest === null ||
+    compiledThen === null ||
+    (hasElse && compiledElse === null)
+  ) {
+    return null
+  }
+
+  return (env, ctx) => {
+    if (is.truthy(compiledTest(env, ctx))) {
+      return compiledThen(env, ctx)
+    } else {
+      return compiledElse ? compiledElse(env, ctx) : v.nil()
+    }
+  }
+}
+
+/**
+ * Compiles a do expression to a js closure.
+ * Evaluates all forms in sequence, returns last result.
+ * Returns null if any form cannot be compiled.
+ * Falling back to the interpreter.
+ *
+ * (do e1 e2 ... eN)
+ */
+export function compileDo(
+  node: CljValue[],
+  compileEnv: CompileEnv | null,
+  compile: CompileFn
+): CompiledExpr | null {
+  const compiledForms: CompiledExpr[] = []
+  for (const form of node) {
+    const compiled = compile(form, compileEnv)
+    // Can't compile a form, so bail out
+    if (compiled === null) return null
+    compiledForms.push(compiled)
+  }
+
+  return (env, ctx) => {
+    let result: CljValue = v.nil()
+    for (const compiled of compiledForms) {
+      result = compiled(env, ctx)
+    }
+    return result
+  }
+}

package/src/core/compiler/index.ts

@@ -0,0 +1,121 @@
+/**
+ * Compiler — Incremental Implementation
+ *
+ * Transforms AST nodes into compiled closures that eliminate
+ * interpreter dispatch overhead. Supports:
+ * - Phase 1: Literals, symbols
+ * - Phase 2: if, do
+ * - Phase 3: let with slot indexing
+ * - Phase 4: fn with compile-once caching
+ * - Phase 5: loop/recur → while
+ *
+ * Returns null for unsupported forms (fallback to interpreter).
+ * See ./evaluate.ts:evaluateWithContext for the entry point.
+ */
+import { is } from '../assertions.ts'
+import { lookup } from '../env.ts'
+import { specialFormKeywords, valueKeywords } from '../keywords.ts'
+import {
+  type CljList,
+  type CljSymbol,
+  type CljValue,
+  type CompiledExpr,
+  type CompileEnv,
+  type CompileFn,
+} from '../types.ts'
+import { compileLet, compileLoop, compileRecur } from './binding.ts'
+import { compileCall } from './callable.ts'
+import { findSlot } from './compile-env.ts'
+import { compileDo, compileIf } from './control-flow.ts'
+
+/**
+ * Export the compiler functions for use in the evaluator
+ * Ideally external consumers should only use the compile function,
+ * not it's children!
+ */
+export { compileDo, compileIf, compileLet, compileLoop, compileRecur }
+
+function compileList(
+  node: CljList,
+  compileEnv: CompileEnv | null,
+  compile: CompileFn
+): CompiledExpr | null {
+  if (node.value.length === 0) return () => node
+  const head = node.value[0]
+  // First check supported special forms
+  if (is.symbol(head)) {
+    switch (head.name) {
+      case specialFormKeywords.if:
+        return compileIf(node, compileEnv, compile)
+      case specialFormKeywords.do:
+        return compileDo(node.value.slice(1), compileEnv, compile)
+      case specialFormKeywords.let:
+        return compileLet(node, compileEnv, compile)
+      case specialFormKeywords.loop:
+        return compileLoop(node, compileEnv, compile)
+      case specialFormKeywords.recur:
+        return compileRecur(node, compileEnv, compile)
+    }
+  }
+
+  if (!is.specialForm(head)) {
+    // Otherwise, compile as a callable
+    return compileCall(node, compileEnv, compile)
+  }
+
+  // Unsupported form, bail out
+  return null
+}
+
+/**
+ * Compiles a symbol to a compiled expression.
+ * It will look for the symbol as a slot in the compile environment,
+ * if found, it will return a closure that directly accesses the slot value.
+ * If not found, it will return a closure that looks up the symbol
+ * in the local evaluation environment.
+ */
+function compileSymbol(
+  node: CljSymbol,
+  compileEnv: CompileEnv | null
+): CompiledExpr | null {
+  const symbolName = node.name
+  const slashIdx = symbolName.indexOf('/')
+  if (slashIdx > 0 && slashIdx < symbolName.length - 1) {
+    // qualified symbol not supported yet
+    return null
+  }
+  const slot = findSlot(symbolName, compileEnv)
+  if (slot !== null) {
+    return (_env, _ctx) => slot.value! // direct slot access, no lookup
+  }
+  // Regular lookup
+  return (env, _ctx) => lookup(symbolName, env)
+}
+
+/**
+ * A pure function that compiles a node to a compiled expression.
+ * The goal is to remove the overhead of interpreting the AST structure.
+ * Non-supported nodes return null and fallback to the evaluator.
+ */
+export function compile(
+  node: CljValue,
+  compileEnv: CompileEnv | null = null
+): CompiledExpr | null {
+  switch (node.kind) {
+    // Self evaluating forms compile to constant closures
+    case valueKeywords.number:
+    case valueKeywords.string:
+    case valueKeywords.keyword:
+    case valueKeywords.nil:
+    case valueKeywords.boolean:
+    case valueKeywords.regex:
+      return () => node
+    case valueKeywords.symbol: {
+      return compileSymbol(node, compileEnv)
+    }
+    case valueKeywords.list: {
+      return compileList(node, compileEnv, compile)
+    }
+  }
+  return null
+}

package/src/core/env.ts

@@ -43,9 +43,9 @@ export function lookup(name: string, env: Env): CljValue {
     // Local bindings are stored as plain values — do NOT auto-deref.
     // A var stored in a local binding (e.g. from `(var foo)`) is a first-class value.
     if (raw !== undefined) return raw
-    const v = current.ns?.vars.get(name)
+    const theVar = current.ns?.vars.get(name)
     // Namespace vars are always auto-deref'd: `foo` resolves to the var's current value.
-    if (v !== undefined) return derefValue(v)
+    if (theVar !== undefined) return derefValue(theVar)
     current = current.outer
   }
   throw new EvaluationError(`Symbol ${name} not found`, { name })
@@ -56,8 +56,8 @@ export function tryLookup(name: string, env: Env): CljValue | undefined {
   while (current) {
     const raw = current.bindings.get(name)
     if (raw !== undefined) return raw
-    const v = current.ns?.vars.get(name)
-    if (v !== undefined) return derefValue(v)
+    const theVar = current.ns?.vars.get(name)
+    if (theVar !== undefined) return derefValue(theVar)
     current = current.outer
   }
   return undefined

package/src/core/errors.ts

@@ -45,3 +45,4 @@ export class CljThrownSignal {
     this.value = value
   }
 }
+

package/src/core/evaluator/apply.ts

@@ -1,6 +1,7 @@
 import { is } from '../assertions'
 import { EvaluationError } from '../errors'
 import { cljNil } from '../factories'
+import { valueKeywords } from '../keywords'
 import { printString } from '../printer'
 import type {
   CljFunction,
@@ -19,14 +20,14 @@ export function applyFunctionWithContext(
   ctx: EvaluationContext,
   callEnv: Env
 ): CljValue {
-  if (fn.kind === 'native-function') {
+  if (fn.kind === valueKeywords.nativeFunction) {
     // New path, native fns receive evaluation context as first argument
     if (fn.fnWithContext) {
       return fn.fnWithContext(ctx, callEnv, ...args)
     }
     return fn.fn(...args)
   }
-  if (fn.kind === 'function') {
+  if (fn.kind === valueKeywords.function) {
     const arity = resolveArity(fn.arities, args.length)
     let currentArgs = args
     while (true) {
@@ -39,6 +40,9 @@ export function applyFunctionWithContext(
         callEnv
       )
       try {
+        if (arity.compiledBody) {
+          return arity.compiledBody(localEnv, ctx)
+        }
         return ctx.evaluateForms(arity.body, localEnv)
       } catch (e) {
         if (e instanceof RecurSignal) {
@@ -91,7 +95,7 @@ export function applyCallableWithContext(
     return applyFunctionWithContext(fn, args, ctx, callEnv)
   }
   if (is.jsValue(fn)) {
-    if (typeof fn.value !== 'function') {
+    if (typeof fn.value !== valueKeywords.function) {
       throw new EvaluationError(
         `js-value is not callable: ${typeof fn.value}`,
         { fn, args }

package/src/core/evaluator/arity.ts

@@ -12,6 +12,8 @@ import type {
 } from '../types'
 import { destructureBindings } from './destructure'
 
+const REST_SYMBOL = '&'
+
 export class RecurSignal {
   args: CljValue[]
   constructor(args: CljValue[]) {
@@ -23,24 +25,32 @@ export function parseParamVector(
   args: CljVector,
   env: Env
 ): { params: DestructurePattern[]; restParam: DestructurePattern | null } {
-  const ampIdx = args.value.findIndex((a) => is.symbol(a) && a.name === '&')
+  const ampIdx = args.value.findIndex(
+    (a) => is.symbol(a) && a.name === REST_SYMBOL
+  )
   let params: DestructurePattern[] = []
   let restParam: DestructurePattern | null = null
   if (ampIdx === -1) {
     params = args.value as DestructurePattern[]
   } else {
     const ampsCount = args.value.filter(
-      (a) => is.symbol(a) && a.name === '&'
+      (a) => is.symbol(a) && a.name === REST_SYMBOL
     ).length
     if (ampsCount > 1) {
-      throw new EvaluationError('& can only appear once', { args, env })
-    }
-    if (ampIdx !== args.value.length - 2) {
-      throw new EvaluationError('& must be second-to-last argument', {
+      throw new EvaluationError(`${REST_SYMBOL} can only appear once`, {
         args,
         env,
       })
     }
+    if (ampIdx !== args.value.length - 2) {
+      throw new EvaluationError(
+        `${REST_SYMBOL} must be second-to-last argument`,
+        {
+          args,
+          env,
+        }
+      )
+    }
     params = args.value.slice(0, ampIdx) as DestructurePattern[]
     restParam = args.value[ampIdx + 1] as DestructurePattern
   }