conjure-js 0.0.12 → 0.0.13

package/src/core/stdlib/async-fns.ts

@@ -0,0 +1,132 @@
+/**
+ * Async stdlib functions: then, catch*, pending?, promise-of
+ * EXPERIMENTAL — part of CljPending support. Deleteable.
+ * To revert: delete this file and remove the import from core-module.ts.
+ */
+
+import { v } from '../factories'
+import { CljThrownSignal, EvaluationError } from '../errors'
+import { is } from '../assertions'
+import { printString } from '../printer'
+import { toSeq } from '../transformations'
+import type { EvaluationContext, CljValue, Env } from '../types'
+
+export const asyncFunctions: Record<string, CljValue> = {
+  // (then val f) — apply f when resolved, or immediately if val is not pending
+  then: v
+    .nativeFnCtx(
+      'then',
+      (ctx: EvaluationContext, callEnv: Env, val: CljValue, f: CljValue) => {
+        if (!is.callable(f)) {
+          throw new EvaluationError(
+            `${printString(f)} is not a callable value`,
+            { fn: f, args: [] }
+          )
+        }
+        if (val.kind !== 'pending') {
+          return ctx.applyCallable(f, [val], callEnv)
+        }
+        const promise = val.promise.then((resolved) => {
+          try {
+            const result = ctx.applyCallable(f, [resolved], callEnv)
+            // Unwrap nested CljPending for transparent chaining
+            return result.kind === 'pending' ? result.promise : result
+          } catch (e) {
+            return Promise.reject(e)
+          }
+        })
+        return v.pending(promise)
+      }
+    )
+    .doc(
+      'Applies f to the resolved value of a pending, or to val directly if not pending.',
+      [['val', 'f']]
+    ),
+
+  // (catch* val f) — handle rejection; named catch* to avoid collision with catch special form
+  'catch*': v
+    .nativeFnCtx(
+      'catch*',
+      (ctx: EvaluationContext, callEnv: Env, val: CljValue, f: CljValue) => {
+        if (!is.callable(f)) {
+          throw new EvaluationError(
+            `${printString(f)} is not a callable value`,
+            { fn: f, args: [] }
+          )
+        }
+        if (val.kind !== 'pending') return val // not pending — no rejection possible
+        const promise = val.promise.catch((err) => {
+          // Normalize the thrown value to a CljValue map
+          let errVal: CljValue
+          if (err instanceof CljThrownSignal) {
+            // (throw ...) inside async: pass the thrown value directly
+            errVal = err.value
+          } else {
+            errVal = {
+              kind: 'map',
+              entries: [
+                [
+                  { kind: 'keyword', name: ':type' },
+                  { kind: 'keyword', name: ':error/js' },
+                ],
+                [
+                  { kind: 'keyword', name: ':message' },
+                  {
+                    kind: 'string',
+                    value: err instanceof Error ? err.message : String(err),
+                  },
+                ],
+              ],
+            }
+          }
+          try {
+            const result = ctx.applyCallable(f, [errVal], callEnv)
+            return result.kind === 'pending' ? result.promise : result
+          } catch (e) {
+            return Promise.reject(e)
+          }
+        })
+        return v.pending(promise)
+      }
+    )
+    .doc(
+      'Handles rejection of a pending value by calling f with the thrown value or an error map.',
+      [['val', 'f']]
+    ),
+
+  // (pending? x) → boolean
+  'pending?': v
+    .nativeFn('pending?', (val: CljValue) => {
+      return v.boolean(val.kind === 'pending')
+    })
+    .doc('Returns true if val is a pending (async) value.', [['val']]),
+
+  // (promise-of val) → CljPending that resolves immediately with val
+  // Primarily for testing / development before host JS interop is built.
+  'promise-of': v
+    .nativeFn('promise-of', (val: CljValue) => {
+      return v.pending(Promise.resolve(val))
+    })
+    .doc(
+      'Wraps val in an immediately-resolving pending value. Useful for testing async composition.',
+      [['val']]
+    ),
+
+  // (all pendings) → CljPending of a vector of all resolved values.
+  // Accepts any seqable (vector, list, lazy-seq, cons, nil); non-pending items resolve immediately.
+  // If any input rejects, the result pending rejects with that error.
+  all: v
+    .nativeFn('all', (val: CljValue) => {
+      const items: CljValue[] = val.kind === 'nil' ? [] : toSeq(val)
+      const promises = items.map((item) =>
+        item.kind === 'pending' ? item.promise : Promise.resolve(item)
+      )
+      return v.pending(
+        Promise.all(promises).then((results) => v.vector(results))
+      )
+    })
+    .doc(
+      'Returns a pending that resolves with a vector of all results when every input resolves.',
+      [['pendings']]
+    ),
+}

package/src/core/stdlib/atoms.ts

@@ -1,76 +1,311 @@
-import { isAtom, isAFunction, isReduced, isVolatile } from '../assertions'
+import { is } from '../assertions'
 import { EvaluationError } from '../errors'
-import {
-  cljAtom,
-  cljBoolean,
-  cljNativeFunctionWithContext,
-  cljNativeFunction,
-  withDoc,
-} from '../factories'
-import type { CljValue, Env } from '../types'
+import { v } from '../factories'
+import { printString } from '../printer'
+import { realizeDelay } from '../transformations'
+import type {
+  CljAtom,
+  CljFunction,
+  CljNativeFunction,
+  CljValue,
+  Env,
+} from '../types'
+
+function validateAtom(
+  a: CljAtom,
+  newVal: CljValue,
+  ctx: import('../types').EvaluationContext,
+  callEnv: Env
+) {
+  if (a.validator && is.aFunction(a.validator)) {
+    const result = ctx.applyFunction(a.validator, [newVal], callEnv)
+    if (is.falsy(result)) {
+      throw new EvaluationError('Invalid reference state', { newVal })
+    }
+  }
+}
+
+function notifyWatches(a: CljAtom, oldVal: CljValue, newVal: CljValue) {
+  if (a.watches) {
+    for (const [, { key, fn, ctx, callEnv }] of a.watches) {
+      ctx.applyFunction(
+        fn as CljFunction | CljNativeFunction,
+        [key, { kind: 'atom', value: newVal } as CljValue, oldVal, newVal],
+        callEnv
+      )
+    }
+  }
+}
 
 export const atomFunctions: Record<string, CljValue> = {
-  atom: withDoc(
-    cljNativeFunction('atom', (value: CljValue) => {
-      return cljAtom(value)
-    }),
-    'Returns a new atom holding the given value.',
-    [['value']]
-  ),
+  atom: v
+    .nativeFn('atom', function atom(value: CljValue) {
+      return v.atom(value)
+    })
+    .doc('Returns a new atom holding the given value.', [['value']]),
 
-  deref: withDoc(
-    cljNativeFunction('deref', (value: CljValue) => {
-      if (isAtom(value)) return value.value
-      if (isVolatile(value)) return value.value
-      if (isReduced(value)) return value.value
-      throw EvaluationError.atArg(`deref expects an atom, volatile, or reduced value, got ${value.kind}`, { value }, 0)
-    }),
-    'Returns the wrapped value from an atom, volatile, or reduced value.',
-    [['value']]
-  ),
+  deref: v
+    .nativeFn('deref', function deref(value: CljValue) {
+      if (is.atom(value)) return value.value
+      if (is.volatile(value)) return value.value
+      if (is.reduced(value)) return value.value
+      if (is.delay(value)) return realizeDelay(value)
+      // --- ASYNC (experimental) ---
+      if (value.kind === 'pending') {
+        throw EvaluationError.atArg(
+          '@ on a pending value requires an (async ...) context. Use (async @x) or compose with then/catch.',
+          { value },
+          0
+        )
+      }
+      // --- END ASYNC ---
+      throw EvaluationError.atArg(
+        `deref expects an atom, volatile, reduced, or delay value, got ${value.kind}`,
+        { value },
+        0
+      )
+    })
+    .doc(
+      'Returns the wrapped value from an atom, volatile, reduced, or delay value.',
+      [['value']]
+    ),
 
-  'swap!': withDoc(
-    cljNativeFunctionWithContext(
+  'swap!': v
+    .nativeFnCtx(
       'swap!',
-      (
+      function swap(
         ctx,
         callEnv: Env,
         atomVal: CljValue,
         fn: CljValue,
         ...extraArgs: CljValue[]
-      ) => {
-        if (!isAtom(atomVal)) {
-          throw EvaluationError.atArg(`swap! expects an atom as its first argument, got ${atomVal.kind}`, { atomVal }, 0)
+      ) {
+        if (!is.atom(atomVal)) {
+          throw EvaluationError.atArg(
+            `swap! expects an atom as its first argument, got ${atomVal.kind}`,
+            { atomVal },
+            0
+          )
         }
-        if (!isAFunction(fn)) {
-          throw EvaluationError.atArg(`swap! expects a function as its second argument, got ${fn.kind}`, { fn }, 1)
+        if (!is.aFunction(fn)) {
+          throw EvaluationError.atArg(
+            `swap! expects a function as its second argument, got ${fn.kind}`,
+            { fn },
+            1
+          )
         }
-        const newVal = ctx.applyFunction(fn, [atomVal.value, ...extraArgs], callEnv)
-        atomVal.value = newVal
+        const a = atomVal as CljAtom
+        const oldVal = a.value
+        const newVal = ctx.applyFunction(fn, [oldVal, ...extraArgs], callEnv)
+        validateAtom(a, newVal, ctx, callEnv)
+        a.value = newVal
+        notifyWatches(a, oldVal, newVal)
+        return newVal
+      }
+    )
+    .doc(
+      'Applies fn to the current value of the atom, replacing the current value with the result. Returns the new value.',
+      [['atomVal', 'fn', '&', 'extraArgs']]
+    ),
+
+  'reset!': v
+    .nativeFnCtx(
+      'reset!',
+      function reset(ctx, callEnv: Env, atomVal: CljValue, newVal: CljValue) {
+        if (!is.atom(atomVal)) {
+          throw EvaluationError.atArg(
+            `reset! expects an atom as its first argument, got ${atomVal.kind}`,
+            { atomVal },
+            0
+          )
+        }
+        const a = atomVal as CljAtom
+        const oldVal = a.value
+        validateAtom(a, newVal, ctx, callEnv)
+        a.value = newVal
+        notifyWatches(a, oldVal, newVal)
         return newVal
       }
+    )
+    .doc('Sets the value of the atom to newVal and returns the new value.', [
+      ['atomVal', 'newVal'],
+    ]),
+
+  'atom?': v
+    .nativeFn('atom?', function isAtomPredicate(value: CljValue) {
+      return v.boolean(is.atom(value))
+    })
+    .doc('Returns true if the value is an atom, false otherwise.', [['value']]),
+
+  'swap-vals!': v
+    .nativeFnCtx(
+      'swap-vals!',
+      function swapVals(
+        ctx,
+        callEnv: Env,
+        atomVal: CljValue,
+        fn: CljValue,
+        ...extraArgs: CljValue[]
+      ) {
+        if (!is.atom(atomVal)) {
+          throw EvaluationError.atArg(
+            `swap-vals! expects an atom, got ${printString(atomVal)}`,
+            { atomVal },
+            0
+          )
+        }
+        if (!is.aFunction(fn)) {
+          throw EvaluationError.atArg(
+            `swap-vals! expects a function, got ${printString(fn)}`,
+            { fn },
+            1
+          )
+        }
+        const oldVal = atomVal.value
+        const newVal = ctx.applyFunction(fn, [oldVal, ...extraArgs], callEnv)
+        atomVal.value = newVal
+        return v.vector([oldVal, newVal])
+      }
+    )
+    .doc(
+      'Atomically swaps the value of atom to be (apply f current-value-of-atom args). Returns [old new].',
+      [['atom', 'f', '&', 'args']]
+    ),
+
+  'reset-vals!': v
+    .nativeFn(
+      'reset-vals!',
+      function resetVals(atomVal: CljValue, newVal: CljValue) {
+        if (!is.atom(atomVal)) {
+          throw EvaluationError.atArg(
+            `reset-vals! expects an atom, got ${printString(atomVal)}`,
+            { atomVal },
+            0
+          )
+        }
+        const oldVal = atomVal.value
+        atomVal.value = newVal
+        return v.vector([oldVal, newVal])
+      }
+    )
+    .doc('Sets the value of atom to newVal. Returns [old new].', [
+      ['atom', 'newval'],
+    ]),
+
+  'compare-and-set!': v
+    .nativeFn(
+      'compare-and-set!',
+      function compareAndSet(
+        atomVal: CljValue,
+        oldv: CljValue,
+        newv: CljValue
+      ) {
+        if (!is.atom(atomVal)) {
+          throw EvaluationError.atArg(
+            `compare-and-set! expects an atom, got ${printString(atomVal)}`,
+            { atomVal },
+            0
+          )
+        }
+        if (is.equal(atomVal.value, oldv)) {
+          atomVal.value = newv
+          return v.boolean(true)
+        }
+        return v.boolean(false)
+      }
+    )
+    .doc(
+      'Atomically sets the value of atom to newval if and only if the current value of the atom is identical to oldval. Returns true if set happened, else false.',
+      [['atom', 'oldval', 'newval']]
+    ),
+
+  'add-watch': v
+    .nativeFnCtx(
+      'add-watch',
+      function addWatch(
+        ctx,
+        callEnv: Env,
+        atomVal: CljValue,
+        key: CljValue,
+        fn: CljValue
+      ) {
+        if (!is.atom(atomVal)) {
+          throw EvaluationError.atArg(
+            `add-watch expects an atom, got ${printString(atomVal)}`,
+            { atomVal },
+            0
+          )
+        }
+        if (!is.aFunction(fn)) {
+          throw EvaluationError.atArg(
+            `add-watch expects a function, got ${printString(fn)}`,
+            { fn },
+            2
+          )
+        }
+        const a = atomVal as CljAtom
+        if (!a.watches) a.watches = new Map()
+        // Store a wrapper that calls the user fn through the evaluator
+        a.watches.set(printString(key), { key, fn, ctx, callEnv })
+        return atomVal
+      }
+    )
+    .doc(
+      'Adds a watch function to an atom. The watch fn must be a fn of 4 args: a key, the atom, its old-state, its new-state.',
+      [['atom', 'key', 'fn']]
     ),
-    'Applies fn to the current value of the atom, replacing the current value with the result. Returns the new value.',
-    [['atomVal', 'fn', '&', 'extraArgs']]
-  ),
 
-  'reset!': withDoc(
-    cljNativeFunction('reset!', (atomVal: CljValue, newVal: CljValue) => {
-      if (!isAtom(atomVal)) {
-        throw EvaluationError.atArg(`reset! expects an atom as its first argument, got ${atomVal.kind}`, { atomVal }, 0)
+  'remove-watch': v
+    .nativeFn(
+      'remove-watch',
+      function removeWatch(atomVal: CljValue, key: CljValue) {
+        if (!is.atom(atomVal)) {
+          throw EvaluationError.atArg(
+            `remove-watch expects an atom, got ${printString(atomVal)}`,
+            { atomVal },
+            0
+          )
+        }
+        const a = atomVal as CljAtom
+        if (a.watches) a.watches.delete(printString(key))
+        return atomVal
       }
-      atomVal.value = newVal
-      return newVal
-    }),
-    'Sets the value of the atom to newVal and returns the new value.',
-    [['atomVal', 'newVal']]
-  ),
+    )
+    .doc('Removes a watch (set by add-watch) from an atom.', [['atom', 'key']]),
 
-  'atom?': withDoc(
-    cljNativeFunction('atom?', (value: CljValue) => {
-      return cljBoolean(isAtom(value))
-    }),
-    'Returns true if the value is an atom, false otherwise.',
-    [['value']]
-  ),
+  'set-validator!': v
+    .nativeFnCtx(
+      'set-validator!',
+      function setValidator(
+        _ctx,
+        _callEnv: Env,
+        atomVal: CljValue,
+        fn: CljValue
+      ) {
+        if (!is.atom(atomVal)) {
+          throw EvaluationError.atArg(
+            `set-validator! expects an atom, got ${printString(atomVal)}`,
+            { atomVal },
+            0
+          )
+        }
+        if (fn.kind === 'nil') {
+          ;(atomVal as CljAtom).validator = undefined
+          return v.nil()
+        }
+        if (!is.aFunction(fn)) {
+          throw EvaluationError.atArg(
+            `set-validator! expects a function or nil, got ${printString(fn)}`,
+            { fn },
+            1
+          )
+        }
+        ;(atomVal as CljAtom).validator = fn
+        return v.nil()
+      }
+    )
+    .doc(
+      'Sets the validator-fn for an atom. fn must be nil or a side-effect-free fn of one argument.',
+      [['atom', 'fn']]
+    ),
 }

package/src/core/stdlib/errors.ts

@@ -1,11 +1,11 @@
 import { CljThrownSignal, EvaluationError } from '../errors'
-import { cljKeyword, cljMap, cljNativeFunction, cljNil, withDoc } from '../factories'
-import { isKeyword, isMap } from '../assertions'
+import { v } from '../factories'
+import { is } from '../assertions'
 import type { CljValue } from '../types'
 
 export const errorFunctions = {
-  throw: withDoc(
-    cljNativeFunction('throw', (...args: CljValue[]) => {
+  throw: v
+    .nativeFn('throw', function throwImpl(...args: CljValue[]) {
       if (args.length !== 1) {
         throw new EvaluationError(
           `throw requires exactly 1 argument, got ${args.length}`,
@@ -13,13 +13,14 @@ export const errorFunctions = {
         )
       }
       throw new CljThrownSignal(args[0])
-    }),
-    'Throws a value as an exception. The value may be any CljValue; maps are idiomatic.',
-    [['value']]
-  ),
+    })
+    .doc(
+      'Throws a value as an exception. The value may be any CljValue; maps are idiomatic.',
+      [['value']]
+    ),
 
-  'ex-info': withDoc(
-    cljNativeFunction('ex-info', (...args: CljValue[]) => {
+  'ex-info': v
+    .nativeFn('ex-info', function exInfoImpl(...args: CljValue[]) {
       if (args.length < 2) {
         throw new EvaluationError(
           `ex-info requires at least 2 arguments, got ${args.length}`,
@@ -27,55 +28,58 @@ export const errorFunctions = {
         )
       }
       const [msg, data, cause] = args
-      if (msg.kind !== 'string') {
-        throw new EvaluationError(
-          'ex-info: first argument must be a string',
-          { msg }
-        )
+      if (!is.string(msg)) {
+        throw new EvaluationError('ex-info: first argument must be a string', {
+          msg,
+        })
       }
       const entries: [CljValue, CljValue][] = [
-        [cljKeyword(':message'), msg],
-        [cljKeyword(':data'), data],
+        [v.keyword(':message'), msg],
+        [v.keyword(':data'), data],
       ]
       if (cause !== undefined) {
-        entries.push([cljKeyword(':cause'), cause])
+        entries.push([v.keyword(':cause'), cause])
       }
-      return cljMap(entries)
-    }),
-    'Creates an error map with :message and :data keys. Optionally accepts a :cause.',
-    [['msg', 'data'], ['msg', 'data', 'cause']]
-  ),
+      return v.map(entries)
+    })
+    .doc(
+      'Creates an error map with :message and :data keys. Optionally accepts a :cause.',
+      [
+        ['msg', 'data'],
+        ['msg', 'data', 'cause'],
+      ]
+    ),
 
-  'ex-message': withDoc(
-    cljNativeFunction('ex-message', (...args: CljValue[]) => {
+  'ex-message': v
+    .nativeFn('ex-message', function exMessageImpl(...args: CljValue[]) {
       const [e] = args
-      if (!isMap(e)) return cljNil()
-      const entry = e.entries.find(([k]) => isKeyword(k) && k.name === ':message')
-      return entry ? entry[1] : cljNil()
-    }),
-    'Returns the :message of an error map, or nil.',
-    [['e']]
-  ),
+      if (!is.map(e)) return v.nil()
+      const entry = e.entries.find(function findMessageKey([k]) {
+        return is.keyword(k) && k.name === ':message'
+      })
+      return entry ? entry[1] : v.nil()
+    })
+    .doc('Returns the :message of an error map, or nil.', [['e']]),
 
-  'ex-data': withDoc(
-    cljNativeFunction('ex-data', (...args: CljValue[]) => {
+  'ex-data': v
+    .nativeFn('ex-data', function exDataImpl(...args: CljValue[]) {
       const [e] = args
-      if (!isMap(e)) return cljNil()
-      const entry = e.entries.find(([k]) => isKeyword(k) && k.name === ':data')
-      return entry ? entry[1] : cljNil()
-    }),
-    'Returns the :data map of an error map, or nil.',
-    [['e']]
-  ),
+      if (!is.map(e)) return v.nil()
+      const entry = e.entries.find(function findDataKey([k]) {
+        return is.keyword(k) && k.name === ':data'
+      })
+      return entry ? entry[1] : v.nil()
+    })
+    .doc('Returns the :data map of an error map, or nil.', [['e']]),
 
-  'ex-cause': withDoc(
-    cljNativeFunction('ex-cause', (...args: CljValue[]) => {
+  'ex-cause': v
+    .nativeFn('ex-cause', function exCauseImpl(...args: CljValue[]) {
       const [e] = args
-      if (!isMap(e)) return cljNil()
-      const entry = e.entries.find(([k]) => isKeyword(k) && k.name === ':cause')
-      return entry ? entry[1] : cljNil()
-    }),
-    'Returns the :cause of an error map, or nil.',
-    [['e']]
-  ),
+      if (!is.map(e)) return v.nil()
+      const entry = e.entries.find(function findCauseKey([k]) {
+        return is.keyword(k) && k.name === ':cause'
+      })
+      return entry ? entry[1] : v.nil()
+    })
+    .doc('Returns the :cause of an error map, or nil.', [['e']]),
 }