conjure-js 0.0.12 → 0.0.13

package/src/core/evaluator/form-parsers.ts

@@ -0,0 +1,178 @@
+/**
+ * Shared structural parsers for special forms.
+ *
+ * These helpers are pure data transformations — no evaluation, no side effects.
+ * Both the sync evaluator (special-forms.ts) and the async evaluator
+ * (async-evaluator.ts) import from here so the logic lives in exactly one place.
+ *
+ * matchesDiscriminator also lives here because it is the same algorithm in both
+ * paths — only the EvaluationContext it receives differs (the real ctx in sync,
+ * asyncCtx.syncCtx in async, which is correct: discriminator matching is
+ * inherently synchronous).
+ */
+
+import { is } from '../assertions'
+import { EvaluationError } from '../errors'
+import type {
+  CljFunction,
+  CljList,
+  CljNativeFunction,
+  CljValue,
+  CljVector,
+  Env,
+  EvaluationContext,
+} from '../types'
+
+// ---- let / loop bindings ----
+
+/**
+ * Validates that a binding vector is well-formed: must be a vector with an
+ * even number of forms. Used by let and loop handlers in both the sync and
+ * async evaluators so the error messages are consistent.
+ *
+ * @param formName  Display name for the error message, e.g. 'let' or 'loop'.
+ */
+export function validateBindingVector(
+  vec: CljValue,
+  formName: string,
+  env: Env
+): asserts vec is CljVector {
+  if (!is.vector(vec)) {
+    throw new EvaluationError(`${formName} bindings must be a vector`, {
+      bindings: vec,
+      env,
+    })
+  }
+  if (vec.value.length % 2 !== 0) {
+    throw new EvaluationError(
+      `${formName} bindings must have an even number of forms`,
+      { bindings: vec, env }
+    )
+  }
+}
+
+// ---- try ----
+
+export type CatchClause = {
+  discriminator: CljValue
+  binding: string
+  body: CljValue[]
+}
+
+export type TryStructure = {
+  bodyForms: CljValue[]
+  catchClauses: CatchClause[]
+  finallyForms: CljValue[] | null
+}
+
+/**
+ * Splits a (try ...) list into body forms, catch clauses, and an optional
+ * finally clause. Validates that catch has a discriminator + binding symbol and
+ * that finally (if present) is the last form.
+ */
+export function parseTryStructure(list: CljList, env: Env): TryStructure {
+  const forms = list.value.slice(1)
+  const bodyForms: CljValue[] = []
+  const catchClauses: CatchClause[] = []
+  let finallyForms: CljValue[] | null = null
+
+  for (let i = 0; i < forms.length; i++) {
+    const form = forms[i]
+    if (is.list(form) && form.value.length > 0 && is.symbol(form.value[0])) {
+      const head = form.value[0].name
+
+      if (head === 'catch') {
+        if (form.value.length < 3) {
+          throw new EvaluationError(
+            'catch requires a discriminator and a binding symbol',
+            { form, env }
+          )
+        }
+        const discriminator = form.value[1]
+        const bindingSym = form.value[2]
+        if (!is.symbol(bindingSym)) {
+          throw new EvaluationError('catch binding must be a symbol', {
+            form,
+            env,
+          })
+        }
+        catchClauses.push({
+          discriminator,
+          binding: bindingSym.name,
+          body: form.value.slice(3),
+        })
+        continue
+      }
+
+      if (head === 'finally') {
+        if (i !== forms.length - 1) {
+          throw new EvaluationError(
+            'finally clause must be the last in try expression',
+            { form, env }
+          )
+        }
+        finallyForms = form.value.slice(1)
+        continue
+      }
+    }
+    bodyForms.push(form)
+  }
+
+  return { bodyForms, catchClauses, finallyForms }
+}
+
+/**
+ * Determines whether a catch clause's discriminator matches a thrown value.
+ *
+ * Rules (same as Clojure-on-JVM, adapted for JS runtime):
+ * - Discriminator evaluates to a symbol → catch-all (JVM class names fall here)
+ * - `:default` keyword → catch-all
+ * - Any other keyword → matches if thrown is a map with a :type entry equal to
+ *   the discriminator keyword
+ * - A callable function → call it with the thrown value; truthy = match
+ * - Anything else → error
+ *
+ * @param ctx  Use the real EvaluationContext in sync paths; use asyncCtx.syncCtx
+ *             in async paths. Discriminator matching is always synchronous.
+ */
+export function matchesDiscriminator(
+  discriminator: CljValue,
+  thrown: CljValue,
+  env: Env,
+  ctx: EvaluationContext
+): boolean {
+  let disc: CljValue
+  try {
+    disc = ctx.evaluate(discriminator, env)
+  } catch {
+    // Discriminator failed to evaluate (e.g. unresolvable Java class name like
+    // java.lang.Throwable). Treat as catch-all — we're not on the JVM.
+    return true
+  }
+  // A symbol that evaluated to itself (shouldn't happen, but guard anyway)
+  if (disc.kind === 'symbol') return true
+
+  if (is.keyword(disc)) {
+    if (disc.name === ':default') return true
+    if (!is.map(thrown)) return false
+    const typeEntry = thrown.entries.find(
+      ([k]) => is.keyword(k) && k.name === ':type'
+    )
+    if (!typeEntry) return false
+    return is.equal(typeEntry[1], disc)
+  }
+
+  if (is.aFunction(disc)) {
+    const result = ctx.applyFunction(
+      disc as CljFunction | CljNativeFunction,
+      [thrown],
+      env
+    )
+    return is.truthy(result)
+  }
+
+  throw new EvaluationError(
+    'catch discriminator must be a keyword or a predicate function',
+    { discriminator: disc, env }
+  )
+}

package/src/core/evaluator/index.ts

@@ -39,12 +39,19 @@ export function createEvaluationContext(): EvaluationContext {
       applyMacroWithContext(macro, rawArgs, ctx),
     expandAll: (form: CljValue, env: Env) =>
       macroExpandAllWithContext(form, env, ctx),
+    resolveNs: (_name: string) => null as null,
+    // IO defaults — overwritten by buildSessionFacade with session-specific channels.
+    io: {
+      stdout: (text: string) => console.log(text),
+      stderr: (text: string) => console.error(text),
+    },
   }
   return ctx
 }
 
 /** Public API, this is the only place where we create a new evaluation context
  * All inner evaluations will use the same context
+ * @deprecated use session.applyFunction instead
  */
 export function applyFunction(
   fn: CljFunction | CljNativeFunction,
@@ -53,15 +60,6 @@ export function applyFunction(
 ): CljValue {
   return createEvaluationContext().applyFunction(fn, args, callEnv)
 }
-export function applyMacro(macro: CljMacro, rawArgs: CljValue[]): CljValue {
-  return createEvaluationContext().applyMacro(macro, rawArgs)
-}
-export function evaluate(expr: CljValue, env: Env): CljValue {
-  return createEvaluationContext().evaluate(expr, env)
-}
-export function evaluateForms(forms: CljValue[], env: Env): CljValue {
-  return createEvaluationContext().evaluateForms(forms, env)
-}
 
 export function evaluateWithMeasurements(
   expr: CljValue,

package/src/core/evaluator/js-interop.ts

@@ -0,0 +1,189 @@
+import { is } from '../assertions'
+import { EvaluationError } from '../errors'
+import { cljBoolean, cljJsValue, cljNil, cljNumber, cljString } from '../factories'
+import type { CljList, CljValue, Env, EvaluationContext } from '../types'
+
+// ---------------------------------------------------------------------------
+// JS ↔ Clojure conversion
+// ---------------------------------------------------------------------------
+
+/**
+ * Convert a raw JS value to a CljValue.
+ * - null → CljNil (intentional absence)
+ * - undefined → CljJsValue(undefined) (property does not exist / unset — distinct from null)
+ * - primitives convert; everything else boxes.
+ */
+export function jsToClj(raw: unknown): CljValue {
+  if (raw === null) return cljNil()
+  if (raw === undefined) return cljJsValue(undefined)
+  if (typeof raw === 'number') return cljNumber(raw)
+  if (typeof raw === 'string') return cljString(raw)
+  if (typeof raw === 'boolean') return cljBoolean(raw)
+  return cljJsValue(raw)
+}
+
+/**
+ * Convert a CljValue map key to a JS object key string.
+ * Only primitive keys are allowed. Rich keys (vectors, maps, sets, etc.)
+ * have no meaningful JS representation and must be reduced to a primitive first.
+ */
+function mapKeyToString(key: CljValue): string {
+  if (key.kind === 'string') return key.value
+  if (key.kind === 'keyword') return key.name.slice(1) // strip leading ':'
+  if (key.kind === 'number') return String(key.value)
+  if (key.kind === 'boolean') return String(key.value)
+  throw new EvaluationError(
+    `cljToJs: map key must be a string, keyword, number, or boolean — ` +
+    `got ${key.kind} (rich keys are not allowed as JS object keys; reduce to a primitive first)`,
+    { key }
+  )
+}
+
+/**
+ * Convert a CljValue to a raw JS value for crossing the interop boundary.
+ * Called on each argument passed to `.` and `js/new`.
+ */
+export function cljToJs(val: CljValue, ctx: EvaluationContext, callEnv: Env): unknown {
+  switch (val.kind) {
+    case 'js-value': return val.value
+    case 'number': return val.value
+    case 'string': return val.value
+    case 'boolean': return val.value
+    case 'nil': return null
+    case 'keyword': return val.name.slice(1) // strip leading ':'
+    case 'function':
+    case 'native-function': {
+      const fn = val
+      // Wrap so JS can call it: converts args JS→Clj on entry, result Clj→JS on exit.
+      return (...jsArgs: unknown[]) => {
+        const cljArgs = jsArgs.map(jsToClj)
+        const result = ctx.applyCallable(fn, cljArgs, callEnv)
+        return cljToJs(result, ctx, callEnv)
+      }
+    }
+    case 'list':
+    case 'vector':
+      return val.value.map((v) => cljToJs(v, ctx, callEnv))
+    case 'map': {
+      const obj: Record<string, unknown> = {}
+      for (const [key, value] of val.entries) {
+        obj[mapKeyToString(key)] = cljToJs(value, ctx, callEnv)
+      }
+      return obj
+    }
+    default:
+      throw new EvaluationError(
+        `cannot convert ${val.kind} to JS value — no coercion defined`,
+        { val }
+      )
+  }
+}
+
+// ---------------------------------------------------------------------------
+// (. obj prop) / (. obj method arg1 arg2 ...)
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract the raw JS value from a target CljValue for use in `.`.
+ * Strings, numbers, and booleans are auto-boxed (JS auto-promotes them for
+ * property/method access). Nil and all other Clojure types are rejected.
+ */
+function extractRawTarget(target: CljValue): unknown {
+  switch (target.kind) {
+    case 'js-value': return target.value
+    case 'string':
+    case 'number':
+    case 'boolean': return target.value
+    default:
+      throw new EvaluationError(
+        `cannot use . on ${target.kind}`,
+        { target }
+      )
+  }
+}
+
+export function evaluateDot(
+  list: CljList,
+  env: Env,
+  ctx: EvaluationContext
+): CljValue {
+  if (list.value.length < 3) {
+    throw new EvaluationError(
+      '. requires at least 2 arguments: (. obj prop)',
+      { list }
+    )
+  }
+
+  const target = ctx.evaluate(list.value[1], env)
+  const rawTarget = extractRawTarget(target)
+
+  if (rawTarget === null || rawTarget === undefined) {
+    const label = rawTarget === null ? 'null' : 'undefined'
+    throw new EvaluationError(
+      `cannot use . on ${label} js value — check for nil/undefined before accessing properties`,
+      { target }
+    )
+  }
+
+  const propForm = list.value[2]
+  if (!is.symbol(propForm)) {
+    throw new EvaluationError(
+      `. expects a symbol for property name, got: ${propForm.kind}`,
+      { propForm }
+    )
+  }
+
+  const propName = propForm.name
+  const rawObj = rawTarget as Record<string, unknown>
+
+  if (list.value.length === 3) {
+    // Property access — zero extra args.
+    // Functions are bound to their object so that ((. obj method)) works correctly.
+    const rawProp = rawObj[propName]
+    if (typeof rawProp === 'function') {
+      return cljJsValue((rawProp as (...a: unknown[]) => unknown).bind(rawObj))
+    }
+    return jsToClj(rawProp)
+  }
+
+  // Method call — one or more extra args
+  const method = rawObj[propName]
+  if (typeof method !== 'function') {
+    throw new EvaluationError(
+      `method '${propName}' is not callable on ${String(rawObj)}`,
+      { propName, rawObj }
+    )
+  }
+
+  const cljArgs = list.value.slice(3).map((a) => ctx.evaluate(a, env))
+  const jsArgs = cljArgs.map((a) => cljToJs(a, ctx, env))
+  const rawResult = (method as (...args: unknown[]) => unknown).apply(rawObj, jsArgs)
+  return jsToClj(rawResult)
+}
+
+// ---------------------------------------------------------------------------
+// (js/new ClassName arg1 arg2 ...)
+// ---------------------------------------------------------------------------
+
+export function evaluateNew(
+  list: CljList,
+  env: Env,
+  ctx: EvaluationContext
+): CljValue {
+  if (list.value.length < 2) {
+    throw new EvaluationError('js/new requires a constructor argument', { list })
+  }
+
+  const cls = ctx.evaluate(list.value[1], env)
+  if (!is.jsValue(cls) || typeof cls.value !== 'function') {
+    throw new EvaluationError(
+      `js/new: expected js-value constructor, got ${cls.kind}`,
+      { cls }
+    )
+  }
+
+  const cljArgs = list.value.slice(2).map((a) => ctx.evaluate(a, env))
+  const jsArgs = cljArgs.map((a) => cljToJs(a, ctx, env))
+  const ctor = cls.value as new (...args: unknown[]) => unknown
+  return cljJsValue(new ctor(...jsArgs))
+}

package/src/core/evaluator/quasiquote.ts

@@ -1,6 +1,7 @@
-import { isList, isSymbol, isVector } from '../assertions'
+import { is } from '../assertions'
 import { EvaluationError } from '../errors'
 import { cljList, cljMap, cljVector } from '../factories'
+import { toSeq } from '../transformations'
 import { makeGensym } from '../gensym'
 import {
   type CljValue,
@@ -19,11 +20,11 @@ export function evaluateQuasiquote(
     case valueKeywords.vector:
     case valueKeywords.list: {
       // Handle unquote
-      const isAList = isList(form)
+      const isAList = is.list(form)
       if (
         isAList &&
         form.value.length === 2 &&
-        isSymbol(form.value[0]) &&
+        is.symbol(form.value[0]) &&
         form.value[0].name === 'unquote'
       ) {
         return ctx.evaluate(form.value[1], env)
@@ -34,19 +35,24 @@ export function evaluateQuasiquote(
       for (const elem of form.value) {
         // Handle unquote splicing
         if (
-          isList(elem) &&
+          is.list(elem) &&
           elem.value.length === 2 &&
-          isSymbol(elem.value[0]) &&
+          is.symbol(elem.value[0]) &&
           elem.value[0].name === 'unquote-splicing'
         ) {
           const toSplice = ctx.evaluate(elem.value[1], env)
-          if (!isList(toSplice) && !isVector(toSplice)) {
+          if (is.list(toSplice) || is.vector(toSplice)) {
+            elements.push(...toSplice.value)
+          } else if (is.lazySeq(toSplice) || is.cons(toSplice)) {
+            elements.push(...toSeq(toSplice))
+          } else if (is.nil(toSplice)) {
+            // nil splices as empty — nothing to push
+          } else {
             throw new EvaluationError(
-              'Unquote-splicing must evaluate to a list or vector',
+              'Unquote-splicing must evaluate to a seqable',
               { elem, env }
             )
           }
-          elements.push(...toSplice.value)
           continue
         }
         // Otherwise, recursively evaluate the quasiquote

package/src/core/evaluator/recur-check.ts

@@ -1,4 +1,4 @@
-import { isList, isSymbol, isVector } from '../assertions'
+import { is } from '../assertions'
 import { EvaluationError } from '../errors'
 import type { CljValue } from '../types'
 import { specialFormKeywords } from './special-forms'
@@ -28,9 +28,9 @@ export function assertRecurInTailPosition(body: CljValue[]): void {
 
 function isRecurForm(form: CljValue): boolean {
   return (
-    isList(form) &&
+    is.list(form) &&
     form.value.length >= 1 &&
-    isSymbol(form.value[0]) &&
+    is.symbol(form.value[0]) &&
     form.value[0].name === specialFormKeywords.recur
   )
 }
@@ -44,7 +44,7 @@ function validateForms(forms: CljValue[], inTail: boolean): void {
 
 /** Walk a single form; `inTail` = whether a direct recur here is valid. */
 function validateForm(form: CljValue, inTail: boolean): void {
-  if (!isList(form)) return
+  if (!is.list(form)) return
 
   if (isRecurForm(form)) {
     if (!inTail) {
@@ -57,7 +57,7 @@ function validateForm(form: CljValue, inTail: boolean): void {
 
   const first = form.value[0]
 
-  if (!isSymbol(first)) {
+  if (!is.symbol(first)) {
     // Anonymous fn call etc. — all sub-forms are non-tail
     for (const sub of form.value) validateForm(sub, false)
     return
@@ -92,7 +92,7 @@ function validateForm(form: CljValue, inTail: boolean): void {
   // `let`: binding values are non-tail; last body form inherits inTail
   if (name === specialFormKeywords.let) {
     const bindings = form.value[1]
-    if (isVector(bindings)) {
+    if (is.vector(bindings)) {
       for (let i = 1; i < bindings.value.length; i += 2) {
         validateForm(bindings.value[i], false)
       }