conjure-js 0.0.12 → 0.0.13

package/src/core/factories.ts

@@ -3,17 +3,24 @@ import type {
   Arity,
   CljAtom,
   CljBoolean,
+  CljCons,
+  CljDelay,
   CljFunction,
+  CljJsValue,
   CljKeyword,
+  CljLazySeq,
   CljList,
   CljMacro,
   CljMap,
   CljMultiMethod,
+  CljNamespace,
   CljNativeFunction,
   CljNil,
   CljNumber,
+  CljPending,
   CljReduced,
   CljRegex,
+  CljSet,
   CljString,
   CljSymbol,
   CljValue,
@@ -39,6 +46,7 @@ export const cljSymbol = <T extends string>(name: T) =>
   ({ kind: 'symbol', name }) as const satisfies CljSymbol
 export const cljList = <T extends CljValue[]>(value: T) =>
   ({ kind: 'list', value }) as const satisfies CljList
+export const cljSet = (values: CljValue[]): CljSet => ({ kind: 'set', values })
 export const cljVector = <T extends CljValue[]>(value: T) =>
   ({ kind: 'vector', value }) as const satisfies CljVector
 export const cljMap = <T extends [CljValue, CljValue][]>(entries: T) =>
@@ -71,7 +79,11 @@ export const cljNativeFunction = <
   ({ kind: 'native-function', name, fn }) as const satisfies CljNativeFunction
 export const cljNativeFunctionWithContext = <
   T extends string,
-  U extends (ctx: EvaluationContext, callEnv: Env, ...args: CljValue[]) => CljValue,
+  U extends (
+    ctx: EvaluationContext,
+    callEnv: Env,
+    ...args: CljValue[]
+  ) => CljValue,
 >(
   name: T,
   fn: U
@@ -110,8 +122,12 @@ export const cljRegex = (pattern: string, flags: string = ''): CljRegex => ({
   flags,
 })
 
-export const cljVar = (ns: string, name: string, value: CljValue, meta?: CljMap): CljVar =>
-  ({ kind: 'var', ns, name, value, meta })
+export const cljVar = (
+  ns: string,
+  name: string,
+  value: CljValue,
+  meta?: CljMap
+): CljVar => ({ kind: 'var', ns, name, value, meta })
 
 export const cljAtom = (value: CljValue): CljAtom => ({ kind: 'atom', value })
 export const cljReduced = (value: CljValue): CljReduced => ({
@@ -122,6 +138,50 @@ export const cljVolatile = (value: CljValue): CljVolatile => ({
   kind: 'volatile',
   value,
 })
+export const cljDelay = (thunk: () => CljValue): CljDelay => ({
+  kind: 'delay',
+  thunk,
+  realized: false,
+})
+export const cljLazySeq = (thunk: () => CljValue): CljLazySeq => ({
+  kind: 'lazy-seq',
+  thunk,
+  realized: false,
+})
+export const cljCons = (head: CljValue, tail: CljValue): CljCons => ({
+  kind: 'cons',
+  head,
+  tail,
+})
+export const cljNamespace = (name: string): CljNamespace => ({
+  kind: 'namespace',
+  name,
+  vars: new Map(),
+  aliases: new Map(),
+  readerAliases: new Map(),
+})
+
+export const cljJsValue = (value: unknown): CljJsValue => ({
+  kind: 'js-value',
+  value,
+})
+
+// --- ASYNC (experimental) ---
+export const cljPending = (promise: Promise<CljValue>): CljPending => {
+  const pending: CljPending = { kind: 'pending', promise }
+  // Track fulfillment so the printer can show #<Pending @val> when already settled.
+  promise.then(
+    (v) => {
+      pending.resolved = true
+      pending.resolvedValue = v
+    },
+    () => {
+      /* rejection — no resolved state; printer shows #<Pending> */
+    }
+  )
+  return pending
+}
+// --- END ASYNC ---
 
 export const withDoc = <T extends CljNativeFunction | CljFunction>(
   fn: T,
@@ -142,6 +202,57 @@ export const withDoc = <T extends CljNativeFunction | CljFunction>(
   ]),
 })
 
+// ---------------------------------------------------------------------------
+// NativeFnBuilder — fluent construction API for native functions
+//
+// Satisfies CljNativeFunction structurally, so it can be stored in any
+// registry or record that expects CljNativeFunction — no .build() call needed.
+// ---------------------------------------------------------------------------
+
+export type NativeFnBuilder = CljNativeFunction & {
+  /** Attach doc-string and optional arglists metadata. */
+  doc(text: string, arglists?: string[][]): NativeFnBuilder
+}
+
+function buildDocMeta(text: string, arglists?: string[][]): CljMap {
+  return cljMap([
+    [cljKeyword(':doc'), cljString(text)],
+    ...(arglists
+      ? ([
+          [
+            cljKeyword(':arglists'),
+            cljVector(arglists.map((args) => cljVector(args.map(cljSymbol)))),
+          ],
+        ] as [CljValue, CljValue][])
+      : []),
+  ])
+}
+
+function makeNativeFnBuilder(def: CljNativeFunction): NativeFnBuilder {
+  // Reconstruct a plain CljNativeFunction explicitly so that the spread
+  // inside .doc() never accidentally picks up builder methods from a previous
+  // clone round.
+  const plain: CljNativeFunction = {
+    kind: 'native-function',
+    name: def.name,
+    fn: def.fn,
+    ...(def.fnWithContext !== undefined
+      ? { fnWithContext: def.fnWithContext }
+      : {}),
+    ...(def.meta !== undefined ? { meta: def.meta } : {}),
+  }
+
+  return {
+    ...plain,
+    doc(text: string, arglists?: string[][]): NativeFnBuilder {
+      return makeNativeFnBuilder({
+        ...plain,
+        meta: buildDocMeta(text, arglists),
+      })
+    },
+  }
+}
+
 export const cljMultiMethod = (
   name: string,
   dispatchFn: CljFunction | CljNativeFunction,
@@ -157,3 +268,71 @@ export const cljMultiMethod = (
   methods,
   defaultMethod,
 })
+
+// ---------------------------------------------------------------------------
+// v — unified value factory namespace
+//
+// Mirrors the cljXxx standalone functions but collected under one object so
+// stdlib files need only a single import.  Primitive factories are thin
+// aliases; nativeFn / nativeFnCtx return a NativeFnBuilder with .doc().
+// ---------------------------------------------------------------------------
+
+export const v = {
+  // primitives
+  number: cljNumber,
+  string: cljString,
+  boolean: cljBoolean,
+  keyword: cljKeyword,
+  nil: cljNil,
+  symbol: cljSymbol,
+  kw: cljKeyword,
+
+  // collections
+  list: cljList,
+  vector: cljVector,
+  map: cljMap,
+  set: cljSet,
+  cons: cljCons,
+
+  // callables
+  function: cljFunction,
+  multiArityFunction: cljMultiArityFunction,
+  macro: cljMacro,
+  multiArityMacro: cljMultiArityMacro,
+  multiMethod: cljMultiMethod,
+
+  // fluent native function builders
+  nativeFn(
+    name: string,
+    fn: (...args: CljValue[]) => CljValue
+  ): NativeFnBuilder {
+    return makeNativeFnBuilder({ kind: 'native-function', name, fn })
+  },
+  nativeFnCtx(
+    name: string,
+    fn: (ctx: EvaluationContext, callEnv: Env, ...args: CljValue[]) => CljValue
+  ): NativeFnBuilder {
+    return makeNativeFnBuilder({
+      kind: 'native-function',
+      name,
+      fn: () => {
+        throw new EvaluationError('Native function called without context', {
+          name,
+        })
+      },
+      fnWithContext: fn,
+    })
+  },
+
+  // other value types
+  var: cljVar,
+  atom: cljAtom,
+  regex: cljRegex,
+  reduced: cljReduced,
+  volatile: cljVolatile,
+  delay: cljDelay,
+  lazySeq: cljLazySeq,
+  namespace: cljNamespace,
+  pending: cljPending,
+  jsValue: cljJsValue,
+}

package/src/core/index.ts

@@ -1,12 +1,35 @@
 // Session API
-export { createSession, snapshotSession, createSessionFromSnapshot } from './session'
-export type { Session, SessionSnapshot } from './session'
+export {
+  createSession,
+  snapshotSession,
+  createSessionFromSnapshot,
+} from './session'
+export type { Session, SessionSnapshot, SessionOptions } from './session'
+
+// Runtime API (advanced embedding)
+export { createRuntime, restoreRuntime } from './runtime'
+export type { Runtime, RuntimeSnapshot, RuntimeOptions } from './runtime'
+
+// Module system
+export { resolveModuleOrder } from './module'
+export { makeCoreModule } from './core-module'
+export type {
+  RuntimeModule,
+  NamespaceDeclaration,
+  VarDeclaration,
+  VarMap,
+  ModuleContext,
+} from './module'
 
 // Conversions
 export { cljToJs, jsToClj, ConversionError } from './conversions'
+export type { FunctionApplier } from './conversions'
 
 // Evaluator
-export { applyFunction, applyMacro, evaluateWithMeasurements } from './evaluator'
+export {
+  applyFunction,
+  evaluateWithMeasurements,
+} from './evaluator'
 
 // Errors
 export { EvaluationError, ReaderError, TokenizerError } from './errors'
@@ -25,9 +48,14 @@ export {
   cljFunction,
   cljMultiArityFunction,
   cljNativeFunction,
+  cljNativeFunctionWithContext,
   cljMacro,
   cljMultiArityMacro,
   cljVar,
+  cljNamespace,
+  cljPending,
+  // fluent builder — use v.nativeFn / v.nativeFnCtx for module authoring
+  v,
 } from './factories'
 
 // Assertions
@@ -47,6 +75,7 @@ export {
   isCollection,
   isEqual,
   isVar,
+  isNamespace,
 } from './assertions'
 
 // Env
@@ -58,8 +87,26 @@ export { valueToString } from './transformations'
 // Printer
 export { printString } from './printer'
 
-// Tokenizer (public for tooling consumers)
+// Tokenizer + Reader (public for tooling consumers and EDN parsing)
 export { tokenize } from './tokenizer'
+export { readForms } from './reader'
+
+// readString — parse a single EDN source string to a CljValue.
+// Equivalent to Clojure's read-string. Useful for deserialising results
+// returned by remote nodes over the mesh wire.
+import { tokenize as _tokenize } from './tokenizer'
+import { readForms as _readForms } from './reader'
+import type { CljValue as _CljValue } from './types'
+
+export function readString(source: string): _CljValue {
+  const tokens = _tokenize(source)
+  const forms = _readForms(tokens)
+  if (forms.length === 0) throw new Error('readString: empty input')
+  return forms[0]
+}
+
+// JS interop — import map type for user-defined session entrypoints
+export type ImportMap = Record<string, unknown>
 
 // Types
 export type {
@@ -78,6 +125,9 @@ export type {
   CljMacro,
   CljVar,
   CljNamespace,
+  CljPending, // experimental
   Env,
   Arity,
+  IOContext,
+  EvaluationContext,
 } from './types'

package/src/core/module.ts

@@ -0,0 +1,136 @@
+import type { CljMap, CljNamespace, CljValue } from './types'
+
+// ---------------------------------------------------------------------------
+// RuntimeModule — declarative unit of capability installation into a runtime.
+// Modules are plain data. `vars(ctx)` is the only computation, called once per
+// namespace declaration at install time in dependency order.
+//
+// Additive namespace model: multiple modules may contribute vars to the same
+// namespace. The uniqueness invariant is at the (namespace, varName) level —
+// two modules cannot declare the same var in the same namespace.
+//
+// `dependsOn` lists namespace names. A module that lists 'clojure.core' will
+// be installed after ALL modules that contribute vars to 'clojure.core'.
+// If no installed module provides a depended-on namespace, resolveModuleOrder
+// throws immediately with a clear message.
+// ---------------------------------------------------------------------------
+
+export type RuntimeModule = {
+  id: string
+  dependsOn?: string[]        // namespace names that must be fully installed before this module
+  declareNs: NamespaceDeclaration[]
+}
+
+export type NamespaceDeclaration = {
+  name: string                // the namespace this declaration contributes vars into
+  vars(ctx: ModuleContext): VarMap
+}
+
+export type VarDeclaration = {
+  value: CljValue
+  meta?: CljMap
+  dynamic?: boolean
+  macro?: boolean
+}
+
+export type VarMap = Map<string, VarDeclaration>
+
+export type ModuleContext = {
+  // Read-only view of already-installed state at construction time
+  getVar(ns: string, name: string): CljValue | null
+  getNamespace(name: string): CljNamespace | null
+}
+
+// ---------------------------------------------------------------------------
+// resolveModuleOrder — returns modules in dependency-safe install order.
+//
+// Algorithm (Kahn's topological sort):
+//   1. Build nsProviders: namespace → [module IDs that contribute to it]
+//   2. For each module M and each dep namespace in M.dependsOn:
+//        - If no provider exists → throw (missing dep)
+//        - For each provider P where P.id ≠ M.id → add edge P → M
+//   3. Run Kahn's algorithm; throw on cycle
+// ---------------------------------------------------------------------------
+
+export function resolveModuleOrder(
+  modules: RuntimeModule[],
+  existingNamespaces?: Set<string>
+): RuntimeModule[] {
+  // Index modules by ID for quick lookup
+  const byId = new Map<string, RuntimeModule>()
+  for (const m of modules) {
+    if (byId.has(m.id)) {
+      throw new Error(`Duplicate module ID: '${m.id}'`)
+    }
+    byId.set(m.id, m)
+  }
+
+  // Build namespace → provider module IDs map
+  const nsProviders = new Map<string, string[]>()
+  for (const m of modules) {
+    for (const decl of m.declareNs) {
+      const providers = nsProviders.get(decl.name) ?? []
+      providers.push(m.id)
+      nsProviders.set(decl.name, providers)
+    }
+  }
+
+  // Build dependency edges: providerID → [dependentIDs]
+  // inDegree tracks how many unresolved dependencies each module has
+  const graph = new Map<string, string[]>()
+  const inDegree = new Map<string, number>()
+  for (const m of modules) {
+    graph.set(m.id, [])
+    inDegree.set(m.id, 0)
+  }
+
+  for (const m of modules) {
+    for (const depNs of m.dependsOn ?? []) {
+      // A dep is satisfied if some already-installed namespace provides it
+      if (existingNamespaces?.has(depNs)) continue
+
+      const providers = nsProviders.get(depNs)
+      if (!providers || providers.length === 0) {
+        throw new Error(
+          `No module provides namespace '${depNs}' (required by '${m.id}')`
+        )
+      }
+      for (const providerId of providers) {
+        // Self-exclusion: a module that both contributes to and depends on the
+        // same namespace does not create a self-loop.
+        if (providerId === m.id) continue
+        graph.get(providerId)!.push(m.id)
+        inDegree.set(m.id, inDegree.get(m.id)! + 1)
+      }
+    }
+  }
+
+  // Kahn's algorithm — start with nodes that have no unresolved deps
+  const queue: string[] = []
+  for (const [id, degree] of inDegree) {
+    if (degree === 0) queue.push(id)
+  }
+
+  const result: RuntimeModule[] = []
+  while (queue.length > 0) {
+    const id = queue.shift()!
+    result.push(byId.get(id)!)
+    for (const dependentId of graph.get(id)!) {
+      const newDegree = inDegree.get(dependentId)! - 1
+      inDegree.set(dependentId, newDegree)
+      if (newDegree === 0) queue.push(dependentId)
+    }
+  }
+
+  // If not all modules were processed, there is a cycle
+  if (result.length !== modules.length) {
+    const unprocessed = modules
+      .map((m) => m.id)
+      .filter((id) => !result.some((m) => m.id === id))
+    throw new Error(
+      `Circular dependency detected in module system. Modules in cycle: ${unprocessed.join(', ')}`
+    )
+  }
+
+  return result
+}

package/src/core/ns-forms.ts

@@ -0,0 +1,107 @@
+import { isKeyword, isList, isSymbol } from './assertions'
+import type { CljValue, Token, TokenSymbol } from './types'
+
+// ---------------------------------------------------------------------------
+// Token scan helpers — lightweight pre-parse scans for ns form metadata.
+// These are semantic (module declaration analysis), not syntactic (parsing).
+// Exported so session.evaluate and runtime.loadFile can reuse them.
+// ---------------------------------------------------------------------------
+
+// Looks for the pattern: LParen Symbol("ns") Symbol(name) at the top of the
+// token stream. Returns the namespace name or null.
+export function extractNsNameFromTokens(tokens: Token[]): string | null {
+  const meaningful = tokens.filter((t) => t.kind !== 'Comment')
+  if (meaningful.length < 3) return null
+  if (meaningful[0].kind !== 'LParen') return null
+  if (meaningful[1].kind !== 'Symbol' || meaningful[1].value !== 'ns')
+    return null
+  if (meaningful[2].kind !== 'Symbol') return null
+  return meaningful[2].value
+}
+
+// Returns Map { 'alias' -> 'full.ns.name' } for all [some.ns :as alias] and
+// [some.ns :as-alias alias] specs found in the ns form's :require clauses.
+// Runs before readForms so the reader can expand ::alias/foo at read time.
+export function extractAliasMapFromTokens(
+  tokens: Token[]
+): Map<string, string> {
+  const aliases = new Map<string, string>()
+  const meaningful = tokens.filter(
+    (t) => t.kind !== 'Comment' && t.kind !== 'Whitespace'
+  )
+  if (meaningful.length < 3) return aliases
+  if (meaningful[0].kind !== 'LParen') return aliases
+  if (meaningful[1].kind !== 'Symbol' || meaningful[1].value !== 'ns')
+    return aliases
+
+  let i = 3 // skip ( ns <name>
+  let depth = 1
+  while (i < meaningful.length && depth > 0) {
+    const tok = meaningful[i]
+    if (tok.kind === 'LParen') {
+      depth++
+      i++
+      continue
+    }
+    if (tok.kind === 'RParen') {
+      depth--
+      i++
+      continue
+    }
+    if (tok.kind === 'LBracket') {
+      let j = i + 1
+      let nsSym: string | null = null
+      while (j < meaningful.length && meaningful[j].kind !== 'RBracket') {
+        const t = meaningful[j]
+        if (t.kind === 'Symbol' && nsSym === null) {
+          nsSym = t.value
+        }
+        if (
+          t.kind === 'Keyword' &&
+          (t.value === ':as' || t.value === ':as-alias')
+        ) {
+          j++
+          if (
+            j < meaningful.length &&
+            meaningful[j].kind === 'Symbol' &&
+            nsSym
+          ) {
+            aliases.set((meaningful[j] as TokenSymbol).value, nsSym)
+          }
+        }
+        j++
+      }
+    }
+    i++
+  }
+  return aliases
+}
+
+function findNsForm(forms: CljValue[]) {
+  const nsForm = forms.find(
+    (f) =>
+      isList(f) &&
+      f.value.length > 0 &&
+      isSymbol(f.value[0]) &&
+      f.value[0].name === 'ns'
+  )
+  if (!nsForm || !isList(nsForm)) return null
+  return nsForm
+}
+
+export function extractRequireClauses(forms: CljValue[]): CljValue[][] {
+  const nsForm = findNsForm(forms)
+  if (!nsForm) return []
+  const clauses: CljValue[][] = []
+  for (let i = 2; i < nsForm.value.length; i++) {
+    const clause = nsForm.value[i]
+    if (
+      isList(clause) &&
+      isKeyword(clause.value[0]) &&
+      clause.value[0].name === ':require'
+    ) {
+      clauses.push(clause.value.slice(1))
+    }
+  }
+  return clauses
+}